polyrob 0.5.0__py3-none-any.whl

modules/pfp/renderer.py

@@ -0,0 +1,85 @@
+"""Headless still renderer — runs the EXACT ``avatar/mindprint.js`` engine in
+Chromium (Playwright) and writes a deterministic PNG. Python only orchestrates;
+every pixel comes from the committed JS engine.
+
+Playwright is an OPTIONAL extra (``pip install '.[browser]' && playwright install
+chromium``). When it (or Chromium) is absent, :func:`render_still` raises
+:class:`PfpRenderUnavailable` so callers (``store.generate_pfp``) can fall back to the
+committed reference PNG. The renderer is never on a runtime/interactive path.
+
+Engine loading: the engine is a CLASSIC script (window globals, no ES-module export),
+injected via ``set_content`` on ``about:blank`` — no ``file://`` / ESM / CSP concerns
+and no local HTTP server.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .config import render_seed, normalized_override
+
+_AVATAR = Path(__file__).resolve().parents[2] / "avatar"
+_ENGINE = _AVATAR / "mindprint.js"
+
+# Renders a deterministic STILL and returns the PNG data-URL + derived meta.
+_JS_RENDER = """(a) => {
+  const mp = new Mindprint(a.seed);
+  Object.assign(mp.override, a.override || {});
+  const cv = document.getElementById('c');
+  cv.width = cv.height = a.size;
+  mp.N = 0;
+  mp.render(cv.getContext('2d'), a.size, 1.0, 0, {still: true});
+  mp.N = 0;
+  return {dataURL: cv.toDataURL('image/png'), traits: mp.traitList(),
+          hex: mp.hex, voice: mp.voiceCfg()};
+}"""
+
+
+class PfpRenderUnavailable(RuntimeError):
+    """Raised when Playwright/Chromium is not available to render a still."""
+
+
+@dataclass
+class RenderResult:
+    path: Path
+    traits: Dict[str, Any]
+    seed_hex: str
+    voice: Dict[str, float]
+
+
+def render_still(config: Dict[str, Any], out_png, *, size: Optional[int] = None) -> RenderResult:
+    """Render ``config`` to ``out_png`` via headless Chromium. Raises
+    :class:`PfpRenderUnavailable` if Playwright/Chromium is missing."""
+    try:
+        from playwright.sync_api import sync_playwright, Error as PlaywrightError
+    except ImportError as e:  # extra not installed
+        raise PfpRenderUnavailable("playwright not installed ('.[browser]')") from e
+
+    engine = _ENGINE.read_text(encoding="utf-8")
+    seed = render_seed(config)
+    override = normalized_override(config.get("override", {}) or {})
+    sz = int(size or config.get("size") or 768)
+    html = (
+        "<!doctype html><meta charset='utf-8'>"
+        "<canvas id='c'></canvas><script>" + engine + "</script>"
+    )
+
+    try:
+        with sync_playwright() as pw:
+            browser = pw.chromium.launch(args=["--disable-gpu"])
+            try:
+                page = browser.new_page()
+                page.set_content(html, wait_until="load")
+                res = page.evaluate(_JS_RENDER, {"seed": seed, "override": override, "size": sz})
+            finally:
+                browser.close()
+    except PlaywrightError as e:  # chromium binary missing / launch failure
+        raise PfpRenderUnavailable(f"chromium unavailable: {e}") from e
+
+    data = base64.b64decode(res["dataURL"].split(",", 1)[1])
+    out_png = Path(out_png)
+    out_png.parent.mkdir(parents=True, exist_ok=True)
+    out_png.write_bytes(data)
+    return RenderResult(path=out_png, traits=res["traits"], seed_hex=res["hex"], voice=res["voice"])

modules/pfp/store.py

@@ -0,0 +1,82 @@
+"""Persist the frozen avatar into the instance identity home.
+
+``generate_pfp`` writes ``<home>/identity/{instance_id}/pfp/{pfp.png,pfp.json}``. It
+is idempotent ("created once" — a no-op if the PNG exists unless ``force``), and it
+falls back to a committed reference PNG when Chromium/Playwright is unavailable, so the
+avatar always materializes even headless / in CI. Trait/voice/seed_hex meta is computed
+by the pure-Python mesh (no browser), so the identity record is complete on either path.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from core.instance import pfp_path, pfp_dir, load_pfp_meta, DEFAULT_INSTANCE_ID
+from .config import load_frozen_config
+from .mesh import Mesh
+from .renderer import render_still, PfpRenderUnavailable
+
+_AVATAR = Path(__file__).resolve().parents[2] / "avatar"
+_DEFAULT_CONFIG = _AVATAR / "config" / "rob.json"
+_DEFAULT_REFERENCE = _AVATAR / "renders" / "rob.png"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def generate_pfp(
+    home_dir,
+    instance_id: str = DEFAULT_INSTANCE_ID,
+    *,
+    config: Optional[Dict[str, Any]] = None,
+    config_path=None,
+    force: bool = False,
+    reference_png=None,
+    size: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Render + persist the instance avatar; return the ``pfp.json`` meta.
+
+    Idempotent unless ``force``. Raises :class:`PfpRenderUnavailable` only if BOTH the
+    headless render fails AND no reference PNG is available.
+    """
+    cfg = config if config is not None else load_frozen_config(config_path or _DEFAULT_CONFIG)
+
+    target = pfp_path(home_dir, instance_id)
+    meta_path = pfp_dir(home_dir, instance_id) / "pfp.json"
+
+    if target.is_file() and not force:
+        existing = load_pfp_meta(home_dir, instance_id)
+        if existing is not None:
+            return existing  # created once — no rewrite
+
+    mesh = Mesh(cfg)  # traits/voice/seed_hex — pure Python, no browser
+
+    try:
+        render_still(cfg, target, size=size)
+        rendered_by = "playwright-chromium"
+    except PfpRenderUnavailable:
+        ref = Path(reference_png) if reference_png else _DEFAULT_REFERENCE
+        if ref.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(ref, target)
+            rendered_by = "committed-reference"
+        else:
+            raise
+
+    meta: Dict[str, Any] = {
+        **cfg,
+        "instance_id": instance_id,
+        "seed_hex": mesh.hex,
+        "traits": mesh.traits(),
+        "voice": mesh.voice(),
+        "config_ref": "avatar/config/rob.json",
+        "rendered_by": rendered_by,
+        "created_at": _now_iso(),
+    }
+    meta_path.parent.mkdir(parents=True, exist_ok=True)
+    meta_path.write_text(json.dumps(meta, indent=2), encoding="utf-8")
+    return meta

modules/skills/__init__.py

@@ -0,0 +1 @@
+"""Skill provenance + usage metrics (W2-D)."""

modules/skills/skill_usage.py

@@ -0,0 +1,248 @@
+"""Skill provenance + usage metrics (W2-D).
+
+Answers the question the safety brief requires of writable skills: *do authored
+skills actually get reused?* Two tiny tenant-scoped tables in
+``<data_dir>/skill_usage.db`` (shared WAL+jitter helpers):
+
+- ``skill_provenance`` — who authored a skill and when (``user``/``agent``/
+  ``background_review``);
+- ``skill_usage`` — per-(skill,user) load_count + last_used_at, bumped each time the
+  agent pulls a skill body via ``load_skill``.
+
+Feeds W5 (curator: archive unused authored skills) and W7 (`/insights`: authored-skill
+reuse %). Pure storage; fail-open at the call sites (a metrics write must never break
+a skill load).
+"""
+from __future__ import annotations
+
+import os
+import time
+import threading
+from typing import Callable, Dict, List, Optional
+
+from core.identity import is_anonymous
+from core.sqlite_util import execute_retry, wal_connect
+
+
+class SkillUsageStore:
+    def __init__(self, db_path: str, *, clock: Callable[[], float] = time.time):
+        self.db_path = db_path
+        self._now = clock
+        parent = os.path.dirname(db_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        conn = wal_connect(self.db_path)
+        try:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS skill_provenance (
+                    skill_id TEXT NOT NULL,
+                    user_id TEXT NOT NULL,
+                    created_by TEXT NOT NULL,
+                    created_at REAL NOT NULL,
+                    PRIMARY KEY (skill_id, user_id)
+                );
+                CREATE TABLE IF NOT EXISTS skill_usage (
+                    skill_id TEXT NOT NULL,
+                    user_id TEXT NOT NULL,
+                    load_count INTEGER NOT NULL DEFAULT 0,
+                    last_used_at REAL,
+                    PRIMARY KEY (skill_id, user_id)
+                );
+                CREATE TABLE IF NOT EXISTS curator_state (
+                    key TEXT PRIMARY KEY,
+                    value TEXT
+                );
+                CREATE TABLE IF NOT EXISTS skill_install_audit (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    name TEXT NOT NULL,
+                    user_id TEXT NOT NULL,
+                    source TEXT NOT NULL,
+                    resolved_sha TEXT,
+                    approver TEXT NOT NULL,
+                    ts REAL NOT NULL
+                );
+                """
+            )
+            conn.commit()
+        finally:
+            conn.close()
+
+    # --- provenance ----------------------------------------------------------
+
+    def record_provenance(self, skill_id: str, user_id: str, created_by: str) -> None:
+        if is_anonymous(user_id):
+            return
+        execute_retry(
+            self.db_path,
+            """INSERT INTO skill_provenance (skill_id,user_id,created_by,created_at)
+               VALUES (?,?,?,?)
+               ON CONFLICT(skill_id,user_id) DO UPDATE SET created_by=excluded.created_by""",
+            (skill_id, user_id, created_by, self._now()),
+        )
+
+    def get_provenance(self, skill_id: str, user_id: str) -> Optional[Dict]:
+        row = execute_retry(
+            self.db_path,
+            "SELECT * FROM skill_provenance WHERE skill_id=? AND user_id=?",
+            (skill_id, user_id), fetch="one",
+        )
+        return dict(row) if row else None
+
+    # --- usage ---------------------------------------------------------------
+
+    def bump_load(self, skill_id: str, user_id: str) -> None:
+        if is_anonymous(user_id):
+            return
+        execute_retry(
+            self.db_path,
+            """INSERT INTO skill_usage (skill_id,user_id,load_count,last_used_at)
+               VALUES (?,?,1,?)
+               ON CONFLICT(skill_id,user_id)
+               DO UPDATE SET load_count=load_count+1, last_used_at=excluded.last_used_at""",
+            (skill_id, user_id, self._now()),
+        )
+
+    def get_usage(self, skill_id: str, user_id: str) -> Dict:
+        row = execute_retry(
+            self.db_path,
+            "SELECT * FROM skill_usage WHERE skill_id=? AND user_id=?",
+            (skill_id, user_id), fetch="one",
+        )
+        return dict(row) if row else {"skill_id": skill_id, "user_id": user_id,
+                                      "load_count": 0, "last_used_at": None}
+
+    def list_authored(self, user_id: Optional[str] = None,
+                      created_by: Optional[List[str]] = None) -> List[Dict]:
+        """Join provenance+usage for authored skills (curator/insights feed)."""
+        sql = ("SELECT p.skill_id, p.user_id, p.created_by, p.created_at, "
+               "COALESCE(u.load_count,0) AS load_count, u.last_used_at "
+               "FROM skill_provenance p LEFT JOIN skill_usage u "
+               "ON p.skill_id=u.skill_id AND p.user_id=u.user_id")
+        clauses, params = [], []
+        if user_id is not None:
+            clauses.append("p.user_id=?"); params.append(user_id)
+        if created_by:
+            clauses.append("p.created_by IN (%s)" % ",".join("?" * len(created_by)))
+            params.extend(created_by)
+        if clauses:
+            sql += " WHERE " + " AND ".join(clauses)
+        rows = execute_retry(self.db_path, sql, tuple(params), fetch="all") or []
+        return [dict(r) for r in rows]
+
+    def authored_reuse_summary(self, user_id: Optional[str] = None) -> Dict:
+        """W7 /insights: did self-authored skills get reused?
+
+        Returns counts + reuse rate over agent/background-authored skills — the
+        measurement the writable-skills safety brief requires. Tenant-scoped when
+        user_id is given.
+        """
+        rows = self.list_authored(user_id=user_id, created_by=["agent", "background_review"])
+        total = len(rows)
+        reused = sum(1 for r in rows if (r.get("load_count") or 0) > 0)
+        by_author: Dict[str, int] = {}
+        for r in rows:
+            by_author[r["created_by"]] = by_author.get(r["created_by"], 0) + 1
+        return {
+            "authored_total": total,
+            "authored_reused": reused,
+            "reuse_rate": (reused / total) if total else 0.0,
+            "by_author": by_author,
+            "top": sorted(
+                ({"skill_id": r["skill_id"], "loads": r.get("load_count") or 0} for r in rows),
+                key=lambda d: d["loads"], reverse=True,
+            )[:10],
+        }
+
+    # --- curator state -------------------------------------------------------
+
+    def get_state(self, key: str) -> Optional[str]:
+        row = execute_retry(self.db_path, "SELECT value FROM curator_state WHERE key=?",
+                            (key,), fetch="one")
+        return row["value"] if row else None
+
+    def set_state(self, key: str, value: str) -> None:
+        execute_retry(
+            self.db_path,
+            "INSERT INTO curator_state (key,value) VALUES (?,?) "
+            "ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+            (key, value),
+        )
+
+    # --- install audit ---------------------------------------------------------
+
+    def record_install(self, name: str, *, user_id: str, source: str,
+                       resolved_sha: Optional[str] = None, approver: str,
+                       ts: Optional[float] = None) -> None:
+        """Append-only audit trail for `polyrob skill install`/`approve`: what
+        skill, whose tenant, where it came from (source + resolved commit SHA
+        when known), who approved it, and when. Never updates/dedupes — a
+        re-install/re-approve of the same name is a NEW event worth keeping."""
+        ts = self._now() if ts is None else ts
+        execute_retry(
+            self.db_path,
+            """INSERT INTO skill_install_audit
+                   (name,user_id,source,resolved_sha,approver,ts)
+               VALUES (?,?,?,?,?,?)""",
+            (name, user_id, source, resolved_sha, approver, ts),
+        )
+
+    def list_installs(self, user_id: Optional[str] = None) -> List[Dict]:
+        sql = "SELECT name,user_id,source,resolved_sha,approver,ts FROM skill_install_audit"
+        params: tuple = ()
+        if user_id is not None:
+            sql += " WHERE user_id=?"
+            params = (user_id,)
+        sql += " ORDER BY ts DESC"
+        rows = execute_retry(self.db_path, sql, params, fetch="all") or []
+        return [dict(r) for r in rows]
+
+
+# --- process-wide singleton (shares one db with the curator) -----------------
+
+_STORE_LOCK = threading.Lock()
+_STORE: Optional[SkillUsageStore] = None
+
+
+def _default_data_dir() -> str:
+    """Stable ABSOLUTE data dir so the singleton resolves the same file regardless of
+    cwd. Otherwise the relative ``"data"`` default (used by the load_skill/provenance
+    call sites) could resolve to a different directory than the curator's
+    ``config.data_dir`` (absolute), silently splitting reuse counts from the curator
+    and /insights. Anchored at the repo root (this file is modules/skills/skill_usage.py).
+    """
+    env = os.getenv("POLYROB_DATA_DIR")
+    if env:
+        return os.path.abspath(env)
+    repo_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    return os.path.join(repo_root, "data")
+
+
+def get_skill_usage_store(data_dir: Optional[str] = None) -> SkillUsageStore:
+    global _STORE
+    with _STORE_LOCK:
+        if _STORE is None:
+            dd = os.path.abspath(data_dir) if data_dir else _default_data_dir()
+            _STORE = SkillUsageStore(os.path.join(dd, "skill_usage.db"))
+        elif data_dir:
+            want = os.path.join(os.path.abspath(data_dir), "skill_usage.db")
+            if want != _STORE.db_path:
+                # First caller's path wins (singleton). Warn loudly if a later caller
+                # (e.g. the curator) expected a different db — that would desync metrics.
+                import logging
+                logging.getLogger(__name__).warning(
+                    "skill_usage store already bound to %s; ignoring requested %s "
+                    "(metrics/curator may read a different file than intended)",
+                    _STORE.db_path, want,
+                )
+        return _STORE
+
+
+def reset_skill_usage_store() -> None:
+    """Test seam."""
+    global _STORE
+    with _STORE_LOCK:
+        _STORE = None

