Product Title Optimiser

Features

• GPT-4o with local LLM endpoint support
• Category-based template creation (up to 50 titles)
• Batch processing (default 20 per request)
• Numerical validation (all numbers preserved)
• 80% minimum word overlap verification
• Missing words flagging in output
• Rate limit handling with exponential backoff

How to use

1. 1 Prepare CSV with Name and Categories columns
2. 2 Run with --input, --model, --batch-size options
3. 3 Review output with Optimized Title, Is Same, Missing Words columns
4. 4 Check flagged titles where words were lost

Frequently asked questions

What must the input CSV look like?

A CSV with a title column and a category column, named Name and Categories by default. Both can be remapped with --title-col and --category-col. Titles are grouped by the exact category string, so if your Categories column holds combined values like 'Torches, Consumables > Tips', each distinct string is treated as its own category with its own template and API calls.

What drives API cost?

One template-creation request per unique category (sent with up to the first 50 titles of that category) plus one optimisation request per batch of 20 titles (configurable with --batch-size). The default model is gpt-4o via your OPENAI_API_KEY, but --base-url lets you point it at a local OpenAI-compatible endpoint such as LM Studio, in which case no key or spend is needed. Use --limit for a cheap trial run first.

Why do so many titles come back unchanged?

Two safety checks silently revert to the original. First, every number is compared as an exact string: if the set of numbers differs at all, including pure reformatting such as '1,000' becoming '1000', the original is kept. Second, at least 80% of the original title's words must appear in the optimised version, so heavy rewording is rejected. The Is Same column shows which rows were left alone.

What does the Missing Words column mean?

Words present in the original title but absent from the optimised one, for titles that still passed the 80% overlap check. These rows survived validation but lost up to 20% of their words, so they are the ones worth reviewing manually before importing.

What happens on rate limits or API failures?

Rate limit errors trigger exponential backoff starting at 1 second and doubling, with up to 5 retries per batch. If a batch still fails after all retries, the original titles are returned for that batch rather than the run crashing, so a completed run can quietly contain unoptimised batches. Check title_optimization.log for warnings.