cortex-agent-sdk 0.0.1__py3-none-any.whl

cortex_agent_sdk/history/models.py

@@ -0,0 +1,145 @@
+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 cortex_agent_sdk.immutable import (
+    FrozenJsonValue,
+    FrozenProviderValue,
+    freeze_json,
+    freeze_provider,
+    thaw_json,
+)
+
+_BYTES_TAG = "$cortex.bytes"
+
+ProviderValue = FrozenProviderValue
+
+
+class ProviderState(BaseModel):
+    """Items nativos necesarios para continuar sin pérdida con un provider."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    provider: str
+    items: tuple[Mapping[str, ProviderValue], ...]
+
+    @field_validator("items", mode="before")
+    @classmethod
+    def decode_bytes(cls, value: object) -> object:
+        return _decode_provider_bytes(value)
+
+    @field_validator("items", mode="after")
+    @classmethod
+    def freeze_items(
+        cls,
+        value: tuple[Mapping[str, ProviderValue], ...],
+    ) -> tuple[Mapping[str, ProviderValue], ...]:
+        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], ...],
+    ) -> tuple[dict[str, object], ...]:
+        return tuple(
+            {key: _encode_provider_bytes(value) for key, value in item.items()} for item in items
+        )
+
+
+class TextPart(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ToolCallPart(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    type: Literal["tool_call"] = "tool_call"
+    call_id: str
+    name: str
+    arguments: Mapping[str, JsonValue]
+
+    @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)
+
+    @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()}
+
+
+class ToolResultPart(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    type: Literal["tool_result"] = "tool_result"
+    call_id: str
+    name: str
+    output: str
+    is_error: bool = False
+    error_code: str | None = None
+
+
+Part = Annotated[TextPart | ToolCallPart | ToolResultPart, Field(discriminator="type")]
+
+
+class Turn(BaseModel):
+    """Turno lógico persistible con extensión nativa opcional."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    role: Literal["user", "assistant", "tool"]
+    parts: tuple[Part, ...]
+    provider_state: ProviderState | None = None
+
+    @classmethod
+    def user(cls, text: str) -> "Turn":
+        return cls(role="user", parts=(TextPart(text=text),))
+
+    @property
+    def text(self) -> str:
+        return "\n".join(part.text for part in self.parts if isinstance(part, TextPart))
+
+
+def _encode_provider_bytes(value: ProviderValue) -> object:
+    if isinstance(value, bytes):
+        encoded = base64.b64encode(value).decode("ascii")
+        return {_BYTES_TAG: encoded}
+    if isinstance(value, tuple):
+        return [_encode_provider_bytes(item) for item in value]
+    if isinstance(value, Mapping):
+        return {key: _encode_provider_bytes(item) for key, item in value.items()}
+    return value
+
+
+def _decode_provider_bytes(value: object) -> object:
+    if isinstance(value, list):
+        return [_decode_provider_bytes(item) for item in value]
+    if not isinstance(value, dict):
+        return value
+    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/history/pipeline.py

