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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-agent-sdk
-Version: 0.0.2
+Version: 0.0.3
 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
@@ -159,6 +159,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 +167,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 +206,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.3}/README.md

@@ -125,6 +125,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 +133,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 +172,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.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.0.2"
+version = "0.0.3"
 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.3}/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.3}/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.3/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.3}/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.3}/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.3/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.3}/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

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.3}/src/cortex_agent_sdk/openai/engine.py

@@ -11,24 +11,24 @@ from cortex_agent_sdk.engine import EngineRequest, EngineResult, ToolCall, Usage
 from cortex_agent_sdk.errores import AppError, CodigoError
 from cortex_agent_sdk.gateway import OpenAICompatibleGateway
 from cortex_agent_sdk.history.models import (
+    HistoryPart,
     ProviderState,
-    ProviderValue,
     TextPart,
     ToolCallPart,
     ToolResultPart,
     Turn,
 )
 from cortex_agent_sdk.immutable import (
-    FrozenJsonValue,
-    FrozenProviderValue,
-    thaw_json,
-    thaw_provider,
+    ProviderItem,
+    thaw_json_object,
+    thaw_provider_item,
 )
+from cortex_agent_sdk.openai.models import OpenAIModels
 from cortex_agent_sdk.openai.options import OpenAIOptions
 from cortex_agent_sdk.tools.models import ToolSpec
 
 _JSON_OBJECT = TypeAdapter(dict[str, JsonValue])
-_PROVIDER_OBJECT = TypeAdapter(dict[str, ProviderValue])
+_PROVIDER_OBJECT = TypeAdapter(ProviderItem)
 
 
 class OpenAIEngine:
@@ -52,9 +52,13 @@ class OpenAIEngine:
 
         self._model = model
         self._options = options or OpenAIOptions()
-        self._client = client or self._create_client(api_key, gateway)
+        if client is None:
+            self._client = self._create_client(api_key, gateway)
+        else:
+            self._client = client
         self._owns_client = client is None
         self._closed = False
+        self._models = OpenAIModels(self._client, self._ensure_open)
 
     @property
     def provider(self) -> str:
@@ -64,17 +68,19 @@ class OpenAIEngine:
     def model(self) -> str:
         return self._model
 
+    @property
+    def models(self) -> OpenAIModels:
+        return self._models
+
     async def __aenter__(self) -> Self:
-        if self._closed:
-            raise AppError(CodigoError.RECURSO_CERRADO, "OpenAIEngine cerrado")
+        self._ensure_open()
         return self
 
     async def __aexit__(self, *_: object) -> None:
         await self.aclose()
 
     async def generate(self, request: EngineRequest) -> EngineResult:
-        if self._closed:
-            raise AppError(CodigoError.RECURSO_CERRADO, "OpenAIEngine cerrado")
+        self._ensure_open()
 
         payload = cast(dict[str, Any], self._build_payload(request))
         try:
@@ -130,6 +136,10 @@ class OpenAIEngine:
                 ) from error
         self._closed = True
 
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise AppError(CodigoError.RECURSO_CERRADO, "OpenAIEngine cerrado")
+
     def _create_client(
         self,
         api_key: str | None,
@@ -205,7 +215,7 @@ def _build_input(history: tuple[Turn, ...]) -> list[ResponseInputItemParam]:
                     "historial contiene estado de otro provider",
                 )
             items.extend(
-                cast(ResponseInputItemParam, thaw_provider(cast(FrozenProviderValue, item)))
+                cast(ResponseInputItemParam, thaw_provider_item(item))
                 for item in turn.provider_state.items
             )
             continue
@@ -226,9 +236,7 @@ def _build_input(history: tuple[Turn, ...]) -> list[ResponseInputItemParam]:
 
 
 def _tool_payload(spec: ToolSpec) -> dict[str, object]:
