agent-riggs 0.1.0__py3-none-any.whl

agent_riggs/__init__.py

@@ -0,0 +1,3 @@
+"""Agent Riggs — cross-session memory and analysis for the Rigged tool suite."""
+
+__version__ = "0.1.0"

agent_riggs/assembly.py

@@ -0,0 +1,53 @@
+"""Build a RiggsService from discovered plugins."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from agent_riggs.config import load_config
+from agent_riggs.service import RiggsService
+from agent_riggs.store import Store
+
+
+def assemble(project_root: Path, read_only: bool = False) -> RiggsService:
+    """Build the service with all discovered plugins."""
+    config = load_config(project_root)
+    store_path = project_root / config.store.path
+    store = Store(store_path, read_only=read_only)
+    service = RiggsService(project_root, store, config)
+
+    _register_core_plugins(service)
+    _register_optional_plugins(service)
+
+    ddl: list[str] = []
+    for p in service.plugins.values():
+        ddl.extend(p.schema_ddl())
+    if not read_only:
+        store.ensure_schema(ddl)
+
+    return service
+
+
+def _register_core_plugins(service: RiggsService) -> None:
+    """Register plugins that are always available."""
+    from agent_riggs.plugins.briefing import BriefingPlugin
+    from agent_riggs.plugins.ingest import IngestPlugin
+    from agent_riggs.plugins.metrics import MetricsPlugin
+    from agent_riggs.plugins.ratchet import RatchetPlugin
+    from agent_riggs.plugins.trust import TrustPlugin
+
+    service.register(TrustPlugin())
+    service.register(IngestPlugin())
+    service.register(RatchetPlugin())
+    service.register(MetricsPlugin())
+    service.register(BriefingPlugin())
+
+
+def _register_optional_plugins(service: RiggsService) -> None:
+    """Register plugins whose backing tools may not be installed."""
+    import shutil
+
+    if shutil.which("blq"):
+        from agent_riggs.plugins.sandbox import SandboxPlugin
+
+        service.register(SandboxPlugin())

agent_riggs/briefing/project.py

@@ -0,0 +1,21 @@
+"""Project-level health assessment."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_riggs.store import Store
+
+
+def project_health(store: Store, project: str) -> dict[str, Any]:
+    row = store.execute(
+        """SELECT count(*), coalesce(avg(trust_end), 1.0), coalesce(avg(failure_rate), 0.0)
+           FROM session_summaries WHERE project = ?""",
+        [project],
+    ).fetchone()
+    return {
+        "total_sessions": row[0],
+        "avg_trust": row[1],
+        "avg_failure_rate": row[2],
+        "healthy": row[1] >= 0.7 and row[2] <= 0.3,
+    }

agent_riggs/briefing/session.py

