realitydiff 0.4.0__py3-none-any.whl

realitydiff/__init__.py

@@ -0,0 +1,8 @@
+"""Reality Diff — Git for beliefs."""
+
+from realitydiff.claim import Claim
+from realitydiff.models import ClaimState, Commit
+from realitydiff.service import RealityDiff
+
+__all__ = ["Claim", "ClaimState", "Commit", "RealityDiff"]
+__version__ = "0.4.0"

realitydiff/__main__.py

@@ -0,0 +1,4 @@
+from realitydiff.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

realitydiff/api.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from realitydiff import __version__
+from realitydiff.config import default_db, load_env
+from realitydiff.models import BlameReport, ClaimDiff, ClaimRecord, Commit, WatchResult
+from realitydiff.schedule import install as install_service
+from realitydiff.schedule import status as service_status
+from realitydiff.schedule import uninstall as uninstall_service
+from realitydiff.service import RealityDiff
+from realitydiff.watcher import WatchLoop
+from realitydiff.xai import XAIError
+
+
+STATIC = Path(__file__).parent / "static"
+load_env()
+DEFAULT_DB = default_db()
+log = logging.getLogger("realitydiff.api")
+
+
+class CreateClaimBody(BaseModel):
+    statement: str = Field(min_length=3, max_length=2000)
+    author: str = Field(default="reasoner", max_length=80)
+
+
+class CommitBody(BaseModel):
+    message: str = Field(min_length=1, max_length=500)
+    author: str = Field(default="user", max_length=80)
+    reason: str = Field(default="", max_length=4000)
+
+
+class RevertBody(BaseModel):
+    sha: str = Field(min_length=7, max_length=64)
+    author: str = Field(default="user", max_length=80)
+
+
+class ServiceBody(BaseModel):
+    interval_seconds: int = Field(default=300, ge=30, le=86_400)
+
+
+class WatchConfigBody(BaseModel):
+    watching: bool = True
+    interval_seconds: int | None = Field(default=None, ge=30, le=86_400)
+
+
+def create_app(
+    engine: RealityDiff | None = None,
+    *,
+    start_watcher: bool = True,
+) -> FastAPI:
+    engine = engine or RealityDiff.open(DEFAULT_DB)
+    watcher = WatchLoop(engine)
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        if start_watcher:
+            watcher.start()
+        yield
+        watcher.stop()
+
+    app = FastAPI(title="Reality Diff", version=__version__, lifespan=lifespan)
+    app.state.engine = engine
+    app.state.watcher = watcher
+
+    @app.exception_handler(StarletteHTTPException)
+    async def _http_exc(request: Request, exc: StarletteHTTPException):
+        detail = exc.detail
+        if not isinstance(detail, str):
+            detail = str(detail)
+        return JSONResponse(status_code=exc.status_code, content={"detail": detail})
+
+    @app.get("/api/health")
+    def health() -> dict[str, str]:
+        try:
+            engine.store.list_claims()
+            db = "ok"
+        except Exception as exc:
+            db = f"error:{exc}"
+        status = "ok" if db == "ok" else "degraded"
+        return {"status": status, "name": "realitydiff", "version": __version__, "db": db}
+
+    @app.get("/api/claims")
+    def list_claims() -> list[dict]:
+        out = []
+        for record in engine.store.list_claims():
+            head = engine.store.head_commit(record.id)
+            history = engine.store.log(record.id)
+            out.append(
+                {
+                    **record.model_dump(mode="json"),
+                    "confidence": head.state.confidence if head else None,
+                    "summary": head.state.summary if head else "",
+                    "commit_count": len(history),
+                    "spark": [c.new_confidence for c in reversed(history[-24:])],
+                }
+            )
+        return out
+
+    @app.post("/api/claims")
+    def create_claim(body: CreateClaimBody) -> dict:
+        try:
+            living, commit = engine.open_claim(body.statement, author=body.author)
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        except XAIError as exc:
+            raise HTTPException(502, f"Reasoner failed: {exc}") from exc
+        except Exception as exc:
+            log.exception("open_claim failed")
+            raise HTTPException(502, f"Reasoner failed: {exc}") from exc
+        return {
+            "claim": living.refresh().model_dump(mode="json"),
+            "commit": commit.model_dump(mode="json"),
+        }
+
+    @app.get("/api/claims/{claim_id}")
+    def get_claim(claim_id: str) -> dict:
+        living = _claim(engine, claim_id)
+        head = living.head
+        working = living.working
+        return {
+            "claim": living.refresh().model_dump(mode="json"),
+            "head": head.model_dump(mode="json") if head else None,
+            "working": working.model_dump(mode="json") if working else None,
+            "dirty": bool(head and working and head.state.tree_hash() != working.tree_hash()),
+        }
+
+    @app.get("/api/claims/{claim_id}/log")
+    def claim_log(claim_id: str) -> list[Commit]:
+        return _claim(engine, claim_id).log()
+
+    @app.get("/api/claims/{claim_id}/diff")
+    def claim_diff(
+        claim_id: str,
+        a: str | None = Query(default=None),
+        b: str | None = Query(default=None),
+    ) -> ClaimDiff:
+        try:
+            return _claim(engine, claim_id).diff(a, b)
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+
+    @app.get("/api/claims/{claim_id}/blame")
+    def claim_blame(claim_id: str) -> BlameReport:
+        return _claim(engine, claim_id).blame()
+
+    @app.post("/api/claims/{claim_id}/commit")
+    def claim_commit(claim_id: str, body: CommitBody) -> Commit:
+        try:
+            return _claim(engine, claim_id).commit(body.message, author=body.author, reason=body.reason)
+        except RuntimeError as exc:
+            raise HTTPException(409, str(exc)) from exc
+
+    @app.post("/api/claims/{claim_id}/revert")
+    def claim_revert(claim_id: str, body: RevertBody) -> Commit:
+        try:
+            return _claim(engine, claim_id).revert(body.sha, author=body.author)
+        except KeyError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except (ValueError, RuntimeError) as exc:
+            raise HTTPException(400, str(exc)) from exc
+
+    @app.get("/api/claims/{claim_id}/at/{sha}")
+    def claim_at(claim_id: str, sha: str) -> dict:
+        living = _claim(engine, claim_id)
+        try:
+            commit = living._resolve(sha)
+        except ValueError as exc:
+            raise HTTPException(400, str(exc)) from exc
+        if commit is None:
+            raise HTTPException(404, f"Unknown commit {sha}")
+        return {
+            "claim": living.refresh().model_dump(mode="json"),
+            "commit": commit.model_dump(mode="json"),
+            "parent_id": commit.parent_id,
+            "is_head": living.head is not None and living.head.id == commit.id,
+            "browse": True,
+        }
+
+    @app.get("/api/claims/{claim_id}/tree")
+    def claim_tree(claim_id: str) -> dict:
+        living = _claim(engine, claim_id)
+        history = living.log()
+        nodes = []
+        for commit in reversed(history):
+            nodes.append(
+                {
+                    "id": commit.id,
+                    "parent_id": commit.parent_id,
+                    "message": commit.message,
+                    "author": commit.author,
+                    "created_at": commit.created_at.isoformat(),
+                    "confidence": commit.new_confidence,
+                    "previous_confidence": commit.previous_confidence,
+                    "reason": commit.reason,
+                    "is_head": living.head is not None and living.head.id == commit.id,
+                }
+            )
+        return {"claim_id": claim_id, "head": living.head.id if living.head else None, "nodes": nodes}
+
+    @app.post("/api/claims/{claim_id}/watch")
+    def claim_watch(claim_id: str) -> WatchResult:
+        _claim(engine, claim_id)
+        try:
+            return engine.watch(claim_id, author="watcher")
+        except XAIError as exc:
+            raise HTTPException(502, f"Watch failed: {exc}") from exc
+        except Exception as exc:
+            log.exception("watch failed")
+            raise HTTPException(502, f"Watch failed: {exc}") from exc
+
+    @app.post("/api/claims/{claim_id}/watching")
+    def set_watching(claim_id: str, body: WatchConfigBody) -> ClaimRecord:
+        _claim(engine, claim_id)
+        try:
+            engine.store.set_watching(claim_id, body.watching, body.interval_seconds)
+        except RuntimeError as exc:
+            raise HTTPException(409, str(exc)) from exc
+        record = engine.store.get_claim(claim_id)
+        assert record is not None
+        return record
+
+    @app.get("/api/service")
+    def get_service() -> dict:
+        return {**service_status(), "db": str(Path(engine.store.path).expanduser().resolve())}
+
+    @app.post("/api/service")
+    def put_service(body: ServiceBody) -> dict:
+        try:
+            return install_service(body.interval_seconds, db=DEFAULT_DB)
+        except Exception as exc:
+            raise HTTPException(500, f"Could not install watch service: {exc}") from exc
+
+    @app.delete("/api/service")
+    def drop_service() -> dict:
+        try:
+            return uninstall_service()
+        except Exception as exc:
+            raise HTTPException(500, f"Could not remove watch service: {exc}") from exc
+
+    if STATIC.exists():
+        app.mount("/static", StaticFiles(directory=STATIC), name="static")
+
+        @app.get("/")
+        def index() -> FileResponse:
+            return FileResponse(STATIC / "index.html", headers={"Cache-Control": "no-store"})
+
+        @app.get("/favicon.svg")
+        def favicon() -> FileResponse:
+            path = STATIC / "favicon.svg"
+            if not path.exists():
+                raise HTTPException(404, "no favicon")
+            return FileResponse(path, media_type="image/svg+xml")
+
+    return app
+
+
+def _claim(engine: RealityDiff, claim_id: str):
+    try:
+        return engine.claim(claim_id)
+    except KeyError as exc:
+        raise HTTPException(404, f"Unknown claim {claim_id}") from exc

