base-agentkit 0.1.0__py3-none-any.whl

agentkit/agent/tool_runtime.py

@@ -0,0 +1,77 @@
+"""Tool runtime filtering and model-call bridging."""
+
+from __future__ import annotations
+
+import json
+from typing import Sequence
+
+from agentkit.llm.types import ToolCallItem, ToolResultItem, UnifiedToolSpec
+from agentkit.tools.registry import ToolRegistry
+from agentkit.tools.types import ToolCallOutcome, ToolInvocation
+
+
+class AgentToolRuntime:
+    """Expose allowed tool schemas and execute tool calls for the agent loop."""
+
+    def __init__(
+        self, registry: ToolRegistry, allowed_tools: Sequence[str] | None = None
+    ) -> None:
+        """Create a runtime view over the registry filtered by agent config."""
+        self._registry = registry
+        if allowed_tools is None:
+            self._allowed = set(registry.list_names())
+        else:
+            self._allowed = set(allowed_tools)
+
+    def schemas(self) -> list[UnifiedToolSpec]:
+        """Return schemas for tools currently allowed to the agent."""
+        raw_schemas = self._registry.schemas(self._allowed)
+        return [
+            UnifiedToolSpec(
+                name=str(schema.get("name") or ""),
+                description=str(schema.get("description") or ""),
+                parameters=dict(schema.get("parameters") or {}),
+            )
+            for schema in raw_schemas
+        ]
+
+    def execute(self, call: ToolCallItem) -> ToolCallOutcome:
+        """Execute one tool call and return the canonical outcome."""
+        if call.name not in self._allowed:
+            return ToolCallOutcome(
+                call_id=call.call_id,
+                name=call.name,
+                arguments=dict(call.arguments),
+                error=f"Tool not allowed by current agent config: {call.name}",
+                model_payload={
+                    "error": {
+                        "code": "tool_not_allowed",
+                        "message": f"Tool '{call.name}' is not allowed by the current agent config.",
+                    }
+                },
+            )
+        return self._registry.execute(
+            ToolInvocation(
+                name=call.name,
+                arguments=call.arguments,
+                call_id=call.call_id,
+            )
+        )
+
+    def build_result_item(self, outcome: ToolCallOutcome) -> ToolResultItem:
+        """Build the model-facing transcript item for a completed tool call."""
+        payload = outcome.model_payload
+        if payload is None:
+            if outcome.is_error:
+                payload = {"error": {"message": outcome.error or "Tool execution failed."}}
+            else:
+                payload = {"output": outcome.output}
+        # Round-trip through JSON so provider adapters only ever see plain Python
+        # primitives, not custom mapping/list subclasses returned by a tool.
+        payload = json.loads(json.dumps(payload, ensure_ascii=False))
+        return ToolResultItem(
+            call_id=outcome.call_id or "",
+            tool_name=outcome.name,
+            payload=payload,
+            is_error=outcome.is_error,
+        )

