Metadata-Version: 2.4
Name: saptiva-agents
Version: 0.2.4
Summary: Saptiva-Agents es un potente framework para construir aplicaciones de IA multiagente que pueden actuar de forma autónoma o colaborar con humanos.
Author-email: Saptiva AI <tools@saptiva.com>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-CODE
Requires-Dist: autogen-core==0.7.5
Requires-Dist: autogen-agentchat==0.7.5
Requires-Dist: autogen-ext==0.7.5
Requires-Dist: autogen-ext[file-surfer,langchain,mcp,openai,redisvl,task-centric-memory,video-surfer,web-surfer]
Requires-Dist: langchain-community
Requires-Dist: python-dotenv
Requires-Dist: sentence-transformers
Dynamic: license-file

## 🤖 Saptiva Agents

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/saptiva-agents.svg)](https://pypi.org/project/saptiva-agents/)
[![License](https://img.shields.io/github/license/saptiva/saptiva-agents)](https://github.com/saptiva-ai/saptiva-agents/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://app.gitbook.com/o/YD7tmPjNuCJPBtMoeymU/s/1Xeu6KDnv2A0dUxoQDDU/saptiva-agents/)

**Saptiva-Agents** es un potente framework para construir aplicaciones de IA multiagente que pueden actuar de forma autónoma o colaborar con humanos.

---

## ⚙️ Instalación

**Saptiva-Agents** requiere **Python 3.10 o superior**. Para instalar desde [**PyPI**](https://pypi.org/project/saptiva-agents/):

```bash
pip install -U saptiva-agents
```
---

## 🚀 Inicio rápido

## 👋 Hola, Mundo

Crea un agente asistente usando `Saptiva Legacy` con **Saptiva-Agents**:


```python


import asyncio

from saptiva_agents import SAPTIVA_LEGACY
from saptiva_agents.base import SaptivaAIChatCompletionClient
from saptiva_agents.agents import AssistantAgent

async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model=SAPTIVA_LEGACY, 
        api_key="TU_SAPTIVA_API_KEY"
    )
    agent = AssistantAgent("assistant", model_client=model_client)
    response = await agent.run(task="Di '¡Hola Mundo!'")
    print(response.messages[1].content)
    
    await model_client.close()

asyncio.run(main())
```

```bash
python hello_world.py
```
---

## 🌐 Equipo de Agentes para Navegación Web

Create a browser-based agent team using Playwright:

```python
# pip install saptiva-agents
# playwright install --with-deps chromium

import asyncio

from saptiva_agents import SAPTIVA_OPS
from saptiva_agents.agents import UserProxyAgent
from saptiva_agents.base import SaptivaAIChatCompletionClient
from saptiva_agents.conditions import TextMentionTermination
from saptiva_agents.teams import RoundRobinGroupChat
from saptiva_agents.web_surfer import MultimodalWebSurfer
from saptiva_agents.ui import Console

async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model=SAPTIVA_OPS, 
        api_key="TU_SAPTIVA_API_KEY"
    )
    web_surfer = MultimodalWebSurfer(
        "web_surfer", 
        model_client, 
        headless=False, 
        animate_actions=True, 
        start_page="https://www.google.com"
    )
    user_proxy = UserProxyAgent("user_proxy")
    termination = TextMentionTermination("exit", sources=["user_proxy"])
    team = RoundRobinGroupChat([web_surfer, user_proxy], termination_condition=termination, max_turns=3)

    try:
        await Console(team.run_stream(task="Navega a saptiva.com y consigue información sobre Saptiva AI."))
    finally:
        await web_surfer.close()
        await model_client.close()

asyncio.run(main())
```

```bash
python web_surfer.py
```
---

## 🎭 Orquestación Multiagente

Puedes usar `AgentTool` para crear una configuración básica de orquestación multiagente.

```python
import asyncio

from saptiva_agents.tools import AgentTool
from saptiva_agents.agents import AssistantAgent
from saptiva_agents.ui import Console
from saptiva_agents.base import SaptivaAIChatCompletionClient


async def main() -> None:
    model_client = SaptivaAIChatCompletionClient(
        model="Saptiva Legacy", 
        api_key="TU_SAPTIVA_API_KEY"
    )
    math_agent = AssistantAgent(
        "math_expert",
        model_client=model_client,
        system_message="Eres un experto en matemáticas.",
        description="Un asistente experto en matemáticas.",
        model_client_stream=True,
    )
    math_agent_tool = AgentTool(math_agent, return_value_as_last_message=True)

    chemistry_agent = AssistantAgent(
        "chemistry_expert",
        model_client=model_client,
        system_message="Eres un experto en química.",
        description="Un asistente experto en química.",
        model_client_stream=True,
    )
    chemistry_agent_tool = AgentTool(chemistry_agent, return_value_as_last_message=True)

    agent = AssistantAgent(
        "assistant",
        system_message="Eres un asistente general. Usa las herramientas de expertos cuando sea necesario.",
        model_client=model_client,
        model_client_stream=True,
        tools=[math_agent_tool, chemistry_agent_tool],
        max_tool_iterations=10,
    )

    await Console(agent.run_stream(task="¿Cuál es la integral de x^2?"))
    await Console(agent.run_stream(task="¿Cuál es el peso molecular del agua?"))

asyncio.run(main())
```
---

# 📚 Modelos Disponibles

Saptiva-Agents soporta una variedad de modelos para tareas de **texto** y **multimodales**.

## 🧠 Modelos de Texto (tareas básicas)

| Nombre            | Modelo base       | Mejor para                       | Casos de uso                                                        |
|-------------------|-------------------|----------------------------------|---------------------------------------------------------------------|
| **Saptiva Ops**   | `gpt-oss:20b`     | Tareas que implican razonamiento | Agentes autónomos, RAG                                              |
| **Saptiva Guard** | `llama-guard3:8b` | Moderación y cumplimiento        | Protección de contenido, validación de incumplimiento legal en LLMs |

En caso de requerir implementación de herramientas (tools) te recomendamos usar los siguientes modelos que soportan dicha caracteristica:

## 🧰 Modelos de Texto (Tools)

| Nombre             | Modelo base    | Mejor para                             | Casos de uso                                  |
|--------------------|----------------|----------------------------------------|-----------------------------------------------|
| **Saptiva Cortex** | `qwen3-tk:30b` | Tareas de razonamiento                 | Agentes con lógica, comprensión profunda      |
| **Saptiva Turbo**  | `qwen3-it:30b` | Casos complejos con tools y SDK        | Agentes autónomos, RAG, websearch             |
| **Saptiva Legacy** | `llama3.3:70b` | Compatibilidad con herramientas legacy | SDK avanzado, pruebas, compatibilidad técnica |

## 🖼️ Modelo Multimodal

| Nombre          | Modelo base      | Mejor para                                                   | Casos de uso                                   |
|-----------------|------------------|--------------------------------------------------------------|------------------------------------------------|
| **Saptiva OCR** | `Nanonets OCR-s` | Extracción inteligente de texto e interpretación de imágenes | OCR, estructuración de documentos, VLM, visión |

> **Nota:**  
> Saptiva-Agents **no soporta embeddings**, por lo tanto, el modelo **Saptiva Embed** no está disponible.

> 🔗 [Ver lista completa de modelos disponibles en Saptiva](https://saptiva.gitbook.io/saptiva-docs/basicos/modelos-disponibles)

---

## 🧰 Custom Tools

Junto a la SDK viene un grupo de tools predeterminadas con funcionalidades que puedes adherir en la fase de inicialización de tus agentes, estas tools dan acceso a funcionalidades tales como extracción de documentos, consultas CURP, CFDI y demás.

Haz clic en el siguiente link para más información:

💼 [**Custom Tools**](https://saptiva.gitbook.io/saptiva-docs/saptiva-agents/custom-tools)

> **Nota:**  
> La lista de tools predeterminadas está disponible a partir de la versión **0.1.3** de nuestro **SDK**.

## 📄 Licencia

Este proyecto está licenciado bajo la [Licencia MIT](https://github.com/saptiva-ai/saptiva-agents/blob/main/LICENSE).

---

## 🌐 Enlaces

- 🔗 [Documentación Oficial](https://saptiva.gitbook.io/saptiva-docs/)
