agentic-systems 2.1.2__tar.gz → 2.1.3__tar.gz

agentic_systems-2.1.3/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: agentic-systems
+Version: 2.1.3
+Summary: Agentic Systems: a computational grammar for building, executing, observing, and evaluating intelligent systems.
+Author-email: Jacobo Gerardo Gonzalez Leon <jacobogerardo.gonzalez@bbva.com>
+License-Expression: MIT
+Project-URL: Homepage, https://www.github.com/JacoboGGLeon/agentic_systems
+Project-URL: Repository, https://www.github.com/JacoboGGLeon/agentic_systems
+Project-URL: LinkedIn, https://www.linkedin.com/in/jacoboggleon/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.7.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: typing-extensions>=4.10.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: jsonschema<5,>=4.23
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.39.0; extra == "bedrock"
+Requires-Dist: botocore>=1.39.0; extra == "bedrock"
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
+Requires-Dist: typing-extensions>=4.10.0; extra == "langgraph"
+Provides-Extra: openai
+Requires-Dist: openai<3,>=2.45.0; extra == "openai"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents<0.19,>=0.18.3; extra == "openai-agents"
+Provides-Extra: strands
+Requires-Dist: strands-agents[a2a]<2,>=1.29.0; extra == "strands"
+Requires-Dist: mcp<2,>=1; extra == "strands"
+Provides-Extra: vllm
+Requires-Dist: openai<3,>=2.45.0; extra == "vllm"
+Provides-Extra: vllm-client
+Requires-Dist: openai<3,>=2.45.0; extra == "vllm-client"
+Provides-Extra: vllm-server
+Requires-Dist: vllm>=0.9.0; extra == "vllm-server"
+Requires-Dist: openai<3,>=2.45.0; extra == "vllm-server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: ruff==0.15.22; extra == "dev"
+Requires-Dist: tomli>=2.1.0; python_version < "3.11" and extra == "dev"
+Requires-Dist: ipykernel>=6.0.0; extra == "dev"
+Requires-Dist: jupyterlab>=4.0.0; extra == "dev"
+Requires-Dist: nbclient>=0.10.0; extra == "dev"
+Requires-Dist: nbformat>=5.10.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100.0; extra == "dev"
+Requires-Dist: pyright>=1.1.390; extra == "dev"
+Requires-Dist: import-linter>=2.0.0; extra == "dev"
+Requires-Dist: pip-audit>=2.7.0; extra == "dev"
+Requires-Dist: radon>=6.0.1; extra == "dev"
+Requires-Dist: cyclonedx-bom>=5.0.0; extra == "dev"
+Requires-Dist: mutmut<4,>=3.7; extra == "dev"
+Provides-Extra: all
+Requires-Dist: boto3>=1.39.0; extra == "all"
+Requires-Dist: botocore>=1.39.0; extra == "all"
+Requires-Dist: langgraph>=0.2.0; extra == "all"
+Requires-Dist: openai<3,>=2.45.0; extra == "all"
+Requires-Dist: openai-agents<0.19,>=0.18.3; extra == "all"
+Requires-Dist: strands-agents[a2a]<2,>=1.29.0; extra == "all"
+Requires-Dist: mcp<2,>=1; extra == "all"
+Requires-Dist: ipykernel>=6.0.0; extra == "all"
+Requires-Dist: jupyterlab>=4.0.0; extra == "all"
+Requires-Dist: nbclient>=0.10.0; extra == "all"
+Requires-Dist: nbformat>=5.10.0; extra == "all"
+Requires-Dist: pytest>=8.0.0; extra == "all"
+Requires-Dist: pytest-cov>=5.0.0; extra == "all"
+Requires-Dist: ruff==0.15.22; extra == "all"
+Requires-Dist: hypothesis>=6.100.0; extra == "all"
+Requires-Dist: pyright>=1.1.390; extra == "all"
+Requires-Dist: import-linter>=2.0.0; extra == "all"
+Requires-Dist: pip-audit>=2.7.0; extra == "all"
+Requires-Dist: radon>=6.0.1; extra == "all"
+Requires-Dist: cyclonedx-bom>=5.0.0; extra == "all"
+Requires-Dist: mutmut<4,>=3.7; extra == "all"
+Requires-Dist: tomli>=2.1.0; python_version < "3.11" and extra == "all"
+
+# Agentic Systems
+
+Construye agentes, coordínalos y comprueba sus resultados con una sola API.
+
+```python
+import agentic_systems as toolkit
+
+worker = toolkit.Agent("total", toolkit.Action("sum", lambda data: {"total": sum(data["values"])}))
+result = worker.run({"values": [2, 3, 5]})
+result.data  # {"total": 10}
+```
+
+Para coordinar unidades, conserva la misma forma de ejecutar:
+
+```python
+app = toolkit.System("application", toolkit.Sequence((worker,)))
+app.run({"values": [2, 3, 5]}).data
+```
+
+Agent y System admiten **Sequence**, **Parallel** y **Graph**. Las decisiones
+son funciones Python. Tools implementan operaciones; Skills las agrupan;
+Environment mantiene episodios y memoria; Eval comprueba el resultado.
+`run()` es el recorrido habitual. `compile()` prepara una declaración para
+reutilizarla cuando hace falta.
+
+Empieza en [tutorials](tutorials/README.md), elige una tarea en
+[examples](examples/README.md) o abre [Studio](examples/agentic_systems_studio/README.md).
+Los [seis flujos](examples/grammar_tour/README.md) muestran la gramática completa
+de Agent y System con entrada, proceso y salida.
+
+El [notebook de toda la API](examples/api_walkthrough/01_api_user_guide.ipynb)
+reúne el recorrido y la aplicación de pedidos. El [inventario de notebooks](docs/NOTEBOOK_INVENTORY_213.md)
+distingue material vigente, referencias compartidas e historia.
+
+La revisión **2.1.3** está en este repositorio y no se ha publicado en esta tarea.
+Instala el wheel local proporcionado; [instalación](INSTALL.md) explica la
+preparación inicial y los SDK opcionales. No hay aliases ni compatibilidad con
+los constructores anteriores.
+
+Para elegir un proveedor o framework, consulta [integraciones](docs/API_213.md#runtime-y-framework).
+Hay pruebas actuales con Python, Ollama, Bedrock API key y OpenAI API key.
+[La validación final](revisions/2.1.3/closeout-evidence/REPORT.md) especifica modelos,
+casos, artefacto, consumo y límites. IAM y GPU siguen requiriendo su entorno.
+
+[Guía de API](docs/API_213.md) · [Referencia completa](docs/API_213_SURFACE.md) ·
+[Criterios de experiencia](docs/USER_EXPERIENCE_213.md) · [Validadores](docs/VALIDATION_213.md)

agentic_systems-2.1.3/README.md

@@ -0,0 +1,46 @@
+# Agentic Systems
+
+Construye agentes, coordínalos y comprueba sus resultados con una sola API.
+
+```python
+import agentic_systems as toolkit
+
+worker = toolkit.Agent("total", toolkit.Action("sum", lambda data: {"total": sum(data["values"])}))
+result = worker.run({"values": [2, 3, 5]})
+result.data  # {"total": 10}
+```
+
+Para coordinar unidades, conserva la misma forma de ejecutar:
+
+```python
+app = toolkit.System("application", toolkit.Sequence((worker,)))
+app.run({"values": [2, 3, 5]}).data
+```
+
+Agent y System admiten **Sequence**, **Parallel** y **Graph**. Las decisiones
+son funciones Python. Tools implementan operaciones; Skills las agrupan;
+Environment mantiene episodios y memoria; Eval comprueba el resultado.
+`run()` es el recorrido habitual. `compile()` prepara una declaración para
+reutilizarla cuando hace falta.
+
+Empieza en [tutorials](tutorials/README.md), elige una tarea en
+[examples](examples/README.md) o abre [Studio](examples/agentic_systems_studio/README.md).
+Los [seis flujos](examples/grammar_tour/README.md) muestran la gramática completa
+de Agent y System con entrada, proceso y salida.
+
+El [notebook de toda la API](examples/api_walkthrough/01_api_user_guide.ipynb)
+reúne el recorrido y la aplicación de pedidos. El [inventario de notebooks](docs/NOTEBOOK_INVENTORY_213.md)
+distingue material vigente, referencias compartidas e historia.
+
+La revisión **2.1.3** está en este repositorio y no se ha publicado en esta tarea.
+Instala el wheel local proporcionado; [instalación](INSTALL.md) explica la
+preparación inicial y los SDK opcionales. No hay aliases ni compatibilidad con
+los constructores anteriores.
+
+Para elegir un proveedor o framework, consulta [integraciones](docs/API_213.md#runtime-y-framework).
+Hay pruebas actuales con Python, Ollama, Bedrock API key y OpenAI API key.
+[La validación final](revisions/2.1.3/closeout-evidence/REPORT.md) especifica modelos,
+casos, artefacto, consumo y límites. IAM y GPU siguen requiriendo su entorno.
+
+[Guía de API](docs/API_213.md) · [Referencia completa](docs/API_213_SURFACE.md) ·
+[Criterios de experiencia](docs/USER_EXPERIENCE_213.md) · [Validadores](docs/VALIDATION_213.md)

{agentic_systems-2.1.2 → agentic_systems-2.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentic-systems"
-version = "2.1.2"
+version = "2.1.3"
 description = "Agentic Systems: a computational grammar for building, executing, observing, and evaluating intelligent systems."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -24,6 +24,7 @@ dependencies = [
     "pandas>=2.0.0",
     "typing-extensions>=4.10.0",
     "rich>=13.0.0",
+    "jsonschema>=4.23,<5",
 ]
 
 
@@ -95,11 +96,14 @@ filterwarnings = [
     "ignore:'asyncio.get_event_loop_policy' is deprecated and slated for removal in Python 3.16:DeprecationWarning:agents\\.run",
 ]
 pythonpath = ["src"]
-testpaths = ["tests"]
+testpaths = ["tests/v213"]
 cache_dir = ".tmp/pytest_cache"
 
 [tool.ruff]
-extend-exclude = ["artifacts"]
+extend-exclude = ["artifacts", "src/agentic_systems/_engine"]
+
+[tool.setuptools.package-data]
+agentic_systems = ["_templates/**/*", "_templates/project/.env.example", "_templates/project/.gitignore"]
 
 [tool.ruff.lint.per-file-ignores]
 "src/agentic_systems/__init__.py" = ["F401"]
@@ -108,8 +112,8 @@ extend-exclude = ["artifacts"]
 [tool.coverage.run]
 source = ["src/agentic_systems"]
 omit = [
-    "src/agentic_systems/providers/bedrock_runtime.py",
-    "src/agentic_systems/providers/bedrock/*",
+    "*/_engine/*",
+    "*/_templates/*",
 ]
 
 [tool.coverage.report]
@@ -123,6 +127,6 @@ exclude_lines = [
 ]
 
 [tool.mutmut]
-source_paths = ["src/agentic_systems/schemas", "src/agentic_systems/registry.py", "src/agentic_systems/normalization.py", "src/agentic_systems/errors.py"]
-pytest_add_cli_args_test_selection = ["tests/contracts"]
+source_paths = ["src/agentic_systems/_contracts.py", "src/agentic_systems/_configuration.py", "src/agentic_systems/_results.py"]
+pytest_add_cli_args_test_selection = ["tests/v213"]
 mutate_only_covered_lines = true

agentic_systems-2.1.3/src/agentic_systems/__init__.py

@@ -0,0 +1,9 @@
+"""Agentic Systems 2.1.3: one construction and execution grammar."""
+from ._configuration import framework, model_artifact, model_server, runtime
+from ._grammar import Action, Agent, Environment, Eval, Graph, Limits, Parallel, Sequence, System
+from ._results import RunResult
+from ._tools import load_skill, skill, tool
+
+__version__ = "2.1.3"
+__all__ = ["tool", "skill", "load_skill", "Action", "Agent", "System", "Sequence", "Parallel", "Graph",
+           "Environment", "Eval", "Limits", "RunResult", "runtime", "framework", "model_artifact", "model_server", "__version__"]

agentic_systems-2.1.3/src/agentic_systems/_configuration.py

@@ -0,0 +1,217 @@
+"""One spelling and one immutable configuration per execution responsibility."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import math
+from types import MappingProxyType
+
+from ._results import _json, _redact
+
+_PROVIDERS = {"python-runtime", "openai-runtime", "ollama-runtime", "bedrock-runtime", "vllm-runtime"}
+_FRAMEWORKS = {"native", "langgraph", "openai-agents", "strands"}
+
+
+@dataclass(frozen=True)
+class _Runtime:
+    provider: str
+    model: str | None
+    region: str | None
+    endpoint: str | None
+    _api_key: str | None = field(repr=False)
+    timeout_s: float
+    max_retries: int
+    max_tool_calls: int
+    max_turns: int
+    max_tokens: int | None
+    backoff_s: float
+    max_concurrency: int
+
+    def inspect(self):
+        return {"provider": self.provider, "model": self.model, "region": self.region, "endpoint": self.endpoint,
+                "api_key_configured": self._api_key is not None, "timeout_s": self.timeout_s,
+                "max_retries": self.max_retries, "max_tool_calls": self.max_tool_calls,
+                "max_turns": self.max_turns, "max_tokens": self.max_tokens,
+                "backoff_s": self.backoff_s, "max_concurrency": self.max_concurrency}
+
+    def _to_engine(self):
+        from ._engine.core.runtime import RuntimeConfig
+        from ._engine.core.scheduler import SchedulerConfig
+        return RuntimeConfig(provider=self.provider, model_id=self.model, region_name=self.region,
+                             endpoint=self.endpoint, api_key=self._api_key,
+                             scheduler=SchedulerConfig(timeout_s=self.timeout_s, max_retries=self.max_retries,
+                                 max_tool_calls=self.max_tool_calls, max_turns=self.max_turns,
+                                 max_concurrency=self.max_concurrency, backoff_s=self.backoff_s))
+
+
+def runtime(*, provider, model=None, region=None, endpoint=None, api_key=None, timeout_s=60.0,
+            max_retries=0, max_tool_calls=5, max_turns=6, max_tokens=None, backoff_s=0.0, max_concurrency=1):
+    if provider not in _PROVIDERS:
+        raise ValueError("Choose an explicit provider: " + ", ".join(sorted(_PROVIDERS)))
+    for name, value, minimum in (("max_retries", max_retries, 0), ("max_tool_calls", max_tool_calls, 0),
+                                  ("max_turns", max_turns, 1), ("max_concurrency", max_concurrency, 1)):
+        if type(value) is not int or value < minimum:
+            raise ValueError(name + " is outside its supported range")
+    if max_tokens is not None and (type(max_tokens) is not int or max_tokens < 1):
+        raise ValueError("max_tokens must be positive")
+    if type(timeout_s) not in {int, float} or not math.isfinite(timeout_s) or timeout_s <= 0:
+        raise ValueError("timeout_s must be positive and finite")
+    if type(backoff_s) not in {int, float} or not math.isfinite(backoff_s) or backoff_s < 0:
+        raise ValueError("backoff_s must be nonnegative and finite")
+    for name, value in (("model", model), ("region", region), ("endpoint", endpoint), ("api_key", api_key)):
+        if value is not None and (not isinstance(value, str) or not value):
+            raise TypeError(name + " must be a nonempty string")
+    if region is not None and provider != "bedrock-runtime":
+        raise ValueError("region belongs to Bedrock")
+    if provider == "python-runtime" and any(v is not None for v in (region, endpoint, api_key, max_tokens)):
+        raise ValueError("Python Runtime does not consume model connection/generation options")
+    return _Runtime(provider, model or ("python-runtime" if provider == "python-runtime" else None), region,
+                    endpoint, api_key, timeout_s, max_retries, max_tool_calls, max_turns, max_tokens, backoff_s, max_concurrency)
+
+
+@dataclass(frozen=True)
+class _Framework:
+    name: str
+    agent_kwargs: object
+    run_kwargs: object
+
+    def inspect(self):
+        return {"name": self.name, "agent_kwargs": {k: type(v).__name__ for k, v in self.agent_kwargs.items()},
+                "run_kwargs": {k: type(v).__name__ for k, v in self.run_kwargs.items()}}
+
+    def _to_engine(self):
+        from ._engine.integrations.config import FrameworkConfig
+        return FrameworkConfig(name=self.name, agent_kwargs=dict(self.agent_kwargs), run_kwargs=dict(self.run_kwargs))
+
+
+def framework(name, *, agent_kwargs=None, run_kwargs=None):
+    if name not in _FRAMEWORKS:
+        raise ValueError("Choose an exact framework name: " + ", ".join(sorted(_FRAMEWORKS)))
+    if agent_kwargs is not None and not isinstance(agent_kwargs, dict) or run_kwargs is not None and not isinstance(run_kwargs, dict):
+        raise TypeError("Framework options must be dictionaries")
+    if name in {"native", "langgraph"} and (agent_kwargs or run_kwargs):
+        raise ValueError("This adapter does not forward native SDK options")
+    from ._engine.integrations.config import RESERVED_AGENT_KWARGS, RESERVED_RUN_KWARGS
+    owned = {"runtime", "model", "provider", "api_key", "endpoint", "timeout_s", "max_retries", "max_tokens", "max_turns", "max_tool_calls", "contract", "policy", "limits"}
+    if (set(agent_kwargs or {}) & (set(RESERVED_AGENT_KWARGS) | owned)
+            or set(run_kwargs or {}) & (set(RESERVED_RUN_KWARGS) | owned)):
+        raise ValueError("Framework options cannot override toolkit-owned configuration")
+    def nested_conflict(value):
+        if isinstance(value, dict):
+            return bool(set(value) & owned) or any(nested_conflict(v) for v in value.values())
+        return False
+    for options in (agent_kwargs or {}, run_kwargs or {}):
+        for key, value in options.items():
+            if key in {"model_settings", "model_kwargs", "generation_config", "run_config", "config"}:
+                settings = value if isinstance(value, dict) else vars(value) if hasattr(value, "__dict__") else {}
+                settings = {k: v for k, v in settings.items() if v is not None}
+                if nested_conflict(settings):
+                    raise ValueError("Nested SDK options cannot override toolkit-owned configuration")
+    return _Framework(name, MappingProxyType(dict(agent_kwargs or {})), MappingProxyType(dict(run_kwargs or {})))
+
+
+@dataclass(frozen=True)
+class _Artifact:
+    model: str
+    base_model: str | None
+    adapter_path: str | None
+    tokenizer: str | None
+    revision: str | None
+    quantization: str | None
+    metadata: object
+
+    def inspect(self):
+        return {"model": self.model, "base_model": self.base_model, "adapter_path": self.adapter_path,
+                "tokenizer": self.tokenizer, "revision": self.revision, "quantization": self.quantization,
+                "metadata": _json(dict(self.metadata))}
+
+    def _to_engine(self):
+        from ._engine.schemas.serving import ModelArtifact
+        return ModelArtifact(model_id=self.model, base_model_id=self.base_model, adapter_path=self.adapter_path,
+                             tokenizer_id=self.tokenizer, revision=self.revision, quantization=self.quantization, metadata=dict(self.metadata))
+
+
+def model_artifact(model, *, base_model=None, adapter_path=None, tokenizer=None, revision=None, quantization=None, metadata=None):
+    if not isinstance(model, str) or not model.strip():
+        raise ValueError("Model identity is required")
+    result = _Artifact(model, base_model, adapter_path, tokenizer, revision, quantization, MappingProxyType(_json(metadata or {})))
+    result._to_engine()
+    return result
+
+
+@dataclass(frozen=True)
+class _Endpoint:
+    url: str
+    model: str
+    backend: str
+    api_key_configured: bool
+    pid: int | None
+    owned: bool
+
+
+@dataclass(frozen=True)
+class _Health:
+    status: str
+    endpoint: _Endpoint
+    detail: str | None
+
+
+def _endpoint(value):
+    return _Endpoint(value.base_url, value.model_id, value.backend, value.api_key_configured, value.pid, value.owned)
+
+
+@dataclass(frozen=True)
+class _Server:
+    _resource: object = field(repr=False)
+
+    @property
+    def endpoint(self):
+        return _endpoint(self._resource.endpoint)
+
+    @property
+    def command(self):
+        key = self._resource.spec.api_key.get_secret_value()
+        args = self._resource.command
+        return tuple("[REDACTED]" if i and args[i-1] == "--api-key" else v.replace(key, "[REDACTED]")
+                     if key and key != "vllm" else v for i, v in enumerate(args))
+
+    def inspect(self):
+        value = self._resource.inspect()
+        value["command"] = list(self.command)
+        value["endpoint"] = self.endpoint.__dict__.copy()
+        configuration = value.pop("spec")
+        artifact = configuration["artifact"]
+        for before, after in (("model_id", "model"), ("base_model_id", "base_model"), ("tokenizer_id", "tokenizer")):
+            artifact[after] = artifact.pop(before)
+        value["configuration"] = configuration
+        return _redact(value)
+
+    def start(self):
+        return _endpoint(self._resource.start())
+
+    def health(self):
+        value = self._resource.health()
+        key = self._resource.spec.api_key.get_secret_value()
+        return _Health(value.status, _endpoint(value.endpoint), value.detail.replace(key, "[REDACTED]") if key and value.detail else value.detail)
+
+    def stop(self):
+        self._resource.stop()
+
+
+def model_server(artifact, *, profile="fast", served_model_name=None, host="127.0.0.1", port=8000,
+                 tool_call_parser="hermes", reasoning_parser=None, enable_auto_tool_choice=True,
+                 api_key="vllm", startup_timeout_s=600.0, log_path="vllm-server.log", binary="vllm", extra_args=(),
+                 gpu_memory_utilization=None, max_model_len=None, max_num_seqs=None):
+    if not isinstance(artifact, _Artifact):
+        raise TypeError("Pass model_artifact(...)")
+    managed = {"--host", "--port", "--served-model-name", "--gpu-memory-utilization", "--max-model-len", "--max-num-seqs",
+               "--tool-call-parser", "--reasoning-parser", "--enable-auto-tool-choice", "--api-key", "--generation-config"}
+    if not isinstance(extra_args, tuple) or any(not isinstance(v, str) or v.split("=", 1)[0] in managed for v in extra_args):
+        raise ValueError("extra_args cannot override managed server parameters")
+    if profile not in {"fast", "medium", "power", "custom"}:
+        raise ValueError("Unknown exact server profile")
+    from ._engine.serving.vllm import VLLMServer, vllm_server_spec
+    spec = vllm_server_spec(artifact._to_engine(), profile=profile, served_model_name=served_model_name, host=host, port=port,
+            tool_call_parser=tool_call_parser, reasoning_parser=reasoning_parser, enable_auto_tool_choice=enable_auto_tool_choice,
+            api_key=api_key, startup_timeout_s=startup_timeout_s, log_path=log_path, binary=binary, extra_args=extra_args,
+            gpu_memory_utilization=gpu_memory_utilization, max_model_len=max_model_len, max_num_seqs=max_num_seqs)
+    return _Server(VLLMServer(spec))

agentic_systems-2.1.3/src/agentic_systems/_contracts.py

@@ -0,0 +1,139 @@
+"""Closed user dictionaries; the engine's policy vocabulary remains private."""
+from __future__ import annotations
+
+from dataclasses import replace
+import json
+
+from ._results import _from_engine, _json
+
+
+def _closed(value, allowed, label):
+    if value is None:
+        return {}
+    if not isinstance(value, dict) or set(value) - set(allowed):
+        raise ValueError(label + " accepts only: " + ", ".join(sorted(allowed)))
+    return _json(value)
+
+
+def _validate_schema(schema):
+    from jsonschema import Draft202012Validator
+    if not isinstance(schema, dict):
+        raise TypeError("output_schema must be a JSON Schema dictionary")
+    def visit(value):
+        if isinstance(value, dict):
+            if "$ref" in value and not value["$ref"].startswith("#"):
+                raise ValueError("Schema references must be local; no remote resolution")
+            for child in value.values():
+                visit(child)
+        elif isinstance(value, list):
+            for child in value:
+                visit(child)
+    visit(schema)
+    Draft202012Validator.check_schema(schema)
+    return _json(schema)
+
+
+def _validate_contract(value, tools=(), runtime=None):
+    result = _closed(value, {"tool_expectation", "completion", "failure_policy", "expected_output", "expected_tool_outputs", "output_schema"}, "contract")
+    expectation = _closed(result.get("tool_expectation"), {"all_of", "any_of", "allowed", "forbidden", "min_count"}, "tool_expectation")
+    for key in ("all_of", "any_of", "allowed", "forbidden"):
+        if key in expectation and (not isinstance(expectation[key], list) or any(not isinstance(v, str) for v in expectation[key])):
+            raise TypeError(key + " requires a list of Tool names")
+    references = set().union(*(set(expectation.get(k, [])) for k in ("all_of", "any_of", "allowed", "forbidden")))
+    if references - set(tools):
+        raise ValueError("Contract references unavailable Tools")
+    required, forbidden = set(expectation.get("all_of", [])), set(expectation.get("forbidden", []))
+    allowed = set(expectation["allowed"]) if "allowed" in expectation else set(tools)
+    if required & forbidden or required - allowed:
+        raise ValueError("Contradictory required/allowed/forbidden Tools")
+    if expectation.get("any_of") and not set(expectation["any_of"]) & (allowed - forbidden):
+        raise ValueError("No any_of Tool can satisfy this contract")
+    if "min_count" in expectation:
+        count = expectation["min_count"]
+        if type(count) is not int or count < 0:
+            raise ValueError("min_count must be nonnegative")
+        if runtime and count > runtime.max_tool_calls:
+            raise ValueError("Contract exceeds the actor Tool budget")
+    if runtime and len(required) > runtime.max_tool_calls:
+        raise ValueError("Required Tools exceed the actor budget")
+    if result.get("completion", "default") not in {"default", "when_required_tools_satisfied", "always_finalize"}:
+        raise ValueError("Unknown exact completion mode")
+    if result.get("failure_policy", "no_unresolved") not in {"allow", "no_unresolved", "fail_fast"}:
+        raise ValueError("Unknown exact failure_policy")
+    for key in ("expected_output", "expected_tool_outputs"):
+        if key in result and not isinstance(result[key], dict):
+            raise TypeError(key + " must be a dictionary")
+    outputs = result.get("expected_tool_outputs", {})
+    if set(outputs) - set(tools) or any(not isinstance(v, dict) for v in outputs.values()):
+        raise ValueError("expected_tool_outputs requires available Tool names and dictionary expectations")
+    if "output_schema" in result:
+        result["output_schema"] = _validate_schema(result["output_schema"])
+    if expectation:
+        result["tool_expectation"] = expectation
+    return result
+
+
+def _validate_policy(value):
+    result = _closed(value, {"temperature", "tool_choice", "repair", "max_repairs", "finalize", "trace", "strict"}, "policy")
+    if "temperature" in result and (type(result["temperature"]) not in {int, float} or not 0 <= result["temperature"] <= 2):
+        raise ValueError("temperature must be between 0 and 2")
+    if "max_repairs" in result and (type(result["max_repairs"]) is not int or result["max_repairs"] < 0):
+        raise ValueError("max_repairs must be nonnegative")
+    for key in ("repair", "strict"):
+        if key in result and type(result[key]) is not bool:
+            raise TypeError(key + " must be boolean")
+    for key, allowed in (("tool_choice", {"auto", "required", "none"}), ("trace", {"compact", "full"}),
+                         ("finalize", {"never", "on_max_turns", "after_required_tools"})):
+        if key in result and result[key] not in allowed:
+            raise ValueError("Unknown " + key)
+    return result
+
+
+def _invoke_actor(owner, config, selected_framework, contract, policy, value):
+    from ._engine.factories import agent
+    expectation = contract.get("tool_expectation", {})
+    private_contract = {k: v for k, v in contract.items() if k != "output_schema"}
+    if expectation:
+        private_contract["tool_expectation"] = {k: v for k, v in expectation.items() if k != "forbidden"}
+        private_contract["must_call"] = expectation.get("all_of", [])
+        private_contract["must_not_call"] = expectation.get("forbidden", [])
+    private_contract["require_no_unresolved_tool_failures"] = contract.get("failure_policy") != "allow"
+    private_policy = {**policy, "max_turns": config.max_turns, "max_tool_calls": config.max_tool_calls}
+    if config.max_tokens is not None:
+        private_policy["max_tokens"] = config.max_tokens
+    instructions = owner.instructions
+    if "output_schema" in contract:
+        instructions += "\nReturn a JSON object satisfying this JSON Schema: " + json.dumps(contract["output_schema"])
+    actor = agent(name=owner.name, runtime=config._to_engine(), framework=selected_framework._to_engine(),
+                  skills=[s._to_engine() for s in owner.skills], instructions=instructions,
+                  contract=private_contract, policy=private_policy)
+    return _from_engine(actor.run(value))
+
+
+def _check_output(output, contract):
+    issues = []
+    schema = contract.get("output_schema")
+    if schema is not None:
+        from jsonschema import Draft202012Validator
+        data = output.data
+        if not data and output.text:
+            try:
+                data = json.loads(output.text)
+            except (TypeError, ValueError):
+                issues.append({"code": "invalid_structured_output", "message": "Model text is not JSON"})
+        if isinstance(data, dict):
+            for error in Draft202012Validator(schema).iter_errors(data):
+                issues.append({"code": "output_schema_mismatch", "message": error.message, "path": list(error.path)})
+        else:
+            issues.append({"code": "output_schema_mismatch", "message": "Expected a JSON object"})
+        if not issues:
+            output = replace(output, data=data)
+    called = {e.name for n in output.walk() for e in n.tool_events}
+    forbidden = set(contract.get("tool_expectation", {}).get("forbidden", []))
+    if called & forbidden:
+        issues.append({"code": "forbidden_tool", "message": "Observed a forbidden Tool"})
+    if issues:
+        return replace(output, ok=False, errors=(*output.errors, *issues), validation={"ok": False, "issues": issues})
+    if output.ok and contract.get("failure_policy") == "allow":
+        output = replace(output, meta={**output.meta, "allowed_error_ids": [n.execution_id for n in output.walk()]})
+    return output

agentic_systems-2.1.3/src/agentic_systems/_engine/__init__.py

@@ -0,0 +1 @@
+"""Private provider and framework execution machinery."""