actant 0.1.0__py3-none-any.whl

actant/__init__.py

@@ -0,0 +1,29 @@
+"""Actant runtime package."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from actant.agents import Agent, AgentDefinition, ContextPolicy, ModelConfig
+    from actant.runtime import AgentRuntime
+
+__all__ = [
+    "Agent",
+    "AgentDefinition",
+    "AgentRuntime",
+    "ContextPolicy",
+    "ModelConfig",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in {"Agent", "AgentDefinition", "ContextPolicy", "ModelConfig"}:
+        from actant import agents
+
+        return getattr(agents, name)
+    if name == "AgentRuntime":
+        from actant import runtime
+
+        return runtime.AgentRuntime
+    raise AttributeError(f"module 'actant' has no attribute {name!r}")

actant/agents.py

@@ -0,0 +1,64 @@
+"""Agent configuration models."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from actant.llm.base import LLMClient
+from actant.llm.messages import Message
+from actant.tools.registry import ToolRegistry
+
+if TYPE_CHECKING:
+    from actant.runtime.events.streaming import StreamListener
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    provider: str
+    model: str
+    temperature: float = 0.0
+    max_tokens: int | None = None
+
+
+@dataclass(frozen=True)
+class Agent:
+    id: str
+    name: str
+    persona: str
+    persona_version: str
+    model: ModelConfig
+    tool_allowlist: set[str] = field(default_factory=set)
+    max_turns_per_thread: int = 25
+
+
+@dataclass(frozen=True)
+class ContextPolicy:
+    max_input_tokens: int | None = None
+    reserve_output_tokens: int = 4096
+
+
+@dataclass(frozen=True)
+class AgentDefinition:
+    id: str
+    name: str
+    persona: str
+    llm: LLMClient
+    tools: ToolRegistry
+    tool_allowlist: set[str] = field(default_factory=set)
+    context_policy: ContextPolicy = field(default_factory=ContextPolicy)
+    persona_version: str = "v1"
+    max_turns_per_thread: int = 25
+
+    async def complete(
+        self,
+        messages: Sequence[Message],
+        listener: "StreamListener | None" = None,
+    ) -> Message:
+        return await self.llm.complete(
+            self.persona,
+            list(messages),
+            self.tools.schemas_for(self.tool_allowlist),
+            listener,
+        )

actant/core.py

@@ -0,0 +1,15 @@
+"""Core utilities and structural types."""
+
+from __future__ import annotations
+
+import uuid
+from typing import TypeAlias
+
+JSONValue: TypeAlias = (
+    str | int | float | bool | None | list["JSONValue"] | dict[str, "JSONValue"]
+)
+JSONObject: TypeAlias = dict[str, JSONValue]
+
+
+def new_id(prefix: str) -> str:
+    return f"{prefix}_{uuid.uuid4().hex}"

actant/inbox.py

@@ -0,0 +1,21 @@
+"""Durable inbox message models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from actant.core import JSONObject
+
+
+@dataclass(frozen=True)
+class InboxMessage:
+    id: str
+    agent_id: str
+    thread_id: str
+    payload: JSONObject
+    source: str = "user"
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    visible_at: datetime | None = None
+    correlation_id: str | None = None
+    environment_id: str | None = None

actant/llm/__init__.py

@@ -0,0 +1,14 @@
+"""LLM provider interfaces."""
+
+from actant.llm.base import LLMClient
+from actant.llm.messages import Message, ToolCall, ToolCallFunction
+from actant.llm.routing import llm_for_model, provider_for_model
+
+__all__ = [
+    "LLMClient",
+    "Message",
+    "ToolCall",
+    "ToolCallFunction",
+    "llm_for_model",
+    "provider_for_model",
+]

actant/llm/base.py

@@ -0,0 +1,23 @@
+"""LLM client protocol."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Protocol
+
+from actant.llm.messages import Message
+
+if TYPE_CHECKING:
+    from actant.runtime.events.streaming import StreamListener
+
+
+class LLMClient(Protocol):
+    model_id: str
+
+    async def complete(
+        self,
+        system: str,
+        messages: Sequence[Message],
+        tools: list[dict],
+        listener: "StreamListener | None" = None,
+    ) -> Message: ...

actant/llm/errors.py

@@ -0,0 +1,7 @@
+"""LLM error types."""
+
+from __future__ import annotations
+
+
+class StreamCancelled(Exception):
+    """Raised when a stream listener requests cancellation mid-generation."""

actant/llm/messages.py

