Code you can run

# csv-roundtrip

Export a CSV, change one column by rule, prove that nothing else changed, import it.
From Distru's No Bullshit AI Course, module 05, lesson 1. Version 1.0 (2026-09-17). MIT.

Works for the three requests we get most: mass-edit sales-order status, bulk cost-type
edit, image-URL mapping. Works for anything else that is "same file back, one column different".

## Files

| file | what |
|---|---|
| `transform.py` | the script. Python 3.10+, standard library only |
| `rules.example.json` | one bulk edit written down: which column, which rows, what value |
| `sample-in.csv` | a fake 8-order export to practise on |
| `sample-out.csv` | what `transform.py` produces from the sample with the example rules |

## Run it

```bash
# 1. see what would change, write nothing
python3 transform.py --in sample-in.csv --rules rules.example.json --out changed.csv --dry-run

# 2. write the file
python3 transform.py --in sample-in.csv --rules rules.example.json --out changed.csv

# 3. prove the file is safe to import (exit code 0 = go, 1 = stop)
python3 transform.py --validate --in sample-in.csv --rules rules.example.json --out changed.csv
```

Expected output of step 1 on the sample:

```
DRY RUN: 8 rows in, 8 rows out
  3 row(s) change in column 'status'
  SO-1041: status: 'READY_TO_SHIP' -> 'DELIVERING'
  SO-1042: status: 'READY_TO_SHIP' -> 'DELIVERING'
  SO-1047: status: 'READY_TO_SHIP' -> 'DELIVERING'
OK (dry run). Re-run without --dry-run to write the file.
```

## What `--validate` refuses

- row count changed
- header changed, or a required column is missing
- the key column (`order_number`, `sku`, ...) changed on any row, is blank, or is duplicated
- any column not named in the rules changed on any row
- a value outside `allowed_values`
- the output differs from what the rules would produce (someone edited it by hand afterwards)

Any of those and it prints `STOP` and exits 1. Do not import a file that says STOP.

## Writing a rules file

`key` is the column that identifies a row. `changes` is a list; each entry names a `column`
and either `set` (one value for every matching row) or `map` (old value to new value).
`where` limits which rows a change touches; every listed column must match, exactly.
`keep_unmapped: true` leaves values that are not in the map alone and tells you which ones it saw.

Let the AI write the rules file for you: paste the header row, three sample rows and this
README, and ask for a `rules.json` that does your edit. Then run `--dry-run` and read the
diff before you believe it.

## Before you import

Open the target system's import template first. Column names have to match it exactly,
and a status has to be one the system accepts (Distru orders use `PENDING`, `PROCESSING`,
`READY_TO_SHIP`, `DELIVERING`, `DELIVERED`, `COMPLETED`, `CANCELED`). Keep the original
export; name it `original-YYYY-MM-DD.csv` and never edit it.

# distru-export

One script that pulls your packages, orders or products out of Distru and saves them as a CSV you can open in a spreadsheet or hand to an AI. From lesson 07-01 of the No Bullshit AI Course. Read-only: it only ever sends GET requests.

## Run it

```bash
# 1. See exactly what it would send. No key, no network.
python3 export.py --resource orders --dry-run

# 2. Get a key: Distru -> Settings -> Integrations -> Distru API -> Create API Key.
#    Keys expire one year after they are issued. Never paste the key into a chat window.
export DISTRU_API_TOKEN=...

# 3. First look: one page only.
python3 export.py --resource orders --max-pages 1

# 4. The real thing: everything changed since a date.
python3 export.py --resource orders --since 2026-09-01 --out orders.csv
python3 export.py --resource packages --since 2026-09-01
python3 export.py --resource products
```

Python 3.8 or newer, standard library only. Nothing to install.

## What it does

- Follows Distru's pagination contract: first request has no page parameter, then it follows the `next_page` URL from each response until it is `null`. It never guesses a page size.
- `--since` becomes an inclusive open-ended datetime range (`updated_datetime=2026-09-01T00:00:00.000000Z,`). The packages list filters on `inserted_datetime` instead; the script picks the right one.
- Flattens nested objects to dotted columns (`company.name`) and stores lists (`items`) as JSON text in one cell. Columns are whatever the API returns, so a new field shows up as a new column instead of breaking the script.
- Money and quantities arrive as strings (`"60.00"`). Keep them as text in your spreadsheet until you need arithmetic.
- On a 429 it waits for `Retry-After` and retries. Today only PDF endpoints are rate limited, so you should not see one.

## Dry-run output (what we saw)

