Polaris

Autonomous, end-to-end AI research: from literature to a reviewed paper.
Powered by a long-running agent core that plans, executes, and self-verifies its own work, turning every task into a resumable, auditable, human-gated run.

English · 简体中文

Polaris runs the entire research lifecycle as a single web application: literature survey, idea generation, idea review, experiment building on real GPU servers, LaTeX paper writing, and paper review. It is built for a research lab, with multi-user access, RBAC, and invite-code registration, and it treats every long task as a Voyage: a persisted, resumable, human-gated agent run that can span hours or days without losing state.

[!NOTE] Polaris is not a chatbot wrapper. The heavy lifting (crawling, parsing, deduplication, metric parsing, citation matching) is deterministic code. LLMs are reserved for the judgement calls: scoring, synthesis, drafting, and review. This split keeps runs cheap, reproducible, and auditable.

Demo

A 2-minute tour of the platform: the six-stage pipeline, the Voyage agent core, a real experiment run, and PolarisBuddy.

https://github.com/user-attachments/assets/388972c1-7ffa-45f2-94c4-07f388379ba2

Try it live

A guest account on a running instance, for looking around: sign in at http://101.37.174.109:8080 with the username guest and the password zjuguest123.

The account is for demonstration only: it is read-only and cannot call any model. It reaches every screen, the admin views included, but nothing it does changes state — creating, editing, deleting and uploading are all refused, and no LLM call will run, whether from chat, compilation or the assistant. Lab members' details and the registration codes are hidden from it as well. It is there to show what the platform looks like, not to do work on it.

The research pipeline

Polaris models research as six stages. Each stage produces durable artifacts that the next stage consumes, and every hand-off can pause at a human approval gate.

flowchart LR
    L["Literature<br/>Research Wiki"]
    I["Idea<br/>Idea Forge"]
    R["Idea Review<br/>Elo debate"]
    X["Experiment<br/>GPU / SSH"]
    W["Paper Writing<br/>LaTeX"]
    V["Paper Review<br/>Citation check"]
    S(["Submission"])

    L --> I --> R
    R -->|promotion gate| X
    X --> W --> V
    V -->|submission gate| S

    classDef stage fill:#eaf1ff,stroke:#2f6bff,stroke-width:1px,color:#10233f;
    classDef gate fill:#fff3e0,stroke:#f59e0b,stroke-width:1px,color:#5b3b00;
    class L,I,R,X,W,V stage;
    class S gate;

The Voyage agent core

Research tasks are long-running by nature: a cold-start literature backfill takes hours, an experiment runs for days. Polaris's central abstraction is that every complex task is a Voyage: a resumable, auditable run driven by a persisted three-part loop.

[!IMPORTANT] A Voyage is backed by a persistent state machine (planning -> executing -> verifying -> ...). If a worker crashes mid-run, the Voyage resumes from its last checkpoint after a health check. Budgets are attached to the run and auto-pause it when exceeded; every plan, action, and verdict is retained and replayable in the UI.

Not every task needs the full cognitive loop. A shared Runtime shell (state machine, checkpointing, gates, budget, cancellation, event streaming) serves all task kinds, while the Brain (the full plan-execute-verify loop) activates only for open-ended kinds such as experiments. Predictable pipelines (wiki compile, idea review, paper drafting) run on fixed templates instead of being over-orchestrated.

Key features

