# {{ project_name }}

Minimal PenguiFlow agent scaffold - the simplest starting point for building agents.

## 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
├── tools.py            # All tools in one file
├── config.py           # Environment-driven settings
├── models.py           # Pydantic data models
└── __main__.py         # CLI entry point
```

## Configuration

| 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 |

## Use a Real LLM

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

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

## Developing

1. Add tools in `src/{{ package_name }}/tools.py`
2. Define input/output models in `models.py`
3. Wire memory or observability as needed

## Testing

```bash
uv run pytest
```

## External Tools (MCP/UTCP)

Discover or preview ToolNode presets from the CLI:

```bash
penguiflow tools list                # show available presets
penguiflow tools connect github      # dry-run config preview
penguiflow tools connect github --discover --show-tools  # fetch tool names (needs penguiflow[planner])
```

## Learn More

- [PenguiFlow Documentation](https://github.com/yourorg/penguiflow)
- Consider the `react` template for more structured projects
