Kedi Programming Language¶

Kedi is a typed orchestration language for building LLM programs whose prompts, dataflow, structured outputs, tools, tests, and agent configuration live in one readable source format. Use it through .kedi programs or embed the same runtime semantics through its Python API.

It combines runtime substitution and typed output capture with reusable procedures, deterministic Python, model and agent configuration, tools, MCP, skills, approvals, subagents, tests, evaluations, and prompt optimization. Model calls run through framework adapters such as Pydantic AI, DSPy, or LangChain, or harness adapters such as Codex, Claude, and ACP.

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.

~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.

Choose a Starting Point¶

• New to Kedi: begin with Start with Kedi.
• Learning the DSL: use the Core Language guide.
• Embedding Kedi in Python: use the Python API.
• Building tool-using or delegated agents: use Agentic Engineering.
• Looking up exact syntax or behavior: use the Reference.

Core Language, Python API, and Agent Adapters¶

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.