Skip to content

Latest commit

 

History

History
278 lines (208 loc) · 7.27 KB

Development.md

File metadata and controls

278 lines (208 loc) · 7.27 KB

Development Guide

Tech Stack

Layer Technology
Frontend Next.js 16, React 18, TypeScript, Tailwind CSS, shadcn/ui
Backend Python 3.11+, FastAPI, LangGraph
Database PostgreSQL, Redis
Storage Cloudflare R2
Sandbox E2B

Prerequisites

  • Node.js 20+
  • Python 3.11+
  • Docker (optional, for PostgreSQL and Redis)

Quick Start

1. Clone and Setup Environment

cd HyperAgent
cp backend/.env.example backend/.env
cp web/.env.example web/.env
# Edit backend/.env and add your API keys

# Optional: use YAML for structured config
cp backend/config.yaml.example backend/config.yaml

2. Start Database Services (Docker)

docker-compose up -d postgres redis

Or run PostgreSQL and Redis locally.

3. Install Dependencies

make install

Or install separately:

make install-web  # Frontend dependencies
make install-backend  # Backend dependencies

4. Start Backend

make dev-backend

5. Start Frontend

make dev-web

Or start both in separate terminals:

make dev  # Shows instructions to run dev-web and dev-backend separately

6. Open Application

Visit http://localhost:5000

Project Structure

HyperAgent/
├── web/                    # Next.js frontend
│   ├── app/               # App router pages
│   ├── components/        # React components
│   │   ├── ui/           # shadcn/ui components
│   │   ├── chat/         # Chat components
│   │   ├── research/     # Research components
│   │   └── layout/       # Layout components
│   └── lib/              # Utilities, stores, types
│
├── backend/                # Python backend
│   ├── app/
│   │   ├── routers/      # API endpoints
│   │   ├── agents/       # LangGraph agents
│   │   │   └── tools/    # Tool implementations (incl. codeact.py)
│   │   ├── sandbox/      # Sandbox managers (unified, execution, app, desktop)
│   │   │   └── hyperagent_lib/  # Helper library for CodeAct mode
│   │   ├── services/     # Business logic (incl. snapshot_service.py)
│   │   └── models/       # Pydantic schemas
│   ├── config.yaml.example  # YAML config template
│   └── pyproject.toml
│
├── docker-compose.yml      # Docker services
└── .env.example           # Environment template

API Endpoints

Endpoint Method Description
/api/v1/health GET Health check
/api/v1/query POST Unified non-streaming query endpoint
/api/v1/query/stream POST Unified streaming query endpoint
/api/v1/tasks GET List tasks
/api/v1/tasks/research POST Submit research task
/api/v1/tasks/{task_id} GET Get task status
/api/v1/tasks/{task_id}/result GET Get completed task result

Removed Endpoints (2026-03-07)

The following endpoints were removed and should not be used:

  • /api/v1/query/status/{task_id}
  • /api/v1/tasks/{task_id}/stream
  • /api/v1/runs/*
  • /api/v1/usage

Configuration

HyperAgent uses a hybrid YAML + env var configuration system.

Loading Priority (highest wins)

  1. Constructor kwargs (programmatic overrides)
  2. Nested env vars (SANDBOX__E2B__API_KEY) — pydantic-settings __ delimiter
  3. Flat env vars / .env file (E2B_API_KEY) — backward-compatible legacy names
  4. YAML config (backend/config.yaml) — structured settings
  5. Defaults (defined in code)

Setup

# Required: copy .env for secrets
cp backend/.env.example backend/.env

# Optional: copy YAML for structured config
cp backend/config.yaml.example backend/config.yaml

Secrets (API keys, passwords) should stay in .env or real environment variables. Non-secret structured settings (timeouts, feature flags, model names) can go in config.yaml.

Accessing Settings

Settings can be accessed via both nested and flat (legacy) paths:

from app.config import settings

# Nested (preferred for new code)
settings.sandbox.e2b.api_key
settings.agents.react.max_iterations
settings.llm.tier_models.max_anthropic

# Flat (backward-compatible, still works everywhere)
settings.e2b_api_key
settings.react_max_iterations
settings.tier_max_anthropic

Overriding with Env Vars

Both flat and nested env var formats work:

# Flat (legacy) — always works
E2B_API_KEY=sk-xxx

# Nested (new) — uses __ delimiter
SANDBOX__E2B__API_KEY=sk-xxx

Key Files

File Purpose
backend/app/config.py Root Settings class
backend/app/config_models.py Nested Pydantic sub-models
backend/app/config_sources.py YAML source, flat alias mapping
backend/config.yaml.example Documented YAML config template
backend/.env.example Env var template (secrets)

Environment Variables (Secrets)

Variable Description Required
ANTHROPIC_API_KEY Anthropic API key Yes*
OPENAI_API_KEY OpenAI API key Yes*
GEMINI_API_KEY Google Gemini API key Yes*
DATABASE_URL PostgreSQL connection No
REDIS_URL Redis connection No
E2B_API_KEY E2B sandbox API key No
NEXTAUTH_SECRET NextAuth session secret Yes (if auth enabled)

*At least one LLM provider key is required.

Web (web/.env)

Variable Description Required
NEXT_PUBLIC_API_URL Backend API URL No

Development Commands

All commands use the Makefile. Run make help to see all available commands.

Installation

make install          # Install all dependencies
make install-web      # Install frontend dependencies only
make install-backend  # Install backend dependencies only

Development

make dev-web          # Start frontend dev server (port 5000)
make dev-backend          # Start backend dev server (port 8080)
make dev-worker       # Start background worker
make dev-all          # Start all services (frontend, backend, worker)

Build

make build            # Build frontend for production
make build-web        # Build frontend only

Linting & Formatting

make lint             # Run all linters
make lint-web         # Lint frontend code
make lint-backend     # Lint backend code
make format-backend   # Format backend code

Testing

make test             # Run all tests
make test-backend     # Run backend tests

Database Migrations

make migrate          # Apply all pending migrations
make migrate-down     # Rollback last migration
make migrate-new msg='description'  # Create new migration
make migrate-status   # Show migration status

Utilities

make clean            # Clean build artifacts and caches
make health           # Check health of all services

Job Queue Management

make queue-stats      # Show job queue statistics
make queue-monitor    # Monitor job queue in real-time
make queue-list       # List all queued jobs
make queue-clear      # Clear all jobs from queue (DESTRUCTIVE)
make queue-health     # Check worker and queue health
make queue-test       # Submit a test task to verify worker