Autonomous Research & Evidence System
A research workspace for exploring questions, working with documents, and tracing answers back to their sources.
Watch the demo · Getting started · Model providers · Architecture · Development · Security
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 an actively developed research application. Start with the local demo or a configured live provider. The release hardening pass disables generated-code execution and strengthens packaging and database provisioning. Local checks do not certify a public deployment; see Security and release status.
- 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: switch between Gemini and local Qwen in the model menu. Ask for a brief answer or a detailed explanation; ARES adapts its writing instructions while retaining source citations. Smaller local models may produce shorter answers after evidence checks.
- 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.
Watch the 2-minute 58-second narrated tour: ask a real question, explore its cited answer and suggested follow-ups, inspect sources and research activity, upload a PDF, and discover Library, Memory, model selection, and research preferences.
ARES-Complete-Tour.mp4
The tour uses synthetic narration and recorded application interactions. Retrieval waiting time is shortened for presentation; available tools depend on the configured runtime.
Read the narration transcript
Meet Ares. A research workspace built for curiosity, and for answers you can explore.
You can start with a suggested question, or simply ask what's on your mind.
Choose how you'd like the answer generated: Gemini in the cloud, or Qwen running locally.
Then set the depth of your research. Search for a quick exploration, or choose Research. You can look across the web, academic sources, software references, and your own documents.
There are optional tools, too. Fast retrieval uses a smaller research budget. Cross-checking asks the system to compare claims across sources.
Let's try a real question. How does retrieval augmented generation work, and what are its limitations?
This is a real research run. We've shortened the waiting time for this tour.
Here's the answer. An explanation built from retrieved evidence, with citations alongside the paragraphs. You can read how the process works, and where its limitations begin.
When you want to look closer, open a citation. You'll find the supporting passage and details about its original source.
The Sources workspace brings that evidence together. Search for a passage, or narrow the list with filters.
And the conversation doesn't have to end there. Ares suggests questions to explore next. You can write your own follow-up, or export the answer to revisit later.
Activity shows the steps behind the research, whenever you want that extra context.
Compare is where evidence-linked visual artifacts appear, when the research provides suitable data.
Diagnostics offers a closer look at the run's reported quality and checks.
You can also bring your own material. Use the plus button beside Search to upload a document. Here, we're adding a real PDF.
Once it's ready, you'll find it in Library, together with your other uploaded files.
Memory gives your research its own space. Review previous research and saved facts in separate views, and manage what you'd like to keep.
In Preferences, you can set research depth, tone, preferred domains, and personal instructions. Small choices that help shape how you work.
Settings shows the current runtime and tool capabilities, including what's ready, and what's turned off.
That's Ares. Ask a question. Explore the evidence. And follow your curiosity.
- 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.
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-lockfileThe 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 migrateRun each command in a separate terminal from the repository root. make worker defaults to the combined profile so uploaded files and research runs are both processed:
# Terminal 1 — API
make api# Terminal 2 — research and document-ingestion worker
make worker# Terminal 3 — frontend
make webOpen 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.
Live research uses ARES_MODE=local_live. Restart the API and worker after changing .env.
Install Ollama, start its service, and download the model:
ollama pull qwen3:4bSet 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:4bLocal 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.
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:
| Setting | Meaning |
|---|---|
GEMINI_RPM |
Requests per minute |
GEMINI_TPM |
Tokens per minute |
GEMINI_RPD |
Requests per day |
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.
Start the local infrastructure when using live web search or PostgreSQL:
make infraThis 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:ares@127.0.0.1:5432/ares
SEARXNG_URL=http://127.0.0.1:8080make migrateThese credentials are for local development only. Changing the database URL selects a different database; it does not transfer existing SQLite conversations or files.
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.
.env.example is the starting point for local configuration. Backend settings define validation rules and defaults; values in your .env override those defaults.
| Setting | Purpose |
|---|---|
ARES_MODE |
demo for fixtures; local_live for live providers |
DEPLOYMENT_ENVIRONMENT |
Deployment context: local or production |
AUTH_MODE |
Local disabled-auth mode or configured OIDC authentication |
DATABASE_URL / BLOB_ROOT |
Database connection and asset storage location |
LOCAL_LLM_ENABLED / LOCAL_LLM_MODEL |
Local Ollama writer configuration |
GEMINI_API_KEY / GEMINI_MODEL |
Cloud writer credentials and model |
STRICT_FREE_MODE |
Provider admission and budget restrictions |
SEMANTIC_CHECKER_ENABLED |
Optional model-assisted claim assessment |
MAX_UPLOAD_BYTES / MAX_PDF_PAGES |
Upload and PDF processing limits |
OCR, rich parsing, embeddings, audio, and video have additional dependencies and provisioning requirements. Enable them only after reviewing the corresponding settings and worker requirements.
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 buildmake check aggregates additional checks, migrations, schema generation, and release verification. Some targets generate or update files. Skipped browser checks are explicitly reported as preflight only. A successful aggregate command alone is not production qualification. Run make verify-m11-release with a running app and the required ARES_E2E_* fixture identifiers for the existing three-browser gate.
The 27 October 2026 hardening pass recorded 299 passing backend tests, 8 skipped backend tests, and 28 passing frontend tests, plus static checks and a successful frontend build. The seven PostgreSQL-specific tests were also run separately and passed. Real document-grounded queries completed with both Gemini and Qwen, and browser checks covered answer rendering, PDF upload, and direct chat deletion. These are a dated local baseline, not a live CI badge or public-hosting certification. Deterministic offline evaluations do not establish general real-provider answer quality.
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 hardening changes include:
- Code execution disabled: generated Python is never executed on the worker. The Code tool is removed from run admission and the composer until an isolated runner exists.
- Tracked-file packaging: source archives use Git's tracked-file inventory and exclude private environment files, keys, backups, runtime data, and symlinks.
- Database provisioning: the bootstrap normalizes the SQLAlchemy URL for
psqland grants runtime roles access to the newer schema tables. - Accurate release metadata: version and migration head are derived from source. Missing browser evidence fails the full gate; skipped checks are explicitly preflight only.
- Security dependency updates: the lockfile updates certifi, OpenTelemetry API, Pillow, fastembed, pypdf, and filelock. Recheck advisories when preparing each 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.
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.