FAROS

Foundation AutoResearch Operating System

Blueprint-driven AutoResearch runtime for the LLM domain today, extensible research workflows tomorrow.

Release Scope · Why FAROS · Workflow · Architecture · Quick Start · API · TODO

Important

FAROS is not a single hardcoded AI scientist agent. It is a research workflow runtime built around Blueprints, Capabilities, Profiles, and Providers.

This release ships the first runnable baseline: FAROS-LLM.

✨ Tagline

Define a research workflow. Bind a profile. Run an AutoResearch system.

idea -> experiment -> paper -> review

📦 Release Scope

This repository is the current release candidate for the LLM-domain FAROS baseline. It is already a runnable AutoResearch runtime, but it is not yet the final cross-domain platform vision.

Included

FAROS runtime under backend/app/faros
Blueprint loading and profile loading
Capability and provider registries
File-backed run, event, artifact, and memory persistence
First blueprint: ml_paper
First profile: faros_llm
Complete LLM workflow: idea -> experiment -> paper -> review
Existing module-native APIs for idea, code, paper, review, platform
Venue-aware LaTeX paper generation

Not Yet Included

full DAG scheduling and parallel orchestration
generalized non-LLM provider ecosystem
full experiment execution and evaluation loop
FAROS frontend console
DB-backed FAROS runtime metadata
mature cross-domain blueprint library

🤔 Why FAROS

Most "AI scientist" systems are built as one fixed application with one workflow and one set of assumptions. FAROS takes a different approach: treat research automation as a runtime problem, not a single-agent prompt stack.

Layer	Responsibility
Blueprint	Defines the workflow graph, constraints, output contract, and validation requirements.
Capability	Implements one executable research step such as idea refinement, experiment provisioning, paper drafting, or reviewer simulation.
Profile	Binds a blueprint to a concrete execution strategy.
Provider	Supplies the actual engine behind a capability, such as LLM, tool, API, or human review.

Note

In FAROS, LLM is only one provider class. This release ships FAROS-LLM, but the runtime is being shaped so future domains can plug in other providers without rewriting the core orchestration layer.

🚀 What Makes This Release Different

Principle	How This Release Applies It
Keep What Works	The current `idea`, `code`, `paper`, `review`, and `platform` modules are reused through FAROS capability adapters instead of being replaced by a second parallel application.
Add a Runtime Boundary	New orchestration logic lives under `backend/app/faros`, giving memory, verification, profiles, and providers a stable place to evolve.
Finish One Domain First	The first complete chain is the LLM research domain. Cross-domain abstraction comes after the first workflow is coherent and runnable.

🔄 Current Workflow

The first FAROS blueprint is ml_paper.

Stage	Capability	Output
1	`idea_refinement`	Idea session, ranked candidates, selected candidate
2	`experiment`	Code project scaffold and experiment record for the LLM domain
3	`paper_drafting`	Venue-aware LaTeX project, PDF, and paper artifacts
4	`reviewer_simulation`	Structured review plus actionable follow-up items

Current Artifact Surface

Artifact Type	Description
`idea_session`	Idea generation session with ranked candidate outputs
`code_project`	Provisioned research code workspace for the experiment stage
`experiment_record`	Experiment metadata record for the LLM workflow
`latex_project`	Paper source bundle with venue-aware LaTeX assets
`paper_pdf`	Compiled paper PDF or fallback rendered PDF
`review_report`	Structured review with action items

🏗️ Architecture

backend/app/
  faros/
    api/
    blueprints/
    capabilities/
    loaders/
    memory/
    models/
    profiles/
    providers/
    registry/
    runtime/
    verification/
  modules/
    idea/
    code/
    paper/
    review/
    platform/

Runtime Layers

Area	Role
FAROS Runtime	Blueprint loading, capability registry, profile binding, orchestrated execution, event logging, artifact persistence, research memory, and baseline verification
Domain Modules	Reusable implementation surfaces for `idea`, `code`, `paper`, `review`, and `platform`

Execution Model

flowchart LR
    B[Blueprint] --> O[Orchestrator]
    P[Profile] --> O
    R[Provider Registry] --> O
    C[Capability Registry] --> O
    O --> I[idea_refinement]
    I --> E[experiment]
    E --> W[paper_drafting]
    W --> V[reviewer_simulation]
    O --> M[Research Memory]
    O --> A[Artifacts]
    O --> Q[Verification]

🗂️ Repository Layout

github-v1/
  backend/
    app/
      faros/
      modules/
      llm/
      db/
      storage/
    templates/latex/
    tests/
  frontend/
    src/
  docs/
    DEVELOPER_GUIDE.md
    FAROS_TODO.md

⚙️ Runtime Requirements

Python 3.11+ or 3.12
Node.js 18+
latexmk and pdflatex for venue-style PDF compilation
a configured LLM provider for real execution

Tip

The development environment used during this release cycle has been the conda environment aist.

