Metadata-Version: 2.5
Name: realitydiff
Version: 0.4.0
Summary: Git for beliefs — living claims that watch the internet and version confidence.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: uvicorn[standard]>=0.34.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Reality Diff

Git for beliefs — a version history of a claim: evidence, confidence, and why that number moved. For people tracking a story that is still unfolding (products, policy, markets) who want a trail, not a vibe.

## Why I built this

News feeds overwrite your memory. Last week’s confidence on a rumor disappears under today’s take. I wanted git-style operations on a belief: commit when evidence actually moves, diff two weeks, blame a confidence jump, browse the claim as of a SHA, or revert a panic. So I built Reality Diff.

## News feed vs this

| | Typical news / search | Reality Diff |
| --- | --- | --- |
| Memory | Overwritten | Versioned history per claim |
| Confidence | Vibes / headlines | Explicit score + reason when it moves |
| Compare | Manual screenshots | `diff` between commits |
| Undo | None | `revert` to an earlier belief state |

## Features

**Claims**

- Open a claim (e.g. “Apple is going to replace Siri with an LLM”)
- Living object: evidence for/against, unknowns, predictions, confidence
- Commits only when **meaningful** new evidence appears (cosmetic rewrites dropped)

**Git-style ops**

- `commit` · `diff` · `blame` · `revert` · `watch` · `log`
- Browse the belief as of any SHA
- Background watch via OS timer (macOS LaunchAgent / Linux systemd / Windows task) or the UI interval picker

**Surfaces**

- Local web UI (`realitydiff serve` → <http://localhost:8000>)
- CLI for agents and scripts
- REST API for the same actions

## Install

One line (macOS or Linux, no sudo):

```bash
curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh
```

It installs [uv](https://docs.astral.sh/uv/) into `~/.local/bin` if you don't have it, installs `realitydiff` as an isolated uv tool, and can save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600). It never uses sudo and only touches your shell rc if you say yes.

```bash
# options go after `sh -s --`
curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --yes          # no prompts
curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --ref <tag-or-commit>
curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --uninstall
```

Prefer to read it first? Download `install.sh`, look it over, then run `sh install.sh --help`.

Or install by hand:

```bash
uv tool install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
# or
pipx install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
```

Then:

```bash
realitydiff serve --host 127.0.0.1   # open http://127.0.0.1:8000
```

The installed CLI keeps claims in `~/.local/share/realitydiff/` (set `REALITYDIFF_DB` to change it). Inside a checkout it still uses `data/`.

## Try it (from a checkout)

```bash
export XAI_API_KEY=...
uv sync --extra dev
uv run realitydiff serve
# open http://localhost:8000
```

```bash
uv run realitydiff open "Apple is going to replace Siri with an LLM."
uv run realitydiff watch <claim_id>
uv run realitydiff log <claim_id>
uv run realitydiff diff <claim_id> <sha_a> <sha_b>
```

```bash
uv run realitydiff service install --interval 300
uv run pytest
```

## Stack

Python 3.11+ · uv · local web UI + REST · xAI Responses API (web + X search) · MIT

## License

[MIT](LICENSE)