@@ -0,0 +1,53 @@
+from datetime import UTC, datetime
+
+from cortex_agent_sdk.errores import AppError, CodigoError
+from cortex_agent_sdk.history.models import Turn
+from cortex_agent_sdk.history.transform import HistoryTransform, TransformContext
+
+
+class HistoryPipeline:
+    def __init__(self, transform: HistoryTransform | None, max_turns: int) -> None:
+        self._transform = transform
+        self._max_turns = max_turns
+
+    async def prepare(
+        self,
+        history: tuple[Turn, ...],
+        session_id: str | None,
+    ) -> tuple[Turn, ...]:
+        transformed = history
+        if self._transform is not None:
+            context = TransformContext(
+                history=history,
+                max_turns=self._max_turns,
+                now=datetime.now(UTC),
+                session_id=session_id,
+            )
+            try:
+                transformed = tuple(await self._transform(context))
+            except AppError:
+                raise
+            except Exception as error:
+                raise AppError(
+                    CodigoError.HISTORIAL_TRANSFORM_INVALIDO,
+                    f"history_transform lanzó {type(error).__name__}",
+                ) from error
+            if not all(isinstance(turn, Turn) for turn in transformed):
+                raise AppError(
+                    CodigoError.HISTORIAL_TRANSFORM_INVALIDO,
+                    "history_transform devolvió un tipo inválido",
+                )
+        return _window_history(transformed, self._max_turns)
+
+    def window(self, history: tuple[Turn, ...]) -> tuple[Turn, ...]:
+        return _window_history(history, self._max_turns)
+
+
+def _window_history(history: tuple[Turn, ...], max_turns: int) -> tuple[Turn, ...]:
+    if len(history) <= max_turns:
+        return history
+    start = len(history) - max_turns
+    while history[start].role == "tool" and start > 0:
+        start -= 1
+    return history[start:]
+

cortex_agent_sdk/history/transform.py

@@ -0,0 +1,17 @@
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime
+
+from cortex_agent_sdk.history.models import Turn
+
+
+@dataclass(frozen=True, slots=True)
+class TransformContext:
+    history: tuple[Turn, ...]
+    max_turns: int
+    now: datetime
+    session_id: str | None
+
+
+HistoryTransform = Callable[[TransformContext], Awaitable[tuple[Turn, ...] | list[Turn]]]
+

cortex_agent_sdk/hooks.py

@@ -0,0 +1,102 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, replace
+from typing import Never
+
+from cortex_agent_sdk.engine import EngineRequest, EngineResult, ToolCall
+from cortex_agent_sdk.errores import AppError, CodigoError
+from cortex_agent_sdk.results import AgentResult
+from cortex_agent_sdk.tools.execution import ToolOutcome
+
+BeforeModelHook = Callable[[EngineRequest], Awaitable[EngineRequest | None]]
+AfterModelHook = Callable[[EngineResult], Awaitable[EngineResult | None]]
+BeforeToolHook = Callable[[ToolCall], Awaitable[ToolCall | None]]
+AfterToolHook = Callable[[ToolOutcome], Awaitable[ToolOutcome | None]]
+TurnFinishedHook = Callable[[AgentResult], Awaitable[None]]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentHooks:
+    before_model: tuple[BeforeModelHook, ...] = ()
+    after_model: tuple[AfterModelHook, ...] = ()
+    before_tool: tuple[BeforeToolHook, ...] = ()
+    after_tool: tuple[AfterToolHook, ...] = ()
+    turn_finished: tuple[TurnFinishedHook, ...] = ()
+
+
+class HookChain:
+    def __init__(self, hooks: AgentHooks, timeout_seconds: float) -> None:
+        self._hooks = hooks
+        self._timeout_seconds = timeout_seconds
+
+    async def run_before_model(self, request: EngineRequest) -> EngineRequest:
+        current = request
+        for hook in self._hooks.before_model:
+            replacement = await self._call(hook(current), "before_model")
+            if replacement is not None:
+                if not isinstance(replacement, EngineRequest):
+                    self._invalid("before_model")
+                try:
+                    current = replace(replacement)
+                except (TypeError, ValueError):
+                    self._invalid("before_model")
+        return current
+
+    async def run_after_model(self, result: EngineResult) -> EngineResult:
+        current = result
+        for hook in self._hooks.after_model:
+            replacement = await self._call(hook(current), "after_model")
+            if replacement is not None:
+                if not isinstance(replacement, EngineResult):
+                    self._invalid("after_model")
+                try:
+                    current = replace(replacement)
+                except (TypeError, ValueError):
+                    self._invalid("after_model")
+        return current
+
+    async def run_before_tool(self, call: ToolCall) -> ToolCall:
+        current = call
+        for hook in self._hooks.before_tool:
+            replacement = await self._call(hook(current), "before_tool")
+            if replacement is not None:
+                if not isinstance(replacement, ToolCall):
+                    self._invalid("before_tool")
+                try:
+                    current = ToolCall.model_validate(replacement.model_dump(round_trip=True))
+                except ValueError:
+                    self._invalid("before_tool")
+        return current
+
+    async def run_after_tool(self, outcome: ToolOutcome) -> ToolOutcome:
+        current = outcome
+        for hook in self._hooks.after_tool:
+            replacement = await self._call(hook(current), "after_tool")
+            if replacement is not None:
+                if not isinstance(replacement, ToolOutcome):
+                    self._invalid("after_tool")
+                try:
+                    current = replace(replacement)
+                except (TypeError, ValueError):
+                    self._invalid("after_tool")
+        return current
+
+    async def run_turn_finished(self, result: AgentResult) -> None:
+        for hook in self._hooks.turn_finished:
+            await self._call(hook(result), "turn_finished")
+
+    async def _call(self, operation: Awaitable[object], name: str) -> object:
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                return await operation
+        except TimeoutError as error:
+            raise AppError(CodigoError.HOOK_FALLO, f"timeout en {name}") from error
+        except Exception as error:
+            raise AppError(
+                CodigoError.HOOK_FALLO,
+                f"{name} lanzó {type(error).__name__}",
+            ) from error
+
+    def _invalid(self, name: str) -> Never:
+        raise AppError(CodigoError.HOOK_FALLO, f"retorno inválido en {name}")
+

