chronomemory 0.1.2__py3-none-any.whl

chronomemory/__init__.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. / BitConcepts, LLC.
+"""chronomemory — Epistemic State Database for agentic AI workflows.
+
+Optional Rust acceleration:
+    Build the Rust extension with maturin to enable a faster backend::
+
+        pip install maturin
+        maturin develop --manifest-path crates/chronomemory-py/Cargo.toml
+
+    When the ``_chronomemory_rust`` extension is present it is imported
+    automatically and ``RUST_BACKEND`` is set to ``True``.
+
+Quick start::
+
+    from chronomemory import ChronoStore, ChronoRecord
+
+    with ChronoStore("/path/to/project") as store:
+        store.upsert(ChronoRecord(
+            id="FACT-001",
+            kind="fact",
+            label="CPSC projection is the sole validity authority",
+            source_type="observed",
+            confidence=0.99,
+            evidence=["CPSC-Specification.md §9"],
+        ))
+
+        facts = store.query(kind="fact", rag_filter=True)
+
+Spec: ESDB-Specification.md v1.0 (Layer1Labs / BitConcepts)
+"""
+
+# ---------------------------------------------------------------------------
+# Optional Rust acceleration
+# ---------------------------------------------------------------------------
+# Try to import the PyO3-compiled extension module. If unavailable (e.g. the
+# Rust extension has not been built yet), fall back silently to pure Python.
+# Build with: maturin develop --manifest-path crates/chronomemory-py/Cargo.toml
+from typing import Any
+
+from chronomemory.bridge import (
+    EsdbBridge,
+    EsdbRecord,
+    EsdbStatus,
+)
+from chronomemory.context_pack import ContextPack, ContextPackCompiler, ContextPackEntry
+from chronomemory.deps import DependencyEdge, DepGraph
+from chronomemory.rollback import RollbackReport, invalidate
+from chronomemory.store import (
+    ChronoRecord,
+    ChronoStore,
+    WalEvent,
+    open_store,
+)
+
+RustChronoStore: Any | None = None
+RustRecord: Any | None = None
+RUST_BACKEND: bool = False
+
+try:
+    import _chronomemory_rust as _rust  # noqa: PLC0415
+
+    RustChronoStore = _rust.RustChronoStore
+    RustRecord = _rust.RustRecord
+    RUST_BACKEND = True
+except ImportError:
+    pass
+
+__version__ = "0.1.2"
+__all__ = [
+    # Core store
+    "ChronoStore",
+    "ChronoRecord",
+    "WalEvent",
+    "open_store",
+    # Bridge (unified read/write with .specsmith/ fallback)
+    "EsdbBridge",
+    "EsdbRecord",
+    "EsdbStatus",
+    # Phase 2: dependency graph
+    "DepGraph",
+    "DependencyEdge",
+    # Phase 2: epistemic rollback
+    "RollbackReport",
+    "invalidate",
+    # Phase 2: context pack compiler
+    "ContextPack",
+    "ContextPackCompiler",
+    "ContextPackEntry",
+    # Phase 3: optional Rust acceleration
+    "RustChronoStore",
+    "RustRecord",
+    "RUST_BACKEND",
+]

chronomemory/bridge.py

