agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/paths.py

@@ -0,0 +1,73 @@
+"""Location policy for running the agent outside its own project folder.
+
+Two roots:
+
+* **Agent home** — the user-global "brain & library" (memory notebook, knowledge
+  graph, skills, profiles, improvements, scheduled jobs). Shared across every
+  project. ``$AGENTKERNEL_HOME`` overrides the default ``~/.agentkernel``.
+* **Project root** — the directory the agent operates on, found by walking up
+  from the target directory for a marker (``agentkernel.toml`` / ``.agentkernel``
+  / ``.git``). Project-local state (session traces, kanban board, checkpoints)
+  lives under ``<project>/.agentkernel``.
+
+``anchor_path`` resolves a configured path against the right root, leaving
+absolute paths untouched, so "global brain, project sessions" works no matter
+where you launch ``agentkernel``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HOME_ENV = "AGENTKERNEL_HOME"
+DEFAULT_HOME_DIRNAME = ".agentkernel"
+_CONFIG_MARKERS = ("agentkernel.toml", ".agentkernel")
+_FALLBACK_MARKERS = (".git",)
+
+
+def agent_home(env: dict[str, str] | None = None) -> Path:
+    """The user-global agent home (``$AGENTKERNEL_HOME`` or ``~/.agentkernel``)."""
+    source = os.environ if env is None else env
+    override = source.get(HOME_ENV)
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / DEFAULT_HOME_DIRNAME
+
+
+def find_project_root(start: str | os.PathLike[str] = ".") -> Path:
+    """Walk up from ``start`` to the nearest project root.
+
+    Prefers a directory containing ``agentkernel.toml`` or ``.agentkernel``; falls
+    back to a ``.git`` root; otherwise returns ``start`` itself.
+    """
+    here = Path(start).expanduser().resolve()
+    if here.is_file():
+        here = here.parent
+    candidates = [here, *here.parents]
+    for directory in candidates:
+        if any((directory / marker).exists() for marker in _CONFIG_MARKERS):
+            return directory
+    for directory in candidates:
+        if any((directory / marker).exists() for marker in _FALLBACK_MARKERS):
+            return directory
+    return here
+
+
+def find_project_config(project_root: Path) -> Path | None:
+    """The project's ``agentkernel.toml`` if present."""
+    candidate = project_root / "agentkernel.toml"
+    return candidate if candidate.is_file() else None
+
+
+def global_config_path(home: Path | None = None) -> Path:
+    """The user-global config file (``<home>/config.toml``)."""
+    return (home or agent_home()) / "config.toml"
+
+
+def anchor_path(value: str | os.PathLike[str], *, base: Path) -> str:
+    """Resolve ``value`` against ``base``; absolute and ``~`` paths are honored."""
+    path = Path(value).expanduser()
+    if path.is_absolute():
+        return str(path)
+    return str((base / path).resolve())

agentkernel/plugins.py

