README.md

metadata

title: AutoForge
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit

AutoForge (AgentOS)

AutoForge is an autonomous DAG-based code generation and verification platform. Users submit natural-language software tasks; the system plans, generates code, tests, analyzes, executes in Docker, verifies, and autonomously repairs failures — with full workflow history persisted in PostgreSQL.

Project Status: Fully implemented MVP (Phases 1-20 completed).

The system supports the full autonomous loop:

• Frontend React DAG visualization and event streaming
• Gemini 3.1 Pro LLM adapter for planning and code generation
• Docker Sandbox execution and verification
• Automated failure diagnosis and repair
• Full PostgreSQL state persistence and user isolation

Architecture

flowchart TB
    FE[Frontend] --> API[Backend API]
    API --> ORCH[Workflow Orchestrator]
    ORCH --> PLANNER[Planner LLM]
    ORCH --> MEM[(PostgreSQL)]
    PLANNER --> DAG[DAG Engine]
    DAG --> CODE[Code Agent]
    DAG --> TEST[Test Agent]
    DAG --> ANALYSIS[Static Analysis]
    CODE --> DOCKER[Docker Sandbox]
    TEST --> DOCKER
    ANALYSIS --> DOCKER
    DOCKER --> VERIFY[Verification]

Phase 1 implements the API, PostgreSQL memory layer, authentication, LLM provider abstraction, and workflow persistence.

Repository Structure

AgentOS/
├── backend/           # FastAPI application
│   ├── api/           # HTTP routes (auth, workflows, settings)
│   ├── agents/        # Agent modules (Phase 2+)
│   ├── orchestration/ # DAG engine (Phase 2+)
│   ├── execution/     # Docker sandbox (Phase 2+)
│   ├── analysis/      # Static analysis (Phase 2+)
│   ├── memory/        # Workflow repository
│   ├── llm/           # Provider abstraction
│   ├── db/            # Models and migrations
│   └── events/        # Event publisher
├── frontend/          # React + Vite web UI (Phase 5)
├── benchmark/         # Evaluation suite (Phase 5)
├── docker/            # Dockerfiles
├── tests/             # Backend tests
├── docker-compose.yml
└── .env.example

Local Setup

Prerequisites

• Docker and Docker Compose
• Python 3.12+ (for local development without Docker)

Quick Start (Docker)

cp .env.example .env
docker compose up --build -d

Hugging Face Space Deployment

For deploying AutoForge to a public Hugging Face Space, please refer to the Hugging Face Deployment Guide.

Services:

Service	URL
Frontend	http://localhost:5173
Backend	http://localhost:8000
API docs	http://localhost:8000/docs
PostgreSQL	localhost:5432

Migrations run automatically when the backend container starts.

Local Development (without Docker backend)

# Start PostgreSQL only
docker compose up -d postgres

# Create virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt

# Copy and configure environment
cp .env.example .env

# Run migrations
alembic upgrade head

# Start API server
uvicorn backend.main:app --reload --port 8000

Frontend Development

cd frontend
npm install
npm run dev

The Vite dev server runs at http://localhost:5173 and proxies /api requests to the backend at http://localhost:8000.

For Docker (backend + frontend + PostgreSQL):

docker compose up --build

Environment Variables

See .env.example. Key variables:

Variable	Description
DATABASE_URL	Async PostgreSQL connection string
SECRET_KEY	JWT signing secret
ENCRYPTION_KEY	Key material for API credential encryption
MAX_RETRIES	Max repair attempts (default: 4)
DOCKER_HOST	Docker socket for sandbox (later phases)

Never commit .env files with real secrets.

API Endpoints (Phase 1)

Method	Endpoint	Description
POST	/auth/signup	Create account
POST	/auth/login	Obtain JWT token
GET	/auth/me	Current user
POST	/workflows	Create workflow
GET	/workflows	List user workflows
GET	/workflows/{workflow_id}	Get workflow details
POST	/workflows/{workflow_id}/start	Plan, validate, and execute DAG
GET	/workflows/{workflow_id}/tasks	List workflow tasks
GET	/workflows/{workflow_id}/events	List workflow events (supports after_id)
GET	/workflows/{workflow_id}/events/stream	SSE live event stream
GET	/workflows/{workflow_id}/attempts	List repair/execution attempts
GET	/settings/providers	List LLM providers and models
POST	/settings/api-credentials	Store encrypted API key
GET	/settings/api-credentials	List credentials (redacted)
DELETE	/settings/api-credentials/{id}	Delete credential
GET	/health	Health + DB connectivity

Database Schema

PostgreSQL tables (Phase 1):

• users — authentication
• workflows — workflow records with status and planner output
• tasks — DAG task nodes (schema ready; populated in Phase 2)
• attempts — generation/execution attempts
• events — workflow event stream
• api_credentials — encrypted user LLM API keys

LLM Provider Abstraction

Providers implement:

• generate() — text completion
• generate_structured() — JSON output
• estimate_cost() — token cost estimation

Currently supported: OpenAI and Gemini. The workflow engine resolves providers through get_llm_provider() — no provider-specific code in API routes.

Users can securely enter their own API keys (OpenAI or Gemini) directly in the frontend Settings page. The keys are encrypted at rest in the database and automatically injected into the containerized runner during execution.

Running Tests

# Ensure PostgreSQL is running
docker compose up -d postgres

# Run migrations (if not already applied)
alembic upgrade head

# Install dependencies and run tests
pip install -r backend/requirements.txt
pytest -v

Tests use a real PostgreSQL connection and truncate tables between test cases.

Security Considerations

• Passwords stored as bcrypt hashes
• API keys encrypted at rest (Fernet-derived key from ENCRYPTION_KEY)
• JWT authentication on all workflow endpoints
• Users cannot access other users' workflows
• Generated code execution will run only inside Docker (Phase 2+)

Known Limitations

• Docker sandbox requires Docker on the host for real code execution
• LLM calls require a valid API key (OpenAI supported)
• Benchmark runner not yet implemented

License

See LICENSE (to be added).