cortex-agent-sdk 0.0.4__tar.gz → 0.2.0__tar.gz

cortex_agent_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: cortex-agent-sdk
+Version: 0.2.0
+Summary: Sesiones Memory y Redis para agentes construidos con Pydantic AI
+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,pydantic-ai,redis,sessions
+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: pydantic-ai-slim<3,>=2.27
+Provides-Extra: all
+Requires-Dist: pydantic-ai-slim[openai]<3,>=2.27; extra == 'all'
+Requires-Dist: redis>=8.1.0; extra == 'all'
+Provides-Extra: openai
+Requires-Dist: pydantic-ai-slim[openai]<3,>=2.27; extra == 'openai'
+Provides-Extra: redis
+Requires-Dist: redis>=8.1.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Cortex Agent SDK
+
+Cortex agrega sesiones Memory y Redis a agentes construidos directamente con Pydantic AI.
+
+No implementa otro loop, otra capa de tools ni otra API de agentes. Pydantic AI conserva el control
+de providers, modelos, tools, tipado, `RunContext`, hooks, límites, approvals, outputs, usage e
+historial. Cortex sólo cubre la pieza que Pydantic AI no incluye: persistencia conversacional con un
+turno activo por sesión.
+
+> Cortex Agent SDK está en alfa. La API puede cambiar antes de la versión `1.0.0`.
+
+## Requisitos
+
+- Python `>=3.13`.
+- Pydantic AI `>=2.27,<3`, instalado por Cortex en su variante slim.
+
+## Instalación
+
+Sesiones en memoria:
+
+```bash
+uv add cortex-agent-sdk
+```
+
+OpenAI Responses:
+
+```bash
+uv add "cortex-agent-sdk[openai]"
+```
+
+OpenAI Responses y Redis:
+
+```bash
+uv add "cortex-agent-sdk[openai,redis]"
+```
+
+## Uso
+
+El agente es el `Agent` nativo de Pydantic AI. El store entrega el historial bajo exclusión y lo
+guarda cuando `session.replace(...)` marca un resultado completo.
+
+```python
+import asyncio
+
+from pydantic_ai import Agent
+
+from cortex_agent_sdk.sessions import MemorySessionStore
+
+
+async def main() -> None:
+    agent = Agent("openai-responses:gpt-5.6-luna")
+    sessions = MemorySessionStore()
+
+    async with agent, sessions:
+        async with sessions.turn("usuario:42") as session:
+            result = await agent.run(
+                "Recuerda que mi color favorito es verde.",
+                message_history=session.messages,
+                conversation_id=session.session_id,
+            )
+            session.replace(result.all_messages())
+
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+`replace()` es explícito por diseño:
+
+- Si no se llama, el store no modifica el historial.
+- Si el bloque termina con una excepción, el store no guarda el reemplazo.
+- Si guardar falla, la excepción se propaga.
+
+## Redis
+
+```python
+from cortex_agent_sdk.redis import RedisSessionStore
+
+sessions = RedisSessionStore(
+    "redis://localhost:6379/0",
+    key_prefix="mi-producto:sesiones:v1",
+    ttl_seconds=86_400,
+)
+```
+
+Redis mantiene un lease renovable durante todo el turno. Mientras conserva el lease, dos procesos no
+pueden usar la misma sesión al mismo tiempo y las sesiones distintas siguen siendo concurrentes. Si
+la renovación falla, Cortex interrumpe el turno propietario y no guarda como owner obsoleto. El
+historial se serializa con `ModelMessagesTypeAdapter`, el formato público de Pydantic AI.
+
+Al cambiar desde el runtime anterior, usa un prefix nuevo. Los formatos no son compatibles y Cortex
+no intenta convertir el historial legacy.
+
+## Endpoint compatible con OpenAI
+
+Pydantic AI puede conectarse directamente. Para un endpoint que no debe reintentar peticiones,
+configura el provider una vez:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIResponsesModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+provider = OpenAIProvider(
+    base_url="https://example.com/v1",
+    api_key="...",
+)
+provider.client.max_retries = 0
+model = OpenAIResponsesModel("gpt-5.6-luna", provider=provider)
+agent = Agent(model)
+```
+
+El context manager de `Agent` administra el transporte del provider.
+
+## Migración desde el runtime anterior
+
+| Antes | Ahora |
+|---|---|
+| `cortex_agent_sdk.Agent` | `pydantic_ai.Agent` |
+| `OpenAIEngine` | `OpenAIResponsesModel` + `OpenAIProvider` |
+| `OpenAICompatibleGateway` | `OpenAIProvider(base_url=..., api_key=...)` |
+| `OpenAIOptions` | `OpenAIResponsesModelSettings` y argumentos de `Agent.run` |
+| `@tool` e `Injected` | tools nativas + `RunContext[Deps]` |
+| `ToolBinding` | `FunctionToolset` o tools preparadas por run |
+| `AgentHooks` | `pydantic_ai.capabilities.Hooks` |
+| `turn_finished` | `Hooks(after_run=...)` |
+| `history_transform` | `Hooks(before_model_request=...)` |
+| `fallback_answer` | política local del producto sobre `AgentRunResult` |
+| `AgentOptions` | `UsageLimits`, settings del modelo y argumentos de `Agent` |
+| `AgentResult.text` | `AgentRunResult.output` |
+| `SessionStore.acquire` | `SessionStore.turn` + `Session.replace` |
+| `agent.reset_session(id)` | `store.reset(id)` |
+
+No se ofrece una capa de compatibilidad. Mantenerla volvería a duplicar la API y el runtime de
+Pydantic AI.
+
+## Superficie pública
+
+- `cortex_agent_sdk.sessions.Session`
+- `cortex_agent_sdk.sessions.SessionStore`
+- `cortex_agent_sdk.sessions.MemorySessionStore`
+- `cortex_agent_sdk.redis.RedisSessionStore`
+- `cortex_agent_sdk.errores.AppError`
+- `cortex_agent_sdk.errores.CodigoError`
+- `cortex_agent_sdk.errores.Severidad`
+
+El loop, tools, hooks, approvals, modelos y resultados se importan desde `pydantic_ai`.
+
+## Licencia
+
+Apache License 2.0.

