This directory contains comprehensive examples demonstrating various features and use cases of PromptKit. Each example is self-contained and includes configuration files, documentation, and any necessary code.

Example Categories

🤖 Arena Testing Examples

Examples demonstrating the PromptKit Arena testing framework for automated prompt evaluation and validation.

🔧 Integration Examples

Examples showing how to integrate PromptKit with external systems and tools.

🧠 Advanced Features

Examples showcasing advanced PromptKit capabilities like human-in-the-loop workflows, state management, and custom middleware.

Available Examples

1. assertions-test

Category: Arena Testing Purpose: Demonstrates how to write and use assertions for automated prompt testing

2. context-management

Category: Integration Purpose: Shows context management and conversation state handling

3. customer-support

Category: Arena Testing Purpose: Complete customer support chatbot example with arena testing

4. customer-support-integrated

Category: Integration Purpose: Integrated customer support system with external tool calls

5. hitl-approval ⭐

Category: Advanced Features Purpose: Human-in-the-loop workflow for high-value operations

6. mcp-chatbot

Category: Integration Purpose: Model Context Protocol (MCP) integration for chatbots

7. mcp-filesystem-test ⭐

Category: Integration Purpose: MCP integration with filesystem operations

8. mcp-memory-test ⭐

Category: Integration Purpose: MCP integration with memory/storage systems

9. phase2-demo ⭐

Category: Advanced Features Purpose: Comprehensive demonstration of PromptKit Phase 2 capabilities

10. statestore-example

Category: Advanced Features Purpose: State store configuration and usage patterns

11. variables-demo ⭐

Category: Arena Testing Purpose: Comprehensive guide to using variables in promptconfigs

Getting Started

Running Arena Examples

Most examples include an arena.yaml file for testing with the PromptKit Arena:

# Navigate to any arena example
cd examples/customer-support

# Run arena testing
promptarena run

# Inspect configuration
promptarena config inspect

# Generate reports
promptarena render

Running Go Examples

Examples with Go code can be built and executed directly:

# Navigate to a Go example
cd examples/hitl-approval

# Build the example
go build

# Run the example
./hitl-approval

Understanding Configuration Files

File Naming Conventions

PromptKit uses typed file extensions for better IDE integration and discoverability:

TypeFile PatternExample
Arenaconfig.arena.yamlconfig.arena.yaml
Provider*.provider.yamlopenai-gpt4.provider.yaml
Scenario*.scenario.yamlsupport-ticket.scenario.yaml
Tool*.tool.yamlsearch.tool.yaml
Persona*.persona.yamlcurious-customer.persona.yaml
PromptConfig*.prompt.yamlassistant.prompt.yaml

Benefits:

config.arena.yaml

Main Arena configuration file defining:

Schema URL: https://promptkit.altairalabs.ai/schemas/latest/arena.json

Provider Files (providers/*.provider.yaml)

Individual provider configurations:

Schema URL: https://promptkit.altairalabs.ai/schemas/latest/provider.json

Scenario Files (scenarios/*.scenario.yaml)

Test scenario definitions:

Schema URL: https://promptkit.altairalabs.ai/schemas/latest/scenario.json

Prompt Files (prompts/*.prompt.yaml)

Prompt configurations and templates:

Schema URL: https://promptkit.altairalabs.ai/schemas/latest/promptconfig.json

Adding Schema Validation

Add $schema at the top of any config file for IDE support:

$schema: https://promptkit.altairalabs.ai/schemas/latest/arena.json
apiVersion: promptkit.altairalabs.ai/v1alpha1
kind: Arena
metadata:
  name: my-arena
spec:
  # ... configuration

This enables:

Example Patterns

Basic Arena Testing

  1. Configure providers in providers/
  2. Define prompts in prompts/ with variables array (required and optional)
  3. Set up scenarios in scenarios/
  4. Configure arena in arena.yaml and override variables as needed
  5. Run tests with promptarena run

Working with Variables

  1. Define variables array in your promptconfig with type, required status, and defaults
  2. Set required: true for values that must be provided
  3. Set required: false with default value for optional variables
  4. Use {{variable_name}} syntax in system_template
  5. Override variables in arena.yaml under prompt_configs[].vars
  6. Test different configurations with scenarios
  7. See variables-demo/ for complete examples

Integration Development

  1. Implement integration logic in Go
  2. Configure MCP servers if needed
  3. Set up workspace in go.work
  4. Build and test integration
  5. Document usage patterns

Advanced Workflows

  1. Design custom middleware
  2. Implement HITL patterns
  3. Configure state management
  4. Set up async processing
  5. Test with arena framework

Best Practices

Configuration Management

Testing Strategy

Code Organization

Troubleshooting

Common Issues

Import Path Errors

Arena Configuration Errors

Build Failures

Getting Help

Contributing

When adding new examples:

  1. Create descriptive directory names
  2. Include comprehensive README.md
  3. Add arena.yaml for testable examples
  4. Update this main README
  5. Test all configurations work
  6. Document any special requirements

Example Template Structure

new-example/
├── README.md              # Detailed example documentation
├── arena.yaml            # Arena configuration (if applicable)
├── go.mod               # Go module (if Go code)
├── main.go              # Main implementation (if Go code)
├── prompts/             # Prompt configurations
├── providers/           # Provider configurations
├── scenarios/           # Test scenarios
└── tools/              # Tool configurations (if applicable)

This examples collection demonstrates the full power and flexibility of PromptKit across various use cases, from simple prompt testing to complex multi-system integrations.