KORA

Open-source execution control for AI workloads.

Most AI apps call the model too soon.

Every request becomes a prompt. Every prompt becomes tokens. Every token becomes latency, cost, and infrastructure pressure.

KORA turns AI requests into structured execution paths before inference: task graphs, deterministic-first execution, validation, telemetry, and model escalation only when needed.

Before:

request -> prompt -> model -> output

After:

request -> task graph -> deterministic path -> validation -> model escalation -> telemetry

Structure first. Inference second.

Prerequisites

KORA uses pyproject.toml-based Python packaging.

• Packaged support: Python 3.11 or newer, as declared in pyproject.toml.
• Observed local result: Python 3.9.6 has been confirmed to run the offline direct_vs_kora example in one user environment.
• Treat Python 3.9.6 as an observed troubleshooting datapoint, not as the advertised package support floor until clean Python 3.9 compatibility testing is completed.
• Before making Python-version compatibility assumptions, check the active interpreter with python3 --version.
• VS Code's selected interpreter may differ from terminal python3; make sure both point to the intended environment when debugging setup issues.
• Upgrade pip, setuptools, and wheel before editable install so local tooling understands modern pyproject.toml builds.

Check your local tools first:

python3 --version
python3 -m pip --version
which python3

3-Minute Local Run

For local development in this repository:

python3 --version

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e ".[dev]"

If editable install reports that setup.py, setup.cfg, or install metadata is missing, first verify that your checkout is current:

git remote -v
git fetch origin
git checkout main
git pull origin main
ls pyproject.toml

If pyproject.toml is still missing after pulling, re-clone from https://github.com/Krako-Labs/KORA.git.

Run the CLI and first offline demo:

python3 -m kora --help
python3 -m kora examples list
python3 -m kora run hello_kora -- --offline
python3 -m kora run direct_vs_kora -- --offline

Inspect the output to see how KORA changes a direct model-first path into a controlled execution path.

Local Setup Troubleshooting

If first-run setup fails after a system restart, Python upgrade, VS Code interpreter change, or virtual environment change, start by collecting the active environment:

python3 --version
python3 -m pip --version
python3 -m pip show pydantic
which python3

TypeError: unsupported operand type(s) for |: 'ModelMetaclass' and 'ModelMetaclass'

This usually indicates a local Python, virtual environment, pip, setuptools, or dependency compatibility problem. Python 3.9.6 has been observed to run the offline direct_vs_kora example in one user environment, but packaged support is currently Python 3.11 or newer. First rebuild the local environment with current build tooling:

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate

python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e ".[dev]"
python3 -m kora run hello_kora -- --offline
python3 -m kora run direct_vs_kora -- --offline

Do not assume this error means a newer Python version is unsupported. Test Python 3.9, 3.10, 3.11, or 3.12 in clean environments before changing the package support floor.

Editable install says setup.py or setup.cfg is missing

KORA uses pyproject.toml-based packaging, so a missing setup.py or setup.cfg message usually means the local pip/build tooling is too old or the virtual environment is stale. Confirm pyproject.toml exists, upgrade build tooling, then reinstall:

ls pyproject.toml
python3 -m pip install --upgrade pip setuptools wheel
python3 -m pip install -e ".[dev]"

VS Code interpreter differs from terminal python3

If KORA works in Terminal but fails in VS Code, compare the selected VS Code interpreter against terminal python3:

which python3
python3 --version
python3 -m pip --version

Select the repository .venv interpreter in VS Code, then reopen the terminal or restart the Python language server before rerunning the examples.

What KORA Does

KORA sits between an AI request and a model call.

It helps developers:

• turn requests into explicit task graphs
• run deterministic work before inference
• validate outputs before escalation
• make model calls conditional instead of default
• record telemetry around each execution path
• compare direct model-first execution against controlled execution

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

Current Alpha Evidence

KORA reduced model invocations by 80% in a reproducible deterministic-heavy benchmark workload.

This result is based on the current deterministic-heavy alpha benchmark and should not be interpreted as a universal production cost-reduction claim.

For methodology, counters, artifact policy, and reproduction commands, see:

• Runtime evidence reviewer guide
• Benchmark artifact policy
• Benchmark result summary
• Claim registry
• Validation roadmap

What We Are Testing Next

1. Runtime-integrated benchmark paths with real model calls
2. Customer-support triage workloads
3. RAG answer-routing workloads
4. Agent budget-guard workloads

We are looking for early developers and AI app teams who want to test KORA against real workloads.

KORA validation roadmap.

See the KORA validation roadmap for the measurement plan.

See the real model-call validation design for the next measurement path.

KORA includes a local no-network validation path that measures model-call routing without requiring API keys or external providers.

Customer-support triage local validation is available as a no-network example.

Local no-network validation examples can generate Markdown reports with --report-md.

Local no-network validation examples support --adapter local_validation by default and explicit --adapter local_runtime for the deterministic in-process local runtime stub.

Reviewer packet: local no-network validation.

The reviewer packet includes the no-network baseline checklist, adapter-selection commands, fail-closed safety checks, and local Markdown report generation examples.

Local model adapter design: provider-neutral local runtime path.

Real provider adapter design-only packet: future provider boundary.

Real provider test harness design-only packet: dry-run provider validation contract.

Help Test KORA

Good candidate workloads:

• customer-support triage
• repetitive RAG workflows
• agent workflows with budget or escalation rules
• deterministic-heavy backend workflows
• LLM apps with high repeated request patterns

To participate, follow the contact and discussion routes.

To contribute code or docs without write access to this repository, use the fork-based pull request workflow. Direct write access is not required to contribute through pull requests.

How to help test KORA with a real workload.

See Help Test KORA for the workload submission template.

When proposing workloads for KORA validation, use only synthetic or sanitized examples. Do not include secrets, API keys, private user data, proprietary datasets, raw provider responses, or production logs.

Documentation

Start with the KORA Documentation Index for the developer path:

• Start
• Understand
• Run
• Inspect evidence
• Help test
• Contribute

Useful entry points:

• Examples directory
• Telemetry and observability counters
• Public language guide
• KORA Studio planning docs
• Contact and discussion routes
• Community manager guide
• Contributing guide

For branch naming, pushing your work, and opening a pull request into main, see the branch and PR workflow.

For support-channel problems or bugs, start with a reproducible report using the bug report template before attempting a code change.

Install

Target package install path:

pip install kora

Homebrew install path:

brew install kora

For the current repository alpha, use the editable local install in the 3-Minute Local Run.

Current Examples

Current examples available in this repository:

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

Use --offline for reproducible first-run paths without OpenAI credentials.

Alpha Scope

Included in the alpha surface:

• 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, stress behavior, and runtime evidence flow
• terminal-first developer workflow

Not included in the alpha surface:

• GUI-first product
• chatbot interface
• desktop AI app
• model hosting or model serving engine
• production cost-reduction proof
• real API-cost reduction proof
• energy reduction evidence

What KORA Is Not

KORA is not:

• a chatbot
• a desktop AI app (not yet)
• a hosted chat-product alternative
• a model serving engine
• another agent wrapper that only forwards prompts to providers

KORA is a standalone open-source execution-control layer for AI workloads.

Contribute

Want to contribute? Start with:

• Contributor pathway
• Contact and discussion routes
• CONTRIBUTING.md
• Good first issue candidates
• SECURITY.md
• GOVERNANCE.md
• CODE_OF_CONDUCT.md

Ecosystem

KORA is part of the broader Krako infrastructure.

Related repository:

• Krako 2.0: TBD

License

Apache-2.0. See LICENSE.