agentlings 0.2.0__py3-none-any.whl

agentlings/core/llm.py

@@ -0,0 +1,509 @@
+"""LLM client abstraction with Anthropic and mock backends."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Literal
+from uuid import uuid4
+
+logger = logging.getLogger(__name__)
+
+BATCH_MAX_REQUESTS = 100_000
+
+# Matches ``delay-<seconds>`` in mock user messages — used by integration
+# tests to produce genuinely slow responses without global configuration.
+# Example: ``"delay-5 please answer"`` sleeps 5 seconds before responding.
+_MOCK_DELAY_RE = re.compile(r"delay-(\d+(?:\.\d+)?)")
+
+
+@dataclass
+class LLMResponse:
+    """Container for an LLM completion response.
+
+    Attributes:
+        content: List of content blocks (text, tool_use, etc.) from the model.
+        stop_reason: Why the model stopped generating (e.g. ``"end_turn"``, ``"tool_use"``).
+    """
+
+    content: list[dict[str, Any]]
+    stop_reason: str | None = None
+
+
+@dataclass
+class BatchRequest:
+    """A single request within a batch submission.
+
+    Attributes:
+        custom_id: Caller-provided ID for correlating results.
+        system: System prompt blocks.
+        messages: Conversation messages.
+        max_tokens: Maximum response tokens.
+        output_schema: JSON Schema for structured output (used with ``output_config``).
+    """
+
+    custom_id: str
+    system: list[dict[str, Any]]
+    messages: list[dict[str, Any]]
+    max_tokens: int = 4096
+    output_schema: dict[str, Any] | None = None
+
+
+@dataclass
+class BatchItemResult:
+    """Result for a single request within a completed batch.
+
+    Attributes:
+        custom_id: The caller-provided ID from the request.
+        content: Response content blocks (or empty on failure).
+        status: Whether this individual request succeeded or failed.
+        error: Error message if the request failed.
+    """
+
+    custom_id: str
+    content: list[dict[str, Any]] = field(default_factory=list)
+    status: Literal["succeeded", "failed"] = "succeeded"
+    error: str | None = None
+
+
+@dataclass
+class BatchStatus:
+    """Status of a batch job.
+
+    Attributes:
+        batch_id: The batch identifier.
+        processing_status: Current batch state.
+        succeeded: Count of succeeded requests.
+        failed: Count of failed requests.
+        total: Total number of requests.
+    """
+
+    batch_id: str
+    processing_status: str
+    succeeded: int = 0
+    failed: int = 0
+    total: int = 0
+
+
+class BaseLLMClient(ABC):
+    """Abstract interface for LLM completion backends."""
+
+    @abstractmethod
+    async def complete(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+        output_schema: dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        """Send a completion request and return the full response.
+
+        Args:
+            system: System prompt blocks.
+            messages: Conversation message history.
+            tools: Tool schemas available to the model.
+            output_schema: JSON Schema for structured output. When provided,
+                the model is constrained to return valid JSON matching this schema.
+
+        Returns:
+            The model's response content and stop reason.
+        """
+        ...
+
+    @abstractmethod
+    async def stream(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Stream completion response blocks incrementally.
+
+        Args:
+            system: System prompt blocks.
+            messages: Conversation message history.
+            tools: Tool schemas available to the model.
+
+        Yields:
+            Individual content blocks as they arrive.
+        """
+        ...
+
+    @abstractmethod
+    async def count_tokens(self, text: str) -> int:
+        """Count the number of tokens in a text string.
+
+        Args:
+            text: The text to tokenize.
+
+        Returns:
+            The token count.
+        """
+        ...
+
+    @abstractmethod
+    async def batch_create(self, requests: list[BatchRequest], model: str | None = None) -> list[str]:
+        """Submit batch requests, chunking at the API limit.
+
+        Args:
+            requests: The batch requests to submit.
+            model: Model override (uses client default if ``None``).
+
+        Returns:
+            List of batch IDs (one per chunk).
+        """
+        ...
+
+    @abstractmethod
+    async def batch_status(self, batch_id: str) -> BatchStatus:
+        """Poll the status of a batch job.
+
+        Args:
+            batch_id: The batch identifier.
+
+        Returns:
+            Current batch status.
+        """
+        ...
+
+    @abstractmethod
+    async def batch_results(self, batch_id: str) -> list[BatchItemResult]:
+        """Retrieve results from a completed batch.
+
+        Args:
+            batch_id: The batch identifier.
+
+        Returns:
+            List of per-request results.
+        """
+        ...
+
+
+class AnthropicLLMClient(BaseLLMClient):
+    """LLM client backed by the Anthropic Messages API.
+
+    Also works against any Anthropic-compatible endpoint by passing
+    ``base_url`` — for example Ollama's ``/v1/messages`` compatibility
+    layer at ``http://localhost:11434``. When pointed at such a backend,
+    set the model to one served by that backend (e.g. ``"qwen3-coder"``)
+    and disable features the backend doesn't implement (batches, the
+    sleep cycle, structured output) via configuration.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        max_tokens: int,
+        base_url: str | None = None,
+    ) -> None:
+        import anthropic
+
+        client_kwargs: dict[str, Any] = {"api_key": api_key or "unset"}
+        if base_url:
+            client_kwargs["base_url"] = base_url
+        self._client = anthropic.AsyncAnthropic(**client_kwargs)
+        self._model = model
+        self._max_tokens = max_tokens
+
+    async def complete(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+        output_schema: dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        kwargs: dict[str, Any] = {
+            "model": self._model,
+            "max_tokens": self._max_tokens,
+            "system": system,
+            "messages": messages,
+        }
+        if tools:
+            kwargs["tools"] = tools
+        if output_schema:
+            kwargs["output_config"] = {
+                "format": {
+                    "type": "json_schema",
+                    "schema": output_schema,
+                }
+            }
+
+        response = await self._client.messages.create(**kwargs)
+        return LLMResponse(
+            content=[block.model_dump() for block in response.content],
+            stop_reason=response.stop_reason,
+        )
+
+    async def stream(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        raise NotImplementedError("Streaming not yet implemented")
+        yield  # pragma: no cover
+
+    async def count_tokens(self, text: str) -> int:
+        result = await self._client.messages.count_tokens(
+            model=self._model,
+            messages=[{"role": "user", "content": text}],
+        )
+        return result.input_tokens
+
+    async def batch_create(self, requests: list[BatchRequest], model: str | None = None) -> list[str]:
+        from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
+        from anthropic.types.messages.batch_create_params import Request
+
+        use_model = model or self._model
+        batch_ids: list[str] = []
+
+        for i in range(0, len(requests), BATCH_MAX_REQUESTS):
+            chunk = requests[i : i + BATCH_MAX_REQUESTS]
+            api_requests = []
+            for req in chunk:
+                params: dict[str, Any] = {
+                    "model": use_model,
+                    "max_tokens": req.max_tokens,
+                    "system": req.system,
+                    "messages": req.messages,
+                }
+                if req.output_schema:
+                    params["output_config"] = {
+                        "format": {
+                            "type": "json_schema",
+                            "schema": req.output_schema,
+                        }
+                    }
+                api_requests.append(
+                    Request(
+                        custom_id=req.custom_id,
+                        params=MessageCreateParamsNonStreaming(**params),
+                    )
+                )
+
+            result = await self._client.messages.batches.create(requests=api_requests)
+            batch_ids.append(result.id)
+            logger.info("batch submitted: %s (%d requests)", result.id, len(chunk))
+
+        return batch_ids
+
+    async def batch_status(self, batch_id: str) -> BatchStatus:
+        result = await self._client.messages.batches.retrieve(batch_id)
+        counts = result.request_counts
+        return BatchStatus(
+            batch_id=result.id,
+            processing_status=result.processing_status,
+            succeeded=counts.succeeded,
+            failed=counts.errored + counts.expired,
+            total=counts.succeeded + counts.errored + counts.expired + counts.processing,
+        )
+
+    async def batch_results(self, batch_id: str) -> list[BatchItemResult]:
+        items: list[BatchItemResult] = []
+        async for entry in await self._client.messages.batches.results(batch_id):
+            if entry.result.type == "succeeded":
+                content = [block.model_dump() for block in entry.result.message.content]
+                items.append(BatchItemResult(
+                    custom_id=entry.custom_id,
+                    content=content,
+                    status="succeeded",
+                ))
+            else:
+                error_msg = str(entry.result.error) if hasattr(entry.result, "error") else "unknown error"
+                items.append(BatchItemResult(
+                    custom_id=entry.custom_id,
+                    status="failed",
+                    error=error_msg,
+                ))
+        return items
+
+
+class MockLLMClient(BaseLLMClient):
+    """Deterministic mock LLM client for testing without API calls.
+
+    Returns canned responses based on pattern matching:
+    tool name in input triggers tool_use, tool results get text replies,
+    everything else gets an echo response.
+
+    Integration tests can produce genuinely slow responses by embedding
+    ``delay-<seconds>`` in the user message (e.g. ``"delay-5 please
+    answer"``). The mock sleeps that many seconds before responding. The
+    delay is skipped on tool-result loops so multi-turn flows don't re-sleep.
+    """
+
+    def __init__(
+        self,
+        tool_names: list[str] | None = None,
+        compaction_threshold: int = 10,
+    ) -> None:
+        self._tool_names = tool_names or []
+        self._compaction_threshold = compaction_threshold
+        self._call_count = 0
+        self._batch_store: dict[str, list[BatchRequest]] = {}
+
+    async def complete(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+        output_schema: dict[str, Any] | None = None,
+    ) -> LLMResponse:
+        self._call_count += 1
+        last_message = messages[-1] if messages else {}
+        last_text = _extract_text(last_message)
+
+        # Honour embedded ``delay-N`` markers, but only on fresh user/assistant
+        # turns — never on tool-result loops (those would re-trip the sleep
+        # every iteration of the completion loop).
+        content = last_message.get("content")
+        is_tool_result_turn = (
+            isinstance(content, list)
+            and any(
+                isinstance(b, dict) and b.get("type") == "tool_result"
+                for b in content
+            )
+        )
+        if not is_tool_result_turn:
+            m = _MOCK_DELAY_RE.search(last_text)
+            if m:
+                await asyncio.sleep(float(m.group(1)))
+
+        if last_message.get("role") == "tool":
+            return LLMResponse(
+                content=[{"type": "text", "text": f"Tool result received: {last_text}"}],
+                stop_reason="end_turn",
+            )
+
+        for tool_name in self._tool_names:
+            if tool_name in last_text:
+                return LLMResponse(
+                    content=[{
+                        "type": "tool_use",
+                        "id": f"toolu_{uuid4().hex[:12]}",
+                        "name": tool_name,
+                        "input": _build_mock_tool_input(tool_name, last_text),
+                    }],
+                    stop_reason="tool_use",
+                )
+
+        return LLMResponse(
+            content=[{"type": "text", "text": f"Mock response to: {last_text}"}],
+            stop_reason="end_turn",
+        )
+
+    async def stream(
+        self,
+        system: list[dict[str, Any]],
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]],
+    ) -> AsyncIterator[dict[str, Any]]:
+        response = await self.complete(system, messages, tools)
+        for block in response.content:
+            yield block
+
+    async def count_tokens(self, text: str) -> int:
+        return len(text) // 4
+
+    async def batch_create(self, requests: list[BatchRequest], model: str | None = None) -> list[str]:
+        batch_id = f"mock_batch_{uuid4().hex[:8]}"
+        self._batch_store[batch_id] = requests
+        return [batch_id]
+
+    async def batch_status(self, batch_id: str) -> BatchStatus:
+        requests = self._batch_store.get(batch_id, [])
+        return BatchStatus(
+            batch_id=batch_id,
+            processing_status="ended",
+            succeeded=len(requests),
+            failed=0,
+            total=len(requests),
+        )
+
+    async def batch_results(self, batch_id: str) -> list[BatchItemResult]:
+        import json
+        requests = self._batch_store.get(batch_id, [])
+        results: list[BatchItemResult] = []
+        for req in requests:
+            text = _extract_text(req.messages[-1]) if req.messages else ""
+            mock_output = {
+                "summary": f"Summary of conversation: {text[:100]}",
+                "memory_candidates": [],
+            }
+            results.append(BatchItemResult(
+                custom_id=req.custom_id,
+                content=[{"type": "text", "text": json.dumps(mock_output)}],
+                status="succeeded",
+            ))
+        return results
+
+
+def create_llm_client(
+    backend: str,
+    api_key: str = "",
+    model: str = "claude-sonnet-4-6",
+    max_tokens: int = 4096,
+    tool_names: list[str] | None = None,
+    base_url: str | None = None,
+) -> BaseLLMClient:
+    """Factory that returns the appropriate LLM client for the given backend.
+
+    Args:
+        backend: Either ``"anthropic"`` for the real API or ``"mock"`` for testing.
+        api_key: Anthropic API key. Required for the upstream Anthropic API,
+            optional when ``base_url`` points at a compatible backend (e.g.
+            Ollama) that does not validate the key.
+        model: Model identifier to use for completions.
+        max_tokens: Maximum tokens in the model response.
+        tool_names: Tool names the mock backend should recognize.
+        base_url: Optional override for the Anthropic Messages endpoint.
+            When set, the client talks to that URL instead of api.anthropic.com.
+
+    Returns:
+        A configured LLM client instance.
+    """
+    if backend == "mock":
+        logger.info("using mock LLM backend")
+        return MockLLMClient(tool_names=tool_names)
+
+    if base_url:
+        logger.info("using Anthropic-compatible LLM backend (model=%s, base_url=%s)", model, base_url)
+    else:
+        logger.info("using Anthropic LLM backend (model=%s)", model)
+    return AnthropicLLMClient(
+        api_key=api_key, model=model, max_tokens=max_tokens, base_url=base_url,
+    )
+
+
+def _extract_text(message: dict[str, Any]) -> str:
+    content = message.get("content", "")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "text":
+                parts.append(block.get("text", ""))
+            elif isinstance(block, dict) and block.get("type") == "tool_result":
+                parts.append(str(block.get("content", "")))
+        return " ".join(parts)
+    return str(content)
+
+
+def _build_mock_tool_input(tool_name: str, text: str) -> dict[str, Any]:
+    if tool_name == "bash":
+        return {"command": "echo 'mock command'"}
+    if tool_name == "read_file":
+        return {"path": "/tmp/mock_file.txt"}
+    if tool_name == "write_file":
+        return {"path": "/tmp/mock_file.txt", "content": "mock content"}
+    if tool_name == "edit_file":
+        return {"path": "/tmp/mock_file.txt", "old_text": "old", "new_text": "new"}
+    if tool_name == "list_directory":
+        return {"path": "/tmp"}
+    if tool_name == "search_files":
+        return {"path": "/tmp", "pattern": "*.txt"}
+    return {"input": text}

agentlings/core/loop.py

@@ -0,0 +1,134 @@
+"""Message loop — the single entrance point for all agent interactions.
+
+In v2, the loop is a thin backwards-compatible facade over ``TaskEngine``.
+Every call to ``process_message`` spawns a task, blocks until it reaches a
+terminal state, and returns the final response as a ``LoopResult``.
+
+Protocol adapters that want the full task surface (poll, cancel, slow-path
+yield) should call ``TaskEngine`` directly via the ``engine`` property.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from agentlings.config import AgentConfig
+from agentlings.core.llm import BaseLLMClient
+from agentlings.core.memory_store import MemoryFileStore
+from agentlings.core.store import JournalStore
+from agentlings.core.task import (
+    TaskEngine,
+    TaskState,
+    TaskStatus,
+)
+from agentlings.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+# "Effectively unlimited" await for callers that expect synchronous semantics.
+# Real deployments rely on ``TaskEngine.spawn`` directly with the configured
+# ``AGENT_TASK_AWAIT_SECONDS`` cap.
+_SYNCHRONOUS_AWAIT_SECONDS = 3600.0
+
+
+class LoopError(RuntimeError):
+    """Raised when the synchronous message-loop facade cannot deliver a result.
+
+    Occurs when the underlying task failed or was cancelled. The ``state``
+    attribute carries the ``TaskState`` for callers that need to inspect.
+    """
+
+    def __init__(self, state: TaskState) -> None:
+        super().__init__(
+            f"task {state.task_id} ended with status {state.status.value}: {state.error or ''}"
+        )
+        self.state = state
+
+
+@dataclass
+class LoopResult:
+    """Result of processing a message through the loop.
+
+    Attributes:
+        context_id: The conversation context identifier.
+        content: Anthropic-format content blocks from the final LLM response.
+        task_id: The task identifier used to execute this message (v2).
+    """
+
+    context_id: str
+    content: list[dict[str, Any]]
+    task_id: str | None = None
+
+
+class MessageLoop:
+    """Synchronous facade over ``TaskEngine`` for legacy callers.
+
+    Attributes:
+        engine: The underlying task engine. Protocol adapters should prefer
+            its API (``spawn``, ``poll``, ``cancel``) when they need the
+            task-based surface.
+    """
+
+    def __init__(
+        self,
+        config: AgentConfig,
+        store: JournalStore,
+        llm: BaseLLMClient,
+        tools: ToolRegistry,
+        memory_store: MemoryFileStore | None = None,
+    ) -> None:
+        self._config = config
+        self._store = store
+        self._engine = TaskEngine(
+            config=config,
+            store=store,
+            llm=llm,
+            tools=tools,
+            memory_store=memory_store,
+        )
+
+    @property
+    def engine(self) -> TaskEngine:
+        """The underlying task engine."""
+        return self._engine
+
+    async def process_message(
+        self,
+        text: str,
+        context_id: str | None = None,
+        stream: bool = False,
+        via: str = "a2a",
+    ) -> LoopResult:
+        """Process a user message and return the agent's response.
+
+        Backward-compatible synchronous API. Internally spawns a task and
+        waits for it to reach a terminal state.
+
+        Args:
+            text: The user's message text.
+            context_id: Existing context ID to continue, or ``None`` for a new one.
+            stream: Legacy flag; currently ignored.
+            via: Protocol that originated the request (``"a2a"`` or ``"mcp"``).
+
+        Returns:
+            The context ID, the final response content blocks, and the task ID.
+
+        Raises:
+            LoopError: If the underlying task failed or was cancelled.
+        """
+        state = await self._engine.spawn(
+            message=text,
+            context_id=context_id,
+            via=via,
+            await_seconds=_SYNCHRONOUS_AWAIT_SECONDS,
+        )
+        if state.status != TaskStatus.COMPLETED:
+            raise LoopError(state)
+        return LoopResult(
+            context_id=state.context_id,
+            content=state.content,
+            task_id=state.task_id,
+        )