driangle-agentrunner 0.0.1__py3-none-any.whl

agentrunner/claudecode/types.py

@@ -0,0 +1,131 @@
+"""Types for Claude Code CLI stream-json output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ContentBlock:
+    """One block inside an assistant message."""
+
+    type: str = ""
+    text: str | None = None
+    thinking: str | None = None
+    name: str | None = None
+    input: Any = None
+    content: Any = None
+
+
+@dataclass
+class StreamUsage:
+    """Token counts from streaming events."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+
+@dataclass
+class ResultUsage:
+    """Token counts from the final result message (includes cache fields)."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+
+
+@dataclass
+class Delta:
+    """Incremental data in delta events."""
+
+    type: str | None = None
+    text: str | None = None
+    thinking: str | None = None
+    partial_json: str | None = None
+    stop_reason: str | None = None
+    stop_sequence: str | None = None
+
+
+@dataclass
+class ContentBlockInfo:
+    """Content block info in content_block_start events."""
+
+    type: str = ""
+    name: str | None = None
+    id: str | None = None
+
+
+@dataclass
+class MessageStartData:
+    """Message metadata from a message_start event."""
+
+    model: str = ""
+    id: str = ""
+    usage: StreamUsage | None = None
+
+
+@dataclass
+class StreamEventInner:
+    """Parsed inner event from a stream_event line."""
+
+    type: str = ""
+    message: MessageStartData | None = None
+    index: int | None = None
+    content_block: ContentBlockInfo | None = None
+    delta: Delta | None = None
+    usage: StreamUsage | None = None
+
+
+@dataclass
+class RateLimitInfo:
+    """Rate limit details from rate_limit_event messages."""
+
+    status: str = ""
+    rate_limit_type: str | None = None
+    utilization: float | None = None
+    resets_at: float | None = None
+    is_using_overage: bool | None = None
+
+
+@dataclass
+class AssistantMessage:
+    """Nested 'message' object inside assistant-type stream lines."""
+
+    model: str | None = None
+    id: str | None = None
+    content: list[ContentBlock] = field(default_factory=list)
+    stop_reason: str | None = None
+    usage: StreamUsage | None = None
+
+
+@dataclass
+class StreamMessage:
+    """Top-level envelope for all Claude stream-json lines."""
+
+    type: str = ""
+    subtype: str | None = None
+    content: list[ContentBlock] = field(default_factory=list)
+    message: AssistantMessage | None = None
+
+    # Result fields.
+    result: str | None = None
+    is_error: bool | None = None
+    total_cost_usd: float | None = None
+    duration_ms: float | None = None
+    duration_api_ms: float | None = None
+    num_turns: int | None = None
+    session_id: str | None = None
+    model: str | None = None
+    usage: ResultUsage | None = None
+
+    # System/init fields.
+    tools: list[Any] | None = None
+
+    # Rate limit info.
+    rate_limit_info: RateLimitInfo | None = None
+
+    # Stream event fields.
+    event: StreamEventInner | None = None
+    parent_tool_use_id: str | None = None

agentrunner/claudecode/version.py

@@ -0,0 +1,47 @@
+"""CLI version detection and compatibility check."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+
+from ..errors import NotFoundError
+
+# Supported Claude Code CLI version range.
+MIN_VERSION = "1.0.12"
+
+_VERSION_RE = re.compile(r"(\d+\.\d+\.\d+)")
+
+
+def _parse_version(version_str: str) -> tuple[int, ...]:
+    """Parse a semver string into a comparable tuple."""
+    return tuple(int(p) for p in version_str.split("."))
+
+
+async def check_version(binary: str) -> str:
+    """Run ``<binary> --version`` and verify it meets the minimum requirement.
+
+    Returns the detected version string.
+    Raises ``NotFoundError`` if the binary is missing or the version is too old.
+    """
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            binary,
+            "--version",
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+    except FileNotFoundError:
+        raise NotFoundError(f"{binary}: command not found")
+
+    output = stdout.decode("utf-8", errors="replace").strip()
+    match = _VERSION_RE.search(output)
+    if not match:
+        raise NotFoundError(f"could not parse version from `{binary} --version`: {output!r}")
+
+    version = match.group(1)
+    if _parse_version(version) < _parse_version(MIN_VERSION):
+        raise NotFoundError(f"{binary} version {version} is below minimum supported {MIN_VERSION}")
+
+    return version