cortex_agent_sdk-0.2.0/README.md

@@ -0,0 +1,152 @@
+# Cortex Agent SDK
+
+Cortex agrega sesiones Memory y Redis a agentes construidos directamente con Pydantic AI.
+
+No implementa otro loop, otra capa de tools ni otra API de agentes. Pydantic AI conserva el control
+de providers, modelos, tools, tipado, `RunContext`, hooks, límites, approvals, outputs, usage e
+historial. Cortex sólo cubre la pieza que Pydantic AI no incluye: persistencia conversacional con un
+turno activo por sesión.
+
+> Cortex Agent SDK está en alfa. La API puede cambiar antes de la versión `1.0.0`.
+
+## Requisitos
+
+- Python `>=3.13`.
+- Pydantic AI `>=2.27,<3`, instalado por Cortex en su variante slim.
+
+## Instalación
+
+Sesiones en memoria:
+
+```bash
+uv add cortex-agent-sdk
+```
+
+OpenAI Responses:
+
+```bash
+uv add "cortex-agent-sdk[openai]"
+```
+
+OpenAI Responses y Redis:
+
+```bash
+uv add "cortex-agent-sdk[openai,redis]"
+```
+
+## Uso
+
+El agente es el `Agent` nativo de Pydantic AI. El store entrega el historial bajo exclusión y lo
+guarda cuando `session.replace(...)` marca un resultado completo.
+
+```python
+import asyncio
+
+from pydantic_ai import Agent
+
+from cortex_agent_sdk.sessions import MemorySessionStore
+
+
+async def main() -> None:
+    agent = Agent("openai-responses:gpt-5.6-luna")
+    sessions = MemorySessionStore()
+
+    async with agent, sessions:
+        async with sessions.turn("usuario:42") as session:
+            result = await agent.run(
+                "Recuerda que mi color favorito es verde.",
+                message_history=session.messages,
+                conversation_id=session.session_id,
+            )
+            session.replace(result.all_messages())
+
+    print(result.output)
+
+
+asyncio.run(main())
+```
+
+`replace()` es explícito por diseño:
+
+- Si no se llama, el store no modifica el historial.
+- Si el bloque termina con una excepción, el store no guarda el reemplazo.
+- Si guardar falla, la excepción se propaga.
+
+## Redis
+
+```python
+from cortex_agent_sdk.redis import RedisSessionStore
+
+sessions = RedisSessionStore(
+    "redis://localhost:6379/0",
+    key_prefix="mi-producto:sesiones:v1",
+    ttl_seconds=86_400,
+)
+```
+
+Redis mantiene un lease renovable durante todo el turno. Mientras conserva el lease, dos procesos no
+pueden usar la misma sesión al mismo tiempo y las sesiones distintas siguen siendo concurrentes. Si
+la renovación falla, Cortex interrumpe el turno propietario y no guarda como owner obsoleto. El
+historial se serializa con `ModelMessagesTypeAdapter`, el formato público de Pydantic AI.
+
+Al cambiar desde el runtime anterior, usa un prefix nuevo. Los formatos no son compatibles y Cortex
+no intenta convertir el historial legacy.
+
+## Endpoint compatible con OpenAI
+
+Pydantic AI puede conectarse directamente. Para un endpoint que no debe reintentar peticiones,
+configura el provider una vez:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIResponsesModel
+from pydantic_ai.providers.openai import OpenAIProvider
+
+provider = OpenAIProvider(
+    base_url="https://example.com/v1",
+    api_key="...",
+)
+provider.client.max_retries = 0
+model = OpenAIResponsesModel("gpt-5.6-luna", provider=provider)
+agent = Agent(model)
+```
+
+El context manager de `Agent` administra el transporte del provider.
+
+## Migración desde el runtime anterior
+
+| Antes | Ahora |
+|---|---|
+| `cortex_agent_sdk.Agent` | `pydantic_ai.Agent` |
+| `OpenAIEngine` | `OpenAIResponsesModel` + `OpenAIProvider` |
+| `OpenAICompatibleGateway` | `OpenAIProvider(base_url=..., api_key=...)` |
+| `OpenAIOptions` | `OpenAIResponsesModelSettings` y argumentos de `Agent.run` |
+| `@tool` e `Injected` | tools nativas + `RunContext[Deps]` |
+| `ToolBinding` | `FunctionToolset` o tools preparadas por run |
+| `AgentHooks` | `pydantic_ai.capabilities.Hooks` |
+| `turn_finished` | `Hooks(after_run=...)` |
+| `history_transform` | `Hooks(before_model_request=...)` |
+| `fallback_answer` | política local del producto sobre `AgentRunResult` |
+| `AgentOptions` | `UsageLimits`, settings del modelo y argumentos de `Agent` |
+| `AgentResult.text` | `AgentRunResult.output` |
+| `SessionStore.acquire` | `SessionStore.turn` + `Session.replace` |
+| `agent.reset_session(id)` | `store.reset(id)` |
+
+No se ofrece una capa de compatibilidad. Mantenerla volvería a duplicar la API y el runtime de
+Pydantic AI.
+
+## Superficie pública
+
+- `cortex_agent_sdk.sessions.Session`
+- `cortex_agent_sdk.sessions.SessionStore`
+- `cortex_agent_sdk.sessions.MemorySessionStore`
+- `cortex_agent_sdk.redis.RedisSessionStore`
+- `cortex_agent_sdk.errores.AppError`
+- `cortex_agent_sdk.errores.CodigoError`
+- `cortex_agent_sdk.errores.Severidad`
+
+El loop, tools, hooks, approvals, modelos y resultados se importan desde `pydantic_ai`.
+
+## Licencia
+
+Apache License 2.0.

{cortex_agent_sdk-0.0.4 → cortex_agent_sdk-0.2.0}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.0.4"
-description = "SDK async y multiproveedor para construir agentes con control explícito"
+version = "0.2.0"
+description = "Sesiones Memory y Redis para agentes construidos con Pydantic AI"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"
 authors = [{ name = "EPOK" }]
-keywords = ["agents", "asyncio", "openai", "sdk"]
+keywords = ["agents", "pydantic-ai", "redis", "sessions"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -17,8 +17,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "jsonschema>=4.25,<5",
-    "pydantic>=2.13,<3",
+    "pydantic-ai-slim>=2.27,<3",
 ]
 
 [project.urls]
@@ -27,27 +26,19 @@ Issues = "https://github.com/epok200/cortex_agent_sdk/issues"
 
 [project.optional-dependencies]
 openai = [
-    "openai>=2.52,<3",
-]
-gateway = [
-    "openai>=2.52,<3",
+    "pydantic-ai-slim[openai]>=2.27,<3",
 ]
 all = [
-    "asyncpg>=0.31.0",
-    "openai>=2.52,<3",
+    "pydantic-ai-slim[openai]>=2.27,<3",
     "redis>=8.1.0",
 ]
 redis = [
     "redis>=8.1.0",
 ]
-postgres = [
-    "asyncpg>=0.31.0",
-]
 
 [dependency-groups]
 dev = [
-    "asyncpg>=0.31.0",
-    "openai>=2.52,<3",
+    "pydantic-ai-slim[openai]>=2.27,<3",
     "pyright>=1.1.408",
     "pytest>=9.0",
     "pytest-asyncio>=1.3",
@@ -74,7 +65,7 @@ markers = [
 ]
 
 [tool.pyright]
-include = ["src", "tests"]
+include = ["src", "tests", "examples"]
 pythonVersion = "3.13"
 typeCheckingMode = "standard"
 

cortex_agent_sdk-0.2.0/src/cortex_agent_sdk/__init__.py

@@ -0,0 +1,5 @@
+from importlib.metadata import version as _package_version
+
+__version__ = _package_version("cortex-agent-sdk")
+
+__all__ = ["__version__"]

{cortex_agent_sdk-0.0.4 → cortex_agent_sdk-0.2.0}/src/cortex_agent_sdk/errores/__init__.py

@@ -1,2 +1,4 @@
 from cortex_agent_sdk.errores.catalogo import CodigoError, Severidad
 from cortex_agent_sdk.errores.excepcion import AppError
+
+__all__ = ["AppError", "CodigoError", "Severidad"]

cortex_agent_sdk-0.2.0/src/cortex_agent_sdk/errores/catalogo.py

@@ -0,0 +1,18 @@
+from enum import StrEnum
+
+
+class Severidad(StrEnum):
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+class CodigoError(StrEnum):
+    UNKNOWN = "UNKNOWN"
+    CONFIG_INVALIDA = "CONFIG_INVALIDA"
+    RECURSO_CERRADO = "RECURSO_CERRADO"
+    SESION_OCUPADA = "SESION_OCUPADA"
+    SESION_LEASE_PERDIDO = "SESION_LEASE_PERDIDO"
+    SESION_INVALIDA = "SESION_INVALIDA"
+    SESION_STORE_FALLO = "SESION_STORE_FALLO"

{cortex_agent_sdk-0.0.4 → cortex_agent_sdk-0.2.0}/src/cortex_agent_sdk/errores/excepcion.py

@@ -2,18 +2,15 @@ from cortex_agent_sdk.errores.catalogo import CodigoError, Severidad
 
 
 class AppError(Exception):
-    """Error del SDK con código estable y mensaje seguro opcional."""
+    """Error de Cortex con código estable."""
 
     def __init__(
         self,
         codigo: CodigoError,
         detalle: str,
         severidad: Severidad = Severidad.ERROR,
-        mensaje_seguro: str | None = None,
     ) -> None:
         self.codigo = codigo
         self.detalle = detalle
         self.severidad = severidad
-        self.mensaje_seguro = mensaje_seguro
         super().__init__(f"[{codigo.value}] {detalle}")
-

{cortex_agent_sdk-0.0.4 → cortex_agent_sdk-0.2.0}/src/cortex_agent_sdk/redis/__init__.py

@@ -1 +1,3 @@
 from cortex_agent_sdk.redis.store import RedisSessionStore
+
+__all__ = ["RedisSessionStore"]

{cortex_agent_sdk-0.0.4 → cortex_agent_sdk-0.2.0}/src/cortex_agent_sdk/redis/scripts.py

@@ -1,14 +1,5 @@
 ACQUIRE = """
-if redis.call('exists', KEYS[1]) == 0 then
-    local token = redis.call('incr', KEYS[2])
-    redis.call('psetex', KEYS[1], ARGV[2], ARGV[1] .. ':' .. token)
-    return token
-end
-return 0
-"""
-
-VERIFY = """
-if redis.call('get', KEYS[1]) == ARGV[1] then
+if redis.call('set', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then
     return 1
 end
 return 0
@@ -26,7 +17,7 @@ LOAD = """
 if redis.call('get', KEYS[1]) ~= ARGV[1] then
     return {0}
 end
-local payload = redis.call('hget', KEYS[2], 'payload')
+local payload = redis.call('get', KEYS[2])
 if payload then
     redis.call('pexpire', KEYS[2], ARGV[2])
     return {1, payload}
@@ -38,12 +29,7 @@ SAVE = """
 if redis.call('get', KEYS[1]) ~= ARGV[1] then
     return 0
 end
-local current = tonumber(redis.call('hget', KEYS[2], 'version') or '0')
-if current ~= tonumber(ARGV[2]) then
-    return -1
-end
-redis.call('hset', KEYS[2], 'version', ARGV[3], 'payload', ARGV[4])
-redis.call('pexpire', KEYS[2], ARGV[5])
+redis.call('psetex', KEYS[2], ARGV[3], ARGV[2])
 return 1
 """
 
@@ -62,4 +48,3 @@ if redis.call('get', KEYS[1]) == ARGV[1] then
 end
 return 0
 """
-