The numbers show that something is wrong. The AI tells you what.

Copy the block

Insert the ai block from the example file into config/config.json and set "enabled": true for the provider you want. If several are enabled, the first in the list counts. You can keep the model (default) or change it.

"ai": {
  "providers": [
    { "name": "anthropic",
      "enabled": true,
      "model": "claude-sonnet-5-5",
      "apiKeyEnvironmentVariable":
        "ANTHROPIC_API_KEY" },
    { "name": "openai", "enabled": false, … }
  ],
  "language": "en",
  "monthlyTokenLimit": 2000000,
  "sendReviewText": true,
  "features": { "summary": true, "sentiment": true,
    "themes": true, "versions": true,
    "comparison": true, "replyDrafts": true,
    "measures": true, "questions": false }
}

Key as environment variable

The script reads the variable’s name from apiKeyEnvironmentVariable. Put the key into your shell configuration, on the Mac usually ~/.zshrc, then open a new terminal. For the daily run via scheduler the variable goes into its environment (see BETRIEB.md).

# ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-…"

# check without showing the value
test -n "$ANTHROPIC_API_KEY" && echo set

If the key accidentally ends up in config.json, the script rejects it. In logs, error messages and the report it is removed automatically.

The most important switches

All in the ai block, all optional:

language        de or en: language of the AI texts
model           per provider, see models below
monthlyTokenLimit  hard brake per month
sendReviewText  false: numbers only, no texts
features.*      switch off single features
questions       free-text questions, off by default
maxReviewsPerRequest 60 per batch
requestTimeoutSeconds 180
servicePort     8765 for the question service

Free-text questions are off by default because every question costs a request. For the “AI questions” tab in the report set "questions": true.

Analyse

Reads the stored reviews, sends only new or changed ones, writes the results as ai-analysis.json per app into data/ and rebuilds the report. At the end there is the cost table per app.

./ratings.sh analyze

Check topic suggestions

The AI suggests new topics and missing search words for known topics. The tool counts how many more reviews a word would match. Both go into config/themen.json only when you confirm them.

./ratings.sh ai-themes
./ratings.sh ai-themes --accept 2
./ratings.sh ai-themes --accept-term 1 3

Questions from the command line

A question to the stored reviews, narrowed by app, period and stars. Needs "questions": true. Saved questions are listed by ai-questions.

./ratings.sh ask "Which apps mention
  the bonus programme?" --app bkk-herkulis
./ratings.sh ai-questions

Install Ollama and pull a model

Mac and Windows via the installer from ollama.com, Linux with one line. Ollama then runs in the background. You pull a model once, about 5 GB.

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# pull a model (once), check
ollama pull llama3.1:8b
ollama list

Enlarge the context window

Ollama starts models with a small window (4096 tokens). A batch of reviews does not fit; the beginning would be cut off silently. Set it once, restart Ollama.

# Mac
launchctl setenv OLLAMA_CONTEXT_LENGTH 16384

# Linux: in the systemd unit
Environment=OLLAMA_CONTEXT_LENGTH=16384

# Windows: system environment variable

Enable the provider, shrink the batches

No key, no environment variable. For local models smaller batches and more time per request; url only if the server runs on another port (LM Studio: 1234, llama.cpp: 8080); label is a free display name, for example “LM Studio”. The former name ollama still works.

"ai": {
  "providers": [
    { "name": "local",
      "enabled": true,
      "model": "llama3.1:8b" }
  ],
  "maxReviewsPerRequest": 15,
  "maxCharsPerRequest": 24000,
  "summaryReviews": 40,
  "requestTimeoutSeconds": 600
}