cortex-agent-sdk 0.2.1__tar.gz → 0.3.1__tar.gz

{cortex_agent_sdk-0.2.1 → cortex_agent_sdk-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: cortex-agent-sdk
-Version: 0.2.1
-Summary: Sesiones Memory y Redis para agentes multiprovider con Pydantic AI
+Version: 0.3.1
+Summary: Sesiones y capacidades puntuales para agentes multiprovider 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
@@ -16,53 +16,60 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.13
-Requires-Dist: pydantic-ai-slim[google,openai]<3,>=2.27
-Provides-Extra: all
-Requires-Dist: redis>=8.1.0; extra == 'all'
+Requires-Dist: pydantic-ai-slim<3,>=2.27
+Provides-Extra: google
+Requires-Dist: pydantic-ai-slim[google]<3,>=2.27; extra == 'google'
 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 multiprovider construidos directamente con
-Pydantic AI.
+Cortex agrega sesiones Memory y Redis, junto con capacidades puntuales que Pydantic AI no incluye,
+a agentes multiprovider 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.
+historial. Cortex aporta persistencia conversacional con un turno activo por sesión y capacidades
+opcionales construidas sobre sus hooks públicos.
 
 > 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`, con Google y OpenAI instalados por Cortex.
+- Pydantic AI `>=2.27,<3`.
 
 ## Instalación
 
-Google, OpenAI y sesiones en memoria:
+Solo sesiones en memoria y capabilities:
 
 ```bash
 uv add cortex-agent-sdk
 ```
 
-Google, OpenAI y Redis:
+OpenAI y sesiones en memoria:
+
+```bash
+uv add "cortex-agent-sdk[openai]"
+```
+
+OpenAI y Redis:
 
 ```bash
-uv add "cortex-agent-sdk[redis]"
+uv add "cortex-agent-sdk[openai,redis]"
 ```
 
-La instalación base incluye Google y OpenAI, además de los endpoints compatibles con OpenAI. Otros
-providers pueden agregarse desde los extras oficiales de Pydantic AI cuando un producto realmente
-los necesite. Cortex no implementa adapters paralelos.
+Google se instala con el extra `google`. Cada producto elige únicamente sus providers. Cortex no
+implementa adapters paralelos ni ofrece un extra que los instale todos.
 
 ## 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.
+El siguiente ejemplo requiere el extra `openai`.
 
 ```python
 import asyncio
@@ -138,6 +145,25 @@ agent = Agent(model)
 
 El context manager de `Agent` administra el transporte del provider.
 
+## Fallback del resultado de una tool
+
+Pydantic AI reintenta cuando un modelo termina sin texto. Para tools cuyo resultado ya es una
+respuesta completa, Cortex puede reutilizar el último resultado exitoso del mismo run:
+
+```python
+from pydantic_ai import Agent
+
+from cortex_agent_sdk.capabilities import last_tool_result_fallback
+
+agent = Agent(
+    "openai-responses:gpt-5.6-luna",
+    capabilities=[last_tool_result_fallback({"confirmar_agenda"})],
+)
+```
+
+La aplicación conserva la decisión sobre las tools elegibles. La capacidad no usa resultados
+fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo.
+
 ## Migración desde el runtime anterior
 
 | Antes | Ahora |
@@ -151,7 +177,7 @@ El context manager de `Agent` administra el transporte del provider.
 | `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` |
+| `fallback_answer` | `last_tool_result_fallback(...)` opcional |
 | `AgentOptions` | `UsageLimits`, settings del modelo y argumentos de `Agent` |
 | `AgentResult.text` | `AgentRunResult.output` |
 | `SessionStore.acquire` | `SessionStore.turn` + `Session.replace` |
@@ -166,6 +192,7 @@ Pydantic AI.
 - `cortex_agent_sdk.sessions.SessionStore`
 - `cortex_agent_sdk.sessions.MemorySessionStore`
 - `cortex_agent_sdk.redis.RedisSessionStore`
+- `cortex_agent_sdk.capabilities.last_tool_result_fallback`
 - `cortex_agent_sdk.errores.AppError`
 - `cortex_agent_sdk.errores.CodigoError`
 - `cortex_agent_sdk.errores.Severidad`

{cortex_agent_sdk-0.2.1 → cortex_agent_sdk-0.3.1}/README.md

@@ -1,42 +1,48 @@
 # Cortex Agent SDK
 
-Cortex agrega sesiones Memory y Redis a agentes multiprovider construidos directamente con
-Pydantic AI.
+Cortex agrega sesiones Memory y Redis, junto con capacidades puntuales que Pydantic AI no incluye,
+a agentes multiprovider 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.
+historial. Cortex aporta persistencia conversacional con un turno activo por sesión y capacidades
+opcionales construidas sobre sus hooks públicos.
 
 > 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`, con Google y OpenAI instalados por Cortex.
+- Pydantic AI `>=2.27,<3`.
 
 ## Instalación
 
-Google, OpenAI y sesiones en memoria:
+Solo sesiones en memoria y capabilities:
 
 ```bash
 uv add cortex-agent-sdk
 ```
 
-Google, OpenAI y Redis:
+OpenAI y sesiones en memoria:
+
+```bash
+uv add "cortex-agent-sdk[openai]"
+```
+
+OpenAI y Redis:
 
 ```bash
-uv add "cortex-agent-sdk[redis]"
+uv add "cortex-agent-sdk[openai,redis]"
 ```
 
-La instalación base incluye Google y OpenAI, además de los endpoints compatibles con OpenAI. Otros
-providers pueden agregarse desde los extras oficiales de Pydantic AI cuando un producto realmente
-los necesite. Cortex no implementa adapters paralelos.
+Google se instala con el extra `google`. Cada producto elige únicamente sus providers. Cortex no
+implementa adapters paralelos ni ofrece un extra que los instale todos.
 
 ## 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.
+El siguiente ejemplo requiere el extra `openai`.
 
 ```python
 import asyncio
@@ -112,6 +118,25 @@ agent = Agent(model)
 
 El context manager de `Agent` administra el transporte del provider.
 
+## Fallback del resultado de una tool
+
+Pydantic AI reintenta cuando un modelo termina sin texto. Para tools cuyo resultado ya es una
+respuesta completa, Cortex puede reutilizar el último resultado exitoso del mismo run:
+
+```python
+from pydantic_ai import Agent
+
+from cortex_agent_sdk.capabilities import last_tool_result_fallback
+
+agent = Agent(
+    "openai-responses:gpt-5.6-luna",
+    capabilities=[last_tool_result_fallback({"confirmar_agenda"})],
+)
+```
+
+La aplicación conserva la decisión sobre las tools elegibles. La capacidad no usa resultados
+fallidos, vacíos ni pertenecientes a otro run, y no reemplaza texto o nuevas llamadas del modelo.
+
 ## Migración desde el runtime anterior
 
 | Antes | Ahora |
@@ -125,7 +150,7 @@ El context manager de `Agent` administra el transporte del provider.
 | `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` |
+| `fallback_answer` | `last_tool_result_fallback(...)` opcional |
 | `AgentOptions` | `UsageLimits`, settings del modelo y argumentos de `Agent` |
 | `AgentResult.text` | `AgentRunResult.output` |
 | `SessionStore.acquire` | `SessionStore.turn` + `Session.replace` |
@@ -140,6 +165,7 @@ Pydantic AI.
 - `cortex_agent_sdk.sessions.SessionStore`
 - `cortex_agent_sdk.sessions.MemorySessionStore`
 - `cortex_agent_sdk.redis.RedisSessionStore`
+- `cortex_agent_sdk.capabilities.last_tool_result_fallback`
 - `cortex_agent_sdk.errores.AppError`
 - `cortex_agent_sdk.errores.CodigoError`
 - `cortex_agent_sdk.errores.Severidad`

{cortex_agent_sdk-0.2.1 → cortex_agent_sdk-0.3.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.2.1"
-description = "Sesiones Memory y Redis para agentes multiprovider con Pydantic AI"
+version = "0.3.1"
+description = "Sesiones y capacidades puntuales para agentes multiprovider con Pydantic AI"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"
@@ -17,7 +17,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "pydantic-ai-slim[google,openai]>=2.27,<3",
+    "pydantic-ai-slim>=2.27,<3",
 ]
 
 [project.urls]
@@ -25,9 +25,11 @@ Repository = "https://github.com/epok200/cortex_agent_sdk"
 Issues = "https://github.com/epok200/cortex_agent_sdk/issues"
 
 [project.optional-dependencies]
-openai = []
-all = [
-    "redis>=8.1.0",
+google = [
+    "pydantic-ai-slim[google]>=2.27,<3",
+]
+openai = [
+    "pydantic-ai-slim[openai]>=2.27,<3",
 ]
 redis = [
     "redis>=8.1.0",

cortex_agent_sdk-0.3.1/src/cortex_agent_sdk/capabilities.py

@@ -0,0 +1,62 @@
+"""Capacidades opcionales para agentes Pydantic AI."""
+
+from collections.abc import Collection
+from dataclasses import replace
+from typing import Any
+
+from pydantic_ai import ModelResponse, RunContext, TextPart
+from pydantic_ai.capabilities.hooks import Hooks
+from pydantic_ai.messages import ModelRequest, ToolReturnPart
+from pydantic_ai.models import ModelRequestContext
+
+__all__ = ["last_tool_result_fallback"]
+
+
+def last_tool_result_fallback(tool_names: str | Collection[str]) -> Hooks[Any]:
+    """Usa el último resultado elegible si el modelo termina sin texto."""
+    if isinstance(tool_names, str):
+        eligible_tools = frozenset((tool_names,))
+    else:
+        eligible_tools = frozenset(tool_names)
+
+    def use_last_tool_result(
+        ctx: RunContext[Any],
+        *,
+        request_context: ModelRequestContext,
+        response: ModelResponse,
+    ) -> ModelResponse:
+        if response.finish_reason not in {None, "stop"}:
+            return response
+        if response.text and response.text.strip():
+            return response
+        if response.tool_calls:
+            return response
+
+        result = _last_tool_result(request_context, ctx.run_id, eligible_tools)
+        if result is None:
+            return response
+        return replace(response, parts=[*response.parts, TextPart(result)])
+
+    return Hooks(after_model_request=use_last_tool_result)
+
+
+def _last_tool_result(
+    request_context: ModelRequestContext,
+    run_id: str | None,
+    tool_names: Collection[str],
+) -> str | None:
+    if run_id is None:
+        return None
+    for message in reversed(request_context.messages):
+        if not isinstance(message, ModelRequest) or message.run_id != run_id:
+            continue
+        for part in reversed(message.parts):
+            if (
+                isinstance(part, ToolReturnPart)
+                and part.outcome == "success"
+                and part.tool_name in tool_names
+                and isinstance(part.content, str)
+                and part.content.strip()
+            ):
+                return part.content
+    return None