agentkernel-cli 0.1.0__py3-none-any.whl

agentkernel/improvement.py

@@ -0,0 +1,133 @@
+"""Self-improvement seam (design §13, Phase 7).
+
+The kernel records structured telemetry from turn one. ``SelfImprover`` reads a
+session trace, asks the configured provider to suggest one concise rule or
+system-prompt addition, and writes the result as a markdown note in
+``.agentkernel/improvements``. It is intentionally lightweight — enough to close
+the loop, with room for a future richer analyzer.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from agentkernel.providers import Provider
+
+
+_REFLECTION_SYSTEM_PROMPT = (
+    "You are a self-improvement analyst for an agent kernel. "
+    "Given a session trace, propose one concise rule, instruction, or "
+    "system-prompt addition that would improve future runs. "
+    "Return only the rule text followed by a brief rationale."
+)
+
+
+@dataclass
+class Improvement:
+    suggestion: str
+    rule: str
+    trace_path: str
+    output_path: str | None = None
+
+
+def _load_trace(path: Path) -> list[dict[str, Any]]:
+    """Load the JSONL trace written by ``JsonlTelemetry``."""
+    records: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                records.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return records
+
+
+def _summarize_trace(records: list[dict[str, Any]]) -> str:
+    """Build a compact textual summary suitable for an LLM prompt."""
+    lines: list[str] = []
+    for i, record in enumerate(records):
+        lines.append(f"--- turn {i} ---")
+        lines.append(f"model: {record.get('model', 'unknown')}")
+        lines.append(f"stop_reason: {record.get('stop_reason', 'unknown')}")
+        for call in record.get("tool_calls", []):
+            lines.append(
+                f"tool: {call.get('name')} approved={call.get('approved')} "
+                f"error={call.get('is_error')}"
+            )
+        # Note: the redacted JSONL trace (design §12) does not carry assistant
+        # text or raw tool args, so reflection works from the structural signal
+        # — tools used, errors, stop reasons, and token/cost figures.
+        cost = record.get("estimated_cost_usd")
+        if cost is not None:
+            lines.append(f"cost_usd: {cost}")
+    return "\n".join(lines)
+
+
+class SelfImprover:
+    """Reflect on a completed session and emit a proposed improvement note."""
+
+    def __init__(self, provider: Provider, output_dir: str | Path) -> None:
+        self.provider = provider
+        self.output_dir = Path(output_dir)
+
+    def analyze_trace(self, trace_path: str | Path) -> Improvement:
+        trace_path = Path(trace_path)
+        records = _load_trace(trace_path)
+        summary = _summarize_trace(records)
+        prompt = (
+            f"Session trace summary:\n{summary}\n\n"
+            "Propose one concise improvement rule for the agent. "
+            "Start with the rule, then a one-line rationale."
+        )
+
+        from agentkernel.types import Message
+
+        messages = [Message(role="user", content=prompt)]
+        response = self.provider.complete(
+            messages,
+            [],
+            max_tokens=1024,
+            system=_REFLECTION_SYSTEM_PROMPT,
+        )
+        suggestion = response.message.content.strip()
+        rule = suggestion.splitlines()[0] if suggestion else suggestion
+
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = time.strftime("%Y%m%d-%H%M%S")
+        output_path = self.output_dir / f"improvement-{timestamp}.md"
+        output_path.write_text(
+            f"---\n"
+            f"type: improvement\n"
+            f"trace: {trace_path}\n"
+            f"timestamp: {timestamp}\n"
+            f"---\n\n"
+            f"{suggestion}\n",
+            encoding="utf-8",
+        )
+
+        return Improvement(
+            suggestion=suggestion,
+            rule=rule,
+            trace_path=str(trace_path),
+            output_path=str(output_path),
+        )
+
+    def latest_trace(self, log_dir: str | Path) -> Path | None:
+        """Return the most recent ``*.jsonl`` trace in ``log_dir``."""
+        log_dir = Path(log_dir)
+        if not log_dir.is_dir():
+            return None
+        traces = sorted(
+            (p for p in log_dir.iterdir() if p.suffix == ".jsonl"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        return traces[0] if traces else None

agentkernel/insights.py

@@ -0,0 +1,141 @@
+"""Usage insights from session traces (design §18.7).
+
+Aggregates the JSONL telemetry under ``log_dir`` — the stable per-turn schema
+from §12 — into a usage/cost/tool-frequency report. Pure reading: it never calls
+a provider, so it works offline and costs nothing.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+
+@dataclass
+class ModelStats:
+    turns: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost: float = 0.0
+
+
+@dataclass
+class ToolStats:
+    calls: int = 0
+    errors: int = 0
+
+
+@dataclass
+class Insights:
+    sessions: int = 0
+    turns: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    total_cost: float = 0.0
+    compactions: int = 0
+    models: dict[str, ModelStats] = field(default_factory=lambda: defaultdict(ModelStats))
+    tools: dict[str, ToolStats] = field(default_factory=lambda: defaultdict(ToolStats))
+    models_without_price: set[str] = field(default_factory=set)
+
+
+def _within(ts: str, cutoff: datetime | None) -> bool:
+    if cutoff is None:
+        return True
+    try:
+        return datetime.fromisoformat(ts) >= cutoff
+    except (ValueError, TypeError):
+        return True  # undated records are kept rather than silently dropped
+
+
+def aggregate_traces(log_dir: str | Path, *, days: int | None = None) -> Insights:
+    """Aggregate every ``*.jsonl`` trace under ``log_dir`` into one ``Insights``."""
+    directory = Path(log_dir)
+    cutoff = datetime.now(UTC) - timedelta(days=days) if days else None
+    ins = Insights()
+    if not directory.is_dir():
+        return ins
+
+    for trace in sorted(directory.glob("*.jsonl")):
+        counted_session = False
+        for line in trace.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not _within(rec.get("ts", ""), cutoff):
+                continue
+            if not counted_session:
+                ins.sessions += 1
+                counted_session = True
+
+            ins.turns += 1
+            ins.input_tokens += rec.get("input_tokens", 0)
+            ins.output_tokens += rec.get("output_tokens", 0)
+            ins.cache_read_tokens += rec.get("cache_read_tokens", 0)
+            ins.cache_write_tokens += rec.get("cache_write_tokens", 0)
+            if rec.get("compaction"):
+                ins.compactions += 1
+
+            model = rec.get("model", "unknown")
+            ms = ins.models[model]
+            ms.turns += 1
+            ms.input_tokens += rec.get("input_tokens", 0)
+            ms.output_tokens += rec.get("output_tokens", 0)
+
+            cost = rec.get("estimated_cost_usd")
+            if cost is None:
+                ins.models_without_price.add(model)
+            else:
+                ins.total_cost += cost
+                ms.cost += cost
+
+            for call in rec.get("tool_calls", []) or []:
+                ts_ = ins.tools[call.get("name", "?")]
+                ts_.calls += 1
+                if call.get("is_error"):
+                    ts_.errors += 1
+    return ins
+
+
+def format_insights(ins: Insights, *, days: int | None = None) -> str:
+    """Render an ``Insights`` as a readable text report."""
+    scope = f" (last {days} day(s))" if days else ""
+    if ins.turns == 0:
+        return f"No trace records found{scope}."
+
+    lines = [f"Usage insights{scope}", ""]
+    lines.append(f"  sessions:  {ins.sessions}")
+    lines.append(f"  turns:     {ins.turns}")
+    lines.append(
+        f"  tokens:    in={ins.input_tokens:,} out={ins.output_tokens:,} "
+        f"cache_read={ins.cache_read_tokens:,} cache_write={ins.cache_write_tokens:,}"
+    )
+    cost_note = "" if not ins.models_without_price else (
+        f"  (excludes {len(ins.models_without_price)} model(s) with no price table)"
+    )
+    lines.append(f"  est. cost: ${ins.total_cost:.4f}{cost_note}")
+    lines.append(f"  compactions: {ins.compactions}")
+
+    lines.append("")
+    lines.append("By model:")
+    for name, ms in sorted(ins.models.items(), key=lambda kv: kv[1].turns, reverse=True):
+        lines.append(
+            f"  {name}: {ms.turns} turns, in={ms.input_tokens:,} out={ms.output_tokens:,}, "
+            f"${ms.cost:.4f}"
+        )
+
+    if ins.tools:
+        lines.append("")
+        lines.append("Tool usage (most used first):")
+        for name, ts_ in sorted(ins.tools.items(), key=lambda kv: kv[1].calls, reverse=True):
+            err = f", {ts_.errors} error(s)" if ts_.errors else ""
+            lines.append(f"  {name}: {ts_.calls} call(s){err}")
+    return "\n".join(lines)