-    parameters = {
-        key: thaw_json(cast(FrozenJsonValue, value)) for key, value in spec.parameters.items()
-    }
+    parameters = thaw_json_object(spec.parameters)
     return {
         "type": "function",
         "name": spec.name,
@@ -255,8 +263,8 @@ def _parse_tool_calls(output: list[object]) -> tuple[ToolCall, ...]:
     return tuple(calls)
 
 
-def _build_parts(text: str, calls: tuple[ToolCall, ...]):
-    parts: list[TextPart | ToolCallPart] = []
+def _build_parts(text: str, calls: tuple[ToolCall, ...]) -> tuple[HistoryPart, ...]:
+    parts: list[HistoryPart] = []
     if text:
         parts.append(TextPart(text=text))
     parts.extend(

cortex_agent_sdk-0.0.3/src/cortex_agent_sdk/openai/models.py

@@ -0,0 +1,57 @@
+from collections.abc import Callable
+from typing import Literal
+
+import openai
+from openai import AsyncOpenAI
+from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError
+
+from cortex_agent_sdk.errores import AppError, CodigoError
+
+
+class OpenAIModel(BaseModel):
+    """Modelo disponible según el catálogo nativo de OpenAI."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    id: str
+    created: int
+    object: Literal["model"]
+    owned_by: str
+
+
+_OPENAI_MODELS = TypeAdapter(tuple[OpenAIModel, ...])
+
+
+class OpenAIModels:
+    """Consulta el catálogo con el mismo cliente que usa el engine."""
+
+    def __init__(self, client: AsyncOpenAI, ensure_open: Callable[[], None]) -> None:
+        self._client = client
+        self._ensure_open = ensure_open
+
+    async def list(self) -> tuple[OpenAIModel, ...]:
+        self._ensure_open()
+        try:
+            response = await self._client.models.list()
+        except openai.APITimeoutError as error:
+            raise AppError(CodigoError.PROVIDER_TIMEOUT, "OpenAI agotó el timeout") from error
+        except openai.APIStatusError as error:
+            request_id = getattr(error, "request_id", None)
+            detail = f"OpenAI respondió {error.status_code}, request_id={request_id}"
+            raise AppError(CodigoError.PROVIDER_FALLO, detail) from error
+        except openai.APIConnectionError as error:
+            raise AppError(CodigoError.PROVIDER_FALLO, "falló la conexión con OpenAI") from error
+        except openai.APIError as error:
+            detail = f"OpenAI SDK lanzó {type(error).__name__}"
+            raise AppError(CodigoError.PROVIDER_FALLO, detail) from error
+
+        try:
+            return _OPENAI_MODELS.validate_python(
+                response.data,
+                from_attributes=True,
+            )
+        except ValidationError as error:
+            raise AppError(
+                CodigoError.PROVIDER_RESPUESTA_INVALIDA,
+                "OpenAI devolvió un catálogo de modelos inválido",
+            ) from error

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.3}/src/cortex_agent_sdk/redis/store.py

@@ -2,6 +2,7 @@ import asyncio
 import time
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass
 from datetime import UTC, datetime
 from hashlib import sha256
 from typing import Self, cast
@@ -19,6 +20,13 @@ from cortex_agent_sdk.sessions.store import SessionLease
 type _RedisArgument = str | bytes | int | float
 
 
+@dataclass(frozen=True, slots=True)
+class _RedisKeys:
+    lease: str
+    record: str
+    fence: str
+
+
 class _RedisLease:
     def __init__(
         self,
@@ -95,7 +103,10 @@ class RedisSessionStore:
         if not key_prefix or min(durations) <= 0:
             raise AppError(CodigoError.CONFIG_INVALIDA, "configuración de Redis inválida")
 
-        self._client = client or Redis.from_url(cast(str, url), decode_responses=False)
+        if client is None:
+            self._client = Redis.from_url(cast(str, url), decode_responses=False)
+        else:
+            self._client = client
         self._owns_client = client is None
         self._key_prefix = key_prefix.rstrip(":")
         self._ttl_milliseconds = _milliseconds(ttl_seconds)
@@ -138,9 +149,10 @@ class RedisSessionStore:
 
     async def reset(self, session_id: str, timeout_seconds: float = 5.0) -> None:
         async with self.acquire(session_id, timeout_seconds) as lease:
+            keys = self._keys(session_id)
             result = await self._eval(
                 scripts.RESET,
-                self._keys(session_id)[:2],
+                (keys.lease, keys.record),
                 self._lease_value(lease),
             )
             if int(cast(int, result)) != 1:
@@ -166,7 +178,7 @@ class RedisSessionStore:
         self._closed = True
 
     async def _acquire(self, session_id: str, owner: str, timeout_seconds: float) -> int:
-        lease_key, _, fence_key = self._keys(session_id)
+        keys = self._keys(session_id)
         deadline = time.monotonic() + timeout_seconds
         while True:
             remaining = deadline - time.monotonic()
@@ -174,7 +186,7 @@ class RedisSessionStore:
                 raise AppError(CodigoError.SESION_OCUPADA, f"sesión ocupada: {session_id}")
             result = await self._eval(
                 scripts.ACQUIRE,
-                (lease_key, fence_key),
+                (keys.lease, keys.fence),
                 owner,
                 self._lease_milliseconds,
                 timeout_seconds=remaining,
@@ -188,16 +200,16 @@ class RedisSessionStore:
             await asyncio.sleep(min(self._retry_interval_seconds, remaining))
 
     async def _verify(self, session_id: str, lease_value: str) -> None:
-        lease_key, _, _ = self._keys(session_id)
-        result = await self._eval(scripts.VERIFY, (lease_key,), lease_value)
+        keys = self._keys(session_id)
+        result = await self._eval(scripts.VERIFY, (keys.lease,), lease_value)
         if int(cast(int, result)) != 1:
             raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
     async def _renew(self, session_id: str, lease_value: str) -> None:
-        lease_key, _, _ = self._keys(session_id)
+        keys = self._keys(session_id)
         result = await self._eval(
             scripts.RENEW,
-            (lease_key,),
+            (keys.lease,),
             lease_value,
             self._lease_milliseconds,
         )
@@ -205,10 +217,10 @@ class RedisSessionStore:
             raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
     async def _load(self, session_id: str, lease_value: str) -> SessionRecord | None:
-        lease_key, session_key, _ = self._keys(session_id)
+        keys = self._keys(session_id)
         raw = await self._eval(
             scripts.LOAD,
-            (lease_key, session_key),
+            (keys.lease, keys.record),
             lease_value,
             self._ttl_milliseconds,
         )
@@ -226,10 +238,10 @@ class RedisSessionStore:
                 "updated_at": datetime.now(UTC),
             }
         )
-        lease_key, session_key, _ = self._keys(record.session_id)
+        keys = self._keys(record.session_id)
         result = await self._eval(
             scripts.SAVE,
-            (lease_key, session_key),
+            (keys.lease, keys.record),
             lease_value,
             record.version,
             saved.version,
@@ -244,8 +256,8 @@ class RedisSessionStore:
         raise AppError(CodigoError.SESION_LEASE_PERDIDO, "ownership de sesión perdido")
 
     async def _release(self, session_id: str, lease_value: str) -> None:
-        lease_key, _, _ = self._keys(session_id)
-        await self._eval(scripts.RELEASE, (lease_key,), lease_value)
+        keys = self._keys(session_id)
+        await self._eval(scripts.RELEASE, (keys.lease,), lease_value)
 
     async def _eval(
         self,
@@ -270,10 +282,14 @@ class RedisSessionStore:
                 f"Redis lanzó {type(error).__name__}",
             ) from error
 
-    def _keys(self, session_id: str) -> tuple[str, str, str]:
+    def _keys(self, session_id: str) -> _RedisKeys:
         digest = sha256(session_id.encode()).hexdigest()
         base = f"{self._key_prefix}:{{{digest}}}"
-        return f"{base}:lease", f"{base}:record", f"{base}:fence"
+        return _RedisKeys(
+            lease=f"{base}:lease",
+            record=f"{base}:record",
+            fence=f"{base}:fence",
+        )
 
     def _lease_value(self, lease: SessionLease) -> str:
         if not isinstance(lease, _RedisLease):
@@ -290,4 +306,3 @@ def _milliseconds(seconds: float) -> int:
     if value < 1:
         raise AppError(CodigoError.CONFIG_INVALIDA, "duración Redis demasiado pequeña")
     return value
-

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.3}/src/cortex_agent_sdk/tools/contracts.py

@@ -2,14 +2,14 @@ import inspect
 from collections.abc import Mapping
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import Annotated, Any, cast, get_args, get_origin, get_type_hints
+from typing import Annotated, Any, get_args, get_origin, get_type_hints
 
 from jsonschema import Draft202012Validator
 from jsonschema.exceptions import SchemaError
 from pydantic import BaseModel, ConfigDict, JsonValue, create_model
 
 from cortex_agent_sdk.errores import AppError, CodigoError
-from cortex_agent_sdk.immutable import FrozenJsonValue, thaw_json
+from cortex_agent_sdk.immutable import thaw_json_object
 from cortex_agent_sdk.tools.models import Injected, ToolBinding, ToolFunction, ToolSpec
 
 
@@ -148,5 +148,4 @@ def _explicit_validator(
 
 
 def _plain_schema(spec: ToolSpec) -> dict[str, JsonValue]:
-    return {key: thaw_json(cast(FrozenJsonValue, value)) for key, value in spec.parameters.items()}
-
+    return thaw_json_object(spec.parameters)

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.3}/src/cortex_agent_sdk/tools/execution.py

@@ -3,14 +3,13 @@ import json
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from types import MappingProxyType
-from typing import cast
 
 from pydantic import JsonValue, TypeAdapter, ValidationError
 
 from cortex_agent_sdk.engine import ToolCall
 from cortex_agent_sdk.errores import AppError, CodigoError
 from cortex_agent_sdk.history.models import ToolResultPart
-from cortex_agent_sdk.immutable import FrozenJsonValue, thaw_json
+from cortex_agent_sdk.immutable import thaw_json_object
 from cortex_agent_sdk.tools.contracts import ToolDefinition, build_definition
 from cortex_agent_sdk.tools.models import ToolBinding, ToolFunction, ToolSpec
 
@@ -132,9 +131,7 @@ def _validate_arguments(
     definition: ToolDefinition,
     call: ToolCall,
 ) -> dict[str, object] | ToolOutcome:
-    public_input = {
-        key: thaw_json(cast(FrozenJsonValue, value)) for key, value in call.arguments.items()
-    }
+    public_input = thaw_json_object(call.arguments)
     if definition.schema_validator is not None:
         schema_error = next(definition.schema_validator.iter_errors(public_input), None)
         if schema_error is not None:
@@ -178,4 +175,3 @@ def _failed_outcome(
     payload = {"ok": False, "error": {"code": code.value, "message": message}}
     output = json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
     return ToolOutcome(call, output, True, is_final_answer, code.value)
-

{cortex_agent_sdk-0.0.2 → cortex_agent_sdk-0.0.3}/src/cortex_agent_sdk/tools/models.py

@@ -1,10 +1,10 @@
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
-from typing import cast
+from types import MappingProxyType
 
 from pydantic import BaseModel, ConfigDict, JsonValue, field_serializer, field_validator
 
-from cortex_agent_sdk.immutable import FrozenJsonValue, freeze_json, thaw_json
+from cortex_agent_sdk.immutable import JsonObject, freeze_json_object, thaw_json_object
 
 
 class _InjectedMarker:
@@ -22,26 +22,23 @@ class ToolSpec(BaseModel):
 
     name: str
     description: str = ""
-    parameters: Mapping[str, JsonValue]
+    parameters: JsonObject
     strict: bool = False
 
     @field_validator("parameters", mode="after")
     @classmethod
     def freeze_parameters(
         cls,
-        value: Mapping[str, JsonValue],
-    ) -> Mapping[str, JsonValue]:
-        frozen = freeze_json(value)
-        if not isinstance(frozen, Mapping):
-            raise TypeError("parameters debe ser un objeto")
-        return cast(Mapping[str, JsonValue], frozen)
+        value: JsonObject,
+    ) -> JsonObject:
+        return freeze_json_object(value)
 
     @field_serializer("parameters", when_used="json")
     def serialize_parameters(
         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)
 
 
 ToolFunction = Callable[..., Awaitable[object]]
@@ -55,3 +52,6 @@ class ToolBinding:
     spec: ToolSpec | None = None
     private_arguments: Mapping[str, object] = field(default_factory=dict)
 
+    def __post_init__(self) -> None:
+        frozen_arguments = MappingProxyType(dict(self.private_arguments))
+        object.__setattr__(self, "private_arguments", frozen_arguments)

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

@@ -1 +0,0 @@
-"""Espacio reservado para el engine de Google posterior a 0.0.1."""

cortex_agent_sdk-0.0.2/src/cortex_agent_sdk/immutable.py

@@ -1,54 +0,0 @@
-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 FrozenProviderValue = (
-    bool
-    | int
-    | float
-    | str
-    | bytes
-    | tuple[FrozenProviderValue, ...]
-    | Mapping[str, FrozenProviderValue]
-    | None
-)
-
-
-def freeze_json(value: JsonValue | Mapping[str, JsonValue]) -> FrozenJsonValue:
-    if isinstance(value, list):
-        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: FrozenJsonValue) -> JsonValue:
-    if isinstance(value, 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: FrozenProviderValue) -> FrozenProviderValue:
-    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: FrozenProviderValue) -> 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
-