@@ -0,0 +1,84 @@
+"""Generate session briefings from cross-session data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agent_riggs.config import RiggsConfig
+from agent_riggs.store import Store
+
+
+@dataclass
+class SessionBriefing:
+    trust_baseline: float | None
+    last_session: dict[str, Any] | None
+    known_issues: list[str]
+    active_candidates: int
+
+    def format(self):
+        lines = []
+        if self.trust_baseline is not None:
+            lines.append(f"Trust baseline: {self.trust_baseline:.2f}")
+        else:
+            lines.append("Trust baseline: no data")
+        if self.last_session:
+            s = self.last_session
+            lines.append(
+                f"Last session: {s['session_id']}, {s['total_turns']} turns, "
+                f"trust {s['trust_end']:.2f}"
+            )
+        else:
+            lines.append("Last session: none")
+        if self.known_issues:
+            lines.append("\nKnown issues:")
+            for issue in self.known_issues:
+                lines.append(f"  - {issue}")
+        if self.active_candidates > 0:
+            lines.append(f"\nActive ratchet candidates: {self.active_candidates}")
+        return "\n".join(lines)
+
+
+def generate_briefing(store: Store, project: str, config: RiggsConfig) -> SessionBriefing:
+    trust_row = store.execute(
+        "SELECT trust_15 FROM turns WHERE project = ? ORDER BY timestamp DESC LIMIT 1",
+        [project],
+    ).fetchone()
+    trust_baseline = trust_row[0] if trust_row else None
+
+    session_row = store.execute(
+        """SELECT session_id, total_turns, total_failures, trust_end, CAST(ended_at AS VARCHAR)
+           FROM session_summaries WHERE project = ? ORDER BY ended_at DESC LIMIT 1""",
+        [project],
+    ).fetchone()
+    last_session = None
+    if session_row:
+        last_session = {
+            "session_id": session_row[0],
+            "total_turns": session_row[1],
+            "total_failures": session_row[2],
+            "trust_end": session_row[3],
+            "ended_at": session_row[4],
+        }
+
+    failure_rows = store.execute(
+        """SELECT failure_category, count(*) AS cnt FROM failure_stream
+           WHERE project = ? GROUP BY failure_category
+           HAVING count(*) >= 3 ORDER BY cnt DESC LIMIT 5""",
+        [project],
+    ).fetchall()
+    known_issues = [f"{r[0]} ({r[1]} occurrences)" for r in failure_rows]
+
+    candidate_row = store.execute(
+        """SELECT count(DISTINCT failure_category || coalesce(tool_name, '') || coalesce(mode, ''))
+           FROM failure_stream WHERE project = ? GROUP BY project HAVING count(*) >= ?""",
+        [project, config.ratchet.min_frequency],
+    ).fetchone()
+    active_candidates = candidate_row[0] if candidate_row else 0
+
+    return SessionBriefing(
+        trust_baseline=trust_baseline,
+        last_session=last_session,
+        known_issues=known_issues,
+        active_candidates=active_candidates,
+    )

agent_riggs/cli.py

@@ -0,0 +1,255 @@
+"""CLI entry point for agent-riggs."""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+import click
+
+from agent_riggs import __version__
+
+
+def find_project_root() -> Path:
+    """Find the project root (cwd for now)."""
+    return Path.cwd()
+
+
+@click.group()
+@click.version_option(__version__, prog_name="agent-riggs")
+@click.pass_context
+def main(ctx: click.Context) -> None:
+    """agent-riggs -- cross-session memory and analysis for the Rigged tool suite."""
+    ctx.ensure_object(dict)
+
+
+@main.command()
+def init() -> None:
+    """Initialize .riggs/ directory and store."""
+    project_root = find_project_root()
+    riggs_dir = project_root / ".riggs"
+    riggs_dir.mkdir(exist_ok=True)
+
+    config_path = riggs_dir / "config.toml"
+    if not config_path.exists():
+        defaults_ref = resources.files("agent_riggs") / "defaults" / "config.toml"
+        config_path.write_text(defaults_ref.read_text(encoding="utf-8"))
+
+    from agent_riggs.assembly import assemble
+
+    service = assemble(project_root)
+
+    tools = []
+    for name in ("kibitzer", "blq", "jetsam", "fledgling"):
+        if shutil.which(name) or (project_root / f".{name}").exists():
+            tools.append(name)
+
+    click.echo(f"Initialized .riggs/ in {project_root}")
+    if tools:
+        click.echo(f"Discovered tools: {', '.join(tools)}")
+    else:
+        click.echo("No sibling tools discovered yet.")
+
+    service.store.close()
+
+
+@main.command()
+def ingest() -> None:
+    """Ingest session data from sibling tools."""
+    from agent_riggs.assembly import assemble
+
+    project_root = find_project_root()
+    service = assemble(project_root)
+
+    ingest_plugin = service.plugin("ingest")
+    result = ingest_plugin.run()
+
+    click.echo(f"Ingested {result.turns_ingested} turns from {result.sources_read}")
+    if result.failures_recorded:
+        click.echo(f"Recorded {result.failures_recorded} failures")
+
+    service.store.close()
+
+
+@main.command()
+def status() -> None:
+    """Show trust scores, mode, and ratchet summary."""
+    from agent_riggs.assembly import assemble
+
+    project_root = find_project_root()
+    service = assemble(project_root)
+
+    trust_plugin = service.plugin("trust")
+    data = trust_plugin.current()
+
+    if not data["has_data"]:
+        click.echo("trust: no data yet")
+        click.echo("\nRun `agent-riggs ingest` after a session.")
+    else:
+        click.echo(
+            f"trust: {data['trust_1']:.2f} / {data['trust_5']:.2f} / {data['trust_15']:.2f}"
+        )
+        click.echo("       now    session  baseline")
+
+    service.store.close()
+
+
+# --- Trust commands ---
+
+
+@main.group("trust")
+def trust_group() -> None:
+    """Trust score commands."""
+
+
+@trust_group.command("current")
+def trust_current() -> None:
+    """Show current trust scores."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    data = service.plugin("trust").current()
+    if not data["has_data"]:
+        click.echo("No trust data yet.")
+    else:
+        click.echo(f"trust_1 (now):      {data['trust_1']:.4f}")
+        click.echo(f"trust_5 (session):  {data['trust_5']:.4f}")
+        click.echo(f"trust_15 (baseline):{data['trust_15']:.4f}")
+    service.store.close()
+
+
+@trust_group.command("history")
+@click.option("--limit", default=20, help="Number of entries")
+def trust_history(limit: int) -> None:
+    """Show trust score history."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    history = service.plugin("trust").history(limit=limit)
+    if not history:
+        click.echo("No trust history.")
+    else:
+        for entry in history:
+            click.echo(
+                f"  [{entry['session_id']}:{entry['turn_number']}] "
+                f"{entry['trust_1']:.2f} / {entry['trust_5']:.2f} / {entry['trust_15']:.2f}"
+            )
+    service.store.close()
+
+
+# --- Ratchet commands ---
+
+
+@main.group("ratchet")
+def ratchet_group() -> None:
+    """Ratchet candidate commands."""
+
+
+@ratchet_group.command("candidates")
+def ratchet_candidates() -> None:
+    """Show pending ratchet candidates."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    candidates = service.plugin("ratchet").candidates()
+    if not candidates:
+        click.echo("No ratchet candidates.")
+    else:
+        for c in candidates:
+            click.echo(f"\n  [{c.candidate_type}] {c.candidate_key}")
+            click.echo(f"    {c.recommendation}")
+            click.echo(f"    Evidence: {c.evidence}")
+    service.store.close()
+
+
+@ratchet_group.command("promote")
+@click.argument("key")
+@click.option("--reason", default=None, help="Reason for promotion")
+def ratchet_promote(key: str, reason: str | None) -> None:
+    """Promote a ratchet candidate."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    try:
+        service.plugin("ratchet").promote(key, reason)
+        click.echo(f"Promoted: {key}")
+    except KeyError:
+        click.echo(f"No candidate with key: {key}", err=True)
+    service.store.close()
+
+
+@ratchet_group.command("reject")
+@click.argument("key")
+@click.option("--reason", required=True, help="Reason for rejection")
+def ratchet_reject(key: str, reason: str) -> None:
+    """Reject a ratchet candidate with reason."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    try:
+        service.plugin("ratchet").reject(key, reason)
+        click.echo(f"Rejected: {key}")
+    except KeyError:
+        click.echo(f"No candidate with key: {key}", err=True)
+    service.store.close()
+
+
+@ratchet_group.command("history")
+def ratchet_history() -> None:
+    """Show ratchet decision history."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    history = service.plugin("ratchet").history()
+    if not history:
+        click.echo("No ratchet decisions recorded.")
+    else:
+        for h in history:
+            click.echo(
+                f"  [{h['decided_at']}] {h['decision']}: "
+                f"{h['candidate_key']} — {h.get('reason', '')}"
+            )
+    service.store.close()
+
+
+# --- Metrics command ---
+
+
+@main.command("metrics")
+@click.option("--period", default=None, type=int, help="Period in days")
+def metrics_cmd(period: int | None) -> None:
+    """Show ratchet metrics dashboard."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    m = service.plugin("metrics").compute(period)
+    click.echo(f"RATCHET METRICS ({m.total_sessions} sessions)\n")
+    click.echo(f"  Ratchet velocity:        {m.ratchet_velocity} promotions")
+    click.echo(f"  Self-service ratio:      {m.structured_tool_fraction:.0%} structured")
+    click.echo(f"  Computation channel %:   {m.computation_channel_fraction:.0%}")
+    click.echo(
+        f"  Trust trajectory:        {m.trust_trajectory_start:.2f} -> "
+        f"{m.trust_trajectory_end:.2f}"
+    )
+    click.echo(f"  Failure rate:            {m.failure_rate:.0%}")
+    if m.mode_distribution:
+        click.echo("\n  Mode distribution:")
+        for mode, frac in sorted(m.mode_distribution.items(), key=lambda x: -x[1]):
+            click.echo(f"    {mode}: {frac:.0%}")
+    service.store.close()
+
+
+# --- Brief command ---
+
+
+@main.command("brief")
+def brief_cmd() -> None:
+    """Full session briefing."""
+    from agent_riggs.assembly import assemble
+
+    service = assemble(find_project_root())
+    briefing = service.plugin("briefing").brief()
+    click.echo(f"PROJECT BRIEFING: {find_project_root().name}\n")
+    click.echo(briefing.format())
+    service.store.close()

