Components - Ensemble Edge

Overview

Components are reusable artifacts that can be versioned, shared, and referenced across your ensembles. They’re managed by edgit, Ensemble’s version control system for AI artifacts.

Component Types

Conductor supports seven types of components:

Component	File Type	Purpose	Example Reference
Schemas	`.json`	JSON Schema for structured AI outputs	`schemas/invoice@v1`
Prompts	`.md`	AI instruction templates	`prompts/summarizer@latest`
Configs	`.json`, `.yaml`	Reusable configuration	`configs/db-prod@stable`
Queries	`.sql`	Database query templates	`queries/analytics@v2`
Scripts	`.js`, `.ts`	JavaScript/TypeScript functions	`scripts/validators@v1`
Templates	`.html`	HTML templates for rendering	`templates/layouts/main@v1`
Docs	`.md`	Markdown documentation with Handlebars	`docs/getting-started@v1`

Why Use Components?

Version Control

# Lock to specific version
schema: schemas/invoice@v1.2.3

# Use latest stable
prompt: prompts/summarizer@production

# Follow major version
config: configs/api@v2

Reusability

Define once, use everywhere:

# ensemble-1.yaml
agents:
  - name: extract
    operation: think
    config:
      schema: schemas/contact@v1
      prompt: prompts/extractor@v1

# ensemble-2.yaml
agents:
  - name: validate
    operation: think
    config:
      schema: schemas/contact@v1  # Same schema

Team Collaboration

Share components across teams
Review changes before deployment
Roll back to previous versions
A/B test different versions

Gradual Rollouts

# Start with canary
edgit tag set summarizer canary v2.0.0

# Promote to production
edgit tag set summarizer production v2.0.0

Component References

Versioned Reference

Reference a specific version:

schema: schemas/invoice@v1.2.3
prompt: prompts/summarizer@v2.0.0
config: configs/database@v1.5.2
query: queries/analytics@v3.1.0
script: scripts/validator@v2.0.0
template: templates/layouts/main@v1.0.0
docs: docs/getting-started@v1.0.0

Tag Reference

Reference by tag:

schema: schemas/invoice@production
prompt: prompts/summarizer@stable
config: configs/database@canary
template: templates/layouts/main@production
docs: docs/api-guide@production

Major Version Reference

Auto-upgrade to latest patch/minor:

schema: schemas/invoice@v1       # Gets latest v1.x.x
prompt: prompts/summarizer@v2    # Gets latest v2.x.x
template: templates/layouts/main@v1  # Gets latest v1.x.x
docs: docs/getting-started@v1    # Gets latest v1.x.x

Latest Reference

Always use the latest version:

schema: schemas/invoice@latest
prompt: prompts/summarizer@latest
template: templates/layouts/main@latest
docs: docs/getting-started@latest

Shorthand (defaults to @latest)

schema: schemas/invoice
prompt: prompts/summarizer
template: templates/layouts/main
docs: docs/getting-started

Component Organization

Organize components in your project:

my-project/
├── schemas/
│   ├── invoice.json
│   ├── contact.json
│   └── sentiment.json
├── prompts/
│   ├── summarizer.md
│   ├── extractor.md
│   └── classifier.md
├── configs/
│   ├── database.yaml
│   ├── api-keys.json
│   └── rate-limits.yaml
├── queries/
│   ├── analytics.sql
│   ├── reports.sql
│   └── cleanup.sql
├── scripts/
│   ├── validators.ts
│   ├── transformers.js
│   └── formatters.ts
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── api-guide.md

Versioning Components

Initialize Component

# Version a component
edgit tag create invoice v1.0.0

# Version with message
edgit tag create summarizer v1.0.0 -m "Initial release"

Semantic Versioning

Follow semver for clear version meanings:

Major (v2.0.0): Breaking changes
Minor (v1.1.0): New features, backwards compatible
Patch (v1.0.1): Bug fixes, no new features

# Bug fix
edgit tag create invoice v1.0.1

# New optional field
edgit tag create invoice v1.1.0

# Breaking change to schema structure
edgit tag create invoice v2.0.0

Tagging

