Skip to content

Built-In Modules

Kedi ships a small set of ordinary .kedi modules. They use the same explicit exports, profiles, Python interop, tool metadata, and resolution rules as project modules.

Resolution and Shadowing

Import a bundled module by name:

> import: filesystem:
  readonlyfs
  read_text_file

A sibling filesystem.kedi takes precedence over the bundled module. Use this deliberately; an accidental same-name file changes the imported API.

errors

The errors module exports ModuleNotInstalledError:

> import: errors

```
raise ModuleNotInstalledError("httpx", required_by="HTTP reports")
```

The exception subclasses ModuleNotFoundError and formats singular or plural missing package names. Use it when a feature has a clear optional Python dependency.

require

require exports a Python-callable helper:

> import: require

```
require(["httpx", "pydantic"], required_by="Remote reports")
```

It checks import availability with Python's module discovery and returns True when all names are present. Missing modules raise ModuleNotInstalledError. It does not install packages or validate their versions.

filesystem

The filesystem module exports:

Name Behavior
read_text_file Read one UTF-8 file
write_text_file Replace/create one UTF-8 file
apply_patch Add, append, or exact-once replace text
path_exists Check file or directory existence
list_directory Return sorted direct child names
create_directory Create a directory tree
get_file_info Return basic path metadata
filesystem Read/write agent profile
readonlyfs Read-only agent profile 
> import: filesystem

@load_readme() -> str:
  = `read_text_file("README.md")`

Paths resolve against the process working directory captured when the module initializes. Every resolved path must remain beneath that root. .., absolute paths, and symlinks cannot escape it.

read_text_file refuses files larger than 1,000,000 bytes. list_directory refuses directories with more than 1,000 direct entries. These are bounded agent-tool operations, not general bulk filesystem APIs.

Files named .env or beginning .env. are treated as secrets. read_text_file(path) refuses them unless secret_files=True. In agent tool use, that argument changes the call's risk classification so approval can be required. Secret opt-in is not an authorization boundary by itself; the host approval policy still decides.

apply_patch("add", ...) refuses an existing file. update requires a nonempty old_text that occurs exactly once. append adds content. Prefer apply_patch over whole-file writes for auditable agent edits.

The public profiles intentionally omit destructive deletion tools. readonlyfs registers reads and metadata only; filesystem adds writes, patching, and directory creation.

sandbox

The optional sandbox module exports execute_code and a sandbox profile:

> import: sandbox

[result: Any] = `execute_code("sum(values)", {"values": [1, 2, 3]})`

It requires the Python package pydantic_monty. Importing the module checks that dependency immediately. execute_code(code, inputs, fail_fast=True) executes with Monty and returns the native final result; the backtick expression preserves that value. With fail_fast=False, an execution failure is returned as text.

This sandbox is for intentionally constrained generated code. It is not the execution mechanism for ordinary Kedi Python blocks, which use the configured Kedi executor.

this and Example Modules

this is a bundled demonstration/easter-egg module whose import executes its encoded output. It is not an application API.

Bundled examples such as wordle demonstrate profiles and tools and may require optional packages. Treat them as examples rather than stable general-purpose stdlib contracts. Production modules should import only the explicit built-in surface they need.