recipe-tool 0.1.3

A tool for executing natural language recipe-like instructions

Recipe Tool

Transform natural language ideas into reliable, automated workflows - Recipe Tool bridges the gap between human intent and executable automation. Write what you want to accomplish in plain English, and Recipe Tool generates the JSON recipe that makes it happen - reproducibly and reliably.

What is Recipe Tool?

Recipe Tool is a command-line interface that combines recipe creation with recipe execution, turning natural language descriptions into automated workflows. Think of it as a compiler that translates your ideas into reliable, repeatable automation.

Key Capabilities:

• 🧠 Natural Language to Code - Describe your workflow in plain English/Markdown
• 🔄 Reliable Execution - Generated recipes run deterministically every time
• 🤖 Multi-LLM Support - Works with OpenAI, Anthropic, Azure OpenAI, Ollama
• 🛠️ Rich Step Types - File operations, conditionals, loops, parallel execution
• 🔗 Tool Integration - MCP (Model Context Protocol) server support
• 📊 Structured Output - Generate JSON, code, documents, reports

The Recipe Tool Workflow

Recipe Tool follows a simple but powerful workflow:

1. Write Your Idea

Start with a natural language description of what you want to accomplish:

# Code Quality Analyzer

Read all Python files in the project and:

1. Count lines of code per file
2. Identify files with no docstrings
3. Check for TODO/FIXME comments
4. Create a comprehensive report with recommendations

2. Generate a Recipe

Transform your idea into an executable JSON recipe:

recipe-tool --create code_analyzer_idea.md
# Creates: output/code_quality_analyzer.json

3. Execute Reliably

Run your recipe with consistent, reproducible results:

recipe-tool --execute output/code_quality_analyzer.json project_path=./my-project

Installation

pip install recipe-tool

Note: Recipe Tool automatically installs recipe-executor as a dependency, giving you both creation and execution capabilities.

Quick Start

Basic Usage

1. Create a simple idea file (hello_world.md):

# Hello World Generator

Create a Python script that prints "Hello, World!" and save it to a file.

2. Generate the recipe:

recipe-tool --create hello_world.md

3. Execute the generated recipe:

recipe-tool --execute output/hello_world_generator.json

Environment Setup

Configure your LLM provider:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# Azure OpenAI
export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_BASE_URL="https://your-resource.openai.azure.com/"

What Gets Generated

When you describe a task, Recipe Tool creates a JSON recipe with structured steps. Here's what gets generated for a file summarization task:

Your Idea:

# File Summarizer
Read a text file and create a summary of its contents.

Generated Recipe:

{
  "name": "file_summarizer",
  "steps": [
    {
      "step_type": "read_files",
      "paths": ["{{ input_file }}"]
    },
    {
      "step_type": "llm_generate",
      "prompt": "Create a concise summary of this content:\n\n{{ file_contents[0] }}",
      "model": "gpt-4o"
    },
    {
      "step_type": "write_files",
      "files": [
        {
          "path": "{{ output_file }}",
          "content": "# Summary\n\n{{ llm_output }}"
        }
      ]
    }
  ]
}

Advanced Examples

Multi-Step Document Processing

# Research Report Generator

1. Read a list of URLs from a file
2. Fetch content from each URL
3. Generate summaries for each source
4. Combine summaries into a comprehensive report
5. Format as markdown with citations

recipe-tool --create research_report.md
recipe-tool --execute output/research_report_generator.json \
  urls_file=sources.txt output_file=research_report.md

Code Generation from Specifications

# API Client Generator

Given an API specification file:
1. Parse the API endpoints and schemas
2. Generate Python client code with proper error handling
3. Create unit tests for the client
4. Generate documentation with usage examples

recipe-tool --create api_client_generator.md
recipe-tool --execute output/api_client_generator.json \
  spec_file=api_spec.yaml output_dir=generated_client/

Batch File Processing

# Image Processing Pipeline