```text
$ python3 export.py --resource orders --since 2026-09-01 --dry-run
DRY RUN: orders -> orders.csv
GET https://app.distru.com/public/v1/orders?updated_datetime=2026-09-01T00%3A00%3A00.000000Z%2C
  Authorization: Bearer <DISTRU_API_TOKEN>
  Content-Type: application/json
  Accept: application/json
  -> then follow response['next_page'] exactly as given, until it is null
No request was sent.
```

## Change it

The `RESOURCES` dict at the top is the only thing to edit to add another list endpoint (`/invoices`, `/companies`, `/inventory?groupings[]=PRODUCT`). Everything under `https://app.distru.com/public/v1/` uses the same auth, pagination and error envelope. Full docs: https://apidocs.distru.dev (or paste https://apidocs.distru.dev/llms.txt into your AI).

Facts above verified against Distru's API documentation and backend on 2026-09-17. Breaking changes are announced only on Distru's API email list; sign up if you build on this.

CC0 1.0. Copy it, change it, no attribution needed. Version 1.0.0.

# csv-head: look before you paste

Two small things for the moment right before you paste a spreadsheet export into an AI chat.

1. `csv-head.py`: prints the header row, row count, a few sample rows, blank cells per column, columns that look like they hold personal data, and a rough token estimate. Offline, standard library only, no network, no install.
2. `paste-this-first.md`: the prompt to send *before* your data, so the AI describes the columns back to you and asks for the formula-or-script route on anything numeric.

From Distru's No Bullshit AI Course, lesson 03-02 "Paste the spreadsheet". CC0 1.0: copy, edit, share, no attribution needed.

## Run it

    python3 csv-head.py packages.csv              # report
    python3 csv-head.py packages.csv -n 5         # show 5 sample rows instead of 3
    python3 csv-head.py packages.csv --paste      # header + 3 rows, ready to paste into a chat
    python3 csv-head.py --self-test               # checks itself on a built-in sample; prints ok/FAIL lines

Needs Python 3.8 or newer, which macOS and most Linux machines already have. On Windows, install Python from python.org and run the same commands in PowerShell.

## What the report tells you

- **data rows / columns.** Write these two numbers down. After any cleanup, the row count should match.
- **ragged rows.** Rows with the wrong number of columns. Usually a comma inside a product name. Fix before pasting; the AI will silently misread them.
- **token estimate.** A range, because tokenizers differ and this is a heuristic. A 500-row, 10-column package export with a Metrc tag on every row comes out around 25K to 29K tokens (the true count was 26.8K), well inside any current model's context window. Tags and numbers cost about one token per 2 characters, far more than prose. Past roughly 60K tokens the script tells you to upload as a file or ask for the script instead of the answer.
- **LOOKS PERSONAL.** Header names that usually hold customer or employee data. Drop the column or replace values with `Customer 1`, `Customer 2` before pasting. The check is on the header name only; it will miss a badly named column and will flag `card_count`. Read the header yourself too.
- **Metrc tags.** Columns where most values match the 24-character `1A…` tag shape. Keep them as text. Spreadsheets turn them into `1.23E+23`.

## How it was tested

2026-09-17, offline. `--self-test` passes on the built-in sample. The estimator's constants were fitted against `tiktoken` (`cl100k_base` and `o200k_base`) on three synthetic 500-row exports with realistic column shapes, then checked:

| file | characters | csv-head range | tiktoken cl100k | o200k |
|---|---|---|---|---|
| tag-heavy, 5 columns | 24,118 | 10.3K to 13.9K | 12,188 | 12,188 |
| prose-heavy, 3 columns | 49,063 | 10.9K to 14.7K | 12,290 | 12,164 |
| mixed package export, 10 columns | 54,473 | 21.3K to 28.8K | 26,830 | 26,653 |

Max error 7%. Anthropic and Google tokenizers were not checked; expect the same order of magnitude. The PII check is header-name only and was not tested beyond the column names listed in the script. Not tested on real customer exports; run it on yours and tell us what it got wrong.

## Change it

The regex `PII_HINTS` is where you add your own column names. `TAG_LIKE` matches Metrc tags; if your state's tags look different, edit it. The token estimate lives in `estimate_tokens()`; if you want the exact count, `pip install tiktoken` and encode the file yourself.

# sop-answers

version 1.0 · 2026-09-25 · MIT · from Distru's No Bullshit AI Course (module 11, lesson 3).

Ask your SOP binder a question in plain words and get the steps back, with the passages they came from. About 160 lines of Python, standard library only. It is a starting point to read and adapt, not a product.

## Files

- `sop-answers.py`: `index` a folder of `.md` or `.txt` files, then `ask` questions.
- `sample-binder/`: six made-up SOPs for a made-up shop, so you can watch it work before you use your own.
- `questions.csv`: ten staff questions, each with the SOP that answers it, for `eval`.

