chimera-memory 0.1.0__py3-none-any.whl

chimera_memory/__init__.py

@@ -0,0 +1,55 @@
+from chimera_memory.drift import detect_drift
+from chimera_memory.ledger import (
+    build_dogfood_status,
+    export_report,
+    query_memory,
+    record_claim,
+    settle_claim,
+)
+from chimera_memory.receipt import (
+    build_receipt,
+    format_receipt_json,
+    format_receipt_markdown,
+    format_receipt_text,
+)
+from chimera_memory.reliability import build_reliability_summary
+from chimera_memory.session import (
+    AttributionConfidence,
+    FinalStatus,
+    IdentitySource,
+    Session,
+    new_session_id,
+)
+from chimera_memory.session_lifecycle import (
+    end_session,
+    get_current_session,
+    get_session,
+    list_sessions,
+    start_session,
+)
+from chimera_memory.storage import MemoryStore
+
+__all__ = [
+    "AttributionConfidence",
+    "FinalStatus",
+    "IdentitySource",
+    "MemoryStore",
+    "Session",
+    "build_dogfood_status",
+    "build_receipt",
+    "build_reliability_summary",
+    "detect_drift",
+    "end_session",
+    "export_report",
+    "format_receipt_json",
+    "format_receipt_markdown",
+    "format_receipt_text",
+    "get_current_session",
+    "get_session",
+    "list_sessions",
+    "new_session_id",
+    "query_memory",
+    "record_claim",
+    "settle_claim",
+    "start_session",
+]

chimera_memory/_index.py

