deploy to hugging face

.dockerignore

@@ -0,0 +1,29 @@
+# Keep the Docker build context small and reproducible.
+.git
+.gitignore
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.template
+
+# local caches / model downloads (rebuilt in the image)
+.cache/
+output/
+*.log
+
+# reference clone used only for local research
+/tmp/cognee-ref/
+
+# docs & dev-only artifacts not needed at runtime
+IMPLEMENTATION_PLAN.md
+bridge.py
+demo.gif
+*.ipynb

.env.template

@@ -0,0 +1,84 @@
+# ============================================================================
+# FALSIFY — environment configuration
+# Copy this file to `.env` and fill in your key:   cp .env.template .env
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# LLM provider (OpenAI-compatible)
+# ----------------------------------------------------------------------------
+# FALSIFY works with OpenAI or ANY OpenAI-compatible endpoint (OpenRouter,
+# vLLM, LM Studio, Azure, local proxies, ...). Pick ONE of the blocks below.
+
+# --- Default: OpenAI ---------------------------------------------------------
+LLM_PROVIDER="openai"
+LLM_API_KEY="sk-your-openai-key-here"
+LLM_MODEL="openai/gpt-5-mini"
+# LLM_ENDPOINT is not needed for the default OpenAI provider.
+
+# --- Alternative: custom / OpenAI-compatible endpoint (e.g. OpenRouter) ------
+# Uncomment this block and comment out the OpenAI block above to use it.
+# LLM_PROVIDER="custom"
+# LLM_API_KEY="your_api_key"
+# LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
+# LLM_ENDPOINT="https://openrouter.ai/api/v1"
+
+# --- Alternative: Alibaba DashScope (Qwen), OpenAI-compatible ----------------
+# Note the "openai/" prefix on the model — litellm needs it to route a raw
+# OpenAI-compatible endpoint. Verified working with FALSIFY.
+# LLM_PROVIDER="custom"
+# LLM_API_KEY="sk-..."
+# LLM_MODEL="openai/qwen-plus"
+# LLM_ENDPOINT="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+
+# ----------------------------------------------------------------------------
+# Embeddings — fastembed (local, CPU-only, zero-cost) is FALSIFY's default
+# ----------------------------------------------------------------------------
+# FALSIFY sets these automatically at import so the pipeline (and
+# `python main.py --demo`) runs with NO external embedding key. This keeps your
+# LLM key (above) LLM-only and avoids the classic "LLM provider != embedding
+# provider" mismatch. Any explicit value here overrides the default.
+EMBEDDING_PROVIDER="fastembed"
+EMBEDDING_MODEL="BAAI/bge-small-en-v1.5"
+EMBEDDING_DIMENSIONS="384"
+EMBEDDING_MAX_TOKENS="512"
+# To use OpenAI embeddings instead, set:
+# EMBEDDING_PROVIDER="openai"
+# EMBEDDING_MODEL="openai/text-embedding-3-large"
+# EMBEDDING_API_KEY="sk-your-openai-key-here"
+
+# ----------------------------------------------------------------------------
+# Session memory / caching
+# ----------------------------------------------------------------------------
+# Cross-session belief persistence uses Cognee's session cache. Default backend
+# is local SQLite — zero external services, survives process restarts.
+# Backends: sqlite (default), postgres, redis, fs, tapes
+CACHING="true"
+CACHE_BACKEND="sqlite"
+# Optional explicit SQLAlchemy URL (only for sqlite/postgres backends):
+# CACHE_DB_URL="postgresql+asyncpg://cognee:cognee@localhost:5432/cognee_db"
+
+# ----------------------------------------------------------------------------
+# Databases (self-hosted defaults — no setup required)
+# ----------------------------------------------------------------------------
+# FALSIFY ships with fully local, zero-dependency stores:
+#   Vector   -> LanceDB
+#   Graph    -> Ladybug
+#   Relational -> SQLite
+# These are the defaults; the lines below are shown only for clarity.
+# VECTOR_DB_PROVIDER="lancedb"
+# GRAPH_DATABASE_PROVIDER="ladybug"
+# DB_PROVIDER="sqlite"
+
+# ----------------------------------------------------------------------------
+# FALSIFY demo behavior
+# ----------------------------------------------------------------------------
+# DEMO_MODE=1 (or `python main.py --demo`) pins the refuted evidence id so the
+# refutation cascade + surgical forget run on real graph/vector APIs even if the
+# LLM contradiction judge stalls or the key is rate-limited. Presentation safety net.
+DEMO_MODE="0"
+
+# ----------------------------------------------------------------------------
+# Optional: quieter logs / telemetry off
+# ----------------------------------------------------------------------------
+# LITELLM_LOG="ERROR"
+# TELEMETRY_DISABLED="1"

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+output/
+*.lance
+.cognee_system/
+.data_storage/

DEPLOYMENT.md

@@ -0,0 +1,133 @@
+# FALSIFY — Deployment Guide
+
+Two ways to put FALSIFY online. **Do Plan A first** — it's one container, one URL,
+and the realtime stream "just works." Fall back to Plan B only if the HF build
+won't cooperate.
+
+| | **Plan A — Hugging Face Spaces** | **Plan B — Vercel + Render** |
+|---|---|---|
+| Pieces | 1 container (frontend + API + SSE) | Vercel (frontend) + Render (API + SSE) |
+| CORS | none (same origin) | required (handled in `server.py`) |
+| Realtime | SSE on port 7860, native | SSE lives on Render; Vercel serves static only |
+| Cost | free | free (Render cold-starts) / $7 always-on |
+| Best when | **default — start here** | HF Docker build fails twice |
+
+The **same Docker image** runs on both (it binds `$PORT`, default 7860). Demo mode is
+**keyless** — a judge can open the URL and hit ▶ Run investigation with no setup.
+
+---
+
+## Plan A — Hugging Face Spaces (PRIMARY)
+
+### What's already in the repo
+- `Dockerfile` — single-stage, non-root uid 1000, pre-warms `fastembed`, binds `$PORT`.
+- `README.md` frontmatter — `sdk: docker`, `app_port: 7860` (HF reads this).
+- `.dockerignore` — trims the build context.
+- `static/` — the frontend, served by `server.py`.
+
+### Steps
+1. **Create the Space.** huggingface.co → *New* → *Space*. Name it `falsify`,
+   **SDK: Docker**, **Blank** template, visibility **Public**.
+2. **Push the repo to the Space remote:**
+   ```bash
+   git remote add space https://huggingface.co/spaces/<your-username>/falsify
+   git push space main
+   ```
+   *(If your local branch is `main` and the Space expects `main`, this is enough.
+   HF authenticates with a write token — when prompted for a password, paste a
+   token from huggingface.co/settings/tokens.)*
+3. **Watch the build.** Open the Space's **Container** / **Logs** tab. First build is
+   slow (Cognee pulls Kuzu/LanceDB/litellm — several minutes). Wait for **Running**.
+4. **Open the Space URL.** The graph should load pre-seeded. Hit **▶ Run
+   investigation** and watch the cascade. That URL is your submission link.
+
+### Secrets (OPTIONAL — demo needs none)
+Space → **Settings** → **Variables and secrets**. Add only if you want Live mode /
+upload / the recall completion:
+- `LLM_API_KEY` = your key · `LLM_MODEL` = `gpt-4o-mini`
+- non-OpenAI endpoint: `LLM_PROVIDER=custom`, `LLM_ENDPOINT=https://…/v1`
+- Cognee Cloud toggle: `COGNEE_CLOUD_URL`, `COGNEE_CLOUD_API_KEY`
+
+Absent a key, the app **stays in keyless demo mode** — nothing errors.
+
+### Alternative push (CLI)
+```bash
+pip install -U huggingface_hub
+huggingface-cli login                 # paste a write token
+huggingface-cli upload <user>/falsify . --repo-type space
+```
+
+---
+
+## Plan B — Vercel (frontend) + Render (backend)
+
+Use this if HF won't build. **Deploy Render first**, then Vercel, then wire CORS.
+
+### Why the split looks the way it does
+- **Vercel can't host the SSE stream** — its serverless functions can't hold a
+  long-lived connection. So Vercel serves **only** the static `static/` files.
+- **Render runs the whole backend** (API + SSE) from the same Dockerfile. The
+  browser opens `EventSource` **directly against Render**, not Vercel.
+
+### Step 1 — Backend on Render
+1. render.com → **New +** → **Web Service** → connect the GitHub repo.
+2. **Runtime: Docker** (it finds `./Dockerfile`). *(Or use **Blueprint** and pick
+   `render.yaml`.)*
+3. **Instance type:** Free to try; **Starter ($7/mo)** to avoid the 15-min-idle
+   cold start during judging. (Free spins down; first hit after idle takes 30–60s.)
+4. **Env vars** (Settings → Environment):
+   - `FRONTEND_ORIGIN` = your Vercel URL (fill in after Step 2, then redeploy)
+   - optional: `LLM_API_KEY`, `LLM_MODEL`, `COGNEE_CLOUD_URL`, `COGNEE_CLOUD_API_KEY`
+5. Deploy → note the URL, e.g. `https://falsify-backend.onrender.com`.
+   Verify: `curl https://falsify-backend.onrender.com/api/health` → `{"ok": true, …}`.
+
+### Step 2 — Frontend on Vercel
+1. **Point the frontend at Render.** Edit `static/config.js`:
+   ```js
+   window.__API_BASE__ = "https://falsify-backend.onrender.com";  // no trailing slash
+   ```
+   Commit + push.
+2. vercel.com → **Add New** → **Project** → import the repo.
+3. Framework preset: **Other**. `vercel.json` already sets output dir = `static`
+   and no build. Deploy.
+4. Note the URL, e.g. `https://falsify.vercel.app`.
+
+### Step 3 — Close the CORS loop
+1. Back in Render → set `FRONTEND_ORIGIN` = `https://falsify.vercel.app` → **redeploy**.
+2. Open the Vercel URL. If it was a free Render instance, hit it once to **warm it**
+   (~30–60s), then reload. ▶ Run investigation should stream live.
+
+---
+
+## Pre-demo checklist (do this right before judging)
+- [ ] Open the live URL in a fresh incognito window (no cache).
+- [ ] Graph loads pre-seeded; connection dot (top bar) shows **live**.
+- [ ] **▶ Run investigation** → E_qa strikes red, K dissolves, B rises green.
+- [ ] Scoreboard shows **FALSIFY ✅ Jan 2021** vs **RAG ⚠ still cites the refuted March report**.
+- [ ] **Diamond** → K2 survives phase 1, collapses phase 2.
+- [ ] **Verify persistence** → reads truth-state from the on-disk graph store and confirms refuted/superseded nodes are there.
+- [ ] (Plan B) Render warmed within the last 10 min so there's no cold-start pause.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause → Fix |
+|---|---|
+| HF build fails on a heavy wheel | Transient hub/network. Re-run the build (Space → *Factory rebuild*). The deps layer caches after the first success. |
+| First request hangs ~20s | `fastembed` model download. The Dockerfile pre-warms it; if skipped, the first embed pays it once. |
+| SSE events arrive in a clump, not live | A proxy is buffering. We already send `X-Accel-Buffering: no` + `Cache-Control: no-cache`; confirm no extra CDN sits in front. |
+| Graph loads but ▶ does nothing | Open devtools → Network. If `/api/*` calls 404/blocked, check `window.__API_BASE__` (empty on HF, Render URL on Vercel). |
+| Vercel UI can't reach backend (CORS error) | `FRONTEND_ORIGIN` on Render ≠ the Vercel origin. Set it exactly (scheme + host, no path) and redeploy. |
+| Render cold start every time | Free tier idle spin-down. Warm it before judging or use Starter. |
+| Upload says "Set LLM_API_KEY" | `cognify` needs an LLM key. Add it as a secret/env var, or just use the keyless demo/diamond. |
+| Permission error writing cache on HF | Container runs as uid 1000; `HF_HOME` is under `$HOME`. Don't write outside `/home/user/app`. |
+
+---
+
+## Local sanity check (optional, before deploying)
+```bash
+pip install -r requirements.txt
+uvicorn server:app --port 8000
+# open http://localhost:8000  → same UI the deploy serves
+```

Dockerfile

@@ -0,0 +1,46 @@
+# ─────────────────────────────────────────────────────────────────────────────
+# FALSIFY — live belief-revision copilot
+#
+# Single-stage image. The frontend is dependency-free static files (no React
+# build), so there is NO Node stage — one fewer thing to break in CI. FastAPI
+# serves the API, the SSE stream, AND the static UI from one port.
+#
+# Portable across hosts: binds to $PORT (Render injects it) and falls back to
+# 7860 (Hugging Face Spaces' default). Same image runs on both.
+# ─────────────────────────────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# Hugging Face Spaces run containers as uid 1000; create that user so writes
+# to cache/model dirs don't hit permission errors.
+RUN useradd -m -u 1000 user
+WORKDIR /home/user/app
+
+# System deps some wheels (lancedb/kuzu/onnxruntime) expect at runtime.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libgomp1 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Dependencies first for layer caching (Cognee is heavy — cache it across rebuilds).
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt && \
+    chown -R user:user /usr/local/lib/python3.11/site-packages/cognee
+
+# Pre-warm the local fastembed model so the FIRST request isn't a model download.
+# Best-effort: never fail the build if the hub is briefly unreachable.
+RUN python -c "from fastembed import TextEmbedding; TextEmbedding()" || true
+
+# App code (includes ./static — the built-in frontend).
+COPY --chown=user . .
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/app/.cache \
+    PORT=7860 \
+    PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+
+# Shell form so $PORT expands (HF=7860, Render=its injected value).
+CMD uvicorn server:app --host 0.0.0.0 --port ${PORT:-7860}

IMPLEMENTATION_PLAN.md

@@ -0,0 +1,764 @@
+# FALSIFY — Tier 2 Implementation & Deployment Plan
+
+> Written incrementally, one section at a time.
+> **Section 1 of ~7 below.** Confirm to continue to Section 2.
+
+---
+
+## Section 1 — Strategy & Scope (win-ROI under a 24h deadline)
+
+**Deadline reality:** Today is July 4; the hackathon closes July 5. We have ~24 hours.
+Every decision below is ranked by *what wins*, not by engineering completeness.
+
+**Two prize tracks — we go for both:**
+- **Best Use of Open Source** (MacBook) — the deployed, self-hosted FALSIFY demo.
+- **Best Use of Cognee Cloud** (iPhone 17) — the same pipeline, toggled to run against a
+  Cognee Cloud tenant via `cognee.serve()`. One flag makes us eligible for a *second* prize.
+
+### Final scope (in priority order)
+
+| # | Feature | Why it wins | Status vs. old plan |
+|---|---------|-------------|---------------------|
+| **F** | **Live animated web UI** (chat + living graph + scoreboard) | The judges' primary visual; the whole story in one screen | **Centerpiece — keep, elevate** |
+| **G** | **Cognee Cloud toggle** (`cognee.serve()`) | Unlocks the *second* prize track for ~1h work | **NEW — was missing entirely** |
+| **S** | **Scoreboard as a permanent panel** (FALSIFY vs plain RAG) | Surfaces the core thesis instead of burying it in a chat reply | **NEW — was hidden** |
+| **L** | **Revision log / "why" narration** | Makes the animation *legible* — judge understands the reasoning | **NEW — explainability** |
+| **U** | **Document upload → `add` + `cognify`** | Turns a fixed demo into a real product; showcases core Cognee | **NEW — from your original vision** |
+| **P** | **Persistence proof, integrated** (reopen memory → still revised) | Same "survives restart" punch, but *visible* in the UI | **Replaces old Feature D subprocess** |
+| **E** | **Diamond scenario** (partial survival → full collapse) | Depth for technical judges | **Demoted: a UI scenario button, not a CLI mode** |
+
+### What we cut / change and why
+- **CUT the `verify_persistence.py` subprocess (old Feature D).** A subprocess printing JSON
+  to a terminal is invisible to judges. We get the same proof *visibly* inside the UI: state
+  lives on disk (Kuzu + LanceDB), so a "Reopen memory" action re-reads from cold storage and
+  the graph is still revised.
+- **DEMOTE the diamond (old Feature E) from a separate `--diamond` CLI mode to one scenario
+  button in the web UI.** The engine work is cheap (zero algorithm change) and stays; only the
+  surfacing moves into F.
+- **SWITCH the real-time transport from WebSocket → Server-Sent Events (SSE).** Verified today:
+  our event stream is one-directional (server→browser), and WebSockets are fragile on exactly
+  the platforms in play — Vercel serverless can't host them, and Render supports them only on
+  paid plans (its free tier's 15-min spin-down severs them regardless). SSE is plain streaming
+  HTTP: it works on the HF Spaces single-port monolith and survives the Vercel+Render split.
+
+### Deployment stance
+- **Primary: Hugging Face Spaces (Docker monolith)** — one container, FastAPI serves the built
+  frontend + API + SSE on port 7860. Keyless demo mode runs out of the box. **Try this first.**
+- **Fallback: Vercel (frontend) + Render (backend)** — documented with its caveats (Render free
+  tier cold start; warm before judging). Detailed in a later section.
+
+### The keyless-demo guarantee
+In **demo mode** the contradiction is pinned, `fastembed` does embeddings locally, and the
+scoreboard falls back to graph traversal — **no API key needed**, so the deployed demo works
+for any judge instantly. Live mode, upload+cognify, and `recall` completion need a key (set as
+an HF secret / Render env var) and degrade gracefully when absent.
+
+---
+
+*End of Section 1.*
+
+---
+
+## Section 2 — Architecture
+
+> **Section 2 of ~7.** Confirm to continue to Section 3.
+
+### 2.1 Shape at a glance
+
+```
+┌─────────────────────────── Browser (built React app) ───────────────────────────┐
+│   ChatPanel        │        GraphCanvas (living graph)      │   Scoreboard        │
+│   + upload         │   force-directed, animated state       │   FALSIFY vs RAG    │
+│   + quick actions  │   transitions (flash/cascade/dissolve) │   RevisionLog feed  │
+└──────┬─────────────┴───────────────┬────────────────────────┴─────────┬──────────┘
+       │ POST /api/chat, /upload,     │ GET /api/graph (snapshot)        │ EventSource
+       │ /scenario, /reset, /mode     │ GET /api/scoreboard              │ GET /api/events (SSE)
+       ▼                              ▼                                  ▼
+┌───────────────────────────────── server.py (FastAPI) ───────────────────────────┐
+│  REST endpoints ──► call falsify.falsify (build_graph / revise / scoreboard)     │
+│  SSE broadcaster ──► fans events to all subscribed browsers                      │
+└───────────────────────────────┬─────────────────────────────────────────────────┘
+                                 │  falsify.events.emit(...)  (no-op in CLI mode)
+                                 ▼
+┌──────────────── falsify/graph_ops.py (the single chokepoint) ────────────────────┐
+│  set_state()  ──► emit_state_change(id, state, epoch)                             │
+│  delete_from_both_stores() ──► emit_forgotten(id)                                 │
+│                    (Cognee graph engine: Kuzu/Ladybug + LanceDB, file-backed)     │
+└──────────────────────────────────────────────────────────────────────────────────┘
+```
+
+The insight from the research pass still holds: **every** belief mutation flows through
+exactly two functions in `graph_ops.py`, so ~4 lines of hooks capture the whole pipeline
+without touching any task code.
+
+### 2.2 Backend (FastAPI) — endpoint contract
+
+| Method + path | Purpose | Calls |
+|---|---|---|
+| `GET /` | Serve the built frontend (`static/index.html`) | — |
+| `GET /api/graph` | Current nodes+edges+truth-state+colors (snapshot) | `graph_ops.load_graph` + `get_truth` |
+| `GET /api/events` | **SSE stream** of live mutation events | subscribes to event bus |
+| `POST /api/chat` | Classify input → fact (`revise`) or question (`scoreboard`); events fire mid-pipeline | `revise` / `scoreboard` |
+| `POST /api/upload` | Ingest a dropped doc → new nodes appear in the graph | `cognee.add` + `cognee.cognify` |
+| `POST /api/scenario` | Build `simple` or `diamond` graph | `build_graph` / `build_diamond_graph` |
+| `POST /api/reset` | Rebuild the seed investigation | `build_graph` |
+| `GET /api/scoreboard?q=` | FALSIFY answer vs stale-RAG answer | `scoreboard` |
+| `GET /api/verify` | **Persistence proof**: re-read truth-state from the on-disk graph store (truth-alignment lives in Kuzu, not process memory) | `get_belief_summary` |
+| `POST /api/mode` | Toggle `opensource` ↔ `cloud` (`cognee.serve(url, key)`) | backend switch (Feature G) |
+
+### 2.3 The SSE event bus (`falsify/events.py`, new — leaf module)
+
+- A module-level **set of subscriber `asyncio.Queue`s**. Each open `GET /api/events`
+  connection registers its own queue; `emit()` fans the event to all of them.
+- `emit()` is a **no-op when there are no subscribers** — so `python main.py --demo` (CLI) is
+  completely unaffected; the 4 new lines in `graph_ops.py` cost nothing.
+- Event shapes (JSON): `node_state_changed {id, state, epoch}`, `node_forgotten {id}`,
+  `graph_reset {}`, `pipeline_step {step, detail}`.
+- SSE framing: `StreamingResponse(media_type="text/event-stream")`, each event as
+  `data: {json}\n\n`, a `: keepalive\n\n` comment every ~15 s, and header
+  `X-Accel-Buffering: no` so proxies (HF/Render) don't buffer the stream.
+- **Leaf-module rule:** `events.py` imports nothing from `falsify` (avoids the circular
+  import `graph_ops → events`).
+
+### 2.4 Frontend (Vite + React + TypeScript + Tailwind)
+
+- **Graph:** `react-force-graph-2d` (the same lib Cognee's own frontend uses — we already read
+  its `nodeCanvasObject` pattern). Custom canvas rendering for glow, dashed-refuted borders,
+  flash rings, shrink-to-dissolve.
+- **Panels/motion:** `framer-motion` for the revision-log slide-ins and scoreboard transitions.
+- **Live updates:** a `useEventStream` hook wraps the browser-native `EventSource` against
+  `/api/events`, with auto-reconnect. On each event it patches the in-memory graph data and
+  triggers the matching animation.
+- **Env-aware API base:** `VITE_API_BASE` (empty for the HF monolith / same-origin; the Render
+  URL for the Vercel split). SSE and fetch both resolve through it.
+- **Built to static** (`vite build → dist/`) — one artifact that either the FastAPI monolith
+  serves (HF) or Vercel serves (split). Same code, both deploy targets.
+
+### 2.5 Keyless-demo wiring
+- **Demo mode** (default for the deployed Space): contradiction pinned, `fastembed` local
+  embeddings, scoreboard graph-traversal fallback → **zero API calls, zero key**.
+- **Live mode / upload / recall-completion:** need `LLM_API_KEY`; read from env (HF secret or
+  Render var). When absent, the UI keeps working in demo mode and shows a subtle "add a key for
+  Live mode" hint instead of erroring.
+
+### 2.6 Directory layout (target)
+
+```
+cognee-hackathon-project/
+├─�� server.py                 # NEW — FastAPI app (endpoints + SSE broadcaster)
+├── falsify/
+│   ├── events.py             # NEW — SSE event bus (leaf module)
+│   ├── graph_ops.py          # +4 lines of emit hooks; + flush_and_release()
+│   ├── seed.py               # + NEW_FACT_2, build_diamond_investigation()  (Feature E)
+│   └── falsify.py            # + build_diamond_graph(); + cloud backend switch (Feature G)
+├── frontend/                 # NEW — Vite React app
+│   ├── src/{App,components,hooks,lib}...
+│   └── dist/                 # build output → served as static
+├── Dockerfile                # NEW — multi-stage (build frontend → serve with backend)
+├── requirements.txt          # + fastapi, uvicorn[standard], sse (stdlib), python-multipart
+└── IMPLEMENTATION_PLAN.md
+```
+
+---
+
+*End of Section 2.*
+
+---
+
+## Section 3 — Backend implementation
+
+> **Section 3 of ~7.** Confirm to continue to Section 4.
+
+All code below matches the **verified** signatures in `graph_ops.py`:
+`set_state(node_id, state, epoch)` and `delete_from_both_stores(node_ids, collections)`.
+
+### 3.1 `falsify/events.py` (NEW — leaf module, imports nothing from falsify)
+
+```python
+"""FALSIFY real-time event bus for the live web UI.
+
+A set of per-connection asyncio.Queues. graph_ops hooks call emit() after each
+state mutation; each open SSE connection drains its own queue. emit() is a no-op
+when there are no subscribers, so the CLI (`python main.py`) is unaffected.
+"""
+from __future__ import annotations
+import asyncio
+from typing import Any, Dict, Set
+
+_subscribers: Set[asyncio.Queue] = set()
+
+def subscribe() -> asyncio.Queue:
+    q: asyncio.Queue = asyncio.Queue(maxsize=1000)
+    _subscribers.add(q)
+    return q
+
+def unsubscribe(q: asyncio.Queue) -> None:
+    _subscribers.discard(q)
+
+async def emit(event: Dict[str, Any]) -> None:
+    for q in list(_subscribers):
+        try:
+            q.put_nowait(event)
+        except asyncio.QueueFull:
+            pass  # slow client: drop rather than block the pipeline
+
+async def emit_state_change(node_id: str, state: str, epoch: int) -> None:
+    await emit({"type": "node_state_changed", "id": str(node_id),
+                "state": state, "epoch": int(epoch)})
+
+async def emit_forgotten(node_id: str) -> None:
+    await emit({"type": "node_forgotten", "id": str(node_id)})
+
+async def emit_graph_reset() -> None:
+    await emit({"type": "graph_reset"})
+
+async def emit_step(step: str, detail: str = "") -> None:
+    await emit({"type": "pipeline_step", "step": step, "detail": detail})
+```
+
+### 3.2 `falsify/graph_ops.py` — the 4-line hook + `flush_and_release()`
+
+Add near the top (after the existing imports):
+```python
+from falsify import events
+```
+In `set_state()`, immediately after the successful `set_node_truth_state` (line ~106):
+```python
+        await events.emit_state_change(str(node_id), value, int(epoch))
+```
+In `delete_from_both_stores()`, after `await ge.delete_nodes(ids)` succeeds (line ~139):
+```python
+        for nid in ids:
+            await events.emit_forgotten(nid)
+```
+Append the persistence helper (used by `GET /api/verify`):
+```python
+async def flush_and_release() -> None:
+    """Checkpoint the graph WAL and evict the engine so the next read is a
+    genuine cold read from disk (basis of the visible persistence proof)."""
+    ge = await get_graph_engine()
+    try:
+        if hasattr(ge, "checkpoint"):
+            await ge.checkpoint()
+    except Exception as exc:
+        logger.debug("checkpoint best-effort skip: %s", exc)
+    try:
+        from cognee.infrastructure.databases.graph.get_graph_engine import evict_graph_engine
+        from cognee.infrastructure.databases.graph.config import get_graph_config
+        evict_graph_engine(**get_graph_config().to_hashable_dict())
+    except Exception as exc:
+        logger.debug("evict best-effort skip: %s", exc)
+```
+
+### 3.3 Feature E — diamond scenario (engine work stays, surfaced via UI)
+
+`falsify/seed.py` — add after `NEW_FACT`:
+```python
+NEW_FACT_2 = (
+    "A forensic analysis of email headers shows the January 2021 supplier email "
+    "was fabricated: the sender domain was not registered until April 2021, and "
+    "the DKIM signature is invalid."
+)
+REFUTED_EVIDENCE_KEY_2 = "E_email"
+```
+Add `build_diamond_investigation()` — identical to `build_investigation()` plus a Conclusion
+`K2` that critically depends on **both** `E_qa` and `E_email`:
+```python
+    conclusion_k2 = Conclusion(
+        statement="Multiple independent sources confirm Company X had pre-recall "
+                  "knowledge of the defect.",
+        confidence=0.85,
+        depends_on_ids=[str(ev_qa.id), str(ev_email.id)],
+        source_id="analyst",
+    )
+    # ... add K2 to the nodes list, persist, then two critical legs:
+    await graph_ops.add_edge(str(conclusion_k2.id), str(ev_qa.id),   DEPENDS_ON, {"critical": True})
+    await graph_ops.add_edge(str(conclusion_k2.id), str(ev_email.id), DEPENDS_ON, {"critical": True})
+    # ... include "K2" in seeded.ids / seeded.labels
+```
+`falsify/falsify.py` — add the orchestrator:
+```python
+async def build_diamond_graph() -> SeededGraph:
+    import cognee
+    from cognee.low_level import setup
+    from falsify.seed import build_diamond_investigation
+    await cognee.forget(everything=True)
+    await setup()
+    return await build_diamond_investigation()
+```
+Two-phase story (driven by the UI scenario button, both targets pinned so it's deterministic):
+Phase 1 refutes `E_qa` → **K dies, K2 survives** (E_email still grounds it). Phase 2 refutes
+`E_email` → **K2 collapses** (both legs gone). No algorithm change — the grounded least-fixpoint
+already does this; we're just showing it.
+
+### 3.4 Feature G — Cognee Cloud toggle (the second prize track)
+
+`falsify/falsify.py` — a backend switch used by `--cloud` and `POST /api/mode`:
+```python
+async def use_backend(mode: str, url: str | None = None, api_key: str | None = None) -> None:
+    """Route Cognee ops to the cloud tenant (mode='cloud') or self-hosted (default)."""
+    import cognee
+    if mode == "cloud" and url and api_key:
+        await cognee.serve(url=url, api_key=api_key)   # all ops now hit Cognee Cloud
+        logger.info("FALSIFY backend -> Cognee Cloud (%s)", url)
+    else:
+        logger.info("FALSIFY backend -> self-hosted (open source)")
+```
+The **same** `build_graph` / `revise` / `scoreboard` pipeline then runs against whichever
+backend is active — so one toggle makes us demonstrable on both tracks. (Caveat: cloud mode
+needs a real tenant URL + key; the primary demo stays open-source and keyless.)
+
+### 3.5 `server.py` (NEW) — FastAPI app, skeleton of the moving parts
+
+```python
+import asyncio, json
+from fastapi import FastAPI, UploadFile, File
+from fastapi.responses import StreamingResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+import falsify                       # sets Cognee env defaults on import
+from falsify import events, graph_ops
+from falsify.falsify import build_graph, build_diamond_graph, revise, scoreboard, use_backend
+from falsify.seed import NEW_FACT, NEW_FACT_2, QUESTION_TEXT
+from falsify.utils import get_belief_summary
+
+app = FastAPI(title="FALSIFY Live")
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+_seeded = None                       # server-held SeededGraph
+_lock = asyncio.Lock()               # serialize revise() (single-user demo safety)
+
+class Chat(BaseModel):
+    message: str
+    demo: bool = True
+
+@app.get("/api/events")
+async def sse():
+    q = events.subscribe()
+    async def gen():
+        try:
+            while True:
+                try:
+                    ev = await asyncio.wait_for(q.get(), timeout=15)
+                    yield f"data: {json.dumps(ev)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ": keepalive\n\n"
+        finally:
+            events.unsubscribe(q)
+    return StreamingResponse(gen(), media_type="text/event-stream",
+                             headers={"X-Accel-Buffering": "no", "Cache-Control": "no-cache"})
+
+@app.get("/api/graph")
+async def api_graph():
+    return await _graph_json()       # load_graph + get_truth → {nodes, edges} with colors
+
+@app.post("/api/chat")
+async def api_chat(c: Chat):
+    async with _lock:
+        if c.message.strip().endswith("?"):
+            board = await scoreboard(c.message, _seeded)
+            return {"type": "answer", "data": board.__dict__}
+        pinned = _seeded.refuted_target_id if (c.demo and _seeded) else None
+        report = await revise(c.message, pinned_target_id=pinned)
+        return {"type": "revision", "data": _report_json(report)}
+
+@app.post("/api/scenario")
+async def api_scenario(kind: str = "simple"):
+    global _seeded
+    _seeded = await (build_diamond_graph() if kind == "diamond" else build_graph())
+    await events.emit_graph_reset()
+    return await _graph_json()
+
+@app.post("/api/upload")
+async def api_upload(file: UploadFile = File(...)):
+    import cognee
+    text = (await file.read()).decode("utf-8", "ignore")
+    await cognee.add(text); await cognee.cognify()
+    await events.emit_graph_reset()
+    return await _graph_json()
+
+@app.get("/api/verify")
+async def api_verify():
+    await graph_ops.flush_and_release()          # cold-read from disk
+    return {"cold_read": True, "summary": await get_belief_summary()}
+
+# GET /api/scoreboard, POST /api/reset, POST /api/mode … analogous
+# GET / and /assets → serve frontend/dist (mounted last so /api/* wins)
+app.mount("/", StaticFiles(directory="static", html=True), name="static")
+
+@app.on_event("startup")
+async def _startup():
+    global _seeded
+    _seeded = await build_graph()
+```
+
+*(Helpers `_graph_json()` and `_report_json()` reuse the color map from
+`utils._STATE_STYLE` and `_infer_type` — no new color logic.)*
+
+### 3.6 `requirements.txt` additions
+```
+# — web UI (Feature F) —
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+python-multipart>=0.0.6      # multipart form parsing for /api/upload
+```
+*(SSE needs no extra package — it's plain `StreamingResponse`. No `websockets` dependency.)*
+
+---
+
+*End of Section 3.*
+
+---
+
+## Section 4 — The "brilliant" frontend
+
+> **Section 4 of ~7.** Confirm to continue to Section 5.
+
+The UI has to do one job in the first 10 seconds a judge looks at it: **make "revised, not
+forgotten" viscerally obvious.** Everything below serves that. A pretty graph is table stakes;
+the win is *legibility of reasoning* — the judge should see a belief die and understand *why*.
+
+### 4.1 Layout — three zones, one screen
+
+```
+┌────────────────────────────────────────────────────────────────────────────────┐
+│  ⬦ FALSIFY   belief-revision copilot          [Open source ▸ Cloud]  [demo ●]    │  top bar
+├───────────────┬──────────────────────────────────────────┬───────────────────────┤
+│  CHAT         │            LIVING GRAPH                    │   SCOREBOARD          │
+│  (380px)      │            (fluid, center stage)           │   (360px)             │
+│               │                                            │                       │
+│  history      │     ●─────●        force-directed          │  FALSIFY  ✅ Jan 2021 │
+│  bubbles      │     │     │        nodes colored by         │  (via alive evidence) │
+│               │    ●──────●        truth-state              │                       │
+│  ┌─────────┐  │        cascade animates on revise          │  plain RAG ⚠ Mar 2021 │
+│  │ upload  │  │                                            │  (cites REFUTED node) │
+│  └─────────┘  │                                            │ ───────────────────── │
+│  [ input …  ] │   [Reset] [Run demo] [Diamond] [Verify]    │  REVISION LOG ▸       │
+│  ( send )     │                                            │  ● E_qa refuted 0.92  │
+│               │                                            │  ● K invalidated      │
+│               │                                            │  ● A superseded → B   │
+└───────────────┴──────────────────────────────────────────┴───────────────────────┘
+```
+
+On narrow screens the three zones stack (chat → graph → scoreboard) and the graph gets a fixed
+tall canvas. Judges will use a laptop, so the 3-column is the one we polish.
+
+### 4.2 Design system (dark, "forensic lab" aesthetic)
+
+- **Palette (reuses the existing `_STATE_STYLE` so CLI, HTML export, and web all match):**
+  bg `#0b1020`, panel `#111827`, hairline `#1f2937`, text `#e5e7eb`, dim `#9ca3af`.
+  Truth-state = the *semantic* colors: alive `#22c55e`, refuted `#ef4444`,
+  invalidated `#9ca3af`, superseded `#f59e0b`, forgotten `#4b5563`.
+- **Accent:** a single electric mint `#34d399` for interactive affordances (send, active tab).
+- **Type:** Inter for UI; a mono (JetBrains Mono / ui-monospace) for node ids, weights, epochs —
+  the "instrument readout" feel.
+- **Depth:** soft outer shadows + 1px inner hairlines; nodes get a faint colored glow (their
+  state color at low alpha) so the canvas looks alive, not like a diagram.
+- **Motion budget:** everything ≤ 400ms, `ease-out`; nothing loops forever (looping motion reads
+  as "loading," not "alive"). `prefers-reduced-motion` collapses animations to instant state
+  swaps.
+
+### 4.3 Component tree
+
+```
+App
+├─ TopBar            (brand, BackendToggle [Open source|Cloud], ModeBadge [demo|live])
+├─ ChatPanel
+│  ├─ MessageList    (user / system bubbles; system messages can embed a mini result card)
+│  ├─ UploadDrop     (drag-drop or click → POST /api/upload; shows "cognifying…" then diff)
+│  └─ Composer       (textarea + Send; Enter=send, Shift+Enter=newline)
+├─ GraphCanvas       (react-force-graph-2d; owns node/link rendering + animation state)
+│  └─ GraphControls  (Reset · Run demo · Diamond · Verify · Legend)
+└─ InsightColumn
+   ├─ Scoreboard     (FALSIFY vs plain-RAG, side by side, with the "stale" warning)
+   └─ RevisionLog    (reverse-chronological feed of what changed and why)
+```
+
+### 4.4 State & data flow
+
+- **`useEventStream()`** — wraps `EventSource('/api/events')`; exponential-backoff reconnect;
+  exposes the latest event + a subscribe callback. Single source of live truth.
+- **`useGraphStore()`** (small Zustand or `useReducer`) — holds `nodes`/`links` plus per-node
+  *animation fields* (`flash`, `flashColor`, `shrink`) that the canvas reads each frame.
+  - `graph_reset` → refetch `GET /api/graph`, diff against current, animate *added* nodes in.
+  - `node_state_changed` → patch color + set `flash=1.0` in the state's color.
+  - `node_forgotten` → set `shrink=1.0`; when it hits 0, drop the node + its links.
+- **Optimistic chat:** user bubble appears instantly; the graph animates from SSE (not from the
+  POST response), so the *cause* (chat) and *effect* (cascade) are visually linked in real time.
+
+### 4.5 The signature animation vocabulary (this is the memorable part)
+
+Four named motions, each mapped to a belief event. Implemented in `nodeCanvasObject` via a
+per-node timer decremented on every `requestAnimationFrame`:
+
+1. **Refute — "the strike."** Target flashes to red, a hard ring pulses outward once, and its
+   border switches to **dashed red**. Sharp and fast (250ms). This is the moment of doubt.
+2. **Cascade — "the sweep."** Invalidation doesn't happen all at once — it *travels*. Each
+   downstream node greys out with a ~120ms stagger along `depends_on` edges, and the traversed
+   edge briefly lights up. The judge literally watches consequence flow through the graph. (We
+   already have `pipeline_step` events + edge data to order this.)
+3. **Forget — "the dissolve."** An orphaned node shrinks to zero radius while fading alpha over
+   300ms, then is removed. Its edges retract with it. "Forgotten" should *feel* like deletion —
+   but note in the log that provenance was retained.
+4. **Promote — "the rise."** The newly-winning hypothesis (B) pulses green, scales up ~1.15×
+   and settles, with a soft green glow that lingers a beat longer than the others. The graph
+   ends on a calm, green, *correct* resting state — the emotional payoff.
+
+Refuted nodes keep the dashed-red border after their flash, so the end-state is self-documenting
+even after motion stops (and in screenshots / the GIF).
+
+### 4.6 Scoreboard — the thesis, made unmissable
+
+Two stacked cards, always visible (not hidden in chat):
+- **FALSIFY** ✅ — the alive-evidence answer ("Jan 2021, via supplier email"), green check,
+  a one-line "supported by: E_email (alive)".
+- **plain RAG** ⚠ — the naive vector answer ("Mar 2021, per QA report"), amber warning, and the
+  killer subtitle: **"still cites E_qa — a node FALSIFY refuted."** When `board.stale` is true,
+  the card gets a subtle red pulse the first time it renders.
+
+That contrast card is the single screenshot that should end up in the submission. Design it to
+be beautiful *standalone*.
+
+### 4.7 Revision log — "why," in plain language
+
+A framer-motion feed; each entry slides in as its SSE event arrives, newest on top:
+- `● E_qa  refuted` · `conf 0.92` · *"contradicted by forensic back-dating finding"*
+- `● K  invalidated` · *"its only critical support (E_qa) died"*
+- `● A  superseded → B promoted` · *"A's evidence collapsed; B still stands"*
+- `● K  forgotten` · *"orphaned — no live consumer (provenance kept)"*
+
+Each row links to its node (hover → highlight in graph). This is what converts "cool animation"
+into "I understand exactly what the system decided and why."
+
+### 4.8 Upload flow (turns a fixed demo into a product)
+
+Drag a `.txt`/`.md` onto the chat → optimistic "Ingesting…" bubble → `POST /api/upload`
+(`cognee.add` + `cognify`) → `graph_reset` fires → new evidence nodes animate in with the same
+"rise" motion. A judge dropping *their own* file and watching it become graph is the answer to
+"why would anyone use this."
+
+### 4.9 Empty / error / no-key states (polish that judges notice)
+- **First load:** graph pre-seeded (startup builds it), a one-line coach-mark: *"Type a
+  contradicting fact, or hit Run demo."*
+- **No LLM key:** Live toggle shows a tooltip *"demo mode — add a key for Live/Upload"*; nothing
+  errors, everything still runs pinned+local.
+- **SSE drop:** a tiny amber dot in the top bar ("reconnecting…"); auto-recovers.
+- **Cloud unreachable:** toggle snaps back to Open source with a toast, demo continues.
+
+### 4.10 Frontend dependencies
+```
+react, react-dom, typescript, vite
+tailwindcss, postcss, autoprefixer
+react-force-graph-2d            # canvas force graph (same lib family as Cognee's UI)
+framer-motion                   # log + scoreboard transitions
+zustand                         # tiny graph/animation store (or useReducer to avoid a dep)
+```
+
+---
+
+*End of Section 4.*
+
+---
+
+## Section 5 — Deployment Plan A: Hugging Face Spaces (PRIMARY)
+
+> **Section 5 of ~7.** Confirm to continue to Section 6.
+
+**Why this is the primary target:** one Docker container serves the built frontend **and** the
+API **and** the SSE stream on a single port. No cross-origin config, SSE works natively, secrets
+are one settings tab, and the keyless demo means a judge just clicks the Space and it runs. This
+is the simplest path to a live URL — **build and ship this first.**
+
+*(All specifics below verified against HF's current Docker Spaces docs, July 2026.)*
+
+### 5.1 The three facts that shape the Dockerfile
+1. **Port 7860.** HF proxies all external traffic to one port; default is 7860. Bind uvicorn to
+   `0.0.0.0:7860` and declare `app_port: 7860` in the README frontmatter.
+2. **SSE/WebSocket both ride that single port.** Because everything is same-origin behind HF's
+   proxy, our `EventSource('/api/events')` just works — no extra config. (This is the payoff of
+   choosing SSE in Section 1.)
+3. **Non-root, UID 1000.** Spaces run the container as uid 1000; create that user and set
+   `HOME`/`PATH` accordingly or writes to cache/model dirs fail.
+
+### 5.2 `README.md` frontmatter (the Space config lives here)
+The Space's `README.md` must start with this YAML block:
+```yaml
+---
+title: FALSIFY — Belief-Revision Copilot
+emoji: ⬦
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+```
+
+### 5.3 Multi-stage `Dockerfile` (build frontend → serve with backend)
+```dockerfile
+# ── Stage 1: build the React frontend ────────────────────────────────
+FROM node:20-slim AS web
+WORKDIR /web
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build                       # emits /web/dist
+
+# ── Stage 2: python backend + serve the built frontend ───────────────
+FROM python:3.11-slim
+RUN useradd -m -u 1000 user             # Spaces run as uid 1000
+WORKDIR /home/user/app
+
+# deps first (layer cache)
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# pre-warm fastembed so the FIRST request isn't a model download
+RUN python -c "from fastembed import TextEmbedding; TextEmbedding()" || true
+
+COPY --chown=user . .
+COPY --from=web --chown=user /web/dist ./static   # server.py mounts ./static
+
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/app/.cache
+EXPOSE 7860
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+### 5.4 Secrets (only for Live mode / upload — demo needs none)
+In **Space → Settings → Variables & secrets**, add as needed:
+- `LLM_API_KEY` (and `LLM_MODEL`, e.g. `gpt-4o-mini`) — enables Live judging, `recall`
+  completion, and `cognify` on upload.
+- For a non-OpenAI endpoint: `LLM_PROVIDER=custom`, `LLM_ENDPOINT=…`.
+- These arrive as env vars at runtime (`os.environ.get(...)`), which `falsify/__init__.py`
+  already reads. **Absent key ⇒ the app stays in keyless demo mode; nothing crashes.**
+
+### 5.5 Persistent storage (optional, and we don't need it)
+- Default disk is **ephemeral** — it resets on rebuild/restart. That's *fine*: the startup hook
+  seeds the graph fresh every boot, and within a session the on-disk Kuzu/LanceDB persistence is
+  what powers the `GET /api/verify` cold-read proof.
+- If we ever want the graph to survive restarts, enable **persistent storage** and point
+  `HF_HOME` (and Cognee's system dir) at `/data`. Not required for the demo — skip it.
+
+### 5.6 Ship it (two ways)
+**Option 1 — Git push to the Space remote:**
+```bash
+# after creating the Space (SDK: Docker) in the HF UI
+git remote add space https://huggingface.co/spaces/<user>/falsify
+git push space main            # HF builds the Dockerfile and deploys
+```
+**Option 2 — `huggingface_hub` CLI:** `pip install huggingface_hub`, `huggingface-cli login`,
+then `huggingface-cli upload <user>/falsify . --repo-type space`.
+
+Watch the **Container** tab for build logs; first build is slow (Cognee pulls Kuzu/LanceDB/
+litellm — several minutes). Once green, the Space URL is the live demo link for the submission.
+
+### 5.7 HF-specific risks & mitigations
+| Risk | Mitigation |
+|---|---|
+| Cognee install is heavy → long/failed build | Pin versions in `requirements.txt`; the deps layer is cached across rebuilds; accept the first slow build |
+| First embed downloads a model → slow first request | Pre-warm `fastembed` in the Dockerfile (line above) |
+| Proxy buffers SSE → events arrive in a clump | `X-Accel-Buffering: no` + `Cache-Control: no-cache` already set on the stream (Section 3.5) |
+| Write to a non-writable dir as uid 1000 | `HF_HOME` under `/home/user/app/.cache`; all app writes under `$HOME` |
+| Build OOM on large frontend deps | `npm ci` in an isolated stage; only `dist/` is copied forward |
+
+---
+
+*End of Section 5.*
+
+---
+
+## Section 6 — Deployment Plan B: Vercel + Render (FALLBACK)
+
+> **Section 6 of ~7.** Confirm to continue to Section 7.
+
+Use this **only if HF Spaces gives trouble.** It splits the app: **Vercel** serves the static
+React build, **Render** runs the FastAPI backend (API + SSE). More moving parts (two deploys,
+CORS, a cold-start caveat) — but it's a clean production shape and a solid Plan B.
+
+### 6.1 The load-bearing insight: SSE, not WebSockets, is what makes this split viable
+Verified today (July 2026):
+- **Vercel serverless cannot host long-lived connections** — WebSockets or otherwise. Functions
+  are pinned to a max duration (~300s) and future connections aren't guaranteed the same
+  instance. So the realtime stream **cannot live on Vercel.**
+- **Render supports WebSockets only on paid plans**, and its free tier spins down after 15 min
+  idle (30–60s cold start) which would sever a socket anyway.
+
+Our Section-1 choice of **SSE** sidesteps both cleanly: the stream lives on **Render** (plain
+streaming HTTP, no paid-WS requirement), and Vercel only ever serves static files + the browser
+connects `EventSource` **directly to the Render origin.** Vercel never has to hold the stream.
+
+```
+Browser ──static──►  Vercel (frontend/dist)
+   │
+   └── fetch + EventSource ──►  Render (FastAPI: /api/*, /api/events SSE)  ──► Cognee (Kuzu/LanceDB)
+```
+
+### 6.2 Backend on Render
+1. **New → Web Service**, connect the GitHub repo.
+2. **Build:** `pip install -r requirements.txt`
+3. **Start:** `uvicorn server:app --host 0.0.0.0 --port $PORT`
+   *(Render injects `$PORT`; do not hardcode 7860 here.)*
+4. **Env vars:** `LLM_API_KEY`, `LLM_MODEL`, and `FRONTEND_ORIGIN=https://<app>.vercel.app`
+   (used by CORS below). Demo mode still needs no key.
+5. **Instance:** Free works for a quick demo **but cold-starts 30–60s** after 15 min idle. For
+   judging, either (a) hit the URL to warm it right before, or (b) use **Starter ($7/mo)** to
+   keep it always-on. Recommend Starter if the budget allows — a judge won't wait 45s.
+
+`server.py` needs CORS scoped to the Vercel origin (wildcard also fine for a demo):
+```python
+import os
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[os.environ.get("FRONTEND_ORIGIN", "*")],
+    allow_methods=["*"], allow_headers=["*"],
+)
+```
+SSE already sets `X-Accel-Buffering: no` / `Cache-Control: no-cache` (Section 3.5), which also
+keeps Render's proxy from buffering the stream.
+
+### 6.3 Frontend on Vercel
+1. **Import Project** → point at the `frontend/` directory (set it as the project root).
+2. **Framework preset:** Vite. **Build:** `npm run build`. **Output:** `dist`.
+3. **Env var:** `VITE_API_BASE=https://<app>.onrender.com` — the frontend resolves *all* fetches
+   and the `EventSource` URL through this base (Section 2.4).
+4. Deploy → Vercel returns `https://<app>.vercel.app`. Put that value into Render's
+   `FRONTEND_ORIGIN` and redeploy the backend so CORS matches.
+
+`frontend/src/lib/api.ts` resolves the base so the *same* build works on HF (same-origin, empty
+base) and on Vercel (cross-origin Render base):
+```ts
+export const API = import.meta.env.VITE_API_BASE ?? "";      // "" ⇒ same-origin (HF monolith)
+export const sse  = () => new EventSource(`${API}/api/events`);
+export const api  = (p: string, o?: RequestInit) => fetch(`${API}${p}`, o);
+```
+
+### 6.4 Order of operations (avoids a CORS chicken-and-egg)
+1. Deploy **Render** first → get the `onrender.com` URL.
+2. Deploy **Vercel** with `VITE_API_BASE` = that URL → get the `vercel.app` URL.
+3. Set Render's `FRONTEND_ORIGIN` = the Vercel URL → redeploy backend.
+4. Warm the Render service, then open the Vercel URL.
+
+### 6.5 Plan A vs Plan B — pick quickly
+| | **HF Spaces (A)** | **Vercel + Render (B)** |
+|---|---|---|
+| Deploys | 1 | 2 |
+| Cross-origin / CORS | none | required |
+| Realtime (SSE) | same-port, trivial | Render origin, works (not WS-gated) |
+| Cold start | container sleep on free tier, but single service | Render free 30–60s; $7 to remove |
+| Secrets | one settings tab | Render env vars |
+| Best when | **default — do this** | HF build won't cooperate |
+
+**Decision rule:** ship A. If the HF build fails twice for reasons you can't fix fast, cut to B
+— Render backend first, Vercel frontend second, warm, done.
+
+---
+
+*End of Section 6. Reply "next" for **Section 7 — Build order, 24h timebox & demo script**
+(the hour-by-hour sequence, what to cut if time runs short, and the 2-minute submission-video
+beat sheet).*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arpit Kumar
+
+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.

README.md

@@ -0,0 +1,301 @@
+---
+title: FALSIFY — Belief-Revision Copilot
+emoji: 🧠
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: The AI that revises, not forgets — on Cognee.
+---
+
+<div align="center">
+
+# FALSIFY
+
+### the AI that revises, not forgets
+
+**Drop one contradicting fact. Watch dependent conclusions die, a losing hypothesis rise — permanently, across sessions.**
+
+[![Track: Best Use of Open Source](https://img.shields.io/badge/Track-Best_Use_of_Open_Source-blue)](#-hackathon-track--theme)
+[![Theme: Research & Knowledge Copilot](https://img.shields.io/badge/Theme-Research_&_Knowledge_Copilot-8A2BE2)](#-hackathon-track--theme)
+[![Built on Cognee](https://img.shields.io/badge/Built_on-Cognee-00C48C)](https://github.com/topoteretes/cognee)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
+
+</div>
+
+---
+
+## The Problem: AI Remembers the *Wrong* Fact
+
+Every memory layer bolted onto an LLM today is an **append-only pile of facts**. It can remember. It cannot *un-believe*.
+
+When new evidence contradicts something the AI already "knows," today's systems do one of two bad things:
+
+- **RAG / vector memory** keeps citing the stale fact forever — it has no notion that a belief can *die*.
+- **Naive "delete the memory"** throws away the fact *and* every conclusion built on top of it, with no record of *why* — a lobotomy, not a revision.
+
+This is **belief-level amnesia**. The AI doesn't just forget *where* it put the context (this hackathon's theme) — it confidently remembers a fact that has since been proven false, and every downstream conclusion inherits the lie.
+
+> A forensic audit reveals the "March QA report" was **back-dated**. A human analyst instantly revises: *"Then the March timeline is dead — the January supplier email is now our best evidence."* Today's AI memory keeps answering **"March 2021."**
+
+---
+
+## The Solution: A Living Belief Graph
+
+FALSIFY treats a research inquiry not as a chat log but as a **living belief graph** of typed, stateful nodes — `Hypothesis`, `Evidence`, `Conclusion` — wired together by dependency edges.
+
+When a new fact **contradicts** an existing piece of evidence, FALSIFY performs **belief revision** on the graph itself:
+
+1. **Refute** — the contradicted `Evidence` flips to `truth_state = REFUTED`.
+2. **Propagate forward** — the refutation cascades *along `depends_on` edges* to every `Conclusion` that critically rested on it → `INVALIDATED`.
+3. **Re-ignite** — the losing `Hypothesis` is demoted to `SUPERSEDED`; the strongest surviving rival is promoted as the new frontier.
+4. **Surgically forget** — orphaned dead-ends (no surviving consumer) are hard-deleted from **both** the graph and the vector store. Provenance nodes (the refuted fact, the superseding fact) are **kept** so the graph always explains *why* it changed.
+5. **Persist** — truth-state is written *on the node*, so the **next session's `recall()` skips the dead branches** — while a plain-RAG baseline still cites the stale fact.
+
+The result is memory that **revises instead of forgets**: it changes its mind, keeps the receipts, and never loses the thread.
+
+---
+
+## Demo
+
+<div align="center">
+
+![FALSIFY demo — a refutation cascade collapsing Hypothesis A and igniting Hypothesis B](output/falsify-demo.gif)
+
+*A **live** run (the LLM judges the contradiction): drop one back-dating fact → `E_qa` turns **red (refuted)** → Conclusion **K is forgotten** (deleted from graph + vector) → Hypothesis **A** dims to **amber (superseded)** → Hypothesis **B ignites** as the new frontier. Caption: **"AI revised, not forgot."***
+
+</div>
+
+The money shot is the **scoreboard** printed on every run:
+
+```text
+[SCOREBOARD]
+   FALSIFY recall : X knew by Jan 2021 (supplier email)   [revised]
+   Plain-RAG      : X knew by Mar 2021 (QA report)         [STALE]
+```
+
+Same underlying store. Same query. FALSIFY revised its belief; the baseline did not.
+
+---
+
+## Key Features
+
+| | Feature | What it does |
+|---|---|---|
+| 🧠 | **Belief graph, not a fact pile** | Nodes are *stateful beliefs* (`alive` / `refuted` / `superseded` / `invalidated`), not immutable rows. |
+| ⚡ | **Forward refutation propagation** | One contradiction cascades through `depends_on` edges and invalidates every dependent conclusion in ~3s. |
+| 🎯 | **Two-gate contradiction detection** | Cheap deterministic vector prefilter (`cosine < 0.35`) → skeptical LLM adjudication (`confidence ≥ 0.6`). No hallucinated refutations. |
+| ✂️ | **Surgical forget** | Orphaned dead-ends are hard-deleted from graph **and** vector; provenance is retained. Not a lobotomy — a revision. |
+| 🔁 | **Cross-session persistence** | Disbelief lives on the node. Restart the process and `recall()` still skips the dead branches. |
+| 📊 | **Live A/B scoreboard** | FALSIFY (revised) vs. plain-RAG (stale) side-by-side, every run — the differentiator made visible. |
+| 🕸️ | **Force-graph visualization** | Nodes colored by truth-state; forgotten nodes red-flash then ripple out of the sim. |
+| 🔌 | **Zero external services** | Self-hosted Cognee defaults — LanceDB (vector) + Ladybug (graph) + SQLite. OpenAI-compatible; bring any endpoint. |
+
+---
+
+## How It Works
+
+FALSIFY drives Cognee's v1.0 memory API (`remember` / `recall` / `improve` / `forget`) plus a set of **custom `memify` tasks** that operate directly on the graph engine's truth-state.
+
+```mermaid
+flowchart TD
+    subgraph S1["Session 1 — build the belief graph"]
+        Q["InvestigationQuestion<br/>Did Company X know before the recall?"]
+        HA["Hypothesis A<br/>knew via QA report, Mar 2021"]
+        HB["Hypothesis B<br/>knew via supplier email, Jan 2021"]
+        HC["Hypothesis C<br/>didn't know"]
+        Eqa["Evidence E_qa<br/>March QA report"]
+        Eem["Evidence E_email<br/>January supplier email"]
+        K["Conclusion K<br/>X knew by March 2021"]
+
+        Q --- HA & HB & HC
+        Eqa -- supports --> HA
+        Eem -- supports --> HB
+        K -- "depends_on (critical)" --> Eqa
+    end
+
+    NF["🆕 New fact (Session 2)<br/>Forensic audit: March QA report was back-dated"]
+
+    subgraph REV["Belief revision — custom memify tasks"]
+        direction TB
+        D["1. Detect contradiction<br/>vector prefilter < 0.35  →  LLM judge ≥ 0.6"]
+        R["2. E_qa → REFUTED"]
+        P["3. Forward BFS on depends_on<br/>K → INVALIDATED"]
+        G["4. A → SUPERSEDED &nbsp;•&nbsp; B ignites (promoted)"]
+        F["5. Forget orphan K<br/>delete from graph + vector<br/>keep E_qa as refuted provenance"]
+        D --> R --> P --> G --> F
+    end
+
+    NF --> D
+    Eqa -.-> D
+
+    subgraph SCORE["Scoreboard"]
+        FA["FALSIFY recall → B (Jan 2021)  ✅ revised"]
+        RA["Plain-RAG → March 2021 QA report  ❌ stale"]
+    end
+
+    F --> FA
+    F --> RA
+```
+
+**The mechanism in one paragraph:** a `Conclusion --depends_on--> Evidence` edge is the propagation rail. Refutation seeds at an `Evidence` node; a conclusion stays justified only if it has a **grounded** critical support chain that bottoms out in a still-alive node. FALSIFY computes this as a **least-fixpoint** over the dependency graph, so one formulation correctly handles chains, **diamonds** (a conclusion survives while any critical alternative is grounded), non-critical dependencies, **and cycles** (a self-supporting loop with no grounded base collapses — and the fixpoint always terminates). Hypotheses are re-scored via their `supports` edges. Truth-state (`truth_alignment` + `truth_epoch`) is written on-node via `set_node_truth_state`, so it survives a restart and `recall()` filters on it. See [`falsify/tasks/propagate_refutation.py`](falsify/tasks/propagate_refutation.py) and [REQUIREMENTS.md](REQUIREMENTS.md) for the full algorithm, edge vocabulary, and edge-case handling.
+
+---
+
+## Install & Setup
+
+### Prerequisites
+- Python **3.10 – 3.14**
+- An OpenAI **or any OpenAI-compatible** API key (OpenRouter, vLLM, LM Studio, Azure, …)
+
+### 1. Clone & create an environment
+
+```bash
+git clone https://github.com/ArpitKumar8649/cognee-hackathon-project.git
+cd cognee-hackathon-project
+
+# uv (recommended)
+uv venv && source .venv/bin/activate
+uv pip install -r requirements.txt
+
+# …or plain pip
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 2. Configure your key
+
+```bash
+cp .env.template .env
+# then edit .env and set LLM_API_KEY
+```
+
+Minimal `.env` (OpenAI):
+
+```bash
+LLM_PROVIDER="openai"
+LLM_API_KEY="sk-..."
+LLM_MODEL="openai/gpt-5-mini"
+```
+
+Any OpenAI-compatible endpoint (OpenRouter shown):
+
+```bash
+LLM_PROVIDER="custom"
+LLM_API_KEY="your_api_key"
+LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
+LLM_ENDPOINT="https://openrouter.ai/api/v1"
+```
+
+> **Heads-up:** if you configure *only* the LLM or *only* embeddings, Cognee defaults the other to OpenAI. Either configure both or keep a valid OpenAI key handy. All databases default to **local, self-hosted** stores — no external services required.
+
+---
+
+## Usage
+
+```bash
+# Full run: build the belief graph, drop the contradicting fact,
+# print the FALSIFY-vs-RAG scoreboard. Judges start here (~2 min).
+python main.py
+
+# Deterministic demo mode — pins the refuted evidence id so the
+# cascade + forget run on real graph/vector APIs even if the LLM
+# judge is flaky. This is the presentation safety net.
+python main.py --demo
+
+# Run the test suite — 11 tests, NO API key required
+# (FakeGraph + mocked LLM): propagation, diamond, cycle-safety,
+# surgical forget, and the two detector gates.
+pytest -q
+pytest -q tests/test_falsify.py     # core belief-revision cascade
+pytest -q tests/test_detect.py      # two-gate contradiction detector
+```
+
+**No API key?** `main.py` prints a clear message explaining how to set `LLM_API_KEY` and exits with code **0** — it never crashes in front of a judge.
+
+### Cross-session persistence
+
+Truth-state is written *on the graph node*, so it survives a process restart. `main.py` re-reads the belief state fresh at the end of the run to prove the refuted branch never comes back. Run `python main.py --keep` to build on top of existing memory instead of pruning first.
+
+### Visualization
+
+Every run writes a self-contained interactive graph to **`output/graph.html`** — just open it in a browser (no server needed). Nodes are colored by truth-state: **alive = green**, **refuted = red (dashed)**, **invalidated = grey**, **superseded = amber**.
+
+---
+
+## Architecture
+
+Full design — verified Cognee API surface, node/edge vocabulary, the exact forward-propagation algorithm, truth-state lifecycle, and every handled edge case — lives in the build contract:
+
+- **[REQUIREMENTS.md](REQUIREMENTS.md)** — grep-verified Cognee API references, truth-state lifecycle, and edge-case matrix.
+
+```text
+main.py                       # entry point — seed + revise + scoreboard; graceful no-key exit 0
+falsify/
+  models.py                   # DataPoint subclasses (Hypothesis/Evidence/Conclusion) + TruthState
+  edges.py                    # edge-name constants: DEPENDS_ON, SUPPORTS, REFUTES, SUPERSEDES
+  graph_ops.py                # verified wrapper over Cognee's graph + vector engines
+  seed.py                     # demo corpus: the Company-X recall investigation
+  tasks/
+    detect_contradictions.py  # two-gate detector (vector prefilter + skeptical-LLM judge)
+    propagate_refutation.py   # grounded-fixpoint refutation cascade + hypothesis promotion
+    cascade_forget.py         # surgical orphan delete (graph + vector), keeps provenance
+  falsify.py                  # orchestration: build_graph(), revise(new_fact), scoreboard()
+  utils.py                    # interactive HTML viz + BEFORE/AFTER console state
+tests/
+  test_falsify.py             # cascade / diamond / cycle-safety / surgical forget / promote
+  test_detect.py              # detector: pinned demo path + Gate-1 filter + Gate-2 thresholds
+  conftest.py                 # FakeGraph fixture — key-free, DB-free in-memory engine stand-in
+```
+
+---
+
+## How FALSIFY Maps to the Judging Criteria
+
+| # | Criterion | How FALSIFY nails it |
+|---|---|---|
+| 1 | **Potential Impact** | Solves *belief-level amnesia* — AI confidently remembering facts that have been proven false. Every research, legal, medical, or intelligence copilot needs memory that can be *revised*, not just appended. |
+| 2 | **Creativity / Originality** | Reframes graph nodes as **stateful beliefs** (alive / refuted / superseded / invalidated) and treats "changing your mind" as a first-class graph operation — not chat history, not RAG. |
+| 3 | **Technical Excellence** | Custom `memify` extraction + enrichment tasks; deterministic-first **two-gate** contradiction detection; forward BFS propagation with cycle/diamond-safe `visited` sets; dual-store surgical delete; on-node persistent truth-state. |
+| 4 | **Best Use of Cognee** | Drives the v1.0 memory API end-to-end — `remember(session_id)` → `recall()` → `improve()` → surgical `forget()` — plus custom `memify` tasks operating directly on `set_node_truth_state` / `get_neighborhood` / `delete_nodes`. |
+| 5 | **UX / Presentation** | One-screen, 30-second beat: paste one fact → watch A collapse and B ignite → read the FALSIFY-vs-RAG scoreboard. Force-graph colored by belief state. |
+| 6 | **Documentation & Reproducibility** | `python main.py` runs in ~2 min with zero external services; graceful no-key exit; full README + REQUIREMENTS + 11 key-free tests + demo script. |
+
+---
+
+## Hackathon Track & Theme
+
+- **Event:** *The Hangover Part AI: Where's My Context?*
+- **Track:** 🏆 **Best Use of Open Source** — built entirely on open-source Cognee with self-hosted, zero-dependency defaults (LanceDB + Ladybug + SQLite).
+- **Category / Theme:** 🔬 **Research & Knowledge Copilot** — a research assistant whose memory revises its beliefs as new evidence arrives.
+
+The theme asks *"Where's my context?"* FALSIFY's answer: the context isn't lost — it was **wrong**, and the AI should *revise* it, not blindly recall it.
+
+---
+
+## Future Work
+
+- **Confidence-weighted partial refutation** — decay a Conclusion's confidence continuously instead of a binary alive/invalidated flip.
+- **Multi-hop evidence provenance UI** — click any node to trace the full chain of *why it lives or died*.
+- **Automated evidence ingestion** — stream documents in and let the two-gate detector surface contradictions proactively.
+- **Human-in-the-loop review** — queue borderline LLM verdicts (0.4–0.6 confidence) for analyst confirmation before cascading.
+- **Belief-diff export** — a git-style diff of the belief graph between any two epochs.
+- **Neo4j / Postgres backends** — swap the graph engine for a distributed store with no code change (Cognee adapter interface).
+
+---
+
+## Acknowledgments
+
+- **[Cognee](https://github.com/topoteretes/cognee)** — the open-source AI memory platform FALSIFY is built on. Its truth-state graph APIs, custom `memify` pipeline, and self-hosted defaults made belief revision possible without a single external service.
+- **[WeMakeDevs](https://wemakedevs.org/)** — for hosting *The Hangover Part AI* hackathon and championing open-source builders.
+
+---
+
+<div align="center">
+
+**FALSIFY — the AI that revises, not forgets.**
+
+</div>

REQUIREMENTS.md

@@ -0,0 +1,393 @@
+# FALSIFY — Requirements & Build Contract
+
+> **Tagline:** Drop one contradicting fact; watch dependent conclusions die and a losing hypothesis rise — permanently, across sessions.
+
+FALSIFY is a belief-revision research copilot. It treats a research inquiry as a **living belief graph** (not a chat log). When new evidence contradicts an existing evidence node, FALSIFY performs **belief revision**: it flips the contradicted evidence to `refuted`, propagates the refutation **forward** through the dependency chain, marks every dependent conclusion invalid, promotes the best surviving hypothesis, and **surgically forgets** the orphaned dead-ends. The refutation is written to graph node truth-state so the **next session's `recall()` skips killed branches** — while a plain-RAG baseline still cites the stale fact.
+
+This document is the **contract** for all downstream build agents. Every API named here has been verified against the read-only reference at `/workspaces/cognee`. Line references are cited where load-bearing.
+
+---
+
+## 0. Verified Cognee API Surface (grep-confirmed)
+
+| API | Exact import / call | Location (reference, read-only) |
+|---|---|---|
+| `Task` | `from cognee.modules.pipelines.tasks.task import Task` **(lowercase module `task`)** | `cognee/modules/pipelines/tasks/task.py` |
+| `memify` | `import cognee; await cognee.memify(extraction_tasks=[...], enrichment_tasks=[...], data=..., node_type=NodeSet, node_name=[...])` | `cognee/modules/memify/memify.py:26` |
+| `remember` | `await cognee.remember(data, dataset_name=..., session_id=...)` | `cognee/api/v1/remember/remember.py:623` |
+| `recall` | `await cognee.recall(query_text, query_type=..., session_id=..., top_k=...)` | `cognee/api/v1/recall/recall.py:361` |
+| `improve` | `await cognee.improve(...)` | `cognee/api/v1/improve/improve.py:36` |
+| `forget` | `await cognee.forget(...)` | `cognee/api/v1/forget/forget.py:16` |
+| `get_graph_engine` | `from cognee.infrastructure.databases.graph import get_graph_engine` → `ge = await get_graph_engine()` **(async)** | `cognee/infrastructure/databases/graph/get_graph_engine.py:110` |
+| `get_vector_engine` | `from cognee.infrastructure.databases.vector import get_vector_engine` → `ve = get_vector_engine()` **(sync)** | `cognee/infrastructure/databases/vector/get_vector_engine.py:44` |
+| `DataPoint`, `Embeddable`, `Dedup`, `LLMContext` | `from cognee.infrastructure.engine import DataPoint, Embeddable, LLMContext, Dedup` | `cognee/infrastructure/engine/models/DataPoint.py:27` |
+| `LLMGateway` | `from cognee.infrastructure.llm.LLMGateway import LLMGateway` | `cognee/infrastructure/llm/LLMGateway.py:52` |
+
+### Graph engine methods (verified in `graph_db_interface.py` + `ladybug/adapter.py`)
+
+```python
+ge = await get_graph_engine()
+
+# Forward traversal — THE propagation rail. Returns (nodes, edges).
+nodes, edges = await ge.get_neighborhood(node_ids: List[str], depth: int = 1, edge_types: Optional[List[str]] = None)
+#   graph_db_interface.py:303 ; ladybug/adapter.py:2068
+
+# Immediate neighbors of ONE node. Returns List[Tuple[source_props, edge_props, target_props]].
+conns = await ge.get_connections(node_id: Union[str, UUID])
+#   graph_db_interface.py:289 ; ladybug/adapter.py:1859
+
+# Truth-state: the alive/dead flag recall() filters on. PERSISTS across restart.
+await ge.set_node_truth_state({node_id: {"truth_alignment": ["refuted"], "truth_epoch": N}})
+state = await ge.get_node_truth_state(node_ids: List[str])
+#   graph_db_interface.py:357,364 ; ladybug impl 1687,1712 ; writes props "truth_alignment" (list) + "truth_epoch" (int) — adapter.py:1576-1578
+
+# Confidence / health signal.
+await ge.set_node_feedback_weights({node_id: 0.9})   # graph_db_interface.py:348
+w = await ge.get_node_feedback_weights(node_ids)     # graph_db_interface.py:341
+
+# Edges.
+await ge.add_edge(from_node: str, to_node: str, relationship_name: str, edge_properties: Dict = {})  # ladybug/adapter.py:1222
+
+# Surgical delete.
+await ge.delete_nodes(node_ids: List[str])           # graph_db_interface.py:102 ; ladybug 1042
+```
+
+### Vector engine methods (verified in `LanceDBAdapter.py`)
+
+```python
+ve = get_vector_engine()
+hits = await ve.search(collection_name: str, query_text: str = None, limit: int = 15, include_payload: bool = False, ...)
+#   LanceDBAdapter.py:992  — each hit exposes `.id`, `.score` (COSINE DISTANCE, lower = closer), `.payload`
+await ve.delete_data_points(collection_name: str, data_point_ids: List[UUID])
+#   vector_db_interface.py:160 ; LanceDBAdapter.py:1106
+```
+
+### LLMGateway (verified `LLMGateway.py:59`)
+
+```python
+# STATIC method — do NOT instantiate. Returns a coroutine; await it.
+result = await LLMGateway.acreate_structured_output(
+    text_input="A(...): <claim>\nB(...): <claim>",
+    system_prompt="skeptical analyst ...",
+    response_model=ContradictionJudgement,   # a pydantic BaseModel
+)
+```
+
+### DataPoint subclass pattern (verified `Tool.py`)
+
+```python
+from typing import Annotated
+from cognee.infrastructure.engine import DataPoint, Embeddable, Dedup
+
+class Hypothesis(DataPoint):
+    statement: Annotated[str, Embeddable(), Dedup()]
+    question_id: str
+    # identity_fields in metadata dedups nodes across sessions (see §2.4)
+    metadata: dict = {"index_fields": ["statement"], "identity_fields": ["question_id", "statement"]}
+```
+
+> **NOTE for implementers:** The FALSIFY spec screenshot wrote `Task(...)` imported from `pipelines.tasks.Task`. The **correct verified path is lowercase** `cognee.modules.pipelines.tasks.task` (class name `Task`). Use that. `get_graph_engine` is `await`-ed; `get_vector_engine` is **not**.
+
+---
+
+## 1. Core Mechanism
+
+### 1.1 Node & edge vocabulary (see §2 for full model)
+
+- Nodes: `InvestigationQuestion` (root), `Hypothesis`, `Evidence`, `Conclusion`.
+- Edges (relationship_name string on `add_edge`):
+  - `depends_on` : **Conclusion → Evidence** — *THE forward-propagation rail.* A Conclusion `depends_on` the Evidence it rests on. `edge_properties = {"critical": bool}`.
+  - `supports` : **Evidence → Hypothesis** — evidence corroborates a hypothesis. `edge_properties = {"weight": float}`.
+  - `refutes` : **Evidence → Hypothesis** — evidence contradicts a hypothesis. `edge_properties = {"weight": float}`.
+  - `supersedes` : **Evidence(new) → Evidence(old)** — written when the new fact back-dates / overrides an old evidence node. `edge_properties = {"confidence": float}`.
+
+### 1.2 Truth-state lifecycle
+
+`truth_alignment` is a list written to the node via `set_node_truth_state`. FALSIFY uses these canonical single-element states:
+
+```
+alive       — default; node participates in recall context
+refuted      — Evidence directly contradicted by a newer fact (entry point of a cascade)
+superseded   — Evidence/Hypothesis replaced by a newer competing node (still exists, demoted)
+invalidated  — Conclusion whose supporting Evidence chain was refuted (forward-cascade victim)
+forgotten    — orphaned dead-end scheduled for surgical delete (transient; node then removed)
+```
+
+Transition rules:
+
+```
+alive --(new fact contradicts this Evidence, LLM-confirmed)--> refuted
+alive --(a competing Evidence supersedes it)---------------> superseded
+Conclusion.alive --(any critical depends_on Evidence is refuted)--> invalidated
+{refuted|invalidated} node with NO surviving alive dependent/consumer --> forgotten --> delete_nodes + delete_data_points
+Hypothesis.alive --(its only supporting Evidence became refuted AND a rival Hypothesis has surviving support)--> superseded
+losing Hypothesis' rival --(gains the strongest surviving support)--> stays alive, feedback_weight promoted
+```
+
+Every state write also bumps `truth_epoch` to a monotonically increasing integer (epoch = the memify run counter). Recall filters on `truth_alignment` containing `"alive"`.
+
+### 1.3 Contradiction detection (two-gate, deterministic-first)
+
+The detector runs inside the `propagate_refutation` extraction/enrichment task. **Two gates** to kill nondeterminism:
+
+1. **Vector prefilter (cheap, deterministic).** `hits = await ve.search("Evidence_claim", query_text=NEW_FACT, limit=5, include_payload=True)`. Candidates = hits with **cosine distance `score < 0.35`** (topically related — same subject). This narrows the LLM to plausibly-conflicting evidence only. Contradictory claims sometimes embed far apart, so claims MUST be normalized to `subject + predicate` phrasing at ingest, and `limit` kept ≥5.
+2. **LLM adjudication (semantic).** For each candidate, call `LLMGateway.acreate_structured_output` with a **skeptical-analyst** system prompt and `response_model=ContradictionJudgement` (below). Only a verdict of `contradicts` (or `supersedes`) with `confidence ≥ 0.6` triggers refutation. This distinguishes *genuine contradiction* ("report was back-dated") from *topical overlap* ("also mentions the report").
+
+```python
+class ContradictionJudgement(BaseModel):
+    relation: Literal["contradicts", "supersedes", "supports", "unrelated"]
+    confidence: float  # 0..1
+    rationale: str
+```
+
+**`--demo` / `DEMO_MODE` override:** when set, the seeded contradiction's target evidence id is pinned (`REFUTED_ID` env / seed constant), so the cascade runs on real graph APIs even if the LLM judge stalls or the key is flaky. This is the non-negotiable demo safety net.
+
+### 1.4 Forward refutation propagation (exact algorithm)
+
+Entry: an Evidence node `E` confirmed `refuted` (§1.3).
+
+```
+1. set_node_truth_state({E.id: {"truth_alignment": ["refuted"], "truth_epoch": epoch}})
+   set_node_feedback_weights({E.id: 0.0})
+
+2. FORWARD CLOSURE — reverse-BFS along depends_on (Conclusion --depends_on--> Evidence).
+   Seeds = [E.id]. Traverse edges of type ["depends_on", "supersedes"] via:
+       nodes, edges = await ge.get_neighborhood([E.id], depth=4, edge_types=["depends_on", "supports"])
+   Collect every Conclusion C where a `depends_on` edge points from C into the refuted set
+   (transitively, up to depth 4). Because depends_on is Conclusion→Evidence, the "dependents"
+   are the SOURCES of those edges. A Conclusion is invalidated iff at least one of its
+   `critical: true` depends_on edges targets a refuted/invalidated node.
+
+3. For each invalidated Conclusion C:
+       set_node_truth_state({C.id: {"truth_alignment": ["invalidated"], "truth_epoch": epoch}})
+       set_node_feedback_weights({C.id: 0.0})
+
+4. PROMOTE competing hypothesis (promote_competing_hypothesis task):
+   - Find the Hypothesis H_dead whose only supporting Evidence is now refuted.
+       set_node_truth_state({H_dead.id: {"truth_alignment": ["superseded"], "truth_epoch": epoch}})
+   - Among rival Hypotheses still holding ≥1 alive `supports` Evidence, pick the one with the
+     highest summed support weight (read edge {"weight"}). Promote it:
+       set_node_feedback_weights({H_win.id: <boosted>})  # stays alive; becomes new frontier
+
+5. RECORD new fact + supersedes edge (add_data_points dual-write):
+   - Materialize NEW_FACT as an Evidence DataPoint, add via add_data_points (writes graph + vector).
+   - add_edge(new_evidence.id, E.id, "supersedes", {"confidence": verdict.confidence})
+```
+
+**Direction summary:** refutation flows *from Evidence up to the Conclusions that depend on it* by walking `depends_on` edges backward (Conclusion is the edge source). Hypotheses are re-scored via their `supports`/`refutes` edges. No forward walk ever crosses a `supersedes` edge into an already-superseded node (prevents loops — see §4).
+
+### 1.5 forget() orphan conditions (surgical delete)
+
+`forget_orphan_deadends()` runs after propagation and grows a **death set** by traversal:
+
+```
+A node is FORGOTTEN (hard-deleted from graph + vector) iff ALL hold:
+  (a) its truth_alignment is refuted OR invalidated (never alive/superseded — superseded nodes
+      are kept as provenance), AND
+  (b) it has NO surviving consumer: no alive node reaches it via depends_on/supports
+      (checked with get_connections — _has_alive_alternative == False), AND
+  (c) it is not itself the target of a supersedes edge FROM an alive node (that node is the
+      provenance anchor of the new truth and must be retained).
+
+Nodes that STILL feed a live node are retained even if refuted (partial refutation, §4).
+```
+
+Delete implementation (one shot per node batch):
+```python
+await ge.delete_nodes([str(id) for id in death_set])
+await ve.delete_data_points("Evidence_claim", [evidence_ids_in_death_set])
+await ve.delete_data_points("Conclusion_statement", [conclusion_ids_in_death_set])
+```
+
+> Provenance is kept: only *truly orphaned* dead-ends are hard-deleted. `refuted`/`superseded` nodes that still explain *why* the graph changed remain, carrying their state flag.
+
+### 1.6 Cross-session persistence (the proof)
+
+Truth-state is stored **on the node** in the graph DB (Ladybug/SQLite-backed), so it survives process restart. Session 2's `recall()` reads only `truth_alignment == alive` context. A parallel **plain-RAG baseline** (`recall(query_type=SearchType.RAG_COMPLETION)` or direct `ve.search`) does NOT read truth-state and re-cites the deleted/stale fact — this A/B is the scoreboard.
+
+---
+
+## 2. Data Model
+
+### 2.1 Node DataPoint subclasses (`memory_core/models.py`)
+
+| Class | Embeddable field | Other fields | Collection (auto) |
+|---|---|---|---|
+| `InvestigationQuestion` | `question: Annotated[str, Embeddable()]` | — | `InvestigationQuestion_question` |
+| `Hypothesis` | `statement: Annotated[str, Embeddable(), Dedup()]` | `question_id: str`, `status: str="alive"`, `prior: float` | `Hypothesis_statement` |
+| `Evidence` | `claim: Annotated[str, Embeddable(), Dedup()]` | `source_id: str`, `quote: str`, `stance: str` (`supports`/`refutes`), `asserted_at: str` (ISO date) | `Evidence_claim` (**the refutation entry point / vector prefilter target**) |
+| `Conclusion` | `statement: Annotated[str, Embeddable()]` | `confidence: float`, `depends_on_ids: list[str]` | `Conclusion_statement` |
+
+The collection name is `"{ClassName}_{embeddable_field}"` — auto-created on write. `Evidence_claim` is the collection the contradiction prefilter searches.
+
+### 2.2 Edge types (already listed §1.1)
+
+`depends_on` (Conclusion→Evidence, `{critical:bool}`), `supports`/`refutes` (Evidence→Hypothesis, `{weight:float}`), `supersedes` (Evidence→Evidence, `{confidence:float}`).
+
+### 2.3 Node-level metadata / state fields (written via engine APIs, not model fields)
+
+| Field | Written by | Meaning |
+|---|---|---|
+| `truth_alignment: list[str]` | `set_node_truth_state` | lifecycle state (§1.2). Recall filter key. |
+| `truth_epoch: int` | `set_node_truth_state` | monotonically increasing revision epoch. |
+| `feedback_weight: float` | `set_node_feedback_weights` | confidence/health (0.0 = dead, promoted hypotheses boosted). |
+| `asserted_at` (model field on Evidence) | ingest | timestamp used for supersede tie-breaks (`newer = max(asserted_at)`). |
+| `source_id` (model field) | ingest | provenance handle for the source document. |
+
+### 2.4 Dedup across sessions
+
+`Hypothesis` and `Evidence` set `identity_fields` in `metadata` (e.g. `["question_id","statement"]`). DataPoint generates a stable identity id from these (`DataPoint.py:76-81`), so re-adding the same belief in a later session updates the existing node instead of duplicating it — essential for cross-session refutation to land on the right node.
+
+---
+
+## 3. User / Demo Flow
+
+### 3.1 End-to-end story (money shot)
+
+> **Question:** *"Did Company X know about the defect before the recall?"*
+>
+> **Session 1** builds:
+> - Hypothesis **A**: "X knew via QA report, Mar 2021" (supported by Evidence `E_qa`)
+> - Hypothesis **B**: "X knew via supplier email, Jan 2021" (supported by Evidence `E_email`)
+> - Hypothesis **C**: "X didn't know" (unsupported)
+> - Conclusion **K**: "X knew by March 2021" — `depends_on(K → E_qa, critical=True)`
+>
+> Saved graph persists (survives restart).
+>
+> **Session 2** (reopened next day): analyst pastes ONE line — *"Forensic audit: the March QA report was back-dated."*
+> 1. `Evidence_claim` vector prefilter finds `E_qa` (distance < 0.35).
+> 2. LLM judge: `contradicts`, confidence 0.9.
+> 3. `E_qa → refuted`; **forward BFS** over `depends_on` finds **K** (critical dep) → `K invalidated`.
+> 4. **A** loses its only support → `A superseded`; **B** ignites as the new frontier (feedback_weight promoted) — in ~3s.
+> 5. `forget_orphan_deadends`: K is orphaned (no alive consumer) → hard-deleted from graph + vector. `E_qa` kept as `refuted` provenance (target of new fact's `supersedes` edge).
+> 6. **Scoreboard:** FALSIFY recall now answers via **B (Jan 2021)**; the **plain-RAG baseline still cites the back-dated March QA report.**
+
+### 3.2 Screen beat (≤30s, one screen)
+
+Force-graph shows A/B/C + K. Analyst pastes the fact → **E_qa flashes red → K crosses out and vanishes → A dims (superseded) → B glows green as new frontier.** A live scoreboard panel: `FALSIFY: "B — Jan 2021 (supplier email)"` vs `Plain RAG: "March 2021 QA report"` — captioned *"AI revised, not forgot."*
+
+### 3.3 Cross-session proof
+
+Restart the process (or run `main.py` a second time with `--session 2`). Because truth-state is on-node persisted, session 2's `recall()` never sees K or A-as-truth. Show the two recalls side by side.
+
+---
+
+## 4. Success Criteria
+
+### 4.1 Unit-test assertions (pytest)
+
+```
+test_direct_refutation:
+    after propagate_refutation(new_fact contradicting E_qa):
+    assert get_node_truth_state([E_qa])[E_qa]["truth_alignment"] == ["refuted"]
+
+test_forward_cascade_invalidates_conclusion:
+    assert get_node_truth_state([K])[K]["truth_alignment"] == ["invalidated"]
+
+test_competing_hypothesis_promoted:
+    assert A.truth_alignment == ["superseded"]
+    assert "alive" in B.truth_alignment
+    assert feedback_weight(B) > feedback_weight(A)
+
+test_orphan_forgotten_from_both_stores:
+    assert K.id NOT in (await ge has node)            # gone from graph
+    assert K.id NOT in ve.search("Conclusion_statement", ...)   # gone from vector
+
+test_provenance_kept:
+    assert E_qa still exists with truth_alignment == ["refuted"]   # NOT deleted (supersede anchor)
+
+test_cross_session_recall_skips_dead:
+    recall("did X know?") context contains B, does NOT contain K or A-as-truth
+
+test_baseline_still_stale:
+    RAG_COMPLETION / raw ve.search STILL returns the March QA claim   # proves the differentiator
+```
+
+### 4.2 Expected `python main.py` output (judges, ~2 min)
+
+```
+[FALSIFY] Session 1: built belief graph for "Did Company X know...?"
+          Hypotheses: A(QA Mar'21) B(email Jan'21) C(didn't know)
+          Conclusion K depends_on E_qa
+[FALSIFY] Session 2: new fact -> "March QA report was back-dated"
+          contradiction: E_qa  (judge=contradicts conf=0.90)
+          forward cascade: K invalidated
+          A superseded  ->  B ignites (new frontier)
+          forgot 1 orphan (K) from graph + vector
+[SCOREBOARD]
+   FALSIFY recall : X knew by Jan 2021 (supplier email)   [revised]
+   Plain-RAG      : X knew by Mar 2021 (QA report)         [STALE]
+```
+
+Graceful exit if no API key: print a clear message + how to set `LLM_API_KEY`, exit code **0**.
+
+### 4.3 Edge cases (must be handled)
+
+| Case | Required behavior |
+|---|---|
+| **Cycle** (A depends_on B depends_on A) | BFS tracks a `visited` set; never revisit. `supersedes` edges never traversed into already-superseded nodes. Termination guaranteed. |
+| **Multiple contradictions** (new fact refutes 2 Evidence nodes) | Each refuted independently; union of their dependent Conclusions invalidated; single forget pass over the merged death set. |
+| **Partial refutation** (Conclusion depends_on E_qa AND E_alt, both critical) | Conclusion invalidated only if a *critical* dep is refuted AND no alive critical alternative remains (`_has_alive_alternative`). If E_alt still alive & critical satisfied, Conclusion stays alive; E_qa refuted but **retained** (still feeds a live node → not orphaned). |
+| **Diamond dependency** (K depends_on E1,E2; E1,E2 both depends-chain to refuted E0) | Deduplicate via visited set so K is invalidated once, not twice; forget counts each node once. Explicit unit test required. |
+| **Non-critical dep refuted** | Conclusion's `confidence` decays but stays `alive` (only `critical:true` deps invalidate). |
+| **Contradiction judge false-positive risk** | Two-gate (vector `<0.35` + LLM `≥0.6`) + `--demo` pin. |
+
+---
+
+## 5. Tech Stack & Module Layout
+
+### 5.1 Cognee APIs used (all §0-verified)
+
+- Persistence: `cognee.remember(session_id=...)`, `cognee.recall(session_id=..., query_type=...)`.
+- Enrichment pipeline: `cognee.memify(extraction_tasks=[Task(collect_belief_subgraph)], enrichment_tasks=[Task(propagate_refutation), Task(promote_competing_hypothesis), Task(forget_orphan_deadends), Task(add_data_points)], data=[{}], node_type=NodeSet, node_name=[question_id])`.
+- Graph: `get_graph_engine()` → `get_neighborhood` (depth=4, edge_types=["depends_on","supports"]), `get_connections`, `set_node_truth_state`, `get_node_truth_state`, `set_node_feedback_weights`, `add_edge`, `delete_nodes`.
+- Vector: `get_vector_engine()` → `search("Evidence_claim", ...)`, `delete_data_points`.
+- LLM: `LLMGateway.acreate_structured_output(text_input, system_prompt, response_model=ContradictionJudgement)`.
+- Storage: `add_data_points` task (`cognee/tasks/storage/add_data_points.py:31`) for dual graph+vector write of the new fact.
+- Baseline: `SearchType.RAG_COMPLETION` (from `cognee/modules/search/types/SearchType.py`).
+
+### 5.2 Module layout (write under `/workspaces/hackathon-app/`)
+
+```
+/workspaces/hackathon-app/
+  main.py                      # `python main.py` entry — runs seed + demo + scoreboard; graceful no-key exit 0
+  requirements.txt / pyproject # deps: cognee (editable ref) + minimal
+  .env.template                # LLM_API_KEY, LLM_PROVIDER=openai, LLM_ENDPOINT (custom endpoint), LLM_MODEL, DEMO_MODE
+  memory_core/
+    __init__.py
+    models.py                  # DataPoint subclasses (§2.1) + ContradictionJudgement
+    edges.py                   # edge-name constants: DEPENDS_ON, SUPPORTS, REFUTES, SUPERSEDES
+    tasks.py                   # collect_belief_subgraph, propagate_refutation,
+                               #   promote_competing_hypothesis, forget_orphan_deadends
+    falsify.py                 # orchestration: build_graph(), revise(new_fact), scoreboard()
+    seed.py                    # demo corpus: Company-X recall investigation (A/B/C + K)
+  ui/
+    graph.html                 # react-force-graph (color by truth_state, red-flash-then-remove ripple ≤3s)
+    server.py                  # tiny static+JSON server feeding get_neighborhood snapshots
+  tests/
+    test_propagation.py        # §4.1 assertions
+    test_edge_cases.py         # cycle / diamond / partial / multi
+```
+
+### 5.3 Visualization approach
+
+- **react-force-graph** (CDN, single `graph.html`) reads a JSON snapshot built from `ge.get_neighborhood([question_id], depth=4)`.
+- Node color keyed on `truth_alignment`: alive=green, refuted=red, invalidated=grey-strikethrough, superseded=dim-amber. Forgotten nodes: **red-flash animation then removed** from the sim (≤3s ripple).
+- Scoreboard panel overlays FALSIFY-vs-RAG answers. No external services — server is stdlib/`http.server` or FastAPI already in cognee.
+
+### 5.4 Config / runtime constraints
+
+- OpenAI-compatible: honor `LLM_PROVIDER` (`openai` or `custom`), `LLM_ENDPOINT`, `LLM_MODEL`, `LLM_API_KEY`. Defaults: LanceDB (vector) + Ladybug (graph) + SQLite (relational) — **zero external services**.
+- `DEMO_MODE=1` (or `--demo`) pins `REFUTED_ID` so the cascade+forget run on real APIs regardless of LLM flakiness.
+- Never modify `/workspaces/cognee`. All writes under `/workspaces/hackathon-app/` (absolute paths).
+
+---
+
+## 6. Non-negotiables (contract invariants)
+
+1. Forward propagation uses `get_neighborhood` + `set_node_truth_state` (on-node, persistent). No in-memory-only state.
+2. Surgical forget deletes from **both** graph (`delete_nodes`) and vector (`delete_data_points`); provenance (`refuted`/`superseded`) nodes are retained.
+3. Cross-session persistence of disbelief is demonstrated (restart / session 2 recall skips dead branches).
+4. The A/B scoreboard (FALSIFY revised vs plain-RAG stale) is shown every run.
+5. Contradiction detection is two-gate (vector prefilter `<0.35` + LLM judge `≥0.6`) with a `--demo` deterministic override.
+6. `Task` imported from `cognee.modules.pipelines.tasks.task` (lowercase); `get_graph_engine` awaited, `get_vector_engine` not.

cognee-hackathon-project-main/.env.template

@@ -0,0 +1,84 @@
+# ============================================================================
+# FALSIFY — environment configuration
+# Copy this file to `.env` and fill in your key:   cp .env.template .env
+# ============================================================================
+
+# ----------------------------------------------------------------------------
+# LLM provider (OpenAI-compatible)
+# ----------------------------------------------------------------------------
+# FALSIFY works with OpenAI or ANY OpenAI-compatible endpoint (OpenRouter,
+# vLLM, LM Studio, Azure, local proxies, ...). Pick ONE of the blocks below.
+
+# --- Default: OpenAI ---------------------------------------------------------
+LLM_PROVIDER="openai"
+LLM_API_KEY="sk-ws-H.LIEMPD.DpZK.MEUCIA7GLanKjqNWA0UKOWsBVdGLaMhqZYh3BHYqMNL9Z_oGAiEA2u1dfrMN6KjNoVmBrQWrYwbfdlgRtKnRIfpRSym-z5M"
+LLM_MODEL="openai/gpt-5-mini"
+# LLM_ENDPOINT is not needed for the default OpenAI provider.
+
+# --- Alternative: custom / OpenAI-compatible endpoint (e.g. OpenRouter) ------
+# Uncomment this block and comment out the OpenAI block above to use it.
+# LLM_PROVIDER="custom"
+# LLM_API_KEY="your_api_key"
+# LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
+# LLM_ENDPOINT="https://openrouter.ai/api/v1"
+
+# --- Alternative: Alibaba DashScope (Qwen), OpenAI-compatible ----------------
+# Note the "openai/" prefix on the model — litellm needs it to route a raw
+# OpenAI-compatible endpoint. Verified working with FALSIFY.
+# LLM_PROVIDER="custom"
+# LLM_API_KEY="sk-..."
+# LLM_MODEL="openai/qwen-plus"
+# LLM_ENDPOINT="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+
+# ----------------------------------------------------------------------------
+# Embeddings — fastembed (local, CPU-only, zero-cost) is FALSIFY's default
+# ----------------------------------------------------------------------------
+# FALSIFY sets these automatically at import so the pipeline (and
+# `python main.py --demo`) runs with NO external embedding key. This keeps your
+# LLM key (above) LLM-only and avoids the classic "LLM provider != embedding
+# provider" mismatch. Any explicit value here overrides the default.
+EMBEDDING_PROVIDER="fastembed"
+EMBEDDING_MODEL="BAAI/bge-small-en-v1.5"
+EMBEDDING_DIMENSIONS="384"
+EMBEDDING_MAX_TOKENS="512"
+# To use OpenAI embeddings instead, set:
+# EMBEDDING_PROVIDER="openai"
+# EMBEDDING_MODEL="openai/text-embedding-3-large"
+# EMBEDDING_API_KEY="sk-your-openai-key-here"
+
+# ----------------------------------------------------------------------------
+# Session memory / caching
+# ----------------------------------------------------------------------------
+# Cross-session belief persistence uses Cognee's session cache. Default backend
+# is local SQLite — zero external services, survives process restarts.
+# Backends: sqlite (default), postgres, redis, fs, tapes
+CACHING="true"
+CACHE_BACKEND="sqlite"
+# Optional explicit SQLAlchemy URL (only for sqlite/postgres backends):
+# CACHE_DB_URL="postgresql+asyncpg://cognee:cognee@localhost:5432/cognee_db"
+
+# ----------------------------------------------------------------------------
+# Databases (self-hosted defaults — no setup required)
+# ----------------------------------------------------------------------------
+# FALSIFY ships with fully local, zero-dependency stores:
+#   Vector   -> LanceDB
+#   Graph    -> Ladybug
+#   Relational -> SQLite
+# These are the defaults; the lines below are shown only for clarity.
+# VECTOR_DB_PROVIDER="lancedb"
+# GRAPH_DATABASE_PROVIDER="ladybug"
+# DB_PROVIDER="sqlite"
+
+# ----------------------------------------------------------------------------
+# FALSIFY demo behavior
+# ----------------------------------------------------------------------------
+# DEMO_MODE=1 (or `python main.py --demo`) pins the refuted evidence id so the
+# refutation cascade + surgical forget run on real graph/vector APIs even if the
+# LLM contradiction judge stalls or the key is rate-limited. Presentation safety net.
+DEMO_MODE="0"
+
+# ----------------------------------------------------------------------------
+# Optional: quieter logs / telemetry off
+# ----------------------------------------------------------------------------
+# LITELLM_LOG="ERROR"
+# TELEMETRY_DISABLED="1"

cognee-hackathon-project-main/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+output/
+*.lance
+.cognee_system/
+.data_storage/
+!output/falsify-demo.gif

cognee-hackathon-project-main/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arpit Kumar
+
+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.

cognee-hackathon-project-main/README.md

@@ -0,0 +1,289 @@
+<div align="center">
+
+# FALSIFY
+
+### the AI that revises, not forgets
+
+**Drop one contradicting fact. Watch dependent conclusions die, a losing hypothesis rise — permanently, across sessions.**
+
+[![Track: Best Use of Open Source](https://img.shields.io/badge/Track-Best_Use_of_Open_Source-blue)](#-hackathon-track--theme)
+[![Theme: Research & Knowledge Copilot](https://img.shields.io/badge/Theme-Research_&_Knowledge_Copilot-8A2BE2)](#-hackathon-track--theme)
+[![Built on Cognee](https://img.shields.io/badge/Built_on-Cognee-00C48C)](https://github.com/topoteretes/cognee)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
+
+</div>
+
+---
+
+## The Problem: AI Remembers the *Wrong* Fact
+
+Every memory layer bolted onto an LLM today is an **append-only pile of facts**. It can remember. It cannot *un-believe*.
+
+When new evidence contradicts something the AI already "knows," today's systems do one of two bad things:
+
+- **RAG / vector memory** keeps citing the stale fact forever — it has no notion that a belief can *die*.
+- **Naive "delete the memory"** throws away the fact *and* every conclusion built on top of it, with no record of *why* — a lobotomy, not a revision.
+
+This is **belief-level amnesia**. The AI doesn't just forget *where* it put the context (this hackathon's theme) — it confidently remembers a fact that has since been proven false, and every downstream conclusion inherits the lie.
+
+> A forensic audit reveals the "March QA report" was **back-dated**. A human analyst instantly revises: *"Then the March timeline is dead — the January supplier email is now our best evidence."* Today's AI memory keeps answering **"March 2021."**
+
+---
+
+## The Solution: A Living Belief Graph
+
+FALSIFY treats a research inquiry not as a chat log but as a **living belief graph** of typed, stateful nodes — `Hypothesis`, `Evidence`, `Conclusion` — wired together by dependency edges.
+
+When a new fact **contradicts** an existing piece of evidence, FALSIFY performs **belief revision** on the graph itself:
+
+1. **Refute** — the contradicted `Evidence` flips to `truth_state = REFUTED`.
+2. **Propagate forward** — the refutation cascades *along `depends_on` edges* to every `Conclusion` that critically rested on it → `INVALIDATED`.
+3. **Re-ignite** — the losing `Hypothesis` is demoted to `SUPERSEDED`; the strongest surviving rival is promoted as the new frontier.
+4. **Surgically forget** — orphaned dead-ends (no surviving consumer) are hard-deleted from **both** the graph and the vector store. Provenance nodes (the refuted fact, the superseding fact) are **kept** so the graph always explains *why* it changed.
+5. **Persist** — truth-state is written *on the node*, so the **next session's `recall()` skips the dead branches** — while a plain-RAG baseline still cites the stale fact.
+
+The result is memory that **revises instead of forgets**: it changes its mind, keeps the receipts, and never loses the thread.
+
+---
+
+## Demo
+
+<div align="center">
+
+![FALSIFY demo — a refutation cascade collapsing Hypothesis A and igniting Hypothesis B](output/falsify-demo.gif)
+
+*A **live** run (the LLM judges the contradiction): drop one back-dating fact → `E_qa` turns **red (refuted)** → Conclusion **K is forgotten** (deleted from graph + vector) → Hypothesis **A** dims to **amber (superseded)** → Hypothesis **B ignites** as the new frontier. Caption: **"AI revised, not forgot."***
+
+</div>
+
+The money shot is the **scoreboard** printed on every run:
+
+```text
+[SCOREBOARD]
+   FALSIFY recall : X knew by Jan 2021 (supplier email)   [revised]
+   Plain-RAG      : X knew by Mar 2021 (QA report)         [STALE]
+```
+
+Same underlying store. Same query. FALSIFY revised its belief; the baseline did not.
+
+---
+
+## Key Features
+
+| | Feature | What it does |
+|---|---|---|
+| 🧠 | **Belief graph, not a fact pile** | Nodes are *stateful beliefs* (`alive` / `refuted` / `superseded` / `invalidated`), not immutable rows. |
+| ⚡ | **Forward refutation propagation** | One contradiction cascades through `depends_on` edges and invalidates every dependent conclusion in ~3s. |
+| 🎯 | **Two-gate contradiction detection** | Cheap deterministic vector prefilter (`cosine < 0.35`) → skeptical LLM adjudication (`confidence ≥ 0.6`). No hallucinated refutations. |
+| ✂️ | **Surgical forget** | Orphaned dead-ends are hard-deleted from graph **and** vector; provenance is retained. Not a lobotomy — a revision. |
+| 🔁 | **Cross-session persistence** | Disbelief lives on the node. Restart the process and `recall()` still skips the dead branches. |
+| 📊 | **Live A/B scoreboard** | FALSIFY (revised) vs. plain-RAG (stale) side-by-side, every run — the differentiator made visible. |
+| 🕸️ | **Force-graph visualization** | Nodes colored by truth-state; forgotten nodes red-flash then ripple out of the sim. |
+| 🔌 | **Zero external services** | Self-hosted Cognee defaults — LanceDB (vector) + Ladybug (graph) + SQLite. OpenAI-compatible; bring any endpoint. |
+
+---
+
+## How It Works
+
+FALSIFY drives Cognee's v1.0 memory API (`remember` / `recall` / `improve` / `forget`) plus a set of **custom `memify` tasks** that operate directly on the graph engine's truth-state.
+
+```mermaid
+flowchart TD
+    subgraph S1["Session 1 — build the belief graph"]
+        Q["InvestigationQuestion<br/>Did Company X know before the recall?"]
+        HA["Hypothesis A<br/>knew via QA report, Mar 2021"]
+        HB["Hypothesis B<br/>knew via supplier email, Jan 2021"]
+        HC["Hypothesis C<br/>didn't know"]
+        Eqa["Evidence E_qa<br/>March QA report"]
+        Eem["Evidence E_email<br/>January supplier email"]
+        K["Conclusion K<br/>X knew by March 2021"]
+
+        Q --- HA & HB & HC
+        Eqa -- supports --> HA
+        Eem -- supports --> HB
+        K -- "depends_on (critical)" --> Eqa
+    end
+
+    NF["🆕 New fact (Session 2)<br/>Forensic audit: March QA report was back-dated"]
+
+    subgraph REV["Belief revision — custom memify tasks"]
+        direction TB
+        D["1. Detect contradiction<br/>vector prefilter < 0.35  →  LLM judge ≥ 0.6"]
+        R["2. E_qa → REFUTED"]
+        P["3. Forward BFS on depends_on<br/>K → INVALIDATED"]
+        G["4. A → SUPERSEDED &nbsp;•&nbsp; B ignites (promoted)"]
+        F["5. Forget orphan K<br/>delete from graph + vector<br/>keep E_qa as refuted provenance"]
+        D --> R --> P --> G --> F
+    end
+
+    NF --> D
+    Eqa -.-> D
+
+    subgraph SCORE["Scoreboard"]
+        FA["FALSIFY recall → B (Jan 2021)  ✅ revised"]
+        RA["Plain-RAG → March 2021 QA report  ❌ stale"]
+    end
+
+    F --> FA
+    F --> RA
+```
+
+**The mechanism in one paragraph:** a `Conclusion --depends_on--> Evidence` edge is the propagation rail. Refutation seeds at an `Evidence` node; a conclusion stays justified only if it has a **grounded** critical support chain that bottoms out in a still-alive node. FALSIFY computes this as a **least-fixpoint** over the dependency graph, so one formulation correctly handles chains, **diamonds** (a conclusion survives while any critical alternative is grounded), non-critical dependencies, **and cycles** (a self-supporting loop with no grounded base collapses — and the fixpoint always terminates). Hypotheses are re-scored via their `supports` edges. Truth-state (`truth_alignment` + `truth_epoch`) is written on-node via `set_node_truth_state`, so it survives a restart and `recall()` filters on it. See [`falsify/tasks/propagate_refutation.py`](falsify/tasks/propagate_refutation.py) and [REQUIREMENTS.md](REQUIREMENTS.md) for the full algorithm, edge vocabulary, and edge-case handling.
+
+---
+
+## Install & Setup
+
+### Prerequisites
+- Python **3.10 – 3.14**
+- An OpenAI **or any OpenAI-compatible** API key (OpenRouter, vLLM, LM Studio, Azure, …)
+
+### 1. Clone & create an environment
+
+```bash
+git clone https://github.com/ArpitKumar8649/cognee-hackathon-project.git
+cd cognee-hackathon-project
+
+# uv (recommended)
+uv venv && source .venv/bin/activate
+uv pip install -r requirements.txt
+
+# …or plain pip
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 2. Configure your key
+
+```bash
+cp .env.template .env
+# then edit .env and set LLM_API_KEY
+```
+
+Minimal `.env` (OpenAI):
+
+```bash
+LLM_PROVIDER="openai"
+LLM_API_KEY="sk-..."
+LLM_MODEL="openai/gpt-5-mini"
+```
+
+Any OpenAI-compatible endpoint (OpenRouter shown):
+
+```bash
+LLM_PROVIDER="custom"
+LLM_API_KEY="your_api_key"
+LLM_MODEL="openrouter/google/gemini-2.0-flash-lite-preview-02-05:free"
+LLM_ENDPOINT="https://openrouter.ai/api/v1"
+```
+
+> **Heads-up:** if you configure *only* the LLM or *only* embeddings, Cognee defaults the other to OpenAI. Either configure both or keep a valid OpenAI key handy. All databases default to **local, self-hosted** stores — no external services required.
+
+---
+
+## Usage
+
+```bash
+# Full run: build the belief graph, drop the contradicting fact,
+# print the FALSIFY-vs-RAG scoreboard. Judges start here (~2 min).
+python main.py
+
+# Deterministic demo mode — pins the refuted evidence id so the
+# cascade + forget run on real graph/vector APIs even if the LLM
+# judge is flaky. This is the presentation safety net.
+python main.py --demo
+
+# Run the test suite — 11 tests, NO API key required
+# (FakeGraph + mocked LLM): propagation, diamond, cycle-safety,
+# surgical forget, and the two detector gates.
+pytest -q
+pytest -q tests/test_falsify.py     # core belief-revision cascade
+pytest -q tests/test_detect.py      # two-gate contradiction detector
+```
+
+**No API key?** `main.py` prints a clear message explaining how to set `LLM_API_KEY` and exits with code **0** — it never crashes in front of a judge.
+
+### Cross-session persistence
+
+Truth-state is written *on the graph node*, so it survives a process restart. `main.py` re-reads the belief state fresh at the end of the run to prove the refuted branch never comes back. Run `python main.py --keep` to build on top of existing memory instead of pruning first.
+
+### Visualization
+
+Every run writes a self-contained interactive graph to **`output/graph.html`** — just open it in a browser (no server needed). Nodes are colored by truth-state: **alive = green**, **refuted = red (dashed)**, **invalidated = grey**, **superseded = amber**.
+
+---
+
+## Architecture
+
+Full design — verified Cognee API surface, node/edge vocabulary, the exact forward-propagation algorithm, truth-state lifecycle, and every handled edge case — lives in the build contract:
+
+- **[REQUIREMENTS.md](REQUIREMENTS.md)** — grep-verified Cognee API references, truth-state lifecycle, and edge-case matrix.
+
+```text
+main.py                       # entry point — seed + revise + scoreboard; graceful no-key exit 0
+falsify/
+  models.py                   # DataPoint subclasses (Hypothesis/Evidence/Conclusion) + TruthState
+  edges.py                    # edge-name constants: DEPENDS_ON, SUPPORTS, REFUTES, SUPERSEDES
+  graph_ops.py                # verified wrapper over Cognee's graph + vector engines
+  seed.py                     # demo corpus: the Company-X recall investigation
+  tasks/
+    detect_contradictions.py  # two-gate detector (vector prefilter + skeptical-LLM judge)
+    propagate_refutation.py   # grounded-fixpoint refutation cascade + hypothesis promotion
+    cascade_forget.py         # surgical orphan delete (graph + vector), keeps provenance
+  falsify.py                  # orchestration: build_graph(), revise(new_fact), scoreboard()
+  utils.py                    # interactive HTML viz + BEFORE/AFTER console state
+tests/
+  test_falsify.py             # cascade / diamond / cycle-safety / surgical forget / promote
+  test_detect.py              # detector: pinned demo path + Gate-1 filter + Gate-2 thresholds
+  conftest.py                 # FakeGraph fixture — key-free, DB-free in-memory engine stand-in
+```
+
+---
+
+## How FALSIFY Maps to the Judging Criteria
+
+| # | Criterion | How FALSIFY nails it |
+|---|---|---|
+| 1 | **Potential Impact** | Solves *belief-level amnesia* — AI confidently remembering facts that have been proven false. Every research, legal, medical, or intelligence copilot needs memory that can be *revised*, not just appended. |
+| 2 | **Creativity / Originality** | Reframes graph nodes as **stateful beliefs** (alive / refuted / superseded / invalidated) and treats "changing your mind" as a first-class graph operation — not chat history, not RAG. |
+| 3 | **Technical Excellence** | Custom `memify` extraction + enrichment tasks; deterministic-first **two-gate** contradiction detection; forward BFS propagation with cycle/diamond-safe `visited` sets; dual-store surgical delete; on-node persistent truth-state. |
+| 4 | **Best Use of Cognee** | Drives the v1.0 memory API end-to-end — `remember(session_id)` → `recall()` → `improve()` → surgical `forget()` — plus custom `memify` tasks operating directly on `set_node_truth_state` / `get_neighborhood` / `delete_nodes`. |
+| 5 | **UX / Presentation** | One-screen, 30-second beat: paste one fact → watch A collapse and B ignite → read the FALSIFY-vs-RAG scoreboard. Force-graph colored by belief state. |
+| 6 | **Documentation & Reproducibility** | `python main.py` runs in ~2 min with zero external services; graceful no-key exit; full README + REQUIREMENTS + 11 key-free tests + demo script. |
+
+---
+
+## Hackathon Track & Theme
+
+- **Event:** *The Hangover Part AI: Where's My Context?*
+- **Track:** 🏆 **Best Use of Open Source** — built entirely on open-source Cognee with self-hosted, zero-dependency defaults (LanceDB + Ladybug + SQLite).
+- **Category / Theme:** 🔬 **Research & Knowledge Copilot** — a research assistant whose memory revises its beliefs as new evidence arrives.
+
+The theme asks *"Where's my context?"* FALSIFY's answer: the context isn't lost — it was **wrong**, and the AI should *revise* it, not blindly recall it.
+
+---
+
+## Future Work
+
+- **Confidence-weighted partial refutation** — decay a Conclusion's confidence continuously instead of a binary alive/invalidated flip.
+- **Multi-hop evidence provenance UI** — click any node to trace the full chain of *why it lives or died*.
+- **Automated evidence ingestion** — stream documents in and let the two-gate detector surface contradictions proactively.
+- **Human-in-the-loop review** — queue borderline LLM verdicts (0.4–0.6 confidence) for analyst confirmation before cascading.
+- **Belief-diff export** — a git-style diff of the belief graph between any two epochs.
+- **Neo4j / Postgres backends** — swap the graph engine for a distributed store with no code change (Cognee adapter interface).
+
+---
+
+## Acknowledgments
+
+- **[Cognee](https://github.com/topoteretes/cognee)** — the open-source AI memory platform FALSIFY is built on. Its truth-state graph APIs, custom `memify` pipeline, and self-hosted defaults made belief revision possible without a single external service.
+- **[WeMakeDevs](https://wemakedevs.org/)** — for hosting *The Hangover Part AI* hackathon and championing open-source builders.
+
+---
+
+<div align="center">
+
+**FALSIFY — the AI that revises, not forgets.**
+
+</div>

cognee-hackathon-project-main/REQUIREMENTS.md

@@ -0,0 +1,393 @@
+# FALSIFY — Requirements & Build Contract
+
+> **Tagline:** Drop one contradicting fact; watch dependent conclusions die and a losing hypothesis rise — permanently, across sessions.
+
+FALSIFY is a belief-revision research copilot. It treats a research inquiry as a **living belief graph** (not a chat log). When new evidence contradicts an existing evidence node, FALSIFY performs **belief revision**: it flips the contradicted evidence to `refuted`, propagates the refutation **forward** through the dependency chain, marks every dependent conclusion invalid, promotes the best surviving hypothesis, and **surgically forgets** the orphaned dead-ends. The refutation is written to graph node truth-state so the **next session's `recall()` skips killed branches** — while a plain-RAG baseline still cites the stale fact.
+
+This document is the **contract** for all downstream build agents. Every API named here has been verified against the read-only reference at `/workspaces/cognee`. Line references are cited where load-bearing.
+
+---
+
+## 0. Verified Cognee API Surface (grep-confirmed)
+
+| API | Exact import / call | Location (reference, read-only) |
+|---|---|---|
+| `Task` | `from cognee.modules.pipelines.tasks.task import Task` **(lowercase module `task`)** | `cognee/modules/pipelines/tasks/task.py` |
+| `memify` | `import cognee; await cognee.memify(extraction_tasks=[...], enrichment_tasks=[...], data=..., node_type=NodeSet, node_name=[...])` | `cognee/modules/memify/memify.py:26` |
+| `remember` | `await cognee.remember(data, dataset_name=..., session_id=...)` | `cognee/api/v1/remember/remember.py:623` |
+| `recall` | `await cognee.recall(query_text, query_type=..., session_id=..., top_k=...)` | `cognee/api/v1/recall/recall.py:361` |
+| `improve` | `await cognee.improve(...)` | `cognee/api/v1/improve/improve.py:36` |
+| `forget` | `await cognee.forget(...)` | `cognee/api/v1/forget/forget.py:16` |
+| `get_graph_engine` | `from cognee.infrastructure.databases.graph import get_graph_engine` → `ge = await get_graph_engine()` **(async)** | `cognee/infrastructure/databases/graph/get_graph_engine.py:110` |
+| `get_vector_engine` | `from cognee.infrastructure.databases.vector import get_vector_engine` → `ve = get_vector_engine()` **(sync)** | `cognee/infrastructure/databases/vector/get_vector_engine.py:44` |
+| `DataPoint`, `Embeddable`, `Dedup`, `LLMContext` | `from cognee.infrastructure.engine import DataPoint, Embeddable, LLMContext, Dedup` | `cognee/infrastructure/engine/models/DataPoint.py:27` |
+| `LLMGateway` | `from cognee.infrastructure.llm.LLMGateway import LLMGateway` | `cognee/infrastructure/llm/LLMGateway.py:52` |
+
+### Graph engine methods (verified in `graph_db_interface.py` + `ladybug/adapter.py`)
+
+```python
+ge = await get_graph_engine()
+
+# Forward traversal — THE propagation rail. Returns (nodes, edges).
+nodes, edges = await ge.get_neighborhood(node_ids: List[str], depth: int = 1, edge_types: Optional[List[str]] = None)
+#   graph_db_interface.py:303 ; ladybug/adapter.py:2068
+
+# Immediate neighbors of ONE node. Returns List[Tuple[source_props, edge_props, target_props]].
+conns = await ge.get_connections(node_id: Union[str, UUID])
+#   graph_db_interface.py:289 ; ladybug/adapter.py:1859
+
+# Truth-state: the alive/dead flag recall() filters on. PERSISTS across restart.
+await ge.set_node_truth_state({node_id: {"truth_alignment": ["refuted"], "truth_epoch": N}})
+state = await ge.get_node_truth_state(node_ids: List[str])
+#   graph_db_interface.py:357,364 ; ladybug impl 1687,1712 ; writes props "truth_alignment" (list) + "truth_epoch" (int) — adapter.py:1576-1578
+
+# Confidence / health signal.
+await ge.set_node_feedback_weights({node_id: 0.9})   # graph_db_interface.py:348
+w = await ge.get_node_feedback_weights(node_ids)     # graph_db_interface.py:341
+
+# Edges.
+await ge.add_edge(from_node: str, to_node: str, relationship_name: str, edge_properties: Dict = {})  # ladybug/adapter.py:1222
+
+# Surgical delete.
+await ge.delete_nodes(node_ids: List[str])           # graph_db_interface.py:102 ; ladybug 1042
+```
+
+### Vector engine methods (verified in `LanceDBAdapter.py`)
+
+```python
+ve = get_vector_engine()
+hits = await ve.search(collection_name: str, query_text: str = None, limit: int = 15, include_payload: bool = False, ...)
+#   LanceDBAdapter.py:992  — each hit exposes `.id`, `.score` (COSINE DISTANCE, lower = closer), `.payload`
+await ve.delete_data_points(collection_name: str, data_point_ids: List[UUID])
+#   vector_db_interface.py:160 ; LanceDBAdapter.py:1106
+```
+
+### LLMGateway (verified `LLMGateway.py:59`)
+
+```python
+# STATIC method — do NOT instantiate. Returns a coroutine; await it.
+result = await LLMGateway.acreate_structured_output(
+    text_input="A(...): <claim>\nB(...): <claim>",
+    system_prompt="skeptical analyst ...",
+    response_model=ContradictionJudgement,   # a pydantic BaseModel
+)
+```
+
+### DataPoint subclass pattern (verified `Tool.py`)
+
+```python
+from typing import Annotated
+from cognee.infrastructure.engine import DataPoint, Embeddable, Dedup
+
+class Hypothesis(DataPoint):
+    statement: Annotated[str, Embeddable(), Dedup()]
+    question_id: str
+    # identity_fields in metadata dedups nodes across sessions (see §2.4)
+    metadata: dict = {"index_fields": ["statement"], "identity_fields": ["question_id", "statement"]}
+```
+
+> **NOTE for implementers:** The FALSIFY spec screenshot wrote `Task(...)` imported from `pipelines.tasks.Task`. The **correct verified path is lowercase** `cognee.modules.pipelines.tasks.task` (class name `Task`). Use that. `get_graph_engine` is `await`-ed; `get_vector_engine` is **not**.
+
+---
+
+## 1. Core Mechanism
+
+### 1.1 Node & edge vocabulary (see §2 for full model)
+
+- Nodes: `InvestigationQuestion` (root), `Hypothesis`, `Evidence`, `Conclusion`.
+- Edges (relationship_name string on `add_edge`):
+  - `depends_on` : **Conclusion → Evidence** — *THE forward-propagation rail.* A Conclusion `depends_on` the Evidence it rests on. `edge_properties = {"critical": bool}`.
+  - `supports` : **Evidence → Hypothesis** — evidence corroborates a hypothesis. `edge_properties = {"weight": float}`.
+  - `refutes` : **Evidence → Hypothesis** — evidence contradicts a hypothesis. `edge_properties = {"weight": float}`.
+  - `supersedes` : **Evidence(new) → Evidence(old)** — written when the new fact back-dates / overrides an old evidence node. `edge_properties = {"confidence": float}`.
+
+### 1.2 Truth-state lifecycle
+
+`truth_alignment` is a list written to the node via `set_node_truth_state`. FALSIFY uses these canonical single-element states:
+
+```
+alive       — default; node participates in recall context
+refuted      — Evidence directly contradicted by a newer fact (entry point of a cascade)
+superseded   — Evidence/Hypothesis replaced by a newer competing node (still exists, demoted)
+invalidated  — Conclusion whose supporting Evidence chain was refuted (forward-cascade victim)
+forgotten    — orphaned dead-end scheduled for surgical delete (transient; node then removed)
+```
+
+Transition rules:
+
+```
+alive --(new fact contradicts this Evidence, LLM-confirmed)--> refuted
+alive --(a competing Evidence supersedes it)---------------> superseded
+Conclusion.alive --(any critical depends_on Evidence is refuted)--> invalidated
+{refuted|invalidated} node with NO surviving alive dependent/consumer --> forgotten --> delete_nodes + delete_data_points
+Hypothesis.alive --(its only supporting Evidence became refuted AND a rival Hypothesis has surviving support)--> superseded
+losing Hypothesis' rival --(gains the strongest surviving support)--> stays alive, feedback_weight promoted
+```
+
+Every state write also bumps `truth_epoch` to a monotonically increasing integer (epoch = the memify run counter). Recall filters on `truth_alignment` containing `"alive"`.
+
+### 1.3 Contradiction detection (two-gate, deterministic-first)
+
+The detector runs inside the `propagate_refutation` extraction/enrichment task. **Two gates** to kill nondeterminism:
+
+1. **Vector prefilter (cheap, deterministic).** `hits = await ve.search("Evidence_claim", query_text=NEW_FACT, limit=5, include_payload=True)`. Candidates = hits with **cosine distance `score < 0.35`** (topically related — same subject). This narrows the LLM to plausibly-conflicting evidence only. Contradictory claims sometimes embed far apart, so claims MUST be normalized to `subject + predicate` phrasing at ingest, and `limit` kept ≥5.
+2. **LLM adjudication (semantic).** For each candidate, call `LLMGateway.acreate_structured_output` with a **skeptical-analyst** system prompt and `response_model=ContradictionJudgement` (below). Only a verdict of `contradicts` (or `supersedes`) with `confidence ≥ 0.6` triggers refutation. This distinguishes *genuine contradiction* ("report was back-dated") from *topical overlap* ("also mentions the report").
+
+```python
+class ContradictionJudgement(BaseModel):
+    relation: Literal["contradicts", "supersedes", "supports", "unrelated"]
+    confidence: float  # 0..1
+    rationale: str
+```
+
+**`--demo` / `DEMO_MODE` override:** when set, the seeded contradiction's target evidence id is pinned (`REFUTED_ID` env / seed constant), so the cascade runs on real graph APIs even if the LLM judge stalls or the key is flaky. This is the non-negotiable demo safety net.
+
+### 1.4 Forward refutation propagation (exact algorithm)
+
+Entry: an Evidence node `E` confirmed `refuted` (§1.3).
+
+```
+1. set_node_truth_state({E.id: {"truth_alignment": ["refuted"], "truth_epoch": epoch}})
+   set_node_feedback_weights({E.id: 0.0})
+
+2. FORWARD CLOSURE — reverse-BFS along depends_on (Conclusion --depends_on--> Evidence).
+   Seeds = [E.id]. Traverse edges of type ["depends_on", "supersedes"] via:
+       nodes, edges = await ge.get_neighborhood([E.id], depth=4, edge_types=["depends_on", "supports"])
+   Collect every Conclusion C where a `depends_on` edge points from C into the refuted set
+   (transitively, up to depth 4). Because depends_on is Conclusion→Evidence, the "dependents"
+   are the SOURCES of those edges. A Conclusion is invalidated iff at least one of its
+   `critical: true` depends_on edges targets a refuted/invalidated node.
+
+3. For each invalidated Conclusion C:
+       set_node_truth_state({C.id: {"truth_alignment": ["invalidated"], "truth_epoch": epoch}})
+       set_node_feedback_weights({C.id: 0.0})
+
+4. PROMOTE competing hypothesis (promote_competing_hypothesis task):
+   - Find the Hypothesis H_dead whose only supporting Evidence is now refuted.
+       set_node_truth_state({H_dead.id: {"truth_alignment": ["superseded"], "truth_epoch": epoch}})
+   - Among rival Hypotheses still holding ≥1 alive `supports` Evidence, pick the one with the
+     highest summed support weight (read edge {"weight"}). Promote it:
+       set_node_feedback_weights({H_win.id: <boosted>})  # stays alive; becomes new frontier
+
+5. RECORD new fact + supersedes edge (add_data_points dual-write):
+   - Materialize NEW_FACT as an Evidence DataPoint, add via add_data_points (writes graph + vector).
+   - add_edge(new_evidence.id, E.id, "supersedes", {"confidence": verdict.confidence})
+```
+
+**Direction summary:** refutation flows *from Evidence up to the Conclusions that depend on it* by walking `depends_on` edges backward (Conclusion is the edge source). Hypotheses are re-scored via their `supports`/`refutes` edges. No forward walk ever crosses a `supersedes` edge into an already-superseded node (prevents loops — see §4).
+
+### 1.5 forget() orphan conditions (surgical delete)
+
+`forget_orphan_deadends()` runs after propagation and grows a **death set** by traversal:
+
+```
+A node is FORGOTTEN (hard-deleted from graph + vector) iff ALL hold:
+  (a) its truth_alignment is refuted OR invalidated (never alive/superseded — superseded nodes
+      are kept as provenance), AND
+  (b) it has NO surviving consumer: no alive node reaches it via depends_on/supports
+      (checked with get_connections — _has_alive_alternative == False), AND
+  (c) it is not itself the target of a supersedes edge FROM an alive node (that node is the
+      provenance anchor of the new truth and must be retained).
+
+Nodes that STILL feed a live node are retained even if refuted (partial refutation, §4).
+```
+
+Delete implementation (one shot per node batch):
+```python
+await ge.delete_nodes([str(id) for id in death_set])
+await ve.delete_data_points("Evidence_claim", [evidence_ids_in_death_set])
+await ve.delete_data_points("Conclusion_statement", [conclusion_ids_in_death_set])
+```
+
+> Provenance is kept: only *truly orphaned* dead-ends are hard-deleted. `refuted`/`superseded` nodes that still explain *why* the graph changed remain, carrying their state flag.
+
+### 1.6 Cross-session persistence (the proof)
+
+Truth-state is stored **on the node** in the graph DB (Ladybug/SQLite-backed), so it survives process restart. Session 2's `recall()` reads only `truth_alignment == alive` context. A parallel **plain-RAG baseline** (`recall(query_type=SearchType.RAG_COMPLETION)` or direct `ve.search`) does NOT read truth-state and re-cites the deleted/stale fact — this A/B is the scoreboard.
+
+---
+
+## 2. Data Model
+
+### 2.1 Node DataPoint subclasses (`memory_core/models.py`)
+
+| Class | Embeddable field | Other fields | Collection (auto) |
+|---|---|---|---|
+| `InvestigationQuestion` | `question: Annotated[str, Embeddable()]` | — | `InvestigationQuestion_question` |
+| `Hypothesis` | `statement: Annotated[str, Embeddable(), Dedup()]` | `question_id: str`, `status: str="alive"`, `prior: float` | `Hypothesis_statement` |
+| `Evidence` | `claim: Annotated[str, Embeddable(), Dedup()]` | `source_id: str`, `quote: str`, `stance: str` (`supports`/`refutes`), `asserted_at: str` (ISO date) | `Evidence_claim` (**the refutation entry point / vector prefilter target**) |
+| `Conclusion` | `statement: Annotated[str, Embeddable()]` | `confidence: float`, `depends_on_ids: list[str]` | `Conclusion_statement` |
+
+The collection name is `"{ClassName}_{embeddable_field}"` — auto-created on write. `Evidence_claim` is the collection the contradiction prefilter searches.
+
+### 2.2 Edge types (already listed §1.1)
+
+`depends_on` (Conclusion→Evidence, `{critical:bool}`), `supports`/`refutes` (Evidence→Hypothesis, `{weight:float}`), `supersedes` (Evidence→Evidence, `{confidence:float}`).
+
+### 2.3 Node-level metadata / state fields (written via engine APIs, not model fields)
+
+| Field | Written by | Meaning |
+|---|---|---|
+| `truth_alignment: list[str]` | `set_node_truth_state` | lifecycle state (§1.2). Recall filter key. |
+| `truth_epoch: int` | `set_node_truth_state` | monotonically increasing revision epoch. |
+| `feedback_weight: float` | `set_node_feedback_weights` | confidence/health (0.0 = dead, promoted hypotheses boosted). |
+| `asserted_at` (model field on Evidence) | ingest | timestamp used for supersede tie-breaks (`newer = max(asserted_at)`). |
+| `source_id` (model field) | ingest | provenance handle for the source document. |
+
+### 2.4 Dedup across sessions
+
+`Hypothesis` and `Evidence` set `identity_fields` in `metadata` (e.g. `["question_id","statement"]`). DataPoint generates a stable identity id from these (`DataPoint.py:76-81`), so re-adding the same belief in a later session updates the existing node instead of duplicating it — essential for cross-session refutation to land on the right node.
+
+---
+
+## 3. User / Demo Flow
+
+### 3.1 End-to-end story (money shot)
+
+> **Question:** *"Did Company X know about the defect before the recall?"*
+>
+> **Session 1** builds:
+> - Hypothesis **A**: "X knew via QA report, Mar 2021" (supported by Evidence `E_qa`)
+> - Hypothesis **B**: "X knew via supplier email, Jan 2021" (supported by Evidence `E_email`)
+> - Hypothesis **C**: "X didn't know" (unsupported)
+> - Conclusion **K**: "X knew by March 2021" — `depends_on(K → E_qa, critical=True)`
+>
+> Saved graph persists (survives restart).
+>
+> **Session 2** (reopened next day): analyst pastes ONE line — *"Forensic audit: the March QA report was back-dated."*
+> 1. `Evidence_claim` vector prefilter finds `E_qa` (distance < 0.35).
+> 2. LLM judge: `contradicts`, confidence 0.9.
+> 3. `E_qa → refuted`; **forward BFS** over `depends_on` finds **K** (critical dep) → `K invalidated`.
+> 4. **A** loses its only support → `A superseded`; **B** ignites as the new frontier (feedback_weight promoted) — in ~3s.
+> 5. `forget_orphan_deadends`: K is orphaned (no alive consumer) → hard-deleted from graph + vector. `E_qa` kept as `refuted` provenance (target of new fact's `supersedes` edge).
+> 6. **Scoreboard:** FALSIFY recall now answers via **B (Jan 2021)**; the **plain-RAG baseline still cites the back-dated March QA report.**
+
+### 3.2 Screen beat (≤30s, one screen)
+
+Force-graph shows A/B/C + K. Analyst pastes the fact → **E_qa flashes red → K crosses out and vanishes → A dims (superseded) → B glows green as new frontier.** A live scoreboard panel: `FALSIFY: "B — Jan 2021 (supplier email)"` vs `Plain RAG: "March 2021 QA report"` — captioned *"AI revised, not forgot."*
+
+### 3.3 Cross-session proof
+
+Restart the process (or run `main.py` a second time with `--session 2`). Because truth-state is on-node persisted, session 2's `recall()` never sees K or A-as-truth. Show the two recalls side by side.
+
+---
+
+## 4. Success Criteria
+
+### 4.1 Unit-test assertions (pytest)
+
+```
+test_direct_refutation:
+    after propagate_refutation(new_fact contradicting E_qa):
+    assert get_node_truth_state([E_qa])[E_qa]["truth_alignment"] == ["refuted"]
+
+test_forward_cascade_invalidates_conclusion:
+    assert get_node_truth_state([K])[K]["truth_alignment"] == ["invalidated"]
+
+test_competing_hypothesis_promoted:
+    assert A.truth_alignment == ["superseded"]
+    assert "alive" in B.truth_alignment
+    assert feedback_weight(B) > feedback_weight(A)
+
+test_orphan_forgotten_from_both_stores:
+    assert K.id NOT in (await ge has node)            # gone from graph
+    assert K.id NOT in ve.search("Conclusion_statement", ...)   # gone from vector
+
+test_provenance_kept:
+    assert E_qa still exists with truth_alignment == ["refuted"]   # NOT deleted (supersede anchor)
+
+test_cross_session_recall_skips_dead:
+    recall("did X know?") context contains B, does NOT contain K or A-as-truth
+
+test_baseline_still_stale:
+    RAG_COMPLETION / raw ve.search STILL returns the March QA claim   # proves the differentiator
+```
+
+### 4.2 Expected `python main.py` output (judges, ~2 min)
+
+```
+[FALSIFY] Session 1: built belief graph for "Did Company X know...?"
+          Hypotheses: A(QA Mar'21) B(email Jan'21) C(didn't know)
+          Conclusion K depends_on E_qa
+[FALSIFY] Session 2: new fact -> "March QA report was back-dated"
+          contradiction: E_qa  (judge=contradicts conf=0.90)
+          forward cascade: K invalidated
+          A superseded  ->  B ignites (new frontier)
+          forgot 1 orphan (K) from graph + vector
+[SCOREBOARD]
+   FALSIFY recall : X knew by Jan 2021 (supplier email)   [revised]
+   Plain-RAG      : X knew by Mar 2021 (QA report)         [STALE]
+```
+
+Graceful exit if no API key: print a clear message + how to set `LLM_API_KEY`, exit code **0**.
+
+### 4.3 Edge cases (must be handled)
+
+| Case | Required behavior |
+|---|---|
+| **Cycle** (A depends_on B depends_on A) | BFS tracks a `visited` set; never revisit. `supersedes` edges never traversed into already-superseded nodes. Termination guaranteed. |
+| **Multiple contradictions** (new fact refutes 2 Evidence nodes) | Each refuted independently; union of their dependent Conclusions invalidated; single forget pass over the merged death set. |
+| **Partial refutation** (Conclusion depends_on E_qa AND E_alt, both critical) | Conclusion invalidated only if a *critical* dep is refuted AND no alive critical alternative remains (`_has_alive_alternative`). If E_alt still alive & critical satisfied, Conclusion stays alive; E_qa refuted but **retained** (still feeds a live node → not orphaned). |
+| **Diamond dependency** (K depends_on E1,E2; E1,E2 both depends-chain to refuted E0) | Deduplicate via visited set so K is invalidated once, not twice; forget counts each node once. Explicit unit test required. |
+| **Non-critical dep refuted** | Conclusion's `confidence` decays but stays `alive` (only `critical:true` deps invalidate). |
+| **Contradiction judge false-positive risk** | Two-gate (vector `<0.35` + LLM `≥0.6`) + `--demo` pin. |
+
+---
+
+## 5. Tech Stack & Module Layout
+
+### 5.1 Cognee APIs used (all §0-verified)
+
+- Persistence: `cognee.remember(session_id=...)`, `cognee.recall(session_id=..., query_type=...)`.
+- Enrichment pipeline: `cognee.memify(extraction_tasks=[Task(collect_belief_subgraph)], enrichment_tasks=[Task(propagate_refutation), Task(promote_competing_hypothesis), Task(forget_orphan_deadends), Task(add_data_points)], data=[{}], node_type=NodeSet, node_name=[question_id])`.
+- Graph: `get_graph_engine()` → `get_neighborhood` (depth=4, edge_types=["depends_on","supports"]), `get_connections`, `set_node_truth_state`, `get_node_truth_state`, `set_node_feedback_weights`, `add_edge`, `delete_nodes`.
+- Vector: `get_vector_engine()` → `search("Evidence_claim", ...)`, `delete_data_points`.
+- LLM: `LLMGateway.acreate_structured_output(text_input, system_prompt, response_model=ContradictionJudgement)`.
+- Storage: `add_data_points` task (`cognee/tasks/storage/add_data_points.py:31`) for dual graph+vector write of the new fact.
+- Baseline: `SearchType.RAG_COMPLETION` (from `cognee/modules/search/types/SearchType.py`).
+
+### 5.2 Module layout (write under `/workspaces/hackathon-app/`)
+
+```
+/workspaces/hackathon-app/
+  main.py                      # `python main.py` entry — runs seed + demo + scoreboard; graceful no-key exit 0
+  requirements.txt / pyproject # deps: cognee (editable ref) + minimal
+  .env.template                # LLM_API_KEY, LLM_PROVIDER=openai, LLM_ENDPOINT (custom endpoint), LLM_MODEL, DEMO_MODE
+  memory_core/
+    __init__.py
+    models.py                  # DataPoint subclasses (§2.1) + ContradictionJudgement
+    edges.py                   # edge-name constants: DEPENDS_ON, SUPPORTS, REFUTES, SUPERSEDES
+    tasks.py                   # collect_belief_subgraph, propagate_refutation,
+                               #   promote_competing_hypothesis, forget_orphan_deadends
+    falsify.py                 # orchestration: build_graph(), revise(new_fact), scoreboard()
+    seed.py                    # demo corpus: Company-X recall investigation (A/B/C + K)
+  ui/
+    graph.html                 # react-force-graph (color by truth_state, red-flash-then-remove ripple ≤3s)
+    server.py                  # tiny static+JSON server feeding get_neighborhood snapshots
+  tests/
+    test_propagation.py        # §4.1 assertions
+    test_edge_cases.py         # cycle / diamond / partial / multi
+```
+
+### 5.3 Visualization approach
+
+- **react-force-graph** (CDN, single `graph.html`) reads a JSON snapshot built from `ge.get_neighborhood([question_id], depth=4)`.
+- Node color keyed on `truth_alignment`: alive=green, refuted=red, invalidated=grey-strikethrough, superseded=dim-amber. Forgotten nodes: **red-flash animation then removed** from the sim (≤3s ripple).
+- Scoreboard panel overlays FALSIFY-vs-RAG answers. No external services — server is stdlib/`http.server` or FastAPI already in cognee.
+
+### 5.4 Config / runtime constraints
+
+- OpenAI-compatible: honor `LLM_PROVIDER` (`openai` or `custom`), `LLM_ENDPOINT`, `LLM_MODEL`, `LLM_API_KEY`. Defaults: LanceDB (vector) + Ladybug (graph) + SQLite (relational) — **zero external services**.
+- `DEMO_MODE=1` (or `--demo`) pins `REFUTED_ID` so the cascade+forget run on real APIs regardless of LLM flakiness.
+- Never modify `/workspaces/cognee`. All writes under `/workspaces/hackathon-app/` (absolute paths).
+
+---
+
+## 6. Non-negotiables (contract invariants)
+
+1. Forward propagation uses `get_neighborhood` + `set_node_truth_state` (on-node, persistent). No in-memory-only state.
+2. Surgical forget deletes from **both** graph (`delete_nodes`) and vector (`delete_data_points`); provenance (`refuted`/`superseded`) nodes are retained.
+3. Cross-session persistence of disbelief is demonstrated (restart / session 2 recall skips dead branches).
+4. The A/B scoreboard (FALSIFY revised vs plain-RAG stale) is shown every run.
+5. Contradiction detection is two-gate (vector prefilter `<0.35` + LLM judge `≥0.6`) with a `--demo` deterministic override.
+6. `Task` imported from `cognee.modules.pipelines.tasks.task` (lowercase); `get_graph_engine` awaited, `get_vector_engine` not.

cognee-hackathon-project-main/demo_video_script.md

@@ -0,0 +1,62 @@
+# FALSIFY — 30-second demo script
+
+A tight, judge-ready narration. Total runtime ~30s of talking over one `python main.py --demo` run. Capture the terminal + the `output/graph.html` for the GIF.
+
+---
+
+## Setup (before recording)
+- Terminal with a dark theme, font large enough to read on playback.
+- `.env` has a working `LLM_API_KEY` (so embeddings + recall are real).
+- Run once beforehand to warm caches; record the second run.
+
+---
+
+## Beat sheet
+
+**[0:00–0:05] The hook**
+> "Every AI memory demo fixes *forgetting*. FALSIFY fixes something worse — an AI that confidently remembers a fact that's been **proven false**."
+
+*Run:* `python main.py --demo`
+
+**[0:05–0:12] Session 1 — the belief graph**
+> "We're investigating: *did Company X know about the defect before the recall?* Two hypotheses — a March QA report, and a January supplier email. A conclusion rests on that March report."
+
+*On screen:* the **BEFORE** panel — every node tagged `ALIVE` in green.
+
+**[0:12–0:20] Session 2 — one contradicting fact**
+> "Now one line arrives: *a forensic audit found the March report was back-dated.* Watch."
+
+*On screen:* the revision log —
+```
+✗ refuted: 1 evidence node
+✗ invalidated: 1 conclusion
+hypothesis A → ↓ superseded
+hypothesis B → ↑ promoted (new frontier)
+🗑 forgotten: Company X knew about the defect by March 2021
+```
+
+**[0:20–0:27] The AFTER + scoreboard**
+> "The March evidence is red. The conclusion built on it collapsed and was **surgically deleted** — from the graph *and* the vector store. Hypothesis B ignites as the new answer."
+
+*On screen:* the **SCOREBOARD** —
+```
+FALSIFY : X knew by Jan 2021 (supplier email)      ← revised
+RAG     : X knew by Mar 2021 (QA report)  [STALE]  ← still cites the refuted fact
+```
+
+**[0:27–0:30] The close**
+> "Same store, same query. FALSIFY revised its belief and the disbelief persists across sessions. Plain RAG can't. **AI revised, not forgot.**"
+
+*On screen:* open `output/graph.html` — the red refuted node, the missing orphan, the green frontier.
+
+---
+
+## The single most important line
+> **"It's not that the AI forgot where the context was — the context was *wrong*, and FALSIFY revised it."**
+
+That reframes the hackathon's "Where's My Context?" theme into FALSIFY's exact contribution.
+
+---
+
+## If asked "why can't RAG do this?"
+> "Refutation is graph traversal over typed edges — *this fact grounds that conclusion three hops away.* A vector index has no edges to walk and no truth-state to filter on. This needs a knowledge graph — which is exactly what Cognee gives us."

cognee-hackathon-project-main/falsify/__init__.py

@@ -0,0 +1,57 @@
+"""
+FALSIFY — Belief Revision Research Copilot
+
+Exposes core models and edge constants for the belief graph.
+
+Import-time environment safety
+------------------------------
+FALSIFY is a single-user, self-hosted demo. We set a few Cognee defaults *before*
+any Cognee module is imported (importing :mod:`falsify.models` pulls in Cognee), so
+that graph writes go into one shared local graph without per-user access-control
+gymnastics. ``setdefault`` means an explicitly-exported env var always wins.
+"""
+
+import os as _os
+
+# Single-user mode: shared local DBs, auth off. Must precede the first cognee import.
+_os.environ.setdefault("ENABLE_BACKEND_ACCESS_CONTROL", "False")
+# Keep logs quiet unless the user opts in.
+_os.environ.setdefault("LOG_LEVEL", "ERROR")
+_os.environ.setdefault("COGNEE_LOG_FILE", "false")
+# Enable the session cache so remember(session_id=...) / improve() work (cross-session proof).
+_os.environ.setdefault("CACHING", "true")
+_os.environ.setdefault("CACHE_BACKEND", "fs")
+# Default embeddings to fastembed — a fully local, CPU-only, zero-cost embedder, so
+# the whole pipeline (and `python main.py --demo`) runs with NO external API key.
+# Any explicit EMBEDDING_* in the environment / .env overrides these (setdefault).
+_os.environ.setdefault("EMBEDDING_PROVIDER", "fastembed")
+_os.environ.setdefault("EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5")
+_os.environ.setdefault("EMBEDDING_DIMENSIONS", "384")
+_os.environ.setdefault("EMBEDDING_MAX_TOKENS", "512")
+
+from falsify.models import (
+    Assertion,
+    Conclusion,
+    Evidence,
+    Hypothesis,
+    InvestigationQuestion,
+    TruthState,
+    # Edge relationship constants
+    CONTRADICTS,
+    DEPENDS_ON,
+    SUPPORTS,
+    SUPERSEDES,
+)
+
+__all__ = [
+    "TruthState",
+    "InvestigationQuestion",
+    "Hypothesis",
+    "Evidence",
+    "Conclusion",
+    "Assertion",
+    "DEPENDS_ON",
+    "SUPPORTS",
+    "CONTRADICTS",
+    "SUPERSEDES",
+]

cognee-hackathon-project-main/falsify/edges.py

@@ -0,0 +1,70 @@
+"""
+Edge relationship-name constants for the FALSIFY belief graph.
+
+These strings are passed as ``relationship_name`` to ``graph_engine.add_edge(...)``
+and used as ``edge_types`` filters in ``get_neighborhood(...)``. They are re-exported
+from :mod:`falsify.models` as well; this module is the single source of truth.
+
+Edge semantics (see REQUIREMENTS.md §1.1)
+-----------------------------------------
+- ``DEPENDS_ON`` : Conclusion -> Evidence. THE forward-propagation rail. A Conclusion
+  depends on the Evidence it rests on. ``edge_properties = {"critical": bool}``.
+- ``SUPPORTS``   : Evidence -> Hypothesis. Evidence corroborates a hypothesis.
+  ``edge_properties = {"weight": float}``.
+- ``REFUTES``    : Evidence -> Hypothesis. Evidence contradicts a hypothesis.
+  ``edge_properties = {"weight": float}``.
+- ``SUPERSEDES`` : Evidence(new) -> Evidence(old). Written when a new fact back-dates /
+  overrides an old evidence node. ``edge_properties = {"confidence": float}``.
+"""
+
+DEPENDS_ON = "depends_on"
+# Non-critical dependency variant. Criticality is encoded in the relationship NAME
+# because some graph backends (e.g. Ladybug) do not round-trip edge *properties* —
+# a name always persists, an edge property may not. So a plain ``depends_on`` edge is
+# treated as critical by default, and ``depends_on_soft`` is the explicit non-critical
+# form. (For in-memory/tests, an explicit ``{"critical": bool}`` property still wins.)
+DEPENDS_ON_SOFT = "depends_on_soft"
+SUPPORTS = "supports"
+REFUTES = "refutes"
+# ``CONTRADICTS`` kept as an alias for the refutes edge (spec used both names).
+CONTRADICTS = REFUTES
+SUPERSEDES = "supersedes"
+
+#: All dependency edge relationship names (critical + soft).
+DEPENDENCY_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT]
+
+#: Edge types traversed when checking whether a node still feeds a live consumer.
+CONSUMER_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT, SUPPORTS]
+
+
+def is_critical_dependency(rel: str, props: dict | None = None) -> bool:
+    """Return whether a dependency edge is *critical*.
+
+    An explicit ``critical`` edge property wins when present (used by in-memory tests).
+    Otherwise criticality is inferred from the relationship name: ``depends_on`` is
+    critical by default, ``depends_on_soft`` is not. This makes correctness independent
+    of whether the backend persists edge properties.
+    """
+    props = props or {}
+    if "critical" in props:
+        return bool(props["critical"])
+    if rel == DEPENDS_ON_SOFT:
+        return False
+    return rel == DEPENDS_ON  # depends_on => critical by default
+
+
+# Edge types traversed during forward refutation propagation.
+PROPAGATION_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT, SUPPORTS]
+
+__all__ = [
+    "DEPENDS_ON",
+    "DEPENDS_ON_SOFT",
+    "SUPPORTS",
+    "REFUTES",
+    "CONTRADICTS",
+    "SUPERSEDES",
+    "DEPENDENCY_EDGE_TYPES",
+    "CONSUMER_EDGE_TYPES",
+    "PROPAGATION_EDGE_TYPES",
+    "is_critical_dependency",
+]

cognee-hackathon-project-main/falsify/falsify.py

@@ -0,0 +1,240 @@
+"""
+FALSIFY orchestration — the belief-revision copilot's public API.
+
+Three verbs tie the engine together:
+
+    build_graph()          -> seed the Session-1 investigation graph (clean slate).
+    revise(new_fact)       -> run the full revision pipeline for an incoming fact:
+                              detect -> propagate -> promote -> record supersede -> forget.
+    scoreboard(question)   -> the money shot: FALSIFY's revised answer (reads truth
+                              state, skips dead branches) vs a plain-RAG baseline
+                              (raw vector search, no truth filter) that still cites the
+                              refuted fact.
+
+Everything is persisted on the graph (truth-state on nodes), so a fresh process /
+second session sees the revised beliefs — the cross-session guarantee.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from falsify import graph_ops
+from falsify.edges import SUPERSEDES, SUPPORTS
+from falsify.models import Evidence, TruthState
+from falsify.seed import SeededGraph, build_investigation
+from falsify.tasks import (
+    Contradiction,
+    cascade_forget,
+    detect_contradictions,
+    promote_competing_hypothesis,
+    propagate_refutation,
+)
+
+logger = logging.getLogger("falsify.orchestrator")
+
+_ALIVE = TruthState.ALIVE.value
+_EVIDENCE_COLLECTION = "Evidence_claim"
+
+
+@dataclass
+class RevisionReport:
+    """Full record of one :func:`revise` run, for demo output and tests."""
+
+    new_fact: str
+    contradictions: List[Contradiction] = field(default_factory=list)
+    refuted: List[str] = field(default_factory=list)
+    invalidated: List[str] = field(default_factory=list)
+    hypothesis_actions: Dict[str, str] = field(default_factory=dict)
+    forgotten: List[str] = field(default_factory=list)
+    forgotten_labels: Dict[str, str] = field(default_factory=dict)
+    retained_provenance: List[str] = field(default_factory=list)
+    new_evidence_id: Optional[str] = None
+    epoch: int = 0
+
+    @property
+    def revised(self) -> bool:
+        """True if the fact actually triggered a belief change."""
+        return bool(self.refuted or self.invalidated)
+
+
+async def build_graph() -> SeededGraph:
+    """Prune everything and build the Session-1 investigation graph.
+
+    Returns the :class:`SeededGraph` with stable handles to the seeded nodes.
+    """
+    import cognee
+    from cognee.low_level import setup
+
+    logger.info("build_graph: pruning and seeding fresh investigation")
+    await cognee.forget(everything=True)
+    await setup()  # (re)create relational tables the storage pipeline needs
+    seeded = await build_investigation()
+    return seeded
+
+
+async def revise(
+    new_fact: str,
+    *,
+    pinned_target_id: Optional[str] = None,
+    source_id: str = "session2_fact",
+) -> RevisionReport:
+    """Run the full belief-revision pipeline for an incoming fact.
+
+    Pipeline (REQUIREMENTS §1.3-§1.5):
+        1. detect_contradictions -> which evidence does the fact contradict?
+        2. propagate_refutation  -> refute it; cascade invalidation forward.
+        3. promote_competing_hypothesis -> demote the losing hypothesis, ignite the rival.
+        4. record the new fact as Evidence + a ``supersedes`` edge to the refuted node
+           (so the refuted node is retained as a provenance tombstone).
+        5. cascade_forget -> hard-delete orphaned dead-ends from graph + vector.
+
+    Args:
+        new_fact: the incoming claim.
+        pinned_target_id: demo override — refute this evidence id deterministically.
+        source_id: provenance id for the materialized new-fact Evidence node.
+
+    Returns:
+        A :class:`RevisionReport` describing everything that changed.
+    """
+    report = RevisionReport(new_fact=new_fact)
+
+    # 1) detect
+    contradictions = await detect_contradictions(new_fact, pinned_target_id=pinned_target_id)
+    report.contradictions = contradictions
+    if not contradictions:
+        logger.info("revise: no contradiction found; graph unchanged")
+        return report
+
+    target_ids = [c.target_id for c in contradictions]
+
+    # 2) propagate
+    prop = await propagate_refutation(target_ids)
+    report.refuted = prop.refuted
+    report.invalidated = prop.invalidated
+    report.epoch = prop.epoch
+
+    # 3) promote competing hypothesis
+    report.hypothesis_actions = await promote_competing_hypothesis(target_ids, prop.epoch)
+
+    # 4) record the new fact + supersedes edge (keeps the refuted node as provenance)
+    report.new_evidence_id = await _record_new_fact(new_fact, contradictions, source_id)
+
+    # 5) forget orphaned dead-ends
+    forget_res = await cascade_forget(prop.affected)
+    report.forgotten = forget_res.forgotten
+    report.forgotten_labels = forget_res.labels
+    report.retained_provenance = forget_res.retained_provenance
+
+    logger.info(
+        "revise complete: refuted=%d invalidated=%d forgotten=%d",
+        len(report.refuted), len(report.invalidated), len(report.forgotten),
+    )
+    return report
+
+
+async def _record_new_fact(
+    new_fact: str,
+    contradictions: List[Contradiction],
+    source_id: str,
+) -> Optional[str]:
+    """Materialize the new fact as an Evidence node and link supersedes edges.
+
+    The new (alive) evidence ``supersedes`` each refuted evidence node. This both
+    records provenance and pins the refuted node as a retained tombstone (an alive
+    supersedes-source protects its target from forget — REQUIREMENTS §1.5c).
+    """
+    from cognee.tasks.storage import add_data_points
+
+    try:
+        new_ev = Evidence(
+            claim=new_fact,
+            source_id=source_id,
+            stance="refutes",
+            confidence=max((c.confidence for c in contradictions), default=0.9),
+        )
+        await add_data_points([new_ev])
+        for c in contradictions:
+            await graph_ops.add_edge(
+                str(new_ev.id), str(c.target_id), SUPERSEDES, {"confidence": c.confidence}
+            )
+        logger.info("recorded new fact %s superseding %d node(s)", new_ev.id, len(contradictions))
+        return str(new_ev.id)
+    except Exception as exc:
+        logger.error("failed to record new fact: %s", exc)
+        return None
+
+
+@dataclass
+class Scoreboard:
+    """The FALSIFY-vs-RAG comparison shown every run."""
+
+    question: str
+    falsify_answer: str
+    falsify_support: List[str] = field(default_factory=list)
+    rag_answer: str = ""
+    rag_citations: List[str] = field(default_factory=list)
+    stale: bool = False  # True if RAG still cites a refuted node FALSIFY dropped
+
+
+async def scoreboard(question: str, seeded: Optional[SeededGraph] = None) -> Scoreboard:
+    """Compare FALSIFY's revised answer against a plain-RAG baseline.
+
+    FALSIFY answer: derived from the graph, reading truth-state and using only
+    hypotheses/evidence still ``alive`` (the promoted frontier hypothesis).
+
+    RAG baseline: a raw vector search over ``Evidence_claim`` with **no** truth
+    filter — so it still returns evidence FALSIFY has refuted, and cites the stale
+    fact. This asymmetry is the demo's whole point.
+    """
+    board = Scoreboard(question=question, falsify_answer="(no surviving hypothesis)")
+
+    # ---- FALSIFY: alive-filtered graph answer ----
+    nodes, edges = await graph_ops.load_graph()
+    node_ids = [nid for nid, _p in nodes]
+    truth = await graph_ops.get_truth(node_ids)
+    props_by_id = {str(nid): (p or {}) for nid, p in nodes}
+
+    # The winning hypothesis = alive hypothesis with the most alive supporting evidence weight.
+    best_hyp, best_score = None, -1.0
+    support_edges = [(s, d, p) for (s, d, r, p) in edges if r == SUPPORTS]
+    for nid, props in nodes:
+        nid = str(nid)
+        if "statement" not in props:  # crude: hypotheses/conclusions carry 'statement'
+            continue
+        if _ALIVE not in truth.get(nid, [_ALIVE]):
+            continue
+        score = 0.0
+        alive_support = []
+        for (src, dst, ep) in support_edges:
+            if str(dst) != nid:
+                continue
+            if _ALIVE in truth.get(str(src), [_ALIVE]):
+                score += float(ep.get("weight", 0.5))
+                alive_support.append(graph_ops.node_label(props_by_id.get(str(src), {})))
+        if alive_support and score > best_score:
+            best_hyp, best_score = nid, score
+            board.falsify_answer = graph_ops.node_label(props)
+            board.falsify_support = alive_support
+
+    # ---- RAG baseline: raw vector search, no truth filter ----
+    ve = graph_ops.get_vector_engine()
+    try:
+        hits = await ve.search(_EVIDENCE_COLLECTION, query_text=question, limit=5, include_payload=True)
+    except Exception as exc:
+        logger.warning("RAG baseline search failed: %s", exc)
+        hits = []
+
+    refuted_ids = {nid for nid in node_ids if TruthState.REFUTED.value in truth.get(str(nid), [])}
+    for h in (hits or []):
+        payload = getattr(h, "payload", {}) or {}
+        text = payload.get("claim") or payload.get("text") or graph_ops.node_label(payload)
+        board.rag_citations.append(str(text))
+        if str(h.id) in refuted_ids:
+            board.stale = True
+    board.rag_answer = board.rag_citations[0] if board.rag_citations else "(no vector hits)"
+
+    logger.info("scoreboard: falsify=%r stale_rag=%s", board.falsify_answer, board.stale)
+    return board

cognee-hackathon-project-main/falsify/graph_ops.py

@@ -0,0 +1,185 @@
+"""
+Low-level graph operations for FALSIFY.
+
+This module is the single, verified surface between FALSIFY's belief logic and
+Cognee's graph/vector engines. Every engine call used elsewhere in the project goes
+through a helper here, so the (few) places that touch Cognee internals are auditable.
+
+Verified Cognee API shapes (grep-confirmed against /workspaces/cognee — see REQUIREMENTS.md §0):
+
+    ge = await get_graph_engine()                     # ASYNC factory
+    nodes, edges = await ge.get_graph_data()          # ([(id, props)], [(src, dst, rel, props)])
+    nodes, edges = await ge.get_neighborhood(ids, depth=, edge_types=)
+    await ge.add_edge(from_node, to_node, relationship_name, edge_properties={})
+    await ge.set_node_truth_state({id: {"truth_alignment": [...], "truth_epoch": N}})
+    state = await ge.get_node_truth_state([ids])      # {id: {"truth_alignment": [...], ...}}
+    await ge.set_node_feedback_weights({id: 0.0})
+    await ge.delete_nodes([ids])
+
+    ve = get_vector_engine()                          # SYNC factory
+    await ve.delete_data_points(collection_name, [uuids])
+    hits = await ve.search(collection_name, query_text=, limit=, include_payload=)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from cognee.infrastructure.databases.graph import get_graph_engine
+from cognee.infrastructure.databases.vector import get_vector_engine
+
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.graph_ops")
+
+# A parsed edge: (source_id, target_id, relationship_name, properties)
+Edge = Tuple[str, str, str, Dict[str, Any]]
+# A parsed node: (node_id, properties)
+GraphNode = Tuple[str, Dict[str, Any]]
+
+
+async def load_graph() -> Tuple[List[GraphNode], List[Edge]]:
+    """Return the full graph as ``(nodes, edges)``.
+
+    Nodes are ``(id, props)`` tuples; edges are ``(src, dst, rel, props)`` tuples.
+    IDs are normalized to ``str`` so they can be used as dict keys regardless of
+    whether the adapter returns ``UUID`` or ``str``.
+    """
+    ge = await get_graph_engine()
+    raw_nodes, raw_edges = await ge.get_graph_data()
+
+    nodes: List[GraphNode] = [(str(nid), props or {}) for nid, props in raw_nodes]
+
+    edges: List[Edge] = []
+    for e in raw_edges:
+        # Adapters return 4-tuples (src, dst, rel, props); be defensive about arity.
+        if len(e) >= 4:
+            src, dst, rel, props = e[0], e[1], e[2], e[3]
+        elif len(e) == 3:
+            src, dst, rel, props = e[0], e[1], e[2], {}
+        else:  # pragma: no cover - unexpected adapter shape
+            continue
+        edges.append((str(src), str(dst), str(rel), props or {}))
+    return nodes, edges
+
+
+async def get_truth(node_ids: List[str]) -> Dict[str, List[str]]:
+    """Return ``{node_id: truth_alignment_list}`` for the given ids.
+
+    A node with no stored truth state is treated as ``["alive"]`` (the default).
+    """
+    if not node_ids:
+        return {}
+    ge = await get_graph_engine()
+    ids = [str(n) for n in node_ids]
+    try:
+        raw = await ge.get_node_truth_state(ids)
+    except Exception as exc:  # adapter may not have state yet
+        logger.debug("get_node_truth_state failed (%s); defaulting to alive", exc)
+        raw = {}
+    out: Dict[str, List[str]] = {}
+    for nid in ids:
+        entry = (raw or {}).get(nid) or (raw or {}).get(str(nid))
+        alignment = (entry or {}).get("truth_alignment") if entry else None
+        out[nid] = list(alignment) if alignment else [TruthState.ALIVE.value]
+    return out
+
+
+async def is_alive(node_id: str) -> bool:
+    """True iff the node's truth_alignment currently contains ``alive``."""
+    state = await get_truth([str(node_id)])
+    return TruthState.ALIVE.value in state.get(str(node_id), [TruthState.ALIVE.value])
+
+
+async def set_state(node_id: str, state: TruthState, epoch: int) -> None:
+    """Persist ``truth_alignment=[state]`` + ``truth_epoch=epoch`` on a node.
+
+    Truth state is stored ON the graph node, so it survives a process restart — the
+    basis of FALSIFY's cross-session persistence guarantee.
+    """
+    ge = await get_graph_engine()
+    value = state.value if isinstance(state, TruthState) else str(state)
+    try:
+        await ge.set_node_truth_state(
+            {str(node_id): {"truth_alignment": [value], "truth_epoch": int(epoch)}}
+        )
+    except Exception as exc:
+        logger.error("set_node_truth_state failed for %s -> %s: %s", node_id, value, exc)
+        raise
+
+
+async def set_weight(node_id: str, weight: float) -> None:
+    """Set a node's feedback weight (confidence/health signal). Best-effort."""
+    ge = await get_graph_engine()
+    try:
+        await ge.set_node_feedback_weights({str(node_id): float(weight)})
+    except Exception as exc:  # non-fatal: weight is a secondary signal
+        logger.debug("set_node_feedback_weights failed for %s: %s", node_id, exc)
+
+
+async def add_edge(src: str, dst: str, rel: str, props: Optional[Dict[str, Any]] = None) -> None:
+    """Add a directed edge ``src --rel--> dst`` with optional properties."""
+    ge = await get_graph_engine()
+    await ge.add_edge(str(src), str(dst), rel, props or {})
+
+
+async def delete_from_both_stores(node_ids: List[str], collections: List[str]) -> int:
+    """Hard-delete nodes from the graph AND their rows from vector collections.
+
+    Returns the number of node ids deleted. Vector deletion is attempted per
+    collection and is best-effort (a node may not live in every collection).
+    """
+    if not node_ids:
+        return 0
+    ids = [str(n) for n in node_ids]
+
+    ge = await get_graph_engine()
+    try:
+        await ge.delete_nodes(ids)
+    except Exception as exc:
+        logger.error("delete_nodes failed: %s", exc)
+        raise
+
+    ve = get_vector_engine()
+    for collection in collections:
+        try:
+            await ve.delete_data_points(collection, ids)
+        except Exception as exc:  # collection may not exist / id not present
+            logger.debug("delete_data_points(%s) best-effort skip: %s", collection, exc)
+    return len(ids)
+
+
+# --------------------------------------------------------------------------- #
+# Adjacency helpers (built from a single load_graph() snapshot)
+# --------------------------------------------------------------------------- #
+
+
+def dependents_of(evidence_id: str, edges: List[Edge], rel: str) -> List[str]:
+    """Return source ids of ``rel`` edges pointing INTO ``evidence_id``.
+
+    For ``depends_on`` (Conclusion -> Evidence) this yields the Conclusions that
+    depend on the given Evidence — i.e. the forward-cascade victims.
+    """
+    tid = str(evidence_id)
+    return [src for (src, dst, r, _p) in edges if r == rel and str(dst) == tid]
+
+
+def incoming(node_id: str, edges: List[Edge], rel: str) -> List[Tuple[str, Dict[str, Any]]]:
+    """Return ``[(source_id, props)]`` for ``rel`` edges pointing into ``node_id``."""
+    tid = str(node_id)
+    return [(src, p) for (src, dst, r, p) in edges if r == rel and str(dst) == tid]
+
+
+def outgoing(node_id: str, edges: List[Edge], rel: str) -> List[Tuple[str, Dict[str, Any]]]:
+    """Return ``[(target_id, props)]`` for ``rel`` edges leaving ``node_id``."""
+    sid = str(node_id)
+    return [(dst, p) for (src, dst, r, p) in edges if r == rel and str(src) == sid]
+
+
+def node_label(props: Dict[str, Any]) -> str:
+    """Best-effort human label for a node from its properties."""
+    for key in ("statement", "claim", "question", "text", "name"):
+        if props.get(key):
+            return str(props[key])
+    return props.get("id", "?")

cognee-hackathon-project-main/falsify/models.py

@@ -0,0 +1,202 @@
+"""
+FALSIFY belief-graph data models.
+
+Every node is a Cognee ``DataPoint`` subclass, so the same object serializes into
+the graph DB (Ladybug) and, via its ``Embeddable`` field, into the vector DB
+(LanceDB). The vector collection auto-created for a class is ``"{ClassName}_{field}"``
+(e.g. ``Evidence_claim`` — the collection the contradiction prefilter searches).
+
+Lifecycle / truth-state note
+----------------------------
+The *authoritative, persistent* belief state of a node lives on the graph node as
+``truth_alignment`` (a list) + ``truth_epoch`` (int), written through the graph
+engine (``set_node_truth_state``), not as pydantic model fields. Those props are
+what ``recall()`` filters on and what survives a process restart.
+
+The ``truth_state`` model field below is a convenience mirror of the node's initial
+state at ingest time (defaults to ``ALIVE``). Do not treat it as the source of
+truth after a memify run — always read back with ``get_node_truth_state``.
+
+Dedup across sessions
+---------------------
+``Hypothesis``, ``Evidence`` and ``Assertion`` mark identity fields with ``Dedup()``.
+DataPoint derives a stable UUID5 id from those fields (``DataPoint.id_for``), so
+re-adding the same belief in a later session updates the existing node instead of
+creating a duplicate — essential for a Session-2 contradiction to land on the exact
+node built in Session 1.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Annotated, List, Optional
+
+from pydantic import Field
+
+from cognee.infrastructure.engine import DataPoint, Dedup, Embeddable, LLMContext
+
+
+def _now_iso() -> str:
+    """Return the current UTC time as an ISO-8601 string (used for node timestamps)."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+class TruthState(str, Enum):
+    """Canonical belief-lifecycle states for a FALSIFY graph node.
+
+    The values are the exact strings written into the node's ``truth_alignment``
+    list, so a state can be compared directly against what ``get_node_truth_state``
+    returns (e.g. ``get_node_truth_state([n])[n]["truth_alignment"] == [TruthState.REFUTED]``).
+
+    States:
+    - ``ALIVE``: default; the node participates in recall context.
+    - ``REFUTED``: Evidence directly contradicted by a newer fact — the entry point
+      of a forward cascade.
+    - ``SUPERSEDED``: a node replaced/demoted by a newer competing node; retained as
+      provenance, excluded from recall.
+    - ``INVALIDATED``: a Conclusion whose critical supporting Evidence chain was
+      refuted (forward-cascade victim).
+    - ``FORGOTTEN``: an orphaned dead-end scheduled for surgical delete (transient;
+      the node is then hard-removed from both graph and vector stores).
+
+    Note: the FALSIFY spec's minimal enum names ALIVE/REFUTED/SUPERSEDED/FORGOTTEN.
+    ``INVALIDATED`` is added here because the forward-propagation algorithm
+    (REQUIREMENTS §1.2/§1.4) needs a distinct state for cascade-victim Conclusions
+    versus directly-refuted Evidence.
+    """
+
+    ALIVE = "alive"
+    REFUTED = "refuted"
+    SUPERSEDED = "superseded"
+    INVALIDATED = "invalidated"
+    FORGOTTEN = "forgotten"
+
+
+# --------------------------------------------------------------------------- #
+# Edge relationship-name constants (passed as ``relationship_name`` to add_edge)
+# --------------------------------------------------------------------------- #
+
+# Conclusion -> Evidence. THE forward-propagation rail. edge_properties={"critical": bool}
+DEPENDS_ON = "depends_on"
+
+# Evidence -> Hypothesis. Evidence corroborates a hypothesis. edge_properties={"weight": float}
+SUPPORTS = "supports"
+
+# Evidence -> Hypothesis. Evidence contradicts a hypothesis. edge_properties={"weight": float}
+# (REQUIREMENTS §1.1 names this edge "refutes"; ``REFUTES`` is provided as an alias.)
+CONTRADICTS = "refutes"
+REFUTES = CONTRADICTS
+
+# Evidence(new) -> Evidence(old). New fact overrides an old evidence node.
+# edge_properties={"confidence": float}
+SUPERSEDES = "supersedes"
+
+
+class InvestigationQuestion(DataPoint):
+    """Root node of a belief graph: the research question under investigation.
+
+    Example: "Did Company X know about the defect before the recall?" Everything
+    else (hypotheses, evidence, conclusions) hangs off this question via
+    ``question_id``.
+    """
+
+    question: Annotated[str, Embeddable(), LLMContext()]
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 1.0
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["question"],
+        "identity_fields": ["question"],
+    }
+
+
+class Hypothesis(DataPoint):
+    """A candidate explanation competing to answer the InvestigationQuestion.
+
+    Hypotheses gain/lose standing through ``supports``/``refutes`` Evidence edges.
+    When a hypothesis' only supporting Evidence is refuted, it is demoted to
+    ``SUPERSEDED`` and the rival with the strongest surviving support is promoted.
+    """
+
+    statement: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    question_id: str
+    status: str = "alive"
+    prior: float = 0.5
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["statement"],
+        "identity_fields": ["question_id", "statement"],
+    }
+
+
+class Evidence(DataPoint):
+    """A factual claim bearing on one or more hypotheses.
+
+    Evidence is the contradiction entry point: the ``Evidence_claim`` vector
+    collection is what the two-gate detector prefilters, and a ``REFUTED`` Evidence
+    node is the seed of every forward cascade. ``asserted_at`` is used as the
+    tie-break when deciding which of two competing claims supersedes the other
+    (newer wins).
+    """
+
+    claim: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    source_id: str
+    quote: str = ""
+    stance: str = "supports"  # "supports" | "refutes"
+    asserted_at: str = Field(default_factory=_now_iso)
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+
+    metadata: dict = {
+        "index_fields": ["claim"],
+        "identity_fields": ["source_id", "claim"],
+    }
+
+
+class Conclusion(DataPoint):
+    """A derived finding that rests on one or more Evidence nodes.
+
+    A Conclusion ``depends_on`` the Evidence it is built from (edge carries
+    ``critical: bool``). When a *critical* dependency is refuted and no alive
+    critical alternative remains, the Conclusion is ``INVALIDATED`` by the forward
+    cascade; if it then has no surviving consumer it is ``FORGOTTEN`` (hard-deleted).
+    """
+
+    statement: Annotated[str, Embeddable(), LLMContext()]
+    confidence: float = 0.5
+    depends_on_ids: List[str] = Field(default_factory=list)
+    truth_state: TruthState = TruthState.ALIVE
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["statement"],
+        "identity_fields": ["statement"],
+    }
+
+
+class Assertion(DataPoint):
+    """A raw, unclassified incoming claim — e.g. the new fact pasted in Session 2.
+
+    An Assertion is the pre-belief form of an incoming statement before the detector
+    decides whether it contradicts/supersedes existing Evidence and materializes a
+    proper ``Evidence`` node. It carries the same lifecycle scaffolding as the other
+    nodes so it can be reasoned over uniformly.
+    """
+
+    text: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["text"],
+        "identity_fields": ["text"],
+    }

cognee-hackathon-project-main/falsify/seed.py

@@ -0,0 +1,197 @@
+"""
+FALSIFY demo corpus — the "Company X recall" investigation.
+
+This module builds the Session-1 belief graph that the demo revises in Session 2.
+It is intentionally small and hand-authored so the belief-revision mechanics are
+legible on screen in under 30 seconds, and so the cascade result is deterministic
+(the winning demo must not depend on a flaky LLM).
+
+The investigation
+-----------------
+Question Q:  "Did Company X know about the defect before the recall?"
+
+Competing hypotheses:
+    A — "X knew via the QA report dated March 2021"      (supported by E_qa)
+    B — "X knew via a supplier email in January 2021"    (supported by E_email)
+    C — "X did not know before the recall"               (unsupported)
+
+Evidence:
+    E_qa    — the March-2021 QA report       (supports A)
+    E_email — the January-2021 supplier email (supports B)
+
+Conclusion:
+    K — "Company X knew about the defect by March 2021"
+        depends_on E_qa  (critical=True)   <-- the propagation rail
+
+The Session-2 fact (NEW_FACT) is a forensic finding that the March QA report was
+back-dated. It contradicts E_qa. Refuting E_qa must cascade:
+
+    E_qa -> refuted
+      -> K (depends_on E_qa, critical) -> invalidated
+      -> A (only supporter E_qa now dead) -> superseded ; B promoted (new frontier)
+      -> K orphaned (no alive consumer) -> forgotten (hard-deleted, graph + vector)
+      -> E_qa kept as refuted provenance (it is NEW_FACT's supersedes anchor)
+
+The scoreboard then shows FALSIFY answering via B (Jan 2021) while a plain vector
+(RAG) baseline still cites the refuted March QA report.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+# NOTE: importing falsify.models runs falsify/__init__, which sets the Cognee env
+# defaults (access-control off, session cache on) before Cognee is imported.
+from falsify import graph_ops
+from falsify.edges import DEPENDS_ON, SUPPORTS
+from falsify.models import (
+    Conclusion,
+    Evidence,
+    Hypothesis,
+    InvestigationQuestion,
+)
+
+logger = logging.getLogger("falsify.seed")
+
+# The research question this whole graph hangs off of.
+QUESTION_TEXT = "Did Company X know about the defect before the recall?"
+
+# The Session-2 fact that triggers belief revision. It contradicts E_qa.
+NEW_FACT = (
+    "A forensic audit found that the March 2021 QA report was back-dated: it was "
+    "actually created shortly after the product recall, not before it."
+)
+
+# Human-readable stable keys -> used by --demo mode to pin the refutation target
+# deterministically (so the cascade runs on real graph APIs even if the LLM judge
+# is unavailable). These map to the ``key`` field on the seeded nodes below.
+REFUTED_EVIDENCE_KEY = "E_qa"
+
+
+@dataclass
+class SeededGraph:
+    """Handles to the nodes created by :func:`build_investigation`.
+
+    ``ids`` maps a stable human key (e.g. ``"E_qa"``, ``"A"``, ``"K"``) to the
+    string node id in the graph, so the demo/tests can reference specific nodes
+    without re-querying. ``labels`` maps the same keys to display strings.
+    """
+
+    question_id: str
+    ids: Dict[str, str] = field(default_factory=dict)
+    labels: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def refuted_target_id(self) -> str:
+        """Node id of the evidence the Session-2 fact contradicts (E_qa)."""
+        return self.ids[REFUTED_EVIDENCE_KEY]
+
+
+async def build_investigation() -> SeededGraph:
+    """Create and persist the Session-1 belief graph. Returns a :class:`SeededGraph`.
+
+    The caller is responsible for starting from a clean state (e.g. via
+    ``cognee.forget(everything=True)`` and ``cognee.low_level.setup()``). This
+    function only builds; it does not prune.
+
+    Nodes are persisted with Cognee's ``add_data_points`` (writing both the graph
+    node and the vector row for each ``Embeddable`` field). Typed edges with
+    properties are then added explicitly through the graph engine so we control the
+    exact relationship names and edge properties (``critical`` / ``weight``).
+    """
+    # Import here so the module import stays cheap and env defaults are already set.
+    from cognee.tasks.storage import add_data_points
+
+    # ------------------------------------------------------------------ nodes
+    question = InvestigationQuestion(question=QUESTION_TEXT, source_id="investigation")
+
+    hyp_a = Hypothesis(
+        statement="Company X knew via the QA report dated March 2021.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.6,
+        source_id="analyst",
+    )
+    hyp_b = Hypothesis(
+        statement="Company X knew via a supplier email in January 2021.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.55,
+        source_id="analyst",
+    )
+    hyp_c = Hypothesis(
+        statement="Company X did not know about the defect before the recall.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.4,
+        source_id="analyst",
+    )
+
+    ev_qa = Evidence(
+        claim="A QA report dated March 2021 documented the defect internally.",
+        source_id="qa_report_2021_03",
+        quote="Internal QA report, dated 2021-03-15, flags the defect.",
+        stance="supports",
+        asserted_at="2021-03-15",
+        confidence=0.8,
+    )
+    ev_email = Evidence(
+        claim="A supplier email in January 2021 warned Company X about the defect.",
+        source_id="supplier_email_2021_01",
+        quote="Supplier email, 2021-01-20: 'we have observed the defect in test units.'",
+        stance="supports",
+        asserted_at="2021-01-20",
+        confidence=0.7,
+    )
+
+    conclusion_k = Conclusion(
+        statement="Company X knew about the defect by March 2021.",
+        confidence=0.8,
+        depends_on_ids=[str(ev_qa.id)],
+        source_id="analyst",
+    )
+
+    nodes: List = [question, hyp_a, hyp_b, hyp_c, ev_qa, ev_email, conclusion_k]
+
+    logger.info("Persisting %d belief nodes via add_data_points", len(nodes))
+    await add_data_points(nodes)
+
+    # ------------------------------------------------------------------ edges
+    # Evidence -> Hypothesis (supports, weighted)
+    await graph_ops.add_edge(str(ev_qa.id), str(hyp_a.id), SUPPORTS, {"weight": 0.8})
+    await graph_ops.add_edge(str(ev_email.id), str(hyp_b.id), SUPPORTS, {"weight": 0.7})
+
+    # Conclusion -> Evidence (depends_on, critical) — THE propagation rail
+    await graph_ops.add_edge(
+        str(conclusion_k.id), str(ev_qa.id), DEPENDS_ON, {"critical": True}
+    )
+
+    # Hypothesis -> Question (answers) — keeps the graph connected for visualization
+    for hyp in (hyp_a, hyp_b, hyp_c):
+        await graph_ops.add_edge(str(hyp.id), str(question.id), "answers", {})
+
+    seeded = SeededGraph(
+        question_id=str(question.id),
+        ids={
+            "Q": str(question.id),
+            "A": str(hyp_a.id),
+            "B": str(hyp_b.id),
+            "C": str(hyp_c.id),
+            "E_qa": str(ev_qa.id),
+            "E_email": str(ev_email.id),
+            "K": str(conclusion_k.id),
+        },
+        labels={
+            "Q": QUESTION_TEXT,
+            "A": hyp_a.statement,
+            "B": hyp_b.statement,
+            "C": hyp_c.statement,
+            "E_qa": ev_qa.claim,
+            "E_email": ev_email.claim,
+            "K": conclusion_k.statement,
+        },
+    )
+    logger.info("Seeded investigation graph: %s", seeded.ids)
+    return seeded

cognee-hackathon-project-main/falsify/tasks/__init__.py

@@ -0,0 +1,36 @@
+"""
+FALSIFY belief-revision tasks.
+
+The three-step revision pipeline, in execution order:
+
+1. :func:`detect_contradictions` — two-gate detector: which existing evidence does a
+   new fact contradict/supersede?
+2. :func:`propagate_refutation` — flip the contradicted evidence to ``refuted`` and
+   cascade ``invalidated`` forward through ``depends_on``; then
+   :func:`promote_competing_hypothesis` re-scores the rival hypotheses.
+3. :func:`cascade_forget` — hard-delete truly-orphaned dead-ends from graph + vector,
+   keeping provenance tombstones.
+"""
+
+from falsify.tasks.detect_contradictions import (
+    Contradiction,
+    ContradictionJudgement,
+    detect_contradictions,
+)
+from falsify.tasks.propagate_refutation import (
+    PropagationResult,
+    promote_competing_hypothesis,
+    propagate_refutation,
+)
+from falsify.tasks.cascade_forget import ForgetResult, cascade_forget
+
+__all__ = [
+    "detect_contradictions",
+    "Contradiction",
+    "ContradictionJudgement",
+    "propagate_refutation",
+    "promote_competing_hypothesis",
+    "PropagationResult",
+    "cascade_forget",
+    "ForgetResult",
+]

cognee-hackathon-project-main/falsify/tasks/cascade_forget.py

@@ -0,0 +1,159 @@
+"""
+Surgical forget — prune orphaned dead-ends from graph **and** vector stores.
+
+After :mod:`falsify.tasks.propagate_refutation` marks nodes ``refuted`` /
+``invalidated``, some of those nodes are still useful: they explain *why* a belief
+changed (provenance) or they still feed a node that is alive. Others are pure
+dead-ends with no surviving consumer. FALSIFY hard-deletes only the latter, from
+both the graph (``delete_nodes``) and the vector index (``delete_data_points``), so a
+subsequent ``recall()`` — and even a raw vector search — can never resurface them.
+
+Orphan rule (REQUIREMENTS §1.5) — a node is FORGOTTEN iff ALL hold:
+    (a) truth state is ``refuted`` or ``invalidated`` (never ``alive``/``superseded``;
+        superseded nodes are kept as provenance), AND
+    (b) no surviving ALIVE node reaches it via ``depends_on`` or ``supports``
+        (it has no live consumer), AND
+    (c) it is NOT the target of a ``supersedes`` edge FROM an alive node (such a node
+        is the provenance anchor of the new truth and must be retained as a tombstone).
+
+The asymmetry is deliberate and is what makes FALSIFY look *surgical*: in the demo the
+orphaned Conclusion K is deleted, while the refuted Evidence E_qa is kept — flagged
+red — because it is the supersedes-anchor of the new fact.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Set
+
+from falsify import graph_ops
+from falsify.edges import CONSUMER_EDGE_TYPES, SUPERSEDES
+from falsify.models import (
+    Conclusion,
+    Evidence,
+    TruthState,
+)
+
+logger = logging.getLogger("falsify.forget")
+
+_DELETABLE_STATES = {TruthState.REFUTED.value, TruthState.INVALIDATED.value}
+_ALIVE = TruthState.ALIVE.value
+
+# Vector collections FALSIFY writes to (``"{ClassName}_{embeddable_field}"``).
+# Deleting an id from a collection it isn't in is a best-effort no-op.
+_VECTOR_COLLECTIONS = [
+    "Evidence_claim",
+    "Conclusion_statement",
+    "Hypothesis_statement",
+    "Assertion_text",
+    "InvestigationQuestion_question",
+]
+
+
+@dataclass
+class ForgetResult:
+    """Outcome of a forget pass.
+
+    Attributes:
+        forgotten: node ids hard-deleted from graph + vector.
+        retained_provenance: refuted/invalidated ids deliberately kept (a supersedes
+            anchor, or still feeding a live node).
+        labels: id -> human label for the forgotten nodes (for demo output).
+    """
+
+    forgotten: List[str] = field(default_factory=list)
+    retained_provenance: List[str] = field(default_factory=list)
+    labels: Dict[str, str] = field(default_factory=dict)
+
+
+async def _alive_consumer_exists(node_id: str, edges, truth: Dict[str, List[str]]) -> bool:
+    """True if some ALIVE node reaches ``node_id`` via depends_on/supports.
+
+    ``depends_on`` (Conclusion->Evidence) and ``supports`` (Evidence->Hypothesis) both
+    point *from consumer to the thing consumed*, so an incoming edge's **source** is a
+    consumer of ``node_id``.
+    """
+    nid = str(node_id)
+    for rel in CONSUMER_EDGE_TYPES:
+        for src, _props in graph_ops.incoming(nid, edges, rel):
+            alignment = truth.get(str(src), [_ALIVE])
+            if _ALIVE in alignment:
+                return True
+    return False
+
+
+def _is_supersedes_anchor(node_id: str, edges, truth: Dict[str, List[str]]) -> bool:
+    """True if ``node_id`` is the target of a ``supersedes`` edge from an ALIVE node.
+
+    That alive source is the new, current truth; the target is its tombstone and must
+    be retained as provenance.
+    """
+    nid = str(node_id)
+    for src, _props in graph_ops.incoming(nid, edges, SUPERSEDES):
+        alignment = truth.get(str(src), [_ALIVE])
+        if _ALIVE in alignment:
+            return True
+    return False
+
+
+async def cascade_forget(candidate_ids: List[str]) -> ForgetResult:
+    """Delete truly-orphaned dead-ends among ``candidate_ids``; keep provenance.
+
+    Args:
+        candidate_ids: nodes marked refuted/invalidated by a preceding cascade.
+
+    Returns:
+        A :class:`ForgetResult`. Deleted nodes are removed from the graph and from
+        every FALSIFY vector collection, so no retrieval path can resurface them.
+    """
+    result = ForgetResult()
+    candidates = [str(c) for c in dict.fromkeys(candidate_ids) if c]
+    if not candidates:
+        return result
+
+    nodes, edges = await graph_ops.load_graph()
+    props_by_id = {str(nid): (props or {}) for nid, props in nodes}
+
+    # Current truth for candidates + their neighbors (consumers/anchors).
+    neighbor_ids: Set[str] = set(candidates)
+    for cid in candidates:
+        for rel in (*CONSUMER_EDGE_TYPES, SUPERSEDES):
+            neighbor_ids.update(str(s) for s, _p in graph_ops.incoming(cid, edges, rel))
+    truth = await graph_ops.get_truth(list(neighbor_ids))
+
+    death_set: List[str] = []
+    for cid in candidates:
+        alignment = truth.get(cid, [_ALIVE])
+
+        # (a) must be refuted/invalidated
+        if not any(state in _DELETABLE_STATES for state in alignment):
+            continue
+        # (c) keep supersedes anchors (provenance tombstones)
+        if _is_supersedes_anchor(cid, edges, truth):
+            result.retained_provenance.append(cid)
+            logger.info("retained %s as supersedes provenance anchor", cid)
+            continue
+        # (b) keep nodes that still feed a live consumer
+        if await _alive_consumer_exists(cid, edges, truth):
+            result.retained_provenance.append(cid)
+            logger.info("retained %s (still feeds a live node)", cid)
+            continue
+
+        death_set.append(cid)
+        result.labels[cid] = graph_ops.node_label(props_by_id.get(cid, {}))
+
+    if not death_set:
+        logger.info("forget pass: nothing orphaned; %d provenance nodes retained",
+                    len(result.retained_provenance))
+        return result
+
+    # Hard-delete from graph + all vector collections in one batch.
+    deleted = await graph_ops.delete_from_both_stores(death_set, _VECTOR_COLLECTIONS)
+    result.forgotten = death_set
+    logger.info(
+        "forget pass: hard-deleted %d orphan(s) from graph + vector; retained %d provenance",
+        deleted,
+        len(result.retained_provenance),
+    )
+    return result

cognee-hackathon-project-main/falsify/tasks/detect_contradictions.py

@@ -0,0 +1,199 @@
+"""
+Two-gate contradiction detection — the trigger for belief revision.
+
+Deciding that a new fact *contradicts* an existing belief is the one genuinely
+fuzzy step in FALSIFY. A false positive nukes a valid conclusion; a false negative
+lets a stale fact survive. We therefore gate it twice, cheap-deterministic first,
+expensive-semantic second, with a hard deterministic override for the live demo.
+
+    Gate 1 — vector prefilter (deterministic).
+        Embed the new fact and search the ``Evidence_claim`` collection. Only
+        evidence within a cosine-distance threshold (``< 0.35`` by default, i.e.
+        clearly on-topic) proceeds. This narrows the LLM to plausibly-conflicting
+        claims and keeps cost + nondeterminism bounded.
+
+    Gate 2 — LLM adjudication (semantic).
+        For each surviving candidate, ask an LLM acting as a skeptical analyst to
+        classify the relation as contradicts / supersedes / supports / unrelated with
+        a confidence. Only ``contradicts`` or ``supersedes`` at confidence >= 0.6
+        triggers refutation. This separates a genuine contradiction ("the report was
+        back-dated") from mere topical overlap ("also mentions the report").
+
+    Demo override (``pinned_target_id`` / ``DEMO_MODE``).
+        When set, gates are bypassed and a fixed high-confidence ``contradicts``
+        verdict is returned for the pinned evidence id, so the on-stage cascade runs
+        on real graph APIs even if the LLM is slow, rate-limited, or the key is
+        absent. This is FALSIFY's demo safety net (REQUIREMENTS §1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from falsify import graph_ops
+
+logger = logging.getLogger("falsify.detect")
+
+# Cosine distance below which two claims are "about the same thing" (Gate 1).
+DEFAULT_DISTANCE_THRESHOLD = 0.35
+# Minimum LLM confidence for a contradiction/supersede to count (Gate 2).
+DEFAULT_CONFIDENCE_THRESHOLD = 0.6
+# Vector collection holding Evidence claims.
+_EVIDENCE_COLLECTION = "Evidence_claim"
+
+_SYSTEM_PROMPT = (
+    "You are a skeptical forensic analyst. You are given an EXISTING evidence claim "
+    "and a NEW fact. Decide the logical relation of the NEW fact to the EXISTING "
+    "claim. Answer 'contradicts' only if the new fact makes the existing claim false "
+    "or untrustworthy (e.g. it was fabricated, back-dated, retracted, or refuted). "
+    "Answer 'supersedes' if the new fact replaces the existing claim with a newer, "
+    "more authoritative version of the same fact. Answer 'supports' if it corroborates "
+    "the claim, and 'unrelated' otherwise. Be conservative: when unsure, prefer "
+    "'unrelated'. Provide a calibrated confidence in [0,1] and a one-sentence rationale."
+)
+
+
+class ContradictionJudgement(BaseModel):
+    """Structured verdict returned by the Gate-2 LLM adjudication."""
+
+    relation: Literal["contradicts", "supersedes", "supports", "unrelated"]
+    confidence: float = Field(ge=0.0, le=1.0)
+    rationale: str = ""
+
+
+@dataclass
+class Contradiction:
+    """A confirmed conflict between the new fact and an existing evidence node.
+
+    Attributes:
+        target_id: the existing Evidence node id that is contradicted/superseded.
+        relation: ``contradicts`` or ``supersedes``.
+        confidence: adjudicated confidence.
+        rationale: short human explanation (shown in the demo).
+        distance: Gate-1 cosine distance (lower = more on-topic).
+    """
+
+    target_id: str
+    relation: str
+    confidence: float
+    rationale: str = ""
+    distance: float = 0.0
+
+
+async def detect_contradictions(
+    new_fact: str,
+    *,
+    pinned_target_id: Optional[str] = None,
+    distance_threshold: float = DEFAULT_DISTANCE_THRESHOLD,
+    confidence_threshold: float = DEFAULT_CONFIDENCE_THRESHOLD,
+    max_candidates: int = 5,
+) -> List[Contradiction]:
+    """Return the existing evidence nodes that ``new_fact`` contradicts or supersedes.
+
+    Args:
+        new_fact: the incoming claim (e.g. the Session-2 forensic finding).
+        pinned_target_id: demo/deterministic override; if given, gates are skipped and
+            a single high-confidence ``contradicts`` verdict is returned for this id.
+        distance_threshold: Gate-1 cosine-distance cutoff (lower = stricter on-topic).
+        confidence_threshold: Gate-2 minimum confidence to accept a verdict.
+        max_candidates: cap on Gate-1 candidates sent to the LLM.
+
+    Returns:
+        A list of :class:`Contradiction` (possibly empty). Callers feed the target
+        ids into :func:`falsify.tasks.propagate_refutation.propagate_refutation`.
+    """
+    # -------- Demo / deterministic override -------------------------------
+    if pinned_target_id:
+        logger.info("detect_contradictions: pinned target %s (demo mode)", pinned_target_id)
+        return [
+            Contradiction(
+                target_id=str(pinned_target_id),
+                relation="contradicts",
+                confidence=0.9,
+                rationale="Pinned contradiction (demo mode): new fact invalidates the target evidence.",
+                distance=0.0,
+            )
+        ]
+
+    # -------- Gate 1: vector prefilter ------------------------------------
+    ve = graph_ops.get_vector_engine()
+    try:
+        hits = await ve.search(
+            _EVIDENCE_COLLECTION,
+            query_text=new_fact,
+            limit=max_candidates,
+            include_payload=True,
+        )
+    except Exception as exc:
+        logger.warning("Gate-1 vector search failed (%s); no contradictions detected", exc)
+        return []
+
+    candidates = [(str(h.id), float(getattr(h, "score", 1.0)), getattr(h, "payload", {}) or {})
+                  for h in (hits or [])]
+    on_topic = [c for c in candidates if c[1] < distance_threshold]
+    logger.info(
+        "Gate-1: %d hit(s), %d within distance %.2f", len(candidates), len(on_topic), distance_threshold
+    )
+    if not on_topic:
+        return []
+
+    # -------- Gate 2: LLM adjudication ------------------------------------
+    from cognee.infrastructure.llm.LLMGateway import LLMGateway
+
+    confirmed: List[Contradiction] = []
+    for target_id, distance, payload in on_topic:
+        existing_claim = _payload_text(payload) or "(existing evidence claim)"
+        text_input = (
+            f"EXISTING claim:\n{existing_claim}\n\nNEW fact:\n{new_fact}\n\n"
+            "Classify the relation of the NEW fact to the EXISTING claim."
+        )
+        try:
+            verdict: ContradictionJudgement = await LLMGateway.acreate_structured_output(
+                text_input=text_input,
+                system_prompt=_SYSTEM_PROMPT,
+                response_model=ContradictionJudgement,
+            )
+        except Exception as exc:
+            logger.warning("Gate-2 LLM judge failed for %s (%s); skipping candidate", target_id, exc)
+            continue
+
+        if verdict.relation in ("contradicts", "supersedes") and verdict.confidence >= confidence_threshold:
+            confirmed.append(
+                Contradiction(
+                    target_id=target_id,
+                    relation=verdict.relation,
+                    confidence=verdict.confidence,
+                    rationale=verdict.rationale,
+                    distance=distance,
+                )
+            )
+            logger.info(
+                "Gate-2: CONFIRMED %s on %s (conf=%.2f)", verdict.relation, target_id, verdict.confidence
+            )
+        else:
+            logger.info(
+                "Gate-2: rejected %s (relation=%s conf=%.2f)",
+                target_id, verdict.relation, verdict.confidence,
+            )
+
+    return confirmed
+
+
+def _payload_text(payload: dict) -> Optional[str]:
+    """Extract the human-readable claim text from a vector-hit payload."""
+    if not payload:
+        return None
+    for key in ("claim", "text", "statement", "content"):
+        if payload.get(key):
+            return str(payload[key])
+    # cognee payloads sometimes nest the original properties
+    props = payload.get("properties") or payload.get("metadata")
+    if isinstance(props, dict):
+        for key in ("claim", "text", "statement"):
+            if props.get(key):
+                return str(props[key])
+    return None

cognee-hackathon-project-main/falsify/tasks/propagate_refutation.py

@@ -0,0 +1,281 @@
+"""
+Forward refutation propagation — the core of FALSIFY's belief revision.
+
+When a piece of Evidence is refuted, the conclusions that *depend on it* can no
+longer stand. This module walks the dependency structure and flips the truth-state
+of every node that transitively rests on the refuted evidence, then re-scores the
+competing hypotheses.
+
+Why this can't be done by RAG
+-----------------------------
+Vector similarity has no notion of "this fact supports that conclusion three hops
+away." Refutation propagation is *graph traversal over typed edges* — it is exactly
+the thing a knowledge graph can do and an embedding index cannot. This is FALSIFY's
+differentiator and maps directly to the hackathon's "Best Use of Cognee" criterion.
+
+Direction of travel (critical detail)
+-------------------------------------
+The ``depends_on`` edge points **Conclusion -> Evidence** (a conclusion depends on
+the evidence it rests on). So to find what *breaks* when Evidence ``E`` is refuted,
+we look for ``depends_on`` edges whose **target** is ``E``; their **sources** are the
+dependent Conclusions. We then recurse: a newly-invalidated Conclusion may itself be
+the target of further ``depends_on`` edges.
+
+Correctness cases handled (REQUIREMENTS §4.3)
+--------------------------------------------
+* **Cycle safety** — a ``visited`` set guarantees termination on cyclic graphs.
+* **Critical vs non-critical** — only a ``critical: true`` dependency can invalidate
+  a conclusion. A non-critical dependency being refuted decays confidence but the
+  conclusion stays ``alive``.
+* **Diamond / partial refutation** — a conclusion with several critical supporters is
+  invalidated only when it loses its **last** alive critical supporter. If an
+  alternative critical support is still alive, the conclusion survives (and the
+  refuted evidence is *retained*, because it still feeds a live node).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+from falsify import graph_ops
+from falsify.edges import (
+    DEPENDENCY_EDGE_TYPES,
+    DEPENDS_ON,
+    SUPPORTS,
+    is_critical_dependency,
+)
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.propagate")
+
+# Truth states that count as "dead" for the purpose of dependency support.
+_DEAD_STATES = {TruthState.REFUTED.value, TruthState.INVALIDATED.value, TruthState.FORGOTTEN.value}
+
+
+@dataclass
+class PropagationResult:
+    """Outcome of a refutation cascade.
+
+    Attributes:
+        refuted: evidence node ids set to ``refuted`` (the cascade seeds).
+        invalidated: conclusion node ids set to ``invalidated`` by the cascade.
+        weakened: conclusion ids whose confidence decayed but stayed ``alive``
+            (a non-critical dependency was refuted).
+        epoch: the revision epoch stamped on every state change in this cascade.
+        affected: convenience union of refuted + invalidated ids (the death set
+            candidates for :mod:`falsify.tasks.cascade_forget`).
+    """
+
+    refuted: List[str] = field(default_factory=list)
+    invalidated: List[str] = field(default_factory=list)
+    weakened: List[str] = field(default_factory=list)
+    epoch: int = 0
+
+    @property
+    def affected(self) -> List[str]:
+        return list(dict.fromkeys(self.refuted + self.invalidated))
+
+
+async def _next_epoch() -> int:
+    """Return a monotonically increasing revision epoch.
+
+    We derive it from the current maximum ``truth_epoch`` present on any node so the
+    counter survives restarts (state is persisted on nodes). Falls back to 1.
+    """
+    try:
+        nodes, _edges = await graph_ops.load_graph()
+        max_epoch = 0
+        for _nid, props in nodes:
+            ep = props.get("truth_epoch")
+            if isinstance(ep, int) and ep > max_epoch:
+                max_epoch = ep
+        return max_epoch + 1
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("epoch derivation failed (%s); defaulting to 1", exc)
+        return 1
+
+
+async def propagate_refutation(
+    refuted_evidence_ids: List[str],
+    epoch: Optional[int] = None,
+) -> PropagationResult:
+    """Refute the given evidence and cascade the consequence forward.
+
+    Args:
+        refuted_evidence_ids: evidence node ids directly contradicted by a new fact.
+        epoch: optional explicit revision epoch; if omitted a fresh one is derived.
+
+    Returns:
+        A :class:`PropagationResult` describing what changed. All state changes are
+        persisted on the graph nodes via ``set_node_truth_state`` (so they survive a
+        process restart — the basis of cross-session belief revision).
+
+    Algorithm — grounded least-fixpoint justification
+    -------------------------------------------------
+    A conclusion is *justified* only if it has a **critical** ``depends_on`` support
+    chain that bottoms out in a still-alive node. We therefore:
+
+        1. Mark each seed evidence ``refuted``.
+        2. Build the "dead" set = seeds plus anything already refuted / invalidated /
+           superseded from prior revisions.
+        3. Compute the GROUNDED set as a least fixpoint: a node is grounded if it is
+           not dead and either (a) it has no critical ``depends_on`` edges (a base
+           node — evidence, or a conclusion resting only on non-critical support) or
+           (b) at least one of its critical dependencies is itself grounded. Iterate
+           to convergence.
+        4. Every *conclusion* (a node that is the source of a ``depends_on`` edge)
+           that is currently alive but **not** grounded is ``invalidated``.
+        5. A conclusion that survives (stays grounded) yet lost some dependency to the
+           dead set is merely ``weakened`` (confidence decayed).
+
+    This single formulation is correct for chains, diamonds (survives while any
+    critical alternative is grounded), partial/non-critical refutation, **and cycles**
+    (a mutually-supporting loop with no grounded base is not justified, so it
+    collapses) — the fixpoint terminates because ``grounded`` only ever grows.
+    """
+    result = PropagationResult(epoch=epoch if epoch is not None else await _next_epoch())
+    seeds = [str(e) for e in refuted_evidence_ids if e]
+    if not seeds:
+        logger.info("propagate_refutation called with no seeds; nothing to do")
+        return result
+
+    nodes, edges = await graph_ops.load_graph()
+    node_ids = [str(nid) for nid, _p in nodes]
+
+    # 1) seed refutations (persisted)
+    for ev_id in seeds:
+        await graph_ops.set_state(ev_id, TruthState.REFUTED, result.epoch)
+        await graph_ops.set_weight(ev_id, 0.0)
+        result.refuted.append(ev_id)
+        logger.info("refuted evidence %s", ev_id)
+
+    # 2) dead set = seeds + already-dead-from-prior-revisions
+    truth = await graph_ops.get_truth(node_ids)
+    dead: Set[str] = set(seeds)
+    for nid in node_ids:
+        alignment = truth.get(nid, [TruthState.ALIVE.value])
+        if any(s in _DEAD_STATES or s == TruthState.SUPERSEDED.value for s in alignment):
+            dead.add(nid)
+
+    # Dependency structure: node -> critical / all depends_on targets.
+    conclusions: Set[str] = set()
+    critical_targets: Dict[str, Set[str]] = {}
+    all_targets: Dict[str, Set[str]] = {}
+    for src, dst, rel, props in edges:
+        if rel not in DEPENDENCY_EDGE_TYPES:
+            continue
+        s, d = str(src), str(dst)
+        conclusions.add(s)
+        all_targets.setdefault(s, set()).add(d)
+        if is_critical_dependency(rel, props):
+            critical_targets.setdefault(s, set()).add(d)
+
+    def _has_critical(n: str) -> bool:
+        return bool(critical_targets.get(n))
+
+    # 3) grounded least fixpoint
+    grounded: Set[str] = {nid for nid in node_ids if nid not in dead and not _has_critical(nid)}
+    changed = True
+    while changed:
+        changed = False
+        for c in conclusions:
+            if c in grounded or c in dead:
+                continue
+            if critical_targets.get(c, set()) & grounded:
+                grounded.add(c)
+                changed = True
+
+    # 4) invalidate currently-alive conclusions that lost grounding
+    for c in conclusions:
+        if c in grounded:
+            continue
+        alignment = truth.get(c, [TruthState.ALIVE.value])
+        if TruthState.ALIVE.value not in alignment:
+            continue  # already dead in a prior revision; don't re-report
+        await graph_ops.set_state(c, TruthState.INVALIDATED, result.epoch)
+        await graph_ops.set_weight(c, 0.0)
+        result.invalidated.append(c)
+        logger.info("invalidated conclusion %s (lost grounded critical support)", c)
+
+    # 5) weaken survivors that lost some dependency to the dead set
+    for c in conclusions:
+        if c not in grounded:
+            continue
+        if all_targets.get(c, set()) & dead:
+            result.weakened.append(c)
+            await graph_ops.set_weight(c, 0.3)
+            logger.info("weakened conclusion %s (lost a dependency but stays grounded)", c)
+
+    logger.info(
+        "propagation done: refuted=%d invalidated=%d weakened=%d epoch=%d",
+        len(result.refuted),
+        len(result.invalidated),
+        len(result.weakened),
+        result.epoch,
+    )
+    return result
+
+
+async def promote_competing_hypothesis(
+    refuted_evidence_ids: List[str],
+    epoch: int,
+) -> Dict[str, str]:
+    """Demote hypotheses whose support just died; promote the strongest survivor.
+
+    A hypothesis is ``superseded`` when every ``supports`` Evidence pointing at it is
+    now dead. Among the hypotheses still holding at least one alive ``supports`` edge,
+    the one with the greatest summed support ``weight`` is promoted (its feedback
+    weight is boosted) and becomes the new frontier answer.
+
+    Returns a dict mapping hypothesis id -> action (``"superseded"`` / ``"promoted"``).
+    """
+    actions: Dict[str, str] = {}
+    _nodes, edges = await graph_ops.load_graph()
+
+    # Collect hypotheses that are the target of any supports edge.
+    supports_edges = [(s, d, p) for (s, d, r, p) in edges if r == SUPPORTS]
+    hypothesis_ids = {str(d) for (_s, d, _p) in supports_edges}
+    if not hypothesis_ids:
+        return actions
+
+    # Determine current dead evidence set (seeds + anything already refuted/invalidated).
+    all_ids = list({str(s) for (s, _d, _p) in supports_edges} | {str(e) for e in refuted_evidence_ids})
+    truth = await graph_ops.get_truth(all_ids)
+
+    def _is_dead(node_id: str) -> bool:
+        alignment = truth.get(str(node_id), [TruthState.ALIVE.value])
+        return any(state in _DEAD_STATES for state in alignment) or str(node_id) in {
+            str(e) for e in refuted_evidence_ids
+        }
+
+    # Score each hypothesis by its surviving support.
+    live_support: Dict[str, float] = {}
+    for hyp_id in hypothesis_ids:
+        total = 0.0
+        for (src, dst, props) in supports_edges:
+            if str(dst) != hyp_id:
+                continue
+            if _is_dead(src):
+                continue
+            total += float(props.get("weight", 0.5))
+        live_support[hyp_id] = total
+
+    # Demote hypotheses with zero surviving support.
+    for hyp_id, score in live_support.items():
+        if score <= 0.0:
+            await graph_ops.set_state(hyp_id, TruthState.SUPERSEDED, epoch)
+            await graph_ops.set_weight(hyp_id, 0.0)
+            actions[hyp_id] = "superseded"
+            logger.info("superseded hypothesis %s (no surviving support)", hyp_id)
+
+    # Promote the strongest surviving hypothesis, if any.
+    survivors = {h: s for h, s in live_support.items() if s > 0.0}
+    if survivors:
+        winner = max(survivors, key=survivors.get)
+        await graph_ops.set_weight(winner, 1.0)
+        actions[winner] = "promoted"
+        logger.info("promoted hypothesis %s (support=%.2f) as new frontier", winner, survivors[winner])
+
+    return actions

cognee-hackathon-project-main/falsify/utils.py

@@ -0,0 +1,250 @@
+"""
+FALSIFY presentation helpers — console state + interactive graph visualization.
+
+These functions turn the belief graph into the two things a judge actually sees:
+
+* :func:`print_graph_state` — the BEFORE/AFTER console beat, each node tagged with a
+  colored ``ALIVE`` / ``REFUTED`` / ``INVALIDATED`` / ``SUPERSEDED`` marker.
+* :func:`visualize_belief_graph` — a single self-contained HTML file (vis-network via
+  CDN, no build step) that colors nodes by truth-state so the cascade is legible at a
+  glance: green = alive, red (dashed) = refuted, grey = invalidated, amber = superseded.
+* :func:`get_belief_summary` — counts by type/state, used in output and tests.
+* :func:`verify_propagation` — a small assertion helper for tests.
+
+Everything degrades gracefully on an empty graph and never hard-depends on ``rich``.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import logging
+import os
+from typing import Dict, List, Optional
+
+from falsify import graph_ops
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.utils")
+
+# truth-state -> (console tag, hex color for the graph)
+_STATE_STYLE = {
+    TruthState.ALIVE.value: ("ALIVE", "#22c55e"),
+    TruthState.REFUTED.value: ("REFUTED", "#ef4444"),
+    TruthState.INVALIDATED.value: ("INVALIDATED", "#9ca3af"),
+    TruthState.SUPERSEDED.value: ("SUPERSEDED", "#f59e0b"),
+    TruthState.FORGOTTEN.value: ("FORGOTTEN", "#4b5563"),
+}
+
+# ANSI colors for console tags (fall back to plain text if not a TTY).
+_ANSI = {
+    "ALIVE": "\033[92m",
+    "REFUTED": "\033[91m",
+    "INVALIDATED": "\033[90m",
+    "SUPERSEDED": "\033[93m",
+    "FORGOTTEN": "\033[90m",
+}
+_RESET = "\033[0m"
+
+
+def _colored(tag: str) -> str:
+    """Return an ANSI-colored tag if stdout is a TTY, else the plain tag."""
+    if os.environ.get("NO_COLOR") or not _stdout_is_tty():
+        return tag
+    return f"{_ANSI.get(tag, '')}{tag}{_RESET}"
+
+
+def _stdout_is_tty() -> bool:
+    try:
+        import sys
+
+        return bool(sys.stdout.isatty())
+    except Exception:
+        return False
+
+
+async def _state_of(node_ids: List[str]) -> Dict[str, str]:
+    """Return ``{id: single-state-string}`` (first alignment entry, default alive)."""
+    truth = await graph_ops.get_truth(node_ids)
+    return {nid: (align[0] if align else TruthState.ALIVE.value) for nid, align in truth.items()}
+
+
+async def get_belief_summary(dataset: Optional[str] = None) -> Dict[str, Dict[str, int]]:
+    """Count nodes grouped by node type and truth-state.
+
+    Returns e.g. ``{"Hypothesis": {"alive": 2, "superseded": 1}, "Conclusion": {...}}``.
+    Node type is inferred from the node's ``type`` property, falling back to the
+    dominant embeddable field present.
+    """
+    nodes, _edges = await graph_ops.load_graph()
+    if not nodes:
+        return {}
+    states = await _state_of([str(nid) for nid, _p in nodes])
+    summary: Dict[str, Dict[str, int]] = {}
+    for nid, props in nodes:
+        ntype = _infer_type(props)
+        state = states.get(str(nid), TruthState.ALIVE.value)
+        summary.setdefault(ntype, {})
+        summary[ntype][state] = summary[ntype].get(state, 0) + 1
+    return summary
+
+
+def _infer_type(props: dict) -> str:
+    """Best-effort node-type label from properties."""
+    if props.get("type"):
+        return str(props["type"])
+    for field, label in (
+        ("question", "InvestigationQuestion"),
+        ("claim", "Evidence"),
+        ("statement", "Hypothesis/Conclusion"),
+        ("text", "Assertion"),
+    ):
+        if props.get(field):
+            return label
+    return "Node"
+
+
+async def print_graph_state(title: str, dataset: Optional[str] = None) -> None:
+    """Print every node with a colored truth-state tag (the BEFORE/AFTER beat)."""
+    nodes, _edges = await graph_ops.load_graph()
+    print(f"\n{'=' * 64}\n  {title}\n{'=' * 64}")
+    if not nodes:
+        print("  (empty graph)")
+        return
+    states = await _state_of([str(nid) for nid, _p in nodes])
+    # Stable, readable ordering: questions, hypotheses, evidence, conclusions.
+    order = {"InvestigationQuestion": 0, "Hypothesis/Conclusion": 1, "Evidence": 2, "Assertion": 3}
+    rows = []
+    for nid, props in nodes:
+        ntype = _infer_type(props)
+        state = states.get(str(nid), TruthState.ALIVE.value)
+        tag = _STATE_STYLE.get(state, ("ALIVE", ""))[0]
+        label = graph_ops.node_label(props)
+        rows.append((order.get(ntype, 9), ntype, tag, label))
+    for _o, ntype, tag, label in sorted(rows, key=lambda r: r[0]):
+        clipped = label if len(label) <= 66 else label[:63] + "..."
+        print(f"  [{_colored(tag):<22}] {ntype:<22} {clipped}")
+    print()
+
+
+async def visualize_belief_graph(
+    out_path: str = "output/graph.html",
+    dataset: Optional[str] = None,
+    title: str = "FALSIFY belief graph",
+) -> Optional[str]:
+    """Write a self-contained interactive HTML visualization of the belief graph.
+
+    Nodes are colored by truth-state (green/red/grey/amber). Refuted nodes are drawn
+    with a dashed red border so the cascade result reads at a glance. Returns the
+    written path, or ``None`` if the graph is empty.
+    """
+    nodes, edges = await graph_ops.load_graph()
+    if not nodes:
+        logger.info("visualize_belief_graph: empty graph, nothing to draw")
+        return None
+
+    states = await _state_of([str(nid) for nid, _p in nodes])
+
+    vis_nodes = []
+    for nid, props in nodes:
+        nid = str(nid)
+        state = states.get(nid, TruthState.ALIVE.value)
+        tag, color = _STATE_STYLE.get(state, ("ALIVE", "#22c55e"))
+        label = graph_ops.node_label(props)
+        short = label if len(label) <= 40 else label[:37] + "..."
+        vis_nodes.append(
+            {
+                "id": nid,
+                "label": short,
+                "title": f"{_infer_type(props)} — {tag}\n{html.escape(label)}",
+                "color": {"background": color, "border": "#111827"},
+                "shapeProperties": {"borderDashes": state == TruthState.REFUTED.value},
+                "borderWidth": 3 if state == TruthState.REFUTED.value else 1,
+                "font": {"color": "#0b1020"},
+            }
+        )
+
+    vis_edges = []
+    for src, dst, rel, props in edges:
+        vis_edges.append(
+            {
+                "from": str(src),
+                "to": str(dst),
+                "label": rel,
+                "arrows": "to",
+                "font": {"align": "middle", "size": 10},
+                "color": {"color": "#94a3b8"},
+            }
+        )
+
+    os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
+    doc = _HTML_TEMPLATE.replace("__TITLE__", html.escape(title)) \
+        .replace("__NODES__", json.dumps(vis_nodes)) \
+        .replace("__EDGES__", json.dumps(vis_edges))
+    with open(out_path, "w", encoding="utf-8") as fh:
+        fh.write(doc)
+    logger.info("wrote visualization to %s (%d nodes, %d edges)", out_path, len(vis_nodes), len(vis_edges))
+    return out_path
+
+
+async def verify_propagation(refuted_id: str, expected_affected: List[str]) -> bool:
+    """Test helper: assert every ``expected_affected`` id is now non-alive.
+
+    Returns True iff the refuted node is refuted and each expected dependent is in a
+    dead state (refuted/invalidated/forgotten or absent from the graph).
+    """
+    ids = [str(refuted_id)] + [str(x) for x in expected_affected]
+    truth = await graph_ops.get_truth(ids)
+    dead = {TruthState.REFUTED.value, TruthState.INVALIDATED.value, TruthState.FORGOTTEN.value}
+    nodes, _edges = await graph_ops.load_graph()
+    present = {str(nid) for nid, _p in nodes}
+
+    r_align = truth.get(str(refuted_id), [])
+    if TruthState.REFUTED.value not in r_align:
+        return False
+    for dep in expected_affected:
+        dep = str(dep)
+        if dep not in present:  # forgotten (deleted) counts as affected
+            continue
+        if not any(s in dead for s in truth.get(dep, [TruthState.ALIVE.value])):
+            return False
+    return True
+
+
+_HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>__TITLE__</title>
+  <script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+  <style>
+    body { margin:0; font-family: ui-sans-serif, system-ui, sans-serif; background:#0b1020; color:#e5e7eb; }
+    #hdr { padding:14px 18px; font-size:18px; font-weight:600; border-bottom:1px solid #1f2937; }
+    #legend { padding:8px 18px; font-size:13px; color:#9ca3af; }
+    .chip { display:inline-block; width:11px; height:11px; border-radius:3px; margin:0 5px 0 14px; vertical-align:middle; }
+    #net { width:100%; height:calc(100vh - 92px); }
+  </style>
+</head>
+<body>
+  <div id="hdr">__TITLE__</div>
+  <div id="legend">
+    <span class="chip" style="background:#22c55e"></span>alive
+    <span class="chip" style="background:#ef4444"></span>refuted
+    <span class="chip" style="background:#9ca3af"></span>invalidated
+    <span class="chip" style="background:#f59e0b"></span>superseded
+  </div>
+  <div id="net"></div>
+  <script>
+    const nodes = new vis.DataSet(__NODES__);
+    const edges = new vis.DataSet(__EDGES__);
+    const container = document.getElementById('net');
+    const options = {
+      physics: { stabilization: true, barnesHut: { gravitationalConstant: -8000, springLength: 150 } },
+      nodes: { shape: 'box', margin: 10, widthConstraint: { maximum: 200 } },
+      edges: { smooth: { type: 'cubicBezier' } }
+    };
+    new vis.Network(container, { nodes, edges }, options);
+  </script>
+</body>
+</html>
+"""

cognee-hackathon-project-main/main.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+FALSIFY — the AI research copilot that *revises*, not forgets.
+
+Run this to watch belief revision happen on a real Cognee knowledge graph:
+
+    python main.py            # full run (uses your LLM to judge the contradiction)
+    python main.py --demo     # deterministic: pins the contradiction so the cascade
+                              #   always runs, even without/with a flaky LLM key
+    python main.py --keep     # don't prune existing memory first (advanced)
+
+The story (Company X recall investigation)
+------------------------------------------
+Session 1 builds a belief graph with two competing hypotheses:
+    A — "X knew via the March 2021 QA report"        (supported by evidence E_qa)
+    B — "X knew via a January 2021 supplier email"   (supported by evidence E_email)
+and a Conclusion K that *depends on* E_qa.
+
+Session 2 drops ONE contradicting fact: "the March QA report was back-dated."
+FALSIFY refutes E_qa, cascades the refutation forward (K collapses), promotes B as
+the new frontier, and surgically forgets the orphaned conclusion — writing the
+disbelief onto the graph so it survives a restart. A plain-RAG baseline, which has no
+notion of truth-state, keeps citing the refuted March report. That contrast is the
+whole point: *AI revised, not forgot.*
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+# Load .env before importing cognee/falsify so provider config is in place.
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except Exception:  # python-dotenv is optional; env may be set another way
+    pass
+
+# Importing falsify sets single-user Cognee env defaults (access control off, cache on).
+import falsify  # noqa: F401  (import-time side effects)
+from falsify.seed import NEW_FACT, QUESTION_TEXT
+
+
+C = {
+    "b": "\033[1m", "dim": "\033[2m", "g": "\033[92m", "r": "\033[91m",
+    "y": "\033[93m", "c": "\033[96m", "x": "\033[0m",
+}
+if os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+    C = {k: "" for k in C}
+
+
+def banner(text: str) -> None:
+    print(f"\n{C['b']}{C['c']}{'━' * 64}{C['x']}")
+    print(f"{C['b']}{C['c']}  {text}{C['x']}")
+    print(f"{C['b']}{C['c']}{'━' * 64}{C['x']}")
+
+
+def _has_llm_key() -> bool:
+    """True if some LLM API key is configured (OpenAI-compatible or otherwise)."""
+    for var in ("LLM_API_KEY", "OPENAI_API_KEY"):
+        if os.environ.get(var):
+            return True
+    return False
+
+
+def _print_no_key_help() -> None:
+    print(
+        f"""
+{C['y']}{C['b']}No LLM API key found.{C['x']}
+
+FALSIFY needs an OpenAI-compatible API key to (a) embed claims for the vector
+prefilter and (b) judge contradictions. Set it up:
+
+  1. cp .env.template .env
+  2. edit .env and set:
+       LLM_API_KEY="your_key_here"
+       LLM_MODEL="gpt-4o-mini"          # or any OpenAI-compatible model
+       # For a non-OpenAI endpoint (OpenRouter, vLLM, LM Studio, Groq):
+       #   LLM_PROVIDER="custom"
+       #   LLM_ENDPOINT="https://your-endpoint/v1"
+  3. re-run:  python main.py
+
+{C['dim']}Tip: `python main.py --demo` runs FULLY OFFLINE — fastembed handles
+embeddings locally and the contradiction is pinned, so no API key is needed at all.
+A key is only required for LIVE mode, where the LLM judges the contradiction.{C['x']}
+"""
+    )
+
+
+async def run(demo: bool, keep: bool) -> int:
+    from falsify.falsify import build_graph, revise, scoreboard
+    from falsify.utils import get_belief_summary, print_graph_state, visualize_belief_graph
+
+    banner("FALSIFY — belief-revision research copilot")
+    print(f"  Research question: {C['b']}{QUESTION_TEXT}{C['x']}")
+    print(f"  Mode: {'DEMO (deterministic contradiction pin)' if demo else 'LIVE (LLM judge)'}")
+
+    # ---- Session 1: build the belief graph -------------------------------
+    banner("SESSION 1 — build the investigation")
+    if keep:
+        from cognee.low_level import setup
+
+        from falsify.seed import build_investigation
+
+        await setup()
+        seeded = await build_investigation()
+    else:
+        seeded = await build_graph()
+    await print_graph_state("BEFORE — both hypotheses stand, Conclusion K rests on E_qa")
+
+    # ---- Session 2: drop the contradicting fact --------------------------
+    banner("SESSION 2 — a new fact arrives")
+    print(f"  {C['y']}New fact:{C['x']} {NEW_FACT}\n")
+
+    pinned = seeded.refuted_target_id if demo else None
+    report = await revise(NEW_FACT, pinned_target_id=pinned)
+
+    if not report.revised:
+        print(f"  {C['y']}No contradiction was confirmed — graph unchanged.{C['x']}")
+        print(f"  {C['dim']}(Try `python main.py --demo` to force the cascade deterministically.){C['x']}")
+    else:
+        print(f"  {C['r']}✗ refuted:{C['x']} {len(report.refuted)} evidence node(s)")
+        print(f"  {C['r']}✗ invalidated:{C['x']} {len(report.invalidated)} conclusion(s)")
+        for hid, action in report.hypothesis_actions.items():
+            if action == "superseded":
+                mark = f"{C['r']}↓ superseded{C['x']}"
+            else:
+                mark = f"{C['g']}↑ promoted (new frontier){C['x']}"
+            print(f"     hypothesis {hid[:8]} → {mark}")
+        for fid in report.forgotten:
+            label = report.forgotten_labels.get(fid, fid)
+            print(f"  {C['dim']}🗑 forgotten (deleted from graph + vector):{C['x']} {label}")
+        if report.retained_provenance:
+            print(f"  {C['dim']}⚑ kept as red provenance:{C['x']} {len(report.retained_provenance)} node(s)")
+
+    await print_graph_state("AFTER — refutation cascaded, B ignites, orphan forgotten")
+
+    # ---- The scoreboard: FALSIFY vs plain RAG ----------------------------
+    banner("SCOREBOARD — FALSIFY (revised) vs plain RAG (stale)")
+    board = await scoreboard(QUESTION_TEXT, seeded)
+    print(f"  {C['g']}{C['b']}FALSIFY :{C['x']} {board.falsify_answer}")
+    if board.falsify_support:
+        print(f"            {C['dim']}supported by: {', '.join(board.falsify_support)}{C['x']}")
+    rag_tag = f"{C['r']}[STALE — still cites a refuted fact]{C['x']}" if board.stale else ""
+    print(f"  {C['y']}{C['b']}RAG     :{C['x']} {board.rag_answer} {rag_tag}")
+    print(f"\n  {C['b']}→ AI revised, not forgot.{C['x']}")
+
+    # ---- Cross-session proof: reload belief state fresh ------------------
+    banner("CROSS-SESSION PROOF — reopen memory, beliefs stay revised")
+    summary = await get_belief_summary()
+    print(f"  Persisted belief state (re-read from graph): {summary}")
+    print(f"  {C['dim']}Truth-state lives on the graph nodes, so a brand-new process sees the")
+    print(f"  revised graph — the refuted branch never comes back.{C['x']}")
+
+    # ---- Visualization ---------------------------------------------------
+    out = await visualize_belief_graph("output/graph.html", title="FALSIFY — Company X investigation")
+    if out:
+        banner("VISUALIZATION")
+        print(f"  Interactive belief graph written to: {C['b']}{os.path.abspath(out)}{C['x']}")
+        print(f"  {C['dim']}Open it in a browser — red = refuted, grey = invalidated, green = alive.{C['x']}")
+
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="FALSIFY belief-revision demo")
+    parser.add_argument("--demo", action="store_true",
+                        help="pin the contradiction deterministically (LLM-independent cascade)")
+    parser.add_argument("--keep", action="store_true",
+                        help="do not prune existing memory before building")
+    args = parser.parse_args()
+
+    if not _has_llm_key() and not args.demo:
+        _print_no_key_help()
+        # Live mode needs an LLM key to judge the contradiction. Exit cleanly (0) with
+        # setup help rather than a stack trace. (`--demo` runs fully offline below.)
+        return 0
+
+    try:
+        return asyncio.run(run(demo=args.demo, keep=args.keep))
+    except KeyboardInterrupt:
+        print("\ninterrupted.")
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cognee-hackathon-project-main/requirements.txt

@@ -0,0 +1,13 @@
+# FALSIFY — dependencies
+#
+# The only hard requirement is Cognee (the self-hosted AI-memory platform this
+# project is built on). Everything else is small tooling. Cognee itself pulls in
+# LanceDB / Ladybug / SQLite / litellm, so there is no separate DB to install.
+
+cognee>=0.1.0          # AI-memory platform: graph + vector + memify/forget APIs
+fastembed>=0.3.0       # local, CPU-only embeddings (no API key needed for the demo)
+python-dotenv>=1.0.0   # load .env configuration
+
+# ── dev / test (optional: pip install -r requirements.txt already includes these) ──
+pytest>=7.4.0
+pytest-asyncio>=0.21.0

cognee-hackathon-project-main/tests/__init__.py

@@ -0,0 +1 @@
+"""FALSIFY test suite."""

cognee-hackathon-project-main/tests/conftest.py

@@ -0,0 +1,97 @@
+"""
+Pytest fixtures for FALSIFY.
+
+The core belief-revision logic (refutation propagation, orphan forget, hypothesis
+promotion) is pure graph reasoning: given nodes, typed edges, and truth-states, it
+decides what to flip and what to delete. We test that logic against an in-memory
+:class:`FakeGraph` that stands in for Cognee's graph/vector engines — so the whole
+suite runs with **no API key, no database, no network**.
+
+Only the handful of *engine-touching* helpers in :mod:`falsify.graph_ops` are
+monkeypatched (``load_graph``, ``get_truth``, ``set_state``, ``set_weight``,
+``delete_from_both_stores``, ``get_vector_engine``). The pure adjacency helpers
+(``dependents_of``, ``incoming``, ``outgoing``, ``node_label``) are exercised as-is,
+so the tests cover the real code paths.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+import pytest
+
+from falsify import graph_ops
+from falsify.models import TruthState
+
+Edge = Tuple[str, str, str, Dict[str, Any]]
+Node = Tuple[str, Dict[str, Any]]
+
+
+class FakeGraph:
+    """A minimal in-memory graph mimicking the subset of the engine FALSIFY uses.
+
+    Nodes are ``{id: props}``; edges are ``(src, dst, rel, props)`` tuples; truth is
+    ``{id: {"truth_alignment": [...], "truth_epoch": n}}``. Deletions remove nodes and
+    record deleted ids/collections so tests can assert vector cleanup happened.
+    """
+
+    def __init__(self) -> None:
+        self.nodes: Dict[str, Dict[str, Any]] = {}
+        self.edges: List[Edge] = []
+        self.truth: Dict[str, Dict[str, Any]] = {}
+        self.weights: Dict[str, float] = {}
+        self.deleted: List[str] = []
+        self.deleted_from_collections: List[str] = []
+
+    # -- builders -------------------------------------------------------
+    def add_node(self, nid: str, **props: Any) -> str:
+        self.nodes[nid] = props
+        self.truth.setdefault(nid, {"truth_alignment": [TruthState.ALIVE.value], "truth_epoch": 0})
+        return nid
+
+    def add_edge(self, src: str, dst: str, rel: str, **props: Any) -> None:
+        self.edges.append((src, dst, rel, props))
+
+    # -- engine-shaped async API (monkeypatched onto graph_ops) ---------
+    async def load_graph(self) -> Tuple[List[Node], List[Edge]]:
+        nodes = [(nid, dict(props)) for nid, props in self.nodes.items()]
+        return nodes, list(self.edges)
+
+    async def get_truth(self, node_ids: List[str]) -> Dict[str, List[str]]:
+        out: Dict[str, List[str]] = {}
+        for nid in node_ids:
+            entry = self.truth.get(str(nid))
+            out[str(nid)] = list(entry["truth_alignment"]) if entry else [TruthState.ALIVE.value]
+        return out
+
+    async def set_state(self, node_id: str, state: TruthState, epoch: int) -> None:
+        value = state.value if isinstance(state, TruthState) else str(state)
+        self.truth[str(node_id)] = {"truth_alignment": [value], "truth_epoch": int(epoch)}
+
+    async def set_weight(self, node_id: str, weight: float) -> None:
+        self.weights[str(node_id)] = float(weight)
+
+    async def delete_from_both_stores(self, node_ids: List[str], collections: List[str]) -> int:
+        for nid in node_ids:
+            self.nodes.pop(str(nid), None)
+            self.truth.pop(str(nid), None)
+            self.deleted.append(str(nid))
+        self.edges = [e for e in self.edges if e[0] not in node_ids and e[1] not in node_ids]
+        self.deleted_from_collections.extend(collections)
+        return len(node_ids)
+
+
+@pytest.fixture
+def fake_graph(monkeypatch) -> FakeGraph:
+    """Install a :class:`FakeGraph` in place of the real engine helpers.
+
+    Returns the graph so a test can build topology (``add_node``/``add_edge``) and
+    later assert on final truth-states and deletions.
+    """
+    g = FakeGraph()
+    monkeypatch.setattr(graph_ops, "load_graph", g.load_graph)
+    monkeypatch.setattr(graph_ops, "get_truth", g.get_truth)
+    monkeypatch.setattr(graph_ops, "set_state", g.set_state)
+    monkeypatch.setattr(graph_ops, "set_weight", g.set_weight)
+    monkeypatch.setattr(graph_ops, "delete_from_both_stores", g.delete_from_both_stores)
+    return g

cognee-hackathon-project-main/tests/test_detect.py

@@ -0,0 +1,93 @@
+"""
+Tests for the two-gate contradiction detector — no live LLM required.
+
+* The ``--demo`` / ``pinned_target_id`` path bypasses both gates and must return a
+  deterministic high-confidence verdict (this is what keeps the live demo reliable).
+* The Gate-2 path is exercised with a monkeypatched ``LLMGateway`` so we test the
+  accept/reject thresholding without any API key.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from falsify import graph_ops
+from falsify.tasks import detect_contradictions
+from falsify.tasks.detect_contradictions import ContradictionJudgement
+
+pytestmark = pytest.mark.asyncio
+
+
+async def test_pinned_target_is_deterministic():
+    """Pinned mode returns exactly one high-confidence 'contradicts' verdict."""
+    out = await detect_contradictions("any new fact", pinned_target_id="E_qa")
+    assert len(out) == 1
+    assert out[0].target_id == "E_qa"
+    assert out[0].relation == "contradicts"
+    assert out[0].confidence >= 0.6
+
+
+class _FakeHit:
+    def __init__(self, _id, score, payload):
+        self.id = _id
+        self.score = score
+        self.payload = payload
+
+
+class _FakeVectorEngine:
+    def __init__(self, hits):
+        self._hits = hits
+
+    async def search(self, collection, query_text=None, limit=15, include_payload=False, **kw):
+        return self._hits
+
+
+async def test_gate2_accepts_high_confidence_contradiction(monkeypatch):
+    """An on-topic candidate judged 'contradicts' with conf>=0.6 is returned."""
+    hits = [_FakeHit("E_qa", 0.10, {"claim": "March QA report documents the defect"})]
+    monkeypatch.setattr(graph_ops, "get_vector_engine", lambda: _FakeVectorEngine(hits))
+
+    async def fake_llm(text_input, system_prompt, response_model, **kw):
+        return ContradictionJudgement(relation="contradicts", confidence=0.9, rationale="back-dated")
+
+    from cognee.infrastructure.llm.LLMGateway import LLMGateway
+    monkeypatch.setattr(LLMGateway, "acreate_structured_output", staticmethod(fake_llm))
+
+    out = await detect_contradictions("the report was back-dated")
+    assert len(out) == 1
+    assert out[0].target_id == "E_qa"
+    assert out[0].relation == "contradicts"
+
+
+async def test_gate1_filters_off_topic(monkeypatch):
+    """A candidate beyond the distance threshold is filtered before the LLM runs."""
+    hits = [_FakeHit("E_far", 0.90, {"claim": "unrelated topic"})]
+    monkeypatch.setattr(graph_ops, "get_vector_engine", lambda: _FakeVectorEngine(hits))
+
+    called = {"llm": False}
+
+    async def fake_llm(text_input, system_prompt, response_model, **kw):
+        called["llm"] = True
+        return ContradictionJudgement(relation="contradicts", confidence=1.0)
+
+    from cognee.infrastructure.llm.LLMGateway import LLMGateway
+    monkeypatch.setattr(LLMGateway, "acreate_structured_output", staticmethod(fake_llm))
+
+    out = await detect_contradictions("some fact", distance_threshold=0.35)
+    assert out == []
+    assert called["llm"] is False  # Gate-1 rejected it; LLM never consulted
+
+
+async def test_gate2_rejects_low_confidence(monkeypatch):
+    """On-topic but low-confidence verdicts are not treated as contradictions."""
+    hits = [_FakeHit("E_qa", 0.10, {"claim": "March QA report"})]
+    monkeypatch.setattr(graph_ops, "get_vector_engine", lambda: _FakeVectorEngine(hits))
+
+    async def fake_llm(text_input, system_prompt, response_model, **kw):
+        return ContradictionJudgement(relation="contradicts", confidence=0.2, rationale="unsure")
+
+    from cognee.infrastructure.llm.LLMGateway import LLMGateway
+    monkeypatch.setattr(LLMGateway, "acreate_structured_output", staticmethod(fake_llm))
+
+    out = await detect_contradictions("weak signal")
+    assert out == []

cognee-hackathon-project-main/tests/test_falsify.py

@@ -0,0 +1,163 @@
+"""
+FALSIFY core-logic tests — belief revision without any API key or database.
+
+Each test builds a small graph via the :class:`~tests.conftest.FakeGraph` fixture,
+runs the real cascade/forget code, and asserts on the resulting truth-states. These
+cover the correctness cases enumerated in REQUIREMENTS.md §4.3:
+
+    * direct refutation                       (test_direct_refutation)
+    * forward cascade invalidates conclusion  (test_forward_cascade_invalidates)
+    * diamond / partial refutation            (test_diamond_partial_refutation)
+    * non-critical dependency survives         (test_non_critical_dependency_survives)
+    * cycle safety (termination)              (test_cycle_safety)
+    * surgical forget of orphans only         (test_forget_orphan_keeps_provenance)
+    * hypothesis demote/promote               (test_promote_competing_hypothesis)
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from falsify.edges import DEPENDS_ON, SUPERSEDES, SUPPORTS
+from falsify.models import TruthState
+from falsify.tasks.cascade_forget import cascade_forget
+from falsify.tasks.propagate_refutation import (
+    promote_competing_hypothesis,
+    propagate_refutation,
+)
+
+pytestmark = pytest.mark.asyncio
+
+
+async def _alignment(g, nid: str):
+    entry = g.truth.get(str(nid))
+    return entry["truth_alignment"] if entry else None
+
+
+async def test_direct_refutation(fake_graph):
+    """Refuting an evidence node sets its truth_alignment to ['refuted']."""
+    g = fake_graph
+    g.add_node("E", claim="the March QA report documents the defect")
+
+    res = await propagate_refutation(["E"])
+
+    assert res.refuted == ["E"]
+    assert await _alignment(g, "E") == [TruthState.REFUTED.value]
+
+
+async def test_forward_cascade_invalidates(fake_graph):
+    """A→B→C depends_on chain: refuting the base evidence invalidates the chain.
+
+    Topology (depends_on points Conclusion→Evidence):
+        C  --depends_on(critical)-->  B  --depends_on(critical)-->  E(evidence)
+    Refuting E must invalidate B, then C.
+    """
+    g = fake_graph
+    g.add_node("E", claim="base evidence")
+    g.add_node("B", statement="mid conclusion")
+    g.add_node("C", statement="top conclusion")
+    g.add_edge("B", "E", DEPENDS_ON, critical=True)
+    g.add_edge("C", "B", DEPENDS_ON, critical=True)
+
+    res = await propagate_refutation(["E"])
+
+    assert await _alignment(g, "E") == [TruthState.REFUTED.value]
+    assert await _alignment(g, "B") == [TruthState.INVALIDATED.value]
+    assert await _alignment(g, "C") == [TruthState.INVALIDATED.value]
+    assert set(res.invalidated) == {"B", "C"}
+
+
+async def test_diamond_partial_refutation(fake_graph):
+    """A conclusion with two critical supporters survives losing only one.
+
+    K depends_on E1 (critical) AND E2 (critical). Refuting only E1 must keep K alive
+    (E2 still supports it); refuting E2 as well then invalidates K.
+    """
+    g = fake_graph
+    g.add_node("E1", claim="evidence one")
+    g.add_node("E2", claim="evidence two")
+    g.add_node("K", statement="conclusion on both")
+    g.add_edge("K", "E1", DEPENDS_ON, critical=True)
+    g.add_edge("K", "E2", DEPENDS_ON, critical=True)
+
+    # First refutation: K keeps an alive critical supporter (E2) -> stays alive.
+    await propagate_refutation(["E1"])
+    assert await _alignment(g, "E1") == [TruthState.REFUTED.value]
+    assert await _alignment(g, "K") == [TruthState.ALIVE.value]
+
+    # Second refutation: K loses its last critical supporter -> invalidated.
+    await propagate_refutation(["E2"])
+    assert await _alignment(g, "K") == [TruthState.INVALIDATED.value]
+
+
+async def test_non_critical_dependency_survives(fake_graph):
+    """Refuting a NON-critical dependency weakens but does not invalidate."""
+    g = fake_graph
+    g.add_node("E", claim="soft evidence")
+    g.add_node("K", statement="conclusion softly resting on E")
+    g.add_edge("K", "E", DEPENDS_ON, critical=False)
+
+    res = await propagate_refutation(["E"])
+
+    assert await _alignment(g, "K") == [TruthState.ALIVE.value]
+    assert "K" in res.weakened
+    assert "K" not in res.invalidated
+
+
+async def test_cycle_safety(fake_graph):
+    """A cyclic depends_on graph terminates (visited set) and doesn't hang."""
+    g = fake_graph
+    g.add_node("E", claim="evidence")
+    g.add_node("X", statement="X")
+    g.add_node("Y", statement="Y")
+    # Cycle among conclusions, all critically resting on E and each other.
+    g.add_edge("X", "E", DEPENDS_ON, critical=True)
+    g.add_edge("Y", "X", DEPENDS_ON, critical=True)
+    g.add_edge("X", "Y", DEPENDS_ON, critical=True)
+
+    res = await propagate_refutation(["E"])  # must return, not loop forever
+
+    assert await _alignment(g, "E") == [TruthState.REFUTED.value]
+    assert "X" in res.invalidated and "Y" in res.invalidated
+
+
+async def test_forget_orphan_keeps_provenance(fake_graph):
+    """cascade_forget deletes an orphaned invalidated conclusion but keeps the
+    refuted evidence that is a supersedes-anchor (provenance tombstone)."""
+    g = fake_graph
+    g.add_node("E", claim="refuted evidence")
+    g.add_node("K", statement="orphaned conclusion")
+    g.add_node("NEW", claim="the new fact")
+    g.add_edge("K", "E", DEPENDS_ON, critical=True)
+    g.add_edge("NEW", "E", SUPERSEDES, confidence=0.9)  # NEW (alive) supersedes E
+
+    # Run the cascade, then forget.
+    prop = await propagate_refutation(["E"])
+    forget = await cascade_forget(prop.affected)
+
+    # K is orphaned (no alive consumer) -> deleted from both stores.
+    assert "K" in forget.forgotten
+    assert "K" in g.deleted
+    assert g.deleted_from_collections  # vector collections were targeted
+    # E is refuted but retained as the supersedes provenance anchor.
+    assert "E" in forget.retained_provenance
+    assert "E" not in g.deleted
+
+
+async def test_promote_competing_hypothesis(fake_graph):
+    """When A's only support dies, A is superseded and rival B is promoted."""
+    g = fake_graph
+    g.add_node("E_a", claim="evidence for A")
+    g.add_node("E_b", claim="evidence for B")
+    g.add_node("A", statement="hypothesis A")
+    g.add_node("B", statement="hypothesis B")
+    g.add_edge("E_a", "A", SUPPORTS, weight=0.8)
+    g.add_edge("E_b", "B", SUPPORTS, weight=0.7)
+
+    # Refute A's evidence, then re-score hypotheses.
+    prop = await propagate_refutation(["E_a"])
+    actions = await promote_competing_hypothesis(["E_a"], prop.epoch)
+
+    assert actions.get("A") == "superseded"
+    assert actions.get("B") == "promoted"
+    assert await _alignment(g, "A") == [TruthState.SUPERSEDED.value]

cognee-hackathon-project-main/tools/make_demo_gif.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""
+Build the FALSIFY demo GIF from a LIVE run (Qwen judges the contradiction).
+
+The belief graph is rendered natively with Pillow (no browser needed) from the real
+node/edge/truth-state data, so the GIF shows the actual graph transforming:
+
+    BEFORE : every node green (alive)
+    AFTER  : E_qa red (refuted), K removed (forgotten), A amber (superseded),
+             B green (the new frontier)
+
+Frames: title -> Session 1 -> BEFORE graph -> Session 2 (the fact) -> AFTER graph
+        -> scoreboard -> closing.
+
+Run:  python tools/make_demo_gif.py           # live (needs .env LLM key)
+      python tools/make_demo_gif.py --demo    # offline (pinned contradiction)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+from dotenv import load_dotenv
+
+load_dotenv(os.path.join(os.path.dirname(__file__), "..", ".env"))
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+import falsify  # noqa: E402
+from falsify import graph_ops  # noqa: E402
+from falsify.models import TruthState  # noqa: E402
+
+from PIL import Image, ImageDraw, ImageFont  # noqa: E402
+
+W, H = 1000, 700
+BG = (11, 16, 32)
+PANEL = (17, 24, 39)
+FG = (229, 231, 235)
+GREEN = (34, 197, 94)
+RED = (239, 68, 68)
+AMBER = (245, 158, 11)
+GREY = (107, 114, 128)
+DIM = (148, 163, 184)
+CYAN = (34, 211, 238)
+EDGE = (71, 85, 105)
+
+FONT_DIR = "/usr/share/fonts/truetype/dejavu"
+
+STATE_COLOR = {
+    TruthState.ALIVE.value: GREEN,
+    TruthState.REFUTED.value: RED,
+    TruthState.INVALIDATED.value: GREY,
+    TruthState.SUPERSEDED.value: AMBER,
+}
+
+# Fixed layout for the 7-node Company-X graph (x, y = node center).
+LAYOUT = {
+    "Q": (500, 130),
+    "A": (215, 300), "B": (500, 300), "C": (785, 300),
+    "E_qa": (215, 470), "E_email": (500, 470),
+    "K": (215, 615),
+}
+SHORT = {
+    "Q": "Q: Did X know\nbefore recall?",
+    "A": "Hyp A\nMar QA report",
+    "B": "Hyp B\nJan email",
+    "C": "Hyp C\ndidn't know",
+    "E_qa": "E_qa\nMarch QA report",
+    "E_email": "E_email\nJan supplier email",
+    "K": "K: knew by\nMarch 2021",
+}
+# edges as (src_key, dst_key, label)
+EDGES = [
+    ("A", "Q", "answers"), ("B", "Q", "answers"), ("C", "Q", "answers"),
+    ("E_qa", "A", "supports"), ("E_email", "B", "supports"),
+    ("K", "E_qa", "depends_on"),
+]
+
+
+def font(size, bold=False, mono=False):
+    if mono:
+        name = "DejaVuSansMono-Bold.ttf" if bold else "DejaVuSansMono.ttf"
+    else:
+        name = "DejaVuSans-Bold.ttf" if bold else "DejaVuSans.ttf"
+    return ImageFont.truetype(os.path.join(FONT_DIR, name), size)
+
+
+def _center(d, text, f, y, color=FG):
+    w = d.textlength(text, font=f)
+    d.text(((W - w) / 2, y), text, font=f, fill=color)
+
+
+def card(lines):
+    img = Image.new("RGB", (W, H), BG)
+    d = ImageDraw.Draw(img)
+    for text, size, bold, color, y in lines:
+        _center(d, text, font(size, bold), y, color)
+    return img
+
+
+def title_card():
+    return card([
+        ("FALSIFY", 92, True, CYAN, 200),
+        ("the AI that revises, not forgets", 34, False, FG, 315),
+        ("belief revision on a Cognee knowledge graph", 22, False, DIM, 378),
+    ])
+
+
+def session1_card():
+    return card([
+        ("SESSION 1", 42, True, CYAN, 150),
+        ("Build the belief graph", 30, False, FG, 222),
+        ("Q: Did Company X know about the defect before the recall?", 21, False, DIM, 300),
+        ("A — via March 2021 QA report     B — via Jan 2021 email", 20, False, FG, 358),
+        ("Conclusion K depends on the March QA report", 19, False, DIM, 408),
+    ])
+
+
+def session2_card():
+    return card([
+        ("SESSION 2", 42, True, CYAN, 150),
+        ("One contradicting fact arrives", 30, False, FG, 224),
+        ('"A forensic audit found the March 2021', 25, True, AMBER, 322),
+        ('QA report was back-dated."', 25, True, AMBER, 364),
+    ])
+
+
+def scoreboard_card(falsify_ans, stale):
+    ans = falsify_ans if len(falsify_ans) <= 58 else falsify_ans[:57] + "…"
+    return card([
+        ("SCOREBOARD", 42, True, CYAN, 120),
+        ("FALSIFY  (revised)", 30, True, GREEN, 220),
+        (ans, 22, False, FG, 272),
+        ("plain RAG  (stale)", 30, True, RED, 362),
+        ("still anchored to the refuted March QA report", 21, False, DIM, 414),
+        ("AI revised, not forgot.", 36, True, FG, 520),
+    ])
+
+
+def closing_card():
+    return card([
+        ("FALSIFY", 76, True, CYAN, 240),
+        ("revise, don't forget.", 30, False, FG, 355),
+        ("github.com/ArpitKumar8649/cognee-hackathon-project", 18, False, DIM, 430),
+    ])
+
+
+def _round_rect(d, box, radius, fill, outline, width=2, dashed=False):
+    d.rounded_rectangle(box, radius=radius, fill=fill, outline=outline, width=width)
+
+
+def draw_graph(states: dict, deleted: set, caption: str, sub: str) -> Image.Image:
+    """Render the belief graph. `states` maps node-key -> truth-state string."""
+    img = Image.new("RGB", (W, H), BG)
+    d = ImageDraw.Draw(img)
+
+    # caption banner
+    d.rectangle([0, 0, W, 74], fill=PANEL)
+    d.text((26, 16), caption, font=font(30, True), fill=CYAN)
+    if sub:
+        d.text((26, 50), sub, font=font(15), fill=DIM)
+
+    bw, bh = 168, 62  # node box size
+
+    def box_of(key):
+        cx, cy = LAYOUT[key]
+        return [cx - bw // 2, cy - bh // 2, cx + bw // 2, cy + bh // 2]
+
+    # edges first
+    for s, t, label in EDGES:
+        if s in deleted or t in deleted:
+            continue
+        sx, sy = LAYOUT[s]
+        tx, ty = LAYOUT[t]
+        col = RED if (states.get(s) == TruthState.REFUTED.value or
+                      states.get(t) == TruthState.REFUTED.value) else EDGE
+        d.line([sx, sy, tx, ty], fill=col, width=2)
+        mx, my = (sx + tx) // 2, (sy + ty) // 2
+        d.text((mx - d.textlength(label, font=font(12)) / 2, my - 16), label,
+               font=font(12), fill=DIM)
+
+    # nodes
+    for key, (cx, cy) in LAYOUT.items():
+        if key in deleted:
+            # ghost outline for a forgotten node
+            b = box_of(key)
+            d.rounded_rectangle(b, radius=10, outline=(55, 65, 81), width=2)
+            _center_box(d, "🗑 forgotten", font(13, True), cx, cy, (75, 85, 99))
+            continue
+        st = states.get(key, TruthState.ALIVE.value)
+        color = STATE_COLOR.get(st, GREEN)
+        b = box_of(key)
+        dashed = st == TruthState.REFUTED.value
+        d.rounded_rectangle(b, radius=10, fill=_tint(color), outline=color,
+                            width=4 if dashed else 2)
+        # label (2 lines)
+        lines = SHORT[key].split("\n")
+        fnt = font(14, True)
+        total_h = len(lines) * 17
+        yy = cy - total_h // 2
+        for ln in lines:
+            _center_box(d, ln, fnt, cx, yy + 8, (12, 16, 32))
+            yy += 17
+        # state tag
+        d.text((b[0] + 6, b[1] + 4), st.upper(), font=font(10, True), fill=(12, 16, 32))
+
+    return img
+
+
+def _center_box(d, text, f, cx, cy, color):
+    w = d.textlength(text, font=f)
+    d.text((cx - w / 2, cy - 8), text, font=f, fill=color)
+
+
+def _tint(color):
+    """Lighten a state color for the node fill."""
+    return tuple(min(255, int(c * 0.55 + 120)) for c in color)
+
+
+def states_from_ids(truth: dict, ids: dict) -> dict:
+    out = {}
+    for key, nid in ids.items():
+        align = truth.get(nid, [TruthState.ALIVE.value])
+        out[key] = align[0] if align else TruthState.ALIVE.value
+    return out
+
+
+async def build(demo: bool) -> None:
+    from falsify.falsify import build_graph, revise, scoreboard
+    from falsify.seed import NEW_FACT, QUESTION_TEXT
+
+    os.makedirs("output", exist_ok=True)
+
+    print("[gif] Session 1: building belief graph…")
+    seeded = await build_graph()
+    t_before = await graph_ops.get_truth(list(seeded.ids.values()))
+    before_states = states_from_ids(t_before, seeded.ids)
+
+    print(f"[gif] Session 2: revising (mode={'demo' if demo else 'live'})…")
+    pinned = seeded.refuted_target_id if demo else None
+    report = await revise(NEW_FACT, pinned_target_id=pinned)
+
+    nodes, _ = await graph_ops.load_graph()
+    present = {str(n) for n, _ in nodes}
+    deleted_keys = {k for k, v in seeded.ids.items() if v not in present}
+    t_after = await graph_ops.get_truth([v for v in seeded.ids.values() if v in present])
+    after_states = states_from_ids(t_after, {k: v for k, v in seeded.ids.items()
+                                             if v in present})
+
+    board = await scoreboard(QUESTION_TEXT, seeded)
+
+    print("[gif] composing frames…")
+    frames = [
+        (title_card(), 2600),
+        (session1_card(), 2500),
+        (draw_graph(before_states, set(), "BEFORE — every belief is alive",
+                    "green = alive"), 3000),
+        (session2_card(), 2800),
+        (draw_graph(after_states, deleted_keys, "AFTER — refutation cascaded",
+                    "red = refuted · K forgotten · amber = superseded · B ignites"), 3800),
+        (scoreboard_card(board.falsify_answer, board.stale), 3600),
+        (closing_card(), 2400),
+    ]
+    imgs = [f.convert("P", palette=Image.ADAPTIVE, colors=128) for f, _ in frames]
+    durations = [dur for _, dur in frames]
+    out_path = "output/falsify-demo.gif"
+    imgs[0].save(out_path, save_all=True, append_images=imgs[1:],
+                 duration=durations, loop=0, optimize=False, disposal=2)
+    print(f"[gif] wrote {out_path} ({os.path.getsize(out_path)//1024} KB, {len(imgs)} frames)")
+    print(f"[gif] refuted={len(report.refuted)} invalidated={len(report.invalidated)} "
+          f"forgotten={len(report.forgotten)}")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--demo", action="store_true")
+    args = ap.parse_args()
+    asyncio.run(build(demo=args.demo))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

demo_video_script.md

@@ -0,0 +1,62 @@
+# FALSIFY — 30-second demo script
+
+A tight, judge-ready narration. Total runtime ~30s of talking over one `python main.py --demo` run. Capture the terminal + the `output/graph.html` for the GIF.
+
+---
+
+## Setup (before recording)
+- Terminal with a dark theme, font large enough to read on playback.
+- `.env` has a working `LLM_API_KEY` (so embeddings + recall are real).
+- Run once beforehand to warm caches; record the second run.
+
+---
+
+## Beat sheet
+
+**[0:00–0:05] The hook**
+> "Every AI memory demo fixes *forgetting*. FALSIFY fixes something worse — an AI that confidently remembers a fact that's been **proven false**."
+
+*Run:* `python main.py --demo`
+
+**[0:05–0:12] Session 1 — the belief graph**
+> "We're investigating: *did Company X know about the defect before the recall?* Two hypotheses — a March QA report, and a January supplier email. A conclusion rests on that March report."
+
+*On screen:* the **BEFORE** panel — every node tagged `ALIVE` in green.
+
+**[0:12–0:20] Session 2 — one contradicting fact**
+> "Now one line arrives: *a forensic audit found the March report was back-dated.* Watch."
+
+*On screen:* the revision log —
+```
+✗ refuted: 1 evidence node
+✗ invalidated: 1 conclusion
+hypothesis A → ↓ superseded
+hypothesis B → ↑ promoted (new frontier)
+🗑 forgotten: Company X knew about the defect by March 2021
+```
+
+**[0:20–0:27] The AFTER + scoreboard**
+> "The March evidence is red. The conclusion built on it collapsed and was **surgically deleted** — from the graph *and* the vector store. Hypothesis B ignites as the new answer."
+
+*On screen:* the **SCOREBOARD** —
+```
+FALSIFY : X knew by Jan 2021 (supplier email)      ← revised
+RAG     : X knew by Mar 2021 (QA report)  [STALE]  ← still cites the refuted fact
+```
+
+**[0:27–0:30] The close**
+> "Same store, same query. FALSIFY revised its belief and the disbelief persists across sessions. Plain RAG can't. **AI revised, not forgot.**"
+
+*On screen:* open `output/graph.html` — the red refuted node, the missing orphan, the green frontier.
+
+---
+
+## The single most important line
+> **"It's not that the AI forgot where the context was — the context was *wrong*, and FALSIFY revised it."**
+
+That reframes the hackathon's "Where's My Context?" theme into FALSIFY's exact contribution.
+
+---
+
+## If asked "why can't RAG do this?"
+> "Refutation is graph traversal over typed edges — *this fact grounds that conclusion three hops away.* A vector index has no edges to walk and no truth-state to filter on. This needs a knowledge graph — which is exactly what Cognee gives us."

falsify/__init__.py

@@ -0,0 +1,57 @@
+"""
+FALSIFY — Belief Revision Research Copilot
+
+Exposes core models and edge constants for the belief graph.
+
+Import-time environment safety
+------------------------------
+FALSIFY is a single-user, self-hosted demo. We set a few Cognee defaults *before*
+any Cognee module is imported (importing :mod:`falsify.models` pulls in Cognee), so
+that graph writes go into one shared local graph without per-user access-control
+gymnastics. ``setdefault`` means an explicitly-exported env var always wins.
+"""
+
+import os as _os
+
+# Single-user mode: shared local DBs, auth off. Must precede the first cognee import.
+_os.environ.setdefault("ENABLE_BACKEND_ACCESS_CONTROL", "False")
+# Keep logs quiet unless the user opts in.
+_os.environ.setdefault("LOG_LEVEL", "ERROR")
+_os.environ.setdefault("COGNEE_LOG_FILE", "false")
+# Enable the session cache so remember(session_id=...) / improve() work (cross-session proof).
+_os.environ.setdefault("CACHING", "true")
+_os.environ.setdefault("CACHE_BACKEND", "fs")
+# Default embeddings to fastembed — a fully local, CPU-only, zero-cost embedder, so
+# the whole pipeline (and `python main.py --demo`) runs with NO external API key.
+# Any explicit EMBEDDING_* in the environment / .env overrides these (setdefault).
+_os.environ.setdefault("EMBEDDING_PROVIDER", "fastembed")
+_os.environ.setdefault("EMBEDDING_MODEL", "BAAI/bge-small-en-v1.5")
+_os.environ.setdefault("EMBEDDING_DIMENSIONS", "384")
+_os.environ.setdefault("EMBEDDING_MAX_TOKENS", "512")
+
+from falsify.models import (
+    Assertion,
+    Conclusion,
+    Evidence,
+    Hypothesis,
+    InvestigationQuestion,
+    TruthState,
+    # Edge relationship constants
+    CONTRADICTS,
+    DEPENDS_ON,
+    SUPPORTS,
+    SUPERSEDES,
+)
+
+__all__ = [
+    "TruthState",
+    "InvestigationQuestion",
+    "Hypothesis",
+    "Evidence",
+    "Conclusion",
+    "Assertion",
+    "DEPENDS_ON",
+    "SUPPORTS",
+    "CONTRADICTS",
+    "SUPERSEDES",
+]

falsify/edges.py

@@ -0,0 +1,70 @@
+"""
+Edge relationship-name constants for the FALSIFY belief graph.
+
+These strings are passed as ``relationship_name`` to ``graph_engine.add_edge(...)``
+and used as ``edge_types`` filters in ``get_neighborhood(...)``. They are re-exported
+from :mod:`falsify.models` as well; this module is the single source of truth.
+
+Edge semantics (see REQUIREMENTS.md §1.1)
+-----------------------------------------
+- ``DEPENDS_ON`` : Conclusion -> Evidence. THE forward-propagation rail. A Conclusion
+  depends on the Evidence it rests on. ``edge_properties = {"critical": bool}``.
+- ``SUPPORTS``   : Evidence -> Hypothesis. Evidence corroborates a hypothesis.
+  ``edge_properties = {"weight": float}``.
+- ``REFUTES``    : Evidence -> Hypothesis. Evidence contradicts a hypothesis.
+  ``edge_properties = {"weight": float}``.
+- ``SUPERSEDES`` : Evidence(new) -> Evidence(old). Written when a new fact back-dates /
+  overrides an old evidence node. ``edge_properties = {"confidence": float}``.
+"""
+
+DEPENDS_ON = "depends_on"
+# Non-critical dependency variant. Criticality is encoded in the relationship NAME
+# because some graph backends (e.g. Ladybug) do not round-trip edge *properties* —
+# a name always persists, an edge property may not. So a plain ``depends_on`` edge is
+# treated as critical by default, and ``depends_on_soft`` is the explicit non-critical
+# form. (For in-memory/tests, an explicit ``{"critical": bool}`` property still wins.)
+DEPENDS_ON_SOFT = "depends_on_soft"
+SUPPORTS = "supports"
+REFUTES = "refutes"
+# ``CONTRADICTS`` kept as an alias for the refutes edge (spec used both names).
+CONTRADICTS = REFUTES
+SUPERSEDES = "supersedes"
+
+#: All dependency edge relationship names (critical + soft).
+DEPENDENCY_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT]
+
+#: Edge types traversed when checking whether a node still feeds a live consumer.
+CONSUMER_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT, SUPPORTS]
+
+
+def is_critical_dependency(rel: str, props: dict | None = None) -> bool:
+    """Return whether a dependency edge is *critical*.
+
+    An explicit ``critical`` edge property wins when present (used by in-memory tests).
+    Otherwise criticality is inferred from the relationship name: ``depends_on`` is
+    critical by default, ``depends_on_soft`` is not. This makes correctness independent
+    of whether the backend persists edge properties.
+    """
+    props = props or {}
+    if "critical" in props:
+        return bool(props["critical"])
+    if rel == DEPENDS_ON_SOFT:
+        return False
+    return rel == DEPENDS_ON  # depends_on => critical by default
+
+
+# Edge types traversed during forward refutation propagation.
+PROPAGATION_EDGE_TYPES = [DEPENDS_ON, DEPENDS_ON_SOFT, SUPPORTS]
+
+__all__ = [
+    "DEPENDS_ON",
+    "DEPENDS_ON_SOFT",
+    "SUPPORTS",
+    "REFUTES",
+    "CONTRADICTS",
+    "SUPERSEDES",
+    "DEPENDENCY_EDGE_TYPES",
+    "CONSUMER_EDGE_TYPES",
+    "PROPAGATION_EDGE_TYPES",
+    "is_critical_dependency",
+]

falsify/events.py

@@ -0,0 +1,86 @@
+"""
+FALSIFY real-time event bus — the seam between the belief pipeline and the live UI.
+
+The whole point of the web demo is that a judge *watches* a belief die: the refute
+flash, the cascade sweep, the forget-dissolve. Those animations are driven by events
+that this module fans out to every connected browser over Server-Sent Events.
+
+Design constraints that shaped this module:
+
+* **Leaf module.** It imports nothing from ``falsify`` so that ``graph_ops`` can import
+  it without a cycle (``graph_ops -> events`` only, never the reverse).
+* **No-op when nobody's watching.** ``emit`` iterates an empty subscriber set under the
+  CLI (``python main.py``), so the two hooks in ``graph_ops`` cost effectively nothing
+  and the offline demo behaves exactly as before.
+* **Never block the pipeline.** A slow browser must not stall belief revision, so we
+  ``put_nowait`` and drop on a full queue rather than awaiting backpressure. The client
+  re-syncs via ``GET /api/graph`` on reconnect, so a dropped frame is cosmetic.
+
+Each open ``GET /api/events`` connection owns one queue (``subscribe`` / ``unsubscribe``);
+``server.py`` drains it and serializes each event as an SSE ``data:`` frame.
+"""
+
+from __future__ import annotations
+
+import logging
+from asyncio import Queue, QueueFull
+from typing import Any, Dict, Set
+
+logger = logging.getLogger("falsify.events")
+
+# One queue per live SSE connection. Empty set == CLI / offline == emit is a no-op.
+_subscribers: Set[Queue] = set()
+
+# Per-connection buffer. Large enough that a whole cascade never overflows a healthy
+# client; a client slow enough to fill 1000 frames is already gone.
+_QUEUE_MAXSIZE = 1000
+
+
+def subscribe() -> Queue:
+    """Register a new SSE connection and return its private event queue."""
+    q: Queue = Queue(maxsize=_QUEUE_MAXSIZE)
+    _subscribers.add(q)
+    logger.debug("SSE subscriber added (now %d)", len(_subscribers))
+    return q
+
+
+def unsubscribe(q: Queue) -> None:
+    """Drop a disconnected SSE connection's queue (idempotent)."""
+    _subscribers.discard(q)
+    logger.debug("SSE subscriber removed (now %d)", len(_subscribers))
+
+
+def has_subscribers() -> bool:
+    """True if at least one browser is listening — lets the server pace animations
+    (small inter-step sleeps) only when someone is actually watching."""
+    return bool(_subscribers)
+
+
+async def emit(event: Dict[str, Any]) -> None:
+    """Fan one event out to every live connection. No-op when none. Never blocks."""
+    for q in list(_subscribers):
+        try:
+            q.put_nowait(event)
+        except QueueFull:  # slow client: drop the frame, don't stall the pipeline
+            logger.debug("dropping event for a full subscriber queue")
+
+
+async def emit_state_change(node_id: str, state: str, epoch: int) -> None:
+    """A node's truth-state changed (refuted / invalidated / superseded / alive)."""
+    await emit({"type": "node_state_changed", "id": str(node_id),
+                "state": str(state), "epoch": int(epoch)})
+
+
+async def emit_forgotten(node_id: str) -> None:
+    """A node was hard-deleted from the graph (the forget-dissolve animation)."""
+    await emit({"type": "node_forgotten", "id": str(node_id)})
+
+
+async def emit_graph_reset() -> None:
+    """The graph was rebuilt/reseeded — clients should refetch the full snapshot."""
+    await emit({"type": "graph_reset"})
+
+
+async def emit_step(step: str, detail: str = "") -> None:
+    """A human-readable pipeline milestone, for the revision-log feed."""
+    await emit({"type": "pipeline_step", "step": str(step), "detail": str(detail)})

falsify/falsify.py

@@ -0,0 +1,463 @@
+"""
+FALSIFY orchestration — the belief-revision copilot's public API.
+
+Three verbs tie the engine together:
+
+    build_graph()          -> seed the Session-1 investigation graph (clean slate).
+    revise(new_fact)       -> run the full revision pipeline for an incoming fact:
+                              detect -> propagate -> promote -> record supersede -> forget.
+    scoreboard(question)   -> the money shot: FALSIFY's revised answer (reads truth
+                              state, skips dead branches) vs a plain-RAG baseline
+                              (raw vector search, no truth filter) that still cites the
+                              refuted fact.
+
+Everything is persisted on the graph (truth-state on nodes), so a fresh process /
+second session sees the revised beliefs — the cross-session guarantee.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from falsify import graph_ops
+from falsify.edges import SUPERSEDES, SUPPORTS
+from falsify.models import Evidence, TruthState
+from falsify.seed import SeededGraph, build_diamond_investigation, build_investigation
+from falsify.tasks import (
+    Contradiction,
+    cascade_forget,
+    detect_contradictions,
+    promote_competing_hypothesis,
+    propagate_refutation,
+)
+
+logger = logging.getLogger("falsify.orchestrator")
+
+_ALIVE = TruthState.ALIVE.value
+_EVIDENCE_COLLECTION = "Evidence_claim"
+
+
+@dataclass
+class RevisionReport:
+    """Full record of one :func:`revise` run, for demo output and tests."""
+
+    new_fact: str
+    contradictions: List[Contradiction] = field(default_factory=list)
+    refuted: List[str] = field(default_factory=list)
+    invalidated: List[str] = field(default_factory=list)
+    hypothesis_actions: Dict[str, str] = field(default_factory=dict)
+    forgotten: List[str] = field(default_factory=list)
+    forgotten_labels: Dict[str, str] = field(default_factory=dict)
+    retained_provenance: List[str] = field(default_factory=list)
+    new_evidence_id: Optional[str] = None
+    epoch: int = 0
+    rag_snapshot: Optional[List[Dict]] = None
+
+    @property
+    def revised(self) -> bool:
+        """True if the fact actually triggered a belief change."""
+        return bool(self.refuted or self.invalidated)
+
+
+async def build_graph() -> SeededGraph:
+    """Prune everything and build the Session-1 investigation graph.
+
+    Returns the :class:`SeededGraph` with stable handles to the seeded nodes.
+    """
+    import cognee
+    from cognee.low_level import setup
+
+    logger.info("build_graph: pruning and seeding fresh investigation")
+    await cognee.forget(everything=True)
+    await setup()  # (re)create relational tables the storage pipeline needs
+    seeded = await build_investigation()
+    return seeded
+
+
+async def build_diamond_graph() -> SeededGraph:
+    """Prune everything and build the diamond-dependency investigation graph.
+
+    Same clean-slate sequence as :func:`build_graph`, but seeds the extended graph
+    with Conclusion K2 (critically dependent on both E_qa and E_email). Drives the
+    two-phase "survive then collapse" demo; see
+    :func:`falsify.seed.build_diamond_investigation`.
+    """
+    import cognee
+    from cognee.low_level import setup
+
+    logger.info("build_diamond_graph: pruning and seeding diamond investigation")
+    await cognee.forget(everything=True)
+    await setup()
+    return await build_diamond_investigation()
+
+
+async def use_backend(
+    mode: str = "opensource",
+    *,
+    url: Optional[str] = None,
+    api_key: Optional[str] = None,
+) -> str:
+    """Route Cognee operations to a backend and return the active mode.
+
+    ``mode="cloud"`` (with a tenant ``url`` + ``api_key``) points every subsequent
+    ``remember`` / ``recall`` / ``memify`` / ``forget`` call at a Cognee Cloud tenant
+    via :func:`cognee.serve` — making the *same* FALSIFY pipeline demonstrable on the
+    Cognee Cloud track without changing any belief logic. Anything else keeps the
+    self-hosted (open-source) engines. Best-effort: if the cloud handshake fails we
+    log and stay open-source so the demo never hard-fails.
+    """
+    import cognee
+
+    if mode == "cloud" and url and api_key:
+        try:
+            await cognee.serve(url=url, api_key=api_key)
+            logger.info("FALSIFY backend -> Cognee Cloud (%s)", url)
+            return "cloud"
+        except Exception as exc:
+            logger.warning("cognee.serve failed (%s); staying open-source", exc)
+            return "opensource"
+    logger.info("FALSIFY backend -> self-hosted (open source)")
+    return "opensource"
+
+
+async def revise(
+    new_fact: str,
+    *,
+    pinned_target_id: Optional[str] = None,
+    source_id: str = "session2_fact",
+) -> RevisionReport:
+    """Run the full belief-revision pipeline for an incoming fact.
+
+    Pipeline (REQUIREMENTS §1.3-§1.5):
+        1. detect_contradictions -> which evidence does the fact contradict?
+        2. propagate_refutation  -> refute it; cascade invalidation forward.
+        3. promote_competing_hypothesis -> demote the losing hypothesis, ignite the rival.
+        4. record the new fact as Evidence + a ``supersedes`` edge to the refuted node
+           (so the refuted node is retained as a provenance tombstone).
+        5. cascade_forget -> hard-delete orphaned dead-ends from graph + vector.
+
+    Args:
+        new_fact: the incoming claim.
+        pinned_target_id: demo override — refute this evidence id deterministically.
+        source_id: provenance id for the materialized new-fact Evidence node.
+
+    Returns:
+        A :class:`RevisionReport` describing everything that changed.
+    """
+    report = RevisionReport(new_fact=new_fact)
+
+    # Route through cognee.memify() pipeline for deep Cognee API integration.
+    # Falls back to direct calls if memify is unavailable.
+    try:
+        report = await revise_via_memify(
+            new_fact, pinned_target_id=pinned_target_id, source_id=source_id,
+        )
+        if not report.revised:
+            logger.info("revise: no contradiction found; graph unchanged")
+        else:
+            logger.info(
+                "revise complete (via memify): refuted=%d invalidated=%d forgotten=%d",
+                len(report.refuted), len(report.invalidated), len(report.forgotten),
+            )
+        return report
+    except Exception as exc:
+        logger.warning("memify pipeline failed (%s); falling back to direct calls", exc)
+
+    # Fallback: direct task calls (same logic, no pipeline wrapper)
+    contradictions = await detect_contradictions(new_fact, pinned_target_id=pinned_target_id)
+    report.contradictions = contradictions
+    if not contradictions:
+        logger.info("revise: no contradiction found; graph unchanged")
+        return report
+
+    target_ids = [c.target_id for c in contradictions]
+
+    prop = await propagate_refutation(target_ids)
+    report.refuted = prop.refuted
+    report.invalidated = prop.invalidated
+    report.epoch = prop.epoch
+
+    report.hypothesis_actions = await promote_competing_hypothesis(target_ids, prop.epoch)
+
+    report.new_evidence_id = await _record_new_fact(new_fact, contradictions, source_id)
+
+    report.rag_snapshot = await _snapshot_rag(new_fact)
+
+    forget_res = await cascade_forget(prop.affected)
+    report.forgotten = forget_res.forgotten
+    report.forgotten_labels = forget_res.labels
+    report.retained_provenance = forget_res.retained_provenance
+
+    logger.info(
+        "revise complete (direct): refuted=%d invalidated=%d forgotten=%d",
+        len(report.refuted), len(report.invalidated), len(report.forgotten),
+    )
+    return report
+
+
+async def _record_new_fact(
+    new_fact: str,
+    contradictions: List[Contradiction],
+    source_id: str,
+) -> Optional[str]:
+    """Materialize the new fact as an Evidence node and link supersedes edges.
+
+    The new (alive) evidence ``supersedes`` each refuted evidence node. This both
+    records provenance and pins the refuted node as a retained tombstone (an alive
+    supersedes-source protects its target from forget — REQUIREMENTS §1.5c).
+    """
+    from cognee.tasks.storage import add_data_points
+
+    try:
+        new_ev = Evidence(
+            claim=new_fact,
+            source_id=source_id,
+            stance="refutes",
+            confidence=max((c.confidence for c in contradictions), default=0.9),
+        )
+        await add_data_points([new_ev])
+        for c in contradictions:
+            await graph_ops.add_edge(
+                str(new_ev.id), str(c.target_id), SUPERSEDES, {"confidence": c.confidence}
+            )
+        logger.info("recorded new fact %s superseding %d node(s)", new_ev.id, len(contradictions))
+        return str(new_ev.id)
+    except Exception as exc:
+        logger.error("failed to record new fact: %s", exc)
+        return None
+
+
+async def _snapshot_rag(query: str) -> List[Dict]:
+    """Capture RAG vector hits before cascade_forget deletes them."""
+    ve = graph_ops.get_vector_engine()
+    try:
+        hits = await ve.search(
+            _EVIDENCE_COLLECTION, query_text=query, limit=5, include_payload=True,
+        )
+    except Exception:
+        return []
+    results = []
+    for h in (hits or []):
+        payload = getattr(h, "payload", {}) or {}
+        results.append({"id": str(h.id), "payload": payload})
+    return results
+
+
+# --------------------------------------------------------------------------- #
+# memify adapter — wraps FALSIFY tasks as a cognee.memify() pipeline
+# --------------------------------------------------------------------------- #
+
+
+async def _task_detect(data: List[Dict[str, Any]], **kwargs) -> List[Dict[str, Any]]:
+    """memify extraction task: detect contradictions."""
+    c = data[0] if data else {}
+    contradictions = await detect_contradictions(
+        c["new_fact"], pinned_target_id=c.get("pinned_target_id"),
+    )
+    c["contradictions"] = contradictions
+    return [c]
+
+
+async def _task_propagate(data: List[Dict[str, Any]], **kwargs) -> List[Dict[str, Any]]:
+    """memify enrichment task 1: propagate refutation + promote hypotheses."""
+    c = data[0] if data else {}
+    contradictions = c.get("contradictions", [])
+    if not contradictions:
+        return [c]
+
+    target_ids = [con.target_id for con in contradictions]
+    prop = await propagate_refutation(target_ids)
+    c["propagation"] = prop
+    c["hypothesis_actions"] = await promote_competing_hypothesis(target_ids, prop.epoch)
+    return [c]
+
+
+async def _task_record_and_forget(data: List[Dict[str, Any]], **kwargs) -> List[Dict[str, Any]]:
+    """memify enrichment task 2: record new fact, snapshot RAG, cascade forget."""
+    c = data[0] if data else {}
+    contradictions = c.get("contradictions", [])
+    if not contradictions:
+        return [c]
+
+    new_evidence_id = await _record_new_fact(
+        c["new_fact"], contradictions, c.get("source_id", "session2_fact"),
+    )
+    c["new_evidence_id"] = new_evidence_id
+    c["rag_snapshot"] = await _snapshot_rag(c["new_fact"])
+
+    prop = c.get("propagation")
+    if prop:
+        forget_res = await cascade_forget(prop.affected)
+        c["forget_result"] = forget_res
+
+    return [c]
+
+
+async def revise_via_memify(
+    new_fact: str,
+    *,
+    pinned_target_id: Optional[str] = None,
+    source_id: str = "session2_fact",
+) -> RevisionReport:
+    """Run the belief-revision pipeline through cognee.memify().
+
+    Functionally identical to the direct-call path, but routes through Cognee's
+    memify pipeline runner so the revision tasks appear as first-class Cognee
+    pipeline stages — demonstrating deep API integration.
+    """
+    import cognee
+    from cognee.modules.pipelines.tasks.task import Task
+
+    pipeline_input = [{
+        "new_fact": new_fact,
+        "pinned_target_id": pinned_target_id,
+        "source_id": source_id,
+    }]
+
+    await cognee.memify(
+        extraction_tasks=[Task(_task_detect)],
+        enrichment_tasks=[
+            Task(_task_propagate),
+            Task(_task_record_and_forget),
+        ],
+        data=pipeline_input,
+    )
+
+    # Build the report from the mutated context dict
+    ctx = pipeline_input[0]
+    report = RevisionReport(new_fact=new_fact)
+    report.contradictions = ctx.get("contradictions", [])
+
+    prop = ctx.get("propagation")
+    if prop:
+        report.refuted = prop.refuted
+        report.invalidated = prop.invalidated
+        report.epoch = prop.epoch
+
+    report.hypothesis_actions = ctx.get("hypothesis_actions", {})
+    report.new_evidence_id = ctx.get("new_evidence_id")
+    report.rag_snapshot = ctx.get("rag_snapshot")
+
+    forget_res = ctx.get("forget_result")
+    if forget_res:
+        report.forgotten = forget_res.forgotten
+        report.forgotten_labels = forget_res.labels
+        report.retained_provenance = forget_res.retained_provenance
+
+    return report
+
+
+@dataclass
+class Scoreboard:
+    """The FALSIFY-vs-RAG comparison shown every run."""
+
+    question: str
+    falsify_answer: str
+    falsify_support: List[str] = field(default_factory=list)
+    rag_answer: str = ""
+    rag_citations: List[str] = field(default_factory=list)
+    stale: bool = False  # True if RAG still cites a refuted node FALSIFY dropped
+
+
+async def scoreboard(
+    question: str,
+    seeded: Optional[SeededGraph] = None,
+    rag_snapshot: Optional[List[Dict]] = None,
+) -> Scoreboard:
+    """Compare FALSIFY's revised answer against a plain-RAG baseline.
+
+    FALSIFY answer: derived from the graph, reading truth-state and using only
+    hypotheses/evidence still ``alive`` (the promoted frontier hypothesis).
+
+    RAG baseline: a raw vector search over ``Evidence_claim`` with **no** truth
+    filter — so it still returns evidence FALSIFY has refuted, and cites the stale
+    fact. This asymmetry is the demo's whole point.
+    """
+    board = Scoreboard(question=question, falsify_answer="(no surviving hypothesis)")
+
+    # ---- FALSIFY: try cognee.recall() first, fall back to graph traversal ----
+    recall_succeeded = False
+    try:
+        import cognee
+        from cognee.modules.search.types.SearchType import SearchType
+
+        recall_results = await cognee.recall(
+            query_text=question,
+            query_type=SearchType.GRAPH_COMPLETION,
+            top_k=3,
+        )
+        if recall_results:
+            best = recall_results[0]
+            answer_text = getattr(best, "text", None) or str(best)
+            board.falsify_answer = answer_text
+            board.falsify_support = ["(via cognee.recall GRAPH_COMPLETION)"]
+            recall_succeeded = True
+            logger.info("scoreboard: used cognee.recall() for FALSIFY answer")
+    except Exception as exc:
+        logger.info("cognee.recall() unavailable (%s); falling back to graph traversal", exc)
+
+    # Fall back to manual graph traversal (always works, including --demo offline mode)
+    nodes, edges = await graph_ops.load_graph()
+    node_ids = [nid for nid, _p in nodes]
+    truth = await graph_ops.get_truth(node_ids)
+    props_by_id = {str(nid): (p or {}) for nid, p in nodes}
+
+    if not recall_succeeded:
+        best_hyp, best_score = None, -1.0
+        support_edges = [(s, d, p) for (s, d, r, p) in edges if r == SUPPORTS]
+        for nid, props in nodes:
+            nid = str(nid)
+            if "statement" not in props:
+                continue
+            if _ALIVE not in truth.get(nid, [_ALIVE]):
+                continue
+            score = 0.0
+            alive_support = []
+            for (src, dst, ep) in support_edges:
+                if str(dst) != nid:
+                    continue
+                if _ALIVE in truth.get(str(src), [_ALIVE]):
+                    score += float(ep.get("weight", 0.5))
+                    alive_support.append(graph_ops.node_label(props_by_id.get(str(src), {})))
+            if alive_support and score > best_score:
+                best_hyp, best_score = nid, score
+                board.falsify_answer = graph_ops.node_label(props)
+                board.falsify_support = alive_support
+
+    # ---- RAG baseline: use pre-forget snapshot if available, else live search ----
+    refuted_ids = {str(nid) for nid in node_ids
+                   if TruthState.REFUTED.value in truth.get(str(nid), [])}
+
+    if rag_snapshot is not None:
+        for entry in rag_snapshot:
+            payload = entry.get("payload", {})
+            text = (payload.get("claim") or payload.get("text")
+                    or graph_ops.node_label(payload))
+            board.rag_citations.append(str(text))
+            if entry["id"] in refuted_ids:
+                board.stale = True
+    else:
+        ve = graph_ops.get_vector_engine()
+        try:
+            hits = await ve.search(
+                _EVIDENCE_COLLECTION, query_text=question, limit=5,
+                include_payload=True,
+            )
+        except Exception as exc:
+            logger.warning("RAG baseline search failed: %s", exc)
+            hits = []
+        for h in (hits or []):
+            payload = getattr(h, "payload", {}) or {}
+            text = (payload.get("claim") or payload.get("text")
+                    or graph_ops.node_label(payload))
+            board.rag_citations.append(str(text))
+            if str(h.id) in refuted_ids:
+                board.stale = True
+
+    board.rag_answer = (board.rag_citations[0] if board.rag_citations
+                        else "(no vector hits)")
+
+    logger.info("scoreboard: falsify=%r stale_rag=%s", board.falsify_answer, board.stale)
+    return board

falsify/graph_ops.py

@@ -0,0 +1,219 @@
+"""
+Low-level graph operations for FALSIFY.
+
+This module is the single, verified surface between FALSIFY's belief logic and
+Cognee's graph/vector engines. Every engine call used elsewhere in the project goes
+through a helper here, so the (few) places that touch Cognee internals are auditable.
+
+Verified Cognee API shapes (grep-confirmed against /workspaces/cognee — see REQUIREMENTS.md §0):
+
+    ge = await get_graph_engine()                     # ASYNC factory
+    nodes, edges = await ge.get_graph_data()          # ([(id, props)], [(src, dst, rel, props)])
+    nodes, edges = await ge.get_neighborhood(ids, depth=, edge_types=)
+    await ge.add_edge(from_node, to_node, relationship_name, edge_properties={})
+    await ge.set_node_truth_state({id: {"truth_alignment": [...], "truth_epoch": N}})
+    state = await ge.get_node_truth_state([ids])      # {id: {"truth_alignment": [...], ...}}
+    await ge.set_node_feedback_weights({id: 0.0})
+    await ge.delete_nodes([ids])
+
+    ve = get_vector_engine()                          # SYNC factory
+    await ve.delete_data_points(collection_name, [uuids])
+    hits = await ve.search(collection_name, query_text=, limit=, include_payload=)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from cognee.infrastructure.databases.graph import get_graph_engine
+from cognee.infrastructure.databases.vector import get_vector_engine
+
+from falsify import events
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.graph_ops")
+
+# A parsed edge: (source_id, target_id, relationship_name, properties)
+Edge = Tuple[str, str, str, Dict[str, Any]]
+# A parsed node: (node_id, properties)
+GraphNode = Tuple[str, Dict[str, Any]]
+
+
+async def load_graph() -> Tuple[List[GraphNode], List[Edge]]:
+    """Return the full graph as ``(nodes, edges)``.
+
+    Nodes are ``(id, props)`` tuples; edges are ``(src, dst, rel, props)`` tuples.
+    IDs are normalized to ``str`` so they can be used as dict keys regardless of
+    whether the adapter returns ``UUID`` or ``str``.
+    """
+    ge = await get_graph_engine()
+    raw_nodes, raw_edges = await ge.get_graph_data()
+
+    nodes: List[GraphNode] = [(str(nid), props or {}) for nid, props in raw_nodes]
+
+    edges: List[Edge] = []
+    for e in raw_edges:
+        # Adapters return 4-tuples (src, dst, rel, props); be defensive about arity.
+        if len(e) >= 4:
+            src, dst, rel, props = e[0], e[1], e[2], e[3]
+        elif len(e) == 3:
+            src, dst, rel, props = e[0], e[1], e[2], {}
+        else:  # pragma: no cover - unexpected adapter shape
+            continue
+        edges.append((str(src), str(dst), str(rel), props or {}))
+    return nodes, edges
+
+
+async def get_truth(node_ids: List[str]) -> Dict[str, List[str]]:
+    """Return ``{node_id: truth_alignment_list}`` for the given ids.
+
+    A node with no stored truth state is treated as ``["alive"]`` (the default).
+    """
+    if not node_ids:
+        return {}
+    ge = await get_graph_engine()
+    ids = [str(n) for n in node_ids]
+    try:
+        raw = await ge.get_node_truth_state(ids)
+    except Exception as exc:  # adapter may not have state yet
+        logger.debug("get_node_truth_state failed (%s); defaulting to alive", exc)
+        raw = {}
+    out: Dict[str, List[str]] = {}
+    for nid in ids:
+        entry = (raw or {}).get(nid) or (raw or {}).get(str(nid))
+        alignment = (entry or {}).get("truth_alignment") if entry else None
+        out[nid] = list(alignment) if alignment else [TruthState.ALIVE.value]
+    return out
+
+
+async def is_alive(node_id: str) -> bool:
+    """True iff the node's truth_alignment currently contains ``alive``."""
+    state = await get_truth([str(node_id)])
+    return TruthState.ALIVE.value in state.get(str(node_id), [TruthState.ALIVE.value])
+
+
+async def set_state(node_id: str, state: TruthState, epoch: int) -> None:
+    """Persist ``truth_alignment=[state]`` + ``truth_epoch=epoch`` on a node.
+
+    Truth state is stored ON the graph node, so it survives a process restart — the
+    basis of FALSIFY's cross-session persistence guarantee.
+    """
+    ge = await get_graph_engine()
+    value = state.value if isinstance(state, TruthState) else str(state)
+    try:
+        await ge.set_node_truth_state(
+            {str(node_id): {"truth_alignment": [value], "truth_epoch": int(epoch)}}
+        )
+    except Exception as exc:
+        logger.error("set_node_truth_state failed for %s -> %s: %s", node_id, value, exc)
+        raise
+    # Reaching here means the write succeeded (the except re-raises). Tell any live
+    # UI so the node can animate its state change; no-op under the CLI.
+    await events.emit_state_change(str(node_id), value, int(epoch))
+
+
+async def set_weight(node_id: str, weight: float) -> None:
+    """Set a node's feedback weight (confidence/health signal). Best-effort."""
+    ge = await get_graph_engine()
+    try:
+        await ge.set_node_feedback_weights({str(node_id): float(weight)})
+    except Exception as exc:  # non-fatal: weight is a secondary signal
+        logger.debug("set_node_feedback_weights failed for %s: %s", node_id, exc)
+
+
+async def add_edge(src: str, dst: str, rel: str, props: Optional[Dict[str, Any]] = None) -> None:
+    """Add a directed edge ``src --rel--> dst`` with optional properties."""
+    ge = await get_graph_engine()
+    await ge.add_edge(str(src), str(dst), rel, props or {})
+
+
+async def delete_from_both_stores(node_ids: List[str], collections: List[str]) -> int:
+    """Hard-delete nodes from the graph AND their rows from vector collections.
+
+    Returns the number of node ids deleted. Vector deletion is attempted per
+    collection and is best-effort (a node may not live in every collection).
+    """
+    if not node_ids:
+        return 0
+    ids = [str(n) for n in node_ids]
+
+    ge = await get_graph_engine()
+    try:
+        await ge.delete_nodes(ids)
+    except Exception as exc:
+        logger.error("delete_nodes failed: %s", exc)
+        raise
+    # Graph delete succeeded — animate each node's forget-dissolve in any live UI.
+    for nid in ids:
+        await events.emit_forgotten(nid)
+
+    ve = get_vector_engine()
+    for collection in collections:
+        try:
+            await ve.delete_data_points(collection, ids)
+        except Exception as exc:  # collection may not exist / id not present
+            logger.debug("delete_data_points(%s) best-effort skip: %s", collection, exc)
+    return len(ids)
+
+
+# --------------------------------------------------------------------------- #
+# Adjacency helpers (built from a single load_graph() snapshot)
+# --------------------------------------------------------------------------- #
+
+
+def dependents_of(evidence_id: str, edges: List[Edge], rel: str) -> List[str]:
+    """Return source ids of ``rel`` edges pointing INTO ``evidence_id``.
+
+    For ``depends_on`` (Conclusion -> Evidence) this yields the Conclusions that
+    depend on the given Evidence — i.e. the forward-cascade victims.
+    """
+    tid = str(evidence_id)
+    return [src for (src, dst, r, _p) in edges if r == rel and str(dst) == tid]
+
+
+def incoming(node_id: str, edges: List[Edge], rel: str) -> List[Tuple[str, Dict[str, Any]]]:
+    """Return ``[(source_id, props)]`` for ``rel`` edges pointing into ``node_id``."""
+    tid = str(node_id)
+    return [(src, p) for (src, dst, r, p) in edges if r == rel and str(dst) == tid]
+
+
+def outgoing(node_id: str, edges: List[Edge], rel: str) -> List[Tuple[str, Dict[str, Any]]]:
+    """Return ``[(target_id, props)]`` for ``rel`` edges leaving ``node_id``."""
+    sid = str(node_id)
+    return [(dst, p) for (src, dst, r, p) in edges if r == rel and str(src) == sid]
+
+
+def node_label(props: Dict[str, Any]) -> str:
+    """Best-effort human label for a node from its properties."""
+    for key in ("statement", "claim", "question", "text", "name"):
+        if props.get(key):
+            return str(props[key])
+    return props.get("id", "?")
+
+
+async def flush_and_release() -> None:
+    """Checkpoint the graph WAL and evict the engine from Cognee's cache.
+
+    After this call, the next graph operation re-opens the on-disk store from
+    scratch — so a subsequent read is a genuine *cold* read, which is what makes
+    the web UI's persistence proof (``GET /api/verify``) honest rather than a
+    reflection of a warm in-memory handle. Every step is best-effort: on an
+    adapter that lacks ``checkpoint`` (e.g. the test FakeGraph), or if Cognee's
+    eviction internals move, we log and continue rather than break the demo.
+    """
+    ge = await get_graph_engine()
+    try:
+        if hasattr(ge, "checkpoint"):
+            await ge.checkpoint()
+    except Exception as exc:
+        logger.debug("checkpoint best-effort skip: %s", exc)
+    try:
+        from cognee.infrastructure.databases.graph.get_graph_engine import (
+            evict_graph_engine,
+        )
+        from cognee.infrastructure.databases.graph.config import get_graph_config
+
+        evict_graph_engine(**get_graph_config().to_hashable_dict())
+    except Exception as exc:
+        logger.debug("evict_graph_engine best-effort skip: %s", exc)

falsify/models.py

@@ -0,0 +1,202 @@
+"""
+FALSIFY belief-graph data models.
+
+Every node is a Cognee ``DataPoint`` subclass, so the same object serializes into
+the graph DB (Ladybug) and, via its ``Embeddable`` field, into the vector DB
+(LanceDB). The vector collection auto-created for a class is ``"{ClassName}_{field}"``
+(e.g. ``Evidence_claim`` — the collection the contradiction prefilter searches).
+
+Lifecycle / truth-state note
+----------------------------
+The *authoritative, persistent* belief state of a node lives on the graph node as
+``truth_alignment`` (a list) + ``truth_epoch`` (int), written through the graph
+engine (``set_node_truth_state``), not as pydantic model fields. Those props are
+what ``recall()`` filters on and what survives a process restart.
+
+The ``truth_state`` model field below is a convenience mirror of the node's initial
+state at ingest time (defaults to ``ALIVE``). Do not treat it as the source of
+truth after a memify run — always read back with ``get_node_truth_state``.
+
+Dedup across sessions
+---------------------
+``Hypothesis``, ``Evidence`` and ``Assertion`` mark identity fields with ``Dedup()``.
+DataPoint derives a stable UUID5 id from those fields (``DataPoint.id_for``), so
+re-adding the same belief in a later session updates the existing node instead of
+creating a duplicate — essential for a Session-2 contradiction to land on the exact
+node built in Session 1.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Annotated, List, Optional
+
+from pydantic import Field
+
+from cognee.infrastructure.engine import DataPoint, Dedup, Embeddable, LLMContext
+
+
+def _now_iso() -> str:
+    """Return the current UTC time as an ISO-8601 string (used for node timestamps)."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+class TruthState(str, Enum):
+    """Canonical belief-lifecycle states for a FALSIFY graph node.
+
+    The values are the exact strings written into the node's ``truth_alignment``
+    list, so a state can be compared directly against what ``get_node_truth_state``
+    returns (e.g. ``get_node_truth_state([n])[n]["truth_alignment"] == [TruthState.REFUTED]``).
+
+    States:
+    - ``ALIVE``: default; the node participates in recall context.
+    - ``REFUTED``: Evidence directly contradicted by a newer fact — the entry point
+      of a forward cascade.
+    - ``SUPERSEDED``: a node replaced/demoted by a newer competing node; retained as
+      provenance, excluded from recall.
+    - ``INVALIDATED``: a Conclusion whose critical supporting Evidence chain was
+      refuted (forward-cascade victim).
+    - ``FORGOTTEN``: an orphaned dead-end scheduled for surgical delete (transient;
+      the node is then hard-removed from both graph and vector stores).
+
+    Note: the FALSIFY spec's minimal enum names ALIVE/REFUTED/SUPERSEDED/FORGOTTEN.
+    ``INVALIDATED`` is added here because the forward-propagation algorithm
+    (REQUIREMENTS §1.2/§1.4) needs a distinct state for cascade-victim Conclusions
+    versus directly-refuted Evidence.
+    """
+
+    ALIVE = "alive"
+    REFUTED = "refuted"
+    SUPERSEDED = "superseded"
+    INVALIDATED = "invalidated"
+    FORGOTTEN = "forgotten"
+
+
+# --------------------------------------------------------------------------- #
+# Edge relationship-name constants (passed as ``relationship_name`` to add_edge)
+# --------------------------------------------------------------------------- #
+
+# Conclusion -> Evidence. THE forward-propagation rail. edge_properties={"critical": bool}
+DEPENDS_ON = "depends_on"
+
+# Evidence -> Hypothesis. Evidence corroborates a hypothesis. edge_properties={"weight": float}
+SUPPORTS = "supports"
+
+# Evidence -> Hypothesis. Evidence contradicts a hypothesis. edge_properties={"weight": float}
+# (REQUIREMENTS §1.1 names this edge "refutes"; ``REFUTES`` is provided as an alias.)
+CONTRADICTS = "refutes"
+REFUTES = CONTRADICTS
+
+# Evidence(new) -> Evidence(old). New fact overrides an old evidence node.
+# edge_properties={"confidence": float}
+SUPERSEDES = "supersedes"
+
+
+class InvestigationQuestion(DataPoint):
+    """Root node of a belief graph: the research question under investigation.
+
+    Example: "Did Company X know about the defect before the recall?" Everything
+    else (hypotheses, evidence, conclusions) hangs off this question via
+    ``question_id``.
+    """
+
+    question: Annotated[str, Embeddable(), LLMContext()]
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 1.0
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["question"],
+        "identity_fields": ["question"],
+    }
+
+
+class Hypothesis(DataPoint):
+    """A candidate explanation competing to answer the InvestigationQuestion.
+
+    Hypotheses gain/lose standing through ``supports``/``refutes`` Evidence edges.
+    When a hypothesis' only supporting Evidence is refuted, it is demoted to
+    ``SUPERSEDED`` and the rival with the strongest surviving support is promoted.
+    """
+
+    statement: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    question_id: str
+    status: str = "alive"
+    prior: float = 0.5
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["statement"],
+        "identity_fields": ["question_id", "statement"],
+    }
+
+
+class Evidence(DataPoint):
+    """A factual claim bearing on one or more hypotheses.
+
+    Evidence is the contradiction entry point: the ``Evidence_claim`` vector
+    collection is what the two-gate detector prefilters, and a ``REFUTED`` Evidence
+    node is the seed of every forward cascade. ``asserted_at`` is used as the
+    tie-break when deciding which of two competing claims supersedes the other
+    (newer wins).
+    """
+
+    claim: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    source_id: str
+    quote: str = ""
+    stance: str = "supports"  # "supports" | "refutes"
+    asserted_at: str = Field(default_factory=_now_iso)
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+
+    metadata: dict = {
+        "index_fields": ["claim"],
+        "identity_fields": ["source_id", "claim"],
+    }
+
+
+class Conclusion(DataPoint):
+    """A derived finding that rests on one or more Evidence nodes.
+
+    A Conclusion ``depends_on`` the Evidence it is built from (edge carries
+    ``critical: bool``). When a *critical* dependency is refuted and no alive
+    critical alternative remains, the Conclusion is ``INVALIDATED`` by the forward
+    cascade; if it then has no surviving consumer it is ``FORGOTTEN`` (hard-deleted).
+    """
+
+    statement: Annotated[str, Embeddable(), LLMContext()]
+    confidence: float = 0.5
+    depends_on_ids: List[str] = Field(default_factory=list)
+    truth_state: TruthState = TruthState.ALIVE
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["statement"],
+        "identity_fields": ["statement"],
+    }
+
+
+class Assertion(DataPoint):
+    """A raw, unclassified incoming claim — e.g. the new fact pasted in Session 2.
+
+    An Assertion is the pre-belief form of an incoming statement before the detector
+    decides whether it contradicts/supersedes existing Evidence and materializes a
+    proper ``Evidence`` node. It carries the same lifecycle scaffolding as the other
+    nodes so it can be reasoned over uniformly.
+    """
+
+    text: Annotated[str, Embeddable(), Dedup(), LLMContext()]
+    truth_state: TruthState = TruthState.ALIVE
+    confidence: float = 0.5
+    timestamp: str = Field(default_factory=_now_iso)
+    source_id: Optional[str] = None
+
+    metadata: dict = {
+        "index_fields": ["text"],
+        "identity_fields": ["text"],
+    }

falsify/seed.py

@@ -0,0 +1,317 @@
+"""
+FALSIFY demo corpus — the "Company X recall" investigation.
+
+This module builds the Session-1 belief graph that the demo revises in Session 2.
+It is intentionally small and hand-authored so the belief-revision mechanics are
+legible on screen in under 30 seconds, and so the cascade result is deterministic
+(the winning demo must not depend on a flaky LLM).
+
+The investigation
+-----------------
+Question Q:  "Did Company X know about the defect before the recall?"
+
+Competing hypotheses:
+    A — "X knew via the QA report dated March 2021"      (supported by E_qa)
+    B — "X knew via a supplier email in January 2021"    (supported by E_email)
+    C — "X did not know before the recall"               (unsupported)
+
+Evidence:
+    E_qa    — the March-2021 QA report       (supports A)
+    E_email — the January-2021 supplier email (supports B)
+
+Conclusion:
+    K — "Company X knew about the defect by March 2021"
+        depends_on E_qa  (critical=True)   <-- the propagation rail
+
+The Session-2 fact (NEW_FACT) is a forensic finding that the March QA report was
+back-dated. It contradicts E_qa. Refuting E_qa must cascade:
+
+    E_qa -> refuted
+      -> K (depends_on E_qa, critical) -> invalidated
+      -> A (only supporter E_qa now dead) -> superseded ; B promoted (new frontier)
+      -> K orphaned (no alive consumer) -> forgotten (hard-deleted, graph + vector)
+      -> E_qa kept as refuted provenance (it is NEW_FACT's supersedes anchor)
+
+The scoreboard then shows FALSIFY answering via B (Jan 2021) while a plain vector
+(RAG) baseline still cites the refuted March QA report.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+# NOTE: importing falsify.models runs falsify/__init__, which sets the Cognee env
+# defaults (access-control off, session cache on) before Cognee is imported.
+from falsify import graph_ops
+from falsify.edges import DEPENDS_ON, SUPPORTS
+from falsify.models import (
+    Conclusion,
+    Evidence,
+    Hypothesis,
+    InvestigationQuestion,
+)
+
+logger = logging.getLogger("falsify.seed")
+
+# The research question this whole graph hangs off of.
+QUESTION_TEXT = "Did Company X know about the defect before the recall?"
+
+# The Session-2 fact that triggers belief revision. It contradicts E_qa.
+NEW_FACT = (
+    "A forensic audit found that the March 2021 QA report was back-dated: it was "
+    "actually created shortly after the product recall, not before it."
+)
+
+# The SECOND contradiction, used only by the diamond scenario. It contradicts
+# E_email. Dropped after NEW_FACT to demonstrate iterative revision: once BOTH
+# legs of a multi-source conclusion are refuted, the conclusion finally collapses.
+NEW_FACT_2 = (
+    "A forensic analysis of email headers shows the January 2021 supplier email was "
+    "fabricated: the sender domain was not registered until April 2021, and the DKIM "
+    "signature is invalid."
+)
+
+# Human-readable stable keys -> used by --demo mode to pin the refutation target
+# deterministically (so the cascade runs on real graph APIs even if the LLM judge
+# is unavailable). These map to the ``key`` field on the seeded nodes below.
+REFUTED_EVIDENCE_KEY = "E_qa"
+REFUTED_EVIDENCE_KEY_2 = "E_email"  # second-phase target for the diamond scenario
+
+
+@dataclass
+class SeededGraph:
+    """Handles to the nodes created by :func:`build_investigation`.
+
+    ``ids`` maps a stable human key (e.g. ``"E_qa"``, ``"A"``, ``"K"``) to the
+    string node id in the graph, so the demo/tests can reference specific nodes
+    without re-querying. ``labels`` maps the same keys to display strings.
+    """
+
+    question_id: str
+    ids: Dict[str, str] = field(default_factory=dict)
+    labels: Dict[str, str] = field(default_factory=dict)
+
+    @property
+    def refuted_target_id(self) -> str:
+        """Node id of the evidence the Session-2 fact contradicts (E_qa)."""
+        return self.ids[REFUTED_EVIDENCE_KEY]
+
+
+async def build_investigation() -> SeededGraph:
+    """Create and persist the Session-1 belief graph. Returns a :class:`SeededGraph`.
+
+    The caller is responsible for starting from a clean state (e.g. via
+    ``cognee.forget(everything=True)`` and ``cognee.low_level.setup()``). This
+    function only builds; it does not prune.
+
+    Nodes are persisted with Cognee's ``add_data_points`` (writing both the graph
+    node and the vector row for each ``Embeddable`` field). Typed edges with
+    properties are then added explicitly through the graph engine so we control the
+    exact relationship names and edge properties (``critical`` / ``weight``).
+    """
+    # Import here so the module import stays cheap and env defaults are already set.
+    from cognee.tasks.storage import add_data_points
+
+    # ------------------------------------------------------------------ nodes
+    question = InvestigationQuestion(question=QUESTION_TEXT, source_id="investigation")
+
+    hyp_a = Hypothesis(
+        statement="Company X knew via the QA report dated March 2021.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.6,
+        source_id="analyst",
+    )
+    hyp_b = Hypothesis(
+        statement="Company X knew via a supplier email in January 2021.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.55,
+        source_id="analyst",
+    )
+    hyp_c = Hypothesis(
+        statement="Company X did not know about the defect before the recall.",
+        question_id=str(question.id),
+        prior=0.5,
+        confidence=0.4,
+        source_id="analyst",
+    )
+
+    ev_qa = Evidence(
+        claim="A QA report dated March 2021 documented the defect internally.",
+        source_id="qa_report_2021_03",
+        quote="Internal QA report, dated 2021-03-15, flags the defect.",
+        stance="supports",
+        asserted_at="2021-03-15",
+        confidence=0.8,
+    )
+    ev_email = Evidence(
+        claim="A supplier email in January 2021 warned Company X about the defect.",
+        source_id="supplier_email_2021_01",
+        quote="Supplier email, 2021-01-20: 'we have observed the defect in test units.'",
+        stance="supports",
+        asserted_at="2021-01-20",
+        confidence=0.7,
+    )
+
+    conclusion_k = Conclusion(
+        statement="Company X knew about the defect by March 2021.",
+        confidence=0.8,
+        depends_on_ids=[str(ev_qa.id)],
+        source_id="analyst",
+    )
+
+    nodes: List = [question, hyp_a, hyp_b, hyp_c, ev_qa, ev_email, conclusion_k]
+
+    logger.info("Persisting %d belief nodes via add_data_points", len(nodes))
+    await add_data_points(nodes)
+
+    # ------------------------------------------------------------------ edges
+    # Evidence -> Hypothesis (supports, weighted)
+    await graph_ops.add_edge(str(ev_qa.id), str(hyp_a.id), SUPPORTS, {"weight": 0.8})
+    await graph_ops.add_edge(str(ev_email.id), str(hyp_b.id), SUPPORTS, {"weight": 0.7})
+
+    # Conclusion -> Evidence (depends_on, critical) — THE propagation rail
+    await graph_ops.add_edge(
+        str(conclusion_k.id), str(ev_qa.id), DEPENDS_ON, {"critical": True}
+    )
+
+    # Hypothesis -> Question (answers) — keeps the graph connected for visualization
+    for hyp in (hyp_a, hyp_b, hyp_c):
+        await graph_ops.add_edge(str(hyp.id), str(question.id), "answers", {})
+
+    seeded = SeededGraph(
+        question_id=str(question.id),
+        ids={
+            "Q": str(question.id),
+            "A": str(hyp_a.id),
+            "B": str(hyp_b.id),
+            "C": str(hyp_c.id),
+            "E_qa": str(ev_qa.id),
+            "E_email": str(ev_email.id),
+            "K": str(conclusion_k.id),
+        },
+        labels={
+            "Q": QUESTION_TEXT,
+            "A": hyp_a.statement,
+            "B": hyp_b.statement,
+            "C": hyp_c.statement,
+            "E_qa": ev_qa.claim,
+            "E_email": ev_email.claim,
+            "K": conclusion_k.statement,
+        },
+    )
+    logger.info("Seeded investigation graph: %s", seeded.ids)
+    return seeded
+
+
+async def build_diamond_investigation() -> SeededGraph:
+    """Build the Session-1 graph WITH a diamond dependency (Conclusion K2).
+
+    This is the same investigation as :func:`build_investigation`, plus one extra
+    Conclusion K2 that *critically depends on BOTH* E_qa and E_email. It exists to
+    demonstrate that FALSIFY's propagation is a grounded least-fixpoint, not a naive
+    cascade: a conclusion with two critical supports survives losing one of them, and
+    only collapses when the LAST support dies.
+
+    Two-phase story the demo drives on top of this graph:
+
+        Phase 1 — refute E_qa (NEW_FACT):
+            E_qa -> refuted ; K (single dep) -> invalidated -> forgotten
+            K2 -> STILL ALIVE (E_email keeps it grounded) ; A superseded, B promoted
+            E_qa -> retained (K2 alive still depends on it, and it anchors NEW_FACT)
+
+        Phase 2 — refute E_email (NEW_FACT_2):
+            E_email -> refuted ; K2 (last dep now dead) -> invalidated -> forgotten
+            B -> superseded ; only C ("did not know") may remain
+
+    The base nodes are re-created here (rather than shared with build_investigation)
+    so the proven single-contradiction demo path stays untouched.
+    """
+    from cognee.tasks.storage import add_data_points
+
+    # ------------------------------------------------------------------ nodes
+    question = InvestigationQuestion(question=QUESTION_TEXT, source_id="investigation")
+
+    hyp_a = Hypothesis(
+        statement="Company X knew via the QA report dated March 2021.",
+        question_id=str(question.id), prior=0.5, confidence=0.6, source_id="analyst",
+    )
+    hyp_b = Hypothesis(
+        statement="Company X knew via a supplier email in January 2021.",
+        question_id=str(question.id), prior=0.5, confidence=0.55, source_id="analyst",
+    )
+    hyp_c = Hypothesis(
+        statement="Company X did not know about the defect before the recall.",
+        question_id=str(question.id), prior=0.5, confidence=0.4, source_id="analyst",
+    )
+
+    ev_qa = Evidence(
+        claim="A QA report dated March 2021 documented the defect internally.",
+        source_id="qa_report_2021_03",
+        quote="Internal QA report, dated 2021-03-15, flags the defect.",
+        stance="supports", asserted_at="2021-03-15", confidence=0.8,
+    )
+    ev_email = Evidence(
+        claim="A supplier email in January 2021 warned Company X about the defect.",
+        source_id="supplier_email_2021_01",
+        quote="Supplier email, 2021-01-20: 'we have observed the defect in test units.'",
+        stance="supports", asserted_at="2021-01-20", confidence=0.7,
+    )
+
+    conclusion_k = Conclusion(
+        statement="Company X knew about the defect by March 2021.",
+        confidence=0.8, depends_on_ids=[str(ev_qa.id)], source_id="analyst",
+    )
+    # THE DIAMOND: K2 rests on two independent critical supports.
+    conclusion_k2 = Conclusion(
+        statement="Multiple independent sources confirm Company X had pre-recall "
+                  "knowledge of the defect.",
+        confidence=0.85,
+        depends_on_ids=[str(ev_qa.id), str(ev_email.id)],
+        source_id="analyst",
+    )
+
+    nodes: List = [question, hyp_a, hyp_b, hyp_c, ev_qa, ev_email, conclusion_k, conclusion_k2]
+
+    logger.info("Persisting %d belief nodes (diamond) via add_data_points", len(nodes))
+    await add_data_points(nodes)
+
+    # ------------------------------------------------------------------ edges
+    await graph_ops.add_edge(str(ev_qa.id), str(hyp_a.id), SUPPORTS, {"weight": 0.8})
+    await graph_ops.add_edge(str(ev_email.id), str(hyp_b.id), SUPPORTS, {"weight": 0.7})
+
+    # K depends on E_qa only (single-leg — dies in phase 1).
+    await graph_ops.add_edge(
+        str(conclusion_k.id), str(ev_qa.id), DEPENDS_ON, {"critical": True}
+    )
+    # K2's two critical legs — the diamond. Survives phase 1, collapses in phase 2.
+    await graph_ops.add_edge(
+        str(conclusion_k2.id), str(ev_qa.id), DEPENDS_ON, {"critical": True}
+    )
+    await graph_ops.add_edge(
+        str(conclusion_k2.id), str(ev_email.id), DEPENDS_ON, {"critical": True}
+    )
+
+    for hyp in (hyp_a, hyp_b, hyp_c):
+        await graph_ops.add_edge(str(hyp.id), str(question.id), "answers", {})
+
+    seeded = SeededGraph(
+        question_id=str(question.id),
+        ids={
+            "Q": str(question.id),
+            "A": str(hyp_a.id), "B": str(hyp_b.id), "C": str(hyp_c.id),
+            "E_qa": str(ev_qa.id), "E_email": str(ev_email.id),
+            "K": str(conclusion_k.id), "K2": str(conclusion_k2.id),
+        },
+        labels={
+            "Q": QUESTION_TEXT,
+            "A": hyp_a.statement, "B": hyp_b.statement, "C": hyp_c.statement,
+            "E_qa": ev_qa.claim, "E_email": ev_email.claim,
+            "K": conclusion_k.statement, "K2": conclusion_k2.statement,
+        },
+    )
+    logger.info("Seeded diamond investigation graph: %s", seeded.ids)
+    return seeded

falsify/tasks/__init__.py

@@ -0,0 +1,36 @@
+"""
+FALSIFY belief-revision tasks.
+
+The three-step revision pipeline, in execution order:
+
+1. :func:`detect_contradictions` — two-gate detector: which existing evidence does a
+   new fact contradict/supersede?
+2. :func:`propagate_refutation` — flip the contradicted evidence to ``refuted`` and
+   cascade ``invalidated`` forward through ``depends_on``; then
+   :func:`promote_competing_hypothesis` re-scores the rival hypotheses.
+3. :func:`cascade_forget` — hard-delete truly-orphaned dead-ends from graph + vector,
+   keeping provenance tombstones.
+"""
+
+from falsify.tasks.detect_contradictions import (
+    Contradiction,
+    ContradictionJudgement,
+    detect_contradictions,
+)
+from falsify.tasks.propagate_refutation import (
+    PropagationResult,
+    promote_competing_hypothesis,
+    propagate_refutation,
+)
+from falsify.tasks.cascade_forget import ForgetResult, cascade_forget
+
+__all__ = [
+    "detect_contradictions",
+    "Contradiction",
+    "ContradictionJudgement",
+    "propagate_refutation",
+    "promote_competing_hypothesis",
+    "PropagationResult",
+    "cascade_forget",
+    "ForgetResult",
+]

falsify/tasks/cascade_forget.py

@@ -0,0 +1,159 @@
+"""
+Surgical forget — prune orphaned dead-ends from graph **and** vector stores.
+
+After :mod:`falsify.tasks.propagate_refutation` marks nodes ``refuted`` /
+``invalidated``, some of those nodes are still useful: they explain *why* a belief
+changed (provenance) or they still feed a node that is alive. Others are pure
+dead-ends with no surviving consumer. FALSIFY hard-deletes only the latter, from
+both the graph (``delete_nodes``) and the vector index (``delete_data_points``), so a
+subsequent ``recall()`` — and even a raw vector search — can never resurface them.
+
+Orphan rule (REQUIREMENTS §1.5) — a node is FORGOTTEN iff ALL hold:
+    (a) truth state is ``refuted`` or ``invalidated`` (never ``alive``/``superseded``;
+        superseded nodes are kept as provenance), AND
+    (b) no surviving ALIVE node reaches it via ``depends_on`` or ``supports``
+        (it has no live consumer), AND
+    (c) it is NOT the target of a ``supersedes`` edge FROM an alive node (such a node
+        is the provenance anchor of the new truth and must be retained as a tombstone).
+
+The asymmetry is deliberate and is what makes FALSIFY look *surgical*: in the demo the
+orphaned Conclusion K is deleted, while the refuted Evidence E_qa is kept — flagged
+red — because it is the supersedes-anchor of the new fact.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Set
+
+from falsify import graph_ops
+from falsify.edges import CONSUMER_EDGE_TYPES, SUPERSEDES
+from falsify.models import (
+    Conclusion,
+    Evidence,
+    TruthState,
+)
+
+logger = logging.getLogger("falsify.forget")
+
+_DELETABLE_STATES = {TruthState.REFUTED.value, TruthState.INVALIDATED.value}
+_ALIVE = TruthState.ALIVE.value
+
+# Vector collections FALSIFY writes to (``"{ClassName}_{embeddable_field}"``).
+# Deleting an id from a collection it isn't in is a best-effort no-op.
+_VECTOR_COLLECTIONS = [
+    "Evidence_claim",
+    "Conclusion_statement",
+    "Hypothesis_statement",
+    "Assertion_text",
+    "InvestigationQuestion_question",
+]
+
+
+@dataclass
+class ForgetResult:
+    """Outcome of a forget pass.
+
+    Attributes:
+        forgotten: node ids hard-deleted from graph + vector.
+        retained_provenance: refuted/invalidated ids deliberately kept (a supersedes
+            anchor, or still feeding a live node).
+        labels: id -> human label for the forgotten nodes (for demo output).
+    """
+
+    forgotten: List[str] = field(default_factory=list)
+    retained_provenance: List[str] = field(default_factory=list)
+    labels: Dict[str, str] = field(default_factory=dict)
+
+
+async def _alive_consumer_exists(node_id: str, edges, truth: Dict[str, List[str]]) -> bool:
+    """True if some ALIVE node reaches ``node_id`` via depends_on/supports.
+
+    ``depends_on`` (Conclusion->Evidence) and ``supports`` (Evidence->Hypothesis) both
+    point *from consumer to the thing consumed*, so an incoming edge's **source** is a
+    consumer of ``node_id``.
+    """
+    nid = str(node_id)
+    for rel in CONSUMER_EDGE_TYPES:
+        for src, _props in graph_ops.incoming(nid, edges, rel):
+            alignment = truth.get(str(src), [_ALIVE])
+            if _ALIVE in alignment:
+                return True
+    return False
+
+
+def _is_supersedes_anchor(node_id: str, edges, truth: Dict[str, List[str]]) -> bool:
+    """True if ``node_id`` is the target of a ``supersedes`` edge from an ALIVE node.
+
+    That alive source is the new, current truth; the target is its tombstone and must
+    be retained as provenance.
+    """
+    nid = str(node_id)
+    for src, _props in graph_ops.incoming(nid, edges, SUPERSEDES):
+        alignment = truth.get(str(src), [_ALIVE])
+        if _ALIVE in alignment:
+            return True
+    return False
+
+
+async def cascade_forget(candidate_ids: List[str]) -> ForgetResult:
+    """Delete truly-orphaned dead-ends among ``candidate_ids``; keep provenance.
+
+    Args:
+        candidate_ids: nodes marked refuted/invalidated by a preceding cascade.
+
+    Returns:
+        A :class:`ForgetResult`. Deleted nodes are removed from the graph and from
+        every FALSIFY vector collection, so no retrieval path can resurface them.
+    """
+    result = ForgetResult()
+    candidates = [str(c) for c in dict.fromkeys(candidate_ids) if c]
+    if not candidates:
+        return result
+
+    nodes, edges = await graph_ops.load_graph()
+    props_by_id = {str(nid): (props or {}) for nid, props in nodes}
+
+    # Current truth for candidates + their neighbors (consumers/anchors).
+    neighbor_ids: Set[str] = set(candidates)
+    for cid in candidates:
+        for rel in (*CONSUMER_EDGE_TYPES, SUPERSEDES):
+            neighbor_ids.update(str(s) for s, _p in graph_ops.incoming(cid, edges, rel))
+    truth = await graph_ops.get_truth(list(neighbor_ids))
+
+    death_set: List[str] = []
+    for cid in candidates:
+        alignment = truth.get(cid, [_ALIVE])
+
+        # (a) must be refuted/invalidated
+        if not any(state in _DELETABLE_STATES for state in alignment):
+            continue
+        # (c) keep supersedes anchors (provenance tombstones)
+        if _is_supersedes_anchor(cid, edges, truth):
+            result.retained_provenance.append(cid)
+            logger.info("retained %s as supersedes provenance anchor", cid)
+            continue
+        # (b) keep nodes that still feed a live consumer
+        if await _alive_consumer_exists(cid, edges, truth):
+            result.retained_provenance.append(cid)
+            logger.info("retained %s (still feeds a live node)", cid)
+            continue
+
+        death_set.append(cid)
+        result.labels[cid] = graph_ops.node_label(props_by_id.get(cid, {}))
+
+    if not death_set:
+        logger.info("forget pass: nothing orphaned; %d provenance nodes retained",
+                    len(result.retained_provenance))
+        return result
+
+    # Hard-delete from graph + all vector collections in one batch.
+    deleted = await graph_ops.delete_from_both_stores(death_set, _VECTOR_COLLECTIONS)
+    result.forgotten = death_set
+    logger.info(
+        "forget pass: hard-deleted %d orphan(s) from graph + vector; retained %d provenance",
+        deleted,
+        len(result.retained_provenance),
+    )
+    return result

falsify/tasks/detect_contradictions.py

@@ -0,0 +1,199 @@
+"""
+Two-gate contradiction detection — the trigger for belief revision.
+
+Deciding that a new fact *contradicts* an existing belief is the one genuinely
+fuzzy step in FALSIFY. A false positive nukes a valid conclusion; a false negative
+lets a stale fact survive. We therefore gate it twice, cheap-deterministic first,
+expensive-semantic second, with a hard deterministic override for the live demo.
+
+    Gate 1 — vector prefilter (deterministic).
+        Embed the new fact and search the ``Evidence_claim`` collection. Only
+        evidence within a cosine-distance threshold (``< 0.35`` by default, i.e.
+        clearly on-topic) proceeds. This narrows the LLM to plausibly-conflicting
+        claims and keeps cost + nondeterminism bounded.
+
+    Gate 2 — LLM adjudication (semantic).
+        For each surviving candidate, ask an LLM acting as a skeptical analyst to
+        classify the relation as contradicts / supersedes / supports / unrelated with
+        a confidence. Only ``contradicts`` or ``supersedes`` at confidence >= 0.6
+        triggers refutation. This separates a genuine contradiction ("the report was
+        back-dated") from mere topical overlap ("also mentions the report").
+
+    Demo override (``pinned_target_id`` / ``DEMO_MODE``).
+        When set, gates are bypassed and a fixed high-confidence ``contradicts``
+        verdict is returned for the pinned evidence id, so the on-stage cascade runs
+        on real graph APIs even if the LLM is slow, rate-limited, or the key is
+        absent. This is FALSIFY's demo safety net (REQUIREMENTS §1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from falsify import graph_ops
+
+logger = logging.getLogger("falsify.detect")
+
+# Cosine distance below which two claims are "about the same thing" (Gate 1).
+DEFAULT_DISTANCE_THRESHOLD = 0.35
+# Minimum LLM confidence for a contradiction/supersede to count (Gate 2).
+DEFAULT_CONFIDENCE_THRESHOLD = 0.6
+# Vector collection holding Evidence claims.
+_EVIDENCE_COLLECTION = "Evidence_claim"
+
+_SYSTEM_PROMPT = (
+    "You are a skeptical forensic analyst. You are given an EXISTING evidence claim "
+    "and a NEW fact. Decide the logical relation of the NEW fact to the EXISTING "
+    "claim. Answer 'contradicts' only if the new fact makes the existing claim false "
+    "or untrustworthy (e.g. it was fabricated, back-dated, retracted, or refuted). "
+    "Answer 'supersedes' if the new fact replaces the existing claim with a newer, "
+    "more authoritative version of the same fact. Answer 'supports' if it corroborates "
+    "the claim, and 'unrelated' otherwise. Be conservative: when unsure, prefer "
+    "'unrelated'. Provide a calibrated confidence in [0,1] and a one-sentence rationale."
+)
+
+
+class ContradictionJudgement(BaseModel):
+    """Structured verdict returned by the Gate-2 LLM adjudication."""
+
+    relation: Literal["contradicts", "supersedes", "supports", "unrelated"]
+    confidence: float = Field(ge=0.0, le=1.0)
+    rationale: str = ""
+
+
+@dataclass
+class Contradiction:
+    """A confirmed conflict between the new fact and an existing evidence node.
+
+    Attributes:
+        target_id: the existing Evidence node id that is contradicted/superseded.
+        relation: ``contradicts`` or ``supersedes``.
+        confidence: adjudicated confidence.
+        rationale: short human explanation (shown in the demo).
+        distance: Gate-1 cosine distance (lower = more on-topic).
+    """
+
+    target_id: str
+    relation: str
+    confidence: float
+    rationale: str = ""
+    distance: float = 0.0
+
+
+async def detect_contradictions(
+    new_fact: str,
+    *,
+    pinned_target_id: Optional[str] = None,
+    distance_threshold: float = DEFAULT_DISTANCE_THRESHOLD,
+    confidence_threshold: float = DEFAULT_CONFIDENCE_THRESHOLD,
+    max_candidates: int = 5,
+) -> List[Contradiction]:
+    """Return the existing evidence nodes that ``new_fact`` contradicts or supersedes.
+
+    Args:
+        new_fact: the incoming claim (e.g. the Session-2 forensic finding).
+        pinned_target_id: demo/deterministic override; if given, gates are skipped and
+            a single high-confidence ``contradicts`` verdict is returned for this id.
+        distance_threshold: Gate-1 cosine-distance cutoff (lower = stricter on-topic).
+        confidence_threshold: Gate-2 minimum confidence to accept a verdict.
+        max_candidates: cap on Gate-1 candidates sent to the LLM.
+
+    Returns:
+        A list of :class:`Contradiction` (possibly empty). Callers feed the target
+        ids into :func:`falsify.tasks.propagate_refutation.propagate_refutation`.
+    """
+    # -------- Demo / deterministic override -------------------------------
+    if pinned_target_id:
+        logger.info("detect_contradictions: pinned target %s (demo mode)", pinned_target_id)
+        return [
+            Contradiction(
+                target_id=str(pinned_target_id),
+                relation="contradicts",
+                confidence=0.9,
+                rationale="Pinned contradiction (demo mode): new fact invalidates the target evidence.",
+                distance=0.0,
+            )
+        ]
+
+    # -------- Gate 1: vector prefilter ------------------------------------
+    ve = graph_ops.get_vector_engine()
+    try:
+        hits = await ve.search(
+            _EVIDENCE_COLLECTION,
+            query_text=new_fact,
+            limit=max_candidates,
+            include_payload=True,
+        )
+    except Exception as exc:
+        logger.warning("Gate-1 vector search failed (%s); no contradictions detected", exc)
+        return []
+
+    candidates = [(str(h.id), float(getattr(h, "score", 1.0)), getattr(h, "payload", {}) or {})
+                  for h in (hits or [])]
+    on_topic = [c for c in candidates if c[1] < distance_threshold]
+    logger.info(
+        "Gate-1: %d hit(s), %d within distance %.2f", len(candidates), len(on_topic), distance_threshold
+    )
+    if not on_topic:
+        return []
+
+    # -------- Gate 2: LLM adjudication ------------------------------------
+    from cognee.infrastructure.llm.LLMGateway import LLMGateway
+
+    confirmed: List[Contradiction] = []
+    for target_id, distance, payload in on_topic:
+        existing_claim = _payload_text(payload) or "(existing evidence claim)"
+        text_input = (
+            f"EXISTING claim:\n{existing_claim}\n\nNEW fact:\n{new_fact}\n\n"
+            "Classify the relation of the NEW fact to the EXISTING claim."
+        )
+        try:
+            verdict: ContradictionJudgement = await LLMGateway.acreate_structured_output(
+                text_input=text_input,
+                system_prompt=_SYSTEM_PROMPT,
+                response_model=ContradictionJudgement,
+            )
+        except Exception as exc:
+            logger.warning("Gate-2 LLM judge failed for %s (%s); skipping candidate", target_id, exc)
+            continue
+
+        if verdict.relation in ("contradicts", "supersedes") and verdict.confidence >= confidence_threshold:
+            confirmed.append(
+                Contradiction(
+                    target_id=target_id,
+                    relation=verdict.relation,
+                    confidence=verdict.confidence,
+                    rationale=verdict.rationale,
+                    distance=distance,
+                )
+            )
+            logger.info(
+                "Gate-2: CONFIRMED %s on %s (conf=%.2f)", verdict.relation, target_id, verdict.confidence
+            )
+        else:
+            logger.info(
+                "Gate-2: rejected %s (relation=%s conf=%.2f)",
+                target_id, verdict.relation, verdict.confidence,
+            )
+
+    return confirmed
+
+
+def _payload_text(payload: dict) -> Optional[str]:
+    """Extract the human-readable claim text from a vector-hit payload."""
+    if not payload:
+        return None
+    for key in ("claim", "text", "statement", "content"):
+        if payload.get(key):
+            return str(payload[key])
+    # cognee payloads sometimes nest the original properties
+    props = payload.get("properties") or payload.get("metadata")
+    if isinstance(props, dict):
+        for key in ("claim", "text", "statement"):
+            if props.get(key):
+                return str(props[key])
+    return None

falsify/tasks/propagate_refutation.py

@@ -0,0 +1,281 @@
+"""
+Forward refutation propagation — the core of FALSIFY's belief revision.
+
+When a piece of Evidence is refuted, the conclusions that *depend on it* can no
+longer stand. This module walks the dependency structure and flips the truth-state
+of every node that transitively rests on the refuted evidence, then re-scores the
+competing hypotheses.
+
+Why this can't be done by RAG
+-----------------------------
+Vector similarity has no notion of "this fact supports that conclusion three hops
+away." Refutation propagation is *graph traversal over typed edges* — it is exactly
+the thing a knowledge graph can do and an embedding index cannot. This is FALSIFY's
+differentiator and maps directly to the hackathon's "Best Use of Cognee" criterion.
+
+Direction of travel (critical detail)
+-------------------------------------
+The ``depends_on`` edge points **Conclusion -> Evidence** (a conclusion depends on
+the evidence it rests on). So to find what *breaks* when Evidence ``E`` is refuted,
+we look for ``depends_on`` edges whose **target** is ``E``; their **sources** are the
+dependent Conclusions. We then recurse: a newly-invalidated Conclusion may itself be
+the target of further ``depends_on`` edges.
+
+Correctness cases handled (REQUIREMENTS §4.3)
+--------------------------------------------
+* **Cycle safety** — a ``visited`` set guarantees termination on cyclic graphs.
+* **Critical vs non-critical** — only a ``critical: true`` dependency can invalidate
+  a conclusion. A non-critical dependency being refuted decays confidence but the
+  conclusion stays ``alive``.
+* **Diamond / partial refutation** — a conclusion with several critical supporters is
+  invalidated only when it loses its **last** alive critical supporter. If an
+  alternative critical support is still alive, the conclusion survives (and the
+  refuted evidence is *retained*, because it still feeds a live node).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Set
+
+from falsify import graph_ops
+from falsify.edges import (
+    DEPENDENCY_EDGE_TYPES,
+    DEPENDS_ON,
+    SUPPORTS,
+    is_critical_dependency,
+)
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.propagate")
+
+# Truth states that count as "dead" for the purpose of dependency support.
+_DEAD_STATES = {TruthState.REFUTED.value, TruthState.INVALIDATED.value, TruthState.FORGOTTEN.value}
+
+
+@dataclass
+class PropagationResult:
+    """Outcome of a refutation cascade.
+
+    Attributes:
+        refuted: evidence node ids set to ``refuted`` (the cascade seeds).
+        invalidated: conclusion node ids set to ``invalidated`` by the cascade.
+        weakened: conclusion ids whose confidence decayed but stayed ``alive``
+            (a non-critical dependency was refuted).
+        epoch: the revision epoch stamped on every state change in this cascade.
+        affected: convenience union of refuted + invalidated ids (the death set
+            candidates for :mod:`falsify.tasks.cascade_forget`).
+    """
+
+    refuted: List[str] = field(default_factory=list)
+    invalidated: List[str] = field(default_factory=list)
+    weakened: List[str] = field(default_factory=list)
+    epoch: int = 0
+
+    @property
+    def affected(self) -> List[str]:
+        return list(dict.fromkeys(self.refuted + self.invalidated))
+
+
+async def _next_epoch() -> int:
+    """Return a monotonically increasing revision epoch.
+
+    We derive it from the current maximum ``truth_epoch`` present on any node so the
+    counter survives restarts (state is persisted on nodes). Falls back to 1.
+    """
+    try:
+        nodes, _edges = await graph_ops.load_graph()
+        max_epoch = 0
+        for _nid, props in nodes:
+            ep = props.get("truth_epoch")
+            if isinstance(ep, int) and ep > max_epoch:
+                max_epoch = ep
+        return max_epoch + 1
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("epoch derivation failed (%s); defaulting to 1", exc)
+        return 1
+
+
+async def propagate_refutation(
+    refuted_evidence_ids: List[str],
+    epoch: Optional[int] = None,
+) -> PropagationResult:
+    """Refute the given evidence and cascade the consequence forward.
+
+    Args:
+        refuted_evidence_ids: evidence node ids directly contradicted by a new fact.
+        epoch: optional explicit revision epoch; if omitted a fresh one is derived.
+
+    Returns:
+        A :class:`PropagationResult` describing what changed. All state changes are
+        persisted on the graph nodes via ``set_node_truth_state`` (so they survive a
+        process restart — the basis of cross-session belief revision).
+
+    Algorithm — grounded least-fixpoint justification
+    -------------------------------------------------
+    A conclusion is *justified* only if it has a **critical** ``depends_on`` support
+    chain that bottoms out in a still-alive node. We therefore:
+
+        1. Mark each seed evidence ``refuted``.
+        2. Build the "dead" set = seeds plus anything already refuted / invalidated /
+           superseded from prior revisions.
+        3. Compute the GROUNDED set as a least fixpoint: a node is grounded if it is
+           not dead and either (a) it has no critical ``depends_on`` edges (a base
+           node — evidence, or a conclusion resting only on non-critical support) or
+           (b) at least one of its critical dependencies is itself grounded. Iterate
+           to convergence.
+        4. Every *conclusion* (a node that is the source of a ``depends_on`` edge)
+           that is currently alive but **not** grounded is ``invalidated``.
+        5. A conclusion that survives (stays grounded) yet lost some dependency to the
+           dead set is merely ``weakened`` (confidence decayed).
+
+    This single formulation is correct for chains, diamonds (survives while any
+    critical alternative is grounded), partial/non-critical refutation, **and cycles**
+    (a mutually-supporting loop with no grounded base is not justified, so it
+    collapses) — the fixpoint terminates because ``grounded`` only ever grows.
+    """
+    result = PropagationResult(epoch=epoch if epoch is not None else await _next_epoch())
+    seeds = [str(e) for e in refuted_evidence_ids if e]
+    if not seeds:
+        logger.info("propagate_refutation called with no seeds; nothing to do")
+        return result
+
+    nodes, edges = await graph_ops.load_graph()
+    node_ids = [str(nid) for nid, _p in nodes]
+
+    # 1) seed refutations (persisted)
+    for ev_id in seeds:
+        await graph_ops.set_state(ev_id, TruthState.REFUTED, result.epoch)
+        await graph_ops.set_weight(ev_id, 0.0)
+        result.refuted.append(ev_id)
+        logger.info("refuted evidence %s", ev_id)
+
+    # 2) dead set = seeds + already-dead-from-prior-revisions
+    truth = await graph_ops.get_truth(node_ids)
+    dead: Set[str] = set(seeds)
+    for nid in node_ids:
+        alignment = truth.get(nid, [TruthState.ALIVE.value])
+        if any(s in _DEAD_STATES or s == TruthState.SUPERSEDED.value for s in alignment):
+            dead.add(nid)
+
+    # Dependency structure: node -> critical / all depends_on targets.
+    conclusions: Set[str] = set()
+    critical_targets: Dict[str, Set[str]] = {}
+    all_targets: Dict[str, Set[str]] = {}
+    for src, dst, rel, props in edges:
+        if rel not in DEPENDENCY_EDGE_TYPES:
+            continue
+        s, d = str(src), str(dst)
+        conclusions.add(s)
+        all_targets.setdefault(s, set()).add(d)
+        if is_critical_dependency(rel, props):
+            critical_targets.setdefault(s, set()).add(d)
+
+    def _has_critical(n: str) -> bool:
+        return bool(critical_targets.get(n))
+
+    # 3) grounded least fixpoint
+    grounded: Set[str] = {nid for nid in node_ids if nid not in dead and not _has_critical(nid)}
+    changed = True
+    while changed:
+        changed = False
+        for c in conclusions:
+            if c in grounded or c in dead:
+                continue
+            if critical_targets.get(c, set()) & grounded:
+                grounded.add(c)
+                changed = True
+
+    # 4) invalidate currently-alive conclusions that lost grounding
+    for c in conclusions:
+        if c in grounded:
+            continue
+        alignment = truth.get(c, [TruthState.ALIVE.value])
+        if TruthState.ALIVE.value not in alignment:
+            continue  # already dead in a prior revision; don't re-report
+        await graph_ops.set_state(c, TruthState.INVALIDATED, result.epoch)
+        await graph_ops.set_weight(c, 0.0)
+        result.invalidated.append(c)
+        logger.info("invalidated conclusion %s (lost grounded critical support)", c)
+
+    # 5) weaken survivors that lost some dependency to the dead set
+    for c in conclusions:
+        if c not in grounded:
+            continue
+        if all_targets.get(c, set()) & dead:
+            result.weakened.append(c)
+            await graph_ops.set_weight(c, 0.3)
+            logger.info("weakened conclusion %s (lost a dependency but stays grounded)", c)
+
+    logger.info(
+        "propagation done: refuted=%d invalidated=%d weakened=%d epoch=%d",
+        len(result.refuted),
+        len(result.invalidated),
+        len(result.weakened),
+        result.epoch,
+    )
+    return result
+
+
+async def promote_competing_hypothesis(
+    refuted_evidence_ids: List[str],
+    epoch: int,
+) -> Dict[str, str]:
+    """Demote hypotheses whose support just died; promote the strongest survivor.
+
+    A hypothesis is ``superseded`` when every ``supports`` Evidence pointing at it is
+    now dead. Among the hypotheses still holding at least one alive ``supports`` edge,
+    the one with the greatest summed support ``weight`` is promoted (its feedback
+    weight is boosted) and becomes the new frontier answer.
+
+    Returns a dict mapping hypothesis id -> action (``"superseded"`` / ``"promoted"``).
+    """
+    actions: Dict[str, str] = {}
+    _nodes, edges = await graph_ops.load_graph()
+
+    # Collect hypotheses that are the target of any supports edge.
+    supports_edges = [(s, d, p) for (s, d, r, p) in edges if r == SUPPORTS]
+    hypothesis_ids = {str(d) for (_s, d, _p) in supports_edges}
+    if not hypothesis_ids:
+        return actions
+
+    # Determine current dead evidence set (seeds + anything already refuted/invalidated).
+    all_ids = list({str(s) for (s, _d, _p) in supports_edges} | {str(e) for e in refuted_evidence_ids})
+    truth = await graph_ops.get_truth(all_ids)
+
+    def _is_dead(node_id: str) -> bool:
+        alignment = truth.get(str(node_id), [TruthState.ALIVE.value])
+        return any(state in _DEAD_STATES for state in alignment) or str(node_id) in {
+            str(e) for e in refuted_evidence_ids
+        }
+
+    # Score each hypothesis by its surviving support.
+    live_support: Dict[str, float] = {}
+    for hyp_id in hypothesis_ids:
+        total = 0.0
+        for (src, dst, props) in supports_edges:
+            if str(dst) != hyp_id:
+                continue
+            if _is_dead(src):
+                continue
+            total += float(props.get("weight", 0.5))
+        live_support[hyp_id] = total
+
+    # Demote hypotheses with zero surviving support.
+    for hyp_id, score in live_support.items():
+        if score <= 0.0:
+            await graph_ops.set_state(hyp_id, TruthState.SUPERSEDED, epoch)
+            await graph_ops.set_weight(hyp_id, 0.0)
+            actions[hyp_id] = "superseded"
+            logger.info("superseded hypothesis %s (no surviving support)", hyp_id)
+
+    # Promote the strongest surviving hypothesis, if any.
+    survivors = {h: s for h, s in live_support.items() if s > 0.0}
+    if survivors:
+        winner = max(survivors, key=survivors.get)
+        await graph_ops.set_weight(winner, 1.0)
+        actions[winner] = "promoted"
+        logger.info("promoted hypothesis %s (support=%.2f) as new frontier", winner, survivors[winner])
+
+    return actions

falsify/utils.py

@@ -0,0 +1,250 @@
+"""
+FALSIFY presentation helpers — console state + interactive graph visualization.
+
+These functions turn the belief graph into the two things a judge actually sees:
+
+* :func:`print_graph_state` — the BEFORE/AFTER console beat, each node tagged with a
+  colored ``ALIVE`` / ``REFUTED`` / ``INVALIDATED`` / ``SUPERSEDED`` marker.
+* :func:`visualize_belief_graph` — a single self-contained HTML file (vis-network via
+  CDN, no build step) that colors nodes by truth-state so the cascade is legible at a
+  glance: green = alive, red (dashed) = refuted, grey = invalidated, amber = superseded.
+* :func:`get_belief_summary` — counts by type/state, used in output and tests.
+* :func:`verify_propagation` — a small assertion helper for tests.
+
+Everything degrades gracefully on an empty graph and never hard-depends on ``rich``.
+"""
+
+from __future__ import annotations
+
+import html
+import json
+import logging
+import os
+from typing import Dict, List, Optional
+
+from falsify import graph_ops
+from falsify.models import TruthState
+
+logger = logging.getLogger("falsify.utils")
+
+# truth-state -> (console tag, hex color for the graph)
+_STATE_STYLE = {
+    TruthState.ALIVE.value: ("ALIVE", "#22c55e"),
+    TruthState.REFUTED.value: ("REFUTED", "#ef4444"),
+    TruthState.INVALIDATED.value: ("INVALIDATED", "#9ca3af"),
+    TruthState.SUPERSEDED.value: ("SUPERSEDED", "#f59e0b"),
+    TruthState.FORGOTTEN.value: ("FORGOTTEN", "#4b5563"),
+}
+
+# ANSI colors for console tags (fall back to plain text if not a TTY).
+_ANSI = {
+    "ALIVE": "\033[92m",
+    "REFUTED": "\033[91m",
+    "INVALIDATED": "\033[90m",
+    "SUPERSEDED": "\033[93m",
+    "FORGOTTEN": "\033[90m",
+}
+_RESET = "\033[0m"
+
+
+def _colored(tag: str) -> str:
+    """Return an ANSI-colored tag if stdout is a TTY, else the plain tag."""
+    if os.environ.get("NO_COLOR") or not _stdout_is_tty():
+        return tag
+    return f"{_ANSI.get(tag, '')}{tag}{_RESET}"
+
+
+def _stdout_is_tty() -> bool:
+    try:
+        import sys
+
+        return bool(sys.stdout.isatty())
+    except Exception:
+        return False
+
+
+async def _state_of(node_ids: List[str]) -> Dict[str, str]:
+    """Return ``{id: single-state-string}`` (first alignment entry, default alive)."""
+    truth = await graph_ops.get_truth(node_ids)
+    return {nid: (align[0] if align else TruthState.ALIVE.value) for nid, align in truth.items()}
+
+
+async def get_belief_summary(dataset: Optional[str] = None) -> Dict[str, Dict[str, int]]:
+    """Count nodes grouped by node type and truth-state.
+
+    Returns e.g. ``{"Hypothesis": {"alive": 2, "superseded": 1}, "Conclusion": {...}}``.
+    Node type is inferred from the node's ``type`` property, falling back to the
+    dominant embeddable field present.
+    """
+    nodes, _edges = await graph_ops.load_graph()
+    if not nodes:
+        return {}
+    states = await _state_of([str(nid) for nid, _p in nodes])
+    summary: Dict[str, Dict[str, int]] = {}
+    for nid, props in nodes:
+        ntype = _infer_type(props)
+        state = states.get(str(nid), TruthState.ALIVE.value)
+        summary.setdefault(ntype, {})
+        summary[ntype][state] = summary[ntype].get(state, 0) + 1
+    return summary
+
+
+def _infer_type(props: dict) -> str:
+    """Best-effort node-type label from properties."""
+    if props.get("type"):
+        return str(props["type"])
+    for field, label in (
+        ("question", "InvestigationQuestion"),
+        ("claim", "Evidence"),
+        ("statement", "Hypothesis/Conclusion"),
+        ("text", "Assertion"),
+    ):
+        if props.get(field):
+            return label
+    return "Node"
+
+
+async def print_graph_state(title: str, dataset: Optional[str] = None) -> None:
+    """Print every node with a colored truth-state tag (the BEFORE/AFTER beat)."""
+    nodes, _edges = await graph_ops.load_graph()
+    print(f"\n{'=' * 64}\n  {title}\n{'=' * 64}")
+    if not nodes:
+        print("  (empty graph)")
+        return
+    states = await _state_of([str(nid) for nid, _p in nodes])
+    # Stable, readable ordering: questions, hypotheses, evidence, conclusions.
+    order = {"InvestigationQuestion": 0, "Hypothesis/Conclusion": 1, "Evidence": 2, "Assertion": 3}
+    rows = []
+    for nid, props in nodes:
+        ntype = _infer_type(props)
+        state = states.get(str(nid), TruthState.ALIVE.value)
+        tag = _STATE_STYLE.get(state, ("ALIVE", ""))[0]
+        label = graph_ops.node_label(props)
+        rows.append((order.get(ntype, 9), ntype, tag, label))
+    for _o, ntype, tag, label in sorted(rows, key=lambda r: r[0]):
+        clipped = label if len(label) <= 66 else label[:63] + "..."
+        print(f"  [{_colored(tag):<22}] {ntype:<22} {clipped}")
+    print()
+
+
+async def visualize_belief_graph(
+    out_path: str = "output/graph.html",
+    dataset: Optional[str] = None,
+    title: str = "FALSIFY belief graph",
+) -> Optional[str]:
+    """Write a self-contained interactive HTML visualization of the belief graph.
+
+    Nodes are colored by truth-state (green/red/grey/amber). Refuted nodes are drawn
+    with a dashed red border so the cascade result reads at a glance. Returns the
+    written path, or ``None`` if the graph is empty.
+    """
+    nodes, edges = await graph_ops.load_graph()
+    if not nodes:
+        logger.info("visualize_belief_graph: empty graph, nothing to draw")
+        return None
+
+    states = await _state_of([str(nid) for nid, _p in nodes])
+
+    vis_nodes = []
+    for nid, props in nodes:
+        nid = str(nid)
+        state = states.get(nid, TruthState.ALIVE.value)
+        tag, color = _STATE_STYLE.get(state, ("ALIVE", "#22c55e"))
+        label = graph_ops.node_label(props)
+        short = label if len(label) <= 40 else label[:37] + "..."
+        vis_nodes.append(
+            {
+                "id": nid,
+                "label": short,
+                "title": f"{_infer_type(props)} — {tag}\n{html.escape(label)}",
+                "color": {"background": color, "border": "#111827"},
+                "shapeProperties": {"borderDashes": state == TruthState.REFUTED.value},
+                "borderWidth": 3 if state == TruthState.REFUTED.value else 1,
+                "font": {"color": "#0b1020"},
+            }
+        )
+
+    vis_edges = []
+    for src, dst, rel, props in edges:
+        vis_edges.append(
+            {
+                "from": str(src),
+                "to": str(dst),
+                "label": rel,
+                "arrows": "to",
+                "font": {"align": "middle", "size": 10},
+                "color": {"color": "#94a3b8"},
+            }
+        )
+
+    os.makedirs(os.path.dirname(out_path) or ".", exist_ok=True)
+    doc = _HTML_TEMPLATE.replace("__TITLE__", html.escape(title)) \
+        .replace("__NODES__", json.dumps(vis_nodes)) \
+        .replace("__EDGES__", json.dumps(vis_edges))
+    with open(out_path, "w", encoding="utf-8") as fh:
+        fh.write(doc)
+    logger.info("wrote visualization to %s (%d nodes, %d edges)", out_path, len(vis_nodes), len(vis_edges))
+    return out_path
+
+
+async def verify_propagation(refuted_id: str, expected_affected: List[str]) -> bool:
+    """Test helper: assert every ``expected_affected`` id is now non-alive.
+
+    Returns True iff the refuted node is refuted and each expected dependent is in a
+    dead state (refuted/invalidated/forgotten or absent from the graph).
+    """
+    ids = [str(refuted_id)] + [str(x) for x in expected_affected]
+    truth = await graph_ops.get_truth(ids)
+    dead = {TruthState.REFUTED.value, TruthState.INVALIDATED.value, TruthState.FORGOTTEN.value}
+    nodes, _edges = await graph_ops.load_graph()
+    present = {str(nid) for nid, _p in nodes}
+
+    r_align = truth.get(str(refuted_id), [])
+    if TruthState.REFUTED.value not in r_align:
+        return False
+    for dep in expected_affected:
+        dep = str(dep)
+        if dep not in present:  # forgotten (deleted) counts as affected
+            continue
+        if not any(s in dead for s in truth.get(dep, [TruthState.ALIVE.value])):
+            return False
+    return True
+
+
+_HTML_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>__TITLE__</title>
+  <script src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+  <style>
+    body { margin:0; font-family: ui-sans-serif, system-ui, sans-serif; background:#0b1020; color:#e5e7eb; }
+    #hdr { padding:14px 18px; font-size:18px; font-weight:600; border-bottom:1px solid #1f2937; }
+    #legend { padding:8px 18px; font-size:13px; color:#9ca3af; }
+    .chip { display:inline-block; width:11px; height:11px; border-radius:3px; margin:0 5px 0 14px; vertical-align:middle; }
+    #net { width:100%; height:calc(100vh - 92px); }
+  </style>
+</head>
+<body>
+  <div id="hdr">__TITLE__</div>
+  <div id="legend">
+    <span class="chip" style="background:#22c55e"></span>alive
+    <span class="chip" style="background:#ef4444"></span>refuted
+    <span class="chip" style="background:#9ca3af"></span>invalidated
+    <span class="chip" style="background:#f59e0b"></span>superseded
+  </div>
+  <div id="net"></div>
+  <script>
+    const nodes = new vis.DataSet(__NODES__);
+    const edges = new vis.DataSet(__EDGES__);
+    const container = document.getElementById('net');
+    const options = {
+      physics: { stabilization: true, barnesHut: { gravitationalConstant: -8000, springLength: 150 } },
+      nodes: { shape: 'box', margin: 10, widthConstraint: { maximum: 200 } },
+      edges: { smooth: { type: 'cubicBezier' } }
+    };
+    new vis.Network(container, { nodes, edges }, options);
+  </script>
+</body>
+</html>
+"""

main.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""
+FALSIFY — the AI research copilot that *revises*, not forgets.
+
+Run this to watch belief revision happen on a real Cognee knowledge graph:
+
+    python main.py            # full run (uses your LLM to judge the contradiction)
+    python main.py --demo     # deterministic: pins the contradiction so the cascade
+                              #   always runs, even without/with a flaky LLM key
+    python main.py --keep     # don't prune existing memory first (advanced)
+
+The story (Company X recall investigation)
+------------------------------------------
+Session 1 builds a belief graph with two competing hypotheses:
+    A — "X knew via the March 2021 QA report"        (supported by evidence E_qa)
+    B — "X knew via a January 2021 supplier email"   (supported by evidence E_email)
+and a Conclusion K that *depends on* E_qa.
+
+Session 2 drops ONE contradicting fact: "the March QA report was back-dated."
+FALSIFY refutes E_qa, cascades the refutation forward (K collapses), promotes B as
+the new frontier, and surgically forgets the orphaned conclusion — writing the
+disbelief onto the graph so it survives a restart. A plain-RAG baseline, which has no
+notion of truth-state, keeps citing the refuted March report. That contrast is the
+whole point: *AI revised, not forgot.*
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+
+# Load .env before importing cognee/falsify so provider config is in place.
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except Exception:  # python-dotenv is optional; env may be set another way
+    pass
+
+# Importing falsify sets single-user Cognee env defaults (access control off, cache on).
+import falsify  # noqa: F401  (import-time side effects)
+from falsify.seed import NEW_FACT, QUESTION_TEXT
+
+
+C = {
+    "b": "\033[1m", "dim": "\033[2m", "g": "\033[92m", "r": "\033[91m",
+    "y": "\033[93m", "c": "\033[96m", "x": "\033[0m",
+}
+if os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+    C = {k: "" for k in C}
+
+
+def banner(text: str) -> None:
+    print(f"\n{C['b']}{C['c']}{'━' * 64}{C['x']}")
+    print(f"{C['b']}{C['c']}  {text}{C['x']}")
+    print(f"{C['b']}{C['c']}{'━' * 64}{C['x']}")
+
+
+def _has_llm_key() -> bool:
+    """True if some LLM API key is configured (OpenAI-compatible or otherwise)."""
+    for var in ("LLM_API_KEY", "OPENAI_API_KEY"):
+        if os.environ.get(var):
+            return True
+    return False
+
+
+def _print_no_key_help() -> None:
+    print(
+        f"""
+{C['y']}{C['b']}No LLM API key found.{C['x']}
+
+FALSIFY needs an OpenAI-compatible API key to (a) embed claims for the vector
+prefilter and (b) judge contradictions. Set it up:
+
+  1. cp .env.template .env
+  2. edit .env and set:
+       LLM_API_KEY="your_key_here"
+       LLM_MODEL="gpt-4o-mini"          # or any OpenAI-compatible model
+       # For a non-OpenAI endpoint (OpenRouter, vLLM, LM Studio, Groq):
+       #   LLM_PROVIDER="custom"
+       #   LLM_ENDPOINT="https://your-endpoint/v1"
+  3. re-run:  python main.py
+
+{C['dim']}Tip: `python main.py --demo` runs FULLY OFFLINE — fastembed handles
+embeddings locally and the contradiction is pinned, so no API key is needed at all.
+A key is only required for LIVE mode, where the LLM judges the contradiction.{C['x']}
+"""
+    )
+
+
+async def run(demo: bool, keep: bool) -> int:
+    from falsify.falsify import build_graph, revise, scoreboard
+    from falsify.utils import get_belief_summary, print_graph_state, visualize_belief_graph
+
+    banner("FALSIFY — belief-revision research copilot")
+    print(f"  Research question: {C['b']}{QUESTION_TEXT}{C['x']}")
+    print(f"  Mode: {'DEMO (deterministic contradiction pin)' if demo else 'LIVE (LLM judge)'}")
+
+    # ---- Session 1: build the belief graph -------------------------------
+    banner("SESSION 1 — build the investigation")
+    if keep:
+        from cognee.low_level import setup
+
+        from falsify.seed import build_investigation
+
+        await setup()
+        seeded = await build_investigation()
+    else:
+        seeded = await build_graph()
+    await print_graph_state("BEFORE — both hypotheses stand, Conclusion K rests on E_qa")
+
+    # ---- Session 2: drop the contradicting fact --------------------------
+    banner("SESSION 2 — a new fact arrives")
+    print(f"  {C['y']}New fact:{C['x']} {NEW_FACT}\n")
+
+    pinned = seeded.refuted_target_id if demo else None
+    report = await revise(NEW_FACT, pinned_target_id=pinned)
+
+    if not report.revised:
+        print(f"  {C['y']}No contradiction was confirmed — graph unchanged.{C['x']}")
+        print(f"  {C['dim']}(Try `python main.py --demo` to force the cascade deterministically.){C['x']}")
+    else:
+        print(f"  {C['r']}✗ refuted:{C['x']} {len(report.refuted)} evidence node(s)")
+        print(f"  {C['r']}✗ invalidated:{C['x']} {len(report.invalidated)} conclusion(s)")
+        for hid, action in report.hypothesis_actions.items():
+            if action == "superseded":
+                mark = f"{C['r']}↓ superseded{C['x']}"
+            else:
+                mark = f"{C['g']}↑ promoted (new frontier){C['x']}"
+            print(f"     hypothesis {hid[:8]} → {mark}")
+        for fid in report.forgotten:
+            label = report.forgotten_labels.get(fid, fid)
+            print(f"  {C['dim']}🗑 forgotten (deleted from graph + vector):{C['x']} {label}")
+        if report.retained_provenance:
+            print(f"  {C['dim']}⚑ kept as red provenance:{C['x']} {len(report.retained_provenance)} node(s)")
+
+    await print_graph_state("AFTER — refutation cascaded, B ignites, orphan forgotten")
+
+    # ---- The scoreboard: FALSIFY vs plain RAG ----------------------------
+    banner("SCOREBOARD — FALSIFY (revised) vs plain RAG (stale)")
+    board = await scoreboard(
+        QUESTION_TEXT, seeded,
+        rag_snapshot=report.rag_snapshot if report.revised else None,
+    )
+    print(f"  {C['g']}{C['b']}FALSIFY :{C['x']} {board.falsify_answer}")
+    if board.falsify_support:
+        print(f"            {C['dim']}supported by: {', '.join(board.falsify_support)}{C['x']}")
+    rag_tag = f"{C['r']}[STALE — still cites a refuted fact]{C['x']}" if board.stale else ""
+    print(f"  {C['y']}{C['b']}RAG     :{C['x']} {board.rag_answer} {rag_tag}")
+    print(f"\n  {C['b']}→ AI revised, not forgot.{C['x']}")
+
+    # ---- Cross-session proof: reload belief state fresh ------------------
+    banner("CROSS-SESSION PROOF — reopen memory, beliefs stay revised")
+    summary = await get_belief_summary()
+    print(f"  Persisted belief state (re-read from graph): {summary}")
+    print(f"  {C['dim']}Truth-state lives on the graph nodes, so a brand-new process sees the")
+    print(f"  revised graph — the refuted branch never comes back.{C['x']}")
+
+    # ---- Visualization ---------------------------------------------------
+    out = await visualize_belief_graph("output/graph.html", title="FALSIFY — Company X investigation")
+    if out:
+        banner("VISUALIZATION")
+        print(f"  Interactive belief graph written to: {C['b']}{os.path.abspath(out)}{C['x']}")
+        print(f"  {C['dim']}Open it in a browser — red = refuted, grey = invalidated, green = alive.{C['x']}")
+
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="FALSIFY belief-revision demo")
+    parser.add_argument("--demo", action="store_true",
+                        help="pin the contradiction deterministically (LLM-independent cascade)")
+    parser.add_argument("--keep", action="store_true",
+                        help="do not prune existing memory before building")
+    args = parser.parse_args()
+
+    if not _has_llm_key() and not args.demo:
+        _print_no_key_help()
+        # Live mode needs an LLM key to judge the contradiction. Exit cleanly (0) with
+        # setup help rather than a stack trace. (`--demo` runs fully offline below.)
+        return 0
+
+    try:
+        return asyncio.run(run(demo=args.demo, keep=args.keep))
+    except KeyboardInterrupt:
+        print("\ninterrupted.")
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

render.yaml

@@ -0,0 +1,28 @@
+# Render blueprint for the FALSIFY backend (Deployment Plan B).
+# Render builds the repo's Dockerfile and injects $PORT (our CMD honors it).
+#
+# One-click: push this file, then in Render → "New +" → "Blueprint" → pick the repo.
+# Or create a Web Service manually with runtime=docker (see DEPLOYMENT.md §Render).
+services:
+  - type: web
+    name: falsify-backend
+    runtime: docker              # uses ./Dockerfile
+    plan: free                   # NOTE: free spins down after 15 min idle (30–60s cold start).
+                                 # Bump to "starter" ($7/mo) to keep it always-on for judging.
+    region: oregon
+    healthCheckPath: /api/health
+    autoDeploy: true
+    envVars:
+      # The Vercel URL that may call this backend. Set after the frontend deploys.
+      - key: FRONTEND_ORIGIN
+        sync: false
+      # Optional — only needed for Live mode / document upload (cognify) / recall.
+      - key: LLM_API_KEY
+        sync: false
+      - key: LLM_MODEL
+        value: gpt-4o-mini
+      # Optional — only if you demo the Cognee Cloud toggle from this backend.
+      - key: COGNEE_CLOUD_URL
+        sync: false
+      - key: COGNEE_CLOUD_API_KEY
+        sync: false

requirements.txt

@@ -0,0 +1,18 @@
+# FALSIFY — dependencies
+#
+# The only hard requirement is Cognee (the self-hosted AI-memory platform this
+# project is built on). Everything else is small tooling. Cognee itself pulls in
+# LanceDB / Ladybug / SQLite / litellm, so there is no separate DB to install.
+
+cognee>=0.1.0          # AI-memory platform: graph + vector + memify/forget APIs
+fastembed>=0.3.0       # local, CPU-only embeddings (no API key needed for the demo)
+python-dotenv>=1.0.0   # load .env configuration
+
+# ── web UI (Feature F): FastAPI backend + SSE stream, no WebSocket dep ──
+fastapi>=0.104.0       # async web framework serving the live UI + REST + SSE
+uvicorn[standard]>=0.24.0  # ASGI server
+python-multipart>=0.0.6    # multipart parsing for document upload (/api/upload)
+
+# ── dev / test (optional: pip install -r requirements.txt already includes these) ──
+pytest>=7.4.0
+pytest-asyncio>=0.21.0

server.py

@@ -0,0 +1,355 @@
+"""
+FALSIFY live web server — FastAPI backend for the animated belief-revision UI.
+
+This is the additive "web mode" for FALSIFY. The CLI (`python main.py`) is untouched;
+this server exposes the same three core operations — build / revise / scoreboard — over
+HTTP, plus a Server-Sent Events stream so a browser can *watch* belief revision happen:
+the refute flash, the cascade sweep, the forget-dissolve.
+
+Why SSE and not WebSockets: our event stream is one-directional (server -> browser), and
+SSE is plain streaming HTTP. That makes it work behind the Hugging Face Spaces single-port
+proxy AND across a Vercel(frontend)+Render(backend) split, neither of which hosts
+long-lived WebSockets on their free tiers. See IMPLEMENTATION_PLAN.md §6.1.
+
+Run locally:   uvicorn server:app --reload --port 8000   ->  http://localhost:8000
+On HF Spaces:  uvicorn server:app --host 0.0.0.0 --port 7860
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from fastapi import FastAPI, File, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+# Importing `falsify` first sets Cognee's env defaults (access-control off, etc.)
+# before any Cognee module is imported — same ordering contract as main.py.
+import falsify  # noqa: F401
+from falsify import events, graph_ops
+from falsify.falsify import (
+    Scoreboard,
+    build_diamond_graph,
+    build_graph,
+    revise,
+    scoreboard,
+    use_backend,
+)
+from falsify.models import TruthState
+from falsify.seed import NEW_FACT, NEW_FACT_2, QUESTION_TEXT
+from falsify.utils import _STATE_STYLE, _infer_type, get_belief_summary
+
+logger = logging.getLogger("falsify.server")
+
+app = FastAPI(title="FALSIFY Live", version="1.0")
+
+# Wide-open CORS: the demo may be served same-origin (HF monolith) or cross-origin
+# (Vercel frontend -> Render backend). FRONTEND_ORIGIN narrows it when set.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[os.environ.get("FRONTEND_ORIGIN", "*")],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ------------------------------------------------------------------ server state
+_seeded = None                    # the active SeededGraph (set on startup / reset)
+_scenario: str = "simple"         # "simple" | "diamond"
+_backend_mode: str = "opensource" # "opensource" | "cloud"
+_revise_lock = asyncio.Lock()     # serialize revise() — single-user demo safety
+
+
+# ------------------------------------------------------------------ request models
+class ChatRequest(BaseModel):
+    message: str
+    demo: bool = True
+
+
+class ScenarioRequest(BaseModel):
+    kind: str = "simple"          # "simple" | "diamond"
+
+
+class ModeRequest(BaseModel):
+    mode: str = "opensource"      # "opensource" | "cloud"
+    url: Optional[str] = None
+    api_key: Optional[str] = None
+
+
+# ------------------------------------------------------------------ JSON shaping
+async def _graph_json() -> Dict[str, Any]:
+    """Current graph as UI-ready JSON: nodes (with truth-state color) + edges.
+
+    Colors come straight from utils._STATE_STYLE so the web UI, the CLI console,
+    and the static HTML export all share one palette.
+    """
+    nodes, edges = await graph_ops.load_graph()
+    ids = [nid for nid, _p in nodes]
+    truth = await graph_ops.get_truth(ids)
+
+    out_nodes: List[Dict[str, Any]] = []
+    for nid, props in nodes:
+        align = truth.get(str(nid), [TruthState.ALIVE.value])
+        state = align[0] if align else TruthState.ALIVE.value
+        _tag, color = _STATE_STYLE.get(state, ("ALIVE", "#22c55e"))
+        out_nodes.append({
+            "id": str(nid),
+            "label": graph_ops.node_label(props),
+            "type": _infer_type(props),
+            "state": state,
+            "color": color,
+        })
+
+    out_edges = [
+        {"source": str(s), "target": str(d), "relation": r}
+        for (s, d, r, _p) in edges
+    ]
+    return {"nodes": out_nodes, "edges": out_edges,
+            "scenario": _scenario, "backend": _backend_mode}
+
+
+def _scoreboard_json(b: Scoreboard) -> Dict[str, Any]:
+    return {
+        "question": b.question,
+        "falsify_answer": b.falsify_answer,
+        "falsify_support": b.falsify_support,
+        "rag_answer": b.rag_answer,
+        "rag_citations": b.rag_citations,
+        "stale": b.stale,
+    }
+
+
+def _report_json(r) -> Dict[str, Any]:
+    return {
+        "new_fact": r.new_fact,
+        "refuted": r.refuted,
+        "invalidated": r.invalidated,
+        "forgotten": r.forgotten,
+        "forgotten_labels": r.forgotten_labels,
+        "hypothesis_actions": r.hypothesis_actions,
+        "retained_provenance": r.retained_provenance,
+        "new_evidence_id": r.new_evidence_id,
+        "epoch": r.epoch,
+        "revised": r.revised,
+    }
+
+
+# ------------------------------------------------------------------ SSE stream
+@app.get("/api/events")
+async def api_events():
+    """Server-Sent Events: one frame per belief mutation, fanned from the event bus."""
+    q = events.subscribe()
+
+    async def gen():
+        # Prime the stream so the client's onopen fires immediately behind proxies.
+        yield ": connected\n\n"
+        try:
+            while True:
+                try:
+                    ev = await asyncio.wait_for(q.get(), timeout=15)
+                    yield f"data: {json.dumps(ev)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ": keepalive\n\n"
+        finally:
+            events.unsubscribe(q)
+
+    return StreamingResponse(
+        gen(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",   # stop HF/Render proxies buffering the stream
+        },
+    )
+
+
+# ------------------------------------------------------------------ REST endpoints
+@app.get("/api/graph")
+async def api_graph():
+    return await _graph_json()
+
+
+@app.get("/api/scoreboard")
+async def api_scoreboard(q: str = QUESTION_TEXT):
+    board = await scoreboard(q, _seeded)
+    return _scoreboard_json(board)
+
+
+@app.post("/api/chat")
+async def api_chat(req: ChatRequest):
+    """A question (ends with '?') -> scoreboard; anything else -> a new fact to revise.
+
+    Graph mutations emit SSE events *during* revise(), so the browser animates the
+    cascade in real time while this call is still in flight.
+    """
+    msg = req.message.strip()
+    if not msg:
+        return {"type": "noop", "data": {}}
+
+    if msg.endswith("?"):
+        board = await scoreboard(msg, _seeded)
+        return {"type": "answer", "data": _scoreboard_json(board)}
+
+    async with _revise_lock:
+        pinned = _seeded.refuted_target_id if (req.demo and _seeded) else None
+        await events.emit_step("ingest", "New contradicting fact received")
+        report = await revise(msg, pinned_target_id=pinned)
+    return {"type": "revision", "data": _report_json(report)}
+
+
+@app.post("/api/scenario")
+async def api_scenario(req: ScenarioRequest):
+    """(Re)build the graph as the simple or diamond investigation."""
+    global _seeded, _scenario
+    if req.kind == "diamond":
+        _seeded, _scenario = await build_diamond_graph(), "diamond"
+    else:
+        _seeded, _scenario = await build_graph(), "simple"
+    await events.emit_graph_reset()
+    return await _graph_json()
+
+
+@app.post("/api/reset")
+async def api_reset():
+    """Rebuild the current scenario from scratch (fresh belief state)."""
+    return await api_scenario(ScenarioRequest(kind=_scenario))
+
+
+@app.post("/api/demo")
+async def api_demo():
+    """One-click headline demo on the simple graph: drop the back-dated-QA fact.
+
+    Rebuilds the simple investigation, then refutes E_qa (pinned, so it runs
+    keyless). Graph mutations stream over SSE while this call is in flight, so the
+    browser animates the cascade live; the returned report + scoreboard let the UI
+    finish with the promotion 'rise' and the FALSIFY-vs-RAG panel.
+    """
+    global _seeded, _scenario
+    async with _revise_lock:
+        _seeded, _scenario = await build_graph(), "simple"
+        await events.emit_graph_reset()
+        await asyncio.sleep(0.4)
+        await events.emit_step("ingest", "New fact: the March 2021 QA report was back-dated")
+        report = await revise(NEW_FACT, pinned_target_id=_seeded.refuted_target_id)
+    board = await scoreboard(
+        QUESTION_TEXT, _seeded,
+        rag_snapshot=report.rag_snapshot if report.revised else None,
+    )
+    return {"report": _report_json(report), "scoreboard": _scoreboard_json(board)}
+
+
+@app.post("/api/diamond")
+async def api_diamond():
+    """Two-phase diamond story: K2 survives phase 1, then collapses in phase 2.
+
+    Phase 1 refutes E_qa — the single-dependency conclusion K dies but the diamond
+    K2 survives on E_email. A pause lets the UI show K2 standing, then phase 2
+    refutes E_email and K2 finally collapses. Both targets are pinned so it runs
+    keyless and deterministically.
+    """
+    global _seeded, _scenario
+    async with _revise_lock:
+        _seeded, _scenario = await build_diamond_graph(), "diamond"
+        await events.emit_graph_reset()
+        await asyncio.sleep(0.5)
+        await events.emit_step("phase1", "Phase 1 — the March 2021 QA report was back-dated")
+        r1 = await revise(NEW_FACT, pinned_target_id=_seeded.ids["E_qa"])
+        await asyncio.sleep(1.6)  # hold on K2 surviving before the second blow
+        await events.emit_step("phase2", "Phase 2 — the January 2021 supplier email was fabricated")
+        r2 = await revise(NEW_FACT_2, pinned_target_id=_seeded.ids["E_email"])
+    board = await scoreboard(
+        QUESTION_TEXT, _seeded,
+        rag_snapshot=r2.rag_snapshot if r2.revised else None,
+    )
+    return {"phase1": _report_json(r1), "phase2": _report_json(r2),
+            "scoreboard": _scoreboard_json(board)}
+
+
+@app.post("/api/upload")
+async def api_upload(file: UploadFile = File(...)):
+    """Ingest an uploaded document into memory via cognee.add + cognify.
+
+    Turns the fixed demo into a real product: a judge can drop their own file and
+    watch it become graph. Requires an LLM key for cognify; degrades with a clear
+    error otherwise (the demo keeps working).
+    """
+    import cognee
+
+    raw = await file.read()
+    text = raw.decode("utf-8", "ignore").strip()
+    if not text:
+        return {"ok": False, "error": "empty or unreadable file"}
+    try:
+        await events.emit_step("upload", f"Ingesting {file.filename}…")
+        await cognee.add(text)
+        await cognee.cognify()
+        await events.emit_graph_reset()
+        return {"ok": True, "graph": await _graph_json()}
+    except Exception as exc:  # most likely: no LLM key for cognify
+        logger.warning("upload cognify failed: %s", exc)
+        return {"ok": False, "error": str(exc),
+                "hint": "Set LLM_API_KEY to enable document ingestion."}
+
+
+@app.get("/api/verify")
+async def api_verify():
+    """Re-read the persisted belief state from the on-disk graph store.
+
+    Truth-state (refuted / invalidated / superseded) is written ON the graph nodes
+    in Cognee's file-backed Kuzu store — not held in process memory — so re-reading
+    it here returns the *revised* beliefs, which is exactly what survives a full
+    process or container restart.
+
+    We deliberately do NOT evict the engine mid-request: in Ladybug subprocess mode
+    a worker process holds the DB file lock, so an in-process cold-reopen would
+    collide with that lock. The durable-proof claim rests on the truth_alignment
+    living in storage, and on the graph coming back revised after a real restart.
+    """
+    try:
+        summary = await get_belief_summary()
+        return {"persisted": True, "summary": summary}
+    except Exception as exc:
+        logger.error("verify read failed: %s", exc)
+        return {"persisted": False, "error": str(exc)}
+
+
+@app.post("/api/mode")
+async def api_mode(req: ModeRequest):
+    """Toggle the Cognee backend between self-hosted (open source) and Cognee Cloud."""
+    global _backend_mode
+    # Cloud creds can come from the request or the environment.
+    url = req.url or os.environ.get("COGNEE_CLOUD_URL")
+    api_key = req.api_key or os.environ.get("COGNEE_CLOUD_API_KEY")
+    _backend_mode = await use_backend(req.mode, url=url, api_key=api_key)
+    return {"backend": _backend_mode}
+
+
+@app.get("/api/health")
+async def api_health():
+    return {"ok": True, "scenario": _scenario, "backend": _backend_mode,
+            "subscribers": events.has_subscribers()}
+
+
+# ------------------------------------------------------------------ lifecycle
+@app.on_event("startup")
+async def _startup():
+    """Seed the simple investigation so the first page load shows a live graph."""
+    global _seeded
+    try:
+        _seeded = await build_graph()
+        logger.info("startup: seeded simple investigation")
+    except Exception as exc:  # don't let a seed hiccup take the server down
+        logger.error("startup seed failed: %s", exc)
+
+
+# Serve the built frontend LAST so /api/* routes take precedence. The directory is
+# created by the Docker build (frontend/dist -> ./static); guard so local dev without
+# a build still boots (API-only).
+if os.path.isdir("static"):
+    app.mount("/", StaticFiles(directory="static", html=True), name="static")