@@ -0,0 +1,76 @@
+"""Plugin tool discovery (design §18.7).
+
+Loads user-authored tools from a ``plugins/`` directory and registers them
+exactly like builtins — the same seam MCP uses (§13). A plugin is a ``.py`` file
+that exposes either a ``tools()`` callable returning ``list[ToolSpec]`` (optionally
+taking ``working_dir``) or a module-level ``TOOLS`` list.
+
+SECURITY: importing a plugin executes its module code. Discovery is opt-in
+(``enable_plugins``), and only files you place in ``plugins_dir`` are loaded.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+from pathlib import Path
+
+from agentkernel.tools.base import ToolSpec
+
+
+def _import_file(path: Path):
+    spec = importlib.util.spec_from_file_location(f"agentkernel_plugin_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _call_tools_fn(fn, working_dir: str) -> list[ToolSpec]:
+    """Call a plugin's ``tools`` entrypoint, passing working_dir if it accepts it."""
+    try:
+        params = inspect.signature(fn).parameters
+    except (TypeError, ValueError):
+        params = {}
+    result = fn(working_dir) if params else fn()
+    return [s for s in (result or []) if isinstance(s, ToolSpec)]
+
+
+def _extract(module, working_dir: str) -> list[ToolSpec]:
+    specs: list[ToolSpec] = []
+    fn = getattr(module, "tools", None)
+    if callable(fn):
+        specs.extend(_call_tools_fn(fn, working_dir))
+    table = getattr(module, "TOOLS", None)
+    if isinstance(table, (list, tuple)):
+        specs.extend(s for s in table if isinstance(s, ToolSpec))
+    return specs
+
+
+def load_plugin_tools(
+    plugins_dir: str | Path,
+    *,
+    working_dir: str = ".",
+    on_error=None,
+) -> list[ToolSpec]:
+    """Discover and return tools from every ``*.py`` in ``plugins_dir``.
+
+    A module that fails to import is skipped; ``on_error(path, exc)`` is called if
+    provided so the caller can warn. Files starting with ``_`` are ignored.
+    """
+    directory = Path(plugins_dir)
+    specs: list[ToolSpec] = []
+    if not directory.is_dir():
+        return specs
+    for path in sorted(directory.glob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        try:
+            module = _import_file(path)
+            if module is not None:
+                specs.extend(_extract(module, working_dir))
+        except Exception as exc:  # noqa: BLE001 - a bad plugin must not crash startup
+            if on_error is not None:
+                on_error(path, exc)
+    return specs

agentkernel/profiles.py

@@ -0,0 +1,70 @@
+"""Profile seam (Phase 5, design §13).
+
+A ``Profile`` parameterizes a run: system prompt, tool filter, optional model
+override, and an optional rubric for evaluation. The kernel honors
+``system_prompt`` and ``tool_filter``; ``model_override`` and ``rubric`` are
+extension points for later phases / the CLI.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Profile:
+    """A parameterization of one run (design §13)."""
+
+    name: str
+    system_prompt: str | None = None
+    tool_filter: list[str] | None = None
+    model_override: str | None = None
+    rubric: str | None = None
+    reasoning: str | None = None  # "low" | "medium" | "high" (§18.5); ignored where unsupported
+
+
+def _normalize(raw: dict[str, Any]) -> dict[str, Any]:
+    """Accept snake_case keys plus the older-style aliases in TOML files."""
+    out: dict[str, Any] = {}
+    for key, value in raw.items():
+        out[key] = value
+    return out
+
+
+def load_profile(name: str, *, search_dirs: Sequence[Path] | None = None) -> Profile | None:
+    """Load a profile by name from the first matching TOML file.
+
+    Searches, in order:
+      - ``<search_dir>/<name>.toml`` for each directory in ``search_dirs``
+      - ``profiles/<name>.toml``
+      - ``.agentkernel/profiles/<name>.toml``
+
+    Returns ``None`` if no file is found.
+    """
+    if search_dirs is None:
+        search_dirs = []
+    search_dirs = [
+        *search_dirs,
+        Path("profiles"),
+        Path(".agentkernel/profiles"),
+    ]
+
+    for directory in search_dirs:
+        path = Path(directory) / f"{name}.toml"
+        if path.is_file():
+            with path.open("rb") as fh:
+                data = tomllib.load(fh)
+            values = _normalize(data)
+            return Profile(
+                name=name,
+                system_prompt=values.get("system_prompt"),
+                tool_filter=values.get("tool_filter"),
+                model_override=values.get("model_override"),
+                rubric=values.get("rubric"),
+                reasoning=values.get("reasoning"),
+            )
+    return None

agentkernel/progress.py

@@ -0,0 +1,89 @@
+"""Per-turn progress display for the REPL.
+
+Wraps a ``JsonlTelemetry`` so every recorded turn is also printed as a concise,
+one-line status line. The progress wrapper tracks cumulative usage and cost for
+the current REPL session without changing the underlying telemetry interface or
+the agent loop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+from agentkernel.budget import BudgetGuard
+from agentkernel.context import CompactionEvent
+from agentkernel.telemetry import JsonlTelemetry, ToolOutcome, estimate_cost
+from agentkernel.types import CompletionResponse, Usage
+
+
+@dataclass
+class ProgressTelemetry:
+    """Prints a status line for each turn and keeps cumulative totals."""
+
+    telemetry: JsonlTelemetry
+    output_fn: Callable[[str], None]
+    _cumulative: BudgetGuard = field(init=False)
+
+    def __post_init__(self) -> None:
+        self._cumulative = BudgetGuard(
+            model=self.telemetry.model,
+            prices=self.telemetry.prices.copy(),
+        )
+
+    @property
+    def path(self) -> str:
+        return str(self.telemetry.path)
+
+    @property
+    def cumulative_cost(self) -> float | None:
+        return self._cumulative.total_cost
+
+    @property
+    def cumulative_usage(self) -> Usage:
+        return self._cumulative.total_usage
+
+    def record_turn(
+        self,
+        iteration: int,
+        response: CompletionResponse,
+        *,
+        tool_outcomes: Sequence[ToolOutcome] = (),
+        compaction: CompactionEvent | None = None,
+    ) -> None:
+        self._cumulative.add(response.usage)
+        self.output_fn(_format_line(iteration, response, tool_outcomes, self._cumulative))
+        self.telemetry.record_turn(
+            iteration,
+            response,
+            tool_outcomes=tool_outcomes,
+            compaction=compaction,
+        )
+
+    def close(self) -> None:
+        self.telemetry.close()
+
+
+def _format_line(
+    iteration: int,
+    response: CompletionResponse,
+    tool_outcomes: Sequence[ToolOutcome],
+    cumulative: BudgetGuard,
+) -> str:
+    usage = response.usage
+    parts = [f"[{iteration}]"]
+    if response.message.tool_calls:
+        names = [o.name for o in tool_outcomes]
+        parts.append(f"tool_use: {', '.join(names) if names else '...'}")
+    else:
+        parts.append(response.stop_reason)
+    parts.append(f"in={usage.input_tokens} out={usage.output_tokens}")
+    if usage.cache_read_tokens or usage.cache_write_tokens:
+        parts.append(f"cache={usage.cache_read_tokens}/{usage.cache_write_tokens}")
+    turn_cost = estimate_cost(cumulative.model, usage, cumulative.prices)
+    if turn_cost is not None:
+        parts.append(f"this=${turn_cost:.6f}")
+    total_cost = cumulative.total_cost
+    if total_cost is not None:
+        parts.append(f"total=${total_cost:.6f}")
+    return " ".join(parts)

agentkernel/providers/__init__.py

@@ -0,0 +1,35 @@
+"""Provider abstraction and adapters (design §5)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from agentkernel.providers._http import ProviderError
+from agentkernel.providers.anthropic import AnthropicProvider
+from agentkernel.providers.base import Provider
+from agentkernel.providers.local import LocalProvider
+from agentkernel.providers.openai import OpenAIProvider
+
+if TYPE_CHECKING:
+    from agentkernel.config import Config
+
+__all__ = [
+    "Provider",
+    "ProviderError",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "LocalProvider",
+    "make_provider",
+]
+
+
+def make_provider(config: Config) -> Provider:
+    """Construct the adapter named by ``config.provider``. Keys come from env."""
+    if config.provider == "anthropic":
+        return AnthropicProvider(config.model)
+    if config.provider == "openai":
+        return OpenAIProvider(config.model)
+    if config.provider == "local":
+        kwargs = {} if config.base_url is None else {"base_url": config.base_url}
+        return LocalProvider(config.model, **kwargs)
+    raise ProviderError(f"unknown provider: {config.provider!r}")

agentkernel/providers/_http.py

@@ -0,0 +1,157 @@
+"""Shared HTTP transport for provider adapters.
+
+A provider that is unreachable after retries raises ``ProviderError`` — one of
+the few kernel faults that is allowed to propagate out of the loop (design §8.3).
+Tests never touch this module: they exercise the pure translation functions
+directly, so the suite stays offline (design §15).
+"""
+
+from __future__ import annotations
+
+import email.utils
+import json
+import time
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+# Cap how long a server-supplied Retry-After can stall us, so a hostile or
+# misconfigured header can't park the loop for minutes.
+_MAX_RETRY_AFTER = 30.0
+
+
+class ProviderError(RuntimeError):
+    """A non-recoverable provider/transport fault (config or network)."""
+
+
+class RateLimitError(ProviderError):
+    """The request was rate-limited (HTTP 429) after retries — a pool may rotate."""
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a ``Retry-After`` header (delta-seconds or HTTP-date) to seconds.
+
+    Returns ``None`` when the header is absent or unparseable, and never a
+    negative delay (a past date clamps to 0).
+    """
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        parsed = email.utils.parsedate_to_datetime(value)
+    except (ValueError, TypeError):
+        return None
+    if parsed is None:
+        return None
+    delay = parsed.timestamp() - time.time()
+    return max(0.0, delay)
+
+
+def post_json(
+    url: str,
+    *,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    timeout: float = 120.0,
+    retries: int = 2,
+) -> dict[str, Any]:
+    """POST ``payload`` as JSON and return the parsed JSON response.
+
+    Retries transient transport errors and retryable status codes; raises
+    ``ProviderError`` once retries are exhausted or on a non-retryable 4xx.
+    """
+    last_detail = ""
+    last_status: int | None = None
+    for attempt in range(retries + 1):
+        retry_after: float | None = None
+        try:
+            resp = httpx.post(url, headers=headers, json=payload, timeout=timeout)
+        except httpx.TransportError as exc:
+            last_detail = f"transport error: {exc}"
+            last_status = None
+        else:
+            if resp.status_code < 400:
+                return resp.json()
+            # Body may contain provider error detail but never our secrets.
+            last_status = resp.status_code
+            last_detail = f"HTTP {resp.status_code}: {resp.text[:500]}"
+            if resp.status_code not in _RETRYABLE_STATUS:
+                raise ProviderError(f"{url} -> {last_detail}")
+            # Honor Retry-After (429/503) when the server tells us how long to
+            # wait, bounded so a bad header can't stall the loop indefinitely.
+            retry_after = _parse_retry_after(resp.headers.get("Retry-After"))
+        if attempt < retries:
+            backoff = 0.5 * (attempt + 1)
+            delay = min(retry_after, _MAX_RETRY_AFTER) if retry_after is not None else backoff
+            time.sleep(delay)
+    # A 429 that survived retries is recoverable by rotating to another key.
+    err = RateLimitError if last_status == 429 else ProviderError
+    raise err(f"{url} unreachable after {retries + 1} attempts; {last_detail}")
+
+
+def stream_sse(
+    url: str,
+    *,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    timeout: float = 600.0,
+) -> Iterator[dict[str, Any]]:
+    """Yield parsed ``data:`` JSON objects from a streaming (SSE) POST.
+
+    Raises ``ProviderError`` on a non-2xx status (the error body is read first).
+    Both Anthropic and OpenAI carry a ``type``/``choices`` field in each ``data:``
+    payload, so callers parse the event from the JSON itself; ``event:`` lines and
+    keep-alives are ignored. ``[DONE]`` terminates the stream.
+    """
+    with httpx.stream("POST", url, headers=headers, json=payload, timeout=timeout) as resp:
+        if resp.status_code >= 400:
+            body = resp.read().decode("utf-8", "replace")[:500]
+            raise ProviderError(f"{url} -> HTTP {resp.status_code}: {body}")
+        for raw in resp.iter_lines():
+            line = raw if isinstance(raw, str) else raw.decode("utf-8", "replace")
+            line = line.strip()
+            if not line or not line.startswith("data:"):
+                continue
+            data = line[len("data:"):].strip()
+            if data == "[DONE]":
+                return
+            try:
+                yield json.loads(data)
+            except json.JSONDecodeError:
+                continue
+
+
+def post_json_pooled(
+    url: str,
+    *,
+    header_for_key,
+    payload: dict[str, Any],
+    pool,
+    timeout: float = 120.0,
+    retries: int = 2,
+    _post=None,
+) -> dict[str, Any]:
+    """POST with credential rotation: on a rate limit, mark the key exhausted and
+    retry with the next one in ``pool`` until a key works or all are spent."""
+    post = _post if _post is not None else post_json
+    last_exc: ProviderError | None = None
+    for _ in range(max(1, len(pool))):
+        key = pool.current()
+        try:
+            return post(
+                url, headers=header_for_key(key), payload=payload,
+                timeout=timeout, retries=retries,
+            )
+        except RateLimitError as exc:
+            last_exc = exc
+            pool.mark_exhausted()
+            if not pool.rotate():
+                break
+    if last_exc is not None:
+        raise last_exc
+    raise ProviderError(f"{url}: no credentials available")