Skip to content

MODULAR_BUILDER.md

Latest commit

 

History

History
278 lines (197 loc) · 5.53 KB

MODULAR_BUILDER.md

File metadata and controls

278 lines (197 loc) · 5.53 KB

Using modular-builder Agent

Guide to using the modular-builder AI agent for generating module scaffolding.

What is modular-builder?

modular-builder is an AI agent that generates module scaffold code based on specifications. It helps you:

  • Generate initial module structure
  • Create pyproject.toml with correct entry points
  • Scaffold test files
  • Generate basic README documentation

Important: modular-builder generates starting points, not production code. Always review and test.

When to Use

Use modular-builder when:

  • Starting a new module from scratch
  • Unsure about entry point configuration
  • Want to quickly prototype an idea
  • Need boilerplate for a standard pattern

Write manually when:

  • Complex custom logic required
  • Integrating with existing code
  • Performance-critical implementation
  • Specialized error handling needed

Specification Format

Create a YAML specification:

# module-spec.yaml
name: myfeature
type: tool
description: Convert text to various formats
author: Your Name

functions:
  - name: to_uppercase
    description: Convert text to uppercase
    parameters:
      text:
        type: string
        description: The text to convert
    returns:
      type: string
      description: The uppercased text

  - name: to_lowercase
    description: Convert text to lowercase
    parameters:
      text:
        type: string
        description: The text to convert
    returns:
      type: string
      description: The lowercased text

config:
  strict_mode:
    type: boolean
    default: false
    description: Raise errors on invalid input

dependencies:
  - amplifier-foundation>=0.1.0

test_coverage: 85

Invoking modular-builder

# Generate module
modular-builder generate --spec module-spec.yaml --output ./amplifier-module-tool-myfeature

# With custom template
modular-builder generate --spec module-spec.yaml --template advanced --output ./my-module

# Dry run (show what would be generated)
modular-builder generate --spec module-spec.yaml --dry-run

Generated Structure

modular-builder creates:

amplifier-module-tool-myfeature/
├── amplifier_module_tool_myfeature/
│   ├── __init__.py          # mount() and get_schema()
│   ├── _internal.py         # Implementation stubs
│   └── py.typed
├── tests/
│   ├── conftest.py          # Test fixtures
│   └── test_unit.py         # Test stubs
├── pyproject.toml            # Complete with entry points
├── README.md                 # Generated documentation
└── .gitignore

Validating Generated Code

After generation:

1. Review the Code

cd amplifier-module-tool-myfeature

# Check structure
tree .

# Read generated code
cat amplifier_module_tool_myfeature/__init__.py

2. Install Dependencies

uv venv
uv pip install -e ".[dev]"

3. Run Tests

uv run pytest

4. Test Locally

export AMPLIFIER_MODULE_TOOL_MYFEATURE=$(pwd)

python -c "
from amplifier_foundation import load_bundle
import asyncio
asyncio.run(load_bundle('./test_profile.md'))
"

5. Review README

# Ensure README matches implementation
cat README.md

Iterating on Specifications

If generated code isn't right:

Update Specification

# Add new function
functions:
  - name: to_titlecase
    description: Convert to title case
    # ...

Regenerate

# Regenerate (will prompt before overwriting)
modular-builder generate --spec module-spec.yaml --output ./amplifier-module-tool-myfeature

# Force overwrite
modular-builder generate --spec module-spec.yaml --output ./amplifier-module-tool-myfeature --force

Merge Manually

# Generate to temp directory
modular-builder generate --spec module-spec.yaml --output ./temp-module

# Review changes
diff -r ./amplifier-module-tool-myfeature ./temp-module

# Merge manually
# Copy desired files from temp-module

Best Practices

1. Start with Simple Specs

# Start simple
name: myfeature
type: tool
description: Does one thing

functions:
  - name: do_thing
    # ...

2. Iterate on Generated Code

Don't try to get the spec perfect on first try. Generate, review, adjust.

3. Always Review

Generated code may have:

  • Missing error handling
  • Inefficient algorithms
  • Missing edge cases
  • Incomplete documentation

4. Write Tests

Generated test stubs are minimal. Add comprehensive tests.

5. Update README

Generated README is basic. Enhance with:

  • Real usage examples
  • Complete API documentation
  • Configuration details

Integration with Manual Development

Hybrid Workflow

  1. Generate scaffold with modular-builder
  2. Implement core logic manually
  3. Regenerate docs/tests with updated spec
  4. Merge manually

Using for Boilerplate Only

# Generate minimal boilerplate
modular-builder generate --spec minimal-spec.yaml --template minimal

# Then write all logic manually

Common Issues

Issue: Entry Points Not Registered

Problem: Module not found by amplifier

Solution: Check pyproject.toml:

[project.entry-points."amplifier.tools"]
myfeature = "amplifier_module_tool_myfeature:mount"

Issue: Import Errors

Problem: Cannot import module

Solution: Install in editable mode:

uv pip install -e .

Issue: Tests Fail

Problem: Generated tests don't match implementation

Solution: Review and update tests manually.

For complete examples, see EXAMPLES.md. For manual development, see DEVELOPMENT_WORKFLOW.md.