## Run

```
export OPENROUTER_API_KEY=...            # openrouter.ai/keys
python3 sop-answers.py --self-test        # offline checks, no key needed
python3 sop-answers.py index sample-binder/
python3 sop-answers.py ask "what do I do with moldy flower?"
python3 sop-answers.py ask "what time does the store open on Sundays?"   # not in the binder: it should say so
python3 sop-answers.py ask "a customer returned a leaking cart" --dry-run  # see what it found and the prompt, no answer call
python3 sop-answers.py eval questions.csv  # did search find the right SOP for each question?
```

Indexing the sample costs a small fraction of a cent. Each question costs one embedding (next to nothing) plus one answer from the model, usually well under a cent.

## How it works

1. **Index, once.** Each file is split into paragraph-sized passages. Each passage is turned into a list of numbers (an embedding) with its SOP title in front, and saved to `sop-index.json`.
2. **Ask.** Your question is embedded the same way, and the four closest passages are picked.
3. **Answer.** Only those passages go to the model, with instructions to answer from them alone, cite them like [1], and say "The binder does not cover this." when they do not.

## Before you point it at your own binder

- **Your documents leave the building.** Passages go to OpenRouter for embedding, and the ones it picks go to the answering model. Read the provider's data terms, and leave out anything with customer names, license numbers or package tags.
- **Re-index when an SOP changes.** The index is a snapshot. An old index answers from old rules.
- **Check it on questions you know the answer to.** Replace `questions.csv` with twenty or more real questions in your staff's words and the file that answers each, then run `eval`. The sample scores 10 of 10 on a six-SOP binder, which is easy; your real binder will miss some, and the misses are the useful part. If the right SOP is not in the four it found, the answer cannot be right either.
- **It is not a compliance officer.** It repeats your binder. If your binder is wrong or out of date, so is the answer.

## Settings

Environment variables: `EMBED_MODEL` (default `openai/text-embedding-3-small`), `ANSWER_MODEL` (default `anthropic/claude-sonnet-5`), `SOP_INDEX` (default `sop-index.json`). If you change `EMBED_MODEL`, rebuild the index; it refuses to mix models.

# status-agent

A small, boring program that moves today's Distru sales orders from READY_TO_SHIP to DELIVERING, with the guardrails you would want before letting anything touch orders on its own. From lesson 07-04 of the No Bullshit AI Course.

It is deliberately not clever. The allowlist, the cap and the gate live in one block at the top of `agent.py`, so the person who signs off on it can read the whole policy in a minute.

## Run it

```bash
# 1. Rehearse offline: four fake orders, every decision printed. No key, no network.
python3 agent.py --dry-run --fixture sample-orders.json

# 2. Read live, write nothing.
export DISTRU_API_TOKEN=...          # Distru -> Settings -> Integrations -> Distru API
python3 agent.py --dry-run

# 3. Live. Run it by hand for a week before you put it on a schedule.
python3 agent.py
```

Python 3.8+, standard library only. Optional: `pip install typesafe-sdk` and `STATUS_AGENT_GATE=typesafe` to add a one-question decision-model check before each write (lesson 06-05).

## The guardrails

| guardrail | where | what it does |
|---|---|---|
| allowlist of transitions | `ALLOWED_TRANSITIONS` | only `READY_TO_SHIP -> DELIVERING`. Anything else is skipped and logged. |
| find-before-write | `reread()` | re-reads each order by id right before writing. The list can lag about a second, and a rep may have moved it. |
| idempotent | `status-agent-ledger.jsonl` | an order already written today is skipped, so running it twice writes once. |
| stopping condition | `MAX_WRITES_PER_RUN` | 25 writes, then it stops and says so. Also stops on the first unexpected HTTP error. |
| pre-write gate | `gate()` | field checks (customer set, lines fulfilled); optionally one Noul question. |
| dry run | `--dry-run` | every decision, no POST. |
| log | the ledger | one JSON line per order per run: action, from, to, reason, time. |

## What the dry run printed (fixture)

