aurora

<!-- mcp-name: io.github.FantasyLab-ai/aurora -->
<div align="center">
  <img src="docs/screenshots/aurora-mascot-wizard.png" alt="Aurora" width="200"/>

  # Aurora

  ### Glass-box quantitative intelligence. Local. Open. Cited.

  Aurora is the **verification cortex** for serious quantitative work — for humans analyzing hard data, and for AI systems that can't afford to hallucinate.

  > **Cloud LLMs guess. Aurora computes.**

  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
  [![Status](https://img.shields.io/badge/status-v2.0%20active-purple.svg)](#)
  [![Tests](https://img.shields.io/badge/tests-699%20passing-brightgreen.svg)](#)
  [![Patreon](https://img.shields.io/badge/support-Patreon-f96854.svg)](https://www.patreon.com/c/FantasyLab3DStudio)

  **[⬇️ Download the desktop app](#%EF%B8%8F-download-the-desktop-app)** · [Run from source](#-quickstart-60-seconds) · [Aurora Sentinel demos](#-aurora-sentinel--decision-contracts-in-the-room) · [See it in action](#see-aurora-in-action) · [Aurora Copilot](#-aurora-copilot--for-humans) · [Aurora Cortex (MCP + SDK)](#%EF%B8%8F-aurora-cortex--for-ai-systems) · [Roadmap](ROADMAP.md) · [FantasyLab.ai](https://fantasylab.ai)
</div>

---

## ⬇️ Download the desktop app

**The easiest way to run Aurora — no Python, no terminal, no setup.** Download
the installer for your OS, double-click, and Aurora opens as a native app with
the analysis backend bundled inside it.

### → [**Download the latest release**](https://github.com/FantasyLab-ai/aurora/releases/latest)

Pick the file that matches your OS (filenames carry the version, e.g. `0.2.0`):

| OS | File to download | Install |
|---|---|---|
| **Windows 10/11** | `Aurora_x.x.x_x64-setup.exe` **(recommended)** | Run the setup wizard. |
| Windows 10/11 | `Aurora_x.x.x_x64_en-US.msi` | Alternative MSI installer (same app). |
| **macOS** (Apple Silicon · M1/M2/M3/M4) | `Aurora_x.x.x_aarch64.dmg` | Open the `.dmg`, drag Aurora to Applications. |
| **Linux** (Debian / Ubuntu / Mint) | `Aurora_x.x.x_amd64.deb` | `sudo apt install ./Aurora_x.x.x_amd64.deb` |
| **Linux** (Fedora / RHEL / openSUSE) | `Aurora-x.x.x-1.x86_64.rpm` | `sudo dnf install ./Aurora-x.x.x-1.x86_64.rpm` |

> `Aurora_aarch64.app.tar.gz` is an auto-updater artifact, **not** a download —
> use the `.dmg` on macOS. There is currently no Intel-Mac (`x86_64`) or Linux
> AppImage build; Intel-Mac users can [run from source](#-quickstart-60-seconds).

On first launch Aurora bootstraps a small knowledge-bank seed, then runs **fully
offline** — no API keys, no cloud, no telemetry. Drop a CSV on the window and
watch it analyze. Aurora is **local-first: your data never leaves your machine**
unless you explicitly share a single finding — see [PRIVACY.md](PRIVACY.md).

> **Heads up on the "Unknown Publisher" warning.** Current releases are not yet
> code-signed, so Windows SmartScreen may show *"Windows protected your PC"* and
> macOS Gatekeeper may say *"unidentified developer."* This is expected for a
> young open-source project. On Windows: **More info → Run anyway**. On macOS:
> **right-click the app → Open**. Code-signing is on the roadmap.

### Desktop app — tips & known quirks

A few things that are **expected behavior**, not bugs:

- **First launch shows a welcome screen, not a run.** That's intentional — a
  fresh start is clean. Drop a CSV (or click a demo card) to begin; your past
  runs are always available under **Data → Bundles**.
- **Give the backend a few seconds on first launch.** Aurora starts a local
  analysis server (`127.0.0.1:8001`) the first time you open it; the status dot
  reads "connecting…" for ~5–10 s before it goes live. If it lingers, the app
  is still warming up — it is not frozen.
- **Big datasets take longer, and results land all at once.** A large file can
  spend a while in *"analyzing…"*. When it finishes you'll see *"analysis
  complete"* and the views populate. If the Overview looks momentarily empty
  right after completion, give it a few seconds or click another tab and back —
  the assembled state is still being fetched, and it will fill in.
- **Re-running the same file is instant.** Identical data + settings reuse a
  cached analysis; the banner reads *"instant · cached."* That's a speed win,
  not a skipped run.
- **Knowledge Bank starts small on a fresh install.** The bundled app ships with
  a seed bank that grows over time; the large multi-thousand-entry bank you may
  see in screenshots is built up on a machine that's been ingesting data for a
  while. Citations still work against whatever is local.

Want to build it yourself or run from source? Keep reading.

---

## ⚡ Quickstart (60 seconds)

```bash
# 1. Clone + create a virtualenv
git clone https://github.com/FantasyLab-ai/aurora.git
cd aurora
python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

# 2. Install
pip install -r requirements.txt

# 3. Run the Studio
python studio_api.py
```

Open <http://127.0.0.1:8000>. Click **▶ Try a demo** for an instant smoke test, or drop your own CSV / Parquet / JSON / XLSX.

> First run will download a small knowledge-bank seed (~50 MB). After that, Aurora runs **fully offline** — no API keys, no cloud, no telemetry.

**Optional extras** (only if you need them):

```bash
pip install cryptography             # Ed25519 bundle signing
pip install mcp                      # MCP server for LLM agents (Claude Desktop, Cursor, etc.)
pip install -r requirements-dev.txt  # contributor / test extras
```

For the optional Vite + TypeScript frontend build (developers only), see [§ Optional frontend build](#optional-enhanced-frontend-build).

---

## 🖥️ The desktop app

A native, installable app — frameless window, sidebar navigation,
drag-and-drop any file onto it. Built with Tauri 2, with Aurora's **full
analysis backend bundled inside the installer**, so it runs with zero
setup: no Python, no venv, no terminal.

> **Most people should just [download it](#%EF%B8%8F-download-the-desktop-app).**
> The rest of this section is for developers who want to build it from
> source or hack on the UI.

### What it does

| Surface | Behavior |
|---|---|
| Frameless window | Rounded card on transparent OS background; `aurora ◆` titlebar with min/max/close |
| Sidebar (left) | Workspace · Data · Full Studio sections + live "aurora: online / offline" status dot |
| Tab strip (top) | Overview / Findings / Data with one shared sliding underline |
| **Drag & drop ANY file** | CSV, TSV, JSON, JSONL, Parquet, XLSX — drop anywhere on the window, or click to browse |
| Overview | Stat cards (Findings · Methods · Anomalies · Regimes) + **Aurora's narrative** in plain English |
| Findings | Severity-filtered card grid; **click a card for the full evidence panel** |
| Methods | Per-run method tally with share-bars |
| Datasets | Bundled fixtures + demo datasets — **click any card to run it** |
| Bundles | Past runs — every signed `.aurora.json` on disk, status-coded |
| Aurora Studio sidebar | Full legacy UI in an iframe — every feature still reachable |

### Build it from source / develop

The desktop app lives in [`desktop/`](desktop/). To build the installer
yourself (PyInstaller backend + Tauri shell) or run the UI in hot-reload
dev mode, see **[`desktop/README.md`](desktop/README.md)** — it covers the
prerequisites (Node, Rust), the one-command launcher (`launch.ps1`), the
installer build (`build_installer.ps1`), and the Windows Smart App Control
caveat. A `git tag vX.Y.Z` push triggers the cross-platform release CI.

---

## 🚨 Aurora Sentinel — Decision Contracts in the room

Aurora ships a complete **demo rig** under [`demos/`](demos/) that turns a Decision Contract trip into something tangible — a Discord ping, a Slack alert, an OBS overlay card, a smart-plug flipping in your room. Five "I gave my local AI X and watch what it caught" videos, all built on the same scaffolding.

| # | Demo | Hero shot | What it shows |
|---|---|---|---|
| 1 | **Aurora Alarm** | A physical light flips when the data breaks | The closed loop is real — software → cited reason → real-world consequence |
| 2 | **Community Sentinel** | A Discord embed lands with method + row + |z|σ | Drop-in for any Discord community; cited anomalies, no cloud |
| 3 | **The Save** | A Slack ping arrives at the regime shift | The "human watching dashboards would have slept through this" demo |
| 4 | **Verification Cortex** | An agent calls Aurora's MCP and acts on a *verified* number | Sells the agent-builder use case; no more confidently-wrong z-scores |
| 5 | **Rediscover the Law** | Aurora derives `y = ½·a·t²` from a falling-ball video | The flagship hook — a free local AI rediscovers gravity, cited to SINDy |

**Quickstart for the demos** (after the install above):

```bash
# Generate the synthetic datasets one time:
python -m demos.datasets.falling_ball.generate
python -m demos.datasets.server_metrics.generate

# Install the demo contracts into Aurora's contracts dir:
cp demos/contracts/*.json ~/.aurora/decision_contracts/        # macOS / Linux
copy demos\contracts\*.json $env:USERPROFILE\.aurora\decision_contracts\   # Windows

# Configure your webhooks once (copy the template + paste your URLs):
cp demos/.env.demos.example demos/.env.demos                   # macOS / Linux
copy demos\.env.demos.example demos\.env.demos                 # Windows

# Run the relay (it reads .env.demos for Discord/Slack URLs):
python -m demos.relay.app
```

Full step-by-step recording walkthrough with OBS setup, contract installation, and a per-demo runbook lives at **[`demos/README.md`](demos/README.md)**.

---

## See Aurora in action

A real run on an environmental air-quality dataset — captured straight from a Studio session.

<div align="center">
  <img src="docs/screenshots/07-summary-run.png" alt="Aurora run summary banner — domain selec