Documentation

Everything you need to import a guest list, describe the constraints that matter, run the optimizer and export the result. The machine-readable version of this page is published at /api/v1/csv-schema.json and /openapi.json.

Guests CSV

The guests file requires three columns — name, party_size and groups. Header matching is case-insensitive and surrounding whitespace is ignored. A row is one booking, not one person: party_size is how many chairs that entry needs, so a couple is a single row with a party size of two. A party size of zero marks the entry inactive, which is a convenient way to keep a declined invitation in the file without seating it. At most 1,000 guest rows and 10 MB are accepted.

name,party_size,groups
John Smith,2,Friends>College
Jane Doe,4,Family>Cousins
Bob Wilson,1,"Work,Friends"
Declined Guest,0,Family

Groups and hierarchy

The groups cell is a comma-separated list of group paths, which is why a cell naming more than one group has to be quoted. A path uses > to nest a subgroup inside a parent — Family>Cousins places the guest in Family and in Family > Cousins. For right-to-left guest lists, < is accepted as the same separator. Groups are identified by their full path, so two different Cousins groups under different parents stay distinct. Each level is created with a default cohesion strength that rises with depth (3 at the top level, capped at 10), and every strength can be edited in the interface afterwards.

Tables CSV

The tables file requires id and capacity, and optionally accepts x and y coordinates that place the table in the venue view. Capacity must be a positive integer. Coordinates are plain numbers in the venue's own coordinate space; leave them blank and the table is positioned for you. At most 100 tables are accepted.

id,capacity,x,y
T1,8,100,100
T2,10,200,100
Bar,4,,

Seating preferences and locks

A seating preference points one guest at a target: a specific table, an area of the venue, or another guest. Preferences are soft — the optimizer pays a penalty proportional to how far the final placement lands from the requested target rather than refusing to seat anyone. A lock is hard: a locked guest stays on the table you chose and the optimizer rearranges everyone else around that decision. Locks are the right tool for seats you have already promised; preferences are the right tool for everything else.

What the optimizer minimizes

The reported penalty is the sum of three terms, each scaled by 1000 and truncated to an integer so figures stay comparable between runs:

  • Group cohesion, weight 10 — strength × √members for every extra table a group is split across, with a credit back when a subgroup sits with its parent group.
  • Seating preferences, weight 1 — scaled by the guest's strongest group and by the normalized distance between the two tables, or from the table to the area rectangle.
  • Table usage, weight 0.5 — charged per table used, so the venue prefers fewer, fuller tables.

The search constructs a good arrangement greedily and improves it with simulated annealing over relocate, swap, ejection-chain and group-move neighbourhoods. Intermediate candidates may pass through over-capacity states under a penalty, because in a tightly packed venue the capacity-feasible neighbourhood can be disconnected — but only capacity-feasible arrangements are ever shown or exported.

Export format

Exporting produces one row per table with the columns Table,Guests,Taken,Capacity. Guests are joined with a comma inside a single quoted cell, and Taken counts entries seated at the table.

Table,Guests,Taken,Capacity
T1,"John Smith, Jane Doe",2,8
T2,"Bob Wilson",1,10

Try it with sample data

/en/?demo=1 opens the optimizer pre-loaded with the example guest list and table layout below, so you can watch a real optimization run before importing anything of your own. It seeds an empty workspace only, so it will not overwrite work in progress.

Sample files and machine-readable schemas

The developer portal explains how to call those endpoints, and the llms.txt file tells an agent when reaching for this tool is the right move.