For all images in a directory:
1. Resize to multiple dimensions (thumbnail, medium, large)
2. Optimize file sizes
3. Generate metadata JSON files
4. Create an index HTML file with image gallery

recipe-tool --create image_processor.md
recipe-tool --execute output/image_processing_pipeline.json \
  input_dir=raw_images/ output_dir=processed/

CLI Reference

Core Commands

# Create a recipe from natural language
recipe-tool --create IDEA_FILE

# Execute an existing recipe
recipe-tool --execute RECIPE_FILE [CONTEXT_VARS...]

# Show help
recipe-tool --help

Options

--log-dir DIR           Directory for log files (default: logs)
--debug                 Enable debug mode with breakpoints

Context Variables

Pass variables to recipes:

recipe-tool --execute recipe.json \
  input_file=data.txt \
  output_dir=results/ \
  model=gpt-4o \
  temperature=0.3

Recipe Ecosystem

Recipe Tool is part of a larger ecosystem:

• recipe-executor - Core execution engine (auto-installed)
• recipe-tool - This package - adds creation capabilities
• recipe-tool-app - Web interface for visual recipe management
• MCP servers - Integration with AI assistants like Claude

Web Interface

For a visual experience, install and run the web interface:

# Install the web app (separate package)
pip install recipe-tool-app

# Launch the interface
recipe-tool-app

Features:

• Visual recipe creation and editing
• Real-time execution with step-by-step output
• Example recipe browser
• Context variable management
• File upload and download

Integration with AI Assistants

Recipe Tool provides MCP (Model Context Protocol) integration for AI assistants:

# For Claude Desktop
recipe-tool-mcp-server stdio

# For HTTP clients
recipe-tool-mcp-server sse --port 3002

This allows AI assistants to:

• Create recipes from your conversations
• Execute workflows on your behalf
• Iterate on recipes based on results

Use Cases

Recipe Tool excels at:

📝 Content Generation

• Blog posts, documentation, reports
• Code generation from specifications
• Template-based content creation

🔧 Automation Workflows

• File processing and transformation
• API integration and data collection
• Batch operations and data migration

🧪 Research & Analysis

• Data analysis and visualization
• Web scraping and content aggregation
• Competitive analysis and reporting

💻 Development Tasks

• Code generation and scaffolding
• Test data creation
• Documentation generation

Philosophy: More Code Than Model

Recipe Tool follows a "more code than model" philosophy:

• LLM for Creation - Use AI to generate the recipe from your idea
• Deterministic Execution - Run the recipe with consistent, reliable results
• Reproducible Workflows - Same inputs always produce same outputs
• Version Control Ready - Recipes are JSON files that can be tracked and shared

This approach gives you the creativity and accessibility of AI with the reliability and reproducibility of traditional automation.

Python API

Use Recipe Tool programmatically:

from recipe_tool.app import create_recipe, execute_recipe

# Create a recipe from text
recipe_json = await create_recipe(
    idea="Generate a Python class for user management",
    reference_files=["user_model.py"]
)

# Execute the recipe
result = await execute_recipe(
    recipe_json,
    context={"class_name": "UserManager"}
)

Error Handling

Recipe Tool provides comprehensive error handling:

• Creation Errors - Clear feedback on malformed ideas or missing context
• Execution Errors - Step-by-step error reporting with context
• Validation - Recipe validation before execution
• Logging - Detailed logs for debugging and audit trails

Part of Recipe Tool Ecosystem

Recipe Tool is part of the larger Recipe Tool Project:

• Full Documentation - Comprehensive guides and examples
• Example Recipes - Pre-built recipes for common tasks
• Community Recipes - Shared recipes and patterns
• Advanced Features - Self-generating code, parallel execution, MCP integration

For advanced usage, complex examples, and the full ecosystem, visit the Recipe Tool repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

This is an experimental project from Microsoft. For issues and examples:

• GitHub Repository
• Example Recipes
• Documentation
• Web Interface (separate package)