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

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-agent-sdk
-Version: 0.0.2
+Version: 0.0.4
 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
@@ -137,10 +137,51 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+Los type hints son la vía recomendada para tools sencillas. Cortex infiere el contrato visible y
+valida los argumentos antes de ejecutar la función; no hace falta escribir JSON Schema ni
+`ToolSpec` manualmente.
+
+### Contratos Pydantic
+
+Cuando los argumentos forman un contrato reutilizable o tienen validaciones entre campos, puede
+usarse un `BaseModel` como fuente de verdad:
+
+```python
+from datetime import datetime
+from typing import Self
+
+from pydantic import BaseModel, Field, model_validator
+
+from cortex_agent_sdk import final_answer
+
+
+class ReminderArgs(BaseModel):
+    message: str = Field(min_length=1, description="Texto del recordatorio.")
+    when: datetime | None = None
+    cron: str | None = None
+
+    @model_validator(mode="after")
+    def validate_mode(self) -> Self:
+        if (self.when is None) == (self.cron is None):
+            raise ValueError("se requiere exactamente when o cron")
+        return self
+
+
+@final_answer(input_model=ReminderArgs)
+async def schedule_reminder(args: ReminderArgs) -> str:
+    """Programa un recordatorio."""
+    return f"Recordatorio: {args.message}"
+```
+
+Cortex genera el `ToolSpec` neutral a partir del modelo, rechaza propiedades adicionales y entrega a
+la función una instancia ya validada. `ToolBinding(input_model=...)` ofrece la misma capacidad para
+tools construidas en runtime. El `ToolSpec` manual continúa disponible como escape hatch cuando el
+schema visible necesita construirse dinámicamente o requiere control de bajo nivel.
+
 ## Capacidades del alfa
 
 - Loop async acotado.
-- Tools async con schema inferido o explícito.
+- Tools async con schema inferido, Pydantic explícito o `ToolSpec` manual.
 - Historial y sesiones en memoria, Redis o PostgreSQL.
 - Hooks locales.
 - Timeouts para providers y tools.
@@ -159,6 +200,7 @@ renovable, fencing token y compare-and-swap.
 Redis no requiere inicialización de schema:
 
 ```python
+import asyncio
 import os
 
 from cortex_agent_sdk import Agent
@@ -166,26 +208,38 @@ 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()
+async def main() -> None:
+    store = RedisSessionStore(os.environ["REDIS_URL"])
+    async with Agent(
+        OpenAIEngine("gpt-5.6-luna"),
+        session_store=store,
+        own_session_store=True,
+    ) as agent:
+        result = await agent.run("Hola", session_id="producto:tenant:usuario")
+    print(result.text)
+
+
+asyncio.run(main())
 ```
 
 PostgreSQL exige crear su tabla de forma explícita una vez:
 
 ```python
+import asyncio
 import os
 
 from cortex_agent_sdk.postgres import PostgresSessionStore
 
 
-store = PostgresSessionStore(os.environ["POSTGRES_URL"])
-await store.setup()
+async def main() -> None:
+    store = PostgresSessionStore(os.environ["POSTGRES_URL"])
+    try:
+        await store.setup()
+    finally:
+        await store.aclose()
+
+
+asyncio.run(main())
 ```
 
 Una tarea periódica puede ejecutar `await store.cleanup_expired()` para vaciar historiales vencidos
