Skip to content

README.md

Latest commit

 

History

History
283 lines (232 loc) · 9.66 KB

README.md

File metadata and controls

283 lines (232 loc) · 9.66 KB

robot image

COMandA Examples

This directory contains various examples demonstrating different capabilities of COMandA. The examples are organized into categories based on their primary functionality.

Categories

Parallel Processing (parallel-processing/)

Examples demonstrating parallel execution of independent steps:

  • parallel-inference.yaml - Run multiple model inferences in parallel and compare results
  • parallel-model-comparison.yaml - Compare stories generated by different models in parallel
  • parallel-data-processing.yaml - Process the same data in different ways simultaneously
# Example of parallel processing structure
parallel-process:
  step_one:
    input:
      - NA
    model: gpt-4o
    action:
      - write a sonnet about network cables
    output:
      - examples/sonnet1.txt

  step_two:
    input:
      - NA
    model: claude-3-5-sonnet-latest
    action:
      - write a sonnet about network cables
    output:
      - examples/sonnet2.txt

step_three:
  input:
    - examples/sonnet1.txt
    - examples/sonnet2.txt
  model: gpt-4o-mini
  action:
    - compare these two sonnets and rate them
  output: STDOUT

Multi-Agent Collaboration (multi-agent/)

Examples demonstrating how to leverage Claude Code, Gemini CLI, and OpenAI Codex together:

  • architecture-planning.yaml - Parallel analysis with synthesis for comprehensive architecture design
  • architecture-review.yaml - Sequential refinement where each agent improves the previous work
  • architecture-decision.yaml - Voting/consensus pattern for specific architectural decisions
# Example: Parallel multi-agent analysis
parallel-process:
  claude-analysis:
    input: STDIN
    model: claude-code
    action: "Analyze system design aspects"
    output: $CLAUDE_RESULT

  gemini-analysis:
    input: STDIN
    model: gemini-cli
    action: "Analyze patterns and best practices"
    output: $GEMINI_RESULT

  codex-analysis:
    input: STDIN
    model: openai-codex
    action: "Analyze implementation structure"
    output: $CODEX_RESULT

synthesize:
  input: |
    Claude: $CLAUDE_RESULT
    Gemini: $GEMINI_RESULT
    Codex: $CODEX_RESULT
  model: claude-code
  action: "Synthesize into unified recommendation"
  output: STDOUT

Usage:

echo "Design a real-time collaborative editor" | comanda process multi-agent/architecture-planning.yaml

Server Examples (server-examples/)

Examples demonstrating server functionality and STDIN input:

  • stdin-example.yaml - Shows STDIN input usage with server POST requests

    # Can be processed via HTTP POST with input string
analyze_text:
  input: STDIN  # Makes YAML eligible for POST requests
  model: gpt-4o
  action: "Analyze the following text and provide key insights:"
  output: STDOUT

    Process via server:

    # Using query parameter
curl -X POST "http://localhost:8080/process?filename=server-examples/stdin-example.yaml&input=your text here"

# Using JSON body
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":"your text here"}' \
  "http://localhost:8080/process?filename=server-examples/stdin-example.yaml"

This server example also demonstrates how comanda can be used as part of a comand line data pipe:

cat text.txt|comanda process stdin-example.yaml

Database Connections (database-connections/)

Examples demonstrating database integration:

  • db-example.yaml - Database read/write operations
  • simpledb.sql - Sample database schema and data
  • Supporting files: Dockerfile for test environment

To start up the docker container for testing the database examples, run the following commands (after installing Docker)

cd examples/database-connections/postgres
docker build -t comanda-postgres .
docker run -d -p 5432:5432 comanda-postgres

Model Examples (model-examples/)

Examples demonstrating integration with different AI models:

  • openai-example.yaml - Basic OpenAI integration example
  • ollama-example.yaml - Using local Ollama models
  • anthropic-pdf-example.yaml - Using Anthropic's Claude model with PDF processing
  • google-example.yaml - Integration with Google's AI models
  • xai-example.yaml - X.AI model integration example

File Processing (file-processing/)

Examples of file manipulation and processing:

  • analyze-csv.yaml - Processing CSV data
  • batch-processing-example.yaml - Safely processing multiple files with error handling
  • consolidate-example.yaml - Combining multiple files
  • multi-file-example.yaml - Working with multiple files
  • wildcard-example.yaml - Using wildcard patterns to process multiple files
  • Supporting files: harvey1.txt, harvey2.txt, consolidated.txt, test.csv

Web Scraping (web-scraping/)