agentkernel/kanban.py

@@ -0,0 +1,114 @@
+"""A lightweight work-queue board for multi-agent coordination (design §18.3).
+
+A durable JSON board of tasks that a long mission can fan out across — the parent
+(or a human) files tasks, and workers (often spawned sub-agents) claim, work, and
+complete or block them. Deliberately "lite": one JSON file, whole-file
+read-modify-write, no daemon or dispatcher. For heavy multi-worker contention a
+real SQLite board (cf. Hermes) would be the next step; this covers the common
+case with a fraction of the surface area.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+STATUSES = ("todo", "in_progress", "done", "blocked")
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+@dataclass
+class Task:
+    id: str
+    title: str
+    status: str = "todo"
+    assignee: str | None = None
+    notes: list[str] = field(default_factory=list)
+    created: str = ""
+    updated: str = ""
+
+
+class Board:
+    """JSON-backed kanban board. Each mutation rewrites the whole file."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    # --- persistence ------------------------------------------------------
+    def _read(self) -> list[Task]:
+        if not self._path.is_file():
+            return []
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return []
+        return [Task(**t) for t in raw if isinstance(t, dict)]
+
+    def _write(self, tasks: list[Task]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(
+            json.dumps([asdict(t) for t in tasks], indent=2), encoding="utf-8"
+        )
+
+    def _update(self, task_id: str, mutate) -> Task | None:
+        tasks = self._read()
+        for t in tasks:
+            if t.id == task_id:
+                mutate(t)
+                t.updated = _now()
+                self._write(tasks)
+                return t
+        return None
+
+    # --- operations -------------------------------------------------------
+    def list(self, status: str | None = None) -> list[Task]:
+        tasks = self._read()
+        return [t for t in tasks if status is None or t.status == status]
+
+    def get(self, task_id: str) -> Task | None:
+        return next((t for t in self._read() if t.id == task_id), None)
+
+    def add(self, title: str) -> Task:
+        task = Task(id=uuid.uuid4().hex[:8], title=title.strip(), created=_now(), updated=_now())
+        tasks = self._read()
+        tasks.append(task)
+        self._write(tasks)
+        return task
+
+    def claim(self, task_id: str, assignee: str) -> Task | None:
+        def _claim(t: Task) -> None:
+            t.assignee = assignee
+            t.status = "in_progress"
+        return self._update(task_id, _claim)
+
+    def complete(self, task_id: str) -> Task | None:
+        return self._update(task_id, lambda t: setattr(t, "status", "done"))
+
+    def block(self, task_id: str, reason: str) -> Task | None:
+        def _block(t: Task) -> None:
+            t.status = "blocked"
+            if reason:
+                t.notes.append(f"blocked: {reason}")
+        return self._update(task_id, _block)
+
+    def comment(self, task_id: str, text: str) -> Task | None:
+        return self._update(task_id, lambda t: t.notes.append(text))
+
+    def next_todo(self) -> Task | None:
+        """The first unclaimed task, for a worker pulling work off the board."""
+        return next((t for t in self._read() if t.status == "todo"), None)
+
+
+_MARKS = {"todo": "[ ]", "in_progress": "[~]", "done": "[x]", "blocked": "[!]"}
+
+
+def render_task(t: Task) -> str:
+    mark = _MARKS.get(t.status, "[ ]")
+    who = f" @{t.assignee}" if t.assignee else ""
+    return f"{mark} {t.id}{who}  {t.title}"