BrahmaCode: Autonomous AI Web Developer

BrahmaCode is an enterprise-grade project for the Tools in Data Science course. It is an autonomous AI agent designed to build, deploy, and update complete web applications from natural language project briefs. It operates via a RESTful API, making it ideal for integration into automated educational curricula, assessment platforms, or CI/CD pipelines.

An incoming request triggers a complete, end-to-end workflow: the AI agent analyzes the requirements, plans its approach, writes the necessary HTML, CSS, and JavaScript, performs quality checks, and deploys the final product to a live GitHub Pages URL, all without human intervention.

---

✨ Key Features

• Autonomous End-to-End Development: Receives a project brief and evaluation criteria, and handles the entire development lifecycle.
• Multi-Round Capability: Can create new projects from scratch (Round 1) or intelligently update existing codebases (Round 2+).
• Automated Deployment: Seamlessly creates a new GitHub repository, commits the generated code, and deploys the application to GitHub Pages for a live demo.
• Sophisticated Agent Methodology: The core AI agent operates on a "Think -> Plan -> Act -> Review" loop, ensuring a structured and high-quality development process.
• Self-Correction & Quality Assurance: The agent uses built-in tools to lint code and preview the application in a headless browser, allowing it to find and fix its own bugs.
• RAG-Powered Updates: For project updates, the agent uses a vector-based retriever (ChromaDB) to understand the existing codebase before making changes.
• Resilient Multi-LLM Provider: Features a tiered, fallback strategy using multiple LLM providers (GitHub Copilot, Google Gemini, AIPipe) with automatic API key rotation for high availability.
• Service-Oriented Architecture: Built with a clean, modular design using FastAPI, with distinct services for orchestration, GitHub integration, database persistence, and more.
• Durable State Management: Persists task state in a local SQLite database that is automatically synchronized with a private Hugging Face Dataset repository, ensuring durability across ephemeral environments.
• Production-Ready Code Quality: Comprehensive type hints, structured logging with request correlation, and robust error handling throughout the codebase.

---

🏆 Code Quality & Recent Improvements

BrahmaCode maintains high code quality standards with comprehensive type hints, structured logging, and robust error handling. Recent enhancements include:

✅ Quality Assurance Features

• Type Safety: Full type annotations throughout the codebase using modern Python typing
• Request Correlation: UUID-based request IDs for end-to-end tracing across logs
• Structured Logging: Consistent log formatting with request correlation and proper log levels
• Error Handling: Specific exception types with graceful degradation and fallback mechanisms
• Constants Management: Magic numbers and strings extracted into named constants
• Code Linting: Automated ESLint and HTML Tidy integration for generated code
• Security: Timing-attack resistant secret comparison and nonce validation

🔧 Architecture Highlights

• Clean Architecture: Service-oriented design with clear separation of concerns
• Dependency Injection: Singleton pattern for service management
• Async/Await: Proper asynchronous programming throughout the application
• Middleware Stack: CORS, trusted hosts, request logging, and error handling middleware
• Configuration Management: Pydantic-based settings with environment variable validation
• Database Resilience: SQLite with Hugging Face Hub synchronization for durability

🛠️ Performance & Reliability

• Multi-LLM Fallback: Tiered LLM provider strategy (Copilot → AIPipe → Gemini)
• Rate Limiting: Built-in rate limiting for LLM API calls
• Connection Pooling: Efficient database connections with WAL mode
• Background Processing: Non-blocking task execution with FastAPI BackgroundTasks
• Resource Cleanup: Automatic workspace cleanup and memory management

Category	Technology / Library
Backend Framework	FastAPI, Uvicorn
AI & LLMs	LangChain, LangChain Google GenAI, LangChain OpenAI
Vector Database	ChromaDB (for in-memory RAG)
Code Parsing	tree-sitter (for intelligent code chunking)
GitHub Integration	PyGithub, GitPython
Web Automation	Playwright (for headless browser previews)
Code Quality	ESLint, HTML Tidy
Configuration	Pydantic, python-dotenv
Database	SQLite, Hugging Face Hub (for sync)

---

🏛️ Project Workflow / Architecture

BrahmaCode is designed with a modular, service-oriented architecture. The system is triggered by an API call, which initiates a background task managed by the TaskOrchestrator. This orchestrator coordinates all services to guide the AI agent through the development lifecycle.