@@ -193,8 +247,12 @@ que nunca volvieron a solicitarse. El row mínimo permanece para conservar el fe
 
 `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.
+`AgentOptions.shutdown_timeout_seconds` y cubre tanto el drenado como el cierre físico. Si vence
+mientras hay un turno activo, el SDK no lo cancela ni empieza a cerrar recursos. Si vence durante el
+cierre físico, algunos recursos podrían haberse cerrado ya. El timeout es un presupuesto de cierre,
+no una garantía estricta de tiempo de pared: un finalizador que resista la cancelación puede retrasar
+el retorno para no abandonar recursos a medias. Al excederlo regresa `RUNTIME_CIERRE_TIMEOUT` y una
+segunda llamada a `aclose()` reintenta lo pendiente.
 
 Una sesión dañada o deliberadamente descartada se elimina mediante
 `await agent.reset_session(session_id)`.

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/README.md

@@ -103,10 +103,51 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+Los type hints son la vía recomendada para tools sencillas. Cortex infiere el contrato visible y
+valida los argumentos antes de ejecutar la función; no hace falta escribir JSON Schema ni
+`ToolSpec` manualmente.
+
+### Contratos Pydantic
+
+Cuando los argumentos forman un contrato reutilizable o tienen validaciones entre campos, puede
+usarse un `BaseModel` como fuente de verdad:
+
+```python
+from datetime import datetime
+from typing import Self
+
+from pydantic import BaseModel, Field, model_validator
+
+from cortex_agent_sdk import final_answer
+
+
+class ReminderArgs(BaseModel):
+    message: str = Field(min_length=1, description="Texto del recordatorio.")
+    when: datetime | None = None
+    cron: str | None = None
+
+    @model_validator(mode="after")
+    def validate_mode(self) -> Self:
+        if (self.when is None) == (self.cron is None):
+            raise ValueError("se requiere exactamente when o cron")
+        return self
+
+
+@final_answer(input_model=ReminderArgs)
+async def schedule_reminder(args: ReminderArgs) -> str:
+    """Programa un recordatorio."""
+    return f"Recordatorio: {args.message}"
+```
+
+Cortex genera el `ToolSpec` neutral a partir del modelo, rechaza propiedades adicionales y entrega a
+la función una instancia ya validada. `ToolBinding(input_model=...)` ofrece la misma capacidad para
+tools construidas en runtime. El `ToolSpec` manual continúa disponible como escape hatch cuando el
+schema visible necesita construirse dinámicamente o requiere control de bajo nivel.
+
 ## Capacidades del alfa
 
 - Loop async acotado.
-- Tools async con schema inferido o explícito.
+- Tools async con schema inferido, Pydantic explícito o `ToolSpec` manual.
 - Historial y sesiones en memoria, Redis o PostgreSQL.
 - Hooks locales.
 - Timeouts para providers y tools.
@@ -125,6 +166,7 @@ renovable, fencing token y compare-and-swap.
 Redis no requiere inicialización de schema:
 
 ```python
+import asyncio
 import os
 
 from cortex_agent_sdk import Agent
@@ -132,26 +174,38 @@ 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()
+async def main() -> None:
+    store = RedisSessionStore(os.environ["REDIS_URL"])
+    async with Agent(
+        OpenAIEngine("gpt-5.6-luna"),
+        session_store=store,
+        own_session_store=True,
+    ) as agent:
+        result = await agent.run("Hola", session_id="producto:tenant:usuario")
+    print(result.text)
+
+
+asyncio.run(main())
 ```
 
 PostgreSQL exige crear su tabla de forma explícita una vez:
 
 ```python
+import asyncio
 import os
 
 from cortex_agent_sdk.postgres import PostgresSessionStore
 
 
-store = PostgresSessionStore(os.environ["POSTGRES_URL"])
-await store.setup()
+async def main() -> None:
+    store = PostgresSessionStore(os.environ["POSTGRES_URL"])
+    try:
+        await store.setup()
+    finally:
+        await store.aclose()
+
+
+asyncio.run(main())
 ```
 
 Una tarea periódica puede ejecutar `await store.cleanup_expired()` para vaciar historiales vencidos
@@ -159,8 +213,12 @@ que nunca volvieron a solicitarse. El row mínimo permanece para conservar el fe
 
 `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.
+`AgentOptions.shutdown_timeout_seconds` y cubre tanto el drenado como el cierre físico. Si vence
+mientras hay un turno activo, el SDK no lo cancela ni empieza a cerrar recursos. Si vence durante el
+cierre físico, algunos recursos podrían haberse cerrado ya. El timeout es un presupuesto de cierre,
+no una garantía estricta de tiempo de pared: un finalizador que resista la cancelación puede retrasar
+el retorno para no abandonar recursos a medias. Al excederlo regresa `RUNTIME_CIERRE_TIMEOUT` y una
+segunda llamada a `aclose()` reintenta lo pendiente.
 
 Una sesión dañada o deliberadamente descartada se elimina mediante
 `await agent.reset_session(session_id)`.

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

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.0.2"
+version = "0.0.4"
 description = "SDK async y multiproveedor para construir agentes con control explícito"
 readme = "README.md"
 license = "Apache-2.0"

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/agent.py

@@ -43,7 +43,10 @@ class Agent:
         self._options = options or AgentOptions()
         self._history = HistoryPipeline(history_transform, self._options.max_history_turns)
         self._hooks = HookChain(hooks or AgentHooks(), self._options.hook_timeout_seconds)
