base-agentkit 0.1.0__py3-none-any.whl

agentkit/__init__.py

@@ -0,0 +1,35 @@
+"""Generic LLM agent framework."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .agent.agent import Agent
+from .config.loader import load_config
+from .config.schema import AgentkitConfig
+
+
+def create_agent(
+    config_or_path: AgentkitConfig | str | Path,
+) -> Agent:
+    """Build an :class:`Agent` from config data or a config file.
+
+    Args:
+        config_or_path: Either a fully instantiated framework config object or a
+            filesystem path to a YAML/JSON config file.
+
+    Returns:
+        Agent: A configured agent instance ready to execute tasks.
+
+    Raises:
+        agentkit.errors.ConfigError: If the config file is invalid or missing required
+            fields.
+    """
+    if isinstance(config_or_path, AgentkitConfig):
+        config = config_or_path
+    else:
+        config = load_config(config_or_path)
+    return Agent.from_config(config)
+
+
+__all__ = ["Agent", "AgentkitConfig", "create_agent", "load_config"]

agentkit/agent/__init__.py

@@ -0,0 +1,7 @@
+"""Public agent runtime exports."""
+
+from .agent import Agent
+from .report import RunReport
+from .tool_runtime import AgentToolRuntime
+
+__all__ = ["Agent", "AgentToolRuntime", "RunReport"]

agentkit/agent/agent.py

@@ -0,0 +1,368 @@
+"""Agent core loop: model inference <-> tool execution."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict
+from typing import Any
+
+from agentkit.agent.budgets import RuntimeBudget
+from agentkit.agent.report import RunReport, RunReportProjector
+from agentkit.agent.tool_runtime import AgentToolRuntime
+from agentkit.config.schema import AgentkitConfig
+from agentkit.errors import ProviderError
+from agentkit.llm.base import BaseLLMProvider
+from agentkit.llm.factory import build_provider
+from agentkit.llm.types import (
+    ConversationItem,
+    ConversationState,
+    GenerationOptions,
+    MessageItem,
+    ToolCallItem,
+    ToolResultItem,
+    UnifiedLLMRequest,
+    Usage,
+)
+from agentkit.llm.usage import merge_usage, usage_to_payload
+from agentkit.runlog import JsonlRunLogSink
+from agentkit.tools.loader import load_tools_from_library
+from agentkit.tools.registry import ToolRegistry
+from agentkit.runlog.recorder import RunRecorder
+from agentkit.workspace.fs import WorkspaceFS
+from agentkit.workspace.layout import init_workspace_layout
+
+
+class Agent:
+    """Coordinate model calls, tool execution, and event-driven projections.
+
+    The Agent orchestrates the core loop:
+
+        User Task
+            ↓
+        Model Inference
+            ↓
+        Tool Calls (optional)
+            ↓
+        Tool Execution
+            ↓
+        Model Continues
+            ↓
+        Final Result
+
+    All events are recorded and projected into a RunReport and optional run logs.
+    """
+
+    def __init__(
+        self,
+        *,
+        config: AgentkitConfig,
+        fs: WorkspaceFS,
+        provider: BaseLLMProvider,
+        tool_runtime: AgentToolRuntime,
+        runlog_sink: JsonlRunLogSink,
+    ) -> None:
+        self.config = config
+        self.fs = fs
+        self.provider = provider
+        self.tool_runtime = tool_runtime
+        self.runlog_sink = runlog_sink
+
+    @classmethod
+    def from_config(cls, config: AgentkitConfig) -> "Agent":
+        """Build an Agent from validated configuration."""
+
+        # Initialize workspace directory layout
+        workspace_root = init_workspace_layout(config.workspace.root)
+        fs = WorkspaceFS(workspace_root)
+
+        # Build the configured LLM provider
+        provider = build_provider(config.provider)
+
+        # Load tools from the workspace library and register them
+        registry = ToolRegistry()
+        registry.register_many(load_tools_from_library(fs))
+
+        # Create tool runtime with allowlist filtering
+        tool_runtime = AgentToolRuntime(registry, config.tools.allowed)
+
+        # Initialize run logging
+        runlog_sink = JsonlRunLogSink(fs, config.runlog)
+
+        return cls(
+            config=config,
+            fs=fs,
+            provider=provider,
+            tool_runtime=tool_runtime,
+            runlog_sink=runlog_sink,
+        )
+
+    def run(self, task: str) -> RunReport:
+        """Execute the full model-tool loop for a single task.
+
+        The run proceeds as:
+
+        1. Initialize runtime state
+        2. Call model
+        3. Execute tools if requested
+        4. Feed tool results back to model
+        5. Repeat until model completes
+        6. Produce final RunReport
+        """
+
+        # Project events into both a final report and the optional run log.
+        report_projector = RunReportProjector()
+        recorder = RunRecorder(sinks=[report_projector, self.runlog_sink])
+
+        tool_specs = self.tool_runtime.schemas()  # tool schemas exposed to the LLM
+        instructions = self.config.agent.system_prompt  # system prompt
+        options = GenerationOptions(
+            temperature=self.config.provider.temperature,
+            reasoning_effort=self.config.provider.reasoning_effort,
+            thinking_enabled=self.config.provider.enable_thinking,
+        )  # generation parameters
+
+        # Start run recording
+        run_id = recorder.start_run(
+            task=task,
+            context={
+                "provider": self.config.provider.kind,
+                "model": self.config.provider.model,
+                "conversation_mode": self.config.provider.conversation_mode,
+                "instructions": instructions,
+                "tools": [asdict(tool) for tool in tool_specs],
+                "options": asdict(options),
+            },
+        )
+
+        # Runtime guardrails
+        budget = RuntimeBudget(
+            max_steps=self.config.agent.budget.max_steps,
+            time_budget_s=self.config.agent.budget.time_budget_s,
+        )
+
+        # Conversation state holds full chat history
+        state = ConversationState(mode=self.config.provider.conversation_mode)
+
+        # Inputs for the next model turn
+        next_inputs: list[ConversationItem] = [MessageItem(role="user", text=task)]
+
+        step = 0
+        run_closed = False
+        model_step_count = 0
+        tool_call_count = 0
+        aggregate_usage = Usage()
+
+        # Track last response for better error reporting
+        last_response_reason: str | None = None
+        last_response_output = ""
+
+        try:
+            while True:
+                # Ensure execution stays within configured limits
+                budget.ensure_can_continue(step)
+
+                # Build the unified LLM request
+                req = UnifiedLLMRequest(
+                    provider=self.config.provider.kind,
+                    model=self.config.provider.model,
+                    state=state,
+                    inputs=list(next_inputs),
+                    instructions=instructions,
+                    tools=tool_specs,
+                    options=options,
+                )
+
+                # Call LLM provider
+                call_start = time.perf_counter()
+                response = self.provider.generate(req)
+                call_ms = (time.perf_counter() - call_start) * 1000
+
+                last_response_reason = response.reason
+                last_response_output = response.output_text
+                merge_usage(aggregate_usage, response.usage)
+
+                # Update conversation history
+                state.history.extend(req.inputs)
+                state.history.extend(response.output_items)
+
+                # Apply provider state patches (cursor updates etc.)
+                if response.state_patch.new_provider_cursor is not None:
+                    state.provider_cursor = response.state_patch.new_provider_cursor
+
+                if response.state_patch.provider_meta_patch:
+                    state.provider_meta.update(response.state_patch.provider_meta_patch)
+
+                # Record model response event
+                recorder.emit(
+                    "model_responded",
+                    step=step,
+                    payload={
+                        "status": response.status,
+                        "reason": response.reason,
+                        "output_text": response.output_text,
+                        "duration_ms": call_ms,
+                        "requested_tools": [
+                            self._serialize_item(call) for call in response.tool_calls
+                        ],
+                        "request": {
+                            "state_cursor": req.state.provider_cursor,
+                            "inputs": [self._serialize_item(i) for i in req.inputs],
+                        },
+                        "response": {
+                            "response_id": response.response_id,
+                            "output_items": [
+                                self._serialize_item(i) for i in response.output_items
+                            ],
+                            "usage": asdict(response.usage),
+                            "state_patch": asdict(response.state_patch),
+                            "raw_response": response.raw_response,
+                        },
+                    },
+                )
+
+                model_step_count += 1
+                next_inputs = []
+
+                # Branch based on provider response status
+                match response.status:
+                    case "requires_tool":
+                        # Model requested tool execution
+
+                        if not response.tool_calls:
+                            raise ProviderError(
+                                "Model turn requested tool execution but returned no tool calls."
+                            )
+
+                        # Execute tools and collect results
+                        for call in response.tool_calls:
+                            outcome = self.tool_runtime.execute(call)
+
+                            # Tool result becomes next model input
+                            next_inputs.append(
+                                self.tool_runtime.build_result_item(outcome)
+                            )
+
+                            # Record tool execution
+                            recorder.emit(
+                                "tool_executed",
+                                step=step,
+                                payload=outcome.to_event_payload(),
+                            )
+
+                            tool_call_count += 1
+
+                        step += 1
+                        continue
+
+                    case "completed" | "blocked" | "incomplete":
+                        # Run finished (successfully or otherwise)
+
+                        if response.reason == "pause":
+                            raise ProviderError(
+                                "Model turn paused with reason=pause. Automatic continuation is not implemented."
+                            )
+
+                        recorder.end_run(
+                            status=response.status,
+                            payload={
+                                "reason": response.reason,
+                                "step_count": model_step_count,
+                                "tool_call_count": tool_call_count,
+                                "final_output": response.output_text,
+                                "usage": usage_to_payload(aggregate_usage),
+                            },
+                        )
+
+                        run_closed = True
+                        break
+
+                    case "failed":
+                        # Provider explicitly reported failure
+                        raise ProviderError(
+                            f"Model turn failed with reason={response.reason}."
+                        )
+
+                    case _:
+                        # Unknown response status
+                        raise ProviderError(
+                            f"Model turn returned unsupported status={response.status!r}."
+                        )
+
+        except Exception as exc:
+            # Ensure failed runs are properly recorded
+            if not run_closed:
+                payload = {
+                    "step_count": model_step_count,
+                    "tool_call_count": tool_call_count,
+                    "error_type": type(exc).__name__,
+                    "error_message": str(exc),
+                }
+
+                if last_response_reason is not None:
+                    payload["reason"] = last_response_reason
+
+                if last_response_output:
+                    payload["final_output"] = last_response_output
+
+                payload["usage"] = usage_to_payload(aggregate_usage)
+
+                recorder.end_run(
+                    status="failed",
+                    payload=payload,
+                )
+
+            raise
+
+        # Build final report from recorded events
+        report = report_projector.build(
+            runlog_path=(
+                str(self.runlog_sink.runlog_path_for_run(run_id))
+                if self.runlog_sink.enabled
+                else None
+            )
+        )
+
+        # Safety check to ensure run IDs match
+        if report.run_id != run_id:
+            raise RuntimeError(
+                "Run report projection mismatch: run_id changed during recording."
+            )
+
+        return report
+
+    def _serialize_item(self, item: ConversationItem) -> dict[str, Any]:
+        """Convert a conversation item into a run-log friendly structure.
+
+        This avoids leaking internal objects into logs and ensures JSON-safe output.
+        """
+
+        if isinstance(item, MessageItem):
+            return {"kind": "message", "role": item.role, "text": item.text}
+
+        if isinstance(item, ToolCallItem):
+            return {
+                "kind": "tool_call",
+                "call_id": item.call_id,
+                "name": item.name,
+                "arguments": item.arguments,
+                "raw_arguments": item.raw_arguments,
+            }
+
+        if isinstance(item, ToolResultItem):
+            return {
+                "kind": "tool_result",
+                "call_id": item.call_id,
+                "tool_name": item.tool_name,
+                "payload": item.payload,
+                "output_text": item.output_text,
+                "is_error": item.is_error,
+            }
+
+        # Default: reasoning / thinking items
+        return {
+            "kind": "reasoning",
+            "text": item.text,
+            "summary": item.summary,
+            "raw_item": item.raw_item,
+            "replay_hint": item.replay_hint,
+        }