@@ -0,0 +1,204 @@
+"""Sidecar SQLite settlement-aware claim search index.
+
+Folded from chimera-graphsource into chimera-memory for the public package.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from chimera_memory_types.knowledge import Claim
+
+
+class ClaimIndex:
+    def __init__(self, path: str | Path, *, force_like: bool = False) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.connection = sqlite3.connect(str(self.path))
+        self.connection.row_factory = sqlite3.Row
+        self.fts_enabled = False if force_like else self._probe_fts5()
+        self._init_schema()
+
+    def _probe_fts5(self) -> bool:
+        try:
+            self.connection.execute("CREATE VIRTUAL TABLE temp._fts_probe USING fts5(value)")
+            self.connection.execute("DROP TABLE temp._fts_probe")
+            return True
+        except sqlite3.Error:
+            return False
+
+    def _init_schema(self) -> None:
+        self.connection.execute(
+            """
+            CREATE TABLE IF NOT EXISTS claims (
+                claim_id TEXT PRIMARY KEY,
+                claim_type TEXT NOT NULL,
+                claim_status TEXT NOT NULL,
+                entity_id TEXT,
+                polarity TEXT,
+                settled INTEGER NOT NULL,
+                wealth REAL NOT NULL,
+                text TEXT NOT NULL,
+                claim_json TEXT NOT NULL
+            )
+            """
+        )
+        if self.fts_enabled:
+            self.connection.execute(
+                "CREATE VIRTUAL TABLE IF NOT EXISTS claims_fts USING fts5(claim_id UNINDEXED, text)"
+            )
+        self.connection.commit()
+
+    def index(self, claim: Claim) -> None:
+        text = _claim_text(claim)
+        settled = _is_settled(claim)
+        wealth = _wealth(claim)
+        entity_id = _metadata_string(claim, "entity_id")
+        polarity = _metadata_string(claim, "polarity")
+        payload = (
+            claim.claim_id,
+            claim.claim_type.value,
+            claim.claim_status.value,
+            entity_id,
+            polarity,
+            int(settled),
+            wealth,
+            text,
+            json.dumps(claim.model_dump(mode="json"), sort_keys=True),
+        )
+        self.connection.execute(
+            """
+            INSERT INTO claims (
+                claim_id, claim_type, claim_status, entity_id, polarity,
+                settled, wealth, text, claim_json
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(claim_id) DO UPDATE SET
+                claim_type=excluded.claim_type,
+                claim_status=excluded.claim_status,
+                entity_id=excluded.entity_id,
+                polarity=excluded.polarity,
+                settled=excluded.settled,
+                wealth=excluded.wealth,
+                text=excluded.text,
+                claim_json=excluded.claim_json
+            """,
+            payload,
+        )
+        if self.fts_enabled:
+            self.connection.execute("DELETE FROM claims_fts WHERE claim_id = ?", (claim.claim_id,))
+            self.connection.execute(
+                "INSERT INTO claims_fts (claim_id, text) VALUES (?, ?)",
+                (claim.claim_id, text),
+            )
+        self.connection.commit()
+
+    def search(
+        self,
+        query: str,
+        *,
+        settled_only: bool = False,
+        min_wealth: float | None = None,
+        claim_type: str | None = None,
+    ) -> list[Claim]:
+        where: list[str] = []
+        params: list[Any] = []
+        if settled_only:
+            where.append("claims.settled = 1")
+        if min_wealth is not None:
+            where.append("claims.wealth >= ?")
+            params.append(float(min_wealth))
+        if claim_type is not None:
+            where.append("claims.claim_type = ?")
+            params.append(str(claim_type))
+
+        if self.fts_enabled:
+            sql = "SELECT claims.claim_json FROM claims JOIN claims_fts USING (claim_id)"
+            where.append("claims_fts.text MATCH ?")
+            params.append(query)
+        else:
+            sql = "SELECT claims.claim_json FROM claims"
+            where.append("LOWER(claims.text) LIKE ?")
+            params.append(f"%{query.lower()}%")
+        if where:
+            sql += " WHERE " + " AND ".join(where)
+        sql += " ORDER BY claims.wealth DESC, claims.claim_id ASC"
+        rows = self.connection.execute(sql, params).fetchall()
+        return [Claim.model_validate(json.loads(row["claim_json"])) for row in rows]
+
+    def find_contradictions(self, claim_id: str) -> list[Claim]:
+        row = self.connection.execute(
+            "SELECT entity_id, polarity FROM claims WHERE claim_id = ? AND settled = 1",
+            (claim_id,),
+        ).fetchone()
+        if row is None or row["entity_id"] is None or row["polarity"] is None:
+            return []
+        opposite = _opposite_polarity(row["polarity"])
+        if opposite is None:
+            return []
+        rows = self.connection.execute(
+            """
+            SELECT claim_json FROM claims
+            WHERE settled = 1
+              AND claim_id != ?
+              AND entity_id = ?
+              AND polarity = ?
+            ORDER BY wealth DESC, claim_id ASC
+            """,
+            (claim_id, row["entity_id"], opposite),
+        ).fetchall()
+        return [Claim.model_validate(json.loads(result["claim_json"])) for result in rows]
+
+
+def _claim_text(claim: Claim) -> str:
+    parts = [
+        claim.claim_id,
+        claim.claim_type.value,
+        claim.claim_status.value,
+        claim.title,
+        claim.summary,
+        claim.formal_statement or "",
+        str(claim.metadata.get("entity_id", "")),
+        str(claim.metadata.get("polarity", "")),
+    ]
+    if claim.settlement is not None:
+        parts.extend(
+            [
+                claim.settlement.status.value,
+                str(claim.settlement.proper_score or ""),
+                str(claim.settlement.wealth.wealth),
+            ]
+        )
+    return " ".join(part for part in parts if part)
+
+
+def _is_settled(claim: Claim) -> bool:
+    return bool(claim.settlement is not None and claim.settlement.events)
+
+
+def _wealth(claim: Claim) -> float:
+    if claim.settlement is None:
+        return 0.0
+    return claim.settlement.wealth.wealth
+
+
+def _metadata_string(claim: Claim, key: str) -> str | None:
+    value = claim.metadata.get(key)
+    if value is None:
+        return None
+    return str(value)
+
+
+def _opposite_polarity(polarity: str) -> str | None:
+    pairs = {
+        "positive": "negative",
+        "negative": "positive",
+        "true": "false",
+        "false": "true",
+        "support": "oppose",
+        "oppose": "support",
+    }
+    return pairs.get(polarity.lower())

chimera_memory/adapters/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

chimera_memory/adapters/git.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+
+from chimera_memory_types.finding import EvidenceRef, EvidenceRefType
+
+
+def capture_git_evidence(
+    root: Path | str | None = None,
+    claim_time: datetime | None = None,
+) -> tuple[list[EvidenceRef], dict[str, object]]:
+    repo = Path(root) if root is not None else Path.cwd()
+    available_at = claim_time or datetime.now(UTC)
+
+    head = _run_git(repo, "rev-parse", "HEAD")
+    if head.missing:
+        return [], {"git_available": False, "reason": "git executable not available"}
+    if not head.ok:
+        return [], {"git_available": False, "reason": head.reason}
+
+    commit_sha = head.stdout.strip()
+    branch_result = _run_git(repo, "branch", "--show-current")
+    branch = branch_result.stdout.strip() if branch_result.ok else ""
+    if not branch:
+        branch = "HEAD"
+
+    status_result = _run_git(repo, "status", "--short")
+    status = status_result.stdout.splitlines() if status_result.ok else []
+    files_changed = [_status_path(line) for line in status if _status_path(line)]
+
+    metadata: dict[str, object] = {
+        "git_available": True,
+        "commit_sha": commit_sha,
+        "branch": branch,
+        "files_changed": files_changed,
+        "dirty_state": bool(status),
+        "status": status,
+    }
+    return [
+        EvidenceRef(
+            ref_type=EvidenceRefType.EXTERNAL,
+            ref_id=f"git:{commit_sha}",
+            available_at=available_at,
+        )
+    ], metadata
+
+
+class _GitResult:
+    def __init__(
+        self,
+        *,
+        ok: bool,
+        stdout: str = "",
+        reason: str = "",
+        missing: bool = False,
+    ) -> None:
+        self.ok = ok
+        self.stdout = stdout
+        self.reason = reason
+        self.missing = missing
+
+
+def _run_git(root: Path, *args: str) -> _GitResult:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=root,
+            check=False,
+            text=True,
+            capture_output=True,
+            shell=False,
+        )
+    except FileNotFoundError:
+        return _GitResult(ok=False, reason="git executable not available", missing=True)
+
+    if result.returncode != 0:
+        reason = result.stderr.strip() or result.stdout.strip() or "git command failed"
+        return _GitResult(ok=False, reason=reason)
+    return _GitResult(ok=True, stdout=result.stdout)
+
+
+def _status_path(line: str) -> str:
+    if " -> " in line:
+        return line.split(" -> ", 1)[1].strip()
+    return line[3:].strip()

chimera_memory/adapters/manual.py

@@ -0,0 +1 @@
+__all__: list[str] = []

chimera_memory/adapters/pytest_ci.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+import time
+from dataclasses import dataclass, field
+
+_EXCERPT_MAX = 2000
+_ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]|\x1b\(B")
+
+
+@dataclass(frozen=True)
+class PytestRunResult:
+    command: list[str]
+    exit_code: int
+    observed: bool
+    duration_seconds: float
+    stdout_excerpt: str = field(default="")
+    stderr_excerpt: str = field(default="")
+
+
+def run_pytest(command_args: list[str]) -> PytestRunResult:
+    """Run pytest and capture output for witness storage while showing it live.
+
+    Captures stdout+stderr as bounded, redacted excerpts for failure witnesses.
+    Output is printed to the terminal so the developer sees it.
+    """
+    from chimera_memory.redaction import redact
+
+    command = _pytest_command(command_args)
+    started_at = time.monotonic()
+    result = subprocess.run(
+        command, shell=False, capture_output=True, text=True, errors="replace"
+    )
+    duration_seconds = time.monotonic() - started_at
+    exit_code = int(result.returncode)
+
+    # Print to terminal so developer sees output
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+        sys.stdout.flush()
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+        sys.stderr.flush()
+
+    stdout_raw = _ANSI_RE.sub("", (result.stdout or "")[-_EXCERPT_MAX:])
+    stderr_raw = _ANSI_RE.sub("", (result.stderr or "")[-_EXCERPT_MAX:])
+    return PytestRunResult(
+        command=command,
+        exit_code=exit_code,
+        observed=exit_code == 0,
+        duration_seconds=duration_seconds,
+        stdout_excerpt=redact(stdout_raw),
+        stderr_excerpt=redact(stderr_raw),
+    )
+
+
+def run_command(command_args: list[str]) -> PytestRunResult:
+    """Run an arbitrary command and return a result shaped like PytestRunResult.
+
+    exit code 0 → observed=True (VALIDATED)
+    exit code nonzero → observed=False (CONTRADICTED)
+    Captures stdout/stderr as bounded excerpts (last _EXCERPT_MAX chars).
+    """
+    from chimera_memory.redaction import redact
+
+    started_at = time.monotonic()
+    result = subprocess.run(
+        command_args, shell=False, capture_output=True, text=True, errors="replace"
+    )
+    duration_seconds = time.monotonic() - started_at
+    exit_code = int(result.returncode)
+    return PytestRunResult(
+        command=command_args,
+        exit_code=exit_code,
+        observed=exit_code == 0,
+        duration_seconds=duration_seconds,
+        stdout_excerpt=redact(_ANSI_RE.sub("", (result.stdout or "")[-_EXCERPT_MAX:])),
+        stderr_excerpt=redact(_ANSI_RE.sub("", (result.stderr or "")[-_EXCERPT_MAX:])),
+    )
+
+
+def _pytest_command(command_args: list[str]) -> list[str]:
+    if not command_args or command_args[0] != "pytest":
+        raise ValueError("wrap supports pytest commands only")
+    return [sys.executable, "-m", "pytest", *command_args[1:]]

chimera_memory/append_state.py

@@ -0,0 +1,159 @@
+"""Append-state cache for O(1) claim/integrity appends.
+
+Stores derived state (last line number, last chain hash) so append_claim
+avoids re-reading the full claims.jsonl and integrity.jsonl on every write.
+
+This is a cache/accelerator only — NOT the source of truth.
+canonical source of truth: claims.jsonl + integrity.jsonl
+verify always reads the canonical files, ignoring this cache.
+
+Validation: before trusting a loaded state, we read only the last line of
+integrity.jsonl (O(1) via seek-from-end) and compare. If mismatch, we rebuild
+from canonical files (O(N) fallback). This closes the stale-valid-JSON caveat.
+
+If the cache is missing, corrupt, stale, or mismatched it is rebuilt from
+canonical files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+_STATE_FILE = "append_state.json"
+
+
+@dataclass
+class AppendState:
+    last_line_number: int        # number of non-empty lines currently in claims.jsonl
+    last_chain_hash: str | None  # chain_hash of the last integrity entry (None if none)
+    last_record_hash: str | None # record_hash of the last claim (for mismatch check)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "last_line_number": self.last_line_number,
+            "last_chain_hash": self.last_chain_hash,
+            "last_record_hash": self.last_record_hash,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> AppendState:
+        return cls(
+            last_line_number=int(d["last_line_number"]),
+            last_chain_hash=d.get("last_chain_hash"),
+            last_record_hash=d.get("last_record_hash"),
+        )
+
+
+def _rebuild_from_canonical(memory_dir: Path) -> AppendState:
+    """Rebuild append state by scanning canonical files. O(N) but only on fallback."""
+    claims_path = memory_dir / "claims.jsonl"
+    integrity_path = memory_dir / "integrity.jsonl"
+
+    last_line_number = 0
+    last_record_hash: str | None = None
+    if claims_path.exists():
+        lines = claims_path.read_text(encoding="utf-8").splitlines()
+        non_empty = [ln for ln in lines if ln.strip()]
+        last_line_number = len(non_empty)
+        if non_empty:
+            last_record_hash = hashlib.sha256(
+                non_empty[-1].rstrip("\n").encode("utf-8")
+            ).hexdigest()
+
+    last_chain_hash: str | None = None
+    if integrity_path.exists():
+        int_lines = integrity_path.read_text(encoding="utf-8").splitlines()
+        for raw in reversed(int_lines):
+            raw = raw.strip()
+            if raw:
+                try:
+                    last_chain_hash = json.loads(raw).get("chain_hash")
+                except (json.JSONDecodeError, KeyError):
+                    pass
+                break
+
+    return AppendState(
+        last_line_number=last_line_number,
+        last_chain_hash=last_chain_hash,
+        last_record_hash=last_record_hash,
+    )
+
+
+def _read_integrity_tail(memory_dir: Path) -> dict[str, object] | None:
+    """Read only the last non-empty line of integrity.jsonl — O(1) via seek.
+
+    Returns the parsed dict, or None if the file is missing/empty/unparseable.
+    Never reads the full file.
+    """
+    integrity_path = memory_dir / "integrity.jsonl"
+    if not integrity_path.exists():
+        return None
+    try:
+        size = integrity_path.stat().st_size
+        if size == 0:
+            return None
+        chunk_size = min(4096, size)
+        with integrity_path.open("rb") as fh:
+            fh.seek(-chunk_size, 2)  # seek from end
+            tail = fh.read().decode("utf-8", errors="replace")
+        for raw in reversed(tail.splitlines()):
+            raw = raw.strip()
+            if raw:
+                result: dict[str, object] = json.loads(raw)
+                return result
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError, ValueError):
+        pass
+    return None
+
+
+def _state_matches_tail(state: AppendState, tail: dict[str, object] | None) -> bool:
+    """Return True if state is consistent with the integrity.jsonl tail entry.
+
+    If tail is None (no integrity entries), validates state reflects empty chain.
+    """
+    if tail is None:
+        # No integrity entries yet — valid only if chain is empty.
+        return state.last_chain_hash is None
+    try:
+        line_ok = int(str(tail["line_number"])) == state.last_line_number
+        chain_ok = tail.get("chain_hash") == state.last_chain_hash
+        record_ok = (
+            state.last_record_hash is None
+            or tail.get("record_hash") == state.last_record_hash
+        )
+        return line_ok and chain_ok and record_ok
+    except (KeyError, TypeError, ValueError):
+        return False
+
+
+def load_or_rebuild(memory_dir: Path) -> AppendState:
+    """Load cached append state, validating against integrity tail; rebuild if needed.
+
+    Fast path (valid state AND matches integrity.jsonl tail): O(1).
+    Slow path (any mismatch, missing, or corrupt): O(N) rebuild.
+    """
+    state_path = memory_dir / _STATE_FILE
+    if state_path.exists():
+        try:
+            d = json.loads(state_path.read_text(encoding="utf-8"))
+            state = AppendState.from_dict(d)
+            tail = _read_integrity_tail(memory_dir)
+            if _state_matches_tail(state, tail):
+                return state
+            # Stale or mismatched — fall through to rebuild
+        except (json.JSONDecodeError, KeyError, ValueError):
+            pass  # corrupt → rebuild
+    return _rebuild_from_canonical(memory_dir)
+
+
+def save(memory_dir: Path, state: AppendState) -> None:
+    """Atomically write append state cache via temp-file rename."""
+    state_path = memory_dir / _STATE_FILE
+    tmp_path = memory_dir / f".{_STATE_FILE}.tmp"
+    tmp_path.write_text(json.dumps(state.to_dict(), sort_keys=True), encoding="utf-8")
+    os.replace(tmp_path, state_path)  # atomic on POSIX; best-effort on Windows