adjacency-agents 0.1.0__py3-none-any.whl

adjacency_agents/__init__.py

@@ -0,0 +1,28 @@
+"""adjacency-agents public facade (§8.1)."""
+
+from adjacency_agents.decorators import tool_node
+from adjacency_agents.engine import DeterministicEngine
+from adjacency_agents.models import (
+    EnrichedPointer,
+    FinalAnswer,
+    Message,
+    Observation,
+    ToolCall,
+    ToolPolicy,
+    UserContext,
+)
+from adjacency_agents.tracing import ExecutionTrace, TraceEvent
+
+__all__ = [
+    "DeterministicEngine",
+    "EnrichedPointer",
+    "ExecutionTrace",
+    "FinalAnswer",
+    "Message",
+    "Observation",
+    "TraceEvent",
+    "ToolCall",
+    "ToolPolicy",
+    "UserContext",
+    "tool_node",
+]

adjacency_agents/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Provider adapters.
+
+Adapters live in their own subpackage so that the core library has no
+hard dependency on any specific LLM SDK. Each adapter module imports
+its provider SDK lazily when needed, and accepts the SDK client object
+directly so that tests can substitute lightweight fakes.
+"""

adjacency_agents/adapters/anthropic.py

@@ -0,0 +1,216 @@
+"""Anthropic Messages API adapter — DDD §13.4, §18.3, Phase 6.
+
+Translates between the engine's provider-agnostic protocol and the
+Anthropic Messages API.
+
+Design notes:
+
+* No hard dependency on ``anthropic``. The user passes an instantiated
+  client (sync or async); the adapter only relies on the duck-typed
+  shape ``client.messages.create(**kwargs)``.
+* Anthropic's tool format is ``{name, description, input_schema}`` with
+  no function envelope, and ``input_schema`` IS the JSON schema (no
+  nesting under ``parameters``). The adapter strips our internal
+  ``title``/``description`` keys before forwarding the schema body.
+* ``role="system"`` messages are pulled out of the conversation and
+  promoted to the top-level ``system`` kwarg; multiple system messages
+  are concatenated with two newlines.
+* ``role="tool"`` messages (produced by synthesis) are rewritten as
+  ``user`` messages prefixed with ``[tool: <name>]`` so the API does
+  not require a paired assistant ``tool_use`` block — which our
+  synthesis flow never produces.
+* ``allow_tool_calls=False`` omits ``tools`` entirely. If the model
+  still returns a ``tool_use`` block, ``SynthesisError`` is raised.
+* The Anthropic response is a list of content blocks. ``text`` blocks
+  are concatenated; a ``tool_use`` block returns ``ToolCall`` with the
+  already-decoded ``input`` dict.
+* ``max_tokens`` is required by the API. Defaults to 1024 unless the
+  caller overrides it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from adjacency_agents.errors import InvalidToolCallError, SynthesisError
+from adjacency_agents.models import FinalAnswer, Message, ToolCall
+
+__all__ = ["AnthropicClient", "AsyncAnthropicClient"]
+
+_DEFAULT_MAX_TOKENS = 1024
+
+
+def _convert_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Project internal schemas onto Anthropic's ``{name, description,
+    input_schema}`` shape."""
+    out: list[dict[str, Any]] = []
+    for schema in tools:
+        input_schema: dict[str, Any] = {
+            k: v for k, v in schema.items() if k not in ("title", "description")
+        }
+        if "type" not in input_schema:
+            input_schema["type"] = "object"
+        entry: dict[str, Any] = {
+            "name": schema.get("title", ""),
+            "input_schema": input_schema,
+        }
+        description = schema.get("description")
+        if description:
+            entry["description"] = description
+        out.append(entry)
+    return out
+
+
+def _split_messages(
+    messages: Sequence[Message],
+) -> tuple[str | None, list[dict[str, Any]]]:
+    """Pull ``role=system`` messages into a single system string and
+    convert the remaining messages to Anthropic's wire format."""
+    system_parts: list[str] = []
+    chat: list[dict[str, Any]] = []
+    for msg in messages:
+        if msg.role == "system":
+            system_parts.append(msg.content)
+            continue
+        if msg.role == "tool":
+            label = msg.name or "tool"
+            chat.append(
+                {
+                    "role": "user",
+                    "content": f"[tool: {label}] {msg.content}",
+                }
+            )
+            continue
+        chat.append({"role": msg.role, "content": msg.content})
+    system = "\n\n".join(system_parts) if system_parts else None
+    return system, chat
+
+
+def _build_kwargs(
+    *,
+    model: str,
+    max_tokens: int,
+    messages: Sequence[Message],
+    tools: list[dict[str, Any]],
+    allow_tool_calls: bool,
+    extra: dict[str, Any] | None,
+) -> dict[str, Any]:
+    system, chat = _split_messages(messages)
+    payload: dict[str, Any] = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": chat,
+    }
+    if system is not None:
+        payload["system"] = system
+    if allow_tool_calls and tools:
+        payload["tools"] = _convert_tools(tools)
+        payload["tool_choice"] = {"type": "auto"}
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def _parse_response(
+    response: Any, *, allow_tool_calls: bool
+) -> ToolCall | FinalAnswer | str:
+    blocks = list(getattr(response, "content", []) or [])
+    text_chunks: list[str] = []
+    for block in blocks:
+        btype = getattr(block, "type", None)
+        if btype == "tool_use":
+            if not allow_tool_calls:
+                raise SynthesisError(
+                    "Anthropic returned a tool_use block during synthesis (§14.7.3)"
+                )
+            name = getattr(block, "name", None)
+            args = getattr(block, "input", None)
+            if not isinstance(name, str) or not name:
+                raise InvalidToolCallError("Anthropic tool_use block missing name")
+            if args is None:
+                args = {}
+            if not isinstance(args, dict):
+                raise InvalidToolCallError(
+                    f"Anthropic tool_use input must be a JSON object, "
+                    f"got {type(args).__name__}"
+                )
+            return ToolCall(name=name, kwargs=dict(args))
+        if btype == "text":
+            text_chunks.append(getattr(block, "text", "") or "")
+
+    if not text_chunks:
+        raise InvalidToolCallError(
+            "Anthropic response had no text and no tool_use blocks"
+        )
+    return FinalAnswer(content="".join(text_chunks))
+
+
+class AnthropicClient:
+    """Synchronous adapter for ``anthropic.Anthropic``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        max_tokens: int = _DEFAULT_MAX_TOKENS,
+        extra_create_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._max_tokens = max_tokens
+        self._extra = dict(extra_create_kwargs) if extra_create_kwargs else None
+
+    def complete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = self._client.messages.create(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)
+
+
+class AsyncAnthropicClient:
+    """Asynchronous adapter for ``anthropic.AsyncAnthropic``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        max_tokens: int = _DEFAULT_MAX_TOKENS,
+        extra_create_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._max_tokens = max_tokens
+        self._extra = dict(extra_create_kwargs) if extra_create_kwargs else None
+
+    async def acomplete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            max_tokens=self._max_tokens,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = await self._client.messages.create(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)

