---
name: llm
description: 'Text from language models (one provider per tool, the API key declared as a secret and the provider''s host fixed; llm/local for a model server on this machine, no key) and llm/prompt, which composes what they read. Tools: cohere, local, prompt. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet
  tools: cohere.py, local.py, prompt.py
---

# LLM

Text from language models (one provider per tool, the API key declared as a secret and the provider's host fixed; llm/local for a model server on this machine, no key) and llm/prompt, which composes what they read.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/cohere.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `cohere.py`

One Cohere chat completion (api.cohere.com/v2/chat) from a prompt file or inline prompt, with an optional system prompt file, written to response.md. The host is fixed -- there is no base-URL parameter -- so the API key can only ever be sent to Cohere. seed makes sampling best-effort reproducible; stdout is a one-line summary (model, seed, tokens, finish reason), never the completion.

Use when a workflow step needs text generated by a language model -- a poem, a caption, a summary -- from a prompt file, and a Cohere API key (free trial keys work) is available.

```sh
<skill-dir>/cohere.py [-p prompt="<prompt>"] [-p prompt_text="<prompt_text>"] [-p system="<system>"] [-p model=command-a-03-2025] [-p temperature=0.7] [-p seed=42] [-p max_tokens=1024] [-p thinking_budget="<thinking_budget>"] --output response.md
```

Parameters:
- `prompt` (file, optional) — Prompt file (the user message)
- `prompt_text` (string, optional) — Inline prompt, when there is no prompt file
- `system` (file, optional) — System prompt file
- `model` (string, optional, default `command-a-03-2025`) — Cohere model id
- `temperature` (string, optional, default `0.7`) — Sampling temperature, 0 to 1
- `seed` (string, optional, default `42`) — Sampling seed; same seed and inputs give best-effort identical output
- `max_tokens` (string, optional, default `1024`) — Maximum tokens to generate (a thinking model's thinking counts)
- `thinking_budget` (string, optional) — For a thinking model (e.g. command-a-plus-05-2026): the most tokens it may think before answering, so the answer fits max_tokens; empty: the model's default
- `COHERE_API_KEY` (secret, required) — read from the caller's environment, never passed with `-p`; Cohere API key (trial keys: 1,000 calls/month)

Outputs:
- `response.md` — copy out with `--output response.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `local.py`

One chat completion from a local, OpenAI-compatible model server (LM Studio, llama.cpp, Ollama) from a prompt file and an optional system prompt file, written to response.md; no key. With think=false a reasoning model is asked to answer at once (an empty think block is prefilled), and any think block left in the answer is removed. stdout is a one-line summary, never the completion.

Use when a workflow step needs text from a language model running on this machine (LM Studio, llama.cpp, Ollama): no key, no cloud.

```sh
<skill-dir>/local.py [-p prompt="<prompt>"] [-p prompt_text="<prompt_text>"] [-p system="<system>"] -p model="<model>" [-p endpoint="<endpoint>"] [-p temperature=0.7] [-p seed=42] [-p max_tokens=400] [-p think=false] [-p timeout=900] --output response.md
```

Parameters:
- `prompt` (file, optional) — Prompt file (the user message)
- `prompt_text` (string, optional) — Inline prompt, when there is no prompt file
- `system` (file, optional) — System prompt file
- `model` (string, required) — The model's id on the server, e.g. qwen/qwen3.8-27b
- `endpoint` (string, optional) — The server's chat completions URL as the container reaches it; empty: LM Studio on this machine (host.docker.internal, port 11234)
- `temperature` (string, optional, default `0.7`) — Sampling temperature
- `seed` (string, optional, default `42`) — Sampling seed
- `max_tokens` (string, optional, default `400`) — Most tokens to generate
- `think` (string, optional, default `false`) — Let a reasoning model think before it answers
- `timeout` (string, optional, default `900`) — Seconds to wait for the answer: a local server may be busy with another agent's call, or loading the model

Outputs:
- `response.md` — copy out with `--output response.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `prompt.py`

The two files an LLM step reads, for llm/cohere's prompt and system: prompt.md (the task, its subject, reference text, constraints) and system.md (the voice or house style, examples). Reference text and examples are length-capped and fenced as material, never instructions, so an earlier step's output (headlines, a transcript, a page) cannot rewrite the task. For poems, poem/prompt knows the forms.

Use as the step before llm/cohere when a request combines a task with text an earlier step produced or with a stored style guide, or whenever the prompt itself should be its own reproducible step.

```sh
<skill-dir>/prompt.py -p task="<task>" [-p subject="<subject>"] [-p context="<context>"] [-p context_file="<context_file>"] [-p context_label=Reference material] [-p constraints="<constraints>"] [-p style="<style>"] [-p style_file="<style_file>"] [-p examples_file="<examples_file>"] --output prompt.md
```

Parameters:
- `task` (string, required) — What the model must produce, in one or two sentences
- `subject` (string, optional) — What it is about, with the concrete names, numbers and events to keep
- `context` (string, optional) — Reference text to work from, inline (often an earlier step's output); context_file for a file
- `context_file` (file, optional) — Reference text to work from, as a file (e.g. news/headlines' headlines.md)
- `context_label` (string, optional, default `Reference material`) — What the reference text is, named in prompt.md
- `constraints` (string, optional) — Hard requirements such as length, form or things to avoid; newline- or semicolon-separated
- `style` (string, optional) — The voice or house style for system.md, inline; style_file for a file
- `style_file` (file, optional) — The voice or house style for system.md, as a file
- `examples_file` (file, optional) — Examples of the wanted output (their voice is borrowed, never their content)

Outputs:
- `prompt.md` — copy out with `--output prompt.md[=<host path>]`
- `system.md` — copy out with `--output system.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
