# Turn a feedback batch into a report you can trace

Give this package a feedback CSV and a short collection note. Your installed Codex reads the batch once and proposes themes. Python checks that every input item is accounted for, counts the assignments and creates an HTML report with links back to the items.

For a one-off question, attaching the files to your usual Agent may be simpler. This package is useful when you want to repeat the same input checks, counting and report format. You start each run yourself; it does not watch a folder or run on a schedule.

## Before the first run

Use Python 3.10 or newer and an installed Codex CLI already signed in through ChatGPT. This package has no Python dependencies. In a terminal, check `python3 --version`, `codex --version` and `codex login status`. The runner also checks the required CLI options before sending a batch.

Open the terminal in this package's folder. Use only material you are allowed to send to the account's model. The included batches are fictional. Your inputs are sent through Codex to its model service; they are not processed solely on your device. CodexWork receives nothing. The runner refuses API-key environment variables because this example uses saved ChatGPT CLI login, not API billing. Your plan's limits still apply.

## Try the two supplied batches

Run the first batch:

```sh
python3 run.py --input examples/first/feedback_export.csv --context examples/first/collection.md --out results/first
```

When the command succeeds, open `results/first/report.html`. Follow a theme's item links and check the interpretation against the source index. Items that do not permit direct quotation keep their wording out of the rendered report.

Run the separate later batch:

```sh
python3 run.py --input examples/changed/feedback_export.csv --context examples/changed/collection.md --out results/changed
```

Open its report alongside the first. Each batch gets its own themes and denominator. Neither file is a panel of the same people, so a different share is not evidence of changing customer prevalence. Theme IDs are local to one run.

By default, Codex uses its saved model setting. To select an available model explicitly, add `--model MODEL_ID --effort high`, replacing `MODEL_ID` with an identifier supported by your installed CLI and account. `--timeout 300` allows up to five minutes for that single call. No global setting is changed.

## Use your own feedback

Keep these CSV columns in this order:

```csv
id,date,channel,text,quote_permission
F-001,2026-10-01,support,"The exported invoice is missing a line.",no
```

Use unique IDs of up to 64 letters, digits, dots, underscores or hyphens, beginning with a letter or digit. Dates must use `YYYY-MM-DD`. `quote_permission` is exactly `yes` or `no`. Give each row nonempty channel and text fields. The input limit is 2,000 rows and 1 MiB; each text field allows up to 8,000 characters. These are file limits, not a promise that every model can handle the largest batch.

In your collection note, explain what the feedback concerns, when and how it was collected, what was excluded, and whether the items represent people or repeated messages. Remove identifying details that the analysis does not need. A `no` quotation flag is not permission to send private material to a model.

Point `--input` and `--context` at those files and choose a new `--out` folder. Keep each successful folder: it contains the input snapshot, original model JSON, item assignments, theme summary, unclassified items and the report. The `run.json` record identifies inputs and execution status.

## If a run fails

The command exits without a finished report and prints the location of a separate diagnostics folder. Inspect `diagnostic.txt` and `run.json`. A failed login, timeout, rejected response or invalid JSON is not an empty feedback result.

Correct the reported problem, then run again with a fresh output folder. The runner never retries automatically and never overwrites an existing result. A retry after a model call can consume more of your plan's allowance. Preserved `recorded-run/` evidence cannot be used as an output destination.

## Before sharing a report

Check the model's interpretations, not just its arithmetic. The validator catches missing or invented IDs, duplicate assignments and invalid structure; it cannot establish that the model understood each comment. Counts can overlap across themes. Observations are not customer priorities unless you have independent evidence for that judgment.

The saved folder includes the original inputs and execution logs. The report links to those local input snapshots. A withheld quote in the report does not remove it from the saved CSV. Select and review files before sharing; this package does not grant publication rights or send the report to anyone.

## Interface references

The runner uses [Codex non-interactive mode](https://learn.chatgpt.com/docs/non-interactive-mode) and [saved CLI authentication](https://learn.chatgpt.com/docs/auth). Account access and command options can change; the local preflight reports an unsupported setup instead of silently switching to an API service.