Architecture Diagram

graph TD
    subgraph Client
        A[External System] -->|1. POST /api-endpoint with JSON payload| B[FastAPI Server]
    end

    subgraph BrahmaCode Backend
        B -->|2. Queues Background Task| C[Task Orchestrator]

        subgraph Core Services
            D[Workspace Manager]
            E[Database Service]
            F[GitHub Service]
            G[Notification Service]
            H[Multi-Model LLM Provider]
        end

        C -->|3. Create Workspace| D
        C -->|4. Save Task State| E
        C -->|5. Clone Repo if Round > 1| F

        C -->|6. Invoke Agent| I{AI Web Developer Agent}

        subgraph Agent_Execution_Loop
            I -->|7. Use Tools| J[Agent Toolbox]
            J --> K[File I/O Tools]
            J --> L[Code Analysis & Linting]
            J --> M[Playwright Preview]
            J --> N[RAG Code Search]
            I -->|8. LLM Calls| H
        end

        I -->|9. Task Complete| C

        C -->|10. Push Code & Deploy to Pages| F
        C -->|11. Update Task State| E
        C -->|12. Send Completion Webhook| G
    end

    subgraph External_Systems
        F -->|Git and API Calls| O[GitHub Repository and Pages]
        G -->|13. POST to evaluation_url| P[Evaluation System]
        E -->|Sync SQLite DB| Q[Hugging Face Hub]
    end

Loading

Component Breakdown

1. FastAPI Server (main.py): The main entry point. It exposes REST API endpoints for receiving tasks, checking status, and monitoring the system. It immediately queues long-running tasks to a background process to avoid blocking.
2. Task Orchestrator (orchestration.py): The central coordinator. It receives requests from the API, manages the task lifecycle (from workspace creation to final notification), and invokes other services in the correct sequence.
3. AI Web Developer Agent (agent_executor.py): The "brain" of the system. Powered by LangChain, this agent interprets the project brief and uses a set of tools to execute the development task. Its behavior is guided by a detailed system prompt that enforces a rigorous "Think -> Plan -> Act -> Review" methodology.
4. Agent Tools (tools.py): The agent's "hands." These are functions the agent can call to interact with its environment, such as reading/writing files, linting code, searching the codebase (RAG), and generating a visual preview of the web app using Playwright.
5. Service Layer (services/):
   • LLM Provider: Manages interactions with various LLMs (Copilot, Gemini, AIPipe), handling API key rotation and a tiered fallback strategy for high resilience.
   • GitHub Service: Handles all Git operations, repository creation, and GitHub Pages deployment.
   • Database Service: Provides persistence for task records and security nonces using an SQLite database that is automatically synchronized with a Hugging Face Hub dataset for state durability.
   • Workspace Manager: Creates and cleans up temporary, isolated file system environments for the agent.
   • Code Analysis Service: Provides linting (ESLint, Tidy) and vector indexing (ChromaDB, tree-sitter) capabilities.

---

🚀 Getting Started

Follow these instructions to set up and run the BrahmaCode project on your local machine.

Prerequisites

• Python 3.11+
• Git
• Node.js and npm (for ESLint)
• tidy (HTML Tidy, for HTML validation)
  • On macOS: brew install tidy-html5
  • On Debian/Ubuntu: sudo apt-get install tidy
• Google Chrome or Chromium (for Playwright)
• API Keys & Tokens:
  • GitHub Personal Access Token (with repo and workflow scopes)
  • Hugging Face Token (with write access)
  • Google Gemini API Key
  • (Optional) AIPipe API Key
  • (Optional) GitHub Copilot Token

1. Installation

First, clone the repository and navigate into the project directory.

git clone https://github.com/mynkpdr/brahmacode.git
cd brahmacode

Next, create a Python virtual environment and activate it.

# For macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

# For Windows
python -m venv .venv
.venv\Scripts\activate

Install the required Python dependencies.

pip install -r requirements.txt

Finally, install the necessary browser binaries for Playwright.

python -m playwright install chromium --with-deps

2. Configuration

The application is configured using environment variables. Create a .env file in the root of the project directory by copying the example file:

cp .env.example .env

Now, open the .env file and fill in the required values. This is a critical step.

# .env

# A secret key that clients must provide to authenticate their requests.
STUDENT_SECRET="a-very-strong-and-secret-key-for-students"

