# create-leafmesh

Project scaffolding tool for [LeafMesh](https://pypi.org/project/leafmesh/) — the YAML-native multi-agent orchestration platform.

## Install

```bash
pip install create-leafmesh
```

## Create a Project

```bash
create-leafmesh create my-project
cd my-project
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py
```

## CLI Options

```bash
# Create in a specific directory
create-leafmesh create my-project -o /path/to/dir

# Skip git initialization
create-leafmesh create my-project --no-git

# Interactive mode (prompts for project name)
create-leafmesh create
```

## Generated Project Structure

```
my-project/
  configs/
    config.yaml              # Agent definitions, mesh wiring, HITL config
  agency/
    greeter_agent.py         # LLM agent with @pre_compose
    processor_agent.py       # Programmatic agent with @conditional_chain
    researcher_agent.py      # LLM agent with @chain_with_results + smart memory
    fallback_researcher_agent.py  # Fast fallback (race pattern)
    advisor_agent.py         # LLM fan-in with @chain + @compose
    scheduler_agent.py       # Cron-scheduled agent
    tools.py                 # Custom tools (@global_tool, @tool)
    external_agents.py       # Integration reference (CrewAI, LangGraph, etc.)
  main.py                    # Entry point
  hitl_stub_receiver.py      # Webhook stub for testing HITL locally
  requirements.txt
  .env                       # API keys
  Dockerfile
  docker-compose.yml         # Redis + app
```

## What's Included

- **8 agents** showcasing all 4 agent types (human, llm, programmatic, external)
- **Human-in-the-Loop (HITL)** with dual webhook mode and `from_agent` routing
- **Fan-in/fan-out** with OR expressions (`processor AND (researcher OR fallback)`)
- **Smart memory** with hybrid recency/relevance scoring
- **Scheduled agents** with cron expressions
- **Custom tools** with access control and categories
- **All 5 decorators**: `@pre_compose`, `@chain`, `@chain_with_results`, `@conditional_chain`, `@compose`
- **HITL test stub** (`hitl_stub_receiver.py`) for local webhook testing
- **Docker-ready** with Redis included
- **Full README** with HITL walkthrough (2 scenarios, step-by-step)

## Requirements

- Python 3.10+
- Redis server running (default: localhost:6379)
- At least one LLM API key (e.g. `OPENAI_API_KEY` in `.env`)

## Links

- [LeafMesh SDK](https://pypi.org/project/leafmesh/)
- [LeafCraft Studios](https://leafcraft.ai)

## License

MIT
