kiwime-export 0.1.0__py3-none-any.whl

kiwime_export/__init__.py

@@ -0,0 +1,17 @@
+"""kiwiMe export worker.
+
+Serializes the compiled Expert Context Package (manifest, identity, memories,
+graph, cases, assets, permissions) per docs/schema/core.md "Export layer".
+
+Default behavior is **minimum public**: identity + confirmed cases +
+topic-level capability summary. No raw document text leaves the package
+unless the user explicitly opts in. See ``options.ExportOptions``.
+"""
+
+from .manifest import build_manifest
+from .options import ExportOptions
+from .writer import write_package
+
+__all__ = ["ExportOptions", "build_manifest", "write_package"]
+
+__version__ = "0.0.0"

kiwime_export/__main__.py

@@ -0,0 +1,144 @@
+"""Entry point: ``python -m kiwime_export``.
+
+Reads JSON-RPC requests line-by-line from stdin, writes responses to stdout.
+Logs go to stderr (per docs/architecture/ipc-protocol.md §1: stdout is the
+protocol channel).
+
+Production wiring: the host spawns this with ``--direct <sqlite_path>`` so
+the worker reads the same store database the rest of the system writes to.
+Without ``--direct`` we fall back to a no-op stub, which is only useful for
+the standalone smoke tests in ``tests/`` — every export call would otherwise
+return an empty package.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+import sys
+from typing import Any
+
+from kiwime_store import repo
+
+from .server import dispatch
+from .store_client import StoreClient
+
+
+class _UnwiredStore:
+    """Placeholder used only when ``--direct`` is omitted (tests).
+
+    Returns empty results for every query so the binary can boot in
+    isolation without a database.
+    """
+
+    def query_memories(self, profile_id: str) -> list[dict[str, Any]]:
+        return []
+
+    def query_graph(self, profile_id: str) -> dict[str, list[dict[str, Any]]]:
+        return {"nodes": [], "edges": []}
+
+    def query_capabilities(self, profile_id: str) -> list[dict[str, Any]]:
+        return []
+
+    def query_cases(self, profile_id: str) -> list[dict[str, Any]]:
+        return []
+
+    def query_assets(self, profile_id: str) -> list[dict[str, Any]]:
+        return []
+
+    def query_permissions(self, profile_id: str) -> dict[str, Any]:
+        return {}
+
+
+class SqliteStoreClient:
+    """Direct SQLite reader. The same database file the store sidecar uses.
+
+    We deliberately open in read-only mode (``mode=ro``) — the export
+    worker must never mutate state. Also ``immutable=0`` so SQLite still
+    sees concurrent writes from the store sidecar (otherwise it would
+    cache the page set and miss new memories compiled mid-session).
+    """
+
+    def __init__(self, db_path: str) -> None:
+        uri = f"file:{db_path}?mode=ro"
+        self._conn = sqlite3.connect(uri, uri=True, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+
+    def query_memories(self, profile_id: str) -> list[dict[str, Any]]:
+        return repo.list_memories(self._conn, profile_id)
+
+    def query_graph(self, profile_id: str) -> dict[str, list[dict[str, Any]]]:
+        return repo.get_graph(self._conn, profile_id)
+
+    def query_capabilities(self, profile_id: str) -> list[dict[str, Any]]:
+        return repo.list_capabilities(self._conn, profile_id)
+
+    def query_cases(self, profile_id: str) -> list[dict[str, Any]]:
+        # ``case_record`` rows aren't yet exposed via a repo helper. Read
+        # directly; columns track migrations/0001_init.sql.
+        try:
+            rows = self._conn.execute(
+                "SELECT * FROM case_record WHERE profile_id = ?",
+                (profile_id,),
+            ).fetchall()
+        except sqlite3.OperationalError:
+            return []
+        return [dict(r) for r in rows]
+
+    def query_assets(self, profile_id: str) -> list[dict[str, Any]]:
+        # Assets live under ``source`` — there's no profile_id column on
+        # ``asset`` itself; we join through ``source``.
+        try:
+            rows = self._conn.execute(
+                """
+                SELECT a.* FROM asset a
+                JOIN source s ON s.id = a.source_id
+                WHERE s.profile_id = ? AND a.deleted_at IS NULL
+                """,
+                (profile_id,),
+            ).fetchall()
+        except sqlite3.OperationalError:
+            return []
+        return [dict(r) for r in rows]
+
+    def query_permissions(self, profile_id: str) -> dict[str, Any]:
+        # No persisted permission rows yet — the manifest section is the
+        # canonical record of "what this export contains". Surface the
+        # known sources so downstream consumers see scope at a glance.
+        try:
+            sources = repo.list_sources(self._conn, profile_id)
+        except Exception:
+            sources = []
+        return {
+            "sources": [
+                {"id": s.get("id"), "connector": s.get("connector"), "kind": s.get("kind")}
+                for s in sources
+            ],
+        }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="kiwime-export")
+    parser.add_argument(
+        "--direct",
+        metavar="SQLITE_PATH",
+        help="Open the store SQLite directly (read-only). Required for real exports.",
+    )
+    args, _unknown = parser.parse_known_args()
+
+    # Without --direct: stub mode with empty results. The binary still
+    # serves RPC so smoke tests pass, but every export will be empty.
+    store: StoreClient = SqliteStoreClient(args.direct) if args.direct else _UnwiredStore()
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        response = dispatch(line, store)
+        sys.stdout.write(response + "\n")
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kiwime_export/manifest.py

@@ -0,0 +1,65 @@
+"""Manifest builder.
+
+The manifest is the spine of the package: every file is checksummed, every
+included section is listed, every redaction is named. It is what makes the
+package *auditable* — a downstream importer can verify integrity and see
+exactly what the user chose to share.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+from typing import Any
+
+from .options import ExportOptions
+
+# Bump on breaking changes. v0 = pre-1.0 draft.
+MANIFEST_VERSION = 0
+GENERATOR = "kiwiMe/0.0.0"
+
+
+def _sha256_hex(data: str | bytes) -> str:
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def _utc_now_iso() -> str:
+    """ISO 8601 UTC, millisecond precision, ``Z`` suffix (per schema/core.md)."""
+    now = datetime.now(UTC)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def build_manifest(
+    profile_id: str,
+    opts: ExportOptions,
+    files: dict[str, str | bytes],
+    *,
+    generated_at: str | None = None,
+) -> dict[str, Any]:
+    """Build the manifest object.
+
+    Args:
+        profile_id: The profile being exported.
+        opts: User's per-export toggles.
+        files: Mapping ``filename -> content`` of every file included in the
+            package *other than* ``manifest.json`` itself. Checksums are
+            computed over these.
+        generated_at: Optional override for the timestamp (tests inject a
+            fixed value).
+
+    Returns:
+        The manifest dict, ready to be JSON-serialized.
+    """
+    sections = sorted(files.keys())
+    checksums = {name: _sha256_hex(content) for name, content in files.items()}
+    return {
+        "version": MANIFEST_VERSION,
+        "profile_id": profile_id,
+        "generated_at": generated_at or _utc_now_iso(),
+        "generator": GENERATOR,
+        "sections": sections,
+        "redactions": opts.redactions(),
+        "checksums": checksums,
+    }