adjacency_agents/adapters/ollama.py

@@ -0,0 +1,220 @@
+"""Ollama adapter — DDD §13.4, §18.3, Phase 6.
+
+Targets the official ``ollama`` Python SDK and any HTTP server that
+mimics its ``client.chat(model=..., messages=..., tools=...)`` shape.
+
+Design notes:
+
+* No hard dependency on ``ollama``. The user passes any object exposing
+  ``client.chat(**kwargs)`` (sync) or an awaitable equivalent (async).
+* Ollama uses the same tool envelope as OpenAI:
+  ``{"type": "function", "function": {"name", "description",
+  "parameters"}}``. Conversion mirrors the OpenAI adapter.
+* The conversation roles supported are ``system``, ``user``,
+  ``assistant`` and ``tool``. Ollama keeps ``system`` inside the
+  messages list (unlike Anthropic). ``role="tool"`` messages produced
+  by synthesis are rewritten as ``user`` messages with a
+  ``[tool: <name>]`` prefix because most Ollama models will not accept
+  a bare tool role without a paired assistant ``tool_calls`` block.
+* ``allow_tool_calls=False`` (synthesis) omits ``tools`` entirely. A
+  ``tool_calls`` payload returned anyway raises ``SynthesisError``.
+* Tool arguments returned by the SDK may be either a Python dict
+  (current versions) or a JSON string (older clients / some local
+  servers). Both are accepted; JSON strings are ``json.loads``ed.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Any
+
+from adjacency_agents.errors import InvalidToolCallError, SynthesisError
+from adjacency_agents.models import FinalAnswer, Message, ToolCall
+
+__all__ = ["OllamaClient", "AsyncOllamaClient"]
+
+
+def _convert_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Wrap internal schemas in the OpenAI-compatible function envelope
+    that Ollama accepts."""
+    out: list[dict[str, Any]] = []
+    for schema in tools:
+        params: dict[str, Any] = {
+            k: v for k, v in schema.items() if k not in ("title", "description")
+        }
+        if "type" not in params:
+            params["type"] = "object"
+        fn_def: dict[str, Any] = {
+            "name": schema.get("title", ""),
+            "parameters": params,
+        }
+        description = schema.get("description")
+        if description:
+            fn_def["description"] = description
+        out.append({"type": "function", "function": fn_def})
+    return out
+
+
+def _convert_messages(messages: Sequence[Message]) -> list[dict[str, Any]]:
+    """Map our Message dataclasses to Ollama's wire format."""
+    out: list[dict[str, Any]] = []
+    for msg in messages:
+        if msg.role == "tool":
+            label = msg.name or "tool"
+            out.append(
+                {
+                    "role": "user",
+                    "content": f"[tool: {label}] {msg.content}",
+                }
+            )
+            continue
+        out.append({"role": msg.role, "content": msg.content})
+    return out
+
+
+def _build_kwargs(
+    *,
+    model: str,
+    messages: Sequence[Message],
+    tools: list[dict[str, Any]],
+    allow_tool_calls: bool,
+    extra: dict[str, Any] | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "model": model,
+        "messages": _convert_messages(messages),
+    }
+    if allow_tool_calls and tools:
+        payload["tools"] = _convert_tools(tools)
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def _decode_arguments(raw: Any, tool_name: str) -> dict[str, Any]:
+    """Ollama's ``arguments`` field is a dict in modern clients but may
+    be a JSON string from older servers. Accept both."""
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str):
+        try:
+            decoded = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise InvalidToolCallError(
+                f"Ollama returned non-JSON tool arguments for {tool_name!r}: {raw!r}"
+            ) from exc
+        if not isinstance(decoded, dict):
+            raise InvalidToolCallError(
+                f"Ollama tool arguments must be a JSON object, "
+                f"got {type(decoded).__name__}"
+            )
+        return decoded
+    if raw is None:
+        return {}
+    raise InvalidToolCallError(
+        f"Ollama tool arguments must be dict or JSON string, got {type(raw).__name__}"
+    )
+
+
+def _get(obj: Any, key: str, default: Any = None) -> Any:
+    """Ollama responses come back as either typed objects or plain
+    dicts depending on the client version."""
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+def _parse_response(
+    response: Any, *, allow_tool_calls: bool
+) -> ToolCall | FinalAnswer | str:
+    message = _get(response, "message")
+    if message is None:
+        raise InvalidToolCallError("Ollama response had no message")
+    tool_calls = _get(message, "tool_calls") or []
+    if tool_calls:
+        if not allow_tool_calls:
+            raise SynthesisError(
+                "Ollama returned tool_calls during synthesis (§14.7.3)"
+            )
+        first = tool_calls[0]
+        function = _get(first, "function")
+        if function is None:
+            raise InvalidToolCallError("Ollama tool_call missing function field")
+        name = _get(function, "name")
+        if not isinstance(name, str) or not name:
+            raise InvalidToolCallError("Ollama tool_call missing function name")
+        raw_args = _get(function, "arguments")
+        kwargs = _decode_arguments(raw_args, name)
+        return ToolCall(name=name, kwargs=kwargs)
+
+    content = _get(message, "content")
+    if not isinstance(content, str) or content == "":
+        raise InvalidToolCallError(
+            "Ollama response had neither tool_calls nor non-empty content"
+        )
+    return FinalAnswer(content=content)
+
+
+class OllamaClient:
+    """Synchronous adapter for ``ollama.Client``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        extra_chat_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._extra = dict(extra_chat_kwargs) if extra_chat_kwargs else None
+
+    def complete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = self._client.chat(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)
+
+
+class AsyncOllamaClient:
+    """Asynchronous adapter for ``ollama.AsyncClient``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        extra_chat_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._extra = dict(extra_chat_kwargs) if extra_chat_kwargs else None
+
+    async def acomplete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = await self._client.chat(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)

