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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortex-agent-sdk
-Version: 0.0.3
+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.

{cortex_agent_sdk-0.0.3 → 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.

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

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-agent-sdk"
-version = "0.0.3"
+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.3 → cortex_agent_sdk-0.0.4}/src/cortex_agent_sdk/tools/contracts.py

@@ -21,6 +21,7 @@ class ToolDefinition:
     private_arguments: Mapping[str, object]
     is_final_answer: bool
     schema_validator: Draft202012Validator | None
+    input_parameter: str | None = None
 
 
 def build_definition(item: ToolFunction | ToolBinding) -> ToolDefinition:
@@ -38,42 +39,68 @@ def build_definition(item: ToolFunction | ToolBinding) -> ToolDefinition:
     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)
+    declared_model = _declared_input_model(binding, function)
+    if declared_model is None:
+        input_model, inferred_spec = _infer_contract(function, binding.private_arguments)
+        input_parameter = None
+    else:
+        input_model, inferred_spec, input_parameter = _model_contract(
+            function,
+            declared_model,
+            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,
+        spec=spec,
+        function=binding.function,
+        input_model=input_model,
+        private_arguments=private_arguments,
+        is_final_answer=is_final,
+        schema_validator=schema_validator,
+        input_parameter=input_parameter,
     )
 
 
+def _declared_input_model(
+    binding: ToolBinding,
+    function: ToolFunction,
+) -> type[BaseModel] | None:
+    decorated = getattr(binding.function, "__cortex_input_model__", None)
+    if decorated is None:
+        decorated = getattr(function, "__cortex_input_model__", None)
+    explicit = binding.input_model
+    if explicit is not None and decorated is not None and explicit is not decorated:
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"contratos Pydantic incompatibles en {function.__name__}",
+        )
+    model = explicit or decorated
+    if model is None:
+        return None
+    if not isinstance(model, type) or not issubclass(model, BaseModel):
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"input_model inválido en {function.__name__}",
+        )
+    return model
+
+
 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
+    annotations = _resolved_annotations(function)
 
     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")
+        _validate_parameter(function, name, parameter, annotation)
         if _is_injected(annotation):
             injected_names.add(name)
             continue
@@ -82,24 +109,110 @@ def _infer_contract(
             default = ...
         fields[name] = (annotation, default)
 
+    _validate_injected(function, injected_names, private_arguments)
+
+    config = ConfigDict(extra="forbid")
+    model_name = f"{function.__name__.title().replace('_', '')}Arguments"
+    input_model = create_model(model_name, __config__=config, **fields)
+    return input_model, _spec_from_model(function, input_model)
+
+
+def _model_contract(
+    function: ToolFunction,
+    input_model: type[BaseModel],
+    private_arguments: Mapping[str, object],
+) -> tuple[type[BaseModel], ToolSpec, str]:
+    signature = inspect.signature(function)
+    annotations = _resolved_annotations(function)
+    public_names: list[str] = []
+    injected_names: set[str] = set()
+    input_parameter: str | None = None
+
+    for name, parameter in signature.parameters.items():
+        annotation = annotations.get(name, parameter.annotation)
+        _validate_parameter(function, name, parameter, annotation)
+        if _is_injected(annotation):
+            injected_names.add(name)
+            continue
+        public_names.append(name)
+        if _annotation_base(annotation) is input_model:
+            input_parameter = name
+
+    _validate_injected(function, injected_names, private_arguments)
+    if len(public_names) != 1 or input_parameter is None:
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"{function.__name__} debe recibir un único argumento público {input_model.__name__}",
+        )
+    return input_model, _spec_from_model(function, input_model), input_parameter
+
+
+def _resolved_annotations(function: ToolFunction) -> dict[str, Any]:
+    try:
+        return 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
+
+
+def _validate_parameter(
+    function: ToolFunction,
+    name: str,
+    parameter: inspect.Parameter,
+    annotation: object,
+) -> None:
+    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")
+
+
+def _validate_injected(
+    function: ToolFunction,
+    injected_names: set[str],
+    private_arguments: Mapping[str, object],
+) -> None:
     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)
+
+def _spec_from_model(function: ToolFunction, input_model: type[BaseModel]) -> ToolSpec:
     schema = input_model.model_json_schema()
     schema.pop("title", None)
