baml-codegen

What this skill does

# 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**:
```yaml
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