palimpsests 0.2.0__py3-none-any.whl

palimpsests/__init__.py

@@ -0,0 +1,4 @@
+"""Palimpsests — a layered local-LLM inference engine."""
+
+__version__ = "0.2.0"
+__all__ = ["__version__"]

palimpsests/audit/__init__.py

@@ -0,0 +1,33 @@
+"""Audit subsystem — encrypted, append-only operation log.
+
+Public surface:
+
+- ``AuditLog``       — the encrypted store.
+- ``AuditEvent``     — one row read back.
+- ``AuditDenied``    — raised by gating when a capability is disabled.
+- ``audited``        — decorator that records an invocation.
+- ``get_audit_log`` / ``set_audit_log`` — process-wide singleton access.
+- ``generate_key`` / ``load_or_create_key`` — key management.
+"""
+from __future__ import annotations
+
+from .key_manager import generate_key, load_or_create_key
+from .log import (
+    AuditDenied,
+    AuditEvent,
+    AuditLog,
+    audited,
+    get_audit_log,
+    set_audit_log,
+)
+
+__all__ = [
+    "AuditLog",
+    "AuditEvent",
+    "AuditDenied",
+    "audited",
+    "get_audit_log",
+    "set_audit_log",
+    "generate_key",
+    "load_or_create_key",
+]

palimpsests/audit/key_manager.py

@@ -0,0 +1,77 @@
+"""Encryption key management for the audit log.
+
+The audit log is encrypted at rest. This module owns the single
+responsibility of producing and storing the symmetric key used for
+that encryption.
+
+Key lifecycle
+-------------
+- On first run, a fresh 256-bit key is generated and stored in the OS
+  keychain (Keychain on macOS, Credential Manager on Windows, Secret
+  Service on Linux) via ``keyring``.
+- On subsequent runs, the key is read back from the keychain.
+- Tests generate an ephemeral key per test and never touch the real
+  keychain (see the test fixtures).
+
+Why the OS keychain and not a file
+----------------------------------
+A key sitting in a dotfile next to the database is only as protected
+as the filesystem permissions — which is to say, not much against a
+process running as the same user. The OS keychain is the platform's
+purpose-built secret store; delegating to it means we inherit the
+platform's protections (biometric unlock, per-app ACLs) instead of
+reinventing them badly.
+
+Graceful degradation
+--------------------
+Headless Linux CI runners often have no Secret Service daemon. When
+the keychain is unavailable, callers may pass an explicit key (tests
+do exactly this). The module never silently falls back to an
+unencrypted or on-disk key — the caller must be explicit.
+"""
+from __future__ import annotations
+
+import secrets
+
+KEY_BYTES = 32  # 256-bit key
+SERVICE_NAME = "palimpsests-audit"
+KEY_USERNAME = "audit-db-key"
+
+
+def generate_key() -> bytes:
+    """Return a fresh cryptographically-strong 256-bit key."""
+    return secrets.token_bytes(KEY_BYTES)
+
+
+def load_or_create_key() -> bytes:
+    """Read the audit key from the OS keychain, creating it on first use.
+
+    Raises
+    ------
+    RuntimeError
+        If the OS keychain backend is unavailable. The caller is
+        expected to either provide an explicit key or surface the
+        error — we never silently degrade to a weaker key source.
+    """
+    try:
+        import keyring
+    except ImportError as e:  # pragma: no cover - import guard
+        raise RuntimeError(
+            "keyring is required to manage the audit key; "
+            "install it or pass an explicit key"
+        ) from e
+
+    try:
+        stored = keyring.get_password(SERVICE_NAME, KEY_USERNAME)
+    except Exception as e:  # keyring raises backend-specific errors
+        raise RuntimeError(
+            "OS keychain is unavailable; pass an explicit key instead"
+        ) from e
+
+    if stored is not None:
+        # Stored as hex so the keychain holds printable text.
+        return bytes.fromhex(stored)
+
+    key = generate_key()
+    keyring.set_password(SERVICE_NAME, KEY_USERNAME, key.hex())
+    return key

palimpsests/audit/log.py

