LLM llm

LLM utilities — chat, translation, image OCR, corpospeak rewriting, and session history
Pixelbadger Toolkit — pbtk llm — ← all topics

Prerequisites

All commands in this topic call the OpenAI API. The OPENAI_API_KEY environment variable must be set before running any command.

$ export OPENAI_API_KEY=sk-...

By default all commands use the gpt-5-nano model. Pass --model to override.

Session History

Every llm command automatically persists conversation history — including the system prompt — to a shared SQLite database at ~/.pbtk/history.db. Each invocation creates a new session and stores the full message exchange along with token usage counts.

Sessions are identified by an integer ID that is consistent across all commands, making it possible to inspect history from chat, translate, ocaaar, and corpospeak in a single unified view.

Use llm history list to see all sessions and llm history delete to remove one.

chat

Sends a message to the LLM chat completion API and prints the response. Every invocation is recorded as a session in the history database. Ongoing conversations are resumed by passing the session ID returned from a previous call.

$ pbtk llm chat --message "Hello, how are you?"
$ pbtk llm chat --message "Continue our conversation" --session-id 42 --model gpt-4o-mini
$ pbtk llm chat --message "Solve this hard problem" --reasoning-effort high
flowchart LR MSG["--message"] --> COMP["Send to\nLLM chat API"] SID["--session-id\n(optional)"] -->|"load prior\nmessages"| COMP RE["--reasoning-effort\n(optional)"] --> COMP COMP --> RESP(["stdout: assistant reply"]) COMP --> HIST["Session stored\nin ~/.pbtk/history.db"] COMP --> SID_OUT(["stderr: Session: <id>"])

When --session-id is omitted a new session is created. When provided, all prior messages from that session are loaded and prepended to the API request so the model has full context. The session ID is always written to stderr after the call — capture it to continue the conversation later.

Sessions created by other commands (e.g. translate) can be continued with chat --session-id since all commands share the same history database.
OptionRequiredDefaultDescription
--messageYes—The user message to send
--session-idNo—Session ID to continue a previous conversation
--modelNogpt-5-nanoModel to use
--reasoning-effortNo—Reasoning effort level for o-series models: low, medium, high

translate

Translates a given text into a specified target language using the LLM. The output is the translated text printed to stdout. Each invocation creates a new history session.

$ pbtk llm translate --text "Hello, how are you?" --target-language Spanish
flowchart LR T["--text"] --> CALL["LLM\nchat completion"] LANG["--target-language"] --> CALL CALL --> OUT(["stdout: translated text"]) CALL --> HIST["Session stored\nin ~/.pbtk/history.db"]
OptionRequiredDefaultDescription
--textYes—The text to translate
--target-languageYes—Target language (e.g. Spanish, French, Japanese)
--modelNogpt-5-nanoModel to use

ocaaar

OCR as a Pirate. Sends an image file to the LLM vision API, extracts any text found in the image, and returns it rewritten in pirate speak. Each invocation creates a new history session; the image is recorded as a reference path rather than binary data.

$ pbtk llm ocaaar --image-path ./sign.jpg
flowchart LR IMG["--image-path\n(local image file)"] --> ENC["Base64 encode\nimage"] ENC --> CALL["LLM vision\nchat completion\n(extract text + pirate-speak prompt)"] CALL --> OUT(["stdout: pirate-speak text"]) CALL --> HIST["Session stored\nin ~/.pbtk/history.db"]
The image is base64-encoded and sent inline with the API request. Supported formats are those accepted by the OpenAI vision API: JPEG, PNG, GIF, and WebP.
OptionRequiredDefaultDescription
--image-pathYes—Path to the image file to process
--modelNogpt-5-nanoModel to use (must support vision)

corpospeak

Rewrites source text in the communication style appropriate for a chosen enterprise audience, optionally learning from example messages to match an individual's idiolect. Input can be a literal string or a file path. Each invocation creates a new history session.

$ pbtk llm corpospeak --source "API performance is great" --audience csuite
$ pbtk llm corpospeak --source "New feature deployed" --audience engineering --user-messages "Hey team" "Let's ship this"

Audiences

csuite

Executive language, strategic framing.

engineering

Technical, precise, low jargon.

product

User-focused, outcome-driven.

sales

Value propositions, persuasive tone.

marketing

Brand voice, engaging copy.

operations

Process-oriented, practical.

finance

Metrics-focused, precise numbers.

legal

Formal, risk-aware language.

hr

People-centric, inclusive tone.

customer-success

Empathetic, supportive language.

flowchart LR SRC["--source\n(text or file path)"] --> CALL["LLM\nchat completion\n(audience-tuned prompt)"] AUD["--audience"] --> CALL UM["--user-messages\n(optional idiolect examples)"] --> CALL CALL --> OUT(["stdout: rewritten text"]) CALL --> HIST["Session stored\nin ~/.pbtk/history.db"]

When --user-messages is provided, the examples are included in the prompt so the model can infer and mimic the writer's personal style. Each value can be a literal string or a path to a file containing example text. Multiple values are accepted.

OptionRequiredDefaultDescription
--sourceYes—Source text to rewrite (or file path)
--audienceYes—Target audience slug (see list above)
--user-messagesNo—Example messages to learn idiolect from (text or file paths, repeatable)
--modelNogpt-5-nanoModel to use

history list

Prints a tabular summary of all stored sessions in reverse chronological order, showing the session ID, originating command, creation timestamp, and cumulative token usage.

$ pbtk llm history list

Example output:

ID     Command         Created (UTC)             Tokens (in/out)
--------------------------------------------------------------------
3      corpospeak      2026-05-28 14:30:00       200/90
2      translate       2026-05-28 11:15:00       80/35
1      chat            2026-05-28 09:00:00       350/120

The database file is at ~/.pbtk/history.db. It is created automatically on first use and shared by all llm commands.

history delete

Deletes a session and all of its stored messages from the history database. This operation is permanent.

$ pbtk llm history delete --session-id 42
OptionRequiredDefaultDescription
--session-idYes—ID of the session to delete

Command Reference

Command Required options Optional options Output
llm chat --message --session-id --model --reasoning-effort Assistant reply to stdout; session ID to stderr
llm translate --text --target-language --model Translated text to stdout
llm ocaaar --image-path --model Pirate-speak OCR result to stdout
llm corpospeak --source --audience --user-messages --model Rewritten text to stdout
llm history list — — Session table to stdout
llm history delete --session-id — Confirmation message to stdout