agentkit/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Public CLI entrypoint export."""
+
+from .main import main
+
+__all__ = ["main"]

agentkit/cli/main.py

@@ -0,0 +1,108 @@
+"""CLI entrypoint for running the agent."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from agentkit.agent.agent import Agent
+from agentkit.config.loader import load_config
+from agentkit.errors import AgentFrameworkError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Create the command-line parser for the agent CLI.
+
+    Returns:
+        argparse.ArgumentParser: Parser configured with global flags and the ``run``
+        subcommand.
+    """
+    parser = argparse.ArgumentParser(
+        prog="agentkit", description="LLM Agent Framework CLI"
+    )
+    parser.add_argument(
+        "--config",
+        default="examples/config.openai.yaml",
+        help="Path to YAML/JSON config file.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    run_parser = subparsers.add_parser(
+        "run", help="Run one task with the configured agent."
+    )
+    run_parser.add_argument("--task", help="Task text to execute.")
+    run_parser.add_argument("--task-file", help="Read task text from file.")
+    run_parser.add_argument(
+        "--report-json", help="Optional path to write run report JSON."
+    )
+    return parser
+
+
+def main() -> None:
+    """Parse arguments and dispatch to the selected CLI command.
+
+    Returns:
+        None: The process exits via normal flow or ``SystemExit``.
+    """
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "run":
+        _run_command(args)
+
+
+def _run_command(args: argparse.Namespace) -> None:
+    """Execute the ``run`` command using the parsed CLI arguments.
+
+    Args:
+        args: Parsed command namespace from :func:`build_parser`.
+
+    Returns:
+        None: Prints the final assistant output to stdout.
+
+    Raises:
+        SystemExit: Raised with code ``2`` when agent execution fails with a framework
+            error.
+    """
+    task = _load_task(args.task, args.task_file)
+    config = load_config(args.config)
+    agent = Agent.from_config(config)
+
+    try:
+        report = agent.run(task)
+    except AgentFrameworkError as exc:
+        print(f"[agent-error] {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+    if args.report_json:
+        Path(args.report_json).write_text(
+            json.dumps(report.to_dict(), ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+    print(report.final_output)
+
+
+def _load_task(task: str | None, task_file: str | None) -> str:
+    """Resolve task text from CLI flags.
+
+    Args:
+        task: Inline task text supplied via ``--task``.
+        task_file: Optional path supplied via ``--task-file``.
+
+    Returns:
+        str: The task string to send to the agent.
+
+    Raises:
+        SystemExit: If neither ``task`` nor ``task_file`` is provided.
+    """
+    if task:
+        return task
+    if task_file:
+        return Path(task_file).read_text(encoding="utf-8")
+    raise SystemExit("Please provide --task or --task-file.")
+
+
+if __name__ == "__main__":
+    main()

agentkit/config/__init__.py

@@ -0,0 +1,23 @@
+"""Public configuration loading and schema exports."""
+
+from .loader import load_config
+from .schema import (
+    AgentConfig,
+    AgentkitConfig,
+    BudgetConfig,
+    ProviderConfig,
+    RunLogConfig,
+    ToolConfig,
+    WorkspaceConfig,
+)
+
+__all__ = [
+    "AgentConfig",
+    "AgentkitConfig",
+    "BudgetConfig",
+    "ProviderConfig",
+    "RunLogConfig",
+    "ToolConfig",
+    "WorkspaceConfig",
+    "load_config",
+]

agentkit/config/loader.py

@@ -0,0 +1,108 @@
+"""Load and validate configuration from YAML/JSON."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+import yaml
+
+from agentkit.config.provider_defaults import apply_provider_config_defaults
+from agentkit.config.schema import (
+    AgentConfig,
+    AgentkitConfig,
+    BudgetConfig,
+    ProviderConfig,
+    RunLogConfig,
+    ToolConfig,
+    WorkspaceConfig,
+)
+from agentkit.errors import ConfigError
+
+_ENV_PATTERN = re.compile(r"^\$\{([A-Z0-9_]+)\}$")
+
+
+def load_config(
+    path: str | Path,
+    *,
+    overrides: Mapping[str, Any] | None = None,
+) -> AgentkitConfig:
+    """Load, merge, expand, and validate framework configuration."""
+    raw = _read_raw_config(path)
+    if overrides:
+        raw = _deep_merge(raw, dict(overrides))
+    raw = _expand_env(raw)
+
+    try:
+        workspace = WorkspaceConfig(**raw.get("workspace", {}))
+        provider = ProviderConfig(**raw.get("provider", {}))
+        budget = BudgetConfig(**raw.get("agent", {}).get("budget", {}))
+
+        agent_data = dict(raw.get("agent", {}))
+        agent_data.pop("budget", None)
+        agent = AgentConfig(budget=budget, **agent_data)
+
+        tools = ToolConfig(**raw.get("tools", {}))
+        runlog = RunLogConfig(**raw.get("runlog", {}))
+    except TypeError as exc:
+        raise ConfigError(f"Invalid configuration fields: {exc}") from exc
+
+    apply_provider_config_defaults(provider)
+    return AgentkitConfig(
+        workspace=workspace,
+        provider=provider,
+        agent=agent,
+        tools=tools,
+        runlog=runlog,
+    )
+
+
+def _read_raw_config(path: str | Path) -> dict[str, Any]:
+    """Read and parse a raw YAML/JSON configuration mapping."""
+    config_path = Path(path)
+    if not config_path.exists():
+        raise ConfigError(f"Config not found: {config_path}")
+    text = config_path.read_text(encoding="utf-8")
+    suffix = config_path.suffix.lower()
+
+    if suffix in {".yaml", ".yml"}:
+        loaded = yaml.safe_load(text) or {}
+    elif suffix == ".json":
+        loaded = json.loads(text)
+    else:
+        raise ConfigError(f"Unsupported config format: {config_path.suffix}")
+
+    if not isinstance(loaded, dict):
+        raise ConfigError("Root config must be a mapping/object.")
+    return loaded
+
+
+def _expand_env(value: Any) -> Any:
+    """Recursively substitute ``${ENV_VAR}`` string placeholders."""
+    if isinstance(value, dict):
+        return {k: _expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env(v) for v in value]
+    if isinstance(value, str):
+        match = _ENV_PATTERN.match(value.strip())
+        if match:
+            return os.getenv(match.group(1))
+    return value
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge two mapping trees with ``override`` precedence."""
+    merged = dict(base)
+    for key, value in override.items():
+        if (
+            key in merged
+            and isinstance(merged[key], dict)
+            and isinstance(value, Mapping)
+        ):
+            merged[key] = _deep_merge(merged[key], dict(value))
+        else:
+            merged[key] = value
+    return merged

agentkit/config/provider_defaults.py

@@ -0,0 +1,96 @@
+"""Provider-specific default metadata and normalization helpers."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from agentkit.config.schema import ProviderConfig, ProviderKind
+from agentkit.errors import ConfigError
+
+DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+DEFAULT_QWEN_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+DEFAULT_VLLM_BASE_URL = "http://localhost:8000/v1"
+
+DEFAULT_API_KEY_ENV_BY_PROVIDER: dict[ProviderKind, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "vllm": "VLLM_API_KEY",
+    "qwen": "DASHSCOPE_API_KEY",
+}
+
+DEFAULT_BASE_URL_BY_PROVIDER: dict[ProviderKind, str] = {
+    "anthropic": DEFAULT_ANTHROPIC_BASE_URL,
+    "gemini": DEFAULT_GEMINI_BASE_URL,
+    "qwen": DEFAULT_QWEN_BASE_URL,
+    "vllm": DEFAULT_VLLM_BASE_URL,
+}
+
+
+@dataclass(frozen=True)
+class ProviderDefaults:
+    """Resolved default metadata for one provider kind.
+
+    Attributes:
+        api_key_env: Default environment variable name for the API key.
+        base_url: Default base URL when the provider has a fixed endpoint.
+    """
+
+    api_key_env: str
+    base_url: str | None = None
+
+
+def defaults_for_provider(kind: ProviderKind) -> ProviderDefaults:
+    """Return the shared default metadata for one provider kind."""
+    if kind not in DEFAULT_API_KEY_ENV_BY_PROVIDER:
+        raise ConfigError(f"Unsupported provider kind: {kind}")
+    return ProviderDefaults(
+        api_key_env=DEFAULT_API_KEY_ENV_BY_PROVIDER[kind],
+        base_url=DEFAULT_BASE_URL_BY_PROVIDER.get(kind),
+    )
+
+
+def apply_provider_config_defaults(
+    config: ProviderConfig,
+) -> ProviderConfig:
+    """Mutate a provider config in place with shared defaults and env resolution.
+
+    Args:
+        config: Provider config to normalize.
+
+    Returns:
+        ProviderConfig: The same config object after normalization.
+
+    Raises:
+        agentkit.errors.ConfigError: If the provider still has no API key after
+            applying defaults.
+    """
+    defaults = defaults_for_provider(config.kind)
+
+    if not config.api_key_env:
+        config.api_key_env = defaults.api_key_env
+    if not config.base_url and defaults.base_url:
+        config.base_url = defaults.base_url
+
+    if config.api_key is None and config.api_key_env:
+        config.api_key = os.getenv(config.api_key_env)
+
+    if not config.api_key:
+        if config.kind == "vllm" and is_localhost_base_url(config.base_url):
+            return config
+        env_name = config.api_key_env or defaults.api_key_env
+        raise ConfigError(
+            f"Missing API key. Set {env_name} or provider.api_key/provider.api_key_env in config."
+        )
+
+    return config
+
+
+def is_localhost_base_url(base_url: str | None) -> bool:
+    """Return whether the configured base URL targets a local development server."""
+    if not base_url:
+        return False
+    lowered = base_url.lower()
+    return "localhost" in lowered or "127.0.0.1" in lowered

