aura-llm-gateway AGENTS.md

Aura LLM Gateway

Project Overview

Rust-based LLM proxy implementing the Open Responses API specification for agentic workflows. Provides a unified interface to multiple LLM providers (OpenAI, Anthropic, Google) with load balancing, cost tracking, and observability.

Tech Stack

• Language: Rust (2021 edition)
• Web Framework: Axum
• Database: PostgreSQL (SQLx), Redis
• Async Runtime: Tokio
• Serialization: Serde
• Error Handling: thiserror, anyhow
• Logging: tracing
• HTTP Client: reqwest

Project Structure

/crates/
  aura-types/     # Shared type definitions (Open Responses API types)
    src/
      compression.rs   # Compression config types
      consistency.rs   # Response consistency types
      validation.rs    # Response validation types
  aura-core/      # Core business logic (providers, routing, caching)
    src/
      compression/     # Prompt compression (TOON, YAML, AISP, JSON)
      provider/        # LLM providers (OpenAI, Anthropic, Google)
      router/          # Smart routing with health tracking
  aura-proxy/     # Main server binary (Axum routes, middleware)
  aura-db/        # Database models and queries (SQLx)
/apps/
  chat/           # React chat playground (Vite + React 18)
  landing/        # Marketing landing page (Vite + React, MDX docs)
/docs/            # Documentation
  api/            # API documentation (Markdown)
/migrations/      # SQLx database migrations
/sdks/
  python/         # Python SDK (aura-llm on PyPI)

Development Commands

# Build
cargo build                    # Build all crates
cargo build --release          # Build optimized binary

# Test
cargo test                     # Run all tests
cargo test -p aura-core        # Test specific crate
cargo test -- --nocapture      # Show println output

# Run
cargo run -p aura-proxy        # Run the proxy server
RUST_LOG=debug cargo run -p aura-proxy  # With debug logging

# Lint & Format
cargo clippy                   # Lint all crates
cargo clippy --fix             # Auto-fix lint issues
cargo fmt                      # Format code
cargo fmt -- --check           # Check formatting

# Database (requires sqlx-cli)
sqlx migrate run               # Run migrations
sqlx migrate add <name>        # Create new migration

# Docker
docker-compose up -d           # Start local stack
docker-compose logs -f         # Follow logs

# Frontend Apps
cd apps/chat && npm run dev    # Run chat playground (port 3000)
cd apps/landing && npm run dev # Run landing page (port 3001)
cd apps/chat && npm run build  # Build chat app for production