```text
# status-agent DRY RUN for 2026-09-17
# allowlist: {"READY_TO_SHIP": ["DELIVERING"]}  max writes: 25  gate: deterministic
# GET https://app.distru.com/public/v1/orders?delivery_datetime=2026-09-17T07%3A00%3A00.000000Z%2C2026-09-18T06%3A59%3A59.999999Z&statuses%5B%5D=READY_TO_SHIP
#   Authorization: Bearer <DISTRU_API_TOKEN>
# fixture: 4 orders from sample-orders.json (no request sent)
{"order_id": "…101", "order_number": "SO-1041", "from": "READY_TO_SHIP", "to": "DELIVERING", "action": "wrote", "reason": "fields look complete", "request": "POST https://app.distru.com/public/v1/orders {\"id\": \"…101\", \"status\": \"DELIVERING\"}", ...}
{"order_id": "…102", "order_number": "SO-1042", "from": "PROCESSING", "to": "DELIVERING", "action": "skipped", "reason": "PROCESSING -> DELIVERING not in allowlist", ...}
{"order_id": "…103", "order_number": "SO-1043", "from": "READY_TO_SHIP", "to": "DELIVERING", "action": "skipped", "reason": "no customer on the order; DELIVERING needs one", ...}
{"order_id": "…104", "order_number": "SO-1044", "from": "DELIVERING", "to": "DELIVERING", "action": "skipped", "reason": "DELIVERING -> DELIVERING not in allowlist", ...}
# summary 2026-09-17: wrote=1 skipped=3 failed=0 stopped=0  (dry run: nothing was sent)
```

## Distru facts this relies on (verified 2026-09-17)

- `GET /public/v1/orders` accepts `delivery_datetime=<after>,<before>` (inclusive ISO 8601) and `statuses[]=...`; response is `{"data": [...], "next_page": ...}`.
- `POST /public/v1/orders` with `{"id": "...", "status": "DELIVERING"}` is a sparse update: every field you omit keeps its value.
- Statuses: PENDING, PROCESSING, READY_TO_SHIP, DELIVERING, DELIVERED, COMPLETED, CANCELED. Moving to DELIVERING requires every line fulfilled, a customer set, and a compliance transfer if any item is package-tracked. Distru returns a 400 with a `pointer` when that is not true; the agent logs it as `failed` and continues.
- Only PDF endpoints are rate limited. Writes that sync to Metrc are asynchronous: a 200 means Distru accepted it, not that the state system has it yet.

Set `TIMEZONE_OFFSET_HOURS` to your warehouse. "Today" is your calendar day, converted to UTC for the filter.

## What it will not do

Pick which orders to touch. Retry a 400. Move anything backwards. Run without a human having run it by hand first. If you want mass edits to other statuses, add one line to `ALLOWED_TRANSITIONS`, run `--dry-run`, read the ledger, then decide.

CC0 1.0. Version 1.0.0.

# coa-photo-check

version 1.0 · 2026-09-25 · MIT · from Distru's No Bullshit AI Course (module 05, lesson 7).

Read a COA from a photo with a vision-capable AI, then check what it read with plain code before anyone uses it.

## Files

- `prompt.md`: the prompt to paste with the photo. It lets the AI say UNREADABLE instead of guessing.
- `check.py`: checks the AI's output: every field present and readable, total THC adds up, label matches COA. Standard library only.
- `samples/`: a made-up COA as a clean photo and a blurry one with glare, the real outputs Claude Sonnet 5 gave for each, and a label to compare against.

## Run

```
python3 check.py --self-test
python3 check.py samples/extracted-clean.json samples/label.json        # no flags
python3 check.py samples/extracted-bad-careful.json samples/label.json  # flags the unreadable fields
python3 check.py samples/extracted-bad-naive.json samples/label.json    # flags the misread numbers
```

## What the samples show

We sent both photos to Claude Sonnet 5 (via OpenRouter, about half a cent a photo), with and without the "use UNREADABLE, never guess" instruction:

| | Clean photo | Blurry photo, naive prompt | Blurry photo, careful prompt |
|---|---|---|---|
| THCa | 24.81 % ✓ | 24.91 ✗ | UNREADABLE |
| Total THC | 22.63 % ✓ | 22.53 ✗ | UNREADABLE |
| Total CBD | 0.05 % ✓ | 0.41 ✗ (that is the CBG line) | UNREADABLE |
| Report date | 09/16/2026 ✓ | 09/16/2025 ✗ | 09/16/2026 ✓ |

The naive answer looks perfectly reasonable. `check.py` catches it anyway, because 0.87 + 0.877 × 24.91 is 22.72, not 22.53.

## Before you use it on real COAs

- **The best COA is not a photo.** If the lab sends a PDF, a portal link or a QR code, or the results are in your seed-to-sale system, use that. A photo is the fallback.
- **It reads; it does not verify.** A clean photo of a forged or wrong-batch COA reads perfectly. Check the batch against your inventory and the lab against your approved list.
- **A person decides.** Anything flagged, and anything going onto a label or into Metrc, gets human eyes.
- **Check your state's total THC rule.** The 0.877 conversion is standard, but confirm how your state requires total THC to be calculated and reported.