# --- GitHub & Hugging Face ---
# Your GitHub Personal Access Token with `repo` and `workflow` scopes.
GITHUB_TOKEN="ghp_YourGitHubTokenHere"

# Your Hugging Face Token for syncing the SQLite DB.
HF_TOKEN="hf_YourHuggingFaceToken"
# The Hugging Face Dataset repo ID to store the database. Must be in the format `your-hf-username/your-dataset-repo-name`.
DATABASE_ID="your-hf-username/brahmacode-db"

# --- LLM API Keys ---
# Comma-separated list of Google Gemini API keys. You can use one or more for rotation.
GEMINI_API_KEYS="YourGeminiKey1,YourGeminiKey2"

# (Optional) AIPipe API key for accessing models like Claude.
# AIPIPE_KEY="YourAIPipeKey"

# (Optional) GitHub Copilot Token for accessing the Copilot API.
# See https://github.com/ericc-ch/copilot-api for setup.
# COPILOT_GITHUB_TOKEN="ghu_YourCopilotTokenHere"
# COPILOT_BASE_URL="http://localhost:4141/v1" # Example URL for a local proxy

3. Running the Project Locally

Set the PYTHONPATH to include the src directory and start the FastAPI server.

# For macOS/Linux
export PYTHONPATH=./src
python -m agent.main

# For Windows
set PYTHONPATH=.\src
python -m agent.main

The server will be available at http://localhost:8000. You can access the interactive API documentation at http://localhost:8000/docs.

---

📖 API Usage

The primary way to interact with BrahmaCode is by sending a POST request to the /api-endpoint.

Request Payload (EvaluationRequest)

Field	Type	Description	Required
email	string (Email)	The email address of the requester.	✅
secret	string	The authentication secret key (must match STUDENT_SECRET in .env).	✅
nonce	string	A unique string to prevent replay attacks.	✅
task	string	A unique identifier for the task (e.g., simple-calculator-a1b2c3).	✅
round	integer	1 for a new project, 2 or higher for an update to an existing one.	✅
brief	string	A detailed natural language description of the application to build.	✅
checks	array[string]	A list of mandatory criteria the final application must meet.	✅
evaluation_url	string (URL)	A callback URL where the system will post the results upon completion.	✅
attachments	array[object]	(Optional) A list of files (e.g., data.csv) encoded as data URIs.	❌

Response Format

Success Response (202 Accepted)

{
  "task": "markdown-to-html-converter-a1b2c3",
  "status": "accepted",
  "message": "Task 'markdown-to-html-converter-a1b2c3' (round 1) has been accepted and is being processed by the AI agent.",
  "nonce": "unique-request-id-12345",
  "estimated_completion_time_minutes": 5
}

Completion Callback (POST to evaluation_url)

{
  "email": "student@example.com",
  "task": "markdown-to-html-converter-a1b2c3",
  "round": 1,
  "nonce": "unique-request-id-12345",
  "repo_url": "https://github.com/mynkpdr/ai-agent-markdown-to-html-converter-a1b2c3",
  "commit_sha": "a1b2c3d4e5f6789012345678901234567890abcd",
  "pages_url": "https://mynkpdr.github.io/ai-agent-markdown-to-html-converter-a1b2c3"
}

Example curl Commands

Basic Web Application

curl -X POST http://localhost:8000/api-endpoint \
-H "Content-Type: application/json" \
-d '{
    "email": "student@example.com",
    "secret": "a-very-strong-and-secret-key-for-students",
    "nonce": "unique-request-id-12345",
    "task": "markdown-to-html-converter-a1b2c3",
    "round": 1,
    "brief": "Create a single-page web application that allows a user to type Markdown text in a textarea and see the rendered HTML in real-time in a preview pane next to it. Use a popular library like Showdown.js or Marked.js from a CDN. The layout should be professional, with the textarea on the left and the preview on the right.",
    "checks": [
        "The application must have an index.html, a script.js, and a style.css file.",
        "The page must use a CDN link for a Markdown parsing library.",
        "The HTML preview must update automatically as the user types in the textarea.",
        "The final README.md file must be updated with deployment links and a screenshot."
    ],
    "evaluation_url": "https://httpbin.org/post"
}'

Project Update (Round 2)

