pplyz

python + prompt + analyze

Add LLM-generated columns to a CSV with one command.

Requirements

• uv (Recommended)
• An OpenRouter API key (recommended — one key covers the default model and pplyz judge), any other LiteLLM-compatible API key (OpenAI, Gemini, Anthropic, etc.), or a local Ollama server (no API key needed)

uv is the easiest way to run the CLI.

Usage

Install

uv tool install pplyz

Example

pplyz test.csv \
  --input title,abstract \
  --output "relevant:bool,summary:str" \
  --model openai/gpt-4o-mini

This command sends the title and abstract columns to the LLM, adds relevant and summary columns to test.csv, and uses the openai/gpt-4o-mini model.

Command arguments

Use -h or --help to list arguments.

pplyz -h

Yes/no, choice and scale decisions with Jev (pplyz judge)

pplyz judge asks Jev — TypeSafe's decision-only model — the same questions about every row. Jev never writes text, so answers are always one of the allowed values, and it is much faster and cheaper than a chat LLM (rows run 8 at a time by default).

It uses your OPENROUTER_API_KEY (create one at https://openrouter.ai/keys; see Keeping API keys out of config files). Jev is served from OpenRouter's alpha decisions endpoint, so details may still change.

pplyz judge papers.csv

The first run walks you through the questions — no special syntax needed:

Columns in the CSV (3):
  title, abstract, year
Which columns should Jev read? (comma-separated, Tab to complete): title,abstract

Question 1: What should be judged for each row?
  Jev reads the selected columns of each row and answers this.
  e.g. "Is this paper about cancer research?"
> Is this paper about cancer research?
How should it be answered?
  1) Yes / No (saved as the probability of yes, 0-1)
  2) Pick one of several options
  3) Rate on a scale (lowest -> highest)
Choose [1]: 1
Output column name [paper_about_cancer_research]: is_cancer
Add another question? [y/N]: n

Questions:
  1. is_cancer (yes/no probability): Is this paper about cancer research?
Use these questions? (n = start over) [Y/n]:

→ Saved questions to papers.judge.toml (edit it or rerun to reuse)

• When picking columns, press Tab to complete names — typing any part of a name finds it, which helps with wide CSVs.
• pplyz then previews a few rows and asks before processing the whole file.
• Results are added as new columns to the input CSV (in place). Pass -o out.csv to keep the input unchanged. Existing cells are kept as text (e.g. 001 stays 001).
• Later runs reuse papers.judge.toml and skip rows that already have answers. If you edit the questions, pplyz asks whether to recompute those rows (or pass -f).
• For a scale, list levels from lowest to highest (e.g. low|medium|high).
• Use one questions file per CSV: it remembers which questions produced the answers in that CSV.

Yes/no columns hold the probability itself so you can pick any threshold later (e.g. df[df.is_cancer >= 0.8]). --with-probability adds <column>_p — the probability of the chosen option or level — for choice and scale questions.

Configuration

1. Create the user config once:

mkdir -p ~/.config/pplyz
$EDITOR ~/.config/pplyz/config.toml

On Windows, use %APPDATA%\\pplyz\\config.toml.

2. Add only the providers you actually use:

[env]
OPENROUTER_API_KEY = "keychain:openrouter"   # read from the macOS Keychain
OPENAI_API_KEY = "sk-..."                    # or plain text (not recommended)

[pplyz]
default_model = "openrouter/openai/gpt-4o-mini"
default_input = "title,abstract"
default_output = "relevant:bool,summary:str"

Keeping API keys out of config files (macOS Keychain)

Store the key once — the input is hidden and never lands in shell history:

pplyz auth set openrouter

Then reference it instead of pasting the key:

[env]
OPENROUTER_API_KEY = "keychain:openrouter"

keychain:<name> reads the generic password with service pplyz and account <name>; keychain:<service>/<account> reads any other Keychain item. The same syntax works in environment variables. Keys are only read for the provider actually used.

Settings priority

pplyz loads settings in this order (earlier wins):

1. Existing environment variables
2. pplyz.local.toml in the project root (optional)
3. User config: ~/.config/pplyz/config.toml (or %APPDATA%\\pplyz\\config.toml on Windows; if XDG_CONFIG_HOME is set, it uses that)

To keep configs elsewhere, set PPLYZ_CONFIG_DIR=/path/to/dir and place config.toml there.

[env] table (API keys)

Set these inside the [env] table of your config.toml (or export them as environment variables):

[pplyz] table (Default settings)

Local models with Ollama

pplyz can run entirely offline against a local Ollama server — no API key required.

# 1. Start Ollama and pull a model
ollama serve            # usually already running
ollama pull llama3.1

# 2. Run pplyz against it (use the ollama_chat/ prefix)
pplyz test.csv \
  --input title,abstract \
  --output "relevant:bool,summary:str" \
  --model ollama_chat/llama3.1

Notes:

• Use the ollama_chat/ prefix (chat API); it handles system prompts better than ollama/.
• The default endpoint is http://localhost:11434. Override it with --api-base, the OLLAMA_API_BASE / PPLYZ_API_BASE env var, or default_api_base in config.toml.
• JSON output is enforced via Ollama's JSON mode. Local models follow schemas less reliably than hosted ones — prefer bool fields for decisions and test with --preview.
• --api-base also works for other OpenAI-compatible local servers (LM Studio, vLLM, …).

Supported models

For the latest list of supported models, see the LiteLLM provider docs: https://docs.litellm.ai/docs/providers