adjacency_agents/adapters/openai.py

@@ -0,0 +1,199 @@
+"""OpenAI Chat Completions adapter — DDD §13.4, §18.3, Phase 6.
+
+Translates between the engine's provider-agnostic protocol
+(`LLMClient`/`AsyncLLMClient`) and the OpenAI Chat Completions API.
+
+Design notes:
+
+* No hard dependency on ``openai``. The user passes an instantiated
+  client (sync or async) and the adapter only relies on the duck-typed
+  shape ``client.chat.completions.create(**kwargs)``.
+* The internal JSON schema produced by ``build_json_schema`` is wrapped
+  in OpenAI's ``{"type": "function", "function": {...}}`` envelope.
+* When ``allow_tool_calls=False`` the adapter sends ``tool_choice="none"``
+  and **omits** the ``tools`` argument entirely. If the model still
+  returns a tool call, ``SynthesisError`` is raised.
+* Messages with ``role="tool"`` (produced by the engine during
+  synthesis) cannot be sent as-is — OpenAI requires a paired assistant
+  ``tool_calls`` block, which never exists in our flow. They are
+  rewritten into ``system`` messages prefixed with ``[tool: <name>]``.
+* Tool arguments returned by the model arrive as JSON strings; we
+  ``json.loads`` them. Any parse error raises ``InvalidToolCallError``.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import Any
+
+from adjacency_agents.errors import InvalidToolCallError, SynthesisError
+from adjacency_agents.models import FinalAnswer, Message, ToolCall
+
+__all__ = ["OpenAIClient", "AsyncOpenAIClient"]
+
+
+def _convert_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Wrap our internal schemas in OpenAI's function-tool envelope."""
+    converted: list[dict[str, Any]] = []
+    for schema in tools:
+        params: dict[str, Any] = {
+            k: v for k, v in schema.items() if k not in ("title", "description")
+        }
+        # OpenAI expects parameters to be a JSON schema object.
+        if "type" not in params:
+            params["type"] = "object"
+        fn_def: dict[str, Any] = {
+            "name": schema.get("title", ""),
+            "parameters": params,
+        }
+        description = schema.get("description")
+        if description:
+            fn_def["description"] = description
+        converted.append({"type": "function", "function": fn_def})
+    return converted
+
+
+def _convert_messages(messages: Sequence[Message]) -> list[dict[str, Any]]:
+    """Map our Message dataclasses to OpenAI's wire format.
+
+    ``role="tool"`` messages from synthesis are repackaged as ``system``
+    messages so OpenAI does not reject them (it would otherwise require
+    a matching assistant ``tool_calls`` block we never produced).
+    """
+    out: list[dict[str, Any]] = []
+    for msg in messages:
+        if msg.role == "tool":
+            label = msg.name or "tool"
+            out.append(
+                {
+                    "role": "system",
+                    "content": f"[tool: {label}] {msg.content}",
+                }
+            )
+            continue
+        out.append({"role": msg.role, "content": msg.content})
+    return out
+
+
+def _build_kwargs(
+    *,
+    model: str,
+    messages: Sequence[Message],
+    tools: list[dict[str, Any]],
+    allow_tool_calls: bool,
+    extra: dict[str, Any] | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "model": model,
+        "messages": _convert_messages(messages),
+    }
+    if allow_tool_calls and tools:
+        payload["tools"] = _convert_tools(tools)
+        payload["tool_choice"] = "auto"
+    else:
+        # Synthesis: forbid tool calls outright.
+        payload["tool_choice"] = "none"
+    if extra:
+        payload.update(extra)
+    return payload
+
+
+def _parse_response(
+    response: Any, *, allow_tool_calls: bool
+) -> ToolCall | FinalAnswer | str:
+    choices = getattr(response, "choices", None)
+    if not choices:
+        raise InvalidToolCallError("OpenAI response had no choices")
+    message = choices[0].message
+    tool_calls = getattr(message, "tool_calls", None) or []
+
+    if tool_calls:
+        if not allow_tool_calls:
+            raise SynthesisError(
+                "OpenAI returned a tool_call during synthesis (§14.7.3)"
+            )
+        first = tool_calls[0]
+        name = first.function.name
+        raw_args = first.function.arguments or "{}"
+        try:
+            kwargs = json.loads(raw_args)
+        except json.JSONDecodeError as exc:
+            raise InvalidToolCallError(
+                f"OpenAI returned non-JSON tool arguments for {name!r}: {raw_args!r}"
+            ) from exc
+        if not isinstance(kwargs, dict):
+            raise InvalidToolCallError(
+                f"OpenAI tool arguments must decode to a JSON object, "
+                f"got {type(kwargs).__name__}"
+            )
+        return ToolCall(name=name, kwargs=kwargs)
+
+    content = getattr(message, "content", None)
+    if content is None:
+        raise InvalidToolCallError("OpenAI response had neither content nor tool_calls")
+    return FinalAnswer(content=content)
+
+
+class OpenAIClient:
+    """Synchronous adapter for ``openai.OpenAI``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        extra_create_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._extra = dict(extra_create_kwargs) if extra_create_kwargs else None
+
+    def complete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = self._client.chat.completions.create(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)
+
+
+class AsyncOpenAIClient:
+    """Asynchronous adapter for ``openai.AsyncOpenAI``-shaped clients."""
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str,
+        extra_create_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._extra = dict(extra_create_kwargs) if extra_create_kwargs else None
+
+    async def acomplete(
+        self,
+        *,
+        messages: Sequence[Message],
+        tools: list[dict[str, Any]],
+        allow_tool_calls: bool = True,
+    ) -> ToolCall | FinalAnswer | str:
+        payload = _build_kwargs(
+            model=self._model,
+            messages=messages,
+            tools=tools,
+            allow_tool_calls=allow_tool_calls,
+            extra=self._extra,
+        )
+        response = await self._client.chat.completions.create(**payload)
+        return _parse_response(response, allow_tool_calls=allow_tool_calls)