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

{cortex_agent_sdk-0.2.1 → cortex_agent_sdk-0.3.0}/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.0
+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
@@ -17,8 +17,6 @@ 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'
 Provides-Extra: openai
 Provides-Extra: redis
 Requires-Dist: redis>=8.1.0; extra == 'redis'
@@ -26,13 +24,13 @@ 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`.
 
@@ -138,6 +136,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 +168,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 +183,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.0}/README.md

@@ -1,12 +1,12 @@
 # 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`.
 
@@ -112,6 +112,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 +144,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 +159,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.0}/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.0"
+description = "Sesiones y capacidades puntuales para agentes multiprovider con Pydantic AI"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"
@@ -26,9 +26,6 @@ Issues = "https://github.com/epok200/cortex_agent_sdk/issues"
 
 [project.optional-dependencies]
 openai = []
-all = [
-    "redis>=8.1.0",
-]
 redis = [
     "redis>=8.1.0",
 ]

cortex_agent_sdk-0.3.0/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