realitydiff/blame.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from realitydiff.models import BlameEntry, BlameReport, ClaimState, Commit
+
+
+def blame_history(claim_id: str, history: list[Commit]) -> BlameReport:
+    """history is newest-first (git log order)."""
+    if not history:
+        return BlameReport(claim_id=claim_id, head=None, entries=[])
+
+    chronological = list(reversed(history))
+    head = history[0].id
+    first_seen: dict[str, tuple[Commit, object]] = {}
+    last_seen: dict[str, tuple[Commit, object]] = {}
+
+    def note(path: str, commit: Commit, value: object) -> None:
+        if path not in first_seen:
+            first_seen[path] = (commit, value)
+        last_seen[path] = (commit, value)
+
+    previous: ClaimState | None = None
+    for commit in chronological:
+        state = commit.state
+        if previous is None or previous.statement != state.statement:
+            note("statement", commit, state.statement)
+        if previous is None or previous.refined_statement != state.refined_statement:
+            note("refined_statement", commit, state.refined_statement)
+        if previous is None or previous.confidence != state.confidence:
+            note("confidence", commit, state.confidence)
+        if previous is None or previous.summary != state.summary:
+            note("summary", commit, state.summary)
+        if previous is None or (
+            (previous.outcome is None) != (state.outcome is None)
+            or (
+                previous.outcome
+                and state.outcome
+                and previous.outcome.model_dump(mode="json") != state.outcome.model_dump(mode="json")
+            )
+        ):
+            note("outcome", commit, state.outcome.model_dump(mode="json") if state.outcome else None)
+
+        prev_for = {item.id: item for item in previous.evidence_for} if previous else {}
+        prev_against = {item.id: item for item in previous.evidence_against} if previous else {}
+        prev_unknowns = {item.id: item for item in previous.unknowns} if previous else {}
+        prev_preds = {item.id: item for item in previous.predictions} if previous else {}
+
+        for item in state.evidence_for:
+            dumped = item.model_dump(mode="json")
+            if prev_for.get(item.id) is None or prev_for[item.id].model_dump(mode="json") != dumped:
+                note(f"evidence_for/{item.id}", commit, dumped)
+        for item in state.evidence_against:
+            dumped = item.model_dump(mode="json")
+            if prev_against.get(item.id) is None or prev_against[item.id].model_dump(mode="json") != dumped:
+                note(f"evidence_against/{item.id}", commit, dumped)
+        for item in state.unknowns:
+            dumped = item.model_dump(mode="json")
+            if prev_unknowns.get(item.id) is None or prev_unknowns[item.id].model_dump(mode="json") != dumped:
+                note(f"unknowns/{item.id}", commit, dumped)
+        for item in state.predictions:
+            dumped = item.model_dump(mode="json")
+            if prev_preds.get(item.id) is None or prev_preds[item.id].model_dump(mode="json") != dumped:
+                note(f"predictions/{item.id}", commit, dumped)
+        previous = state
+
+    entries: list[BlameEntry] = []
+    for path, (introduced, value) in first_seen.items():
+        last_commit, last_value = last_seen[path]
+        item_id = path.split("/", 1)[1] if "/" in path else None
+        entries.append(
+            BlameEntry(
+                path=path,
+                item_id=item_id,
+                introduced_in=introduced.id,
+                introduced_at=introduced.created_at,
+                author=introduced.author,
+                message=introduced.message,
+                last_changed_in=last_commit.id,
+                last_changed_at=last_commit.created_at,
+                last_author=last_commit.author,
+                last_message=last_commit.message,
+                value=last_value if last_value is not None else value,
+            )
+        )
+    entries.sort(key=lambda entry: entry.path)
+    return BlameReport(claim_id=claim_id, head=head, entries=entries)

