# {{ project_name }}

Parallel ReactPlanner scaffold demonstrating fan-out and explicit join injection for concurrent tool execution.

## Quick Start

```bash
# Install dependencies
uv sync

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys

# Run the agent
uv run python -m {{ package_name }}
```

## Project Structure

```
{{ package_name }}/
├── orchestrator.py     # Main entry point with parallel execution
├── planner.py          # ReactPlanner with parallel_join_nodes
├── config.py           # Environment-driven settings
├── models.py           # Pydantic data models
├── tools/              # Agent tools
│   ├── fetch_a.py      # Parallel fetch tool A
│   ├── fetch_b.py      # Parallel fetch tool B
│   └── merge.py        # Join/merge tool
└── __main__.py         # CLI entry point
```

## Parallel Execution

This template demonstrates:

1. **Fan-out**: Multiple tools execute concurrently
2. **Join injection**: Results merge at a designated join node
3. **Budget management**: `absolute_max_parallel` limits concurrent tasks

Configure parallel behavior:

```python
planner = ReactPlanner(
    llm=config.llm_model,
    nodes=nodes,
    registry=registry,
    parallel_join_nodes={merge_results},  # Join point
    absolute_max_parallel=config.absolute_max_parallel,
)
```

## Configuration

Key settings (via environment or `config.py`):

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_MODEL` | `stub-llm` | LLM model identifier |
| `PLANNER_MAX_ITERS` | `10` | Maximum planning iterations |
| `PLANNER_HOP_BUDGET` | `6` | Maximum tool hops |
| `PLANNER_MULTI_ACTION_SEQUENTIAL` | `false` | Execute extra tool actions sequentially when multiple JSON actions appear |
| `PLANNER_MULTI_ACTION_READ_ONLY_ONLY` | `true` | Only auto-execute extra actions for read-only tools |
| `PLANNER_MULTI_ACTION_MAX_TOOLS` | `2` | Max extra tool actions to auto-execute per turn |
| `ABSOLUTE_MAX_PARALLEL` | `4` | Maximum concurrent tool calls |

## Use a Real LLM

1. Set your API key in `.env`:
   ```bash
   OPENAI_API_KEY=sk-...
   LLM_MODEL=gpt-4o
   ```

2. In `planner.py`, replace `ScriptedLLM` with:
   ```python
   planner = ReactPlanner(
       llm=config.llm_model,
       nodes=nodes,
       registry=registry,
       parallel_join_nodes={merge_results},
   )
   ```

## Testing

```bash
uv run pytest
```

## Learn More

- [PenguiFlow Documentation](https://github.com/yourorg/penguiflow)
- See `REACT_PLANNER_INTEGRATION_GUIDE.md` for parallel execution details