Examples of web interaction and scraping:

  • scrape-example.yaml - Web scraping functionality
  • url-example.yaml - Working with URLs
  • screenshot-example.yaml - Taking screenshots of web pages
  • scrape-file-example.yaml - File-based scraping configuration

Document Processing (document-processing/)

Examples of working with various document formats:

  • xml-example.yaml - XML file handling
  • google-xml-example.yaml - Google model XML processing
  • markdown-action-example.yaml - Markdown file processing
  • test-action.md - Example markdown action file
  • Supporting files: input.xml, output.xml, sample.pdf

Image Processing (image-processing/)

Examples of image-related operations:

  • image-example.yaml - Basic image processing capabilities
  • Supporting files: image.jpeg

Tool Use (tool-use/)

Examples demonstrating shell command execution within workflows:

  • tool-input-example.yaml - Use shell commands as step input (ls, find, date)
  • tool-output-example.yaml - Pipe step output through commands (jq, grep, awk)
  • beads-workflow-example.yaml - Integration with the bd (beads) issue tracker
  • beads-walkthrough.yaml - Walkthrough: spec analysis → issue preview
  • conveyor-belt-spec-to-beads.yaml - Full automation: spec → bd create execution
  • sample-spec.md - Sample technical spec for testing
# Example: Using tools in workflows
list_issues:
  input: "tool: bd list --json"
  model: NA
  action:
    - Pass through the JSON data
  output: STDOUT
  tool:
    allowlist: [bd]

# Example: Pipe output through jq
filter_json:
  input: data.json
  model: NA
  action:
    - Return the JSON
  output: "tool: jq '.items[] | select(.active)'"
  tool:
    allowlist: [jq]

Security: Tool execution is controlled by allowlist/denylist. Safe commands like ls, grep, jq, bd are allowed by default. Dangerous commands like rm, sudo, curl are blocked.

Running Examples

You can run any example using:

comanda process examples/[category]/[example-file].yaml

For instance:

comanda process examples/model-examples/openai-example.yaml

Each example includes comments explaining its functionality and any specific requirements (like API keys or local model setup).

Example Types

  1. Basic Examples: Start with these to understand core functionality

    • model-examples/openai-example.yaml
    • model-examples/ollama-example.yaml
    • server-examples/stdin-example.yaml (server POST integration)

  2. Advanced Examples: Demonstrate more complex features

    • file-processing/consolidate-example.yaml (multi-file processing)
    • web-scraping/screenshot-example.yaml (browser interaction)
    • document-processing/markdown-action-example.yaml (external action files)
    • database-connections/db-example.yaml (database operations)
    • parallel-processing/parallel-model-comparison.yaml (parallel execution)

  3. Integration Examples: Show provider-specific features

    • model-examples/anthropic-pdf-example.yaml (PDF processing)
    • model-examples/google-example.yaml (Google AI integration)
    • model-examples/xai-example.yaml (X.AI integration)

  4. Multi-Agent Examples: Combine multiple agentic coding tools

    • multi-agent/architecture-planning.yaml (parallel analysis + synthesis)
    • multi-agent/architecture-review.yaml (sequential refinement)
    • multi-agent/architecture-decision.yaml (voting/consensus ADRs)

  5. Data Examples: Demonstrate data processing capabilities

    • database-connections/postgres/db-example.yaml (database operations)
    • parallel-processing/parallel-data-processing.yaml (parallel data analysis)

  6. Server Examples: Show HTTP server functionality

    • server-examples/stdin-example.yaml (POST request with string input)
    # Check if YAML supports POST
curl "http://localhost:8080/list"

# Process with POST if supported
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":"analyze this text"}' \
  "http://localhost:8080/process?filename=server-examples/stdin-example.yaml"

  7. Tool Use Examples: Execute shell commands in workflows

    • tool-use/tool-input-example.yaml (use commands as input)
    • tool-use/tool-output-example.yaml (pipe output through commands)
    • tool-use/beads-workflow-example.yaml (integrate with external CLIs)
    • tool-use/beads-walkthrough.yaml (spec → issues workflow)

Test Environment

A Docker environment is provided for testing database operations:

cd examples/database-connections/postgres
docker build -t comanda-postgres .
docker run -d -p 5432:5432 comanda-postgres

This creates a PostgreSQL database with sample customer and order data.

Contributing

Feel free to add new examples! When contributing:

  1. Place your example in the appropriate category directory
  2. Include clear comments in your YAML file
  3. Update this README with a description of your example
  4. Include any necessary supporting files