agentkit/agent/budgets.py

@@ -0,0 +1,48 @@
+"""Runtime budget guards."""
+
+from __future__ import annotations
+
+import time
+
+from agentkit.errors import BudgetExceededError
+
+
+class RuntimeBudget:
+    """Track and enforce runtime limits for a single agent run."""
+
+    def __init__(self, *, max_steps: int, time_budget_s: int) -> None:
+        """Initialize budget thresholds and start timing.
+
+        Args:
+            max_steps: Maximum number of model/tool loop iterations allowed.
+            time_budget_s: Maximum wall-clock runtime in seconds.
+
+        Returns:
+            None
+        """
+        self.max_steps = max_steps
+        self.time_budget_s = time_budget_s
+        self.started_monotonic = time.monotonic()
+
+    def ensure_can_continue(self, step_index: int) -> None:
+        """Raise if the run exceeded configured step or time budgets.
+
+        Args:
+            step_index: Zero-based index of the next step to execute.
+
+        Returns:
+            None
+
+        Raises:
+            agentkit.errors.BudgetExceededError: If the step count or elapsed time is
+                above configured limits.
+        """
+        if step_index >= self.max_steps:
+            raise BudgetExceededError(
+                f"Step budget exceeded: step={step_index}, max_steps={self.max_steps}"
+            )
+        elapsed = time.monotonic() - self.started_monotonic
+        if elapsed > self.time_budget_s:
+            raise BudgetExceededError(
+                f"Time budget exceeded: elapsed={elapsed:.1f}s, budget={self.time_budget_s}s"
+            )

