Recipe Executor

A tool for executing recipe-like natural language instructions to generate and manipulate code and other files.

Overview

The Recipe Executor is a flexible orchestration system that executes "recipes" - JSON-based definitions of sequential steps to perform tasks such as file reading, LLM-based content generation, and file writing. This project allows you to define complex workflows through simple recipe files.

Key Components

• Recipe Format: JSON-based recipe definitions with steps
• Step Types: Various operations including file reading/writing, LLM generation, and sub-recipe execution
• Context System: Shared state for passing data between steps
• Template Rendering: Liquid templates for dynamic content generation

Setup and Installation

Prerequisites

Recommended installers:

• Linux: apt or your distribution's package manager
• macOS: brew
• Windows: winget

Development tools

The core dependencies you need to install are:

• make - for scripting installation steps of the various projects within this repo
• uv - for managing installed versions of python - for installing python dependencies

Linux:

# make is installed by default on linux
sudo apt update && sudo apt install pipx
pipx ensurepath
pipx install uv

macOS:

brew install make
brew install uv

Windows:

winget install ezwinports.make -e
winget install astral-sh.uv  -e

Setup Steps

1. Clone this repository
2. Copy the environment file and configure your API keys:

   cp .env.example .env
   # Edit .env to add your OPENAI_API_KEY and other optional API keys

3. Run the setup command to create a virtual environment and install dependencies:

   make

4. Activate the virtual environment:
   • Linux/macOS:

     source venv/bin/activate

   • Windows:

     .\venv\Scripts\activate

5. Test the installation by running the example recipe:

   make recipe-executor-create

Using the Makefile

The project includes several useful make commands:

• make: Sets up the virtual environment and installs all dependencies
• make recipe-executor-context: Builds AI context files for recipe executor development
• make recipe-executor-create: Generates recipe executor code from scratch using the recipe itself
• make recipe-executor-edit: Revises existing recipe executor code using recipes

Running Recipes

Execute a recipe using the command line interface:

python recipe_executor/main.py path/to/your/recipe.json

You can also pass context variables:

python recipe_executor/main.py path/to/your/recipe.json --context key=value

Project Structure

The project contains:

• recipe_executor/: Core implementation with modules for execution, context management, and steps
• recipes/: Recipe definition files that can be executed

Building from Recipes

One of the most interesting aspects of this project is that it can generate its own code using recipes:

1. To generate the code from scratch:

   make recipe-executor-create

2. To edit/revise existing code:

   make recipe-executor-edit

This demonstrates the power of the Recipe Executor for code generation and maintenance tasks.

Contributing & Development

We have a doc just for that... dev_guidance.md