Local Development Guide

Learn how to set up ByteMason locally for development and understand its core components.

Quick Setup


# Clone the repository
git clone https://github.com/lumiralabs/bytemason.git
cd bytemason
 
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
 
# Install dependencies
pip install -e .
 
# Set up environment variables
cp .env.example .env
 
# Add API key and model informations

Environment Setup

ByteMason needs just two API keys and four models to work:


# .env file
 
# API keys
ANTHROPIC_API_KEY=your_key
OPENAI_API_KEY=your_key
 
# Default models (available in .env.example) 
PROJECT_BUILDER_MODEL=anthropic/claude-3-5-sonnet-20241022
CODE_AGENT_MODEL=anthropic/claude-3-5-sonnet-20241022
SUPABASE_AGENT_MODEL=anthropic/claude-3-5-sonnet-20241022
REPAIR_AGENT_MODEL=gpt-4o

These keys power the AI agents that generate and repair code.

Project Structure


bytemason/
├── src/
│   └── blueberry/          # Core package directory
│       ├── agents.py       # AI agents implementation
│       ├── cli.py          # Command-line interface
│       ├── models.py       # Data models and types
│       ├── repair_agent.py # Code repair system
│       └── prompts/        # Core prompts for AI
├── tests/                  # Test suite
├── examples/               # Example applications
└── pyproject.toml          # Project configuration

Key Components

Agents (agents.py)


class ProjectBuilder:
    """Main orchestrator for project generation"""
 
class CodeAgent:
    """Handles code generation and modifications"""
 
class SupabaseSetupAgent:
    """Manages database setup and migrations"""

CLI Interface (cli.py)


@app.command()
def plan(prompt: str):
    """Generates project specification from prompt"""
 
@app.command()
def code(spec_path: str):
    """Generates application code from specification"""

Repair System (repair_agent.py)


class RepairAgent:
    """Automatically fixes build errors"""
    def analyze_error(self, error: str) -> BuildErrorReport:
        """Analyzes build errors and suggests fixes"""

Core Prompts

ByteMason uses carefully crafted prompts for different tasks. Here’s a simplified overview:

1. Specification Generation


SPEC_PROMPT = """
Given the following application description:
{user_prompt}
 
Create a detailed specification including:
1. Required database tables and relationships
2. API endpoints and their functionality
3. UI components and their interactions
4. Authentication and authorization rules
"""

2. Code Generation


CODE_PROMPT = """
Generate a Next.js application based on this specification:
{spec}
 
Requirements:
- Use Next.js 14 App Router
- Implement Supabase authentication
- Follow TypeScript best practices
- Use shadcn/ui components
"""

3. Error Repair


REPAIR_PROMPT = """
Given this build error:
{error}
 
And this code context:
{context}
 
Suggest fixes that:
1. Resolve the immediate error
2. Maintain code consistency
3. Follow project patterns
"""

Generated Project Structure

When you create a new project, ByteMason generates this structure:


your-app/
├── app/                   # Next.js 14 App Router
│   ├── page.tsx           # Home page
│   ├── layout.tsx         # Root layout
│   ├── auth/              # Authentication pages
│   └── api/               # API routes
├── components/
│   ├── ui/                # shadcn/ui components
│   └── features/          # Feature components
├── lib/
│   ├── utils.ts           # Utility functions
│   ├── api/               # API functions
├── public/                # Static assets
└── types/                 # TypeScript types

Development Workflow

Making Changes


# Install in development mode
pip install -e .
 
# Try your changes
mason new test
cd test
mason plan "Build a test app"

Testing Prompts
- Modify prompts in src/blueberry/prompts/
- Test with different app descriptions
- Check generated specifications

Contributing Guidelines

Code Style
- Use type hints
- Add docstrings to functions
Documentation
- Update relevant docs
- Add examples for new features
- Include type annotations

Troubleshooting Development

AI Response Issues
- Check API keys
- Review prompt formatting
- Check response logs
Build Problems
- Verify dependencies
- Review error patterns

Next Steps

Read the Architecture Guide
Explore AI Components