agentkit/agent/report.py

@@ -0,0 +1,166 @@
+"""Run report projection from canonical run events."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from agentkit.llm.types import Usage
+from agentkit.llm.usage import usage_from_payload
+from agentkit.runlog.events import RunEvent
+from agentkit.runlog.sinks import RunEventSink
+
+
+@dataclass(slots=True)
+class RunStep:
+    """One model turn summary in the returned run report."""
+
+    step: int
+    assistant_text: str
+    tool_calls: list[str] = field(default_factory=list)
+    ts: str = ""
+
+
+@dataclass(slots=True)
+class RunToolCall:
+    """One tool execution record in the returned run report."""
+
+    step: int
+    call_id: str
+    name: str
+    arguments: dict[str, Any]
+    is_error: bool
+    output: Any = None
+    error: str | None = None
+    model_payload: Any = None
+    duration_ms: float | None = None
+    ts: str = ""
+
+
+@dataclass(slots=True)
+class RunReport:
+    """Structured result object returned by :meth:`agentkit.agent.Agent.run`."""
+
+    task: str
+    started_at: str
+    run_id: str
+    runlog_path: str | None = None
+    status: str = "failed"
+    completed: bool = False
+    final_output: str = ""
+    reason: str | None = None
+    finished_at: str | None = None
+    usage: Usage = field(default_factory=Usage)
+    steps: list[RunStep] = field(default_factory=list)
+    tool_calls: list[RunToolCall] = field(default_factory=list)
+    artifacts: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the report into plain data for CLI or API serialization."""
+        return asdict(self)
+
+
+class RunReportProjector(RunEventSink):
+    """Project canonical run events into a :class:`RunReport`."""
+
+    def __init__(self) -> None:
+        """Initialize empty projection state for a single run."""
+        self._task = ""
+        self._started_at = ""
+        self._run_id = ""
+        self._status = "failed"
+        self._completed = False
+        self._final_output = ""
+        self._reason: str | None = None
+        self._finished_at: str | None = None
+        self._usage = Usage()
+        self._steps: list[RunStep] = []
+        self._tool_calls: list[RunToolCall] = []
+
+    def consume(self, event: RunEvent) -> None:
+        """Update the projection incrementally from one canonical run event."""
+        if event.kind == "run_started":
+            self._task = str(event.payload.get("task", ""))
+            self._started_at = event.ts
+            self._run_id = event.run_id
+            return
+
+        if event.kind == "model_responded":
+            tool_call_names: list[str] = []
+            requested_tools = event.payload.get("requested_tools", [])
+            if isinstance(requested_tools, list):
+                for item in requested_tools:
+                    if isinstance(item, dict) and item.get("name") is not None:
+                        tool_call_names.append(str(item["name"]))
+            self._steps.append(
+                RunStep(
+                    step=event.step or 0,
+                    assistant_text=str(event.payload.get("output_text", "")),
+                    tool_calls=list(tool_call_names)
+                    if isinstance(tool_call_names, list)
+                    else [],
+                    ts=event.ts,
+                )
+            )
+            return
+
+        if event.kind == "tool_executed":
+            arguments = event.payload.get("arguments")
+            self._tool_calls.append(
+                RunToolCall(
+                    step=event.step or 0,
+                    call_id=str(event.payload.get("call_id", "")),
+                    name=str(event.payload.get("name", "")),
+                    arguments=dict(arguments) if isinstance(arguments, dict) else {},
+                    is_error=bool(event.payload.get("is_error", False)),
+                    output=event.payload.get("output"),
+                    error=event.payload.get("error"),
+                    model_payload=event.payload.get("model_payload"),
+                    duration_ms=event.payload.get("duration_ms"),
+                    ts=event.ts,
+                )
+            )
+            return
+
+        if event.kind == "run_finished":
+            self._finished_at = event.ts
+            self._status = str(event.payload.get("status", self._status))
+            self._completed = self._status == "completed"
+            if "final_output" in event.payload:
+                self._final_output = str(event.payload.get("final_output", ""))
+            reason = event.payload.get("reason")
+            if reason is not None:
+                self._reason = str(reason)
+            usage = event.payload.get("usage")
+            if isinstance(usage, dict):
+                self._usage = usage_from_payload(usage)
+
+    def build(self, *, runlog_path: str | None = None) -> RunReport:
+        """Materialize the current projection into an immutable report object."""
+        if not self._run_id or not self._started_at:
+            raise RuntimeError("RunReportProjector has not received run_started.")
+
+        return RunReport(
+            task=self._task,
+            started_at=self._started_at,
+            run_id=self._run_id,
+            runlog_path=runlog_path,
+            status=self._status,
+            completed=self._completed,
+            final_output=self._final_output,
+            reason=self._reason,
+            finished_at=self._finished_at,
+            usage=self._usage,
+            steps=list(self._steps),
+            tool_calls=list(self._tool_calls),
+        )
+
+    @property
+    def step_count(self) -> int:
+        """Return the number of model turns observed so far."""
+        return len(self._steps)
+
+    @property
+    def tool_call_count(self) -> int:
+        """Return the number of tool executions observed so far."""
+        return len(self._tool_calls)