aux4/decision-openai

Ask the OpenAI Decisions API a typed predicate, choice, or score question about text and local images. This package intentionally does not perform arbitrary structured extraction; use aux4/ai-agent with structured output for that job.

Installation

aux4 aux4 pkger install aux4/decision-openai

Quick Start

Set an OpenAI API key, then ask a predicate question:

export OPENAI_API_KEY=sk-...
printf 'The package arrived with a cracked panel.' | aux4 decision openai ask "Does the customer report a damaged item?"

The command prints the API response, including the typed answer and probability.

Use as an aux4/decision provider

Installing this package also installs aux4/decision. Use the generic ask and run commands with --provider openai when you want the same command shape across providers:

aux4 decision ask "Is this message spam?" --provider openai --type choice \
  --options spam --options not-spam --state "Buy now, limited offer"

Repeat --state to classify multiple samples; each answer is printed in input order. If no state is provided, stdin is read as one sample. decision run supports named questions from config.yaml and returns the shared response format, including provider, scale, answers, and usage. OpenAI's scale is estimate: the returned probabilities are model estimates and should not be assumed calibrated.

For direct access to OpenAI-specific features such as image input and the raw API response, keep using aux4 decision openai ask.

Question Types

Predicate

Returns the probability that a condition is true.

aux4 decision openai ask "Does this photo show a missing screw?" --image page.png

Images are read from local files and sent as inline data URLs. Remote image URLs and file IDs are not passed to the API.

Choice

Select one value from at least two supplied options. Pass a comma-separated list or a JSON array; use value=description when the model needs more context.

printf 'The page contains a wall-anchor warning.' | aux4 decision openai ask "Which manual section is this?" --type choice --options 'assembly,safety=Wall anchoring and tip-over guidance,materials'

Score

Rate input against at least two ordered levels. Pass a comma-separated list or a JSON array. The API returns a probability distribution and a probability-weighted score.

aux4 decision openai ask "How clear is the printed part number?" --type score --levels 'low=Unreadable,medium=Partly legible,high=Clearly legible' --input "The vertical label reads 101339."

Offline Request Inspection

Use --dryRun true to print the request without requiring a key or making a network call. This is intended for deterministic tests and request review.

aux4 decision openai ask "Does this page contain an assembly operation?" --input "A panel is attached with two screws." --dryRun true

Configuration and Authentication

The package calls POST https://api.openai.com/v1/decisions with Authorization: Bearer .... Pass --apiKey for an explicit key or let it read OPENAI_API_KEY. Codex sign-in/OAuth is not treated as an API key for this public endpoint. Use --baseUrl only for an authorized compatible endpoint or a local mock in tests.

The default model is gpt-6-luna, currently the only model supported by the Decisions API. Check the official API reference for current model support before overriding it.

Limits and Safety

  • A request can include text, local inline images, or both; the API accepts at most 128 images per request.
  • Choice values are strings or booleans. Score labels are ordered by their supplied sequence.
  • Do not pass secrets in --input, question text, or image paths.
  • Keep the API key in the environment or a secret manager; command-line values can appear in shell history and process listings.

API Contract

The request and response shapes follow the official Decisions guide and create-decision reference. The Decisions API is generally available; check the official documentation for current model support and pricing before enabling live calls.