Tatami/README.md

# Tatami

**T**ool for **A**rranging **T**asty **A**ppointments, **M**eetings & **I**nvitations.

Tatami generates a **running dinner** masterplan. Given a list of participants with
home addresses, it forms small hosting groups, decides which groups cook which
course and who visits whom, and orders the whole evening to minimize travel time
(by bike, using the Google Maps Routes API), finishing at a shared after‑party.

- [What is a running dinner?](#what-is-a-running-dinner)
- [How Tatami builds the plan](#how-tatami-builds-the-plan)
- [Requirements](#requirements)
- [Setup](#setup)
- [Input: the participant CSV](#input-the-participant-csv)
- [Running it](#running-it)
- [Output format](#output-format)
- [What you can tweak](#what-you-can-tweak)
- [How the algorithm works](#how-the-algorithm-works)
- [Testing](#testing)
- [Limitations & scaling](#limitations--scaling)
- [Project layout](#project-layout)
- [Development](#development)

---

## What is a running dinner?

A running dinner is a social dinner event spread across many homes. Participants
are split into **hosting groups**. The evening has three courses — **starter,
main, dessert** — and each group cooks **exactly one** course in their own home.
For the other two courses they travel to other groups' homes as guests. The
tables are mixed for every course, so people meet many others over the night.
Everyone converges on a common **after‑party** location at the end.

Tatami arranges all of this and tries to keep the total cycling time low.

## How Tatami builds the plan

The pipeline (see the `__main__` block of `src/tatami/tatami_masterplan.py`):

1. **Load participants** from a tab‑separated CSV into `Participant` objects.
2. **Fetch travel times** — a full pairwise duration matrix between every
   participant address plus the after‑party address, via the Google Routes API.
3. **Build the masterplan**:
   - Rank participants by how convenient they are as hosts (kitchen‑size penalty
     plus distance to the after‑party), then split into **hosts** (one per group)
     and **semi‑hosts** (distributed into the host groups).
   - Reduce the full matrix to a host‑to‑host matrix and bake in each host's
     kitchen‑size penalty.
   - Run **simulated annealing** to find a low‑travel‑time assignment of groups
     to the dinner rotation.
   - Assign each group a course and compute who hosts whom for each course.
4. **Return** two lists of plain dicts (groups and participants) ready for
   serialization.

## Requirements

- **Python ≥ 3.13**
- **[uv](https://docs.astral.sh/uv/)** for dependency management
- A **Google Maps API key** with the **Routes API** enabled
  (the new `routes.googleapis.com` `computeRouteMatrix` endpoint — *not* the
  legacy Distance Matrix API).

## Setup

```bash
# 1. Install dependencies (creates the virtualenv from uv.lock)
uv sync

# 2. Provide your API key
cp .env.example .env
#   then edit .env and set GOOGLE_MAPS_API_KEY=...
```

The key is read from `.env` automatically (via `python-dotenv`). `.env` is
gitignored, so your secret never gets committed. An already‑exported
`GOOGLE_MAPS_API_KEY` environment variable takes precedence over the file.

> The package raises at import time if no key is found, so `GOOGLE_MAPS_API_KEY`
> must be set (even to a dummy value) just to import `tatami.traveltimes`.

Optionally, also set `GOOGLE_SHEETS_CREDENTIALS_FILE` in `.env` and a
`spreadsheet_id` in the saved `masterplan.json` to export the plan to a
shared Google Sheet — see [Sharing the plan with participants](#sharing-the-plan-with-participants).

## Input: the participant CSV

A **tab‑separated** file (the default working file is `test-config.csv` in the
directory you run from) with these columns:

| Column         | Type   | Meaning                                                              |
|----------------|--------|----------------------------------------------------------------------|
| `name`         | string | Participant / household name.                                        |
| `address`      | string | Full postal address — this is what the Routes API geocodes.          |
| `phone`        | string | Contact number (carried through to the output, not used in routing). |
| `kitchen_size` | number | `0–10`; a *suitability‑to‑host* proxy. Bigger = better kitchen.      |
| `allergies`    | string | Free text (carried through, not used in routing).                    |

Example (columns separated by **tabs**):

```
name	address	phone	kitchen_size	allergies
Alice	Römerstr. 12, 76189 Karlsruhe	555-1234	8	none
Bob	Gottesauerstr. 30, 76131 Karlsruhe	555-5678	7	peanuts
Charlie	Hermann-Hesse-Str 50, 76189 Karlsruhe	555-8765	9	none
```

## Running it

```bash
uv run python -m tatami.tatami_masterplan
```

The first run reads `test-config.csv` from the current directory, calls the
Routes API, computes the masterplan, and **saves it** to `masterplan.json`
(override the path with the `PLAN_FILE` env var). The after‑party address and
travel mode are currently set in the `__main__` block of
`tatami_masterplan.py` (see [What you can tweak](#what-you-can-tweak)).

Every subsequent run **loads `masterplan.json` instead of recomputing**, so
you can hand-edit that file — move a participant between groups, change a
course, fix an address, set `spreadsheet_id` — and rerun to pick up the edit
without calling the Routes API again. Delete (or move) the file to force a
fresh computation.

To use Tatami from your own code:

```python
from tatami.tatami_masterplan import (
    get_after_party_group, compute_masterplan_groups, load_csv_to_participants,
)
from tatami.traveltimes import get_participant_distance_matrix
from tatami.plan import Plan

participants = load_csv_to_participants("my-participants.csv")
after_party = get_after_party_group("Some Street 1, 12345 City")

distance_matrix = get_participant_distance_matrix(
    [*participants, after_party.main_member], mode="BICYCLE"
)
groups, participants_out = compute_masterplan_groups(
    participants, distance_matrix, after_party
)
plan = Plan(groups=groups, after_party_group=after_party)
plan.save("masterplan.json")
```

## Output format

The domain model (`Participant`, `Group`, `Plan` in `src/tatami/`) is built on
[pydantic](https://docs.pydantic.dev/), so everything supports
`model_dump()`/`model_dump_json()` plus `Plan.save(path)`/`Plan.load(path)`
for the full plan.

`get_masterplan` (a thin convenience wrapper around `compute_masterplan_groups`)
returns a tuple `(group_dicts, participant_dicts)`. Each **group** dict:

```python
{
    "uuid": "Group_…",            # group id
    "members": ["…", "…"],        # participant uuids in this group
    "main_member": "…",           # the participant whose home is used for routing
    "course": "starter",          # "starter" | "main" | "dessert"
    "hosts": ["…", "…", "…"],     # the three groups this group eats with,
                                   # ordered starter → main → dessert
                                   # (includes this group itself, for its own course)
}
```

Each **participant** dict mirrors the CSV columns plus a `uuid`. Everything is
keyed by UUID, so resolve names/addresses by looking participants up by `uuid`.

> Note: only a group's `main_member` address is used for all travel calculations;
> other members are assumed to join at the main member's home.

A `Group`'s `hosts` are *other* `Group`s, and these references can form
cycles (a group's hosts can also host that group back), so a `Plan`'s JSON
persists them as plain `host_uuids` id lists rather than embedding the full
objects — `Plan.load()` re-links the live `group.hosts` list from those ids
after loading, so `group.hosts[i].course` etc. works exactly as it does right
after computing the plan.

## Sharing the plan with participants

`Plan` (`src/tatami/plan.py`) bundles the computed `groups`, the
`after_party_group`, and the event-wide configuration below into one
object that feeds an optional Google Sheets export — the same kind of shared
spreadsheet organizers have used in previous years, just generated
automatically instead of by hand.

Set up once:

1. Create a Google Cloud service account and enable the **Google Sheets API**
   for its project.
2. Download the service account's JSON key and point
   `GOOGLE_SHEETS_CREDENTIALS_FILE` at it (in `.env`).
3. Create a blank Google Sheet, share it with the service account's
   `client_email` (from the JSON key) as **Editor**, copy its sheet ID, and
   set `spreadsheet_id` to that ID **in the saved `masterplan.json`** (not
   `.env` — the spreadsheet to export to is part of the plan itself, so it
   round-trips with everything else).

With `GOOGLE_SHEETS_CREDENTIALS_FILE` set and `spreadsheet_id` filled in,
rerunning `uv run python -m tatami.tatami_masterplan` populates that
spreadsheet with an **Overview** tab (every participant, their group, course,
address, phone, allergies — followed by a Meal Times table, a Support
Contacts table, and a free-text Info block, see below) and one tab per group
(their own course, route with addresses and fixed course times, and the
guest list — with allergies — for the course they host). Reruns are
idempotent: tabs are cleared and rewritten, and stale tabs from a previous
run are deleted.

Tatami never contacts participants directly — sharing the sheet's link is
still up to the organizer, exactly as before.

The three extra Overview sections are plain configuration, carried on the
`Plan` and passed straight through to the sheet with no logic in between —
set them when first building the plan, in `tatami_masterplan.py`:

```python
COURSE_TIMES = {
    "starter": "18:30", "main": "20:00", "dessert": "22:00", "after_party": "23:30",
}                                                   # -> "Meal Times" table
ORGANIZER_CONTACTS = [("Lars (Organizer)", "0151-23456789")]  # -> "Support Contacts" table
INFO_TEXT = "Welcome to the running dinner! ..."               # -> "Info" block (one row per line)
```

or by editing `course_times` / `organizer_contacts` / `info_text` directly in
the saved `masterplan.json` afterwards. `organizer_contacts` and `info_text`
are optional (`None`/empty skips that section); `course_times` is also reused
for each group's own route table.

If `spreadsheet_id` is unset, this step is skipped entirely and Tatami just
prints a reminder to fill it in.

## What you can tweak

All knobs currently live in the source. The most useful ones:

| What | Where | Default | Effect |
|------|-------|---------|--------|
| **Saved plan path** | `PLAN_FILE` env var | `masterplan.json` | Where the computed/edited `Plan` is saved to and (on the next run) loaded from. |
| **After‑party address** | `tatami_masterplan.py` (`__main__`) | a Karlsruhe address | Where everyone ends the night; also influences host ranking. Only used the first time a plan is computed. |
| **Travel mode** | `tatami_masterplan.py` (`mode="BICYCLE"`) | `BICYCLE` | Any Routes API `travelMode`: `BICYCLE`, `DRIVE`, `WALK`, `TWO_WHEELER`, `TRANSIT`. |
| **Course start times** | `tatami_masterplan.py` (`COURSE_TIMES`), or `course_times` in the saved plan | `18:30` / `20:00` / `22:00` / `23:30` | Fixed slot times written into the Google Sheet export; the dinner runs on a synchronized schedule, not travel-derived timing. |
| **Group sizing** | `tatami_masterplan.py:54` (`len(participants) / 6`) | 1 group per ~6 people | The divisor sets how many participants form one "course‑triple". Larger → fewer, bigger groups. |
| **Kitchen‑size penalty** | `classes.py` (`minutes=3 * (10 - kitchen_size)`) | 3 min per point | Travel‑time‑equivalent penalty for small kitchens. Raise the `3` to push hosting toward big kitchens. |
| **Annealing schedule** | `tatami_masterplan.py` (`run_simulated_annealing` call) | `T=1000`, `cooling=0.99`, `iters=10000` | Optimization quality vs. runtime. More iterations / slower cooling → better routes, slower. |
| **Course names** | `tatami_masterplan.py` (`courses = [...]`) | `["starter", "main", "dessert"]` | The three courses. The 3‑course rotation is baked into the topology — changing the *count* needs more work (see below). |
| **Rotation topology** | `tatami_masterplan.py` `get_courses` (offsets `+1`, `-4`) | — | Defines who hosts whom. Changing these changes who meets whom; keep the invariant that each group's three hosts cover all three courses. |
| **Distance vs. duration** | `traveltimes.py` `get_distance_matrix(value=…)` | `"duration"` | Optimize on travel **time** (`"duration"`) or **distance** (`"distanceMeters"`). |

After changing routing‑relevant knobs, run the test suite (`uv run pytest`) — the
topology and cost invariants are covered there.

## How the algorithm works

### Group building

`groups_per_course = floor(n / 6)` groups are created **per course**, for
`3 × groups_per_course` groups total. Participants are sorted by
`get_after_party_time` (kitchen penalty + distance to after‑party); the best
become the one **host** of each group, and the rest are shuffled in round‑robin
as **semi‑hosts**. A group's `main_member` (the host) is the only address used
for that group in all distance lookups.

### Rotation topology (`get_courses`)

Each group occupies a **slot** `0 … n‑1`. The course a slot cooks is `slot % 3`
(`0 → starter`, `1 → main`, `2 → dessert`). For slot `i`, the three groups it
dines with are slots `i` (itself, for its own course), `i + 1`, and `i − 4`
(mod `n`). These offsets are chosen so that:

- a group's three hosts always cover **all three** courses,
- **every** host serves **exactly three** groups (itself + two guests) for its
  course,
- guests are mixed differently at each course.

These invariants are verified in `tests/test_routing.py`.

### Route optimization (simulated annealing)

The decision variable is *which physical group sits in which slot*. For a given
assignment, `fast_total_time` sums every group's route
(starter‑host → main‑host → dessert‑host → after‑party) using the reduced,
penalty‑baked matrix. `simulated_annealing` starts from a random assignment and
repeatedly proposes swapping two slots, accepting worse solutions with Boltzmann
probability `exp(-Δ / T)` while the temperature `T` cools, and returns the best
assignment it finds. It is a **heuristic** — good, not provably optimal — though
on small instances it reliably reaches the true optimum.

## Testing

```bash
uv run pytest            # full offline suite (no API calls, HTTP is mocked)
uv run pytest -m e2e     # opt-in live test that calls the real Routes API
```

- The default suite (`tests/`) covers the domain model, group building, the
  rotation topology, the route cost/optimization, and the Routes API wrapper
  (with the HTTP layer mocked) — **no network, no API quota used**.
- `tests/test_e2e_api.py` is marked `e2e` and **excluded by default**. Run it
  explicitly with `-m e2e`. It makes a single minimal request (two addresses →
  a 2×2, 4‑element matrix) and **skips itself** if only a placeholder/dummy key
  is available, so it never spuriously fails.

## Limitations & scaling

- **Participant count.** The Routes API `computeRouteMatrix` caps at **625
  elements** (a 25×25 matrix), so Tatami currently handles up to ~**24
  participants** plus the after‑party in one shot. Bigger events need batching.
- **Group counts** are multiples of 3, and you need **≥ 6 participants** before
  any groups are formed at all.
- **Heuristic routing.** Simulated annealing does not guarantee the global
  optimum on large instances; tune the schedule if results look poor.
- **One address per group.** Only the host's (`main_member`'s) address is used
  for routing; guests are assumed to gather there.

## Project layout

```
src/tatami/
  classes.py            # Participant and Group domain model (pydantic)
  plan.py               # Plan: bundles groups + config, save()/load() to/from JSON
  traveltimes.py        # Google Routes API wrapper + matrix helpers
  sheets_export.py      # optional Google Sheets export for participants
  tatami_masterplan.py  # pipeline: load → fetch → group → optimize → assign
tests/                  # pytest suite (offline + opt-in live e2e)
running_dinner/         # legacy standalone prototype — NOT used by the package
```

> `running_dinner/running_dinner.py` is a pre‑package prototype kept for
> reference only. It uses German field names, a brute‑force search, and the
> **legacy** Distance Matrix API. Don't assume its conventions apply to
> `src/tatami/`.

## Development

This project uses `uv` and enforces quality with `ruff` and `mypy`.

```bash
uv sync                                  # install (incl. dev tools)
uv run ruff check                        # lint
uv run ruff format                       # format
uv run mypy --allow-redefinition src/    # type-check
uv run pre-commit install                # enable the pre-commit hooks
```

Pre‑commit runs `ruff check`, `ruff format`, and `mypy` automatically (see
`.pre-commit-config.yaml`).