@@ -0,0 +1,156 @@
+"""Provider-neutral message and streaming models."""
+
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from dataclasses import dataclass, field
+from typing import Literal, cast
+
+Role = Literal["system", "user", "assistant", "tool"]
+
+
+@dataclass
+class ToolCallFunction:
+    name: str
+    arguments: str
+
+    @classmethod
+    def from_raw(cls, value: "ToolCallFunction | dict[str, object]") -> "ToolCallFunction":
+        if isinstance(value, cls):
+            return cls(name=value.name, arguments=value.arguments)
+        if not isinstance(value, dict):
+            raise TypeError(f"Expected ToolCallFunction or dict, got {type(value).__name__}")
+
+        raw_arguments = value.get("arguments", "")
+        if raw_arguments is None:
+            arguments = ""
+        elif isinstance(raw_arguments, str):
+            arguments = raw_arguments
+        else:
+            arguments = json.dumps(raw_arguments)
+
+        raw_name = value.get("name", "")
+        name = "" if raw_name is None else str(raw_name)
+        return cls(name=name, arguments=arguments)
+
+    def to_dict(self) -> dict[str, object]:
+        return {"name": self.name, "arguments": self.arguments}
+
+
+@dataclass
+class ToolCall:
+    id: str
+    function: ToolCallFunction
+    type: str = "function"
+    thought_signature: str | None = None
+    extra_content: dict[str, object] = field(default_factory=dict)
+
+    @classmethod
+    def from_raw(cls, value: "ToolCall | dict[str, object]") -> "ToolCall":
+        if isinstance(value, cls):
+            return cls(
+                id=value.id,
+                function=ToolCallFunction.from_raw(value.function),
+                type=value.type,
+                thought_signature=value.thought_signature,
+                extra_content=deepcopy(value.extra_content),
+            )
+        if not isinstance(value, dict):
+            raise TypeError(f"Expected ToolCall or dict, got {type(value).__name__}")
+
+        raw_id = value.get("id", "")
+        raw_type = value.get("type", "function")
+        raw_extra = value.get("extra_content", {})
+        raw_signature = value.get("thought_signature")
+        return cls(
+            id="" if raw_id is None else str(raw_id),
+            function=ToolCallFunction.from_raw(cast(dict[str, object], value.get("function", {}))),
+            type="function" if raw_type is None else str(raw_type),
+            thought_signature=str(raw_signature) if raw_signature is not None else None,
+            extra_content=deepcopy(raw_extra) if isinstance(raw_extra, dict) else {},
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "id": self.id,
+            "function": self.function.to_dict(),
+        }
+        if self.type != "function":
+            data["type"] = self.type
+        if self.thought_signature is not None:
+            data["thought_signature"] = self.thought_signature
+        if self.extra_content:
+            data["extra_content"] = deepcopy(self.extra_content)
+        return data
+
+
+@dataclass
+class Message:
+    role: Role
+    content: str | list[dict[str, object]] | None = None
+    tool_calls: list[ToolCall] | None = None
+    tool_call_id: str | None = None
+    name: str | None = None
+    thought_summary: str | None = None
+    thinking_signature: str | None = None
+    reasoning_items: list[object] | None = None
+
+    @classmethod
+    def from_raw(cls, value: "Message | dict[str, object]") -> "Message":
+        if isinstance(value, cls):
+            return cls(
+                role=value.role,
+                content=deepcopy(value.content),
+                tool_calls=(
+                    [ToolCall.from_raw(tc) for tc in value.tool_calls]
+                    if value.tool_calls is not None
+                    else None
+                ),
+                tool_call_id=value.tool_call_id,
+                name=value.name,
+                thought_summary=value.thought_summary,
+                thinking_signature=value.thinking_signature,
+                reasoning_items=deepcopy(value.reasoning_items),
+            )
+        if not isinstance(value, dict):
+            raise TypeError(f"Expected Message or dict, got {type(value).__name__}")
+
+        raw_tool_calls = value.get("tool_calls")
+        content = value.get("content", "")
+        raw_reasoning_items = value.get("reasoning_items")
+        return cls(
+            role=cast(Role, value.get("role", "user")),
+            content=deepcopy(content) if isinstance(content, list) else str(content),
+            tool_calls=(
+                [ToolCall.from_raw(tc) for tc in raw_tool_calls]
+                if isinstance(raw_tool_calls, list)
+                else None
+            ),
+            tool_call_id=cast(str | None, value.get("tool_call_id")),
+            name=cast(str | None, value.get("name")),
+            thought_summary=cast(str | None, value.get("thought_summary")),
+            thinking_signature=cast(str | None, value.get("thinking_signature")),
+            reasoning_items=(
+                deepcopy(raw_reasoning_items) if isinstance(raw_reasoning_items, list) else None
+            ),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data: dict[str, object] = {
+            "role": self.role,
+            "content": deepcopy(self.content),
+        }
+        if self.tool_calls is not None:
+            data["tool_calls"] = [tc.to_dict() for tc in self.tool_calls]
+        if self.tool_call_id is not None:
+            data["tool_call_id"] = self.tool_call_id
+        if self.name is not None:
+            data["name"] = self.name
+        if self.thought_summary is not None:
+            data["thought_summary"] = self.thought_summary
+        if self.thinking_signature is not None:
+            data["thinking_signature"] = self.thinking_signature
+        if self.reasoning_items is not None:
+            data["reasoning_items"] = deepcopy(self.reasoning_items)
+        return data

actant/llm/providers/__init__.py

@@ -0,0 +1,45 @@
+"""LLM provider implementations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from actant.llm.providers.anthropic import AnthropicProvider
+    from actant.llm.providers.fake import FakeLLM, FakeResponse
+    from actant.llm.providers.gemini import GeminiProvider
+    from actant.llm.providers.openai import OpenAIProvider
+    from actant.llm.providers.qwen import QwenProvider
+
+__all__ = [
+    "AnthropicProvider",
+    "FakeLLM",
+    "FakeResponse",
+    "GeminiProvider",
+    "OpenAIProvider",
+    "QwenProvider",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "AnthropicProvider":
+        from actant.llm.providers.anthropic import AnthropicProvider
+
+        return AnthropicProvider
+    if name in {"FakeLLM", "FakeResponse"}:
+        from actant.llm.providers import fake
+
+        return getattr(fake, name)
+    if name == "GeminiProvider":
+        from actant.llm.providers.gemini import GeminiProvider
+
+        return GeminiProvider
+    if name == "OpenAIProvider":
+        from actant.llm.providers.openai import OpenAIProvider
+
+        return OpenAIProvider
+    if name == "QwenProvider":
+        from actant.llm.providers.qwen import QwenProvider
+
+        return QwenProvider
+    raise AttributeError(f"module 'actant.llm.providers' has no attribute {name!r}")

actant/llm/providers/_shared.py

@@ -0,0 +1,112 @@
+"""Shared helpers used by two or more provider adapters.
+
+Single-provider helpers live in their owning provider module:
+- ``REASONING_EFFORT``, ``content_to_openai_user_parts`` → ``openai.py``
+- ``dereference_schema``, ``strip_unsupported_schema_keys`` → ``gemini.py``
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from collections.abc import Mapping, Sequence
+
+from actant.llm.messages import Message, ToolCall
+
+ToolSchema = dict[str, object]
+ContentBlock = dict[str, object]
+
+
+def env_api_key(name: str, explicit: str | None = None) -> str:
+    key = explicit or os.environ.get(name)
+    if not key:
+        raise RuntimeError(f"{name} is required for this provider adapter.")
+    return key
+
+
+def normalize_json_schema(schema: object) -> object:
+    if not isinstance(schema, dict):
+        return schema
+
+    result: dict[str, object] = {}
+    for key, value in schema.items():
+        if key == "prefixItems":
+            if value and isinstance(value, list):
+                result["items"] = normalize_json_schema(value[0])
+            continue
+        if key == "$defs" and isinstance(value, dict):
+            result[key] = {k: normalize_json_schema(v) for k, v in value.items()}
+        elif isinstance(value, dict):
+            result[key] = normalize_json_schema(value)
+        elif isinstance(value, list):
+            result[key] = [normalize_json_schema(item) for item in value]
+        else:
+            result[key] = value
+    return result
+
+
+def convert_image_source(source: Mapping[str, object]) -> ContentBlock | None:
+    if source.get("type") == "base64":
+        return {
+            "type": "input_image",
+            "image_url": f"data:{source['media_type']};base64,{source['data']}",
+        }
+    if source.get("type") == "url":
+        return {"type": "input_image", "image_url": source["url"]}
+    return None
+
+
+def split_tool_content(
+    content: str | list[ContentBlock] | None,
+) -> tuple[str, list[ContentBlock]]:
+    if content is None:
+        return "", []
+    if isinstance(content, str):
+        return content, []
+
+    text_parts: list[str] = []
+    image_parts: list[ContentBlock] = []
+    for block in content:
+        if not isinstance(block, dict):
+            text_parts.append(str(block))
+        elif block.get("type") == "text":
+            text_parts.append(str(block.get("text", "")))
+        elif block.get("type") == "image":
+            source = block.get("source")
+            image = convert_image_source(source) if isinstance(source, Mapping) else None
+            if image:
+                image_parts.append(image)
+    return "\n".join(text_parts) if text_parts else "OK", image_parts
+
+
+def sanitize_tool_messages(
+    messages: Sequence[Message | dict[str, object]],
+) -> list[Message]:
+    sanitized: list[Message] = []
+    pending_ids: list[str] = []
+
+    for raw_message in messages:
+        message = Message.from_raw(raw_message)
+        if message.role == "assistant" and message.tool_calls is not None:
+            normalized_tool_calls: list[ToolCall] = []
+            for raw_tool_call in message.tool_calls:
+                tool_call = ToolCall.from_raw(raw_tool_call)
+                if not tool_call.id:
+                    tool_call.id = f"call_{uuid.uuid4().hex}"
+                pending_ids.append(tool_call.id)
+                normalized_tool_calls.append(tool_call)
+            message.tool_calls = normalized_tool_calls
+        elif message.role == "tool":
+            tool_call_id = message.tool_call_id or ""
+            if tool_call_id:
+                if pending_ids and pending_ids[0] == tool_call_id:
+                    pending_ids.pop(0)
+                elif tool_call_id in pending_ids:
+                    pending_ids.remove(tool_call_id)
+            elif pending_ids:
+                message.tool_call_id = pending_ids.pop(0)
+            else:
+                message.tool_call_id = f"call_{uuid.uuid4().hex}"
+        sanitized.append(message)
+
+    return sanitized