The Kedi language¶

Why Typed LLM Programs¶

Prompts are useful for fuzzy transformations; Python is useful for deterministic logic. Kedi keeps both in one dataflow without pretending they are the same thing.

This definition is a fragment: it does not call a model until the procedure is invoked. The first program supplies model selection, command-line inputs, and a complete executable entry point.

~Ticket(category: str, urgency: int)

@classify(message: str) -> Ticket:
  >> The classification of support message <message> is [ticket: Ticket].
  = `ticket`

<message> is a substitution: Kedi renders an existing value into the prompt. [ticket: Ticket] is an output capture: the adapter asks the model for a value matching the generated schema. = `ticket` returns the native Ticket object. Writing = <ticket> instead would stringify it.

Use output capture whenever a model result participates in the program's dataflow, including plain text. A str capture still gives the adapter an explicit output contract:

@summarize(message: str) -> str:
  >> A two-sentence summary of <message> is [summary: str].
  = <summary>

Raw capture is an escape hatch for deliberately unstructured text, not the default form of a Kedi model call.

Typed does not mean factually correct. Validation checks the declared contract; it cannot prove that a model's answer is true. Deterministic checks, evidence, and evaluation address different questions.

Choose a Starting Point¶

• New to Kedi: begin with Learn Kedi.
• Learning the DSL: use the Language Reference.
• Embedding Kedi in Python: use the Python API.
• Building tool-using or delegated agents: use Agents and Orchestration.
• Looking up exact syntax or behavior: use the Reference.

After the first program, use Projects and Execution to split it across files, then choose a task from the Cookbook. You do not need tools, profiles, or delegated agents to use typed templates.

Language, Python API, and Model Integrations¶

The same runtime semantics are available through two authoring surfaces:

• .kedi files are best for workflows where prompts, types, procedures, tests, and profiles should be visible together.
• @kedi.query and @kedi.bind are best when Python owns the public function signature and Kedi provides the implementation.

Adapters are boundary implementations, not alternative Kedi dialects. The language semantics stay stable, while capability validation reports whether a selected backend supports structured output, tools, MCP, approvals, or subagents.

Documentation Conventions¶

Code blocks marked kedi are Kedi source. Backticks have two different roles:

• single backticks, such as `items`, evaluate a Python expression;
• triple backtick blocks execute multiline Python.

The documentation distinguishes:

• substitution (<value>), which reads and renders a value;
• output capture ([value: Type]), which asks the model to produce a value;
• native return (= `value`), which preserves the Python object;
• rendered return (= <value>), which returns text.

Those choices are called out in examples because replacing one with another can change types, validation, or whether a model response is retained.