HyphaGraph

Hypergraph-based Evidence Knowledge System

HyphaGraph transforms document-based knowledge into a computable, auditable, and explainable knowledge graph. It is designed for domains where information is heterogeneous, sometimes contradictory, and supported by sources of unequal quality.

Knowledge should not be written. It should be derived from documented statements.

---

Who is it for?

• Researchers working with large bodies of scientific literature
• Physicians navigating contradictory clinical evidence
• Analysts in any field requiring auditable, evidence-based reasoning

No prior knowledge of graphs, databases, or formal logic is required.

---

Key Features

• Document-grounded relations — Knowledge is extracted from sources, never invented
• Hypergraph structure — Relations connect multiple entities with explicit roles
• Contradiction handling — Disagreements are preserved and surfaced, not hidden
• Computed syntheses — All conclusions are derived algorithmically, never authored
• Full traceability — Any conclusion reachable to its source in 2 clicks
• Explainability — Confidence breakdowns, contributing factors, and uncertainty always visible
• Constrained AI — LLMs assist with extraction and formatting only, never as authority

---

Local Development

Prerequisites

• Docker + Docker Compose
• Node.js >= 20 (for frontend dev outside Docker)
• Python >= 3.12 + uv (for backend dev outside Docker)

Start

git clone https://github.com/thibaut-d/hyphagraph.git
cd hyphagraph
cp .env.example .env

# Start the full local development stack
docker compose -f docker-compose.local.yml up -d
# or: make up

The API container applies migrations automatically on startup — no manual alembic upgrade head needed.

Access

Service	URL
Frontend	http://localhost
API docs	http://localhost/api/docs
Default admin	[email protected] / changeme123

Verify the proxy against a real API route after startup:

make dev-check

Common commands

make logs          # tail all service logs
make logs-api      # tail API logs only
make api-shell     # shell inside the API container
make db-shell      # psql inside the database container
make db-dump       # dump database to ./backups/
make down          # stop the stack
make clean         # stop + remove volumes (data loss)

Run make help for the full list.

---

Running Tests

Backend (pytest)

# Inside the running container
make api-tests

# Or directly with uv (outside Docker, from backend/)
cd backend
uv run pytest
uv run pytest -q --tb=short          # quiet output
uv run pytest tests/test_foo.py -x   # stop on first failure

Frontend (Vitest)

cd frontend
npm test             # interactive watch mode
npm test -- --run    # single run (CI mode)

End-to-end (Playwright)

See E2E Testing Guide.

---

Production Self-Hosting

HyphaGraph is distributed as versioned Docker images via GitHub Container Registry. Each instance you operate (one per site) pulls those images and manages its own database.

Step 1 — Create your environment file

cp .env.prod.template .env

Edit .env and replace every change-me-* placeholder:

Variable	What to set
POSTGRES_PASSWORD	Strong random password
SECRET_KEY	Long random string
JWT_SECRET_KEY	Long random string (different from above)
ADMIN_EMAIL / ADMIN_PASSWORD	Initial admin credentials
FRONTEND_URL	Your public URL, e.g. https://yoursite.com
HYPHAGRAPH_VERSION	Pin to a release tag, e.g. 1.2.0

Step 2 — Configure your domain

Edit deploy/caddy/Caddyfile.self-host — replace your-domain.com with your actual domain:

yoursite.com {
    handle /api/* {
        reverse_proxy api:8000
    }
    handle {
        reverse_proxy web:80
    }
}

Caddy obtains and renews TLS certificates from Let's Encrypt automatically. Ports 80 and 443 must be reachable from the internet.

Step 3 — Start

docker compose -f docker-compose.prod.yml up -d

The API container runs alembic upgrade head before starting — migrations are applied automatically on every start (idempotent).

Updating

# Pull new images and restart
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

To pin a specific version, set HYPHAGRAPH_VERSION=1.2.0 in .env.

Logs

docker compose -f docker-compose.prod.yml logs -f

---

Tech Stack

Layer	Technology
Backend	Python, FastAPI, SQLAlchemy (async)
Database	PostgreSQL
Frontend	React, TypeScript, Material UI
Auth	Custom JWT (OAuth2 password flow)
Testing	pytest, Vitest, Playwright
Infrastructure	Docker Compose, Caddy

---

Documentation

Document	Description
Project Overview	Vision, philosophy, and scientific motivation
Contributing	Development setup, standards, and workflow
Architecture	System architecture and invariants
Database Schema	Canonical data model
Computed Relations	Inference mathematical model
Code Guide	Coding conventions and patterns
Dev Workflow	Development workflow and commit discipline
Remote Dev Access	Connect to the remote dev server with VS Code, Termius, or plain SSH
SSH Config Sync	Keep the same OpenSSH aliases across machines safely
E2E Testing	Playwright E2E testing guide
Hypergraph RAG Papers	Curated survey of hypergraph RAG, evidence-centric, and claim-centric systems relevant to HyphaGraph
UX Design Brief	UX principles and design constraints
AI Agent Guide	Canonical AI-agent entrypoint and workflow
Roadmap	Project status and upcoming work

---

License

See LICENSE.