code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/puppy_kennel/commands.py

@@ -0,0 +1,206 @@
+"""Slash commands for humans interacting with the kennel.
+
+Sub-commands under ``/kennel``:
+
+* ``/kennel``                 — Show stats and recent activity
+* ``/kennel search <query>``  — FTS5 search the current recall scope
+* ``/kennel wings``           — List all wings and drawer counts
+* ``/kennel stats``           — Storage stats and totals
+* ``/kennel help``            — Usage hint
+
+All commands return ``True`` to mark them handled (per callback contract)
+or ``None`` to let other plugins try. ``False`` is never returned because
+we own the ``/kennel`` prefix unconditionally.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from code_puppy.messaging import emit_error, emit_info, emit_success, emit_warning
+
+from . import kennel
+from .config import DB_PATH
+from .state import is_enabled, set_enabled
+from .wings import default_recall_scope, detect_cwd
+
+
+def _reload_current_agent() -> None:
+    """Rebuild the active agent so its tool list reflects the new kennel state.
+
+    Toggling memory on/off changes what ``register_agent_tools`` advertises,
+    but the live agent has already baked its tools in at construction time.
+    Without a reload, ``/kennel disable`` would leave the kennel tools
+    dangling on the agent (and ``/kennel enable`` wouldn't add them back)
+    until the next natural reload. Fail soft — toggling persisted fine
+    even if the reload trips.
+    """
+    try:
+        from code_puppy.agents.agent_manager import get_current_agent
+
+        get_current_agent().reload_code_generation_agent()
+    except Exception as exc:  # noqa: BLE001
+        emit_error(f"Could not reload agent after kennel toggle: {exc!r}")
+
+
+_COMMAND = "kennel"
+_HELP_LINES: tuple[tuple[str, str], ...] = (
+    ("kennel", "Puppy Kennel — local memory: search, stats, wings"),
+)
+
+
+def _parse(command: str) -> tuple[str, str]:
+    """Split ``/kennel <sub> <rest>`` into ``(sub, rest)``."""
+    body = command.lstrip("/").strip()
+    if body.startswith(_COMMAND):
+        body = body[len(_COMMAND) :].strip()
+    parts = body.split(None, 1)
+    sub = parts[0].lower() if parts else ""
+    rest = parts[1] if len(parts) > 1 else ""
+    return sub, rest
+
+
+def _humanize_bytes(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024:
+            return f"{n:.1f} {unit}"
+        n /= 1024  # type: ignore[assignment]
+    return f"{n:.1f} TB"
+
+
+def _cmd_stats() -> bool:
+    total = kennel.count_drawers()
+    wings = kennel.list_wings()
+    db_size = DB_PATH.stat().st_size if DB_PATH.exists() else 0
+    state = "enabled" if is_enabled() else "DISABLED"
+    emit_info(f"Puppy Kennel at `{DB_PATH}`")
+    emit_info(f"  state   : {state}")
+    emit_info(f"  drawers : {total}")
+    emit_info(f"  wings   : {len(wings)}")
+    emit_info(f"  on disk : {_humanize_bytes(db_size)}")
+    return True
+
+
+def _cmd_status() -> bool:
+    if is_enabled():
+        emit_success("Puppy Kennel memory is ENABLED.")
+    else:
+        emit_warning(
+            "Puppy Kennel memory is DISABLED. Run /kennel enable to turn it on."
+        )
+    return True
+
+
+def _cmd_enable() -> bool:
+    if is_enabled():
+        emit_info("Puppy Kennel memory is already enabled.")
+        return True
+    try:
+        set_enabled(True)
+    except Exception as exc:  # noqa: BLE001
+        emit_warning(f"Could not persist enabled state: {exc!r}")
+        return True
+    _reload_current_agent()
+    emit_success("Puppy Kennel memory ENABLED. New runs will be recorded and recalled.")
+    return True
+
+
+def _cmd_disable() -> bool:
+    if not is_enabled():
+        emit_info("Puppy Kennel memory is already disabled.")
+        return True
+    try:
+        set_enabled(False)
+    except Exception as exc:  # noqa: BLE001
+        emit_warning(f"Could not persist disabled state: {exc!r}")
+        return True
+    _reload_current_agent()
+    emit_success(
+        "Puppy Kennel memory DISABLED. Existing drawers remain on disk; "
+        "recording and recall are paused. Run /kennel enable to resume."
+    )
+    return True
+
+
+def _cmd_wings() -> bool:
+    wings = kennel.list_wings()
+    if not wings:
+        emit_warning("No wings in the kennel yet.")
+        return True
+    emit_info(f"{len(wings)} wing(s):")
+    for w in wings:
+        n = kennel.count_drawers(wing_name=w)
+        emit_info(f"  {w}  ({n} drawer{'s' if n != 1 else ''})")
+    return True
+
+
+def _cmd_search(query: str) -> bool:
+    if not query.strip():
+        emit_warning("Usage: /kennel search <your query>")
+        return True
+    wings = default_recall_scope("code-puppy", detect_cwd())
+    hits = kennel.search_drawers_multi(query, wing_names=wings, limit=5)
+    if not hits:
+        emit_warning(f"No hits for '{query}' in scope {wings}")
+        return True
+    emit_success(f"{len(hits)} hit(s) for '{query}':")
+    for d in hits:
+        agent = (d.metadata or {}).get("agent", "?")
+        preview = d.content[:200].replace("\n", " ")
+        emit_info(f"  [{d.ts}] {agent}: {preview}{'…' if len(d.content) > 200 else ''}")
+    return True
+
+
+def _cmd_help() -> bool:
+    emit_info("Puppy Kennel commands:")
+    emit_info("  /kennel                 - stats + recent activity")
+    emit_info("  /kennel search <query>  - FTS5 search across default scope")
+    emit_info("  /kennel wings           - list wings with drawer counts")
+    emit_info("  /kennel stats           - storage stats + enabled state")
+    emit_info("  /kennel status          - is memory enabled?")
+    emit_info("  /kennel enable          - turn memory on")
+    emit_info("  /kennel disable         - turn memory off (drawers preserved)")
+    emit_info("  /kennel help            - this message")
+    return True
+
+
+def _cmd_default_overview() -> bool:
+    """Bare ``/kennel`` — show stats + a tiny preview of the recent block."""
+    _cmd_stats()
+    from .retriever import build_recall_block
+
+    block = build_recall_block()
+    if block:
+        emit_info("")
+        emit_info(block)
+    return True
+
+
+def handle(command: str, name: str) -> Any:
+    """Dispatch ``/kennel`` and aliases. Returns ``None`` for non-kennel cmds."""
+    if name != _COMMAND:
+        return None
+    sub, rest = _parse(command)
+    if not sub:
+        return _cmd_default_overview()
+    if sub == "search":
+        return _cmd_search(rest)
+    if sub == "wings":
+        return _cmd_wings()
+    if sub == "stats":
+        return _cmd_stats()
+    if sub == "status":
+        return _cmd_status()
+    if sub in ("enable", "on"):
+        return _cmd_enable()
+    if sub in ("disable", "off"):
+        return _cmd_disable()
+    if sub in ("help", "?"):
+        return _cmd_help()
+    emit_warning(f"Unknown /kennel subcommand: '{sub}'")
+    return _cmd_help()
+
+
+def help_entries() -> list[tuple[str, str]]:
+    """``custom_command_help`` callback — list ``/kennel`` in /help."""
+    return list(_HELP_LINES)

code_puppy_core_plugins/puppy_kennel/config.py

@@ -0,0 +1,36 @@
+"""Configuration for the puppy_kennel plugin.
+
+Single source of truth for paths, defaults, and tunable knobs. The
+on/off toggle lives in ``state.py`` and is persisted in ``puppy.cfg``
+under ``kennel_enabled`` -- see that module.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# Root directory for the kennel on disk.
+KENNEL_ROOT = Path(
+    os.environ.get("PUPPY_KENNEL_ROOT", Path.home() / ".code_puppy" / "kennel")
+)
+
+# The SQLite database file lives inside the kennel root.
+DB_PATH = KENNEL_ROOT / "kennel.db"
+
+# Prompt-packing budget for the recall block; estimate tokens at ~4 chars each
+# to avoid a tokenizer dependency.
+PROMPT_BUDGET_TOKENS = int(os.environ.get("PUPPY_KENNEL_PROMPT_BUDGET", "1500"))
+CHARS_PER_TOKEN = 4
+PROMPT_BUDGET_CHARS = PROMPT_BUDGET_TOKENS * CHARS_PER_TOKEN
+
+# Per-class quotas. The remainder goes to recent context (P2).
+USER_PREFS_QUOTA = float(os.environ.get("PUPPY_KENNEL_USER_PREFS_QUOTA", "0.30"))
+STICKY_QUOTA = float(os.environ.get("PUPPY_KENNEL_STICKY_QUOTA", "0.30"))
+
+# Drawers shorter than this are noise — skip them in the recall block.
+MIN_DRAWER_CHARS = int(os.environ.get("PUPPY_KENNEL_MIN_DRAWER_CHARS", "80"))
+
+# Cap on stored drawer text length (chars). Keeps SQLite happy and FTS indexes
+# from getting comically large. Truncation is fine — verbatim within reason.
+MAX_DRAWER_CHARS = int(os.environ.get("PUPPY_KENNEL_MAX_DRAWER_CHARS", "32000"))

code_puppy_core_plugins/puppy_kennel/kennel.py

@@ -0,0 +1,368 @@
+"""The Kennel — storage layer for puppy_kennel.
+
+A thin wrapper around SQLite that exposes the wing/room/drawer vocabulary
+without leaking SQL all over the rest of the plugin. Connections are
+short-lived and use a per-call ``with sqlite3.connect(...)`` block so we
+never accidentally hold the write lock across awaits.
+
+WAL mode means many readers + one writer is safe across processes.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+from .config import DB_PATH, MAX_DRAWER_CHARS, KENNEL_ROOT
+from .schema import PRAGMAS, SCHEMA_SQL
+
+
+@dataclass(slots=True, frozen=True)
+class Drawer:
+    """A verbatim chunk of remembered content."""
+
+    id: int
+    room_id: int
+    role: str | None
+    content: str
+    ts: str
+    session_id: str | None
+    metadata: dict[str, Any] | None
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _ensure_root() -> None:
+    KENNEL_ROOT.mkdir(parents=True, exist_ok=True)
+
+
+@contextmanager
+def _connect(path: Path = DB_PATH) -> Iterator[sqlite3.Connection]:
+    """Yield a SQLite connection with the kennel PRAGMAs applied.
+
+    Short-lived by design: open, do work, close. WAL handles concurrency.
+    """
+    _ensure_root()
+    conn = sqlite3.connect(path, timeout=10.0, isolation_level=None)
+    try:
+        conn.row_factory = sqlite3.Row
+        for pragma in PRAGMAS:
+            conn.execute(pragma)
+        yield conn
+    finally:
+        conn.close()
+
+
+def initialize() -> None:
+    """Create tables, indexes, and FTS triggers if they don't exist.
+
+    Idempotent. Safe to call on every plugin load.
+    """
+    with _connect() as conn:
+        conn.executescript(SCHEMA_SQL)
+
+
+# Wings and rooms (simple upserts)
+
+
+def ensure_wing(name: str, metadata: dict[str, Any] | None = None) -> int:
+    """Return the id of the wing named ``name``, creating it if missing.
+
+    Uses ``INSERT OR IGNORE`` to dodge the SELECT-then-INSERT TOCTOU race
+    between concurrent processes. The single INSERT is atomic; if another
+    writer beat us to it the row already exists and we just re-SELECT.
+    """
+    payload = json.dumps(metadata) if metadata else None
+    with _connect() as conn:
+        conn.execute(
+            "INSERT OR IGNORE INTO wings(name, created_at, metadata) VALUES (?, ?, ?)",
+            (name, _now_iso(), payload),
+        )
+        row = conn.execute("SELECT id FROM wings WHERE name = ?", (name,)).fetchone()
+        return int(row["id"])
+
+
+def ensure_room(wing_id: int, name: str, metadata: dict[str, Any] | None = None) -> int:
+    """Return the id of the room (wing_id, name), creating it if missing.
+
+    Same race-free pattern as ``ensure_wing``.
+    """
+    payload = json.dumps(metadata) if metadata else None
+    with _connect() as conn:
+        conn.execute(
+            "INSERT OR IGNORE INTO rooms(wing_id, name, created_at, metadata) "
+            "VALUES (?, ?, ?, ?)",
+            (wing_id, name, _now_iso(), payload),
+        )
+        row = conn.execute(
+            "SELECT id FROM rooms WHERE wing_id = ? AND name = ?",
+            (wing_id, name),
+        ).fetchone()
+        return int(row["id"])
+
+
+# Drawers — remembered content
+
+
+def add_drawer(
+    room_id: int,
+    content: str,
+    role: str | None = None,
+    session_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> int:
+    """Append a verbatim drawer to a room. Returns the new drawer id."""
+    if not content or not content.strip():
+        return 0
+    if len(content) > MAX_DRAWER_CHARS:
+        content = content[:MAX_DRAWER_CHARS] + "\n...[truncated]"
+    payload = json.dumps(metadata) if metadata else None
+    with _connect() as conn:
+        cur = conn.execute(
+            "INSERT INTO drawers(room_id, role, content, ts, session_id, metadata) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (room_id, role, content, _now_iso(), session_id, payload),
+        )
+        return int(cur.lastrowid)
+
+
+def _row_to_drawer(row: sqlite3.Row) -> Drawer:
+    meta_raw = row["metadata"] if "metadata" in row.keys() else None
+    meta = json.loads(meta_raw) if meta_raw else None
+    return Drawer(
+        id=int(row["id"]),
+        room_id=int(row["room_id"]),
+        role=row["role"],
+        content=row["content"],
+        ts=row["ts"],
+        session_id=row["session_id"],
+        metadata=meta,
+    )
+
+
+def recent_drawers(
+    wing_name: str, limit: int = 5, role: str | None = None
+) -> list[Drawer]:
+    """Return the most recent drawers in a wing, optionally role-filtered.
+
+    ``role=None`` returns every role (assistant + note + ...). Pass a
+    specific value like ``"note"`` to get just sticky writes from
+    ``kennel_remember``.
+    """
+    sql_parts = [
+        "SELECT d.* FROM drawers d",
+        "JOIN rooms r ON r.id = d.room_id",
+        "JOIN wings w ON w.id = r.wing_id",
+        "WHERE w.name = ?",
+    ]
+    params: list[Any] = [wing_name]
+    if role is not None:
+        sql_parts.append("AND d.role = ?")
+        params.append(role)
+    sql_parts.append("ORDER BY d.ts DESC LIMIT ?")
+    params.append(limit)
+    with _connect() as conn:
+        rows = conn.execute(" ".join(sql_parts), params).fetchall()
+    return [_row_to_drawer(r) for r in rows]
+
+
+def recent_drawers_multi(
+    wing_names: list[str] | None = None,
+    limit: int = 5,
+) -> list[Drawer]:
+    """Recent drawers across multiple wings, deduplicated by content.
+
+    Same dual-write workaround as ``search_drawers_multi``: over-fetch then
+    dedupe by content, keeping the most recent copy of each unique drawer.
+    """
+    sql_parts = [
+        "SELECT d.* FROM drawers d",
+        "JOIN rooms r ON r.id = d.room_id",
+        "JOIN wings w ON w.id = r.wing_id",
+    ]
+    params: list[Any] = []
+    if wing_names:
+        placeholders = ",".join("?" * len(wing_names))
+        sql_parts.append(f"WHERE w.name IN ({placeholders})")
+        params.extend(wing_names)
+    sql_parts.append("ORDER BY d.ts DESC LIMIT ?")
+    params.append(max(limit * 4, limit))
+
+    with _connect() as conn:
+        rows = conn.execute(" ".join(sql_parts), params).fetchall()
+
+    seen: set[str] = set()
+    out: list[Drawer] = []
+    for row in rows:
+        drawer = _row_to_drawer(row)
+        if drawer.content in seen:
+            continue
+        seen.add(drawer.content)
+        out.append(drawer)
+        if len(out) >= limit:
+            break
+    return out
+
+
+def write_note(
+    wing_name: str,
+    room_name: str,
+    content: str,
+    role: str = "note",
+    session_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> int:
+    """High-level helper: ensure (wing, room) exist, then add a drawer.
+
+    Returns the new drawer id, or 0 if the content was blank.
+    """
+    wing_id = ensure_wing(wing_name)
+    room_id = ensure_room(wing_id, room_name)
+    return add_drawer(
+        room_id=room_id,
+        content=content,
+        role=role,
+        session_id=session_id,
+        metadata=metadata,
+    )
+
+
+def wings_with_counts() -> list[tuple[str, int]]:
+    """List every wing with its drawer count. Sorted by name."""
+    with _connect() as conn:
+        rows = conn.execute(
+            """
+            SELECT w.name AS name, COUNT(d.id) AS n
+            FROM wings w
+            LEFT JOIN rooms r ON r.wing_id = w.id
+            LEFT JOIN drawers d ON d.room_id = r.id
+            GROUP BY w.id, w.name
+            ORDER BY w.name
+            """
+        ).fetchall()
+    return [(r["name"], int(r["n"])) for r in rows]
+
+
+def search_drawers(
+    query: str,
+    wing_name: str | None = None,
+    limit: int = 5,
+) -> list[Drawer]:
+    """FTS5 BM25 search across drawers, optionally scoped to a single wing."""
+    if not query or not query.strip():
+        return []
+    fts_query = _sanitize_fts_query(query)
+    if not fts_query:
+        return []
+
+    sql_parts = [
+        "SELECT d.* FROM drawers d",
+        "JOIN drawers_fts f ON f.rowid = d.id",
+        "JOIN rooms r ON r.id = d.room_id",
+        "JOIN wings w ON w.id = r.wing_id",
+        "WHERE drawers_fts MATCH ?",
+    ]
+    params: list[Any] = [fts_query]
+    if wing_name:
+        sql_parts.append("AND w.name = ?")
+        params.append(wing_name)
+    sql_parts.append("ORDER BY bm25(drawers_fts) ASC LIMIT ?")
+    params.append(limit)
+
+    with _connect() as conn:
+        rows = conn.execute(" ".join(sql_parts), params).fetchall()
+    return [_row_to_drawer(r) for r in rows]
+
+
+def search_drawers_multi(
+    query: str,
+    wing_names: list[str] | None = None,
+    limit: int = 5,
+) -> list[Drawer]:
+    """Search multiple wings and dedupe by content.
+
+    Because the recorder currently dual-writes every response to the repo
+    wing AND the agent wing, naive multi-wing search returns the same text
+    twice. We over-fetch, then dedupe by content keeping the best-scoring
+    drawer per unique text. This is a pragmatic workaround for the schema
+    duplication noted in the README; remove once the schema is normalised.
+    """
+    if not query or not query.strip():
+        return []
+    fts_query = _sanitize_fts_query(query)
+    if not fts_query:
+        return []
+
+    sql_parts = [
+        "SELECT d.* FROM drawers d",
+        "JOIN drawers_fts f ON f.rowid = d.id",
+        "JOIN rooms r ON r.id = d.room_id",
+        "JOIN wings w ON w.id = r.wing_id",
+        "WHERE drawers_fts MATCH ?",
+    ]
+    params: list[Any] = [fts_query]
+    if wing_names:
+        placeholders = ",".join("?" * len(wing_names))
+        sql_parts.append(f"AND w.name IN ({placeholders})")
+        params.extend(wing_names)
+    # Over-fetch so dedup still leaves us with ``limit`` distinct drawers.
+    sql_parts.append("ORDER BY bm25(drawers_fts) ASC LIMIT ?")
+    params.append(max(limit * 4, limit))
+
+    with _connect() as conn:
+        rows = conn.execute(" ".join(sql_parts), params).fetchall()
+
+    seen: set[str] = set()
+    out: list[Drawer] = []
+    for row in rows:
+        drawer = _row_to_drawer(row)
+        if drawer.content in seen:
+            continue
+        seen.add(drawer.content)
+        out.append(drawer)
+        if len(out) >= limit:
+            break
+    return out
+
+
+# Quote each token and OR them: FTS5 punctuation otherwise acts as operators.
+_FTS_BAD = set('"()*:^-+')
+
+
+def _sanitize_fts_query(query: str) -> str:
+    tokens = []
+    for raw in query.split():
+        stripped = "".join(ch for ch in raw if ch not in _FTS_BAD).strip()
+        if len(stripped) >= 2:
+            tokens.append(f'"{stripped}"')
+    return " OR ".join(tokens)
+
+
+def list_wings() -> list[str]:
+    with _connect() as conn:
+        rows = conn.execute("SELECT name FROM wings ORDER BY name").fetchall()
+    return [r["name"] for r in rows]
+
+
+def count_drawers(wing_name: str | None = None) -> int:
+    with _connect() as conn:
+        if wing_name is None:
+            row = conn.execute("SELECT COUNT(*) AS n FROM drawers").fetchone()
+        else:
+            row = conn.execute(
+                """
+                SELECT COUNT(*) AS n FROM drawers d
+                JOIN rooms r ON r.id = d.room_id
+                JOIN wings w ON w.id = r.wing_id
+                WHERE w.name = ?
+                """,
+                (wing_name,),
+            ).fetchone()
+    return int(row["n"]) if row else 0