# AI Commands

Provider-neutral commands for the Treasure AI LLM Proxy.

## Commands

| Command | Description |
|  --- | --- |
| [`models`](#models) | List LLM Proxy models and aliases |
| [`decision`](#decision) | Answer structured questions about text or images |


## models

Discover model IDs, capabilities, and aliases from the live LLM Proxy catalog.
Models from every family are included by default; deprecated models are hidden.
The default output is a styled model list with an aliases section. Use `--table`
for the standard tdx grid with capability columns.

```bash
tdx ai models [--all] [--provider <name>] [--feature <name>]
```

| Option | Description |
|  --- | --- |
| `--all` | Include deprecated models |
| `--provider <name>` | Filter models by provider (e.g. `anthropic`, `openai`, `google-gemini`) |
| `--feature <name>` | Filter models and aliases by feature (e.g. `v1_messages`, `v1_embeddings`, `v1_images_generations`) |
| `--table` | Use the standard tdx table format instead of the styled default |
| `--json` | Output the catalog as `{ models, aliases }` |
| `--limit <n>` | Limit displayed models and aliases in styled or table output |
| `--output <file>` | Save to a file. A `.json` file receives the JSON catalog; other files receive the styled list (or the table with `--table`) without colors |


Aliases are catalog-wide, so `--provider` only filters the model table. Aliases
without a feature restriction remain visible with `--feature`.
`--jsonl` and `--tsv` are not supported for this two-section catalog.

```bash
# All active model families
tdx ai models

# Anthropic models
tdx ai models --provider anthropic

# Models compatible with Claude Code's --model and --subagent-model
tdx ai models --feature v1_messages

# Embedding models
tdx ai models --feature v1_embeddings

# Machine-readable catalog
tdx ai models --output models.json
```

Use global `--profile` and `--site` options to select the account and region.
The catalog describes proxy models and does not guarantee that your account has
access to every model. [`tdx llm models`](/ja/treasure-code/commands/llm) lists account-specific model
settings from the LLM API instead.

## decision

Ask structured questions about text or images: yes/no probabilities
(`predicate`), one of a fixed set of options (`choice`), or a rating on an
ordered scale (`score`).

Limited access
The Decisions API is not generally available. It must be enabled for your
account; otherwise the command reports that access is denied.

```bash
tdx ai decision <questions-file> <input-file|-> [options]
```

The questions file and input source are positional. No `--batch` flag is needed:
stdin and JSON/JSONL files are processed one record at a time.

| Argument / option | Description |
|  --- | --- |
| `<questions-file>` | Questions from YAML, or JSON when the file ends in `.json` |
| `<input-file|->` | Input file, or `-` for JSON/JSONL stdin; omit when using `--input` or image-only input |
| `--input <text>` | One input text, instead of an input file; produces a single decision |
| `--input-field <name>` | Send only this exact top-level string field; otherwise send the whole row |
| `--concurrency <n>` | Maximum concurrent record requests (default: 16); use `1` for sequential processing |
| `--image <path>` | Attach a local PNG, JPEG, GIF, or WebP image; repeat for multiple images |
| `--model <id>` | Decisions model (default: `gpt-6-luna`) |
| `--json` | Collect record results as a JSON array, or output the single text/image response |
| `--jsonl` | One full result per record (the default for record input) |
| `--table` | Summary table for a plain-text file or image-only input |
| `--dry-run` | Validate input and preview requests without calling the API |
| `--output <file>` | Save output; `.json` and `.jsonl` select their respective formats |


### Input formats

- **Stdin (`-`):** one JSON object or string per non-blank line (JSONL), or a JSON
array of those records. JSONL is read incrementally; JSON arrays are buffered.
- **`.jsonl` files:** the same JSONL record protocol.
- **`.json` files:** a JSON array, or one object/string record; pretty-printed JSON
is supported.
- **Other files:** the complete UTF-8 contents are one text input, including
newlines. This form can also include `--image` attachments.


By default, the whole object row is sent as compact JSON text. Select only the
columns you intend to send to the model. `--input-field review` sends just that
field while preserving all source columns in the output; the field must be a
non-blank string. String records are sent as their contents. Null, numeric,
boolean, nested-array, and blank-string records are rejected. Blank JSONL lines
are ignored; empty streams/arrays make no requests.

Images are sent inline from local files; URLs are not supported. Images cannot
be combined with JSON/JSONL record input. For image-only input, omit the input
source: `tdx ai decision questions.yml --image receipt.png`.

Use `--dry-run` to validate a pipeline before sending requests. Record previews
contain `index`, the original `row`, and `request`; text/image previews contain
the request body with image data shortened. No API calls are made.

Interface change
The old `--questions`, `--questions-file`, and `--file` options are removed.
Move inline questions into a YAML/JSON file, and pass literal text with
`--input "text"`. Raw text on stdin must be encoded as JSON string records.

Each question needs a unique `name`, a `type`, and `instructions`. `choice`
questions list `choices` with a `value` and `description`; `score` questions list
ordered `levels` with a `label` and optional `description`:

```yaml
# questions.yml
- name: is_positive
  type: predicate
  instructions: Is the customer happy with the product?
- name: topic
  type: choice
  instructions: What is the review mainly about?
  choices:
    - { value: price, description: Cost or value for money }
    - { value: quality, description: Product quality or durability }
    - { value: shipping, description: Delivery speed or packaging }
- name: urgency
  type: score
  instructions: How urgently should support follow up?
  levels:
    - { label: low }
    - { label: medium }
    - { label: high, description: Follow up today }
```

```bash
# Process query result rows directly; no mapping or output flags are required.
tdx query 'SELECT id, review FROM mydb.feedback LIMIT 100' --jsonl \
  | tdx ai decision questions.yml -

# Validate the supplied example inputs without sending anything.
tdx ai decision examples/ai-decision-questions.yml examples/ai-decision-inputs.jsonl --dry-run

# Optional: send only the review and collect results in a JSON file.
tdx ai decision questions.yml inputs.jsonl --input-field review --output decisions.json

# Single input: one decision (full JSON response, or --table).
tdx ai decision questions.yml --input "Love it, will buy again"
tdx ai decision questions.yml review.txt --table

# Ask about an image.
tdx ai decision questions.yml --image receipt.png
```

### Results and failures

Record input defaults to ordered JSONL. Each line keeps the zero-based input
`index`, the original `row`, and the full API `response`:

```json
{"index":0,"row":{"id":1,"review":"Excellent"},"response":{"answers":[{"name":"is_positive","type":"predicate","probability":0.95}],"usage":{"input_tokens":42}}}
```

A one-record JSON source has the same envelope. `--json` produces an array of
these results after successful completion. `--input` text, plain-text files,
and image-only inputs retain a single full JSON response by default, or a summary with
`--table`. Table output is not supported for record input; TSV is not supported.

Answers are matched to questions by `name`: a `predicate` returns a
`probability`; a `choice` returns the `choice`, `probabilities`, and
`confidence`; a `score` returns the `score`, `probabilities`, and `confidence`.
A question the model declines to answer is returned as a `refusal`. `usage`
reports the input tokens billed for each request.

Each record makes a separate API call. Records are sent in groups of up to
`--concurrency` (default 16); a group's results are written in input order once
the whole group finishes, so one slow request delays its group. Processing stops on the first invalid
record or API failure, reports the index on stderr, and exits nonzero. Earlier
JSONL results remain available; already-started requests are allowed to finish
and may incur usage. JSON array output is written only after complete success.
There are no automatic retries. A malformed streaming record may be discovered
after earlier requests have run, so use `--dry-run` when validating new input.
Diagnostics never become JSONL records. Output files must not alias a questions,
input, or image file.

💎 Generated with [Treasure Work](https://github.com/treasure-work)