nextloop 0.1.0rc1__py3-none-any.whl

nextloop/__init__.py

@@ -0,0 +1,96 @@
+from .adapters.anthropic import AnthropicProvider
+from .adapters.memory import InMemoryEventStore
+from .adapters.openai import OpenAIProvider
+from .adapters.sqlite import SQLiteEventStore
+from .contracts import (
+    API_VERSION,
+    EVENT_SCHEMA_VERSION,
+    Cancelled,
+    CandidateRequest,
+    CapacityError,
+    Completed,
+    DeliveryOwner,
+    Event,
+    EventStore,
+    EventType,
+    FinalMessage,
+    FinishReason,
+    InvariantViolation,
+    LoopConfig,
+    Message,
+    ModelProvider,
+    ModelResponse,
+    ModelUsage,
+    NewEvent,
+    NextloopError,
+    ProtocolExhausted,
+    ProviderError,
+    RecoveryOutcome,
+    Skipped,
+    SurfaceOp,
+    ToolCall,
+    ToolExecutionMode,
+    ToolOutcome,
+    ToolRuntime,
+    ToolSpec,
+    TurnContext,
+    TurnOutcome,
+    TurnStatus,
+    UncertainHanging,
+    UncertainSettled,
+    ValidatedCall,
+    ValidationIssue,
+    new_id,
+    utc_now,
+)
+from .execute.tools import ToolContext, ToolRegistry
+from .loop import AgentLoop
+
+__all__ = [
+    "API_VERSION",
+    "EVENT_SCHEMA_VERSION",
+    "AgentLoop",
+    "AnthropicProvider",
+    "CandidateRequest",
+    "Cancelled",
+    "CapacityError",
+    "Completed",
+    "DeliveryOwner",
+    "Event",
+    "EventStore",
+    "EventType",
+    "FinalMessage",
+    "FinishReason",
+    "InMemoryEventStore",
+    "InvariantViolation",
+    "LoopConfig",
+    "Message",
+    "ModelProvider",
+    "ModelResponse",
+    "ModelUsage",
+    "NewEvent",
+    "NextloopError",
+    "OpenAIProvider",
+    "ProtocolExhausted",
+    "ProviderError",
+    "RecoveryOutcome",
+    "SQLiteEventStore",
+    "Skipped",
+    "SurfaceOp",
+    "ToolCall",
+    "ToolContext",
+    "ToolExecutionMode",
+    "ToolOutcome",
+    "ToolRegistry",
+    "ToolRuntime",
+    "ToolSpec",
+    "TurnContext",
+    "TurnOutcome",
+    "TurnStatus",
+    "UncertainHanging",
+    "UncertainSettled",
+    "ValidatedCall",
+    "ValidationIssue",
+    "new_id",
+    "utc_now",
+]

nextloop/adapters/__init__.py

@@ -0,0 +1,6 @@
+from .anthropic import AnthropicProvider
+from .memory import InMemoryEventStore
+from .openai import OpenAIProvider
+from .sqlite import SQLiteEventStore
+
+__all__ = ["AnthropicProvider", "InMemoryEventStore", "OpenAIProvider", "SQLiteEventStore"]

nextloop/adapters/_sse.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import httpx
+
+
+async def data_events(response: httpx.Response) -> AsyncIterator[tuple[str, str]]:
+    event = "message"
+    data: list[str] = []
+    async for line in response.aiter_lines():
+        if not line:
+            if data:
+                yield event, "\n".join(data)
+            event = "message"
+            data = []
+            continue
+        if line.startswith(":"):
+            continue
+        if line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:"):
+            data.append(line[5:].lstrip())
+    if data:
+        yield event, "\n".join(data)