🚀 Quick Start

Backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8005 --reload

Frontend

cd frontend
npm install
npm run dev

Useful Endpoints

Endpoint	Purpose
`GET /api/system/health`	Basic backend health
`GET /api/system/version`	Release metadata
`GET /api/docs`	OpenAPI docs
`GET /api/faros/health`	FAROS runtime health
`GET /api/faros/blueprints`	Available FAROS blueprints
`GET /api/faros/profiles`	Available FAROS profiles

If needed, set VITE_API_BASE_URL for the frontend.

🔐 Provider Configuration

The backend supports multiple providers, including minimax.

Configuration is loaded from:

environment variables defined in backend/app/core/settings.py
runtime settings persisted to backend/data/provider_config.json

Do not commit real API keys.

🔌 FAROS API

Endpoint	Purpose
`GET /api/faros/health`	Runtime health and asset counts
`GET /api/faros/blueprints`	List available blueprints
`GET /api/faros/profiles`	List available profiles
`GET /api/faros/capabilities`	List registered capabilities and providers
`GET /api/faros/runs`	List FAROS runs
`POST /api/faros/runs`	Create a FAROS run
`GET /api/faros/runs/{run_id}`	Inspect one FAROS run
`GET /api/faros/runs/{run_id}/events`	Inspect run events
`GET /api/faros/runs/{run_id}/artifacts`	Inspect run artifacts

Example: Plan-Only Run

curl -X POST http://127.0.0.1:8005/api/faros/runs   -H 'Content-Type: application/json'   -d '{
    "blueprintId": "ml_paper",
    "profileId": "faros_llm",
    "executionMode": "plan",
    "inputs": {
      "seedQuery": "Improve CPU efficiency in LLM workflows",
      "paperType": "system",
      "targetVenue": "generic"
    }
  }'

📝 Paper Generation

Paper generation in this release uses real venue-aware LaTeX template assets.

Template	Description
`icml`	ICML-style LaTeX template path
`neurips`	NeurIPS-style LaTeX template path
`iclr`	ICLR-style LaTeX template path
`acl`	ACL-style LaTeX template path
`generic`	Fallback generic template

Compilation prefers latexmk. If LaTeX compilation fails, the backend falls back to simplified PDF rendering so the workflow still yields a previewable artifact.

✅ Verification

Release Checks

bash scripts/check_release.sh

bash backend/scripts/check_backend_release.sh

bash frontend/scripts/check_frontend_release.sh

Current Validation State

github-v1/backend/tests in aist: 10 passed
FAROS runtime routes mounted
plan-mode FAROS run creation verified
LLM-domain FAROS workflow skeleton wired through idea -> experiment -> paper -> review

🧱 Stable Surface In This Release

These parts should be treated as the release baseline:

Area	Stability Statement
`backend/app/faros/*`	Primary runtime surface for future FAROS work
Blueprint/Profile loading	Stable release baseline
FAROS metadata API	Stable release baseline
Plan-mode FAROS run creation	Stable release baseline
Provider settings path	Stable release baseline
Paper generation path	Stable release baseline
Review generation path	Stable release baseline

📌 Important TODO

The most important next steps after this release are:

replace the current experiment scaffold with true code synthesis and execution for the LLM domain
connect experiment outputs to metrics ingestion, figure generation, and run tracking
replace linear graph execution with a real DAG runtime
add stronger verification beyond required-key checks
add a dedicated FAROS frontend console
add provider inheritance policies instead of hardcoded profile defaults

See docs/FAROS_TODO.md for the detailed backlog.

🛠️ Development Notes

Use docs/DEVELOPER_GUIDE.md for module ownership, extension boundaries, and development conventions.

Current working rule:

extend FAROS under backend/app/faros
keep domain-specific logic inside backend/app/modules/*
avoid adding new business logic to legacy compatibility paths unless required for release stability

📍 Project Status

This repository is the first FAROS release candidate. It is already usable as a runtime baseline for LLM-domain AutoResearch workflows, but it is still the beginning of the platform transition rather than the end state.

GitHub Stars

_{Built with care for the research community.}

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
backend		backend
docs		docs
frontend		frontend
scripts		scripts
FAROS.png		FAROS.png
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

FAROS

✨ Tagline

📦 Release Scope

Included

Not Yet Included

🤔 Why FAROS

🚀 What Makes This Release Different

🔄 Current Workflow

Current Artifact Surface

🏗️ Architecture

Runtime Layers

Execution Model

🗂️ Repository Layout

⚙️ Runtime Requirements

🚀 Quick Start

Backend

Frontend

Useful Endpoints

🔐 Provider Configuration

🔌 FAROS API

Example: Plan-Only Run

📝 Paper Generation

✅ Verification

Release Checks

Current Validation State

🧱 Stable Surface In This Release

📌 Important TODO

🛠️ Development Notes

📍 Project Status

GitHub Stars

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages