Metadata-Version: 2.4
Name: cortex-agent-sdk
Version: 0.0.2
Summary: SDK async y multiproveedor para construir agentes con control explícito
Project-URL: Repository, https://github.com/epok200/cortex_agent_sdk
Project-URL: Issues, https://github.com/epok200/cortex_agent_sdk/issues
Author: EPOK
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,asyncio,openai,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: jsonschema<5,>=4.25
Requires-Dist: pydantic<3,>=2.13
Provides-Extra: all
Requires-Dist: asyncpg>=0.31.0; extra == 'all'
Requires-Dist: openai<3,>=2.52; extra == 'all'
Requires-Dist: redis>=8.1.0; extra == 'all'
Provides-Extra: gateway
Requires-Dist: openai<3,>=2.52; extra == 'gateway'
Provides-Extra: openai
Requires-Dist: openai<3,>=2.52; extra == 'openai'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=8.1.0; extra == 'redis'
Description-Content-Type: text/markdown

# Cortex Agent SDK

SDK async para construir agentes con una API pequeña y control explícito del loop, las tools, el
historial y el ciclo de vida.

> Cortex Agent SDK está en alfa. La API puede cambiar antes de la versión `0.1.0`.

## Requisitos

- Python `>=3.13`.
- Una credencial del provider elegido.

## Instalación

Para OpenAI Responses:

```bash
uv add "cortex-agent-sdk[openai]"
```

También puede instalarse con `pip`:

```bash
python -m pip install "cortex-agent-sdk[openai]"
```

El core instala únicamente Pydantic y JSON Schema. Los providers y transportes se habilitan mediante
extras opcionales:

- `openai`: engine de OpenAI Responses.
- `gateway`: conexión mediante un endpoint compatible con OpenAI Responses.
- `redis`: sesiones persistentes en Redis.
- `postgres`: sesiones persistentes en PostgreSQL.
- `all`: todas las integraciones disponibles.

## Uso mínimo

El SDK oficial de OpenAI lee `OPENAI_API_KEY` del entorno.

```python
import asyncio

from cortex_agent_sdk import Agent
from cortex_agent_sdk.openai import OpenAIEngine, OpenAIOptions


async def main() -> None:
    options = OpenAIOptions(max_output_tokens=128, reasoning_effort="low")
    async with Agent(OpenAIEngine("gpt-5.6-luna", options=options)) as agent:
        result = await agent.run("Responde únicamente: hola")
    print(result.text)


asyncio.run(main())
```

## Gateway compatible

`OpenAIEngine` también acepta un endpoint que conserve el protocolo de OpenAI Responses:

```python
import os

from cortex_agent_sdk.gateway import OpenAICompatibleGateway
from cortex_agent_sdk.openai import OpenAIEngine


gateway = OpenAICompatibleGateway(
    url=os.environ["CORTEX_GATEWAY_URL"],
    api_key=os.environ["CORTEX_GATEWAY_API_KEY"],
)
engine = OpenAIEngine("your-model", gateway=gateway)
```

## Tools

Una función async decorada puede exponerse al modelo como respuesta final:

```python
import asyncio

from cortex_agent_sdk import Agent, final_answer
from cortex_agent_sdk.openai import OpenAIEngine


@final_answer
async def sumar(a: int, b: int) -> str:
    """Suma dos enteros."""
    return str(a + b)


async def main() -> None:
    instructions = "Para sumar, usa siempre la herramienta sumar."
    async with Agent(
        OpenAIEngine("gpt-5.6-luna"),
        instructions=instructions,
        tools=(sumar,),
    ) as agent:
        result = await agent.run("Suma 20 y 22.")
    print(result.text)


asyncio.run(main())
```

## Capacidades del alfa

- Loop async acotado.
- Tools async con schema inferido o explícito.
- Historial y sesiones en memoria, Redis o PostgreSQL.
- Hooks locales.
- Timeouts para providers y tools.
- Respuesta tipada con texto, usage, razón de salida y respuesta raw.
- OpenAI Responses directo o mediante un gateway compatible.

Google conserva un namespace estable para la evolución multiproveedor, pero todavía no incluye un
engine funcional. Anthropic y streaming están fuera de este alfa.

## Sesiones persistentes

Redis y PostgreSQL implementan el mismo contrato de sesiones que el store en memoria. El historial
queda aislado por `session_id`, ligado al provider y modelo originales, y protegido con lease
renovable, fencing token y compare-and-swap.

Redis no requiere inicialización de schema:

```python
import os

from cortex_agent_sdk import Agent
from cortex_agent_sdk.openai import OpenAIEngine
from cortex_agent_sdk.redis import RedisSessionStore


store = RedisSessionStore(os.environ["REDIS_URL"])
agent = Agent(
    OpenAIEngine("gpt-5.6-luna"),
    session_store=store,
    own_session_store=True,
)
result = await agent.run("Hola", session_id="producto:tenant:usuario")
await agent.aclose()
```

PostgreSQL exige crear su tabla de forma explícita una vez:

```python
import os

from cortex_agent_sdk.postgres import PostgresSessionStore


store = PostgresSessionStore(os.environ["POSTGRES_URL"])
await store.setup()
```

Una tarea periódica puede ejecutar `await store.cleanup_expired()` para vaciar historiales vencidos
que nunca volvieron a solicitarse. El row mínimo permanece para conservar el fencing counter.

`Agent.aclose()` hace un cierre ordenado: deja de aceptar turnos nuevos, espera los turnos activos y
después cierra los recursos que posee. El límite se configura con
`AgentOptions.shutdown_timeout_seconds`. Si vence, el SDK no cancela el turno ni cierra conexiones;
regresa `RUNTIME_CIERRE_TIMEOUT` para que la aplicación pueda reintentar el cierre.

Una sesión dañada o deliberadamente descartada se elimina mediante
`await agent.reset_session(session_id)`.

## Licencia

Apache License 2.0.