nextloop/adapters/anthropic.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ..contracts import (
+    CandidateRequest,
+    FinishReason,
+    Message,
+    ModelResponse,
+    ModelUsage,
+    ProviderError,
+    ToolCall,
+)
+from ._sse import data_events
+
+
+class AnthropicProvider:
+    def __init__(
+        self,
+        *,
+        model_id: str,
+        base_url: str,
+        api_key: str,
+        default_parameters: Mapping[str, Any] | None = None,
+        timeout_seconds: float = 60.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.model_id = model_id
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.default_parameters = {"max_tokens": 4096, **dict(default_parameters or {})}
+        self.timeout_seconds = timeout_seconds
+        self.http_client = http_client
+
+    async def complete(
+        self,
+        request: CandidateRequest,
+        *,
+        attempt: int,
+        cancel: asyncio.Event,
+    ) -> ModelResponse:
+        system = "\n\n".join(
+            message.content for message in request.messages if message.role == "system"
+        )
+        body = {
+            **self.default_parameters,
+            "model": self.model_id,
+            "messages": self._messages(request.messages),
+            "stream": True,
+        }
+        if system:
+            body["system"] = system
+        if request.tools:
+            body["tools"] = [
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": dict(tool.parameters),
+                }
+                for tool in request.tools
+            ]
+        headers = {
+            "x-api-key": self.api_key,
+            "anthropic-version": "2023-06-01",
+            "Content-Type": "application/json",
+        }
+        client = self.http_client or httpx.AsyncClient(timeout=self.timeout_seconds)
+        text_blocks: dict[int, list[str]] = {}
+        tool_blocks: dict[int, dict[str, Any]] = {}
+        finish_reason = FinishReason.STOP
+        input_tokens = None
+        output_tokens = None
+        try:
+            async with client.stream(
+                "POST", self._endpoint(), json=body, headers=headers
+            ) as response:
+                if response.status_code >= 400:
+                    error_body = await response.aread()
+                    error_text = error_body.decode("utf-8", errors="replace")
+                    raise ProviderError(
+                        f"Anthropic HTTP {response.status_code}: {error_text}",
+                        retryable=response.status_code in (408, 409, 429)
+                        or response.status_code >= 500,
+                        code=str(response.status_code),
+                    )
+                async for event, data in data_events(response):
+                    if cancel.is_set():
+                        return ModelResponse(
+                            content=self._text(text_blocks),
+                            finish_reason=FinishReason.CANCELLED,
+                        )
+                    payload = json.loads(data)
+                    if event == "message_start":
+                        usage = payload.get("message", {}).get("usage", {})
+                        input_tokens = usage.get("input_tokens", input_tokens)
+                    elif event == "content_block_start":
+                        index = int(payload["index"])
+                        block = payload["content_block"]
+                        if block["type"] == "text":
+                            text_blocks[index] = [block.get("text", "")]
+                        elif block["type"] == "tool_use":
+                            tool_blocks[index] = {
+                                "id": block["id"],
+                                "name": block["name"],
+                                "arguments": (
+                                    json.dumps(block["input"], separators=(",", ":"))
+                                    if block.get("input")
+                                    else ""
+                                ),
+                            }
+                    elif event == "content_block_delta":
+                        index = int(payload["index"])
+                        delta = payload["delta"]
+                        if delta["type"] == "text_delta":
+                            text_blocks.setdefault(index, []).append(delta["text"])
+                        elif delta["type"] == "input_json_delta":
+                            tool_blocks[index]["arguments"] += delta["partial_json"]
+                    elif event == "message_delta":
+                        stop_reason = payload.get("delta", {}).get("stop_reason")
+                        finish_reason = self._finish_reason(stop_reason) or finish_reason
+                        output_tokens = payload.get("usage", {}).get("output_tokens", output_tokens)
+                    elif event == "error":
+                        error = payload.get("error", {})
+                        raise ProviderError(
+                            f"Anthropic stream error: {error}",
+                            retryable=error.get("type") in ("overloaded_error", "rate_limit_error"),
+                            partial_output=bool(text_blocks or tool_blocks),
+                            code=error.get("type"),
+                        )
+            return ModelResponse(
+                content=self._text(text_blocks),
+                tool_calls=tuple(
+                    ToolCall(block["id"], block["name"], block["arguments"])
+                    for _, block in sorted(tool_blocks.items())
+                ),
+                finish_reason=finish_reason,
+                usage=ModelUsage(input_tokens=input_tokens, output_tokens=output_tokens),
+            )
+        except ProviderError:
+            raise
+        except (TimeoutError, httpx.HTTPError, json.JSONDecodeError, KeyError) as exc:
+            raise ProviderError(
+                f"Anthropic stream failed: {exc}",
+                retryable=True,
+                partial_output=bool(text_blocks or tool_blocks),
+            ) from exc
+        finally:
+            if self.http_client is None:
+                await client.aclose()
+
+    def _endpoint(self) -> str:
+        if self.base_url.endswith("/v1/messages"):
+            return self.base_url
+        return self.base_url + "/v1/messages"
+
+    @staticmethod
+    def _text(blocks: Mapping[int, list[str]]) -> str:
+        return "".join("".join(parts) for _, parts in sorted(blocks.items()))
+
+    @staticmethod
+    def _messages(messages: tuple[Message, ...]) -> list[dict[str, Any]]:
+        result = []
+        for message in messages:
+            if message.role == "system":
+                continue
+            if message.role == "assistant":
+                content: list[dict[str, Any]] = []
+                if message.content:
+                    content.append({"type": "text", "text": message.content})
+                content.extend(
+                    {
+                        "type": "tool_use",
+                        "id": call.call_id,
+                        "name": call.name,
+                        "input": json.loads(call.arguments),
+                    }
+                    for call in message.tool_calls
+                )
+                result.append({"role": "assistant", "content": content})
+            elif message.role == "tool":
+                result.append(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "type": "tool_result",
+                                "tool_use_id": message.tool_call_id,
+                                "content": message.content,
+                                "is_error": message.content.startswith("[tool error]"),
+                            }
+                        ],
+                    }
+                )
+            else:
+                result.append({"role": "user", "content": message.content})
+        return result
+
+    @staticmethod
+    def _finish_reason(value: Any) -> FinishReason | None:
+        return {
+            "end_turn": FinishReason.STOP,
+            "stop_sequence": FinishReason.STOP,
+            "tool_use": FinishReason.TOOL_CALLS,
+            "max_tokens": FinishReason.LENGTH,
+            "refusal": FinishReason.CONTENT_FILTER,
+        }.get(value)

