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 configuration — it tells Spaces to build the
Dockerfileand route traffic to port 7860. It renders as a small table on GitHub and is otherwise harmless there.
Running locally
# 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.