cortex_agent_sdk/immutable.py

@@ -0,0 +1,54 @@
+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
+

cortex_agent_sdk/lifecycle.py

@@ -0,0 +1,67 @@
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import asynccontextmanager
+
+from cortex_agent_sdk.errores import AppError, CodigoError
+
+
+class AgentLifecycle:
+    """Coordina turnos activos y cierre ordenado del agente."""
+
+    def __init__(self) -> None:
+        self._active_runs = 0
+        self._accepting_runs = True
+        self._closed = False
+        self._guard = asyncio.Lock()
+        self._close_lock = asyncio.Lock()
+        self._drained = asyncio.Event()
+        self._drained.set()
+
+    async def ensure_open(self) -> None:
+        async with self._guard:
+            self._ensure_accepting()
+
+    @asynccontextmanager
+    async def run(self) -> AsyncIterator[None]:
+        async with self._guard:
+            self._ensure_accepting()
+            self._active_runs += 1
+            self._drained.clear()
+        try:
+            yield
+        finally:
+            async with self._guard:
+                self._active_runs -= 1
+                if self._active_runs == 0:
+                    self._drained.set()
+
+    async def close(
+        self,
+        close_resources: Callable[[], Awaitable[None]],
+        timeout_seconds: float,
+    ) -> None:
+        async with self._close_lock:
+            async with self._guard:
+                if self._closed:
+                    return
+                self._accepting_runs = False
+
+            try:
+                async with asyncio.timeout(timeout_seconds):
+                    await self._drained.wait()
+                    await close_resources()
+            except TimeoutError as error:
+                raise AppError(
+                    CodigoError.RUNTIME_CIERRE_TIMEOUT,
+                    "el agente no completó el drenado y cierre dentro del timeout",
+                ) from error
+
+            async with self._guard:
+                self._closed = True
+
+    def _ensure_accepting(self) -> None:
+        if self._closed:
+            raise AppError(CodigoError.RECURSO_CERRADO, "Agent cerrado")
+        if not self._accepting_runs:
+            raise AppError(CodigoError.RECURSO_CERRADO, "Agent en cierre ordenado")
+

cortex_agent_sdk/openai/__init__.py

@@ -0,0 +1,2 @@
+from cortex_agent_sdk.openai.engine import OpenAIEngine
+from cortex_agent_sdk.openai.options import OpenAIOptions