README.md

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

```mermaid
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

```text
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)

```bash
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](HUGGINGFACE_DEPLOYMENT.md).

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)

```bash
# 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

```bash
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):

```bash
docker compose up --build
```

## Environment Variables

See [`.env.example`](.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

```bash
# 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).