agentkit/config/schema.py

@@ -0,0 +1,148 @@
+"""Dataclass schemas for runtime configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from agentkit.constants import (
+    DEFAULT_MAX_INPUT_CHARS,
+    DEFAULT_MAX_STEPS,
+    DEFAULT_TIME_BUDGET_S,
+)
+from agentkit.errors import ConfigError
+
+
+@dataclass(slots=True)
+class WorkspaceConfig:
+    """Workspace-level settings."""
+
+    root: str = "./workspace"
+
+
+ProviderKind = Literal["openai", "anthropic", "gemini", "vllm", "qwen"]
+OpenAIApiVariant = Literal["responses", "chat_completions"]
+ConversationMode = Literal["auto", "client", "server"]
+
+
+@dataclass(slots=True)
+class ProviderConfig:
+    """LLM provider configuration."""
+
+    kind: ProviderKind = "openai"
+    model: str = "gpt-5"
+    openai_api_variant: OpenAIApiVariant = "responses"
+    conversation_mode: ConversationMode = "auto"
+    temperature: float | None = 0.2
+    timeout_s: int = 60
+    retries: int = 2
+    api_key: str | None = None
+    api_key_env: str | None = None
+    base_url: str | None = None
+    reasoning_effort: str | None = None
+    enable_thinking: bool = True
+    thinking_budget: int | None = None
+
+    def __post_init__(self) -> None:
+        """Validate provider-specific invariants and cross-field combinations."""
+        if self.timeout_s <= 0:
+            raise ConfigError("provider.timeout_s must be > 0")
+        if self.retries < 0:
+            raise ConfigError("provider.retries must be >= 0")
+        if self.kind not in {"openai", "anthropic", "gemini", "vllm", "qwen"}:
+            raise ConfigError(f"Unsupported provider kind: {self.kind}")
+        if self.thinking_budget is not None and self.thinking_budget <= 0:
+            raise ConfigError("provider.thinking_budget must be > 0 when provided.")
+
+        if self.openai_api_variant not in {"responses", "chat_completions"}:
+            raise ConfigError(
+                "provider.openai_api_variant must be 'responses' or 'chat_completions'."
+            )
+        if self.conversation_mode not in {"auto", "client", "server"}:
+            raise ConfigError(
+                "provider.conversation_mode must be 'auto', 'client', or 'server'."
+            )
+
+        if (
+            self.kind in {"anthropic", "gemini"}
+            and self.openai_api_variant != "responses"
+        ):
+            raise ConfigError(
+                "provider.openai_api_variant is only configurable for kind=openai; "
+                "kind=anthropic/gemini do not use it."
+            )
+
+        if (
+            self.kind in {"vllm", "qwen"}
+            and self.openai_api_variant != "chat_completions"
+        ):
+            raise ConfigError(
+                f"provider.openai_api_variant for kind={self.kind} must be 'chat_completions'."
+            )
+
+        if self.conversation_mode == "server" and not (
+            self.kind == "openai" and self.openai_api_variant == "responses"
+        ):
+            raise ConfigError(
+                "provider.conversation_mode='server' is only supported for "
+                "kind=openai with openai_api_variant='responses'."
+            )
+
+
+@dataclass(slots=True)
+class BudgetConfig:
+    """Runtime budget limits for one task execution."""
+
+    max_steps: int = DEFAULT_MAX_STEPS
+    time_budget_s: int = DEFAULT_TIME_BUDGET_S
+    max_input_chars: int = DEFAULT_MAX_INPUT_CHARS
+
+    def __post_init__(self) -> None:
+        """Validate that each configured runtime limit is strictly positive."""
+        if self.max_steps <= 0:
+            raise ConfigError("agent.budget.max_steps must be > 0")
+        if self.time_budget_s <= 0:
+            raise ConfigError("agent.budget.time_budget_s must be > 0")
+        if self.max_input_chars <= 0:
+            raise ConfigError("agent.budget.max_input_chars must be > 0")
+
+
+@dataclass(slots=True)
+class AgentConfig:
+    """Agent behavior configuration."""
+
+    system_prompt: str = "You are a helpful agent. Use tools when needed."
+    budget: BudgetConfig = field(default_factory=BudgetConfig)
+
+
+@dataclass(slots=True)
+class ToolConfig:
+    """Tool exposure configuration."""
+
+    allowed: list[str] = field(default_factory=list)
+    entries: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class RunLogConfig:
+    """Run log projection settings."""
+
+    enabled: bool = True
+    redact: bool = True
+    max_text_chars: int = 20_000
+
+    def __post_init__(self) -> None:
+        """Validate redaction and truncation settings for run-log output."""
+        if self.max_text_chars <= 0:
+            raise ConfigError("runlog.max_text_chars must be > 0")
+
+
+@dataclass(slots=True)
+class AgentkitConfig:
+    """Top-level configuration container."""
+
+    workspace: WorkspaceConfig = field(default_factory=WorkspaceConfig)
+    provider: ProviderConfig = field(default_factory=ProviderConfig)
+    agent: AgentConfig = field(default_factory=AgentConfig)
+    tools: ToolConfig = field(default_factory=ToolConfig)
+    runlog: RunLogConfig = field(default_factory=RunLogConfig)

agentkit/constants.py

@@ -0,0 +1,21 @@
+"""Project-level constants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+DEFAULT_WORKSPACE_DIRS: tuple[str, ...] = ("logs",)
+DEFAULT_RUNLOG_PATH = Path("logs/run.jsonl")
+DEFAULT_ENCODING = "utf-8"
+
+DEFAULT_MAX_STEPS = 20
+DEFAULT_TIME_BUDGET_S = 300
+DEFAULT_MAX_INPUT_CHARS = 20_000
+
+SENSITIVE_KEYS: tuple[str, ...] = (
+    "api_key",
+    "apikey",
+    "secret",
+    "password",
+    "authorization",
+)

agentkit/errors.py

@@ -0,0 +1,58 @@
+"""Custom framework exceptions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+
+class AgentFrameworkError(Exception):
+    """Base class for all framework-specific exceptions."""
+
+
+class ConfigError(AgentFrameworkError):
+    """Raised when configuration loading or validation fails."""
+
+
+class WorkspaceError(AgentFrameworkError):
+    """Raised for workspace path isolation and filesystem operation errors."""
+
+
+class ToolError(AgentFrameworkError):
+    """Raised for tool registration, validation, or execution failures."""
+
+
+ProviderIssueCategory = Literal[
+    "auth",
+    "rate_limit",
+    "invalid_request",
+    "timeout",
+    "upstream",
+    "safety",
+    "parse",
+    "unknown",
+]
+
+
+@dataclass(slots=True)
+class ProviderIssue:
+    """Structured provider failure metadata for logging and retry decisions."""
+
+    category: ProviderIssueCategory
+    http_status: int | None = None
+    provider_code: str | None = None
+    retryable: bool = False
+    raw: dict[str, Any] | None = None
+
+
+class ProviderError(AgentFrameworkError):
+    """Raised for model provider request failures or invalid responses."""
+
+    def __init__(self, message: str, *, issue: ProviderIssue | None = None) -> None:
+        """Attach optional structured provider metadata to the raised error."""
+        super().__init__(message)
+        self.issue = issue
+
+
+class BudgetExceededError(AgentFrameworkError):
+    """Raised when runtime step or elapsed-time budget is exceeded."""