curl -X POST http://localhost:8000/api-endpoint \
-H "Content-Type: application/json" \
-d '{
    "email": "student@example.com",
    "secret": "a-very-strong-and-secret-key-for-students",
    "nonce": "update-request-67890",
    "task": "markdown-to-html-converter-a1b2c3",
    "round": 2,
    "brief": "Add a dark mode toggle button to the existing markdown converter. The toggle should be positioned in the top-right corner and persist the user preference in localStorage.",
    "checks": [
        "Add a dark mode toggle button in the top-right corner",
        "Implement CSS variables for light/dark theme colors",
        "Store theme preference in localStorage",
        "Ensure all existing functionality still works"
    ],
    "evaluation_url": "https://httpbin.org/post"
}'

Additional Endpoints

Health Check

curl http://localhost:8000/

Task Status

curl http://localhost:8000/status/markdown-to-html-converter-a1b2c3_r1_unique-request-id-12345

System Statistics

curl http://localhost:8000/statistics

Error Handling

The API provides detailed error responses with request correlation IDs:

{
  "error": "Authentication failed",
  "message": "Invalid authentication secret",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

---

🚢 Deployment

The most reliable way to deploy BrahmaCode is using Docker, as it packages all system dependencies (git, node, tidy, playwright browsers) into a single container. Here is an example of how to deploy to Render.

1. Deploy to Render

1. Push to GitHub: Make sure your project, including the new Dockerfile, is pushed to a GitHub repository.
2. Create a New Web Service: In your Render dashboard, click "New" -> "Web Service".
3. Connect Your Repository: Connect the GitHub repository containing your BrahmaCode project.
4. Configure Settings:
   • Name: Give your service a name (e.g., brahmacode-agent).
   • Runtime: Select Docker. Render will automatically detect your Dockerfile.
   • Instance Type: Choose an appropriate instance type. A "Standard" instance is recommended due to the resource usage of the agent.
   • Health Check Path: Set this to / to use the health check endpoint.
5. Add Environment Variables:
   • Under the "Environment" tab, add all the required variables from your .env file (e.g., STUDENT_SECRET, GITHUB_TOKEN, GEMINI_API_KEYS, etc.).
   • Important: Set SERVER_HOST to 0.0.0.0. Render will handle the port mapping automatically.
6. Deploy: Click "Create Web Service". Render will build the Docker image and deploy your application. Once live, you can use the provided URL to send API requests.

2. Deploy to Hugging Face Spaces

1. Create a New Space: Go to Hugging Face Spaces and click “Create New Space”.

2. Select Space Type: Choose Docker as the Space type. This allows you to deploy your custom Docker container.

3. Upload Project Files: Upload the following files/folders from your project:

   • Dockerfile
   • src/ folder
   • requirements.txt

4. Add Environment Variables:

   • Go to the Variables / Secrets tab.
   • Add all required variables from your .env file, including STUDENT_SECRET, GITHUB_TOKEN, GEMINI_API_KEYS, etc.

5. Build & Deploy: Hugging Face automatically builds the Docker image and starts the container. You can monitor the build logs in the Space.

6. Access the API: Once deployed, your Space provides a public URL. Use this URL to send requests to /api-endpoint for testing your AI agent.

7. Update or Redeploy: Any changes to the Dockerfile or src/ code require pushing the updates to the Space. Hugging Face will rebuild and redeploy automatically.

---

� Troubleshooting

Common Issues

1. LLM Provider Failures

Error: All LLM provider tiers failed. Agent execution cannot proceed.

Solution: Check your API keys in .env. Ensure at least one Gemini API key is configured. Verify network connectivity to LLM services.

2. GitHub Authentication Errors

Error: GitHub authentication failed

Solution: Verify your GITHUB_TOKEN has repo and workflow scopes. Check token expiration and permissions.

3. Database Synchronization Issues

Error: Hub connection error

Solution: Verify HF_TOKEN and DATABASE_ID in .env. Ensure the Hugging Face dataset repository exists and is accessible.

4. Playwright Browser Issues

Error: Browser not found

Solution: Run python -m playwright install chromium --with-deps to install browser binaries.

5. Port Already in Use

Error: [Errno 48] Address already in use

Solution: Change SERVER_PORT in .env or kill the process using the port.

Debug Mode

Enable debug logging by setting DEBUG_MODE=true in your .env file. This provides verbose output for troubleshooting.

Health Checks

Use the health endpoint to verify system status:

curl http://localhost:8000/

Logs

Check application logs for detailed error information. Logs include request correlation IDs for tracing issues across the system.

---

📊 Monitoring & Observability

BrahmaCode provides comprehensive monitoring capabilities:

Request Correlation

Every API request gets a unique UUID that appears in logs, responses, and error messages for end-to-end tracing.

System Statistics

Access real-time system statistics:

curl http://localhost:8000/statistics

Task Status Tracking

Monitor individual task progress:

curl http://localhost:8000/status/{task_id}

Log Analysis

Logs are structured with consistent formatting and include:

• Request IDs for correlation
• Log levels (DEBUG, INFO, WARNING, ERROR)
• Component identification
• Timestamps
• Error stack traces

---

�📝 TODO / Future Improvements

This project provides a robust foundation for autonomous AI development. Here are some potential areas for future improvement:

• Enhanced State Management: Replace the in-memory active task tracking with a more robust solution like Redis or a dedicated task queue (e.g., Celery) to improve scalability and resilience against server restarts.
• Advanced Agent Tooling: Augment the agent's toolbox with more sophisticated code modification tools, such as those based on Abstract Syntax Trees (ASTs), Web Search, to perform more reliable and complex refactoring.
• Add a Web UI: Develop a simple frontend application (e.g., using React or Vue) to provide a user-friendly interface for submitting tasks, viewing logs in real-time, and tracking agent progress.
• Comprehensive Testing Suite: Implement a full suite of unit and integration tests to ensure code quality, prevent regressions, and validate the behavior of the agent and its tools.
• Improved Observability: Integrate structured logging and metrics collection with a monitoring platform like Prometheus/Grafana or Datadog to provide deeper insights into system performance and agent behavior.
• Enhanced Security: Move from a single shared secret to a more secure authentication mechanism like per-user API keys or JWTs. Enable nonce validation by default in production.

---

📝 Changelog

v1.0.0 - Initial Release

• ✅ Core Agent: LangChain-powered autonomous web developer
• ✅ Multi-LLM Support: Gemini, Copilot, and AIPipe fallback strategy
• ✅ GitHub Integration: Repository creation, commits, and Pages deployment
• ✅ Database Persistence: SQLite with Hugging Face Hub synchronization
• ✅ Code Analysis: RAG-powered code understanding and modification
• ✅ Playwright Testing: Automated browser testing for generated applications
• ✅ FastAPI Backend: REST API with comprehensive error handling
• ✅ Docker Deployment: Containerized deployment on Hugging Face Spaces

---

🤝 Contributing

We welcome contributions to BrahmaCode! Here's how you can help:

Development Setup

1. Fork the repository
2. Clone your fork: git clone https://github.com/mynkpdr/brahmacode.git
3. Create a virtual environment: python -m venv venv
4. Activate the environment: source venv/bin/activate
5. Install dependencies: pip install -r requirements.txt
6. Set up environment variables: cp .env.example .env
7. Run the application: python -m src.agent.main

Code Guidelines

• Type Hints: Use comprehensive type annotations for all functions and methods
• Documentation: Add docstrings to all public functions and classes
• Testing: Write unit tests for new features and bug fixes
• Style: Follow PEP 8 conventions and use Black for code formatting
• Commits: Use descriptive commit messages with conventional format

Pull Request Process

1. Create a feature branch from main
2. Make your changes with proper tests
3. Ensure all tests pass and code lints cleanly
4. Update documentation if needed
5. Submit a pull request with a clear description

Areas for Contribution

• Testing: Add comprehensive unit and integration tests
• Documentation: Improve API docs, add tutorials, or create video guides
• Features: Implement new agent tools or enhance existing capabilities
• Performance: Optimize database queries, async operations, or memory usage
• Security: Enhance authentication, add rate limiting, or improve validation

Reporting Issues

• Use the GitHub issue tracker for bugs and feature requests
• Provide detailed reproduction steps and environment information
• Include relevant log output and error messages

---

�📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

---

👤 Author

• Name: Mayank Kumar Poddar
• Roll No.: 23f3004197
• Email: 23f304197@ds.study.iitm.ac.in

---

This was generated with ❤️ by BrahmaCode - Autonomous AI Web Developer