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 · Deployment · 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.

🤔 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.

[!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

🔄 Current Workflow

The first FAROS blueprint is ml_paper.

Current Artifact Surface

🏗️ Architecture

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

Runtime Layers

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

FAROS/
  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

🚢 Deployment

The current RC is intended for a simple internal deployment shape:

• one backend API process
• one frontend process or static build
• one writable data directory
• one configured LLM provider for real LLM-backed execution

The most important runtime knobs are:

• backend:
  • API_HOST
  • API_PORT
  • DATA_DIR
  • ACTIVE_PROVIDER_NAME
• frontend:
  • FRONTEND_HOST
  • FRONTEND_PORT
  • VITE_API_BASE_URL
  • VITE_USE_MOCK

Important:

• the frontend helper script uses FRONTEND_PORT, not the CLI --port flag, as the effective dev-server port
• the default frontend backend target is http://127.0.0.1:8005
• real LLM execution is only ready when /api/system/version reports llm.configured=true

See docs/DEVELOPER_GUIDE.md for developer setup notes and docs/FAROS_TODO.md for the current roadmap.

Useful Endpoints

If needed, set VITE_API_BASE_URL for the frontend.

🔐 Provider Configuration

The backend supports multiple providers, including minimax.

Configuration is loaded from:

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

Do not commit real API keys.

🔌 FAROS API

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.

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

• backend/tests: backend smoke and ranking checks
• 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:

📌 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