base-agentkit 0.1.0__py3-none-any.whl

agentkit/llm/providers/qwen_provider.py

@@ -0,0 +1,34 @@
+"""Qwen provider via OpenAI-compatible Chat Completions API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentkit.config.schema import ProviderConfig
+from agentkit.llm.providers.openai_provider import OpenAIProvider
+from agentkit.llm.types import UnifiedLLMRequest, UnifiedLLMResponse
+
+
+class QwenProvider(OpenAIProvider):
+    """Qwen adapter using OpenAI-compatible chat.completions."""
+
+    def __init__(self, config: ProviderConfig) -> None:
+        super().__init__(config)
+
+    def generate(self, req: UnifiedLLMRequest) -> UnifiedLLMResponse:
+        response = super().generate(req)
+        response.provider_name = "qwen"
+        return response
+
+    def _extra_chat_kwargs(self, req: UnifiedLLMRequest) -> dict[str, Any]:
+        thinking_enabled = req.options.thinking_enabled
+        if thinking_enabled is None:
+            thinking_enabled = self.config.enable_thinking
+
+        extra_body: dict[str, Any] = {
+            "enable_thinking": bool(thinking_enabled),
+        }
+        if self.config.thinking_budget is not None:
+            extra_body["thinking_budget"] = self.config.thinking_budget
+
+        return {"extra_body": extra_body}

agentkit/llm/providers/vllm_provider.py

@@ -0,0 +1,47 @@
+"""vLLM OpenAI-compatible provider."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+from agentkit.config.provider_defaults import is_localhost_base_url
+from agentkit.config.schema import ProviderConfig
+from agentkit.llm.providers.openai_provider import OpenAIProvider
+from agentkit.llm.types import UnifiedLLMRequest, UnifiedLLMResponse
+
+_LOCAL_VLLM_CLIENT_API_KEY = "empty"
+
+
+class VLLMProvider(OpenAIProvider):
+    """OpenAI chat-compatible adapter with vLLM-specific request flags."""
+
+    def __init__(self, config: ProviderConfig) -> None:
+        client_config = replace(config)
+        if client_config.api_key is None and is_localhost_base_url(
+            client_config.base_url
+        ):
+            client_config.api_key = _LOCAL_VLLM_CLIENT_API_KEY
+        super().__init__(client_config)
+        self.config = config
+
+    def generate(self, req: UnifiedLLMRequest) -> UnifiedLLMResponse:
+        response = super().generate(req)
+        response.provider_name = "vllm"
+        return response
+
+    def _allow_reasoning_effort(self) -> bool:
+        # vLLM's OpenAI-compatible server does not support reasoning_effort.
+        return False
+
+    def _extra_chat_kwargs(self, req: UnifiedLLMRequest) -> dict[str, Any]:
+        thinking_enabled = req.options.thinking_enabled
+        if thinking_enabled is None:
+            thinking_enabled = self.config.enable_thinking
+        return {
+            "extra_body": {
+                "chat_template_kwargs": {
+                    "enable_thinking": bool(thinking_enabled),
+                }
+            }
+        }

agentkit/llm/types.py

@@ -0,0 +1,215 @@
+"""Unified provider-agnostic LLM request/response and conversation types."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+ProviderKind = Literal["openai", "anthropic", "gemini", "vllm", "qwen"]
+ConversationMode = Literal["auto", "client", "server"]
+
+TurnStatus = Literal["completed", "requires_tool", "incomplete", "blocked", "failed"]
+CompletionReason = Literal[
+    "stop",
+    "tool_call",
+    "max_tokens",
+    "content_filter",
+    "refusal",
+    "pause",
+    "context_window",
+    "error",
+    "unknown",
+]
+
+
+@dataclass(slots=True)
+class MessageItem:
+    """Plain-text message stored in unified conversation history.
+
+    Attributes:
+        role: Logical speaker for the message.
+        text: Provider-normalized text payload.
+    """
+
+    role: Literal["user", "assistant"]
+    text: str
+
+
+@dataclass(slots=True)
+class ToolCallItem:
+    """Structured tool request emitted by a provider.
+
+    Attributes:
+        call_id: Stable identifier used to match the eventual tool result.
+        name: Registered tool name to execute.
+        arguments: Parsed arguments when the provider returned valid JSON.
+        raw_arguments: Original serialized arguments, preserved for replay fidelity.
+    """
+
+    call_id: str
+    name: str
+    arguments: dict[str, Any]
+    raw_arguments: str | None = None
+
+
+@dataclass(slots=True)
+class ToolResultItem:
+    """Tool execution result appended back into conversation history.
+
+    Attributes:
+        call_id: Identifier of the tool call this result satisfies.
+        tool_name: Tool name, retained for providers that require it on replay.
+        payload: Model-facing success or error payload.
+        is_error: Whether the tool execution failed.
+    """
+
+    call_id: str
+    tool_name: str | None = None
+    payload: Any = field(default_factory=dict)
+    is_error: bool = False
+
+    @property
+    def output_text(self) -> str:
+        """Return the payload as text for providers that require string content."""
+        if isinstance(self.payload, str):
+            return self.payload
+        return json.dumps(self.payload, ensure_ascii=False)
+
+
+@dataclass(slots=True)
+class ReasoningItem:
+    """Provider reasoning artifact captured separately from assistant text.
+
+    Attributes:
+        text: Full reasoning text when the provider exposes it.
+        summary: Shorter reasoning summary when full text is unavailable.
+        raw_item: Original provider payload used for transcript replay.
+        replay_hint: Whether the raw payload should be sent back on future turns.
+    """
+
+    text: str | None
+    summary: str | None = None
+    raw_item: dict[str, Any] | None = None
+    replay_hint: bool = True
+
+
+ConversationItem = MessageItem | ToolCallItem | ToolResultItem | ReasoningItem
+
+
+@dataclass(slots=True)
+class ConversationState:
+    """Mutable provider conversation state carried across turns.
+
+    Attributes:
+        mode: Whether conversation state is managed by the client or provider.
+        history: Canonical transcript items that have already been committed.
+        provider_cursor: Provider-issued cursor or response id for server-side state.
+        provider_meta: Provider-specific metadata needed to continue a session.
+    """
+
+    mode: ConversationMode = "auto"
+    history: list[ConversationItem] = field(default_factory=list)
+    provider_cursor: str | None = None
+    provider_meta: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class UnifiedToolSpec:
+    """Model-facing description of one callable tool."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+
+@dataclass(slots=True)
+class GenerationOptions:
+    """Per-request generation knobs after config defaults are applied."""
+
+    temperature: float | None = None
+    max_output_tokens: int | None = None
+    stop_sequences: list[str] | None = None
+    thinking_enabled: bool | None = None
+    reasoning_effort: str | None = None
+
+
+@dataclass(slots=True)
+class UnifiedLLMRequest:
+    """Provider-agnostic request assembled for one model turn.
+
+    Attributes:
+        provider: Selected provider backend.
+        model: Provider model identifier.
+        state: Conversation state from previous turns.
+        inputs: New conversation items to append for this turn.
+        instructions: System-level instructions for the turn.
+        tools: Tool schemas exposed to the provider.
+        options: Request-level generation overrides.
+    """
+
+    provider: ProviderKind
+    model: str
+    state: ConversationState
+    inputs: list[ConversationItem]
+    instructions: str
+    tools: list[UnifiedToolSpec]
+    options: GenerationOptions
+
+
+@dataclass(slots=True)
+class Usage:
+    """Normalized token accounting returned by providers."""
+
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    total_tokens: int | None = None
+    reasoning_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    raw: dict[str, Any] | None = None
+
+
+@dataclass(slots=True)
+class StatePatch:
+    """Incremental provider-state update returned after a model turn."""
+
+    new_provider_cursor: str | None = None
+    provider_meta_patch: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class UnifiedLLMResponse:
+    """Provider-agnostic response produced for one model turn.
+
+    Attributes:
+        response_id: Provider response identifier when available.
+        status: High-level turn status used by the agent loop.
+        reason: Normalized completion reason.
+        output_items: Canonical output items emitted by the provider.
+        output_text: Human-facing assistant text synthesized from ``output_items``.
+        usage: Normalized token usage information.
+        state_patch: Provider-state updates to apply after committing the turn.
+        provider_name: Provider that produced the response.
+        raw_response: Original provider payload for debugging and replay support.
+    """
+
+    response_id: str | None
+    status: TurnStatus
+    reason: CompletionReason
+    output_items: list[ConversationItem]
+    output_text: str
+    usage: Usage
+    state_patch: StatePatch
+    provider_name: ProviderKind
+    raw_response: dict[str, Any] | None = None
+
+    @property
+    def tool_calls(self) -> list[ToolCallItem]:
+        """Return only tool calls from ``output_items`` for the agent loop."""
+        return [item for item in self.output_items if isinstance(item, ToolCallItem)]
+
+    @property
+    def has_tool_calls(self) -> bool:
+        """Report whether the provider requested at least one tool execution."""
+        return any(isinstance(item, ToolCallItem) for item in self.output_items)

agentkit/llm/usage.py

@@ -0,0 +1,72 @@
+"""Helpers for working with provider usage accounting."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from agentkit.llm.types import Usage
+
+
+def merge_usage(total: Usage, delta: Usage) -> None:
+    """Accumulate one usage snapshot into another in place."""
+
+    total.input_tokens = _sum_optional_int(total.input_tokens, delta.input_tokens)
+    total.output_tokens = _sum_optional_int(total.output_tokens, delta.output_tokens)
+    total.reasoning_tokens = _sum_optional_int(
+        total.reasoning_tokens, delta.reasoning_tokens
+    )
+    total.cache_read_tokens = _sum_optional_int(
+        total.cache_read_tokens, delta.cache_read_tokens
+    )
+    total.cache_write_tokens = _sum_optional_int(
+        total.cache_write_tokens, delta.cache_write_tokens
+    )
+
+    delta_total = delta.total_tokens
+    if delta_total is None and delta.input_tokens is not None and delta.output_tokens is not None:
+        delta_total = delta.input_tokens + delta.output_tokens
+    total.total_tokens = _sum_optional_int(total.total_tokens, delta_total)
+    total.raw = None
+
+
+def usage_to_payload(usage: Usage) -> dict[str, int | None]:
+    """Serialize usage into the run-log friendly payload shape."""
+    return {
+        "input_tokens": usage.input_tokens,
+        "output_tokens": usage.output_tokens,
+        "total_tokens": usage.total_tokens,
+        "reasoning_tokens": usage.reasoning_tokens,
+        "cache_read_tokens": usage.cache_read_tokens,
+        "cache_write_tokens": usage.cache_write_tokens,
+    }
+
+
+def usage_from_payload(payload: Mapping[str, Any]) -> Usage:
+    """Rebuild a :class:`Usage` object from serialized run-log data."""
+    return Usage(
+        input_tokens=_optional_int(payload.get("input_tokens")),
+        output_tokens=_optional_int(payload.get("output_tokens")),
+        total_tokens=_optional_int(payload.get("total_tokens")),
+        reasoning_tokens=_optional_int(payload.get("reasoning_tokens")),
+        cache_read_tokens=_optional_int(payload.get("cache_read_tokens")),
+        cache_write_tokens=_optional_int(payload.get("cache_write_tokens")),
+    )
+
+
+def _sum_optional_int(current: int | None, delta: int | None) -> int | None:
+    """Add two optional counters while preserving ``None`` as unknown."""
+    if delta is None:
+        return current
+    if current is None:
+        return delta
+    return current + delta
+
+
+def _optional_int(value: Any) -> int | None:
+    """Best-effort convert provider payload values into integers."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

agentkit/runlog/__init__.py

@@ -0,0 +1,15 @@
+"""Canonical run event recording primitives."""
+
+from .events import RUN_EVENT_SCHEMA, RunEvent, RunEventKind
+from .jsonl import JsonlRunLogSink
+from .recorder import RunRecorder
+from .sinks import RunEventSink
+
+__all__ = [
+    "JsonlRunLogSink",
+    "RUN_EVENT_SCHEMA",
+    "RunEvent",
+    "RunEventKind",
+    "RunEventSink",
+    "RunRecorder",
+]

