README.md

---
title: Aurelius
emoji: 🧭
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# Aurelius

Aurelius is a general-purpose **graph intelligence engine**: pick two things
in any connected dataset and it walks the real links between them, ranking
every step by meaning — on-device embeddings and graph search, with an
**optional** Gemini layer that narrates the results in plain English —
while the live search animates as an interactive 2D graph. The AI layer is
purely additive: with no key the app runs fully, and every AI panel falls
back to a small notice with the standard result still shown.

It started as a Wikipedia path-finder. Today every dataset is a plug-in
**adapter** behind one protocol, and each domain leads with a purpose-built
research surface — a **company profile** for finance, a **citation
explorer** for papers — with the graph as a secondary explorer:

| Source | Mode | Graph |
|---|---|---|
| Wikipedia | live | article links (fetched on demand) |
| Research papers (OpenAlex) | live | citations — explore any paper's references & citing works (by title, DOI, arXiv id or uploaded PDF) |
| **Finance** (Yahoo Finance) | ingested | companies, ETFs, sectors, executives, countries & macro indicators with typed edges: supply chains, ownership, competition, holdings, and *computed* return correlations |
| **News** (News Intelligence) | ingested | entities + articles from live coverage, co-mention relationships, evolving stories |
| Biomedical (Hetionet) | ingested | genes–compounds–diseases |

Beyond pathfinding, `discover()` performs Swanson-style hidden-connection
mining (candidates with strong indirect support but **no direct link**),
`relate()` scores connection strength with the actual intermediaries, and
every path hop carries human-readable evidence ("supplies", "co-moves
(corr 0.72)", "led by").

The **News Intelligence subsystem** (`news_intel/`) is standalone and
domain-agnostic: connector-based fetching (NewsAPI / GDELT, extensible to
RSS/Reddit/SEC/...), deduplicated raw-article storage, entity extraction,
embeddings, story grouping, and ranked search — exposed at `/api/news/*`
for any domain module to consume.

The frontend is a single static page (`index.html` / `styles.css` /
`app.js` / `graph2d.js`) deployed on Vercel. The backend is this FastAPI
service: an in-process `sentence-transformers` model plus the
source-agnostic navigator, streamed to the browser over a WebSocket.

> The YAML block at the top of this file is
> [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-config-reference)
> configuration — it tells Spaces to build the `Dockerfile` and route traffic
> to port 7860. It renders as a small table on GitHub and is otherwise
> harmless there.

## Running locally

```bash
# Backend (from the repo root)
uvicorn main:app --reload --port 8000

# Frontend — serve the static page next to it:
python -m http.server 8081
# then open http://localhost:8081 (app.js auto-detects localhost backends)

# Populate the ingested sources (finance takes ~3 min, news ~2 min):
python -m ingest.cli finance
python -m ingest.cli news
python -m ingest.cli status
```

## Deploying the backend

This backend needs an **always-on container host** (it holds the model in
memory and serves a persistent WebSocket) — *not* a serverless/edge platform.
The included `Dockerfile` runs as-is on Hugging Face Spaces (Docker SDK),
Fly.io, Railway, or Google Cloud Run.

Useful environment variables:

| Variable | Purpose |
|---|---|
| `AURELIUS_AUTOINGEST=finance,news` | self-populate ingested sources at boot (recommended on Spaces — free-tier storage is ephemeral) |
| `NEWS_REFRESH_MINUTES=180` | scheduled News Intelligence refresh (0 = off) |
| `NEWSAPI_KEY` | richer news fetching via NewsAPI (falls back to keyless GDELT) |
| `GEMINI_API_KEY` | **optional** — enables the AI narration layer (Google AI Studio key). Backend-only secret; never sent to the browser. Unset = app runs fully without AI. |
| `GEMINI_MODEL` | Gemini model id (default `gemini-3.1-flash`) |
| `GEMINI_RPM` | soft calls/min budget so we never trip Google's rate limit (default 12) |
| `ALLOWED_ORIGINS` | CORS/WS origin allow-list for the deployed frontend |

## License

MIT — see [LICENSE](LICENSE).