nextloop/adapters/memory.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+from collections import defaultdict
+from collections.abc import Sequence
+
+from ..contracts import (
+    Event,
+    InvariantViolation,
+    NewEvent,
+    SurfaceOp,
+    utc_now,
+)
+
+
+class InMemoryEventStore:
+    def __init__(self) -> None:
+        self._events: dict[str, list[Event]] = defaultdict(list)
+        self._epochs: dict[str, int] = defaultdict(int)
+        self._lock = asyncio.Lock()
+
+    async def attach_writer(self, session_id: str) -> tuple[int, int, int]:
+        async with self._lock:
+            self._epochs[session_id] += 1
+            events = self._events[session_id]
+            last_turn = max((event.turn for event in events), default=0)
+            return self._epochs[session_id], len(events), last_turn
+
+    async def append(
+        self,
+        session_id: str,
+        writer_epoch: int,
+        expected_seq: int,
+        events: Sequence[NewEvent],
+    ) -> Sequence[Event]:
+        async with self._lock:
+            if self._epochs[session_id] != writer_epoch:
+                raise InvariantViolation("Stale writer_epoch")
+            existing = self._events[session_id]
+            if expected_seq != len(existing) + 1:
+                return self._idempotent(existing, events)
+            committed = []
+            for offset, draft in enumerate(events):
+                event = Event(
+                    session_id=session_id,
+                    seq=expected_seq + offset,
+                    turn=draft.turn,
+                    step=draft.step,
+                    attempt=draft.attempt,
+                    writer_epoch=writer_epoch,
+                    event_id=draft.event_id,
+                    event_type=draft.event_type,
+                    surface_op=draft.surface_op,
+                    payload=copy.deepcopy(dict(draft.payload)),
+                    occurred_at=utc_now(),
+                )
+                existing.append(event)
+                committed.append(event)
+            return committed
+
+    async def load_surface(self, session_id: str) -> Sequence[Event]:
+        async with self._lock:
+            events = self._events[session_id]
+            epoch_seq = max(
+                (event.seq for event in events if event.surface_op == SurfaceOp.EPOCH),
+                default=1,
+            )
+            return tuple(
+                copy.deepcopy(event)
+                for event in events
+                if event.seq >= epoch_seq and event.surface_op != SurfaceOp.NONE
+            )
+
+    async def load_recovery(self, session_id: str) -> Sequence[Event]:
+        async with self._lock:
+            return tuple(copy.deepcopy(self._events[session_id]))
+
+    @staticmethod
+    def _idempotent(existing: list[Event], drafts: Sequence[NewEvent]) -> Sequence[Event]:
+        by_id = {event.event_id: event for event in existing}
+        committed = []
+        for draft in drafts:
+            event = by_id.get(draft.event_id)
+            if event is None:
+                raise InvariantViolation("Expected sequence does not match Session tail")
+            if (
+                event.event_type != draft.event_type
+                or event.turn != draft.turn
+                or event.step != draft.step
+                or event.attempt != draft.attempt
+                or event.surface_op != draft.surface_op
+                or event.payload != dict(draft.payload)
+            ):
+                raise InvariantViolation("Event ID reused with different content")
+            committed.append(event)
+        return committed

