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

cortex_agent_sdk/sessions/models.py

@@ -0,0 +1,70 @@
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from cortex_agent_sdk.errores import AppError, CodigoError
+from cortex_agent_sdk.history.models import Turn
+
+
+class ActiveTurn(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    turn_id: str
+    pending_call_ids: tuple[str, ...]
+    completed_call_ids: tuple[str, ...] = ()
+
+    def complete(self, call_id: str) -> "ActiveTurn":
+        if call_id not in self.pending_call_ids or call_id in self.completed_call_ids:
+            raise AppError(CodigoError.SESION_INVALIDA, f"call inesperada: {call_id}")
+        completed = (*self.completed_call_ids, call_id)
+        return self.model_copy(update={"completed_call_ids": completed})
+
+
+class SessionRecord(BaseModel):
+    """Estado conversacional versionado y ligado a un engine."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    session_id: str
+    provider: str
+    model: str
+    history: tuple[Turn, ...] = ()
+    active_turn: ActiveTurn | None = None
+    version: int = 0
+    created_at: datetime
+    updated_at: datetime
+
+    @classmethod
+    def create(cls, session_id: str, provider: str, model: str) -> "SessionRecord":
+        now = datetime.now(UTC)
+        return cls(
+            session_id=session_id,
+            provider=provider,
+            model=model,
+            created_at=now,
+            updated_at=now,
+        )
+
+    def with_history(self, history: tuple[Turn, ...]) -> "SessionRecord":
+        return self.model_copy(update={"history": history})
+
+    def start_turn(
+        self,
+        turn_id: str,
+        call_ids: tuple[str, ...],
+        history: tuple[Turn, ...],
+    ) -> "SessionRecord":
+        if self.active_turn is not None or not call_ids or len(call_ids) != len(set(call_ids)):
+            raise AppError(CodigoError.SESION_INVALIDA, "turno activo inválido")
+        active_turn = ActiveTurn(turn_id=turn_id, pending_call_ids=call_ids)
+        return self.model_copy(update={"history": history, "active_turn": active_turn})
+
+    def complete_call(self, call_id: str, history: tuple[Turn, ...]) -> "SessionRecord":
+        if self.active_turn is None:
+            return self.with_history(history)
+        active_turn = self.active_turn.complete(call_id)
+        return self.model_copy(update={"history": history, "active_turn": active_turn})
+
+    def finish_turn(self, history: tuple[Turn, ...]) -> "SessionRecord":
+        return self.model_copy(update={"history": history, "active_turn": None})
+

cortex_agent_sdk/sessions/store.py

@@ -0,0 +1,38 @@
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol, runtime_checkable
+
+from cortex_agent_sdk.sessions.models import SessionRecord
+
+
+@runtime_checkable
+class SessionLease(Protocol):
+    @property
+    def session_id(self) -> str: ...
+
+    @property
+    def fencing_token(self) -> int: ...
+
+    @property
+    def renewal_interval_seconds(self) -> float | None: ...
+
+    async def verify_ownership(self, fencing_token: int) -> None: ...
+
+    async def renew(self, fencing_token: int) -> None: ...
+
+    async def load(self, fencing_token: int) -> SessionRecord | None: ...
+
+    async def save(self, record: SessionRecord, fencing_token: int) -> SessionRecord: ...
+
+
+@runtime_checkable
+class SessionStore(Protocol):
+    def acquire(
+        self,
+        session_id: str,
+        timeout_seconds: float,
+    ) -> AbstractAsyncContextManager[SessionLease]: ...
+
+    async def reset(self, session_id: str, timeout_seconds: float = 5.0) -> None: ...
+
+    async def aclose(self) -> None: ...
+

cortex_agent_sdk/tools/__init__.py

@@ -0,0 +1 @@
+from cortex_agent_sdk.tools.models import Injected, ToolBinding, ToolSpec

cortex_agent_sdk/tools/contracts.py

@@ -0,0 +1,152 @@
+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 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.tools.models import Injected, ToolBinding, ToolFunction, ToolSpec
+
+
+@dataclass(frozen=True, slots=True)
+class ToolDefinition:
+    spec: ToolSpec
+    function: ToolFunction
+    input_model: type[BaseModel]
+    private_arguments: Mapping[str, object]
+    is_final_answer: bool
+    schema_validator: Draft202012Validator | None
+
+
+def build_definition(item: ToolFunction | ToolBinding) -> ToolDefinition:
+    if isinstance(item, ToolBinding):
+        binding = item
+    else:
+        binding = ToolBinding(function=item)
+        if not getattr(item, "__cortex_tool__", False):
+            raise AppError(
+                CodigoError.CONFIG_INVALIDA,
+                f"{item.__name__} requiere @tool o ToolBinding",
+            )
+
+    function = inspect.unwrap(binding.function)
+    if not inspect.iscoroutinefunction(function):
+        raise AppError(CodigoError.CONFIG_INVALIDA, f"{function.__name__} debe ser async")
+
+    input_model, inferred_spec = _infer_contract(function, binding.private_arguments)
+    spec = binding.spec or inferred_spec
+    schema_validator = _explicit_validator(binding.spec, inferred_spec)
+    private_arguments = MappingProxyType(dict(binding.private_arguments))
+    is_final = bool(getattr(function, "__cortex_final_answer__", False))
+    return ToolDefinition(
+        spec,
+        binding.function,
+        input_model,
+        private_arguments,
+        is_final,
+        schema_validator,
+    )
+
+
+def _infer_contract(
+    function: ToolFunction,
+    private_arguments: Mapping[str, object],
+) -> tuple[type[BaseModel], ToolSpec]:
+    signature = inspect.signature(function)
+    try:
+        annotations = get_type_hints(function, include_extras=True)
+    except (NameError, TypeError) as error:
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"no se resolvieron tipos de {function.__name__}",
+        ) from error
+
+    fields: dict[str, Any] = {}
+    injected_names: set[str] = set()
+    for name, parameter in signature.parameters.items():
+        annotation = annotations.get(name, parameter.annotation)
+        if annotation is inspect.Signature.empty:
+            raise AppError(CodigoError.CONFIG_INVALIDA, f"falta tipo en {function.__name__}.{name}")
+        if parameter.kind in {parameter.VAR_POSITIONAL, parameter.VAR_KEYWORD}:
+            raise AppError(CodigoError.CONFIG_INVALIDA, f"{function.__name__} no admite variádicos")
+        if _is_injected(annotation):
+            injected_names.add(name)
+            continue
+        default = parameter.default
+        if default is inspect.Signature.empty:
+            default = ...
+        fields[name] = (annotation, default)
+
+    if injected_names != set(private_arguments):
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"inyección inválida en {function.__name__}",
+        )
+
+    config = ConfigDict(extra="forbid")
+    model_name = f"{function.__name__.title().replace('_', '')}Arguments"
+    input_model = create_model(model_name, __config__=config, **fields)
+    schema = input_model.model_json_schema()
+    schema.pop("title", None)
+    description = (inspect.getdoc(function) or "").split("\n", maxsplit=1)[0]
+    spec = ToolSpec(
+        name=function.__name__,
+        description=description,
+        parameters=schema,
+    )
+    return input_model, spec
+
+
+def _is_injected(annotation: object) -> bool:
+    if get_origin(annotation) is not Annotated:
+        return False
+    return Injected in get_args(annotation)[1:]
+
+
+def _explicit_validator(
+    explicit: ToolSpec | None,
+    inferred: ToolSpec,
+) -> Draft202012Validator | None:
+    if explicit is None:
+        return None
+    schema = _plain_schema(explicit)
+    inferred_schema = _plain_schema(inferred)
+    try:
+        Draft202012Validator.check_schema(schema)
+    except SchemaError as error:
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"schema inválido en {explicit.name}",
+        ) from error
+
+    properties = schema.get("properties")
+    inferred_properties = inferred_schema.get("properties")
+    required = schema.get("required", [])
+    inferred_required = inferred_schema.get("required", [])
+    if not isinstance(properties, dict) or not isinstance(inferred_properties, dict):
+        raise AppError(CodigoError.CONFIG_INVALIDA, f"properties inválido en {explicit.name}")
+    explicit_fields = set(properties)
+    inferred_fields = set(inferred_properties)
+    if not explicit_fields <= inferred_fields:
+        raise AppError(CodigoError.CONFIG_INVALIDA, f"campos incompatibles en {explicit.name}")
+    if not isinstance(required, list) or not isinstance(inferred_required, list):
+        raise AppError(CodigoError.CONFIG_INVALIDA, f"required inválido en {explicit.name}")
+    explicit_required = set(required)
+    callable_required = set(inferred_required)
+    valid_required = explicit_required <= explicit_fields and callable_required <= explicit_required
+    if not valid_required:
+        raise AppError(CodigoError.CONFIG_INVALIDA, f"required incompatible en {explicit.name}")
+    return Draft202012Validator(
+        schema,
+        format_checker=Draft202012Validator.FORMAT_CHECKER,
+    )
+
+
+def _plain_schema(spec: ToolSpec) -> dict[str, JsonValue]:
+    return {key: thaw_json(cast(FrozenJsonValue, value)) for key, value in spec.parameters.items()}
+

cortex_agent_sdk/tools/decorators.py

@@ -0,0 +1,15 @@
+from cortex_agent_sdk.tools.models import ToolFunction
+
+
+def tool(function: ToolFunction) -> ToolFunction:
+    """Marca un callable async para registrarlo en un Agent."""
+    function.__cortex_tool__ = True  # type: ignore[attr-defined]
+    return function
+
+
+def final_answer(function: ToolFunction) -> ToolFunction:
+    """Marca una tool cuyo str exitoso termina el turno."""
+    function.__cortex_tool__ = True  # type: ignore[attr-defined]
+    function.__cortex_final_answer__ = True  # type: ignore[attr-defined]
+    return function
+

cortex_agent_sdk/tools/execution.py

@@ -0,0 +1,181 @@
+import asyncio
+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.tools.contracts import ToolDefinition, build_definition
+from cortex_agent_sdk.tools.models import ToolBinding, ToolFunction, ToolSpec
+
+_JSON_ADAPTER = TypeAdapter(JsonValue)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolOutcome:
+    call: ToolCall
+    output: str
+    failed: bool
+    final_answer: bool
+    error_code: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.call, ToolCall) or not isinstance(self.output, str):
+            raise TypeError("ToolOutcome inválido")
+        if not isinstance(self.failed, bool) or not isinstance(self.final_answer, bool):
+            raise TypeError("ToolOutcome inválido")
+        if self.error_code is not None and not isinstance(self.error_code, str):
+            raise TypeError("ToolOutcome inválido")
+
+    @classmethod
+    def skipped(cls, call: ToolCall) -> "ToolOutcome":
+        return _failed_outcome(
+            call,
+            CodigoError.TOOL_OMITIDA_POR_LIMITE,
+            "La herramienta se omitió porque se alcanzó el límite de fallas.",
+        )
+
+    def as_history_part(self) -> ToolResultPart:
+        return ToolResultPart(
+            call_id=self.call.call_id,
+            name=self.call.name,
+            output=self.output,
+            is_error=self.failed,
+            error_code=self.error_code,
+        )
+
+
+class ToolSet:
+    def __init__(self, definitions: Mapping[str, ToolDefinition]) -> None:
+        self._definitions = MappingProxyType(dict(definitions))
+
+    @classmethod
+    def build(cls, tools: Iterable[ToolFunction | ToolBinding]) -> "ToolSet":
+        definitions: dict[str, ToolDefinition] = {}
+        for item in tools:
+            definition = build_definition(item)
+            if definition.spec.name in definitions:
+                raise AppError(
+                    CodigoError.CONFIG_INVALIDA,
+                    f"tool duplicada: {definition.spec.name}",
+                )
+            definitions[definition.spec.name] = definition
+        return cls(definitions)
+
+    @property
+    def specs(self) -> tuple[ToolSpec, ...]:
+        return tuple(definition.spec for definition in self._definitions.values())
+
+    def definition(self, name: str) -> ToolDefinition | None:
+        return self._definitions.get(name)
+
+    def is_final_answer(self, name: str) -> bool:
+        definition = self._definitions.get(name)
+        return definition is not None and definition.is_final_answer
+
+
+class ToolExecutor:
+    def __init__(self, tools: ToolSet, timeout_seconds: float) -> None:
+        self._tools = tools
+        self._timeout_seconds = timeout_seconds
+
+    async def execute(self, call: ToolCall) -> ToolOutcome:
+        definition = self._tools.definition(call.name)
+        if definition is None:
+            return _failed_outcome(
+                call,
+                CodigoError.TOOL_NO_ENCONTRADA,
+                "La herramienta solicitada no existe.",
+            )
+
+        arguments = _validate_arguments(definition, call)
+        if isinstance(arguments, ToolOutcome):
+            return arguments
+
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                result = await definition.function(**arguments)
+        except TimeoutError:
+            return _failed_outcome(
+                call,
+                CodigoError.TOOL_TIMEOUT,
+                "La herramienta agotó su tiempo de ejecución.",
+                definition.is_final_answer,
+            )
+        except AppError as error:
+            message = error.mensaje_seguro or "La herramienta no pudo completar la operación."
+            return _failed_outcome(call, error.codigo, message, definition.is_final_answer)
+        except Exception as error:
+            detail = f"{call.name} lanzó {type(error).__name__}"
+            raise AppError(
+                CodigoError.TOOL_FALLO,
+                detail,
+                mensaje_seguro="La herramienta falló de forma inesperada.",
+            ) from error
+
+        if definition.is_final_answer and not isinstance(result, str):
+            raise AppError(
+                CodigoError.FINAL_ANSWER_INVALIDA,
+                f"{call.name} debe devolver str",
+            )
+        output = _serialize_result(result, call.name)
+        return ToolOutcome(call, output, False, definition.is_final_answer)
+
+
+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()
+    }
+    if definition.schema_validator is not None:
+        schema_error = next(definition.schema_validator.iter_errors(public_input), None)
+        if schema_error is not None:
+            return _failed_outcome(
+                call,
+                CodigoError.TOOL_ARGUMENTOS_INVALIDOS,
+                "Los argumentos de la herramienta son inválidos.",
+                definition.is_final_answer,
+            )
+    try:
+        public_arguments = definition.input_model.model_validate(public_input).model_dump()
+    except ValidationError:
+        return _failed_outcome(
+            call,
+            CodigoError.TOOL_ARGUMENTOS_INVALIDOS,
+            "Los argumentos de la herramienta son inválidos.",
+            definition.is_final_answer,
+        )
+    return {**public_arguments, **definition.private_arguments}
+
+
+def _serialize_result(result: object, tool_name: str) -> str:
+    if isinstance(result, str):
+        return result
+    try:
+        value = _JSON_ADAPTER.validate_python(result)
+    except ValidationError as error:
+        raise AppError(
+            CodigoError.TOOL_RESULTADO_INVALIDO,
+            f"{tool_name} devolvió un resultado no serializable",
+        ) from error
+    return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+
+
+def _failed_outcome(
+    call: ToolCall,
+    code: CodigoError,
+    message: str,
+    is_final_answer: bool = False,
+) -> ToolOutcome:
+    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/tools/models.py

@@ -0,0 +1,57 @@
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+from pydantic import BaseModel, ConfigDict, JsonValue, field_serializer, field_validator
+
+from cortex_agent_sdk.immutable import FrozenJsonValue, freeze_json, thaw_json
+
+
+class _InjectedMarker:
+    def __repr__(self) -> str:
+        return "Injected"
+
+
+Injected = _InjectedMarker()
+
+
+class ToolSpec(BaseModel):
+    """Schema neutral visible para el modelo."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+    description: str = ""
+    parameters: Mapping[str, JsonValue]
+    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)
+
+    @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()}
+
+
+ToolFunction = Callable[..., Awaitable[object]]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolBinding:
+    """Une callable, schema opcional y argumentos privados."""
+
+    function: ToolFunction
+    spec: ToolSpec | None = None
+    private_arguments: Mapping[str, object] = field(default_factory=dict)
+