File size: 4,315 Bytes
3396318 75ce203 19c6bad 658d200 19c6bad 3396318 75ce203 658d200 75ce203 658d200 75ce203 658d200 75ce203 3396318 75ce203 3396318 75ce203 19c6bad 75ce203 3396318 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | ---
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).
|