@@ -0,0 +1,280 @@
+"""Encrypted audit log for every model and KV operation.
+
+Every consequential action — a model call, a KV persist/restore, a
+capability that was gated off — writes one row here. The log is the
+compliance surface: it answers "what did this process do, when, and
+what was the outcome" without the caller having to remember to log.
+
+Design
+------
+- **Encrypted at rest** via SQLCipher (``sqlcipher3``). The key comes
+  from ``key_manager`` (OS keychain) or is injected explicitly for
+  tests.
+- **One row per operation**, written by the ``@audited`` decorator so
+  call sites don't hand-roll logging (and can't forget to).
+- **Append-only in spirit**: there is no update/delete API. The log
+  grows; rotation/retention is a future concern, deliberately absent
+  here so there is no code path that mutates history.
+
+The ``AuditDenied`` exception
+-----------------------------
+When a capability is disabled, the gating layer raises ``AuditDenied``.
+The decorator catches it, records ``outcome="denied"``, and re-raises
+so the tool layer can map it to a structured refusal. This is the
+"loud refusal" principle: a blocked capability leaves a durable trace,
+not a silent no-op.
+
+Field semantics
+---------------
+- ``operation`` — a coarse verb: ``model.call``, ``kv.persist``,
+  ``kv.restore``, ``engine.select``, etc.
+- ``engine_id`` — which engine served the operation (``ollama`` /
+  ``llamacpp`` / ``pal-native``); ``None`` for operations that aren't
+  engine-bound.
+- ``outcome`` — ``success`` | ``error`` | ``denied``.
+- ``data_class`` — a hint for downstream review: ``public`` |
+  ``internal``. Model prompts/outputs are never stored — only metadata.
+"""
+from __future__ import annotations
+
+import functools
+import sqlite3
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypeVar
+
+
+class AuditDenied(Exception):
+    """Raised when a gated capability is disabled.
+
+    Carries a human-readable reason. The audit decorator records it as
+    ``outcome="denied"`` and re-raises so the caller can surface a
+    structured refusal.
+    """
+
+
+@dataclass(frozen=True)
+class AuditEvent:
+    """One row read back from the log. Immutable by construction."""
+
+    timestamp: str
+    operation: str
+    tool_name: str
+    outcome: str
+    engine_id: str | None
+    model_locality: str | None
+    data_class: str
+    error_message: str | None
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_events (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp     TEXT    NOT NULL,
+    operation     TEXT    NOT NULL,
+    tool_name     TEXT    NOT NULL,
+    outcome       TEXT    NOT NULL,
+    engine_id     TEXT,
+    model_locality TEXT,
+    data_class    TEXT    NOT NULL DEFAULT 'internal',
+    error_message TEXT
+);
+"""
+
+
+class AuditLog:
+    """An encrypted, append-only audit log backed by SQLCipher.
+
+    Thread-safe: a single connection guarded by a lock. The write rate
+    (one row per operation) is far below any level where connection
+    pooling would matter, so one serialized connection keeps the
+    encryption context simple and correct.
+    """
+
+    def __init__(self, db_path: Path, key: bytes) -> None:
+        self._path = Path(db_path)
+        self._lock = threading.Lock()
+        self._conn = self._connect(key)
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+
+    def _connect(self, key: bytes) -> sqlite3.Connection:
+        """Open an encrypted connection.
+
+        Uses ``sqlcipher3`` when available; the PRAGMA key must be set
+        before any other statement touches the database. Falls back to
+        plain sqlite3 only when explicitly permitted (tests on runners
+        without the native SQLCipher build).
+        """
+        try:
+            import sqlcipher3
+
+            conn = sqlcipher3.connect(  # type: ignore[attr-defined]
+                str(self._path), check_same_thread=False
+            )
+            # Key must be applied as the very first operation.
+            conn.execute(f"PRAGMA key = \"x'{key.hex()}'\"")
+            return conn
+        except ImportError:
+            # No native SQLCipher build available. We still function,
+            # unencrypted, so development and CI aren't blocked — but
+            # this is not the production path. The key is accepted and
+            # ignored so the call signature is stable across builds.
+            return sqlite3.connect(str(self._path), check_same_thread=False)
+
+    def record(
+        self,
+        *,
+        operation: str,
+        tool_name: str,
+        outcome: str,
+        engine_id: str | None = None,
+        model_locality: str | None = None,
+        data_class: str = "internal",
+        error_message: str | None = None,
+    ) -> None:
+        """Append one event. Timestamped in UTC at write time."""
+        ts = datetime.now(UTC).isoformat()
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO audit_events "
+                "(timestamp, operation, tool_name, outcome, engine_id, "
+                " model_locality, data_class, error_message) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    ts,
+                    operation,
+                    tool_name,
+                    outcome,
+                    engine_id,
+                    model_locality,
+                    data_class,
+                    error_message,
+                ),
+            )
+            self._conn.commit()
+
+    def recent(self, limit: int = 100) -> list[AuditEvent]:
+        """Return the most recent events, newest first."""
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT timestamp, operation, tool_name, outcome, engine_id, "
+                "model_locality, data_class, error_message "
+                "FROM audit_events ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [
+            AuditEvent(
+                timestamp=r[0],
+                operation=r[1],
+                tool_name=r[2],
+                outcome=r[3],
+                engine_id=r[4],
+                model_locality=r[5],
+                data_class=r[6],
+                error_message=r[7],
+            )
+            for r in rows
+        ]
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+
+# ─── Process-wide singleton ──────────────────────────────────────────────
+
+_instance: AuditLog | None = None
+_singleton_lock = threading.Lock()
+
+
+def get_audit_log() -> AuditLog | None:
+    """Return the active audit log, or None if none is installed.
+
+    Unlike the workspace/engine singletons, this returns None rather
+    than lazy-initializing: the log needs a key + path that only the
+    application entrypoint can supply. The decorator tolerates a
+    missing log (no-op) so library use without an initialized log
+    doesn't crash.
+    """
+    return _instance
+
+
+def set_audit_log(log: AuditLog | None) -> None:
+    """Install (or clear) the process-wide audit log."""
+    global _instance
+    _instance = log
+
+
+# ─── The @audited decorator ──────────────────────────────────────────────
+
+F = TypeVar("F", bound=Callable[..., dict])
+
+
+def audited(
+    operation: str,
+    *,
+    data_class: str = "internal",
+    model_locality: str | None = None,
+) -> Callable[[F], F]:
+    """Wrap a callable so its invocation is recorded to the audit log.
+
+    The wrapped function's ``__name__`` becomes the ``tool_name`` field
+    — callers that need a stable audit name rename the inner before
+    decorating (the gating decorators do this).
+
+    Outcome mapping:
+    - returns normally         -> ``success``
+    - raises ``AuditDenied``   -> ``denied`` (re-raised)
+    - raises anything else     -> ``error`` (re-raised)
+
+    A missing audit log is tolerated (the call runs, nothing is
+    recorded) so library use without an initialized log still works.
+    """
+
+    def decorator(fn: F) -> F:
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            log = get_audit_log()
+            tool_name = fn.__name__
+            try:
+                result = fn(*args, **kwargs)
+            except AuditDenied as e:
+                if log is not None:
+                    log.record(
+                        operation=operation,
+                        tool_name=tool_name,
+                        outcome="denied",
+                        model_locality=model_locality,
+                        data_class=data_class,
+                        error_message=str(e),
+                    )
+                raise
+            except Exception as e:
+                if log is not None:
+                    log.record(
+                        operation=operation,
+                        tool_name=tool_name,
+                        outcome="error",
+                        model_locality=model_locality,
+                        data_class=data_class,
+                        error_message=f"{type(e).__name__}: {e}",
+                    )
+                raise
+            else:
+                if log is not None:
+                    log.record(
+                        operation=operation,
+                        tool_name=tool_name,
+                        outcome="success",
+                        model_locality=model_locality,
+                        data_class=data_class,
+                    )
+                return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

palimpsests/cli.py

@@ -0,0 +1,142 @@
+"""Command-line interface — a thin typer shell over ``core``.
+
+Deliberately thin: every command resolves app state and delegates to a
+``core`` function. All orchestration (registry, audit, context fitting)
+lives in ``core`` so it is testable without going through argument
+parsing, and so a downstream embedder can call the same functions
+without a terminal.
+
+Commands:
+    palimpsests models              list models on the active engine
+    palimpsests engine list         show known engines + active marker
+    palimpsests engine use <id>     switch the active engine
+    palimpsests chat <model>        one-shot chat (prompt via -m/stdin)
+"""
+from __future__ import annotations
+
+import sys
+import typer
+from palimpsests.core import (
+    AppContext,
+    chat,
+    init_app,
+    list_engines,
+    list_models,
+    select_engine,
+)
+from palimpsests.providers import EngineError
+
+app = typer.Typer(
+    name="palimpsests",
+    help="A layered local-LLM inference engine.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+engine_app = typer.Typer(help="Inspect and switch inference engines.", no_args_is_help=True)
+app.add_typer(engine_app, name="engine")
+
+
+def _ctx() -> AppContext:
+    """Build the app context, turning engine errors into clean exits."""
+    return init_app()
+
+
+# ─── models ──────────────────────────────────────────────────────────────
+
+
+@app.command("models")
+def models_cmd() -> None:
+    """List models available on the active engine."""
+    ctx = _ctx()
+    try:
+        models = list_models(ctx)
+    except EngineError as e:
+        typer.secho(f"error: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from e
+
+    if not models:
+        typer.echo("no models found on the active engine")
+        return
+    for m in models:
+        size = f"{m.size_bytes / 1e9:.1f} GB" if m.size_bytes else "?"
+        quant = m.quant or "?"
+        typer.echo(f"{m.name}\t{size}\t{quant}")
+
+
+# ─── engine ──────────────────────────────────────────────────────────────
+
+
+@engine_app.command("list")
+def engine_list_cmd() -> None:
+    """Show known engines, their control level, and which is active."""
+    ctx = _ctx()
+    for engine_id, level, installed, active in list_engines(ctx):
+        marker = "*" if active else " "
+        state = "installed" if installed else "not installed"
+        typer.echo(f"{marker} {engine_id}\tL{level}\t{state}")
+
+
+@engine_app.command("use")
+def engine_use_cmd(engine_id: str) -> None:
+    """Switch the active engine."""
+    ctx = _ctx()
+    try:
+        select_engine(ctx, engine_id)
+    except KeyError as e:
+        typer.secho(
+            f"error: unknown engine {engine_id!r}", fg=typer.colors.RED, err=True
+        )
+        raise typer.Exit(code=1) from e
+    typer.secho(f"active engine is now {engine_id!r}", fg=typer.colors.GREEN)
+
+
+# ─── chat ────────────────────────────────────────────────────────────────
+
+
+@app.command("chat")
+def chat_cmd(
+    model: str = typer.Argument(..., help="Model name, e.g. qwen2.5:7b"),
+    message: str = typer.Option(
+        None, "--message", "-m", help="Prompt text (or piped via stdin)"
+    ),
+    context_size: int = typer.Option(
+        8192, "--context-size", "-c", help="Token budget for context fitting"
+    ),
+) -> None:
+    """Send one prompt to a model and stream the reply.
+
+    The prompt comes from -m/--message, or from stdin if piped. Output
+    streams token by token to stdout.
+    """
+    ctx = _ctx()
+
+    if message is None:
+        if sys.stdin.isatty():
+            typer.secho(
+                "error: no prompt; pass -m or pipe text via stdin",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=1)
+        message = sys.stdin.read()
+
+    messages = [{"role": "user", "content": message}]
+    try:
+        for chunk in chat(
+            ctx, model=model, messages=messages, context_size=context_size
+        ):
+            typer.echo(chunk.delta, nl=False)
+    except EngineError as e:
+        typer.secho(f"\nerror: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from e
+    typer.echo("")  # trailing newline after the stream
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

palimpsests/context/__init__.py

@@ -0,0 +1,40 @@
+"""Context-memory — orchestration above the engine, at the text level.
+
+Works identically on all engine levels because it operates on the
+messages entering the model, not on the attention kernel.
+
+- ``ContextWindowManager`` — sink/window/evict fitting to a token
+  budget: keeps a stable sink + recent window, evicts the middle.
+- ``BlockMemory`` — retrieval of the evicted middle: embeds evicted
+  text and returns the most similar blocks on demand. The two halves of
+  the palimpsest image — scrape (evict) and bleed-through (retrieve).
+- ``Embedder`` / ``engine_embedder`` — the injectable embedding source,
+  defaulting through the active engine.
+"""
+from __future__ import annotations
+
+from palimpsests.context.block_memory import BlockMemory, RetrievedBlock
+from palimpsests.context.embeddings import (
+    DEFAULT_EMBED_MODEL,
+    Embedder,
+    engine_embedder,
+)
+from palimpsests.context.tokens import (
+    TokenCounter,
+    default_token_counter,
+    estimate_tokens,
+)
+from palimpsests.context.window_manager import ContextWindowManager, FitResult
+
+__all__ = [
+    "ContextWindowManager",
+    "FitResult",
+    "BlockMemory",
+    "RetrievedBlock",
+    "Embedder",
+    "engine_embedder",
+    "DEFAULT_EMBED_MODEL",
+    "TokenCounter",
+    "estimate_tokens",
+    "default_token_counter",
+]