• Research Wiki, "compile, don't retrieve." LLMs read papers and compile a persistent, cross-linked knowledge base up front, instead of doing on-demand RAG at query time. One wiki per paper, shared platform-wide. Research digests, and Obsidian vault sync with [[wikilinks]] and frontmatter.
• One content pool, four collections. Every paper is stored exactly once; direction libraries, topic shelves, personal libraries, and the daily feed are membership layers over that pool. Libraries are decoupled from topics (many-to-many), own their own inclusion config, and come with governance: curators, monthly budgets, duplicate merge, user-created libraries under admin approval, and a recycle bin that stays out of search.
• Daily arXiv feed. A lab-wide feed of each day's new papers, with likes and one-click collection into any library you can write to. It is also the single arXiv entry point: libraries sync from the pool instead of querying arXiv themselves, on an admin-configurable schedule.
• Idea Forge. Signal-driven gap analysis, four-axis scoring, semantic dedup, and a deep Research-Proposal builder with novelty double-checking against the library and external sources.
• Multi-agent and human review. Persona reviewer agents debate to an Elo ranking; humans join live and are injected into the agent context, not bolted on afterward.
• Experiment Lab over SSH. Agents write and run code on real GPU servers, iterate on metrics, and collect logs and figures, under gated remote writes, command allow/deny lists, full audit, and triple budget caps (total, per-run, concurrency). A run keeps a file-based memory across steps, repairs itself under a time budget, and pauses to ask you a question rather than dying; its console shows a task map and a terminal you can talk to while it runs.
• Paper Writer. Online multi-file LaTeX with collaborative CRDT editing and server-side tectonic compilation; agent drafting bound to real metrics and real citations, plus one-click reference refresh wired into the main TeX file.
• Paper Review with citation verification. Existence and support are checked per citation against the library, Semantic Scholar, and OpenAlex; numbers are fact-checked against the experiment record.
• PolarisBuddy, an in-app assistant. A global companion that rides along on every page: a Claude Code-style multi-turn tool loop (streamed over SSE, with tool cards and inline figures) over the same read-only tool layer, in chat, plan (research-only, propose before acting), and goal (loop toward an objective) modes. It runs the same Navigator / Helm / Sextant split as a Voyage, so its steps are verified rather than merely produced, and it can hand work to subagents. Its greeting is stitched from real SQL counts rather than the model, it searches every library you can see, and it carries page context and persistent per-user memory. It is off unless the account may call a model.
• Skills, in two layers. Agent behavior is packaged as data, not code. Voyage skills are versionable, composable guidance, rubric, persona, and workflow packs injected at named points into agent prompts, enabled globally, with a publish-approve-install-rate marketplace; each Voyage snapshots the skills it used for reproducibility. Agent skills take the SKILL.md shape with three-level progressive disclosure — a one-line description in the catalog, the body fetched by skill_load as a tool result, attachments read on demand — so the model decides what to load and the prompt prefix stays cacheable.
• MCP tool layer. A single registry of read-only tools (literature, knowledge, project state, manuscripts, external search) is exposed both internally to the agent loop and externally as an MCP server (Streamable HTTP and stdio) for Claude Code, Codex, and Cursor, with a self-check and try-it playground. Project-isolated and strictly read-only.
• Real-time everywhere. SSE for agent streaming and Voyage progress; WebSocket for review discussions, approval notifications, experiment log tracking, and collaborative editing.
• Multi-user and RBAC. JWT auth (fastapi-users), invite-code registration, role-based access, and per-call token/cost accounting attributed to user, project, and voyage. Library and paper views are counted into a 7-day heat list, so the lab can see what people are actually reading.
• LLM abstraction and model routing. All model calls go through one layer; a DB-backed routing table maps each research stage to a provider, a model, and a reasoning-effort level (cheap models for scoring, strong models for debate and drafting). Admins set the global routes and users may override their own. The built-in fake provider is structurally disabled in production — setting the flag by mistake cannot turn it on.

Tech stack

Desktop client

Polaris ships as a desktop app for macOS, Windows, and Linux. Download the installer from Releases — .dmg / .zip (macOS, universal), .exe / portable .zip (Windows), .AppImage / .deb (Linux), built by CI on every v* tag. The app checks for updates and applies them without a restart where it can.

The builds are neither signed nor notarized, so each platform needs to be told once that the app is safe to run: on macOS xattr -dr com.apple.quarantine /Applications/Polaris.app (or right-click → Open); on Windows choose More info → Run anyway past SmartScreen; on Linux the AppImage needs libnss3 libgtk-3-0 libasound2, and --no-sandbox under Ubuntu 24.04+ AppArmor.

