KORA

Open-source execution control for AI systems

Structure first. Inference second.

---

KORA is a standalone open-source execution control layer for AI systems. It structures requests into task graphs, runs deterministic work first, and escalates to model inference only when needed.

KORA v0.1 is terminal-first and developer-oriented.

What KORA Is

KORA sits between a request and a model call.

Instead of treating every request as an immediate prompt-to-model operation, KORA turns execution into a structured path:

• decompose work into task graphs
• run deterministic tasks first
• enforce budgets and stage boundaries
• validate outputs against explicit structure
• escalate to model inference only when deterministic execution is insufficient
• record telemetry for inspection and replay

KORA provides execution control before model invocation.

Install

Target install path for v0.1:

pip install kora

Homebrew install path for v0.1:

brew install kora

For local development in this repository:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Quickstart

Terminal-first v0.1 first-run flow:

kora examples list
kora run hello_kora
kora run retry_demo
kora run direct_vs_kora -- --offline
kora telemetry --input docs/reports/sample_telemetry_input.json

Equivalent local-development commands in this repository:

python3 -m kora examples list
python3 -m kora run hello_kora
python3 -m kora run retry_demo
python3 -m kora run direct_vs_kora -- --offline
python3 -m kora telemetry --input docs/reports/sample_telemetry_input.json

Online variant:

kora run direct_vs_kora

Current examples available in this repository:

• examples/hello_kora
• examples/direct_vs_kora
• examples/retry_demo
• examples/real_workload_harness
• examples/stress_test

Use --offline for the reproducible first-run demo path without OpenAI credentials. telemetry can be run immediately with the committed sample input at docs/reports/sample_telemetry_input.json, or with a JSON artifact generated by a prior run or report flow. After the first-run flow and telemetry summary, see docs/benchmark-real-app.md for the next-step benchmark/report path via real_workload_harness.

What KORA Does

KORA structures requests before inference.

In practice, that means:

• separating deterministic work from inference work
• making model invocation conditional instead of default
• enforcing validation and retry boundaries around uncertain steps
• exposing telemetry so execution can be measured, compared, and debugged

KORA does not try to make models smarter. It controls when, why, and how they are used.

Why KORA Exists

Many AI applications still default to a simple pattern:

request -> prompt -> model -> output

That pattern is easy to start with, but it makes several problems harder to control:

• unnecessary model calls
• unstable latency envelopes
• weak execution visibility
• fragile output handling
• limited separation between deterministic logic and probabilistic logic

KORA exists to make execution structure explicit. If part of a request can be handled deterministically, it should be handled deterministically first. Inference should be an escalation path, not the baseline.

Included in v0.1

• execution-layer primitives for structured AI workloads
• task graph and scheduler foundations
• deterministic-first execution and verification components
• telemetry summarization and reporting
• repository examples covering direct-vs-structured execution, retries, and stress behavior
• terminal-first developer workflow

Not Included in v0.1

• GUI-first product
• KORA Studio in the main release
• chatbot interface
• desktop AI app
• model hosting or model serving engine

Who KORA Is For

KORA is for developers and researchers building AI systems that need stronger execution control.

Typical users include:

• engineers who want deterministic preprocessing and validation before model calls
• teams comparing direct inference against structured execution
• developers who need telemetry and bounded execution semantics
• researchers exploring decomposition, verification, and escalation strategies

What KORA Is Not

KORA is not:

• a chatbot
• a desktop AI app
• a ChatGPT alternative
• a model serving engine
• another agent wrapper that only forwards prompts to providers
• a dependent layer inside another platform

KORA is a standalone open-source execution control layer.

Roadmap

Near-term work after v0.1:

• stabilize the terminal CLI around init, run, examples, and trace flows
• expand example coverage around structured execution patterns
• improve packaging and distribution for standard developer install paths
• deepen documentation for task graphs, execution semantics, and telemetry inspection
• continue benchmark and validation work for deterministic-first execution

Future work may include KORA Studio, but it is outside the main v0.1 release scope.

License

Apache-2.0. See LICENSE.