agent_riggs/config.py

@@ -0,0 +1,103 @@
+"""Configuration loading: merge defaults with .riggs/config.toml."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, fields
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TrustConfig:
+    score_success: float = 1.0
+    score_suboptimal: float = 0.7
+    score_mode_switch_agent: float = 0.8
+    score_mode_switch_controller: float = 0.3
+    score_failure: float = 0.2
+    score_path_denial: float = 0.1
+    score_repeated_failure: float = 0.0
+    alpha_short: float = 0.4
+    alpha_session: float = 0.08
+    alpha_baseline: float = 0.02
+    tighten_threshold: float = 0.3
+    auto_tighten_threshold: float = 0.5
+    loosen_threshold: float = 0.9
+    loosen_sustained_turns: int = 20
+
+
+@dataclass
+class RatchetConfig:
+    min_frequency: int = 5
+    min_sessions: int = 3
+    min_success_rate: float = 0.8
+    lookback_days: int = 30
+
+
+@dataclass
+class SandboxConfig:
+    memory_headroom: float = 2.0
+    timeout_headroom: float = 3.0
+    cpu_headroom: float = 2.0
+    min_runs_for_tightening: int = 5
+
+
+@dataclass
+class MetricsConfig:
+    default_period_days: int = 30
+
+
+@dataclass
+class StoreConfig:
+    path: str = ".riggs/store.duckdb"
+
+
+@dataclass
+class RiggsConfig:
+    trust: TrustConfig = field(default_factory=TrustConfig)
+    ratchet: RatchetConfig = field(default_factory=RatchetConfig)
+    sandbox: SandboxConfig = field(default_factory=SandboxConfig)
+    metrics: MetricsConfig = field(default_factory=MetricsConfig)
+    store: StoreConfig = field(default_factory=StoreConfig)
+
+
+def _load_defaults() -> dict[str, Any]:
+    """Load the shipped defaults/config.toml."""
+    defaults_ref = resources.files("agent_riggs") / "defaults" / "config.toml"
+    return tomllib.loads(defaults_ref.read_text(encoding="utf-8"))
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Merge override into base, recursing into nested dicts."""
+    merged = dict(base)
+    for key, value in override.items():
+        if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+            merged[key] = _deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _dict_to_dataclass(cls: type, data: dict[str, Any]) -> Any:
+    """Convert a dict to a dataclass, ignoring unknown keys."""
+    known = {f.name for f in fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in known})
+
+
+def load_config(project_root: Path) -> RiggsConfig:
+    """Load config: defaults merged with .riggs/config.toml."""
+    merged = _load_defaults()
+
+    user_path = project_root / ".riggs" / "config.toml"
+    if user_path.exists():
+        user = tomllib.loads(user_path.read_text(encoding="utf-8"))
+        merged = _deep_merge(merged, user)
+
+    return RiggsConfig(
+        trust=_dict_to_dataclass(TrustConfig, merged.get("trust", {})),
+        ratchet=_dict_to_dataclass(RatchetConfig, merged.get("ratchet", {})),
+        sandbox=_dict_to_dataclass(SandboxConfig, merged.get("sandbox", {})),
+        metrics=_dict_to_dataclass(MetricsConfig, merged.get("metrics", {})),
+        store=_dict_to_dataclass(StoreConfig, merged.get("store", {})),
+    )

agent_riggs/defaults/config.toml

@@ -0,0 +1,35 @@
+[trust]
+score_success = 1.0
+score_suboptimal = 0.7
+score_mode_switch_agent = 0.8
+score_mode_switch_controller = 0.3
+score_failure = 0.2
+score_path_denial = 0.1
+score_repeated_failure = 0.0
+
+alpha_short = 0.4
+alpha_session = 0.08
+alpha_baseline = 0.02
+
+tighten_threshold = 0.3
+auto_tighten_threshold = 0.5
+loosen_threshold = 0.9
+loosen_sustained_turns = 20
+
+[ratchet]
+min_frequency = 5
+min_sessions = 3
+min_success_rate = 0.8
+lookback_days = 30
+
+[sandbox]
+memory_headroom = 2.0
+timeout_headroom = 3.0
+cpu_headroom = 2.0
+min_runs_for_tightening = 5
+
+[metrics]
+default_period_days = 30
+
+[store]
+path = ".riggs/store.duckdb"