-        self._session_store = session_store or MemorySessionStore()
+        if session_store is None:
+            self._session_store = MemorySessionStore()
+        else:
+            self._session_store = session_store
         self._own_engine = own_engine
         self._own_session_store = session_store is None or own_session_store
         self._lifecycle = AgentLifecycle()
@@ -65,7 +68,7 @@ class Agent:
         instructions: str | None = None,
     ) -> AgentResult:
         async with self._lifecycle.run():
-            if not text:
+            if not text.strip():
                 raise AppError(CodigoError.CONFIG_INVALIDA, "text no puede estar vacío")
 
             tool_set = ToolSet.build((*self._static_tools, *tuple(tools)))

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/engine.py

@@ -1,12 +1,12 @@
 from collections.abc import Mapping
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Protocol, cast, runtime_checkable
+from typing import Protocol, runtime_checkable
 
 from pydantic import BaseModel, ConfigDict, JsonValue, field_serializer, field_validator
 
 from cortex_agent_sdk.history.models import ToolCallPart, Turn
-from cortex_agent_sdk.immutable import FrozenJsonValue, freeze_json, thaw_json
+from cortex_agent_sdk.immutable import JsonObject, freeze_json_object, thaw_json_object
 from cortex_agent_sdk.tools.models import ToolSpec
 
 
@@ -15,25 +15,22 @@ class ToolCall(BaseModel):
 
     call_id: str
     name: str
-    arguments: Mapping[str, JsonValue]
+    arguments: JsonObject
 
     @field_validator("arguments", mode="after")
     @classmethod
     def freeze_arguments(
         cls,
-        value: Mapping[str, JsonValue],
-    ) -> Mapping[str, JsonValue]:
-        frozen = freeze_json(value)
-        if not isinstance(frozen, Mapping):
-            raise TypeError("arguments debe ser un objeto")
-        return cast(Mapping[str, JsonValue], frozen)
+        value: JsonObject,
+    ) -> JsonObject:
+        return freeze_json_object(value)
 
     @field_serializer("arguments", when_used="json")
     def serialize_arguments(
         self,
-        value: Mapping[str, JsonValue],
-    ) -> dict[str, object]:
-        return {key: thaw_json(cast(FrozenJsonValue, item)) for key, item in value.items()}
+        value: JsonObject,
+    ) -> dict[str, JsonValue]:
+        return thaw_json_object(value)
 
 
 @dataclass(frozen=True, slots=True)
@@ -117,7 +114,7 @@ class EngineResult:
             isinstance(call, ToolCall) for call in self.tool_calls
         )
         valid_structured = self.structured is None or isinstance(self.structured, BaseModel)
-        if not isinstance(self.turn, Turn) or not valid_calls:
+        if not isinstance(self.turn, Turn) or self.turn.role != "assistant" or not valid_calls:
             raise TypeError("EngineResult inválido")
         turn_calls = tuple(part for part in self.turn.parts if isinstance(part, ToolCallPart))
         aligned_calls = len(turn_calls) == len(self.tool_calls) and all(
@@ -128,7 +125,15 @@ class EngineResult:
         )
         if not aligned_calls:
             raise TypeError("tool_calls no coincide con el turno")
-        if not isinstance(self.usage, Usage) or not self.provider or not self.model:
+        valid_identity = (
+            isinstance(self.provider, str)
+            and bool(self.provider)
+            and isinstance(self.model, str)
+            and bool(self.model)
+        )
+        provider_state = self.turn.provider_state
+        state_matches = provider_state is None or provider_state.provider == self.provider
+        if not isinstance(self.usage, Usage) or not valid_identity or not state_matches:
             raise TypeError("EngineResult inválido")
         if self.stop_reason is not None and not isinstance(self.stop_reason, str):
             raise TypeError("stop_reason inválido")
@@ -147,4 +152,3 @@ class ModelEngine(Protocol):
     async def generate(self, request: EngineRequest) -> EngineResult: ...
 
     async def aclose(self) -> None: ...
-

cortex_agent_sdk-0.0.4/src/cortex_agent_sdk/google/__init__.py

@@ -0,0 +1 @@
+"""Espacio reservado para el futuro engine de Google."""

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/history/models.py

