realitydiff 0.4.0__py3-none-any.whl

realitydiff/compress.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any
+
+from realitydiff.models import ClaimState, Evidence, Prediction
+
+# Ignore retrieved_at / tiny note rewrites when deciding whether a watch is worth a commit.
+MATERIAL_CONFIDENCE = 1.0
+MATERIAL_WEIGHT = 0.08
+
+
+def compact_belief(state: ClaimState) -> dict[str, Any]:
+    """High-compression snapshot for the model: keep ids, urls, scores; drop timestamps."""
+    return {
+        "statement": state.statement,
+        "refined_statement": state.refined_statement,
+        "confidence": state.confidence,
+        "summary": _clip(state.summary, 420),
+        "evidence_for": [_compact_evidence(item) for item in state.evidence_for],
+        "evidence_against": [_compact_evidence(item) for item in state.evidence_against],
+        "unknowns": [
+            {"id": item.id, "question": _clip(item.question, 180), "why": _clip(item.why_it_matters, 140)}
+            for item in state.unknowns
+        ],
+        "predictions": [_compact_prediction(item) for item in state.predictions],
+        "outcome": state.outcome.model_dump(mode="json") if state.outcome else None,
+    }
+
+
+def is_material_change(before: ClaimState, after: ClaimState) -> bool:
+    if abs(after.confidence - before.confidence) >= MATERIAL_CONFIDENCE:
+        return True
+    if before.statement.strip() != after.statement.strip():
+        return True
+    if _evidence_signature(before.evidence_for) != _evidence_signature(after.evidence_for):
+        return True
+    if _evidence_signature(before.evidence_against) != _evidence_signature(after.evidence_against):
+        return True
+    if {u.question.strip().lower() for u in before.unknowns} != {u.question.strip().lower() for u in after.unknowns}:
+        return True
+    if _prediction_signature(before.predictions) != _prediction_signature(after.predictions):
+        return True
+    if (before.outcome is None) != (after.outcome is None):
+        return True
+    if before.outcome and after.outcome and before.outcome.model_dump(mode="json") != after.outcome.model_dump(mode="json"):
+        return True
+    return False
+
+
+def _compact_evidence(item: Evidence) -> dict[str, Any]:
+    return {
+        "id": item.id,
+        "statement": _clip(item.statement, 220),
+        "source_url": item.source_url,
+        "source_title": item.source_title,
+        "weight": round(item.weight, 2),
+        "notes": _clip(item.notes, 160),
+    }
+
+
+def _compact_prediction(item: Prediction) -> dict[str, Any]:
+    return {
+        "id": item.id,
+        "statement": _clip(item.statement, 180),
+        "due": item.due,
+        "status": item.status,
+        "how_to_falsify": _clip(item.how_to_falsify, 140),
+    }
+
+
+def _evidence_signature(items: list[Evidence]) -> set[tuple[str, str, str, float]]:
+    signed: set[tuple[str, str, str, float]] = set()
+    for item in items:
+        weight = round(item.weight / MATERIAL_WEIGHT) * MATERIAL_WEIGHT
+        signed.add(
+            (
+                item.id,
+                (item.source_url or "").rstrip("/").lower(),
+                item.statement.strip().lower()[:160],
+                round(weight, 2),
+            )
+        )
+    return signed
+
+
+def _prediction_signature(items: list[Prediction]) -> set[tuple[str, str]]:
+    return {(item.statement.strip().lower()[:160], item.status) for item in items}
+
+
+def _clip(text: str, limit: int) -> str:
+    text = (text or "").strip()
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1].rstrip() + "…"

realitydiff/config.py