realitydiff/claim.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from realitydiff.blame import blame_history
+from realitydiff.diffing import diff_states
+from realitydiff.models import BlameReport, ClaimDiff, ClaimRecord, ClaimState, Commit
+from realitydiff.store import BeliefStore
+
+
+class Claim:
+    """Living claim with git-like operations: commit, diff, blame, revert."""
+
+    def __init__(self, store: BeliefStore, record: ClaimRecord) -> None:
+        self._store = store
+        self.id = record.id
+        self.record = record
+
+    def refresh(self) -> ClaimRecord:
+        record = self._store.get_claim(self.id)
+        if record is None:
+            raise KeyError(self.id)
+        self.record = record
+        return record
+
+    @property
+    def head(self) -> Commit | None:
+        return self._store.head_commit(self.id)
+
+    @property
+    def working(self) -> ClaimState | None:
+        return self._store.working_state(self.id)
+
+    def checkout(self) -> ClaimState:
+        state = self.working or (self.head.state if self.head else None)
+        if state is None:
+            raise RuntimeError("Claim has no state yet")
+        return state
+
+    def commit(self, message: str, *, author: str = "user", reason: str = "") -> Commit:
+        working = self._store.working_state(self.id)
+        head = self._store.head_commit(self.id)
+        if working is None:
+            if head is None:
+                raise RuntimeError("Nothing to commit")
+            working = head.state
+        if head and working.tree_hash() == head.state.tree_hash():
+            raise RuntimeError("Working tree clean")
+        commit = Commit.create(
+            claim_id=self.id,
+            parent_id=head.id if head else None,
+            state=working,
+            author=author,
+            message=message,
+            reason=reason,
+            previous_confidence=head.state.confidence if head else None,
+        )
+        return self._store.append_commit(commit)
+
+    def diff(self, a: str | None = None, b: str | None = None) -> ClaimDiff:
+        if a is None and b is None:
+            head = self.head
+            working = self.working
+            if head is None:
+                return diff_states(None, working, to_id="WORKING")
+            return diff_states(head.state, working, from_id=head.id, to_id="WORKING")
+        left = self._resolve(a) if a else None
+        right = self._resolve(b) if b else self.head
+        return diff_states(
+            left.state if left else None,
+            right.state if right else None,
+            from_id=left.id if left else None,
+            to_id=right.id if right else None,
+            reason=(right.reason if right else ""),
+        )
+
+    def log(self) -> list[Commit]:
+        return self._store.log(self.id)
+
+    def blame(self) -> BlameReport:
+        return blame_history(self.id, self.log())
+
+    def revert(self, sha: str, *, author: str = "user") -> Commit:
+        target = self._store.get_commit(sha, claim_id=self.id)
+        if target is None:
+            raise KeyError(f"Unknown commit {sha}")
+        head = self.head
+        if head is None:
+            raise RuntimeError("Nothing to revert")
+        if target.state.tree_hash() == head.state.tree_hash():
+            raise RuntimeError("HEAD already matches that commit")
+        commit = Commit.create(
+            claim_id=self.id,
+            parent_id=head.id,
+            state=target.state,
+            author=author,
+            message=f"Revert to {sha[:12]}",
+            reason=f"Restored belief snapshot {sha[:12]}. Previous confidence {head.state.confidence}% → {target.state.confidence}%.",
+            previous_confidence=head.state.confidence,
+        )
+        return self._store.append_commit(commit)
+
+    def _resolve(self, ref: str) -> Commit | None:
+        if ref.upper() in {"HEAD", "WORKING"}:
+            return self.head
+        return self._store.get_commit(ref, claim_id=self.id)