agentrunner/errors.py

@@ -0,0 +1,36 @@
+"""Exception hierarchy for runner errors."""
+
+
+class RunnerError(Exception):
+    """Base class for all runner errors."""
+
+
+class NotFoundError(RunnerError):
+    """Runner binary or API endpoint is not reachable."""
+
+
+class TimeoutError(RunnerError):
+    """Execution exceeded the configured timeout."""
+
+
+class NonZeroExitError(RunnerError):
+    """CLI process exited with a non-zero code."""
+
+    def __init__(self, exit_code: int, message: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class ParseError(RunnerError):
+    """Failed to parse runner output."""
+
+
+class CancelledError(RunnerError):
+    """Execution was cancelled by the caller."""
+
+
+class NoResultError(RunnerError):
+    """Stream ended without a result message."""
+
+    def __init__(self) -> None:
+        super().__init__("no result in output")

agentrunner/ollama/__init__.py

@@ -0,0 +1,14 @@
+"""Ollama runner — talks to the Ollama HTTP API for local model inference."""
+
+from .accessors import message_text, message_thinking
+from .options import OllamaRunnerConfig, OllamaRunOptions
+from .runner import OllamaRunner, OllamaSession
+
+__all__ = [
+    "OllamaRunner",
+    "OllamaRunOptions",
+    "OllamaRunnerConfig",
+    "OllamaSession",
+    "message_text",
+    "message_thinking",
+]

agentrunner/ollama/accessors.py

@@ -0,0 +1,22 @@
+"""Typed accessor functions for Ollama messages."""
+
+from __future__ import annotations
+
+from ..types import Message
+
+
+def message_text(msg: Message) -> str | None:
+    """Return the text content from an assistant or result message, or None."""
+    d = msg._raw_dict()
+    message = d.get("message", {})
+    content = message.get("content")
+    if content:
+        return content
+    return None
+
+
+def message_thinking(msg: Message) -> str | None:
+    """Return the thinking content from a message, or None."""
+    d = msg._raw_dict()
+    message = d.get("message", {})
+    return message.get("thinking") or None

agentrunner/ollama/options.py

@@ -0,0 +1,41 @@
+"""Ollama runner configuration and run options."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ..types import RunOptions
+
+
+@runtime_checkable
+class Logger(Protocol):
+    """Minimal logger interface (matches stdlib logging.Logger)."""
+
+    def debug(self, msg: str, *args: Any, **kwargs: Any) -> None: ...
+    def error(self, msg: str, *args: Any, **kwargs: Any) -> None: ...
+
+
+@dataclass
+class OllamaRunnerConfig:
+    """Configuration for creating an Ollama runner."""
+
+    base_url: str = "http://localhost:11434"
+    logger: Logger | None = None
+
+
+@dataclass
+class OllamaRunOptions(RunOptions):
+    """Ollama-specific options extending common RunOptions."""
+
+    temperature: float | None = None
+    num_ctx: int | None = None
+    num_predict: int | None = None
+    seed: int | None = None
+    stop: list[str] | None = field(default=None)
+    top_k: int | None = None
+    top_p: float | None = None
+    min_p: float | None = None
+    format: str | None = None
+    keep_alive: str | None = None
+    think: bool | None = None

agentrunner/ollama/runner.py

@@ -0,0 +1,327 @@
+"""Ollama runner implementation using the Ollama HTTP API."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from http import HTTPStatus
+from typing import Any
+
+from ..errors import (
+    CancelledError,
+    NoResultError,
+    NotFoundError,
+    ParseError,
+    RunnerError,
+    TimeoutError,
+)
+from ..types import Message, Result, Usage
+from .options import OllamaRunnerConfig, OllamaRunOptions
+from .types import ChatResponse, ModelOptions
+
+DEFAULT_BASE_URL = "http://localhost:11434"
+
+
+class OllamaSession:
+    """Session encapsulates a running Ollama API request.
+
+    Supports ``async for msg in session`` to iterate messages,
+    and ``await session.result`` to get the final result.
+    """
+
+    def __init__(
+        self,
+        config: OllamaRunnerConfig,
+        prompt: str,
+        options: OllamaRunOptions,
+    ) -> None:
+        self._config = config
+        self._prompt = prompt
+        self._options = options
+
+        self._loop = asyncio.get_running_loop()
+        self._queue: asyncio.Queue[Message | None] = asyncio.Queue()
+        self._result_future: asyncio.Future[Result] = self._loop.create_future()
+        self._aborted = False
+        self._task: asyncio.Task[None] = asyncio.ensure_future(self._run_request())
+
+    async def _run_request(self) -> None:
+        try:
+            base_url = self._config.base_url or DEFAULT_BASE_URL
+            body = _build_request_body(self._prompt, self._options)
+
+            if self._config.logger:
+                self._config.logger.debug(
+                    "executing Ollama API request",
+                    extra={"method": "POST", "url": f"{base_url}/api/chat"},
+                )
+
+            reader, writer = await _http_post_stream(
+                base_url, "/api/chat", json.dumps(body)
+            )
+
+            text_parts: list[str] = []
+            final_resp: ChatResponse | None = None
+
+            try:
+                while True:
+                    if self._aborted:
+                        break
+
+                    raw_line = await reader.readline()
+                    if not raw_line:
+                        break
+
+                    line = raw_line.decode("utf-8", errors="replace").strip()
+                    if not line:
+                        continue
+
+                    try:
+                        chunk = ChatResponse.from_dict(json.loads(line))
+                    except (json.JSONDecodeError, KeyError) as exc:
+                        raise ParseError(f"invalid JSON: {line}") from exc
+
+                    if chunk.message.content:
+                        text_parts.append(chunk.message.content)
+
+                    if chunk.done:
+                        final_resp = chunk
+
+                    msg = Message(
+                        type="result" if chunk.done else "assistant",
+                        raw=line,
+                    )
+                    await self._queue.put(msg)
+            finally:
+                writer.close()
+                try:
+                    await writer.wait_closed()
+                except Exception:
+                    pass
+
+            if self._aborted:
+                self._result_future.set_exception(CancelledError("execution cancelled"))
+                return
+
+            if not final_resp:
+                self._result_future.set_exception(NoResultError())
+                return
+
+            usage = Usage(
+                input_tokens=final_resp.prompt_eval_count or 0,
+                output_tokens=final_resp.eval_count or 0,
+            )
+
+            self._result_future.set_result(
+                Result(
+                    text="".join(text_parts),
+                    is_error=False,
+                    exit_code=0,
+                    usage=usage,
+                    cost_usd=0.0,
+                    duration_ms=(
+                        final_resp.total_duration / 1e6
+                        if final_resp.total_duration
+                        else 0.0
+                    ),
+                    session_id="",
+                )
+            )
+        except (CancelledError, TimeoutError, NotFoundError, ParseError, NoResultError):
+            if not self._result_future.done():
+                self._result_future.set_exception(
+                    __import__("sys").exc_info()[1]  # type: ignore[arg-type]
+                )
+        except OSError as exc:
+            err = NotFoundError(f"connection failed: {exc}")
+            if not self._result_future.done():
+                self._result_future.set_exception(err)
+        except Exception as exc:
+            if not self._result_future.done():
+                self._result_future.set_exception(RunnerError(str(exc)))
+        finally:
+            await self._queue.put(None)
+
+    def __aiter__(self) -> AsyncIterator[Message]:
+        return self._message_iter()
+
+    async def _message_iter(self) -> AsyncIterator[Message]:
+        while True:
+            msg = await self._queue.get()
+            if msg is None:
+                break
+            yield msg
+
+    @property
+    def result(self) -> asyncio.Future[Result]:
+        return self._result_future
+
+    def abort(self) -> None:
+        self._aborted = True
+
+    def send(self, input: Any) -> None:
+        raise NotImplementedError("send is not supported for Ollama runner")
+
+
+class OllamaRunner:
+    """Ollama runner — talks to the Ollama HTTP API.
+
+    Construct directly::
+
+        runner = OllamaRunner()
+        runner = OllamaRunner(config=OllamaRunnerConfig(base_url="http://...", logger=logger))
+    """
+
+    def __init__(self, config: OllamaRunnerConfig | None = None) -> None:
+        self._config = config or OllamaRunnerConfig()
+
+    def start(
+        self,
+        prompt: str,
+        options: OllamaRunOptions | None = None,
+    ) -> OllamaSession:
+        opts = options or OllamaRunOptions()
+        if not opts.model:
+            raise RunnerError("model is required for Ollama runner")
+
+        timeout = opts.timeout
+        session = OllamaSession(self._config, prompt, opts)
+
+        if timeout is not None and timeout > 0:
+            loop = asyncio.get_running_loop()
+            loop.call_later(timeout, session.abort)
+
+        return session
+
+    async def run(
+        self,
+        prompt: str,
+        options: OllamaRunOptions | None = None,
+    ) -> Result:
+        session = self.start(prompt, options)
+        async for _msg in session:
+            pass
+        return await session.result
+
+    async def run_stream(
+        self,
+        prompt: str,
+        options: OllamaRunOptions | None = None,
+    ) -> OllamaSession:
+        return self.start(prompt, options)
+
+
+async def _http_post_stream(
+    base_url: str, path: str, body: str
+) -> tuple[asyncio.StreamReader, asyncio.StreamWriter]:
+    """Open a raw HTTP POST connection and return the response body stream.
+
+    Uses asyncio streams directly to avoid external dependencies.
+    Raises NotFoundError on connection failure or HTTP 404.
+    """
+    from urllib.parse import urlparse
+
+    parsed = urlparse(base_url)
+    host = parsed.hostname or "localhost"
+    port = parsed.port or 80
+    use_ssl = parsed.scheme == "https"
+
+    try:
+        if use_ssl:
+            import ssl
+
+            ctx = ssl.create_default_context()
+            reader, writer = await asyncio.open_connection(host, port, ssl=ctx)
+        else:
+            reader, writer = await asyncio.open_connection(host, port)
+    except OSError as exc:
+        raise NotFoundError(f"connection failed: {exc}") from exc
+
+    # Send HTTP request.
+    body_bytes = body.encode("utf-8")
+    request_lines = (
+        f"POST {path} HTTP/1.1\r\n"
+        f"Host: {host}:{port}\r\n"
+        f"Content-Type: application/json\r\n"
+        f"Content-Length: {len(body_bytes)}\r\n"
+        f"Connection: close\r\n"
+        f"\r\n"
+    )
+    writer.write(request_lines.encode("utf-8"))
+    writer.write(body_bytes)
+    await writer.drain()
+
+    # Read status line.
+    status_line = await reader.readline()
+    status_str = status_line.decode("utf-8", errors="replace").strip()
+    parts = status_str.split(" ", 2)
+    if len(parts) < 2:
+        raise NotFoundError(f"invalid HTTP response: {status_str}")
+
+    status_code = int(parts[1])
+
+    # Read headers (discard them, we just need the body stream).
+    while True:
+        header_line = await reader.readline()
+        if header_line in (b"\r\n", b"\n", b""):
+            break
+
+    if status_code == HTTPStatus.NOT_FOUND:
+        raise NotFoundError("model not found (HTTP 404)")
+    if status_code >= 400:
+        raise RunnerError(f"HTTP {status_code}")
+
+    return reader, writer
+
+
+def _build_request_body(prompt: str, options: OllamaRunOptions) -> dict[str, Any]:
+    """Build the JSON request body for POST /api/chat."""
+    messages: list[dict[str, str]] = []
+
+    system_prompt = options.system_prompt or ""
+    if options.append_system_prompt:
+        if system_prompt:
+            system_prompt += "\n" + options.append_system_prompt
+        else:
+            system_prompt = options.append_system_prompt
+
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+
+    messages.append({"role": "user", "content": prompt})
+
+    body: dict[str, Any] = {
+        "model": options.model,
+        "messages": messages,
+        "stream": True,
+    }
+
+    if options.think is not None:
+        body["think"] = options.think
+    if options.format:
+        body["format"] = options.format
+    if options.keep_alive:
+        body["keep_alive"] = options.keep_alive
+
+    model_opts = _build_model_options(options)
+    if model_opts:
+        body["options"] = model_opts
+
+    return body
+
+
+def _build_model_options(options: OllamaRunOptions) -> dict[str, Any] | None:
+    """Build the model options dict, or None if no options are set."""
+    opts = ModelOptions(
+        temperature=options.temperature,
+        num_ctx=options.num_ctx,
+        num_predict=options.num_predict,
+        seed=options.seed,
+        stop=options.stop,
+        top_k=options.top_k,
+        top_p=options.top_p,
+        min_p=options.min_p,
+    )
+    d = opts.to_dict()
+    return d if d else None