CSV Annotation with OpenAI

Adds AI-generated annotations to CSV files by processing each row with a prompt.

Quick Start

uv run annotate-csv.py "Classify sentiment as positive/negative/neutral" reviews.csv

Output: reviews_annotated.csv with new annotation column.

Dependencies install automatically on first run.

Core Usage

uv run annotate-csv.py <prompt> <csv_file> [options]

| Option | Description | Default | |--------|-------------|---------| | -o, --output | Output file path | <input>_annotated.csv | | -c, --column | Annotation column name | annotation | | --context | Columns to use (all or comma-separated) | all | | --model | OpenAI model | gpt-5-mini | | --parallelism | Parallel workers | 10 | | --id-column | Column for progress display | - |

Prompt Sources

Prompts can be inline or from a file:

# Inline prompt
python annotate-csv.py "Extract the main topic" data.csv

# From file (for complex prompts)
python annotate-csv.py prompt.txt data.csv

Common Patterns

Classification:

python annotate-csv.py "Classify sentiment: positive, negative, or neutral" feedback.csv -c sentiment

Extraction:

python annotate-csv.py "Extract the product name mentioned" reviews.csv -c product --context "review_text"

Summarization:

python annotate-csv.py "Summarize in one sentence" articles.csv -c summary

See EXAMPLES.md for more patterns and prompt templates.

Environment Setup

Requires OPENAI_API_KEY in .env file:

OPENAI_API_KEY=sk-...

Run with uv (recommended):

uv run annotate-csv.py "Your prompt" data.csv

Or install dependencies first:

uv pip install -r requirements.txt
python annotate-csv.py "Your prompt" data.csv

Workflow

1. Preview data: Check CSV structure and columns
2. Choose context: Decide which columns the AI needs to see
3. Write prompt: Be specific about expected output format
4. Test on subset: Try on a few rows first if large dataset
5. Run full annotation: Process the complete file
6. Validate results: Spot-check annotation quality

Writing Effective Prompts

• Be explicit about output format (single word, phrase, sentence)
• List valid categories for classification tasks
• Specify what to do with ambiguous cases
• Keep prompts focused on one task

See PROMPTS.md for prompt-writing guidance.

Troubleshooting

| Issue | Solution | |-------|----------| | API key error | Check .env file has OPENAI_API_KEY | | Column not found | Verify column names match CSV exactly | | Rate limits | Reduce --parallelism to 5 or lower | | Empty annotations | Check context columns have data |