@@ -1,21 +1,28 @@
 import base64
 from collections.abc import Mapping
-from typing import Annotated, Literal, cast
-
-from pydantic import BaseModel, ConfigDict, Field, JsonValue, field_serializer, field_validator
+from typing import Annotated, Literal, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    JsonValue,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
 
 from cortex_agent_sdk.immutable import (
-    FrozenJsonValue,
-    FrozenProviderValue,
-    freeze_json,
-    freeze_provider,
-    thaw_json,
+    JsonObject,
+    ProviderItem,
+    ProviderValue,
+    freeze_json_object,
+    freeze_provider_item,
+    thaw_json_object,
 )
 
 _BYTES_TAG = "$cortex.bytes"
 
-ProviderValue = FrozenProviderValue
-
 
 class ProviderState(BaseModel):
     """Items nativos necesarios para continuar sin pérdida con un provider."""
@@ -23,7 +30,7 @@ class ProviderState(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     provider: str
-    items: tuple[Mapping[str, ProviderValue], ...]
+    items: tuple[ProviderItem, ...]
 
     @field_validator("items", mode="before")
     @classmethod
@@ -34,14 +41,14 @@ class ProviderState(BaseModel):
     @classmethod
     def freeze_items(
         cls,
-        value: tuple[Mapping[str, ProviderValue], ...],
-    ) -> tuple[Mapping[str, ProviderValue], ...]:
-        return tuple(_freeze_provider_item(item) for item in value)
+        value: tuple[ProviderItem, ...],
+    ) -> tuple[ProviderItem, ...]:
+        return tuple(freeze_provider_item(item) for item in value)
 
     @field_serializer("items", when_used="json")
     def encode_bytes(
         self,
-        items: tuple[Mapping[str, ProviderValue], ...],
+        items: tuple[ProviderItem, ...],
     ) -> tuple[dict[str, object], ...]:
         return tuple(
             {key: _encode_provider_bytes(value) for key, value in item.items()} for item in items
@@ -61,25 +68,22 @@ class ToolCallPart(BaseModel):
     type: Literal["tool_call"] = "tool_call"
     call_id: str
     name: str
-    arguments: Mapping[str, JsonValue]
+    arguments: JsonObject
 
     @field_validator("arguments", mode="after")
     @classmethod
     def freeze_arguments(
         cls,
-        value: Mapping[str, JsonValue],
-    ) -> Mapping[str, JsonValue]:
-        frozen = freeze_json(value)
-        if not isinstance(frozen, Mapping):
-            raise TypeError("arguments debe ser un objeto")
-        return cast(Mapping[str, JsonValue], frozen)
+        value: JsonObject,
+    ) -> JsonObject:
+        return freeze_json_object(value)
 
     @field_serializer("arguments", when_used="json")
     def serialize_arguments(
         self,
-        value: Mapping[str, JsonValue],
-    ) -> dict[str, object]:
-        return {key: thaw_json(cast(FrozenJsonValue, item)) for key, item in value.items()}
+        value: JsonObject,
+    ) -> dict[str, JsonValue]:
+        return thaw_json_object(value)
 
 
 class ToolResultPart(BaseModel):
@@ -93,7 +97,7 @@ class ToolResultPart(BaseModel):
     error_code: str | None = None
 
 
-Part = Annotated[TextPart | ToolCallPart | ToolResultPart, Field(discriminator="type")]
+HistoryPart = Annotated[TextPart | ToolCallPart | ToolResultPart, Field(discriminator="type")]
 
 
 class Turn(BaseModel):
