Prompt Template

Kodexa prompt resources

A prompt resource is org-scoped, reusable prompt text stored in kdxa_prompts. That is all it is. It carries no model choice, no temperature, no token limit and no output schema — those belong to whoever invokes it. It is also not how you steer document extraction (see "Extraction prompts" below).

Its metadata column is opaque JSON. The server stores whatever you send and hands it back flattened to the top level, so any key you invent will persist and round-trip while being read by nothing. Round-tripping is not evidence a field works. Only the keys below are read by anything.

Consumer detail, variable tables, overrides and troubleshooting: references/consumers.md.

The shape that works

type: prompt-template                  # see "Deploying" — never `promptTemplate`
slug: invoice-extraction-prompt        # required, 3–100 chars; derived from name if omitted
orgSlug: acme-corp                     # target org (or pass --org-slug)
name: Invoice Extraction Prompt
description: Extracts header fields from a vendor invoice

prompt: |                              # read by the Go consumers and the chat picker
  Extract invoiceNumber, invoiceDate and totalAmount from the invoice below.
  Return JSON. Use null for anything not explicitly present.

  {invoiceText}

promptTemplate: |                      # read by the Python consumers
  Extract invoiceNumber, invoiceDate and totalAmount from the invoice below.
  Return JSON. Use null for anything not explicitly present.

  {invoiceText}

templateType: FSTRING                  # FSTRING | MUSTACHE — required by the Python renderer

Everything is flat at the top level. The whole request body is stored as the metadata blob, so a body nested under a metadata: block lands one level down inside it. The GET response flattens that back out, so it still looks right in Studio — but the two Go consumers read the stored blob directly and never see the key. It saves, returns 201, and breaks only at run time.

Which key each consumer reads — the failure that ships silently

Two different code paths look for two different keys, and neither errors loudly when its key is absent.

So a prompt carrying only promptTemplate still "works" from an LLM step — it just sends the model {"slug":"...","name":"...","promptTemplate":"...","templateType":"FSTRING",...} and you get a confused answer, not an error. Anything reached by promptRef / promptTemplateRef must carry a top-level prompt:. Author both keys when in doubt.

template is not an escape hatch: on every metadata resource template is the reserved boolean "is this a template resource" flag, so the Go fallback's template branch can never match a string — and a string sent there fails the request body decode outright.

Template dialects

templateType selects the renderer. There are exactly two, and neither is Handlebars — no {{#each}}, no {{this.field}}.

Both Go paths (the LLM step and the organization LLM endpoint) render FSTRING only — they do a plain {key} substitution regardless of what templateType says. templateType matters to the Python renderer, which raises on any value other than FSTRING or MUSTACHE, including absent.

There is no global variable vocabulary. A placeholder resolves only if the caller puts that key in the parameter map it passes. See references/consumers.md for the variables each caller supplies.

Using a prompt from an activity plan

promptTemplateRef is a bare slug, resolved against kdxa_prompts within the plan's own organization. It is not org/slug and not a prompt-template:// URI.

- slug: classify-invoice
  type: LLM                            # legacy AI_PROMPT also dispatches; AI_PLANNER does not
  name: Classify the invoice
  promptTemplateRef: invoice-extraction-prompt   # bare slug — OR promptBody, never both
  llmModelName: LARGE                  # SMALL | LARGE | a literal gateway model id
  promptVariables:                     # JSONata over {context, enrichment, steps}
    invoiceText: "steps.`load-document`.text"    # backticks — see below
  outputMapping:
    invoiceNumber: "invoiceNumber"     # JSONata over the parsed response

A step with neither promptBody nor promptTemplateRef fails outright, and so does a promptTemplateRef that resolves to nothing. Backtick any hyphenated step slug inside a promptVariables / outputMapping expression — JSONata reads the bare hyphen as subtraction, the variable resolves to nothing, and the {placeholder} is left in the prompt with no error (only conditionExpr is checked for this). Full field list in references/consumers.md; the step graph itself is the activity-plan skill's subject.

Chat pre-built prompts

An org-wide prompt appears in the Studio chat panel's "From prompt" picker when it carries a non-empty prompt body plus a context:

type: prompt-template
slug: summarise-this-task
orgSlug: acme-corp
name: Summarise this task              # doubles as the created chat channel's name
prompt: |
  Summarise the current task, listing open exceptions first.
context: task                          # "task" | "project" — which screen offers it
category: Triage                       # picker grouping; omitted → "General"

The picker lists prompts from the current organization only — publicAccess does not surface a prompt in another org's picker.

Extraction prompts do not live here

Per-data-element extraction guidance is the taxon's semanticDefinition on a data definition, not a prompt resource. typeFeatures.allowTemplating: true on a taxon additionally renders that definition as a Jinja2 template — a third dialect, with exactly three context roots (external_data, metadata, knowledge); undefined lookups render empty rather than raising. Per-vendor overrides are knowledge items of the seeded kodexa/taxon-semantic-definition-customization type, not a bespoke item type of your own — see references/consumers.md, then data-definition and knowledge-system.

Deploying

• Files live in <metadata_dir>/prompt-templates/<slug>.yaml; the manifest key is prompt-template:.
• kdx apply -f <file> needs type: (or --type) plus slug and orgSlug (or --org-slug).
• CRUD is /api/prompts (+ /{id}). Org-scoped, unique on (organization, slug), soft-deleted.
• ${org} in the file is substituted with the target org on push; leftovers are a hard error.
• type is excluded from the push comparison: a type-only edit never re-pushes. Change something else too.

Only prompt and prompt-template are valid type values. The CLI also accepts promptTemplate / prompttemplate / prompt-templates / promptTemplates as file-type aliases, but the value is persisted verbatim and the resource's own uri is built from it — so a camelCase type yields promptTemplate://acme-corp/my-prompt, which POST /api/resolve rejects as an unsupported scheme, and any client that follows that uri fails. type: prompt is what the server defaults to and what the shipped kodexa prompts carry, but it is not a CLI alias, so a file typed prompt bypasses the sync engine and loses ${org} resolution. prompt-template is the only value correct on both sides. Use it.

Declared but inert

Persisted, returned by the API, present in existing files — and read by nothing:

Common mistakes

Prompt engineering that holds up

• Name the format, don't imply it. "Return the date as YYYY-MM-DD, e.g. 2026-03-15".
• Show two or three worked examples, including a messy one: "Invoice #12345" → 12345.
• Say what to do when the value is absent. "Return null; do not infer or guess." Without this the model invents plausible values.
• Ask for JSON explicitly and show the object you want back, then shape it downstream with the step's outputMapping. There is no schema-constrained decoding to lean on.
• One prompt, one job. Extraction, classification and validation as separate prompts are easier to evaluate and to override than one prompt doing all three.
• Keep vendor-specific quirks out of the body — put them in knowledge overrides.

Cross-references

• activity-plan — the LLM step that invokes a prompt, its dependencies and outputs
• knowledge-system — knowledge sets, feature expressions, and prompt-override items
• data-definition — semanticDefinition, allowTemplating, promptStrategy
• module — packaging SKILL.md / SYSTEM_PROMPT.md into a skill module
• kdx-cli — kdx apply, kdx sync push/pull, manifests