Tag versions for deployment stages:

# Tag for canary testing
edgit tag set invoice canary v2.0.0

# Promote to staging
edgit tag set invoice staging v2.0.0

# Promote to production
edgit tag set invoice production v2.0.0

View Versions

# List all versions
edgit tag list invoice

# Show version details
edgit tag show invoice@v1.2.3

A/B Testing Components

Test different component versions:

name: ab-test-prompts

agents:
  - name: summarize-a
    operation: think
    config:
      prompt: prompts/summarizer@v1  # Control
      percentage: 50

  - name: summarize-b
    operation: think
    config:
      prompt: prompts/summarizer@v2  # Treatment
      percentage: 50

See A/B Testing for more patterns.

Component Types Deep Dive

Schemas

JSON Schema definitions for structured AI outputs.

Use for: Extracting structured data from AI
Docs: Schema Components

Prompts

Markdown files with AI instructions and templates.

Use for: Reusable AI prompts with variable interpolation
Docs: Prompt Components

Configs

JSON/YAML configuration files.

Use for: Database configs, API settings, feature flags
Docs: Config Components

Queries

SQL query templates.

Use for: Reusable database queries with parameters
Docs: Query Components

Scripts

JavaScript/TypeScript functions.

Use for: Custom validators, transformers, utilities
Docs: Script Components

Docs

Markdown documentation with Handlebars template support.

Use for: User guides, tutorials, API documentation
Docs: Docs Components

Best Practices

1. Version Early and Often

# Version from the start
edgit tag create new-feature v0.1.0

2. Use Semantic Versioning

# Clear version progression
v1.0.0 → v1.0.1 (fix) → v1.1.0 (feature) → v2.0.0 (breaking)

3. Tag Production Versions

# Development
prompt: prompts/summarizer@latest

# Production
prompt: prompts/summarizer@production

4. Document Breaking Changes

edgit tag create invoice v2.0.0 -m "BREAKING: Renamed 'total' to 'amount'"

5. Test Before Promoting

# Test in canary
edgit tag set contact canary v2.0.0

# If successful, promote
edgit tag set contact production v2.0.0

6. Lock Production to Versions

# ❌ Bad: production using @latest
schema: schemas/invoice@latest

# ✅ Good: production locked to tag
schema: schemas/invoice@production

# ✅ Better: production locked to specific version
schema: schemas/invoice@v1.2.3

Next Steps

Schemas

JSON Schema for structured outputs

Prompts

Reusable AI instruction templates

Configs

Configuration management

Queries

SQL query templates

Scripts

Reusable JavaScript/TypeScript

Docs

Markdown documentation components

Edgit

Version control system

​Overview

​Component Types

​Why Use Components?

​Version Control

​Reusability

​Team Collaboration

​Gradual Rollouts

​Component References

​Versioned Reference

​Tag Reference

​Major Version Reference

​Latest Reference

​Shorthand (defaults to @latest)

​Component Organization

​Versioning Components

​Initialize Component

​Semantic Versioning

​Tagging

​View Versions

​A/B Testing Components

​Component Types Deep Dive

​Schemas

​Prompts

​Configs

​Queries

​Scripts

​Docs

​Best Practices

​1. Version Early and Often

​2. Use Semantic Versioning

​3. Tag Production Versions

​4. Document Breaking Changes

​5. Test Before Promoting

​6. Lock Production to Versions

​Next Steps

Schemas

Prompts

Configs

Queries

Scripts

Docs

Edgit

Overview

Component Types

Why Use Components?

Version Control

Reusability

Team Collaboration

Gradual Rollouts

Component References

Versioned Reference

Tag Reference

Major Version Reference

Latest Reference

Shorthand (defaults to @latest)

Component Organization

Versioning Components

Initialize Component

Semantic Versioning

Tagging

View Versions

A/B Testing Components

Component Types Deep Dive

Schemas

Prompts

Configs

Queries

Scripts

Docs

Best Practices

1. Version Early and Often

2. Use Semantic Versioning

3. Tag Production Versions

4. Document Breaking Changes

5. Test Before Promoting

6. Lock Production to Versions

Next Steps