realitydiff/cli.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from realitydiff import __version__
+from realitydiff.config import config_file, default_db, load_env
+from realitydiff.service import RealityDiff
+from realitydiff.xai import XAIError
+
+load_env()
+DEFAULT_DB = default_db()
+
+
+def _db_path() -> str:
+    return str(Path(DEFAULT_DB).expanduser().resolve())
+
+
+def _engine() -> RealityDiff:
+    return RealityDiff.open(DEFAULT_DB)
+
+
+def _print(data) -> None:
+    if hasattr(data, "model_dump"):
+        print(json.dumps(data.model_dump(mode="json"), indent=2, default=str))
+    else:
+        print(json.dumps(data, indent=2, default=str))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="realitydiff", description="Git for beliefs")
+    parser.add_argument("--version", action="version", version=f"realitydiff {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    open_p = sub.add_parser("open", help="Create a living claim and survey the internet")
+    open_p.add_argument("statement")
+
+    watch_p = sub.add_parser("watch", help="Search for new evidence and maybe commit")
+    watch_p.add_argument("claim_id")
+
+    sub.add_parser("watch-all", help="Watch every due claim once (used by the installed service)")
+
+    log_p = sub.add_parser("log", help="Commit history")
+    log_p.add_argument("claim_id")
+
+    show_p = sub.add_parser("show", help="HEAD state")
+    show_p.add_argument("claim_id")
+
+    diff_p = sub.add_parser("diff", help="Diff two commits (default HEAD vs WORKING)")
+    diff_p.add_argument("claim_id")
+    diff_p.add_argument("a", nargs="?")
+    diff_p.add_argument("b", nargs="?")
+
+    blame_p = sub.add_parser("blame", help="Who introduced each piece of the belief")
+    blame_p.add_argument("claim_id")
+
+    revert_p = sub.add_parser("revert", help="Restore a prior belief snapshot as a new commit")
+    revert_p.add_argument("claim_id")
+    revert_p.add_argument("sha")
+
+    commit_p = sub.add_parser("commit", help="Commit the working tree")
+    commit_p.add_argument("claim_id")
+    commit_p.add_argument("-m", "--message", required=True)
+
+    ls_p = sub.add_parser("ls", help="List claims")
+
+    serve_p = sub.add_parser("serve", help="Run the web UI")
+    serve_p.add_argument("--host", default="0.0.0.0")
+    serve_p.add_argument("--port", type=int, default=8000)
+
+    svc = sub.add_parser("service", help="Install a background timer that runs claim.watch()")
+    svc_sub = svc.add_subparsers(dest="service_cmd", required=True)
+    inst = svc_sub.add_parser("install", help="Install a LaunchAgent / systemd user timer / Windows task")
+    inst.add_argument("--interval", type=int, default=300, help="Seconds between watches (min 30)")
+    svc_sub.add_parser("uninstall", help="Remove the background watch service")
+    svc_sub.add_parser("status", help="Show whether the service is installed")
+
+    args = parser.parse_args(argv)
+    if args.cmd == "serve":
+        import uvicorn
+
+        print(f"realitydiff: database {_db_path()}", file=sys.stderr)
+        uvicorn.run("realitydiff.api:create_app", host=args.host, port=args.port, factory=True, reload=False)
+        return 0
+
+    if args.cmd == "service":
+        from realitydiff.schedule import install, status, uninstall
+
+        if args.service_cmd == "install":
+            _print(install(args.interval, db=DEFAULT_DB))
+            return 0
+        if args.service_cmd == "uninstall":
+            _print(uninstall())
+            return 0
+        _print({**status(), "db": _db_path()})
+        return 0
+
+    try:
+        engine = _engine()
+    except XAIError as exc:
+        print(f"realitydiff: {exc}. Export it or save it in {config_file()}", file=sys.stderr)
+        return 2
+    if args.cmd == "watch-all":
+        _print([item.model_dump(mode="json") for item in engine.watch_due()])
+        return 0
+    if args.cmd == "open":
+        living, commit = engine.open_claim(args.statement)
+        record = living.refresh()
+        _print(
+            {
+                "claim_id": living.id,
+                "commit": commit.id,
+                "confidence": commit.new_confidence,
+                "reason": commit.reason,
+                "closed": record.closed,
+                "outcome_verdict": record.outcome_verdict,
+            }
+        )
+        return 0
+    if args.cmd == "ls":
+        _print([record.model_dump(mode="json") for record in engine.store.list_claims()])
+        return 0
+    if args.cmd == "watch":
+        _print(engine.watch(args.claim_id))
+        return 0
+    living = engine.claim(args.claim_id)
+    if args.cmd == "log":
+        _print(
+            [
+                {
+                    "id": c.id,
+                    "parent": c.parent_id,
+                    "confidence": c.new_confidence,
+                    "message": c.message,
+                    "reason": c.reason,
+                    "author": c.author,
+                    "at": c.created_at.isoformat(),
+                }
+                for c in living.log()
+            ]
+        )
+        return 0
+    if args.cmd == "show":
+        head = living.head
+        if head is None:
+            print("no HEAD", file=sys.stderr)
+            return 1
+        _print(head)
+        return 0
+    if args.cmd == "diff":
+        _print(living.diff(args.a, args.b))
+        return 0
+    if args.cmd == "blame":
+        _print(living.blame())
+        return 0
+    if args.cmd == "revert":
+        _print(living.revert(args.sha))
+        return 0
+    if args.cmd == "commit":
+        _print(living.commit(args.message))
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())