@@ -0,0 +1,66 @@
+"""User config for installed copies of Reality Diff.
+
+The installer can save settings to ``~/.config/realitydiff/env`` (or
+``$XDG_CONFIG_HOME/realitydiff/env``). Values already set in the
+environment always win over the file.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ALLOWED_KEYS = ("XAI_API_KEY", "REALITYDIFF_DB")
+
+
+def config_file() -> Path:
+    override = os.environ.get("REALITYDIFF_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "realitydiff" / "env"
+
+
+def load_env(path: Path | None = None) -> None:
+    """Read KEY=VALUE lines into os.environ without overriding existing values."""
+    path = path or config_file()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return
+    found: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key.startswith("export "):
+            key = key[len("export ") :].strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+            value = value[1:-1]
+        if key in ALLOWED_KEYS and value:
+            found[key] = value  # last line wins, like sourcing the file
+    for key, value in found.items():
+        if not os.environ.get(key):
+            os.environ[key] = value
+
+
+def default_db() -> str:
+    """Where claims are stored.
+
+    REALITYDIFF_DB wins. Inside a Reality Diff checkout (or wherever an old
+    ``data/realitydiff.sqlite`` already exists) keep that path; otherwise use
+    the user data dir so an installed CLI does not drop a data/ folder
+    wherever it is run.
+    """
+    env = os.environ.get("REALITYDIFF_DB")
+    if env:
+        return env
+    legacy = Path("data") / "realitydiff.sqlite"
+    in_checkout = Path("pyproject.toml").is_file() and Path("src", "realitydiff").is_dir()
+    if legacy.exists() or in_checkout:
+        return "data/realitydiff.sqlite"
+    base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
+    return str(Path(base) / "realitydiff" / "realitydiff.sqlite")

realitydiff/diffing.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from typing import Any
+
+from realitydiff.models import ClaimDiff, ClaimState, Evidence, FieldChange, Prediction, Unknown
+
+
+def _index_evidence(items: list[Evidence]) -> dict[str, Evidence]:
+    return {item.id: item for item in items}
+
+
+def _index_unknowns(items: list[Unknown]) -> dict[str, Unknown]:
+    return {item.id: item for item in items}
+
+
+def _index_predictions(items: list[Prediction]) -> dict[str, Prediction]:
+    return {item.id: item for item in items}
+
+
+def _dump(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+def diff_states(
+    before: ClaimState | None,
+    after: ClaimState | None,
+    *,
+    from_id: str | None = None,
+    to_id: str | None = None,
+    reason: str = "",
+) -> ClaimDiff:
+    changes: list[FieldChange] = []
+    prev_conf = before.confidence if before else None
+    new_conf = after.confidence if after else None
+
+    if before is None and after is None:
+        return ClaimDiff(from_id=from_id, to_id=to_id)
+
+    if before is None and after is not None:
+        changes.append(
+            FieldChange(path="statement", before=None, after=after.statement, kind="added")
+        )
+        return ClaimDiff(
+            from_id=from_id,
+            to_id=to_id,
+            previous_confidence=None,
+            new_confidence=after.confidence,
+            confidence_delta=after.confidence,
+            reason=reason or "Initial belief state.",
+            changes=changes
+            + [
+                FieldChange(path=f"evidence_for/{item.id}", before=None, after=_dump(item), kind="added")
+                for item in after.evidence_for
+            ]
+            + [
+                FieldChange(
+                    path=f"evidence_against/{item.id}", before=None, after=_dump(item), kind="added"
+                )
+                for item in after.evidence_against
+            ]
+            + [
+                FieldChange(path=f"unknowns/{item.id}", before=None, after=_dump(item), kind="added")
+                for item in after.unknowns
+            ]
+            + [
+                FieldChange(
+                    path=f"predictions/{item.id}", before=None, after=_dump(item), kind="added"
+                )
+                for item in after.predictions
+            ],
+        )
+
+    if before is not None and after is None:
+        return ClaimDiff(
+            from_id=from_id,
+            to_id=to_id,
+            previous_confidence=before.confidence,
+            new_confidence=None,
+            confidence_delta=-before.confidence,
+            reason=reason or "Belief deleted.",
+            changes=[FieldChange(path="state", before=_dump(before), after=None, kind="removed")],
+        )
+
+    assert before is not None and after is not None
+
+    for field in ("statement", "refined_statement", "summary"):
+        left = getattr(before, field)
+        right = getattr(after, field)
+        if left != right:
+            changes.append(
+                FieldChange(
+                    path=field,
+                    before=left,
+                    after=right,
+                    kind="changed" if left and right else ("added" if right else "removed"),
+                )
+            )
+
+    if before.confidence != after.confidence:
+        changes.append(
+            FieldChange(
+                path="confidence",
+                before=before.confidence,
+                after=after.confidence,
+                kind="changed",
+            )
+        )
+
+    if (before.outcome is None) != (after.outcome is None) or (
+        before.outcome and after.outcome and before.outcome.model_dump(mode="json") != after.outcome.model_dump(mode="json")
+    ):
+        changes.append(
+            FieldChange(
+                path="outcome",
+                before=_dump(before.outcome) if before.outcome else None,
+                after=_dump(after.outcome) if after.outcome else None,
+                kind="added" if after.outcome and not before.outcome else ("removed" if before.outcome and not after.outcome else "changed"),
+            )
+        )
+
+    for bucket in ("evidence_for", "evidence_against"):
+        left_map = _index_evidence(getattr(before, bucket))
+        right_map = _index_evidence(getattr(after, bucket))
+        for key in sorted(set(left_map) | set(right_map)):
+            if key not in right_map:
+                changes.append(
+                    FieldChange(
+                        path=f"{bucket}/{key}",
+                        before=_dump(left_map[key]),
+                        after=None,
+                        kind="removed",
+                    )
+                )
+            elif key not in left_map:
+                changes.append(
+                    FieldChange(
+                        path=f"{bucket}/{key}",
+                        before=None,
+                        after=_dump(right_map[key]),
+                        kind="added",
+                    )
+                )
+            elif left_map[key].model_dump(mode="json") != right_map[key].model_dump(mode="json"):
+                changes.append(
+                    FieldChange(
+                        path=f"{bucket}/{key}",
+                        before=_dump(left_map[key]),
+                        after=_dump(right_map[key]),
+                        kind="changed",
+                    )
+                )
+
+    left_u = _index_unknowns(before.unknowns)
+    right_u = _index_unknowns(after.unknowns)
+    for key in sorted(set(left_u) | set(right_u)):
+        if key not in right_u:
+            changes.append(
+                FieldChange(path=f"unknowns/{key}", before=_dump(left_u[key]), after=None, kind="removed")
+            )
+        elif key not in left_u:
+            changes.append(
+                FieldChange(path=f"unknowns/{key}", before=None, after=_dump(right_u[key]), kind="added")
+            )
+        elif left_u[key].model_dump(mode="json") != right_u[key].model_dump(mode="json"):
+            changes.append(
+                FieldChange(
+                    path=f"unknowns/{key}",
+                    before=_dump(left_u[key]),
+                    after=_dump(right_u[key]),
+                    kind="changed",
+                )
+            )
+
+    left_p = _index_predictions(before.predictions)
+    right_p = _index_predictions(after.predictions)
+    for key in sorted(set(left_p) | set(right_p)):
+        if key not in right_p:
+            changes.append(
+                FieldChange(
+                    path=f"predictions/{key}", before=_dump(left_p[key]), after=None, kind="removed"
+                )
+            )
+        elif key not in left_p:
+            changes.append(
+                FieldChange(
+                    path=f"predictions/{key}", before=None, after=_dump(right_p[key]), kind="added"
+                )
+            )
+        elif left_p[key].model_dump(mode="json") != right_p[key].model_dump(mode="json"):
+            changes.append(
+                FieldChange(
+                    path=f"predictions/{key}",
+                    before=_dump(left_p[key]),
+                    after=_dump(right_p[key]),
+                    kind="changed",
+                )
+            )
+
+    delta = round(after.confidence - before.confidence, 1)
+    return ClaimDiff(
+        from_id=from_id,
+        to_id=to_id,
+        previous_confidence=before.confidence,
+        new_confidence=after.confidence,
+        confidence_delta=delta,
+        reason=reason,
+        changes=changes,
+    )

realitydiff/hashing.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)
+
+
+def sha1_hex(payload: str | bytes) -> str:
+    data = payload.encode("utf-8") if isinstance(payload, str) else payload
+    return hashlib.sha1(data).hexdigest()
+
+
+def object_id(kind: str, value: Any) -> str:
+    blob = f"{kind} {canonical_json(value)}"
+    return sha1_hex(blob)
+
+
+def stable_item_id(prefix: str, *parts: str) -> str:
+    material = "\n".join(part.strip() for part in parts if part)
+    return f"{prefix}_{sha1_hex(material)[:12]}"

realitydiff/models.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from realitydiff.hashing import object_id, stable_item_id
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Evidence(BaseModel):
+    id: str
+    statement: str
+    source_url: str | None = None
+    source_title: str | None = None
+    retrieved_at: datetime = Field(default_factory=utcnow)
+    weight: float = 0.5
+    notes: str = ""
+
+    @field_validator("weight")
+    @classmethod
+    def clamp_weight(cls, value: float) -> float:
+        return max(0.0, min(1.0, value))
+
+    @classmethod
+    def make(
+        cls,
+        statement: str,
+        *,
+        source_url: str | None = None,
+        source_title: str | None = None,
+        weight: float = 0.5,
+        notes: str = "",
+        retrieved_at: datetime | None = None,
+    ) -> "Evidence":
+        return cls(
+            id=stable_item_id("ev", source_url or "", statement),
+            statement=statement,
+            source_url=source_url,
+            source_title=source_title,
+            weight=weight,
+            notes=notes,
+            retrieved_at=retrieved_at or utcnow(),
+        )
+
+
+class Unknown(BaseModel):
+    id: str
+    question: str
+    why_it_matters: str = ""
+
+    @classmethod
+    def make(cls, question: str, why_it_matters: str = "") -> "Unknown":
+        return cls(
+            id=stable_item_id("uk", question),
+            question=question,
+            why_it_matters=why_it_matters,
+        )
+
+
+class ClaimOutcome(BaseModel):
+    verdict: Literal["confirmed", "falsified", "settled"]
+    summary: str
+    source_url: str | None = None
+    source_title: str | None = None
+    closed_at: datetime = Field(default_factory=utcnow)
+
+
+class Prediction(BaseModel):
+    id: str
+    statement: str
+    due: str | None = None
+    status: Literal["open", "confirmed", "falsified"] = "open"
+    how_to_falsify: str = ""
+
+    @classmethod
+    def make(
+        cls,
+        statement: str,
+        *,
+        due: str | None = None,
+        status: Literal["open", "confirmed", "falsified"] = "open",
+        how_to_falsify: str = "",
+    ) -> "Prediction":
+        return cls(
+            id=stable_item_id("pr", statement),
+            statement=statement,
+            due=due,
+            status=status,
+            how_to_falsify=how_to_falsify,
+        )
+
+
+class ClaimState(BaseModel):
+    statement: str
+    refined_statement: str = ""
+    confidence: float = 50.0
+    evidence_for: list[Evidence] = Field(default_factory=list)
+    evidence_against: list[Evidence] = Field(default_factory=list)
+    unknowns: list[Unknown] = Field(default_factory=list)
+    predictions: list[Prediction] = Field(default_factory=list)
+    summary: str = ""
+    outcome: ClaimOutcome | None = None
+
+    @field_validator("confidence")
+    @classmethod
+    def clamp_confidence(cls, value: float) -> float:
+        return round(max(0.0, min(100.0, value)), 1)
+
+    def tree_hash(self) -> str:
+        data = self.model_dump(mode="json")
+        for bucket in ("evidence_for", "evidence_against"):
+            for item in data.get(bucket) or []:
+                item.pop("retrieved_at", None)
+        return object_id("tree", data)
+
+    def all_evidence(self) -> list[tuple[str, Evidence]]:
+        return [("for", item) for item in self.evidence_for] + [
+            ("against", item) for item in self.evidence_against
+        ]
+
+
+class Commit(BaseModel):
+    id: str
+    claim_id: str
+    parent_id: str | None = None
+    tree_hash: str
+    created_at: datetime
+    author: str
+    message: str
+    reason: str = ""
+    previous_confidence: float | None = None
+    new_confidence: float
+    state: ClaimState
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        claim_id: str,
+        parent_id: str | None,
+        state: ClaimState,
+        author: str,
+        message: str,
+        reason: str = "",
+        previous_confidence: float | None = None,
+        created_at: datetime | None = None,
+    ) -> "Commit":
+        created = created_at or utcnow()
+        tree_hash = state.tree_hash()
+        payload = {
+            "author": author,
+            "claim_id": claim_id,
+            "created_at": created.isoformat(),
+            "message": message,
+            "parent": parent_id,
+            "reason": reason,
+            "tree": tree_hash,
+        }
+        return cls(
+            id=object_id("commit", payload),
+            claim_id=claim_id,
+            parent_id=parent_id,
+            tree_hash=tree_hash,
+            created_at=created,
+            author=author,
+            message=message,
+            reason=reason,
+            previous_confidence=previous_confidence,
+            new_confidence=state.confidence,
+            state=state,
+        )
+
+
+class ClaimRecord(BaseModel):
+    id: str
+    created_at: datetime
+    title: str
+    watching: bool = True
+    watch_interval_seconds: int = 300
+    head: str | None = None
+    last_watched_at: datetime | None = None
+    last_response_id: str | None = None
+    compaction_json: str | None = None
+    closed: bool = False
+    closed_at: datetime | None = None
+    outcome_verdict: Literal["confirmed", "falsified", "settled"] | None = None
+
+
+class FieldChange(BaseModel):
+    path: str
+    before: Any = None
+    after: Any = None
+    kind: Literal["added", "removed", "changed"]
+
+
+class ClaimDiff(BaseModel):
+    from_id: str | None
+    to_id: str | None
+    previous_confidence: float | None
+    new_confidence: float | None
+    confidence_delta: float = 0.0
+    reason: str = ""
+    changes: list[FieldChange] = Field(default_factory=list)
+
+
+class BlameEntry(BaseModel):
+    path: str
+    item_id: str | None = None
+    introduced_in: str
+    introduced_at: datetime
+    author: str
+    message: str
+    last_changed_in: str
+    last_changed_at: datetime
+    last_author: str
+    last_message: str
+    value: Any = None
+
+
+class BlameReport(BaseModel):
+    claim_id: str
+    head: str | None
+    entries: list[BlameEntry] = Field(default_factory=list)
+
+
+class WatchResult(BaseModel):
+    claim_id: str
+    changed: bool
+    commit: Commit | None = None
+    diff: ClaimDiff | None = None
+    detail: str = ""
+    in_progress: bool = False
+    cached_tokens: int = 0
+    closed: bool = False