@@ -0,0 +1,249 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. / BitConcepts, LLC.
+"""ESDB bridge — adapter between .specsmith/ JSON and ESDB concepts.
+
+Delegation strategy:
+  1. If .chronomemory/events.wal exists → delegate to ChronoStore (full
+     WAL-based engine with OEA anti-hallucination fields).
+  2. Otherwise → read flat .specsmith/*.json files (legacy fallback).
+
+Write operations (upsert_record, delete_record) are only available when
+ChronoStore is active. Callers should run ``specsmith esdb migrate`` to
+convert a legacy project before calling write paths.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class EsdbRecord:
+    """Python mirror of the Rust Record type."""
+
+    id: str
+    kind: str = "fact"  # Default matches ChronoRecord and ESDB spec
+    status: str = "active"
+    confidence: float = 0.7
+    label: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+    source_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the original source data dict (used for export/backup)."""
+        return (
+            self.data
+            if self.data
+            else {
+                "id": self.id,
+                "kind": self.kind,
+                "status": self.status,
+                "confidence": self.confidence,
+                "label": self.label,
+            }
+        )
+
+
+@dataclass
+class EsdbStatus:
+    """ESDB health status for the REST API."""
+
+    available: bool
+    backend: str  # "esdb" or "json-fallback"
+    record_count: int = 0
+    wal_seq: int = 0
+    epoch: int = 0
+    chain_valid: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "available": self.available,
+            "backend": self.backend,
+            "record_count": self.record_count,
+            "wal_seq": self.wal_seq,
+            "epoch": self.epoch,
+            "chain_valid": self.chain_valid,
+        }
+
+
+class EsdbBridge:
+    """Unified bridge to ESDB: delegates to ChronoStore when available.
+
+    Delegation strategy:
+      - ChronoStore (.chronomemory/events.wal): full WAL engine, all writes
+      - JSON fallback (.specsmith/*.json): legacy read-only access
+    """
+
+    def __init__(self, project_dir: str = ".") -> None:
+        self.root = Path(project_dir).resolve()
+        self._requirements: list[EsdbRecord] | None = None
+        self._testcases: list[EsdbRecord] | None = None
+        self._store: Any = None  # ChronoStore | None
+
+    def _get_store(self) -> Any:
+        """Return an open ChronoStore if available, else None."""
+        if self._store is not None:
+            return self._store
+        wal = self.root / ".chronomemory" / "events.wal"
+        if wal.exists():
+            try:
+                from chronomemory.store import ChronoStore
+
+                self._store = ChronoStore(self.root).open()
+            except Exception:  # noqa: BLE001
+                self._store = None
+        return self._store
+
+    def status(self) -> EsdbStatus:
+        """Return ESDB status."""
+        store = self._get_store()
+        if store is not None:
+            return EsdbStatus(
+                available=True,
+                backend="ChronoStore WAL",
+                record_count=store.record_count(),
+                wal_seq=store.wal_seq(),
+                chain_valid=store.chain_valid(),
+            )
+        # Legacy JSON fallback
+        reqs = self._load_requirements()
+        tests = self._load_testcases()
+        return EsdbStatus(
+            available=True,
+            backend=".specsmith/ JSON (run esdb migrate to upgrade)",
+            record_count=len(reqs) + len(tests),
+        )
+
+    def requirements(self) -> list[EsdbRecord]:
+        """Load requirements as ESDB records."""
+        store = self._get_store()
+        if store is not None:
+            return [
+                EsdbRecord(
+                    id=r.id,
+                    kind=r.kind,
+                    status=r.status,
+                    confidence=r.confidence,
+                    label=r.label,
+                    data=r.data,
+                    source_ids=r.evidence,
+                )
+                for r in store.query(kind="requirement")
+            ]
+        return self._load_requirements()
+
+    def testcases(self) -> list[EsdbRecord]:
+        """Load test cases as ESDB records."""
+        store = self._get_store()
+        if store is not None:
+            return [
+                EsdbRecord(
+                    id=r.id,
+                    kind=r.kind,
+                    status=r.status,
+                    confidence=r.confidence,
+                    label=r.label,
+                    data=r.data,
+                    source_ids=r.evidence,
+                )
+                for r in store.query(kind="testcase")
+            ]
+        return self._load_testcases()
+
+    def record_counts(self) -> dict[str, int]:
+        """Record counts by kind (for dashboard)."""
+        store = self._get_store()
+        if store is not None:
+            records = store.query()
+            counts: dict[str, int] = {}
+            for r in records:
+                counts[r.kind] = counts.get(r.kind, 0) + 1
+            return counts
+        return {
+            "requirements": len(self._load_requirements()),
+            "testcases": len(self._load_testcases()),
+        }
+
+    def upsert_record(self, record: EsdbRecord) -> bool:
+        """Write or update a record. Returns True if ChronoStore is active."""
+        store = self._get_store()
+        if store is None:
+            return False
+        try:
+            from chronomemory.store import ChronoRecord
+
+            chrono_rec = ChronoRecord(
+                id=record.id,
+                kind=record.kind,
+                status=record.status,
+                confidence=record.confidence,
+                label=record.label,
+                data=record.data,
+                evidence=record.source_ids,
+            )
+            store.upsert(chrono_rec)
+            return True
+        except Exception:  # noqa: BLE001
+            return False
+
+    def delete_record(self, record_id: str) -> bool:
+        """Tombstone a record. Returns True if ChronoStore is active."""
+        store = self._get_store()
+        if store is None:
+            return False
+        try:
+            store.delete(record_id)
+            return True
+        except Exception:  # noqa: BLE001
+            return False
+
+    def _load_requirements(self) -> list[EsdbRecord]:
+        if self._requirements is not None:
+            return self._requirements
+        path = self.root / ".specsmith" / "requirements.json"
+        if not path.is_file():
+            self._requirements = []
+            return []
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            self._requirements = [
+                EsdbRecord(
+                    id=r.get("id", ""),
+                    kind="requirement",
+                    label=r.get("title", ""),
+                    confidence=float(r.get("confidence", 0.7)),
+                    data=r,
+                )
+                for r in raw
+                if isinstance(r, dict)
+            ]
+        except (OSError, ValueError):
+            self._requirements = []
+        return self._requirements
+
+    def _load_testcases(self) -> list[EsdbRecord]:
+        if self._testcases is not None:
+            return self._testcases
+        path = self.root / ".specsmith" / "testcases.json"
+        if not path.is_file():
+            self._testcases = []
+            return []
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            self._testcases = [
+                EsdbRecord(
+                    id=r.get("id", ""),
+                    kind="testcase",
+                    label=r.get("title", ""),
+                    confidence=float(r.get("confidence", 1.0)),
+                    data=r,
+                )
+                for r in raw
+                if isinstance(r, dict)
+            ]
+        except (OSError, ValueError):
+            self._testcases = []
+        return self._testcases