@@ -102,9 +106,24 @@ class Turn(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     role: Literal["user", "assistant", "tool"]
-    parts: tuple[Part, ...]
+    parts: tuple[HistoryPart, ...]
     provider_state: ProviderState | None = None
 
+    @model_validator(mode="after")
+    def validate_role_contract(self) -> Self:
+        if self.role == "user":
+            valid_parts = all(isinstance(part, TextPart) for part in self.parts)
+        elif self.role == "assistant":
+            valid_parts = all(isinstance(part, TextPart | ToolCallPart) for part in self.parts)
+        else:
+            valid_parts = all(isinstance(part, ToolResultPart) for part in self.parts)
+
+        if not valid_parts:
+            raise ValueError(f"parts incompatibles con role={self.role}")
+        if self.role != "assistant" and self.provider_state is not None:
+            raise ValueError("provider_state requiere role=assistant")
+        return self
+
     @classmethod
     def user(cls, text: str) -> "Turn":
         return cls(role="user", parts=(TextPart(text=text),))
@@ -133,13 +152,3 @@ def _decode_provider_bytes(value: object) -> object:
     if set(value) == {_BYTES_TAG} and isinstance(value[_BYTES_TAG], str):
         return base64.b64decode(value[_BYTES_TAG], validate=True)
     return {key: _decode_provider_bytes(item) for key, item in value.items()}
-
-
-def _freeze_provider_item(
-    value: Mapping[str, ProviderValue],
-) -> Mapping[str, ProviderValue]:
-    frozen = freeze_provider(value)
-    if not isinstance(frozen, Mapping):
-        raise TypeError("provider item debe ser un objeto")
-    return frozen
-

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/history/transform.py

@@ -1,4 +1,4 @@
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
 from datetime import datetime
 
@@ -13,5 +13,4 @@ class TransformContext:
     session_id: str | None
 
 
-HistoryTransform = Callable[[TransformContext], Awaitable[tuple[Turn, ...] | list[Turn]]]
-
+HistoryTransform = Callable[[TransformContext], Awaitable[Sequence[Turn]]]

cortex_agent_sdk-0.0.4/src/cortex_agent_sdk/immutable.py

@@ -0,0 +1,75 @@
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import cast
+
+from pydantic import JsonValue
+
+type FrozenJsonValue = (
+    bool | int | float | str | tuple[FrozenJsonValue, ...] | Mapping[str, FrozenJsonValue] | None
+)
+type JsonInputObject = Mapping[str, JsonValue]
+type FrozenJsonObject = Mapping[str, FrozenJsonValue]
+type JsonObject = JsonInputObject | FrozenJsonObject
+type ProviderValue = (
+    bool
+    | int
+    | float
+    | str
+    | bytes
+    | tuple[ProviderValue, ...]
+    | Mapping[str, ProviderValue]
+    | None
+)
+type ProviderItem = Mapping[str, ProviderValue]
+
+
+def freeze_json_object(value: JsonObject) -> FrozenJsonObject:
+    frozen = {key: _freeze_json(item) for key, item in value.items()}
+    return MappingProxyType(frozen)
+
+
+def thaw_json_object(value: JsonObject) -> dict[str, JsonValue]:
+    return {key: _thaw_json(item) for key, item in value.items()}
+
+
+def freeze_provider_item(value: ProviderItem) -> ProviderItem:
+    frozen = {key: _freeze_provider(item) for key, item in value.items()}
+    return MappingProxyType(frozen)
+
+
+def thaw_provider_item(value: ProviderItem) -> dict[str, object]:
+    return {key: _thaw_provider(item) for key, item in value.items()}
+
+
+def _freeze_json(value: JsonValue | FrozenJsonValue) -> FrozenJsonValue:
+    if isinstance(value, list | tuple):
+        return tuple(_freeze_json(item) for item in value)
+    if isinstance(value, Mapping):
+        frozen = {key: _freeze_json(item) for key, item in value.items()}
+        return MappingProxyType(frozen)
+    return value
+
+
+def _thaw_json(value: JsonValue | FrozenJsonValue) -> JsonValue:
+    if isinstance(value, list | tuple):
+        return [_thaw_json(item) for item in value]
+    if isinstance(value, Mapping):
+        return {key: _thaw_json(item) for key, item in value.items()}
+    return cast(JsonValue, value)
+
+
+def _freeze_provider(value: ProviderValue) -> ProviderValue:
+    if isinstance(value, tuple):
+        return tuple(_freeze_provider(item) for item in value)
+    if isinstance(value, Mapping):
+        frozen = {key: _freeze_provider(item) for key, item in value.items()}
+        return MappingProxyType(frozen)
+    return value
+
+
+def _thaw_provider(value: ProviderValue) -> object:
+    if isinstance(value, tuple):
+        return [_thaw_provider(item) for item in value]
+    if isinstance(value, Mapping):
+        return {key: _thaw_provider(item) for key, item in value.items()}
+    return value

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/openai/__init__.py

@@ -1,2 +1,3 @@
 from cortex_agent_sdk.openai.engine import OpenAIEngine
+from cortex_agent_sdk.openai.models import OpenAIModel, OpenAIModels
 from cortex_agent_sdk.openai.options import OpenAIOptions