modules/transcription/__init__.py

@@ -0,0 +1,24 @@
+"""Surface-agnostic speech-to-text (#9).
+
+The engine lives here, NOT in any surface, so every chat surface (Telegram today,
+WhatsApp/etc. tomorrow) downloads its own audio and hands raw bytes to one shared
+``Transcriber``. Keep transport-specific extraction in the surface; keep model/runtime
+concerns here.
+
+``build_transcriber()`` is the factory: a real faster-whisper transcriber when the
+extra is installed, else a ``NullTranscriber`` (returns "") so a misconfigured deploy
+degrades to "no transcript" instead of crashing the inbound spine.
+"""
+from .base import Transcriber, NullTranscriber
+
+__all__ = ["Transcriber", "NullTranscriber", "build_transcriber"]
+
+
+def build_transcriber(model_size: str = "base") -> Transcriber:
+    """Return a ready Transcriber. Falls back to NullTranscriber if faster-whisper isn't
+    importable (the model itself loads lazily on first transcribe)."""
+    try:
+        from .faster_whisper_transcriber import FasterWhisperTranscriber
+        return FasterWhisperTranscriber(model_size=model_size)
+    except Exception:  # import-time failure (extra missing) -> degrade, don't crash
+        return NullTranscriber()

modules/transcription/base.py