chronomemory/context_pack.py

@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Layer1Labs Silicon, Inc. / BitConcepts, LLC.
+"""Context Pack Compiler — minimal verified prompt payloads for agent tasks.
+
+Phase 2 / Issue #3: Context Pack Compiler
+Spec: ESDB Master Spec §18
+
+Assembles only the epistemic state an agent actually needs, excluding
+stale, invalidated, and unsupported records, then respects a token budget
+by dropping lowest-confidence candidates first.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from chronomemory.deps import DepGraph
+    from chronomemory.store import ChronoRecord, ChronoStore
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_CHARS_PER_TOKEN: int = 4  # conservative estimate per spec §18
+_MIN_CONFIDENCE: float = 0.6  # H18 threshold
+
+# Record kinds that are infrastructure and should not appear in context packs
+_INFRA_KINDS: frozenset[str] = frozenset(["edge", "rollback_event", "token_metric", "skill_run"])
+
+# Statuses that indicate a record should be excluded
+_EXCLUDED_STATUSES: frozenset[str] = frozenset(["tombstone", "invalidated", "hypothesis"])
+
+
+# ---------------------------------------------------------------------------
+# Data types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ContextPackEntry:
+    """A single record included in a ContextPack."""
+
+    record_id: str
+    kind: str
+    label: str
+    confidence: float
+    token_estimate: int
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "record_id": self.record_id,
+            "kind": self.kind,
+            "label": self.label,
+            "confidence": self.confidence,
+            "token_estimate": self.token_estimate,
+            "data": self.data,
+        }
+
+
+@dataclass
+class ExclusionReason:
+    """Explains why a record was excluded from a ContextPack."""
+
+    record_id: str
+    reason: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {"record_id": self.record_id, "reason": self.reason}
+
+
+@dataclass
+class ContextPack:
+    """A compiled, budget-constrained set of records ready for LLM injection.
+
+    Serializable via :py:meth:`to_dict` for JSON injection into LLM context.
+    """
+
+    task_id: str
+    goal: str
+    token_budget: int
+    entries: list[ContextPackEntry] = field(default_factory=list)
+    excluded: list[ExclusionReason] = field(default_factory=list)
+
+    @property
+    def token_count(self) -> int:
+        """Estimated total tokens consumed by all entries."""
+        return sum(e.token_estimate for e in self.entries)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "task_id": self.task_id,
+            "goal": self.goal,
+            "token_budget": self.token_budget,
+            "token_count": self.token_count,
+            "entries": [e.to_dict() for e in self.entries],
+            "excluded": [x.to_dict() for x in self.excluded],
+        }
+
+
+# ---------------------------------------------------------------------------
+# ContextPackCompiler
+# ---------------------------------------------------------------------------
+
+
+class ContextPackCompiler:
+    """Assembles a minimal, verified prompt payload for a given task.
+
+    Usage::
+
+        compiler = ContextPackCompiler(store, dep_graph)
+        pack = compiler.compile(task_id="TASK-42", goal="fix ruff errors", token_budget=4096)
+
+        # Inject into LLM context
+        context_json = pack.to_dict()
+
+    The ``dep_graph`` argument is optional. When provided, graph relevance
+    traversal is used in addition to keyword matching (Phase 2 extension).
+    """
+
+    def __init__(self, store: ChronoStore, dep_graph: DepGraph | None = None) -> None:
+        self._store = store
+        self._dep_graph = dep_graph
+
+    def compile(
+        self,
+        task_id: str,
+        goal: str,
+        token_budget: int = 4096,
+    ) -> ContextPack:
+        """Compile a token-budget-constrained ContextPack for a task.
+
+        Inclusion rules:
+        * Status must be ``active`` (not tombstone / invalidated / hypothesis)
+        * Confidence must be ≥ 0.6 (H18)
+        * Kind must not be an infrastructure record (edge, rollback_event, …)
+        * Label must share at least one word with *goal* (or *goal* is empty)
+
+        Budget enforcement:
+        * Records are sorted by confidence descending
+        * Records are added until token_budget is reached; remainder is excluded
+        """
+        pack = ContextPack(task_id=task_id, goal=goal, token_budget=token_budget)
+        goal_words = set(goal.lower().split()) if goal.strip() else set()
+
+        candidates: list[ContextPackEntry] = []
+
+        for rec in self._store.query(status=""):
+            token_est = self._estimate_tokens(rec)
+
+            # ── Exclusion: bad status ────────────────────────────────────
+            if rec.status in _EXCLUDED_STATUSES:
+                pack.excluded.append(ExclusionReason(rec.id, f"status={rec.status}"))
+                continue
+
+            # ── Exclusion: confidence below H18 threshold ────────────────
+            if rec.confidence < _MIN_CONFIDENCE:
+                pack.excluded.append(
+                    ExclusionReason(rec.id, f"confidence={rec.confidence:.2f} < {_MIN_CONFIDENCE}")
+                )
+                continue
+
+            # ── Exclusion: infrastructure records ────────────────────────
+            if rec.kind in _INFRA_KINDS:
+                pack.excluded.append(
+                    ExclusionReason(rec.id, f"infrastructure record (kind={rec.kind})")
+                )
+                continue
+
+            # ── Relevance: keyword overlap with goal ─────────────────────
+            if goal_words:
+                label_words = set(rec.label.lower().split())
+                if goal_words.isdisjoint(label_words):
+                    pack.excluded.append(ExclusionReason(rec.id, "not relevant to goal"))
+                    continue
+
+            candidates.append(
+                ContextPackEntry(
+                    record_id=rec.id,
+                    kind=rec.kind,
+                    label=rec.label,
+                    confidence=rec.confidence,
+                    token_estimate=token_est,
+                    data=rec.data,
+                )
+            )
+
+        # ── Sort: highest confidence first (include most trusted first) ──
+        candidates.sort(key=lambda e: e.confidence, reverse=True)
+
+        # ── Budget enforcement: add until budget is exceeded ─────────────
+        running_tokens = 0
+        for entry in candidates:
+            if running_tokens + entry.token_estimate <= token_budget:
+                pack.entries.append(entry)
+                running_tokens += entry.token_estimate
+            else:
+                pack.excluded.append(
+                    ExclusionReason(
+                        entry.record_id,
+                        f"token budget exceeded "
+                        f"({running_tokens}+{entry.token_estimate}>{token_budget})",
+                    )
+                )
+
+        return pack
+
+    @staticmethod
+    def _estimate_tokens(rec: ChronoRecord) -> int:
+        """Estimate token count: ~4 chars per token (label + data repr)."""
+        chars = len(rec.label) + len(str(rec.data))
+        return max(1, chars // _CHARS_PER_TOKEN)