prompt = f"""You are a support agent
for {product}. Be concise.

Customer wrote: {message}
"""
if order_id:
    prompt += f"Order: {order_id}"

msg = {"role": "user", "content": prompt}
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[msg],
)
text = resp.choices[0].message.content

name: support_reply
description: Support reply, house style
version: 1.0.0
messages:
  - role: system
    template: |
      You are a support agent for
      {{ product }}.
      {% include '_partials/style.j2' %}
  - role: user
    template: |
      Customer wrote: {{ message }}
input_schema:
  product: str
  message: str

Install

pip install 'promptkit-core[openai]'      # or [anthropic] · [ollama] · [all]

The base install ships no HTTP client and no provider SDK. Loading, rendering, validation, composition, linting and cost estimation all work with nothing network-shaped in your dependency tree.

Catch the typo before you pay for it

Fat-finger it — {{ prodcut }} in the template while the schema still says product. An f-string would ship that to production. Here it does not get past the gate:

$ promptkit lint support_reply.yaml
support_reply
  PK001 'prodcut' is used but not declared (prodcut)
  PK002 'product' is declared but never used (product)

2 finding(s)

Exit code 1, so CI stops. Fix it, and the rest of the loop is free and offline:

$ promptkit lint support_reply.yaml
✓ support_reply

$ promptkit render support_reply.yaml --set product=Acme --messages
system
You are a support agent for Acme.
Answer in plain language. Prefer short sentences.

user
Customer wrote: placeholder

$ promptkit cost support_reply.yaml --model gpt-4o-mini
support_reply with gpt-4o-mini
Input tokens: 21 (exact)
Output tokens: 500 (assumed)
Estimated cost: $0.000303

Anything you leave out is filled with a placeholder, so you can render and price a prompt before you have real inputs. Not one of those commands needed an API key.

From Python

from promptkit import load_prompt, run_prompt
from promptkit.engines.openai import OpenAIEngine

prompt = load_prompt("support_reply.yaml")

with OpenAIEngine() as engine:
    completion = run_prompt(prompt, {"product": "Acme", "message": msg}, engine)

completion.text  # the reply
completion.usage.prompt_tokens  # 241, straight from the provider
completion.usage.estimated  # False — measured, never quietly guessed
engine.cost_of(completion)  # 8.895e-05

Need JSON back? Hand it a Pydantic model and get a validated object, with automatic re-prompting when the model gets it wrong:

result = run_structured(prompt, inputs, engine, output_model=Invoice)
result.value.total  # a float, and your type checker knows it

What you get

The CLI

Variables come from --set key=value, --vars '{"json": true}', or --vars-file. --set coerces to the type your schema declares.

Not an agent framework

Tool calling, agent loops, conversation memory and RAG are permanently out of scope — a boundary, not a gap. Nothing traps you: engine.client is the real SDK client and completion.raw the real provider response, so dropping down is one attribute away.

Coming from 0.1.x

Your prompt files load unchanged — asserted per-file by the test suite. Most code needs two edits, and a codemod handles the mechanical ones:

python -m promptkit.codemod your_package/          # dry run, prints a diff
python -m promptkit.codemod your_package/ --write  # apply it

Details in the upgrade guide.