Since v0.4.0 the app is an offline, single-machine build: it ships its own Python backend and bootstraps it on first launch (SQLite, no Docker, no login, no server address). The first launch downloads a Python toolchain and dependencies, which can take a few minutes; later launches start immediately. If the local engine cannot start, the app falls back to asking for a Polaris server address, which is also how you connect to a shared multi-user server.

[!NOTE] v0.3.x and earlier are remote-only shells: they always ask for a server address on first run. They cannot update themselves into the local-engine build — download a v0.4.0+ installer from Releases and install it over the old one.

To build it yourself:

make desktop-deps           # install the shell's dependencies (once)
make desktop-dev            # build the frontend and run the shell (app:// protocol)
make desktop-dist           # package an unsigned installer for the current platform

See docs/desktop.md for the process model, the IPC contract, and packaging notes.

Quick start

[!TIP] Docker Compose is the recommended way to run Polaris, in development and in production. It needs only Docker and Docker Compose installed, with no local Python, Node, or database. See docs/deployment.md for production deployment.

cp .env.example .env        # set provider keys and secrets
make dev                    # full stack via docker compose, hot reload

• Frontend: http://localhost:5173
• Backend API docs: http://localhost:8000/docs

Local development without Docker (falls back to SQLite):

make backend-dev            # venv + uvicorn on :8000
make frontend-dev           # npm install + vite dev on :5173

Common tasks:

make migrate                # alembic upgrade head
make test                   # backend pytest + frontend build
make lint                   # ruff check + tsc --noEmit

Docker deployment

Deploy from pre-built images on Docker Hub (tricktreat/polaris-{api,worker,frontend}, published by CI on every v* tag) — no local build needed:

cp .env.example .env        # set POLARIS_ENV=prod, POLARIS_IMAGE_TAG, secrets, and an LLM key
docker compose --env-file .env -f docker/docker-compose.yml pull
docker compose --env-file .env -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml exec api alembic upgrade head   # required on first run

The frontend is served at http://<host>:8080. The worker container is required (it runs all long tasks), and the first-run migration is mandatory (Postgres tables are not auto-created). Pass --env-file .env so Compose reads POLARIS_IMAGE_TAG (default latest) / POLARIS_IMAGE_PREFIX (default tricktreat) from the repo-root .env.

For building locally instead, bind mounts, backups, and restricted networks, see docs/deployment.md.

Documentation

Full documentation lives in docs/:

• Getting started: install, configure, and run Polaris
• Architecture: system design and the Voyage agent core
• Concepts: the research pipeline, Voyage, skills, and MCP tools
• Deployment: production deployment with Docker Compose
• Desktop: the Electron shell — process model, IPC contract, and packaging
• Configuration: environment variables and settings
• Development: local workflow and conventions

Repository layout

src/
  backend/       FastAPI app (package: app) and ARQ worker (package: worker)
    app/
      api/         thin routers
      services/    business logic (ingest, wiki, ideas, review, experiments, manuscripts, ...)
      models/      SQLAlchemy models
      agents/voyage/  the Voyage engine (navigator, helm, sextant, tool loop, per-domain actions)
      core/        config, db, queue (ARQ), events (SSE), llm/ abstraction
      tools/, mcp/ read-only tool registry and the external MCP server
  frontend/      React + Vite (src/features/ has one folder per product area)
  desktop/       Electron shell that wraps the web bundle (macOS / Windows / Linux)
docker/          Dockerfiles and compose (base, dev override, prod overlay)
docs/            English project documentation

Design principles

• Strict layering. Thin routers call services; services hold the business logic and never import the web framework; models sit underneath.
• Deterministic vs. judgemental split. Deterministic work (crawling, parsing, dedup) is plain code or worker tasks; only judgement calls reach an LLM.
• One LLM boundary. All model calls go through a single abstraction layer, and model choice comes from a database routing table rather than being hard-coded.

See docs/architecture.md for the full design.

Contributing

See CONTRIBUTING.md. In short: one feature is one branch is one pull request, branched from the latest origin/main, with English conventional-commit messages, and main stays a read-only fast-forward mirror of origin/main.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.