agentkit/runlog/events.py

@@ -0,0 +1,67 @@
+"""Run event schema shared by reporting and run log projections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+RUN_EVENT_SCHEMA = "agentkit.run_event.v3"
+
+RunEventKind = Literal[
+    "run_started",
+    "model_responded",
+    "tool_executed",
+    "run_finished",
+]
+
+
+def _utc_now() -> str:
+    """Return the current UTC timestamp in ISO-8601 form."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass(slots=True)
+class RunEvent:
+    """Canonical runtime event emitted by :class:`agentkit.runlog.RunRecorder`."""
+
+    schema: str
+    seq: int
+    ts: str
+    run_id: str
+    kind: RunEventKind
+    step: int | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        seq: int,
+        run_id: str,
+        kind: RunEventKind,
+        step: int | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> "RunEvent":
+        """Create a run event with the canonical schema version and timestamp."""
+        return cls(
+            schema=RUN_EVENT_SCHEMA,
+            seq=seq,
+            ts=_utc_now(),
+            run_id=run_id,
+            kind=kind,
+            step=step,
+            payload=payload or {},
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the event for sinks that need plain dictionaries."""
+        return {
+            "schema": self.schema,
+            "seq": self.seq,
+            "ts": self.ts,
+            "run_id": self.run_id,
+            "kind": self.kind,
+            "step": self.step,
+            "payload": self.payload,
+        }

agentkit/runlog/jsonl.py

@@ -0,0 +1,90 @@
+"""JSONL run log sink with basic redaction."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from agentkit.config.schema import RunLogConfig
+from agentkit.constants import DEFAULT_RUNLOG_PATH, SENSITIVE_KEYS
+from agentkit.runlog.events import RunEvent
+from agentkit.workspace.fs import WorkspaceFS
+
+
+class JsonlRunLogSink:
+    """Write canonical run events to JSONL with optional redaction."""
+
+    def __init__(self, fs: WorkspaceFS, config: RunLogConfig) -> None:
+        """Prepare the sink and ensure the run-log directory exists."""
+        self._enabled = config.enabled
+        self._redact = config.redact
+        self._max_text_chars = config.max_text_chars
+        self._default_path: Path = fs.resolve_path(DEFAULT_RUNLOG_PATH)
+        self._default_path.parent.mkdir(parents=True, exist_ok=True)
+        self._current_path: Path | None = None
+        self._current_run_id: str | None = None
+
+    @property
+    def enabled(self) -> bool:
+        """Return whether this sink should persist events to disk."""
+        return self._enabled
+
+    @property
+    def current_run_id(self) -> str | None:
+        """Return the run id currently being written, if any."""
+        return self._current_run_id
+
+    @property
+    def current_runlog_path(self) -> Path:
+        """Return the active run-log path, or the default path before a run starts."""
+        return self._current_path or self._default_path
+
+    def runlog_path_for_run(self, run_id: str) -> Path:
+        """Return the per-run JSONL path for a given run id."""
+        return self._default_path.parent / f"run_{run_id}.jsonl"
+
+    def consume(self, event: RunEvent) -> None:
+        """Persist one event, applying redaction and truncation when enabled."""
+        if event.kind == "run_started":
+            self._current_run_id = event.run_id
+            self._current_path = self.runlog_path_for_run(event.run_id)
+
+        if not self._enabled:
+            if event.kind == "run_finished":
+                self._current_run_id = None
+                self._current_path = None
+            return
+
+        payload: dict[str, Any] = event.to_dict()
+        if self._redact:
+            # Redact before truncation so secrets are never partially preserved in
+            # the run log, even when a long string would be shortened.
+            payload = self._sanitize(payload)
+
+        target_path = self._current_path or self.runlog_path_for_run(event.run_id)
+        with target_path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+        if event.kind == "run_finished":
+            self._current_run_id = None
+            self._current_path = None
+
+    def _sanitize(self, obj: Any, *, key_hint: str = "") -> Any:
+        """Recursively redact sensitive keys and cap very large text fields."""
+        if isinstance(obj, dict):
+            out: dict[str, Any] = {}
+            for key, value in obj.items():
+                lowered = key.lower()
+                if any(token in lowered for token in SENSITIVE_KEYS):
+                    out[key] = "***REDACTED***"
+                else:
+                    out[key] = self._sanitize(value, key_hint=key)
+            return out
+        if isinstance(obj, list):
+            return [self._sanitize(item, key_hint=key_hint) for item in obj]
+        if isinstance(obj, str):
+            if len(obj) > self._max_text_chars:
+                return obj[: self._max_text_chars] + "...<truncated>"
+            return obj
+        return obj

agentkit/runlog/recorder.py

@@ -0,0 +1,94 @@
+"""Run-scoped canonical event recorder."""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable, Sequence
+from datetime import datetime, timezone
+from typing import Any
+
+from agentkit.runlog.events import RunEvent, RunEventKind
+from agentkit.runlog.sinks import RunEventSink
+
+
+class RunRecorder:
+    """Emit canonical run events to one or more sinks."""
+
+    def __init__(
+        self,
+        sinks: Sequence[RunEventSink],
+        *,
+        run_id_factory: Callable[[], str] | None = None,
+    ) -> None:
+        """Create a recorder that multicasts canonical events to configured sinks."""
+        self._sinks = list(sinks)
+        self._run_id_factory = run_id_factory or _build_run_id
+        self._current_run_id: str | None = None
+        self._seq = 0
+
+    @property
+    def current_run_id(self) -> str | None:
+        """Return the active run id, or ``None`` when no run is open."""
+        return self._current_run_id
+
+    def start_run(
+        self,
+        *,
+        task: str = "",
+        context: dict[str, Any] | None = None,
+    ) -> str:
+        """Open a new run and emit the initial ``run_started`` event."""
+        if self._current_run_id is not None:
+            raise RuntimeError("A run is already active.")
+
+        run_id = self._run_id_factory()
+        self._current_run_id = run_id
+        self._seq = 0
+
+        self.emit(
+            "run_started",
+            payload={
+                "task": task,
+                "context": dict(context or {}),
+            },
+        )
+        return run_id
+
+    def emit(
+        self,
+        kind: RunEventKind,
+        *,
+        step: int | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> RunEvent:
+        """Emit one run event to every sink and return the created event."""
+        if self._current_run_id is None:
+            raise RuntimeError("No active run. Call start_run first.")
+        self._seq += 1
+        event = RunEvent.create(
+            seq=self._seq,
+            run_id=self._current_run_id,
+            kind=kind,
+            step=step,
+            payload=payload,
+        )
+        for sink in self._sinks:
+            sink.consume(event)
+        return event
+
+    def end_run(self, *, status: str, payload: dict[str, Any] | None = None) -> None:
+        """Emit the terminal event for the current run and clear recorder state."""
+        run_payload = dict(payload or {})
+        run_payload["status"] = status
+        self.emit(
+            "run_finished",
+            payload=run_payload,
+        )
+        self._current_run_id = None
+
+
+def _build_run_id() -> str:
+    """Build a run id from UTC timestamp and random suffix."""
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S")
+    return f"{timestamp}_{uuid.uuid4().hex[:8]}"

agentkit/runlog/sinks.py

@@ -0,0 +1,15 @@
+"""Sink protocol for run event consumers."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from agentkit.runlog.events import RunEvent
+
+
+class RunEventSink(Protocol):
+    """Consume one canonical runtime event."""
+
+    def consume(self, event: RunEvent) -> None:
+        """Handle one event emitted by :class:`agentkit.runlog.recorder.RunRecorder`."""
+        ...

agentkit/tools/__init__.py

@@ -0,0 +1,16 @@
+"""Public tool abstraction and registry exports."""
+
+from .base import FunctionTool, Tool
+from .loader import load_tools_from_library
+from .registry import ToolRegistry
+from .types import ToolCallOutcome, ToolInvocation, ToolModelError
+
+__all__ = [
+    "FunctionTool",
+    "Tool",
+    "ToolCallOutcome",
+    "ToolInvocation",
+    "ToolModelError",
+    "ToolRegistry",
+    "load_tools_from_library",
+]