nextloop/adapters/openai.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ..contracts import (
+    CandidateRequest,
+    FinishReason,
+    Message,
+    ModelResponse,
+    ModelUsage,
+    ProviderError,
+    ToolCall,
+)
+from ._sse import data_events
+
+
+class OpenAIProvider:
+    def __init__(
+        self,
+        *,
+        model_id: str,
+        base_url: str,
+        api_key: str,
+        default_parameters: Mapping[str, Any] | None = None,
+        timeout_seconds: float = 60.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.model_id = model_id
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.default_parameters = dict(default_parameters or {})
+        self.timeout_seconds = timeout_seconds
+        self.http_client = http_client
+
+    async def complete(
+        self,
+        request: CandidateRequest,
+        *,
+        attempt: int,
+        cancel: asyncio.Event,
+    ) -> ModelResponse:
+        body = {
+            **self.default_parameters,
+            "model": self.model_id,
+            "messages": [self._message(message) for message in request.messages],
+            "stream": True,
+        }
+        if request.tools:
+            body["tools"] = [
+                {
+                    "type": "function",
+                    "function": {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "parameters": dict(tool.parameters),
+                    },
+                }
+                for tool in request.tools
+            ]
+        headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        client = self.http_client or httpx.AsyncClient(timeout=self.timeout_seconds)
+        content_parts: list[str] = []
+        refusal_parts: list[str] = []
+        calls: dict[int, dict[str, str]] = {}
+        finish_reason = FinishReason.STOP
+        usage: ModelUsage | None = None
+        try:
+            async with client.stream(
+                "POST",
+                self._endpoint(),
+                json=body,
+                headers=headers,
+            ) as response:
+                if response.status_code >= 400:
+                    error_body = await response.aread()
+                    error_text = error_body.decode("utf-8", errors="replace")
+                    raise ProviderError(
+                        f"OpenAI HTTP {response.status_code}: {error_text}",
+                        retryable=response.status_code in (408, 409, 429)
+                        or response.status_code >= 500,
+                        code=str(response.status_code),
+                    )
+                async for _event, data in data_events(response):
+                    if cancel.is_set():
+                        return ModelResponse(
+                            content="".join(content_parts),
+                            finish_reason=FinishReason.CANCELLED,
+                        )
+                    if data == "[DONE]":
+                        break
+                    chunk = json.loads(data)
+                    usage = self._usage(chunk.get("usage")) or usage
+                    choices = chunk.get("choices") or []
+                    if not choices:
+                        continue
+                    choice = choices[0]
+                    delta = choice.get("delta") or {}
+                    if delta.get("content"):
+                        content_parts.append(str(delta["content"]))
+                    if delta.get("refusal"):
+                        refusal_parts.append(str(delta["refusal"]))
+                    for fragment in delta.get("tool_calls") or []:
+                        index = int(fragment["index"])
+                        current = calls.setdefault(
+                            index, {"id": f"call_{index}", "name": "", "arguments": ""}
+                        )
+                        if fragment.get("id"):
+                            current["id"] = str(fragment["id"])
+                        function = fragment.get("function") or {}
+                        if function.get("name"):
+                            current["name"] += str(function["name"])
+                        if function.get("arguments"):
+                            current["arguments"] += str(function["arguments"])
+                    finish_reason = (
+                        self._finish_reason(choice.get("finish_reason")) or finish_reason
+                    )
+            return ModelResponse(
+                content="".join(content_parts),
+                refusal="".join(refusal_parts) or None,
+                tool_calls=tuple(
+                    ToolCall(call["id"], call["name"], call["arguments"])
+                    for _, call in sorted(calls.items())
+                ),
+                finish_reason=finish_reason,
+                usage=usage,
+            )
+        except ProviderError:
+            raise
+        except (TimeoutError, httpx.HTTPError, json.JSONDecodeError) as exc:
+            partial = bool(content_parts or refusal_parts or calls)
+            raise ProviderError(
+                f"OpenAI stream failed: {exc}",
+                retryable=True,
+                partial_output=partial,
+            ) from exc
+        finally:
+            if self.http_client is None:
+                await client.aclose()
+
+    def _endpoint(self) -> str:
+        if self.base_url.endswith("/chat/completions"):
+            return self.base_url
+        return self.base_url + "/chat/completions"
+
+    @staticmethod
+    def _message(message: Message) -> dict[str, Any]:
+        if message.role == "tool":
+            return {
+                "role": "tool",
+                "tool_call_id": message.tool_call_id,
+                "content": message.content,
+            }
+        value: dict[str, Any] = {"role": message.role, "content": message.content or None}
+        if message.tool_calls:
+            value["tool_calls"] = [
+                {
+                    "id": call.call_id,
+                    "type": "function",
+                    "function": {"name": call.name, "arguments": call.arguments},
+                }
+                for call in message.tool_calls
+            ]
+        return value
+
+    @staticmethod
+    def _finish_reason(value: Any) -> FinishReason | None:
+        return {
+            "stop": FinishReason.STOP,
+            "tool_calls": FinishReason.TOOL_CALLS,
+            "length": FinishReason.LENGTH,
+            "content_filter": FinishReason.CONTENT_FILTER,
+        }.get(value)
+
+    @staticmethod
+    def _usage(value: Any) -> ModelUsage | None:
+        if not isinstance(value, Mapping):
+            return None
+        details = value.get("prompt_tokens_details") or {}
+        return ModelUsage(
+            input_tokens=value.get("prompt_tokens"),
+            output_tokens=value.get("completion_tokens"),
+            cached_input_tokens=details.get("cached_tokens"),
+        )