+    _forbid_object_extras(schema)
+    if schema.get("type") != "object" or not isinstance(schema.get("properties"), dict):
+        raise AppError(
+            CodigoError.CONFIG_INVALIDA,
+            f"{input_model.__name__} debe describir argumentos de tipo object",
+        )
     description = (inspect.getdoc(function) or "").split("\n", maxsplit=1)[0]
-    spec = ToolSpec(
+    return ToolSpec(
         name=function.__name__,
         description=description,
         parameters=schema,
     )
-    return input_model, spec
+
+
+def _forbid_object_extras(value: object) -> None:
+    if isinstance(value, dict):
+        if value.get("type") == "object" and isinstance(value.get("properties"), dict):
+            value["additionalProperties"] = False
+        for nested in value.values():
+            _forbid_object_extras(nested)
+    elif isinstance(value, list):
+        for nested in value:
+            _forbid_object_extras(nested)
+
+
+def _annotation_base(annotation: object) -> object:
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+    return annotation
 
 
 def _is_injected(annotation: object) -> bool:

cortex_agent_sdk-0.0.4/src/cortex_agent_sdk/tools/decorators.py

@@ -0,0 +1,65 @@
+from collections.abc import Callable
+from typing import overload
+
+from pydantic import BaseModel
+
+from cortex_agent_sdk.tools.models import ToolFunction
+
+
+@overload
+def tool[F: ToolFunction](function: F, /) -> F: ...
+
+
+@overload
+def tool[F: ToolFunction](
+    *,
+    input_model: type[BaseModel] | None = None,
+) -> Callable[[F], F]: ...
+
+
+def tool(
+    function: ToolFunction | None = None,
+    *,
+    input_model: type[BaseModel] | None = None,
+) -> ToolFunction | Callable[[ToolFunction], ToolFunction]:
+    """Marca una tool y permite declarar un contrato Pydantic explícito."""
+
+    def decorate(inner: ToolFunction) -> ToolFunction:
+        inner.__cortex_tool__ = True  # type: ignore[attr-defined]
+        if input_model is not None:
+            inner.__cortex_input_model__ = input_model  # type: ignore[attr-defined]
+        return inner
+
+    if function is None:
+        return decorate
+    return decorate(function)
+
+
+@overload
+def final_answer[F: ToolFunction](function: F, /) -> F: ...
+
+
+@overload
+def final_answer[F: ToolFunction](
+    *,
+    input_model: type[BaseModel] | None = None,
+) -> Callable[[F], F]: ...
+
+
+def final_answer(
+    function: ToolFunction | None = None,
+    *,
+    input_model: type[BaseModel] | None = None,
+) -> ToolFunction | Callable[[ToolFunction], ToolFunction]:
+    """Marca una tool terminal y permite un contrato Pydantic explícito."""
+
+    def decorate(inner: ToolFunction) -> ToolFunction:
+        inner.__cortex_tool__ = True  # type: ignore[attr-defined]
+        inner.__cortex_final_answer__ = True  # type: ignore[attr-defined]
+        if input_model is not None:
+            inner.__cortex_input_model__ = input_model  # type: ignore[attr-defined]
+        return inner
+
+    if function is None:
+        return decorate
+    return decorate(function)

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

@@ -142,7 +142,7 @@ def _validate_arguments(
                 definition.is_final_answer,
             )
     try:
-        public_arguments = definition.input_model.model_validate(public_input).model_dump()
+        validated = definition.input_model.model_validate(public_input, extra="forbid")
     except ValidationError:
         return _failed_outcome(
             call,
@@ -150,6 +150,11 @@ def _validate_arguments(
             "Los argumentos de la herramienta son inválidos.",
             definition.is_final_answer,
         )
+
+    if definition.input_parameter is not None:
+        public_arguments: dict[str, object] = {definition.input_parameter: validated}
+    else:
+        public_arguments = validated.model_dump()
     return {**public_arguments, **definition.private_arguments}
 
 

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

@@ -46,11 +46,12 @@ ToolFunction = Callable[..., Awaitable[object]]
 
 @dataclass(frozen=True, slots=True)
 class ToolBinding:
-    """Une callable, schema opcional y argumentos privados."""
+    """Une callable, contrato opcional y argumentos privados."""
 
     function: ToolFunction
     spec: ToolSpec | None = None
     private_arguments: Mapping[str, object] = field(default_factory=dict)
+    input_model: type[BaseModel] | None = None
 
     def __post_init__(self) -> None:
         frozen_arguments = MappingProxyType(dict(self.private_arguments))

cortex_agent_sdk-0.0.3/src/cortex_agent_sdk/tools/decorators.py

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