Project: An AI Review Analyser

id,product,review
r1,Headphones,Great sound and fast delivery. Love them!
r2,Headphones,Stopped working after a week. I want a refund.
r3,Charger,Arrived late but works perfectly.
r4,Charger,Terrible. It broke on the first day.
r5,Keyboard,"Excellent keys, very happy with it."
r6,Keyboard,It is a keyboard. It types.
r7,Headphones,"Delivery was slow, sound is great."
r8,Charger,"Fast charging, perfect for my phone."

"""Analyse customer reviews with an LLM — or offline, with simple keyword rules."""
import argparse
import json
from dataclasses import asdict, dataclass
from pathlib import Path

import pandas as pd

MODEL = "gpt-5.5"
ALLOWED = {"positive", "negative", "neutral"}
CACHE = Path("cache.jsonl")


@dataclass
class Analysis:
    sentiment: str
    topic: str


def classify_offline(text: str) -> Analysis:
    """A rough keyword baseline: free, instant, and good for testing the pipeline."""
    words = text.lower()
    good = ["love", "great", "excellent", "perfect", "fast", "happy"]
    bad = ["broke", "late", "terrible", "refund", "slow", "stopped"]
    score = sum(w in words for w in good) - sum(w in words for w in bad)
    sentiment = "positive" if score > 0 else "negative" if score < 0 else "neutral"
    topic = "delivery" if any(w in words for w in ["deliver", "arrived", "late"]) else "product"
    return Analysis(sentiment, topic)


def classify_with_llm(client, text: str) -> Analysis:
    response = client.responses.create(
        model=MODEL,
        instructions=(
            "Classify the customer review. Reply with JSON only, like "
            '{"sentiment": "positive", "topic": "delivery"}. '
            "sentiment is positive, negative or neutral; topic is one lower-case word."
        ),
        input=text,
    )
    data = json.loads(response.output_text)          # may raise ValueError
    if data.get("sentiment") not in ALLOWED:
        raise ValueError(f"unexpected sentiment {data.get('sentiment')!r}")
    return Analysis(data["sentiment"], str(data.get("topic", "other")).lower())


def load_cache() -> dict[str, dict]:
    if not CACHE.exists():
        return {}
    with open(CACHE, encoding="utf-8") as f:
        return {row["id"]: row for row in map(json.loads, f)}


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("csv", help="a CSV file with id, product and review columns")
    parser.add_argument("--offline", action="store_true", help="use keyword rules instead of an LLM")
    args = parser.parse_args()

    reviews = pd.read_csv(args.csv)
    cache = load_cache()
    client = None
    if not args.offline:
        from openai import OpenAI
        client = OpenAI(timeout=30, max_retries=3)

    results = []
    with open(CACHE, "a", encoding="utf-8") as cache_file:
        for row in reviews.itertuples():
            if row.id in cache:                     # analysed before: no second API call
                results.append(cache[row.id])
                continue
            try:
                if args.offline:
                    analysis = classify_offline(row.review)
                else:
                    analysis = classify_with_llm(client, row.review)
            except (ValueError, KeyError) as error:
                print(f"Skipping {row.id}: {error}")
                continue
            record = {"id": row.id, "product": row.product, **asdict(analysis)}
            cache_file.write(json.dumps(record, ensure_ascii=False) + "\n")
            results.append(record)

    df = pd.DataFrame(results)
    df.to_csv("results.csv", index=False)
    print(f"Analysed {len(df)} of {len(reviews)} reviews\n")
    print(pd.crosstab(df["product"], df["sentiment"]))
    print("\nTopics:", df["topic"].value_counts().to_dict())


if __name__ == "__main__":
    main()

python analyse_reviews.py reviews.csv --offline     # free: keyword rules
python analyse_reviews.py reviews.csv               # real: calls the model

Analysed 8 of 8 reviews

sentiment   negative  neutral  positive
product                                
Charger            1        1         1
Headphones         1        1         1
Keyboard           0        1         1

Topics: {'product': 5, 'delivery': 3}

Skipping r6: Expecting value: line 1 column 1 (char 0)
Analysed 7 of 8 reviews

sentiment   negative  neutral  positive
product                                
Charger            1        0         2
Headphones         1        1         1
Keyboard           0        0         1

Topics: {'durability': 2, 'delivery': 2, 'sound': 1, 'typing': 1, 'charging': 1}