ARES

Autonomous Research & Evidence System

A research workspace for exploring questions, working with documents, and tracing answers back to their sources.

Getting started · Model providers · Architecture · Development · Security

Overview

ARES brings source discovery, document retrieval, and cited answer generation into one interface. A FastAPI control plane coordinates persistent research runs and background workers; the React workspace displays answers, source evidence, and execution activity.

Use the keyless demo to explore the interface, or configure live research with Google Gemini or a local Qwen model through Ollama.

Release status: ARES is under active development. The current audit identified unresolved security, dependency, packaging, and production startup issues. Local evaluation is the recommended starting point; this checkout is not yet qualified for public hosting. See Security and release status.

What you can do

• Research a question: discover web and academic sources through SearXNG, OpenAlex, Crossref, and arXiv adapters.
• Work with documents: upload files, extract supported content, and retrieve passages for research. Scanned PDFs and richer media require optional parsing capabilities.
• Choose a writer: generate answers with Gemini or a configured local Ollama model.
• Inspect the evidence: follow citations, review source passages, and inspect research activity and visualizations.
• Resume research: persist conversations, run events, assets, and research memory.
• Connect other agents: use the project's Model Context Protocol integration to access research capabilities.

Capabilities depend on the execution mode, enabled settings, provisioned models, and external service availability. Demo results use fixtures rather than live research.

Getting started

Requirements

• Python 3.12 or newer, within the range declared in backend/pyproject.toml.
• uv for backend dependencies.
• Node.js 20.19 or newer, compatible with the locked frontend toolchain.
• pnpm 9.12.3, declared in package.json; use Corepack where available.
• Docker Compose for local PostgreSQL and SearXNG when needed. The SQLite demo does not require Docker.

1. Install dependencies

git clone https://github.com/aman-bhaskar-codes/ARES.git
cd ARES
cp .env.example .env

uv sync --project backend --extra dev --frozen
corepack enable
pnpm install --frozen-lockfile

2. Initialize the demo database

The supplied .env.example selects ARES_MODE=demo and a local SQLite database. Keep these defaults for the first run. No cloud credentials are required.

make migrate

3. Start the application

Run each command in a separate terminal from the repository root:

# Terminal 1 — API
make api

# Terminal 2 — background worker
make worker

# Terminal 3 — frontend
make web

Open http://127.0.0.1:5173. API documentation is available at http://127.0.0.1:8000/docs while the backend is running. Use the URL printed by Vite if the default frontend port is occupied.

Model providers

Live research uses ARES_MODE=local_live. Restart the API and worker after changing .env.

Qwen through Ollama

Install Ollama, start its service, and download the model:

ollama pull qwen3:4b

Set these values in .env:

ARES_MODE=local_live
LOCAL_LLM_ENABLED=true
LOCAL_LLM_URL=http://127.0.0.1:11434
LOCAL_LLM_MODEL=qwen3:4b

Local inference keeps model generation on your machine. Live web and academic discovery still contact external services; enabling cloud providers or cloud processing can send data to those providers.

Google Gemini

Create a key in Google AI Studio and set ARES_MODE=local_live and GEMINI_API_KEY in .env. Set GEMINI_MODEL to a model available to your account; the template includes the project's configured model name.

Also set all three quota controls to values appropriate for your account:

Do not copy another account's quota assumptions. Strict-free mode requires explicit quotas; it does not determine your provider's pricing or guarantee that usage is free. Keep credentials out of commits and shared screenshots.

Search and PostgreSQL

Start the local infrastructure when using live web search or PostgreSQL:

make infra

This starts PostgreSQL and SearXNG, not the API, worker, or frontend. To use the supplied PostgreSQL container, change .env before applying migrations:

DATABASE_URL=postgresql+psycopg://ares:[email protected]:5432/ares
SEARXNG_URL=http://127.0.0.1:8080

make migrate

These credentials are for local development only. Changing the database URL selects a different database; it does not transfer existing SQLite conversations or files.

Architecture

flowchart LR
    UI[React workspace] -->|REST and SSE| API[FastAPI control plane]
    API --> DB[(Run and document storage)]
    DB <--> Worker[Background research worker]
    Worker --> Discovery[Web and academic discovery]
    Discovery --> Retrieval[Extraction and retrieval]
    Retrieval --> Writer[Gemini or Ollama]
    Writer --> Evidence[Claim checks and cited answer]
    Evidence --> DB
    Worker <--> Blobs[Asset storage]

Research runs move through discovery, extraction, retrieval, synthesis, and claim checking. Events are persisted for replay and streamed to the interface. PostgreSQL supports vector retrieval when the required embedding capabilities are configured; local lexical and demo paths provide simpler alternatives.

Claim checks are evidence-assessment signals, not guarantees of truth. Semantic checking is optional and disabled in the example configuration. Citations and retrieved excerpts should be inspected, particularly when a run reports insufficient evidence or falls back after a provider failure.

For implementation details, see Architecture, Evaluation methodology, and Recorded hardening results.

Configuration

.env.example is the starting point for local configuration. Backend settings define validation rules and defaults; values in your .env override those defaults.

OCR, rich parsing, embeddings, audio, and video have additional dependencies and provisioning requirements. Enable them only after reviewing the corresponding settings and worker requirements.

Development

Run focused checks from the repository root:

make lint
make typecheck
make test
make security-scan

pnpm --filter @ares/web typecheck
pnpm --filter @ares/web test
pnpm --filter @ares/web build

make check aggregates additional checks, migrations, schema generation, and release verification. Some targets generate or update files. The current release verifier has known gaps; a successful aggregate command alone is not production qualification.

The 23 October 2026 audit of commit 5212be3 recorded 290 passing backend tests, 8 skipped backend tests, and 28 passing frontend tests, plus a successful frontend build and static checks. These are a dated baseline, not a live CI badge. Deterministic offline evaluations do not establish real-provider answer quality. Fresh Gemini/Qwen browser E2E and production deployment qualification remain required.

Security and release status

ARES includes controls for authentication, request limits, outbound fetching, upload processing, and database tenant isolation. Their effectiveness depends on deployment configuration and enabled capabilities.

The release audit identified issues that must be resolved before public hosting or distributing a release archive:

• Code execution: the Code tool runs generated Python without a dedicated security sandbox. Do not enable it in an untrusted environment.
• Archive contents: the release archive builder can include ignored private files. Review packaging rules and the full archive inventory before distributing an archive.
• Production startup: the documented database bootstrap passes a SQLAlchemy URL to psql; the connection scheme needs correction and a real startup test.
• Release metadata: version and schema metadata are inconsistent, and verification can report success without mandatory E2E evidence.
• Dependencies: the audited backend lockfile contains affected certifi, OpenTelemetry API, and Pillow versions. Upgrade and recheck security advisories before release.

Keep development services on loopback. Public hosting requires configured authentication, reviewed secrets and network exposure, tested migrations, and fresh end-to-end verification. See SECURITY.md for reporting guidance.

Contributing and license

Bug reports and focused contributions are welcome. Include reproduction steps, relevant configuration with secrets removed, and expected versus actual behavior.

Read CONTRIBUTING.md before opening a pull request and CHANGELOG.md for recorded changes. ARES is licensed under the Apache License 2.0.