Gaur Docs

A 250-word description of a Jaffle table, what Gaur generates from it, and what an agent actually reads.

Use case

raw_customers has two columns: id and name. Schema alone can't tell an agent that name is non-unique, that customers without orders are excluded, that customer behaviour is persona-driven, or that "home store" has to be derived. Without that context, the answer to "how many unique customers ordered last month" comes back as COUNT(DISTINCT name) (wrong; names collide).

Context fills that gap.

Data modeling

The description you'd hand to Gaur for raw_customers. Short on purpose; every paragraph disambiguates a column, declares an invariant, or names a gotcha:

business_context/raw_customers.md

One known customer of Jaffle Shop: a person who has placed at least one
order in the dataset's 2-year window. Dimension table. Customers are
deduplicated; the same person never appears twice. Customers who never
ordered are excluded by construction (the table is materialized from
the order stream).

Columns:
- `id`: customer UUID, primary key.
- `name`: full name string. Synthetic / Faker-generated, not real PII,
  safe to display in demos.

Business terminology:
- Customer, guest, patron: synonyms.
- Regular: high-frequency repeat customer (no formal definition; usually
  top decile by order count).
- Cohort: customers grouped by first-order month, used for retention.
- Home store: the store whose market a customer belongs to. Most of a
  customer's orders occur there.

Rules and gotchas:
- `name` is NOT unique. Random collisions occur. Always identify
  customers by `id`, never by `name`.
- No email, phone, address, age, gender, or other PII. Don't try to
  join or aggregate by columns that aren't there.
- No `first_order_at` / `last_order_at` column. Derive from `raw_orders`.
- Customer's "home store" is not stored. Derive as
  `mode(store_id)` from their orders.
- Customers near the window boundaries are partially observed; be
  cautious with LTV near the edges.

Common queries:
- Total known customers: `SELECT COUNT(*) FROM raw_customers`.
- New customers per month: derive from `raw_orders.ordered_at` MIN per
  customer.
- Orders-per-customer distribution: `SELECT customer, COUNT(*) FROM raw_orders`.

What Gaur generates from it

Two structured sections: Object Info (auto-derived from the schema, with your field descriptions slotted in) and Business Context (the prose, indexed under recognized headings).

## Object Info
- Identity: raw_customers, table, primary key id
- Fields:
  | Name | Type | Role        | Description                              |
  |------|------|-------------|------------------------------------------|
  | id   | UUID | identifier  | Customer UUID, primary key.              |
  | name | str  | attribute   | Full name string. Synthetic / Faker.     |

## Business Context

### Terms
- Customer = guest = patron
- Regular: heavy repeat customer (top decile)
- Cohort: first-order-month grouping
- Home store: mode store_id for the customer

### Rules
- name is NOT unique; identify by id
- No PII columns; nothing to join on beyond id and name
- Derive first_order_at from raw_orders
- Derive home store as mode(store_id)
- Partial observation near window edges

### Use Cases
- Total known customers
- New customers per month
- Orders-per-customer distribution

What an agent sees

When an agent considers raw_customers, it gets the two sections above. Headings inside Business Context have to match the recognized set (Terms, Rules, Use Cases for tables and models; plus Measures, Dimensions, Filters for contracts). Anything under unrecognized headings ("Retrieval Anchors", "Query Patterns") is silently dropped during embedding. Stay inside the recognized headings or your prose isn't doing what you think it's doing.

Notes

The litmus test for context: would an analyst reading it on day one learn something they couldn't learn from the schema? If not, cut it. Restating column names, generic analytics advice, and hypothetical SQL examples are pure noise.

Source code

The full set of 19 jaffle business-context descriptions ships at business_context/ in the sample dataset, including raw_customers.md quoted above. See also Context for the author guide and Context for AI for the system-side rules.

Writing context an LLM understands