@@ -0,0 +1,20 @@
+"""Transcriber ABC + a no-op fallback. Surface-agnostic: bytes in, text out."""
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class Transcriber(ABC):
+    @abstractmethod
+    async def transcribe(
+        self, audio: bytes, *, mime: Optional[str] = None, language: Optional[str] = None
+    ) -> str:
+        """Transcribe raw audio bytes to text. Returns "" when nothing is recognized.
+        Implementations MUST be fail-open (never raise into the caller's inbound path)."""
+        ...
+
+
+class NullTranscriber(Transcriber):
+    """Used when transcription is disabled or the faster-whisper extra is unavailable."""
+
+    async def transcribe(self, audio: bytes, *, mime=None, language=None) -> str:
+        return ""

modules/transcription/faster_whisper_transcriber.py

@@ -0,0 +1,55 @@
+"""faster-whisper transcriber. The model loads lazily on first use and inference runs
+in a worker thread (faster-whisper is sync + CPU-bound), so a long transcription never
+blocks the event loop. Fail-open: any error returns "" (no transcript)."""
+import asyncio
+import logging
+import os
+import tempfile
+from typing import Optional
+
+from .base import Transcriber
+
+logger = logging.getLogger(__name__)
+
+
+class FasterWhisperTranscriber(Transcriber):
+    def __init__(self, model_size: str = "base", device: str = "cpu",
+                 compute_type: str = "int8") -> None:
+        self._model_size = model_size
+        self._device = device
+        self._compute_type = compute_type
+        self._model = None  # lazily constructed on first transcribe
+
+    def _ensure_model(self):
+        if self._model is None:
+            from faster_whisper import WhisperModel  # lazy: heavy import + optional extra
+            self._model = WhisperModel(
+                self._model_size, device=self._device, compute_type=self._compute_type
+            )
+        return self._model
+
+    async def transcribe(self, audio: bytes, *, mime: Optional[str] = None,
+                         language: Optional[str] = None) -> str:
+        if not audio:
+            return ""
+        try:
+            return await asyncio.to_thread(self._transcribe_sync, audio, language)
+        except Exception as e:  # fail-open: a transcription failure must not drop the msg
+            logger.warning("faster-whisper transcription failed: %s", e)
+            return ""
+
+    def _transcribe_sync(self, audio: bytes, language: Optional[str]) -> str:
+        model = self._ensure_model()
+        # faster-whisper reads from a path; Telegram voice is OGG/Opus, which ffmpeg
+        # (pulled in by faster-whisper) decodes by content, so the suffix is cosmetic.
+        with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as f:
+            f.write(audio)
+            path = f.name
+        try:
+            segments, _info = model.transcribe(path, language=language)
+            return "".join(seg.text for seg in segments).strip()
+        finally:
+            try:
+                os.unlink(path)
+            except OSError:
+                pass