# contessa - developer documentation

## Overview

Contessa is a recipe suggestion bot. It loads a JSON recipe file at startup
and serves random suggestions or full recipes on demand. There is no external
API, no database, and no persistent state beyond what is in memory.

---

## Module structure

```
contessa/
  commands.py   - all commands and recipe logic
  recipes.json  - bundled recipe data
  __init__.py   - empty
```

---

## Data loading

Recipes are loaded once in `setup()` and stored in `bot.memory["ct_recipes"]`.
The structure is a dict with meal-type keys mapping to lists of dish objects:

```json
{
  "breakfast": [{"name": "...", "description": "...", "ingredients": [...], "steps": [...]}],
  "lunch": [...],
  "dinner": [...],
  "snack": [...]
}
```

If the file is missing or malformed, `setup()` catches the exception and
initializes all categories to empty lists. The bot will respond with "no
recipes loaded" rather than crashing.

There is no hot-reload. A restart is required to pick up changes to the
recipe file.

---

## Recipe lookup

`_find_dish()` does two passes over all categories:
1. Exact name match (case-insensitive)
2. Substring match (case-insensitive)

This order matters. If someone has a dish named "Rice" and another named
"Rice Pudding", searching for "rice" returns "Rice" not "Rice Pudding". The
first exact match wins.

The function is a generator consumer over `_all_dishes()`, which yields
`(category, dish)` tuples from all categories. The double traversal (once
for exact, once for partial) is acceptable given that recipe sets are small.

---

## Output format

`_fmt_recipe()` returns three strings meant to be sent as three separate IRC
messages:
1. Name and description
2. Ingredients joined by comma
3. All steps joined into one line, numbered

The steps line can get long for recipes with many steps. IRC servers typically
truncate or drop messages over ~512 bytes. This is a known limitation. The
decision to keep steps on one line was made to minimize flood (three messages
per recipe is already pushing it in a shared channel).

---

## Channel requirement

All meal and recipe commands require channel context (`@plugin.require_chanmsg`).
The admin commands (join, part, chans, help) do not, since the owner needs to
manage the bot from PM.

---

## Config

| Key | Default | Description |
|-----|---------|-------------|
| `[contessa] recipes_path` | `/var/contessa/recipes.json` | Path to recipe JSON |

The bundled `recipes.json` contains 24 recipes per category (96 total) covering
Egyptian, Middle Eastern, and Western dishes. It is the default data file and
can be replaced or extended without code changes.