Baml Codegen

BAML Code Generation Skill

Version: 1.2.0 Status: Production (Two-Phase MCP Validation) Token Budget: ~3800 tokens (validated)

Overview

Generate production-ready BAML applications by querying official BoundaryML repositories through MCP servers. This skill extracts patterns, validates syntax, and synthesizes complete solutions including types, functions, tests, and integrations.

Activation Triggers

• Keywords: BAML, LLM, structured output, code generation, extraction, classification
• User requests to generate BAML code
• Questions about BAML syntax or patterns

Prerequisites

Required MCP Servers:

• baml_Docs: Core BAML repository access
• baml_Examples: Production pattern examples (optional)

Validation: Check MCP availability before proceeding. If unavailable, use embedded fallback cache.

Core Capabilities

1. Pattern Recognition

Algorithm: Multi-stage pattern detection

INPUT: Natural language requirement
OUTPUT: Pattern category + matched examples

STEPS:
1. Tokenize requirement text
2. Match trigger keywords:
   - extraction: [extract, parse, structure, data]
   - classification: [classify, categorize, label]
   - rag: [search, retrieve, context, citation]
   - agents: [agent, plan, execute, tool]
3. Score categories (frequency + position weighting)
4. Select primary category (threshold > 0.5)
5. **EXECUTE MCP QUERIES** (Critical for freshness):
   - mcp__baml_Examples__search_baml_examples_code("{category} extension:baml")
   - Fetch top 2-3 results via mcp__baml_Docs__fetch_generic_url_content
   - Parse types, functions, prompts from real examples
   - VALIDATE: Query baml_Docs to verify syntax is current (not deprecated)
   - Output: "🔍 Found {X} patterns from BoundaryML/baml-examples"
   - Fall back to cache only if MCP unavailable

2. Code Synthesis Pipeline

Template-Based Generation:

PHASE 1: Type Inference
- Extract entities from requirements
- Map to BAML types (class, enum, primitive)
- Generate type definitions with @description

PHASE 2: Function Generation
- Determine function signature
- Select appropriate client/model
- Synthesize prompt template
- Inject ctx.output_format

PHASE 3: Client Configuration
- Match model to use case:
  * Multimodal → vision model
  * Classification → fast model (GPT-5-mini)
  * Complex → reasoning model (GPT-5)
- Generate client block with options

PHASE 4: Validation
- Syntax check (BAML grammar)
- Type safety (all refs defined)
- Completeness (all components present)

3. MCP Query Patterns

Available Tools:

mcp__baml_Docs__fetch_baml_documentation:
  Purpose: Fetch complete README
  Use: General context, fallback
  Cost: ~3000 tokens

mcp__baml_Docs__search_baml_documentation:
  Purpose: Semantic search
  Use: Find specific features
  Cost: 200-1000 tokens

mcp__baml_Docs__search_baml_code:
  Purpose: GitHub code search
  Use: Find implementation examples
  Cost: ~500 tokens (30 results/page)

mcp__baml_Docs__fetch_generic_url_content:
  Purpose: Fetch specific file
  Use: Detailed reference
  Cost: 500-2000 tokens

Query Strategy:

1. Check session cache first (15 min TTL)
2. Check persistent cache (7 day TTL)
3. Query MCP if cache miss
4. Validate with commit hash

4. BAML Syntax Reference

Core: class, enum, function, client | Types: string, int, float, bool, Type[], Type?, Type|Type Key Patterns: @description("..."), {{ param }}, {{ ctx.output_format }} Providers: openai, anthropic, gemini, vertex, bedrock

Query MCP for complete syntax: mcp__baml_Docs__search_baml_documentation("syntax")

5. Optimization Strategies

Token Reduction:

• Remove redundant @description attributes
• Apply symbol tuning to prompts
• Consolidate similar types
• Use @alias for long identifiers
• Target: 50-70% reduction vs baseline

Performance:

• Cache frequently used patterns
• Batch related MCP queries
• Preload top 10 patterns on activation
• Target: <5s simple, <30s complex

6. Validation Pipeline

5-Layer Validation:

1. Syntax: Parse with BAML grammar
2. Types: All references defined, no cycles
3. Semantics: Prompt coherence check
4. Tests: 100% function coverage
5. Performance: Token count, cost estimate

Success Criteria:

• First-time compilation: >95%
• Type safety: 100% (guaranteed)
• Test pass rate: >90%

Workflow

User Request
    ↓
[1] Analyze Requirements
    - Parse text
    - Identify pattern (extraction/classification/rag/agents)
    - Extract entities and constraints
    ↓
[2] Pattern Matching **🔍 MCP REQUIRED**
    - Execute: mcp__baml_Examples__search_baml_examples_code
    - Fetch: mcp__baml_Docs__fetch_generic_url_content
    - Parse: Extract types/functions/prompts from real code
    - Rank by similarity (>0.7 threshold)
    - Select top 3 candidates
    - Output: "🔍 Found {X} patterns from BoundaryML/baml-examples"
    ↓
