Python Interop¶

Python is Kedi's deterministic execution layer. Use it for arithmetic, validation, data shaping, library calls, control flow, and local side effects; use Kedi templates where model judgement is required.

Where Python Runs¶

Python appears in five public forms:

• inline expressions in single backticks;
• bare inline segments inside rendered text;
• one-line side-effect statements;
• fenced multiline blocks;
• the first top-level fenced block, which acts as the prelude.

Python also supplies runtime type expressions, directive values, defaults, and Python API integrations.

Values Crossing the Boundary¶

A sole Python expression in an assignment, return, or native call argument preserves its Python value:

[limit: int] = `2 * 5`

@take(values: list[str], count: int) -> list[str]:
  = `values[:count]`

Once literal Kedi text is mixed with a value, the result is rendered as str. This boundary is deliberate; do not serialize to text and parse back when a native value can cross directly.

Runtime Names¶

Python can access:

• standard built-ins allowed by the active executor;
• names created by the prelude;
• imported modules and exported values;
• generated Kedi custom types;
• compiled Kedi procedures;
• top-level Kedi values;
• parameters and visible lexical values for the current procedure.

The exact execution environment can vary by executor. Code that requires a library, filesystem, or network capability should import it explicitly and document that runtime requirement.

Type Resolution¶

Backtick type annotations evaluate in the Python type environment:

```
from typing import Literal
Stage = Literal["dev", "staging", "prod"]
```

[stage: `Stage`] = `"prod"`

Direct Kedi type syntax is preferable for static visibility. Runtime type expressions are intended for Python-defined or dynamically selected types.

Scope Model¶

Kedi values are exposed to an executed Python block as module globals. Reading a bare name works normally, but reflection and nested rebinding follow global rather than function-local semantics. New names created by one Python block do not become Kedi variables and do not persist into a later block.

Read Prelude, Globals, and Scope before writing blocks that mutate existing Kedi state or define nested Python functions.

Safety and Side Effects¶

Embedded Python is application code, not a sandbox by default. It can call libraries and perform side effects allowed by the selected executor and host process. Treat .kedi source with Python blocks as trusted code.

Keep model prompts declarative and side effects explicit. A Python block should return data or perform a clearly named operation; hidden I/O inside a value formatting expression makes tests and optimization harder to reason about.

Choosing a Form¶