Skip to content

Start with Kedi

What You Will Build

The first workflow accepts a topic from the command line, asks a model for a short structured brief, and returns the captured text:

@brief(topic: str) -> str:
  >> A two-sentence brief for a software engineer about <topic> is [summary: str].
  = <summary>

= <brief(`args.topic`)>

This is intentionally small, but it demonstrates the main execution model:

  1. args.topic is passed to brief as a native Python string.
  2. <topic> substitutes that runtime value into the prompt.
  3. [summary: str] captures one typed field from the model response.
  4. = <summary> returns its rendered text.

Prerequisites

  • Python 3.10 or newer;
  • a Kedi installation;
  • credentials required by the selected model provider;
  • optionally, an agent harness installation when using Codex, Claude, or ACP.

Parsing does not contact a provider. Use it to validate syntax before setting up credentials.

The Smallest Useful Program

For a fixed prompt with one result, capture the output explicitly:

>> The importance of idempotency, explained in one paragraph, is [answer: str].
= <answer>

The typed field keeps the response and makes its contract visible to the adapter. A plain template without an output field does not keep the response:

>> In one paragraph, idempotency matters because

That form is appropriate only when the call's side effects or trace matter and the text is intentionally discarded. It is usually the wrong choice for a user-facing answer.

Run, Parse, and Validate

Save the first example as brief.kedi, then parse it:

kedi parse brief.kedi

Run it with an application argument:

kedi brief.kedi --topic "distributed locks"

Unknown CLI options after the source file are normalized into the reserved args object. For example, --dry-run becomes args.dry_run. The args binding cannot be reassigned from Kedi or embedded Python.

You can also parse inline source:

kedi -p -c "@broken("

Parse-only mode checks syntax and structural rules. Compilation and execution can additionally fail on type resolution, backend capability validation, provider errors, or approval decisions.

Where to Go Next