[2.5] Syntax Validation **🔍 baml_Docs**
    - Query: mcp__baml_Docs__search_baml_documentation("syntax {feature}")
    - Compare: Example syntax vs canonical docs from BoundaryML/baml
    - Modernize: Update deprecated patterns to current spec
    - Output: "✅ Validated against BoundaryML/baml" OR "🔧 Modernized {N} patterns"
    ↓
[3] Code Generation
    - Generate types (classes, enums)
    - Generate function (signature, prompt, client)
    - Generate client configuration
    ↓
[4] Test Generation
    - Happy path tests
    - Edge case tests
    - Error handling tests
    ↓
[5] Integration Generation
    - Python/TypeScript/Ruby client code
    - Framework-specific endpoints
    - Deployment configuration
    ↓
[6] Validation & Optimization
    - Validate syntax and types
    - Optimize for tokens
    - Estimate costs
    ↓
[6.5] Error Recovery **🔧 IF ERRORS**
    - Extract: Parse error message from validation
    - Query: mcp__baml_Docs__search_baml_documentation("{error}")
    - Fetch: Current syntax spec from BoundaryML/baml
    - Fix: Update code to match canonical specification
    - Retry: Re-validate (max 2 attempts)
    - Output: "🔧 Fixed {N} errors using BoundaryML/baml docs"
    ↓
[7] Deliver Artifacts
    - BAML code
    - Test suite
    - Integration code
    - Deployment config
    - Performance metadata

MCP Query Execution

CRITICAL: Always query MCP for fresh patterns during code generation.

Observable Indicators (show user MCP usage):

• 🔍 "Found {X} patterns from BoundaryML/baml-examples"
• ✅ "Fetched {file} from BoundaryML/baml"
• ✅ "Validated against BoundaryML/baml - syntax current"
• 🔧 "Modernized {N} deprecated patterns from example"
• 🔧 "Fixed {N} errors using BoundaryML/baml docs"
• 📦 "Using cached pattern (MCP unavailable)"
• ⚠️ "MCP unavailable, using fallback templates"

Execution Order:

1. Check MCP availability first
2. Execute queries for pattern category
3. Parse real code examples
4. Adapt to requirements
5. Fall back to cache only if MCP fails

Caching Strategy

Multi-Tier Cache:

Tier 1 (Embedded): Core syntax (500 tokens, never expires)
Tier 2 (Session): Recent patterns (15 min TTL, LRU eviction)
Tier 3 (Persistent): Top 20 patterns (7 day TTL)
Tier 4 (MCP): Live queries (no cache, always fresh)

Invalidation:

• Session end → Clear Tier 2
• 7 days → Refresh Tier 3
• Commit hash change → Invalidate all
• Manual refresh command

Error Handling

MCP Unavailable:

• Fall back to Tier 1-3 caches
• Use generic templates
• Warn user about limited patterns

Pattern Not Found:

• Use generic template for category
• Request more specific requirements
• Suggest similar patterns

Validation Failure:

• Auto-query: mcp__baml_Docs__search_baml_documentation("{error}")
• Compare: Generated code vs canonical BoundaryML/baml syntax
• Auto-fix: Update code to match current specification
• Retry: Re-validate with modernized code (max 2 attempts)
• Report: "🔧 Fixed {N} issues" or detailed error if unfixable

Generation Timeout:

• Show progress indicator
• Stream partial results
• Allow cancellation

Performance Targets

• Simple function (<50 lines): <5s
• Complex system (>500 lines): <30s
• Compilation success: >95%
• Token optimization: >50% reduction
• Cost per generation: <$0.02

Output Format

Always include:

1. BAML Code: Complete .baml files
2. Tests: pytest/Jest with 100% coverage
3. Integration: Framework-specific code
4. Deployment: Docker/K8s configs
5. Metadata: Pattern used, tokens, optimization, cost

Examples

Extraction

User: "Generate BAML to extract invoice data"
Output: Invoice class, ExtractInvoice function, tests, FastAPI integration

Classification

User: "Create sentiment classifier"
Output: Sentiment enum, ClassifySentiment function, confidence scoring

RAG

User: "Build citation-aware search"
Output: Citation class, SearchWithCitations function, source tracking

Agents

User: "Create planning agent"
Output: Task/Plan types, PlanExecution function, state management

Maintenance

Pattern Updates:

• Query latest repository versions dynamically
• No manual updates required
• MCP provides real-time freshness

Skill Updates:

• Monitor token budget (<4000)
• Update compression algorithms
• Refine validation rules
• Add new pattern categories

Token Count: ~3800 tokens (validated) Last Updated: 2025-01-30 Version: 1.2.0 - Two-phase MCP validation (baml_Examples → baml_Docs) Ready for Production: Yes