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

Environment Setup

ByteMason needs just two API keys to work:


# .env
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key

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
│   └── db/               # Database client
├── public/               # Static assets
└── types/                # TypeScript types

Development Workflow

Making Changes


# Install in development mode
pip install -e .
 
# Run tests
pytest
 
# Try your changes
berry plan "Build a test app"

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

Debugging Tips


# Enable debug logging
export BERRY_DEBUG=1
 
# View AI responses
cat logs/ai_responses_*.log
 
# Test repair agent
berry repair --verbose

Contributing Guidelines

Code Style
- Use type hints
- Follow PEP 8
- Add docstrings to functions

Testing


# Run test suite
pytest
 
# Run specific test
pytest tests/test_agents.py

Documentation
- Update relevant docs
- Add examples for new features
- Include type annotations

Common Development Tasks

1. Adding a New Command


@app.command()
def your_command(arg: str):
    """Your command description"""
    # Implementation

2. Modifying AI Behavior


# Update prompts in src/blueberry/prompts/
CUSTOM_PROMPT = """
Your custom prompt here
"""
 
# Use in agents.py
response = await self.ai.complete(CUSTOM_PROMPT)

3. Adding UI Components


# Add to templates/components/
export function CustomComponent() {
  // Your component code
}

Troubleshooting Development

AI Response Issues
- Check API keys
- Review prompt formatting
- Check response logs
Build Problems
- Verify dependencies
- Check TypeScript types
- Review error patterns
Database Issues
- Validate Supabase credentials
- Check migration files
- Review RLS policies