Metadata-Version: 2.5
Name: realitydiff
Version: 0.4.5
Summary: Git for beliefs — living claims that watch the internet and version confidence.
Project-URL: Homepage, https://github.com/kavin0x/RealityDiff
Project-URL: Source, https://github.com/kavin0x/RealityDiff
Project-URL: Issues, https://github.com/kavin0x/RealityDiff/issues
Author: Kavin Shah
License: MIT License
        
        Copyright (c) 2026 Reality Diff contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: beliefs,claims,fact-checking,grok,xai
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
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. This is alpha. Claims still depend on xAI search; compare is a thin side-by-side, not a second reasoner.

## 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://127.0.0.1:8000>)
- Compare view: one question, several models, side by side (xAI and/or OpenRouter)
- CLI for agents and scripts
- REST API for the same actions

## Install

From PyPI (needs Python 3.11+). `uv` and `pipx` each give it its own isolated environment, so use one of them first:

```bash
uv tool install realitydiff     # or: pipx install realitydiff
realitydiff                     # first run walks you through setup
```

Plain `pip install realitydiff` works inside a virtualenv. On macOS and many Linux setups, system-wide `pip` refuses with an "externally-managed-environment" error, which is why I lead with `uv`/`pipx`.

The first time you run `realitydiff` in a terminal (or any time you run `realitydiff setup`), it checks the install, offers to save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600, typing is hidden), optionally offers an `OPENROUTER_API_KEY` the same way (default no), and tells you if the command isn't on your PATH. `realitydiff setup --yes` never prompts, and `--no-key` skips both keys.

Prefer a script that also installs `uv` for you (macOS or Linux, no sudo)?

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

Read it first if you like: download `install.sh`, then run `sh install.sh --help`. Options go after `sh -s --`: `--yes`, `--ref <tag-or-commit>`, `--uninstall`.

Want the latest unreleased code instead of PyPI?

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

Then:

```bash
realitydiff serve                       # binds to 127.0.0.1 only; 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=...                 # claims / watch (xAI Responses API)
export OPENROUTER_API_KEY=...          # optional; compare via OpenRouter
# or put the same keys in ~/.config/realitydiff/env (mode 600)
# claims default to grok-4.7 (500k context). Override with XAI_MODEL.
# optional: OPENROUTER_MODEL=openai/gpt-6-luna
uv sync --extra dev
uv run realitydiff serve               # 127.0.0.1:8000
# open http://127.0.0.1:8000 then click "compare models"
```

### Localhost only by default

The web UI and API have no accounts. It's alpha software and I built it to run on your own machine, so `realitydiff serve` binds to 127.0.0.1 and guards that:

- It only answers requests whose Host header is `127.0.0.1`, `localhost` or `[::1]` (any port). Anything else gets a 400. That blocks DNS rebinding, where a web page you visit points its own domain at 127.0.0.1 to reach your server.
- A browser POST or DELETE from another site's Origin gets a 403. Requests with no Origin header (curl, scripts) still work.
- The CLI `compare` command talks to the providers directly, so none of this touches it.

If you really want other machines to reach it, `serve` won't start on a non-loopback `--host` until you set `REALITYDIFF_TOKEN` (in your env or `~/.config/realitydiff/env`). Then every `/api/` call needs it, as `Authorization: Bearer <token>` or an `X-RealityDiff-Token` header. The web UI asks for it once per tab. Add the names other machines use to reach you with `REALITYDIFF_ALLOWED_HOSTS` (comma separated, `*` for any). It's still plain HTTP, so I'd only do this on a network you trust, and I'd put a spend limit on your OpenRouter key too.

```bash
export REALITYDIFF_TOKEN="$(openssl rand -hex 32)"
REALITYDIFF_ALLOWED_HOSTS=mybox.local uv run realitydiff serve --host 0.0.0.0
```

### Compare spend limits

I put a few brakes on compare so one bad afternoon can't drain a key:

- Every chat call asks for at most 1024 output tokens. Change it with `REALITYDIFF_MAX_TOKENS` (I clamp it to 16 through 8192).
- At most 3 model calls run at the same time across all compare requests. Extra ones wait their turn.
- At most 30 model calls per minute in total (a 6 model compare counts as 6). Past that, the API answers 429 with a `Retry-After` header. Change it with `REALITYDIFF_COMPARE_PER_MINUTE` (1 through 600).
- If you set `REALITYDIFF_COMPARE_MODELS`, only those models can run. It's comma separated: `openrouter:openai/gpt-6-luna` pins a provider, a bare id like `grok-4.7` works on either one. Leave it unset and any model id goes.

```bash
export REALITYDIFF_MAX_TOKENS=1024
export REALITYDIFF_COMPARE_PER_MINUTE=30
export REALITYDIFF_COMPARE_MODELS="openrouter:openai/gpt-6-luna,grok-4.7"
```

These can also go in `~/.config/realitydiff/env`. All of this lives in the app, so it only helps while the app is the thing spending. I'd also set a credit limit on the OpenRouter key itself (openrouter.ai, Keys page, edit the key) so the cap holds even if something else gets the key.

```bash
uv run realitydiff open "Apple is going to replace Siri with an LLM."
uv run realitydiff open --model grok-4.7 "..."
uv run realitydiff watch <claim_id>
uv run realitydiff log <claim_id>
uv run realitydiff diff <claim_id> <sha_a> <sha_b>
uv run realitydiff compare "Will Apple replace Siri this year?" \
  -m xai:grok-4.7 -m openrouter:openai/gpt-6-luna
```

```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) · OpenRouter chat completions (optional, compare only) · MIT

## License

[MIT](LICENSE)