kiwime_export/options.py

@@ -0,0 +1,70 @@
+"""Export options.
+
+Defaults are deliberately conservative: **minimum public**. No raw document
+text leaves the package, no episodic memories, no provenance ingestion-layer
+refs, no assets. The user must explicitly opt in to expand the package.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+ExportFormat = Literal["directory", "tarball"]
+
+
+@dataclass(frozen=True)
+class ExportOptions:
+    """User-controlled toggles for what goes into the Expert Context Package.
+
+    Every field is opt-in by default. The package contains the *compiled*
+    expert context, not the user's source material.
+    """
+
+    include_episodic: bool = False
+    """If False, episodic memories are filtered out (only identity + semantic)."""
+
+    include_provenance: bool = False
+    """If False, ingestion-layer refs are stripped from graph/cases/memories."""
+
+    include_asset_ids: list[str] = field(default_factory=list)
+    """Explicit allow-list of asset ids. Empty means: no assets exported."""
+
+    include_raw_text: bool = False
+    """If False, the ``text`` field of memories/documents is summarized only.
+
+    Note: this is the load-bearing privacy switch. With ``False`` (default),
+    no raw user document text is in the package.
+    """
+
+    format: ExportFormat = "directory"
+    """Either a directory of files or an additional ``package.tar.gz``."""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, object] | None) -> ExportOptions:
+        if not d:
+            return cls()
+        return cls(
+            include_episodic=bool(d.get("include_episodic", False)),
+            include_provenance=bool(d.get("include_provenance", False)),
+            include_asset_ids=list(d.get("include_asset_ids", []) or []),  # type: ignore[arg-type]
+            include_raw_text=bool(d.get("include_raw_text", False)),
+            format=d.get("format", "directory"),  # type: ignore[arg-type]
+        )
+
+    def redactions(self) -> list[str]:
+        """List of section names that were redacted by these options.
+
+        Surfaced in ``manifest.json`` so a downstream importer can see what
+        the user chose to omit, without leaking what was actually in there.
+        """
+        out: list[str] = []
+        if not self.include_episodic:
+            out.append("episodic_memories")
+        if not self.include_raw_text:
+            out.append("raw_document_text")
+        if not self.include_provenance:
+            out.append("provenance_refs")
+        if not self.include_asset_ids:
+            out.append("assets")
+        return out

kiwime_export/resume.py

@@ -0,0 +1,231 @@
+"""Static resume page — render the compiled expert context as one HTML file.
+
+The "public resume" use case: a user exports a single self-contained
+``resume.html`` (inline CSS, zero external requests, no JS required) and
+hosts it anywhere — GitHub Pages, their own domain — as a live, provenance-
+aware alternative to a PDF resume.
+
+Privacy stance mirrors the package exporter: this renders only *compiled*
+context (identity summary, capabilities, confirmed cases), never raw
+document text, and applies the same governance filters (dismissed/archived
+excluded, superseded memories skipped, candidate cases skipped). The page
+is meant to be published, so the bar is "what the user already chose to
+stand behind", not "everything the store knows".
+
+The optional ``narrative`` (an LLM-written professional summary) is
+generated by the compiler's assistant role — the host orchestrates that
+call and passes the text in, so this worker stays LLM-free.
+"""
+
+from __future__ import annotations
+
+import html
+from datetime import UTC, datetime
+from typing import Any
+
+from .store_client import StoreClient
+
+# Governance statuses that must never appear on a public page.
+_EXCLUDED_STATUSES = frozenset({"dismissed", "archived"})
+
+# recency column values → human phrasing, in display order.
+_RECENCY_LABEL = {
+    "recent": "current focus",
+    "stable": "established",
+    "dormant": "earlier work",
+}
+_RECENCY_ORDER = {"recent": 0, "stable": 1, "dormant": 2}
+
+
+def collect_resume_data(profile_id: str, store: StoreClient) -> dict[str, Any]:
+    """Gather everything the template needs, applying governance filters.
+
+    Returns a plain dict so it can double as the ``resume.json`` payload
+    (machine-readable twin of the page) and be unit-tested without HTML
+    parsing.
+    """
+    memories = store.query_memories(profile_id)
+    identities = [
+        m
+        for m in memories
+        if m.get("kind") == "identity"
+        and not m.get("superseded_by")
+        and m.get("status") not in _EXCLUDED_STATUSES
+    ]
+    identities.sort(key=lambda m: m.get("created_at", ""), reverse=True)
+    identity = identities[0] if identities else None
+
+    capabilities = [
+        c
+        for c in store.query_capabilities(profile_id)
+        if c.get("status") not in _EXCLUDED_STATUSES
+    ]
+    # Confidence within recency bucket: current focus first, strongest first.
+    capabilities.sort(
+        key=lambda c: (
+            _RECENCY_ORDER.get(str(c.get("recency")), 3),
+            -float(c.get("confidence") or 0.0),
+        )
+    )
+
+    cases = [c for c in store.query_cases(profile_id) if c.get("status") == "confirmed"]
+    cases.sort(key=lambda c: -float(c.get("confidence") or 0.0))
+
+    return {
+        "identity": {
+            "summary": (identity.get("summary") or "").strip() if identity else "",
+            "text": (identity.get("text") or "").strip() if identity else "",
+        },
+        "capabilities": [
+            {
+                "name": c.get("name") or "",
+                "description": c.get("description") or "",
+                "confidence": float(c.get("confidence") or 0.0),
+                "recency": str(c.get("recency") or "stable"),
+            }
+            for c in capabilities
+        ],
+        "cases": [
+            {
+                "title": c.get("title") or "",
+                "summary": c.get("summary") or "",
+                "outcome": c.get("outcome") or "",
+            }
+            for c in cases
+        ],
+    }
+
+
+def _esc(s: str) -> str:
+    return html.escape(s, quote=True)
+
+
+def _confidence_bar(confidence: float) -> str:
+    pct = max(0, min(100, round(confidence * 100)))
+    return (
+        f'<div class="bar" role="img" aria-label="confidence {pct}%">'
+        f'<div class="bar-fill" style="width:{pct}%"></div></div>'
+    )
+
+
+def render_resume_html(
+    data: dict[str, Any],
+    *,
+    narrative: str = "",
+    display_name: str = "",
+    generated_at: str | None = None,
+) -> str:
+    """Render the resume page. Self-contained: inline CSS, no JS, no fetches.
+
+    ``narrative`` is the optional LLM-written summary (host passes it in);
+    when absent the page falls back to the compiled identity text, and when
+    that's absent too, the section is omitted — never filled with boilerplate.
+    """
+    ts = generated_at or datetime.now(UTC).strftime("%Y-%m-%d")
+    name = display_name.strip() or "Expert Context"
+    summary = narrative.strip() or data["identity"]["text"] or data["identity"]["summary"]
+
+    cap_items: list[str] = []
+    for c in data["capabilities"]:
+        cap_items.append(
+            '<li class="cap">'
+            f'<div class="cap-head"><span class="cap-name">{_esc(c["name"])}</span>'
+            f'<span class="tag">{_esc(_RECENCY_LABEL.get(c["recency"], c["recency"]))}</span></div>'
+            f"{_confidence_bar(c['confidence'])}"
+            f'<p class="cap-desc">{_esc(c["description"])}</p>'
+            "</li>"
+        )
+
+    case_items: list[str] = []
+    for c in data["cases"]:
+        outcome = (
+            f'<p class="case-outcome"><strong>Outcome:</strong> {_esc(c["outcome"])}</p>'
+            if c["outcome"]
+            else ""
+        )
+        case_items.append(
+            '<li class="case">'
+            f"<h3>{_esc(c['title'])}</h3>"
+            f"<p>{_esc(c['summary'])}</p>"
+            f"{outcome}"
+            "</li>"
+        )
+
+    summary_section = (
+        f'<section><h2>Profile</h2><p class="summary">{_esc(summary)}</p></section>'
+        if summary
+        else ""
+    )
+    caps_section = (
+        f'<section><h2>Capabilities</h2><ul class="caps">{"".join(cap_items)}</ul></section>'
+        if cap_items
+        else ""
+    )
+    cases_section = (
+        f'<section><h2>Selected cases</h2><ul class="cases">{"".join(case_items)}</ul></section>'
+        if case_items
+        else ""
+    )
+
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="index, follow">
+<title>{_esc(name)}</title>
+<style>
+:root {{ color-scheme: light dark; }}
+* {{ box-sizing: border-box; margin: 0; }}
+body {{
+  font: 16px/1.65 system-ui, -apple-system, "Segoe UI", sans-serif;
+  max-width: 46rem; margin: 0 auto; padding: 3rem 1.5rem 4rem;
+  color: #1a2233; background: #fdfdfc;
+}}
+@media (prefers-color-scheme: dark) {{
+  body {{ color: #d7dce6; background: #0d1117; }}
+  .tag {{ background: #1f2937; color: #93a4bd; }}
+  .bar {{ background: #1f2937; }}
+  header, section {{ border-color: #232b3a; }}
+}}
+header {{ border-bottom: 2px solid #e5e4df; padding-bottom: 1.25rem; margin-bottom: 2rem; }}
+h1 {{ font-size: 1.75rem; letter-spacing: -0.02em; }}
+.meta {{ font-size: .8rem; opacity: .55; margin-top: .35rem; }}
+section {{ margin-bottom: 2.25rem; }}
+h2 {{
+  font-size: .8rem; text-transform: uppercase; letter-spacing: .12em;
+  opacity: .6; margin-bottom: 1rem;
+}}
+.summary {{ font-size: 1.05rem; }}
+ul.caps, ul.cases {{ list-style: none; padding: 0; display: grid; gap: 1.1rem; }}
+.cap-head {{ display: flex; align-items: baseline; gap: .6rem; }}
+.cap-name {{ font-weight: 600; }}
+.tag {{
+  font-size: .68rem; text-transform: uppercase; letter-spacing: .06em;
+  background: #eceae4; color: #5b6472; border-radius: 999px; padding: .1rem .55rem;
+}}
+.bar {{ height: 4px; background: #eceae4; border-radius: 2px; margin: .4rem 0; max-width: 16rem; }}
+.bar-fill {{ height: 100%; background: #22a3a9; border-radius: 2px; }}
+.cap-desc, .case p {{ font-size: .92rem; opacity: .85; }}
+.case h3 {{ font-size: 1rem; margin-bottom: .25rem; }}
+.case-outcome {{ font-size: .88rem; margin-top: .35rem; }}
+footer {{ margin-top: 3rem; font-size: .75rem; opacity: .45; }}
+footer a {{ color: inherit; }}
+</style>
+</head>
+<body>
+<header>
+  <h1>{_esc(name)}</h1>
+  <p class="meta">Compiled expert context · generated {_esc(ts)}</p>
+</header>
+{summary_section}
+{caps_section}
+{cases_section}
+<footer>
+  <p>Generated from a continuously compiled expert context —
+  every capability and case above traces back to real work.
+  Built with <a href="https://github.com/kiwiberry-ai/kiwime">kiwiMe</a>.</p>
+</footer>
+</body>
+</html>
+"""