# 🧠 coreason-runtime
[](https://pypi.org/project/coreason_runtime)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/ci.yml)
[](https://coreason-ai.github.io/coreason-runtime/)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/docs.yml)
[](https://pypi.org/project/coreason_runtime)
[](https://pypi.org/project/coreason_runtime/)
[](https://prosperitylicense.com/versions/3.0.0)
[](https://coreason.ai)
<br>
[](https://scorecard.dev/viewer/?uri=github.com/CoReason-AI/coreason-runtime)
[](https://codecov.io/gh/CoReason-AI/coreason-runtime)
[](https://mypy-lang.org/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/PyCQA/bandit)
<br>
[](https://github.com/astral-sh/uv)
[](https://github.com/CoReason-AI/coreason-runtime/network/members)
[](https://coreason.ai)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/osv-scanner.yml)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/trivy.yml)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/trufflehog.yml)
[](https://github.com/CoReason-AI/coreason-runtime/actions/workflows/dast.yml)
**The official zero-trust, high-throughput kinetic execution engine for the `coreason-manifest` ontology.**
`coreason-runtime` is a State-of-the-Art (SOTA) 2026 cybernetic execution engine. It abandons legacy, fragile "chain-of-thought" LLM scripting in favor of deterministic **Active Inference**, Topological Data Analysis (TDA), and strictly bounded Markov Decision Processes. It is the definitive implementation of the CoReason Tripartite Doctrine for Tier-1 Kinetic Execution.
If `coreason-manifest` is the DNA of your multi-agent topologies, `coreason-runtime` is the biological cell that safely executes them.
---
## 🚀 The Paradigm Shift
Modern enterprise AI cannot rely on unbounded `while True` loops and raw Python `exec()`. The `coreason-runtime` enforces mathematical rigor at every boundary:
* **Deterministic Orchestration:** Built on **Temporal**, Cognitive Topology executions are durably serialized. If a GPU dies or a network request fails, the topology pauses, rehydrates, and resumes exactly where it left off. No amnesia. No ghost processes.
* **Zero-Trust WASM Sandboxing:** Kinetic actions (Tools) are executed inside isolated WebAssembly environments via **Extism**. Agents can execute complex IO without ever touching your host's root kernel or filesystem.
* **Epistemic Vector Ledger:** Native, zero-copy integration with **LanceDB**. The runtime automatically projects the agent's latent state into an embedded vector memory layer.
* **Embedded Medallion Analytics:** No need for heavy Spark clusters. Raw telemetry (SSE) is ingested via **dlt** and transformed into Silver/Gold analytical intelligence matrices using Rust-backed **Polars** directly inside the daemon.
* **Human-in-the-Loop (HITL) Webhooks:** When an agent calculates high Variational Free Energy (epistemic uncertainty), it durably suspends its thread and emits an Oracle Request, waiting safely for a human expert to inject resolving priors via API.
* **Bipartite Proposer-Verifier Protocol:** The runtime is physically isolated from local OS capability generation. To fabricate assets, the runtime strictly proposes topological models over air-gapped MCP boundaries to the remote Universal Asset Forge (`coreason-meta-engineering`).
---
## ⚡ Installation
We utilize `uv` for ultra-fast, deterministic resolution. Ensure you are running Python 3.14+.
```bash
uv add coreason-runtime
```
*Note: For bare-metal enterprise deployment with SGLang GPU passthrough, refer to our [Docker Deployment Guide](docs/DEPLOYMENT.md).*
------
## 🐳 Docker Deployment & Hardware Capabilities
The local docker development environment dynamically scales its container footprint depending on the capabilities of the host system.
If the host system does not have an NVIDIA GPU, it skips the heavy `sglang` (Cognitive Engine) image download (10GB+) and installs a lightweight `runtime` package without CUDA/PyTorch dependencies.
To automatically configure your environment based on host capabilities, run:
### Windows (PowerShell)
```powershell
./scripts/detect_capabilities.ps1
```
### macOS/Linux
```bash
chmod +x ./scripts/detect_capabilities.sh
./scripts/detect_capabilities.sh
```
These scripts will automatically inspect your hardware and generate/update the local `.env` configuration file with:
- `COMPOSE_PROFILES=gpu` (activated only if NVIDIA GPU is detected)
- `EXTRAS=inference` (packages deep learning libraries only if GPU is present)
After running the capability check, start the local stack:
```bash
docker compose up --build
```
------
## 🛠️ Quickstart
The runtime is designed to be operated via its CLI or mounted as an API edge.
### 1\. Run a Local Cognitive Topology
To execute a mathematically verified agentic topology, simply pass the JSON/YAML manifest to the runtime:
```bash
coreason run ./my_topology_manifest.json
```
### 2\. Boot the API Edge & Telemetry Broker
To boot the runtime as a continuous daemon (exposing the CRDT State Sync, Schema Projection, and Server-Sent Events telemetry):
```bash
coreason serve --port 8000
```
Your frontend IDE can now connect to `http://localhost:8000/api/v1/telemetry/stream` to visualize the active inference loops in real-time.
-----
## 🏗️ Architecture
The runtime operates across five isolated computational boundaries under the CoReason Tripartite Doctrine:
1. **The Orchestrator:** Temporal Python SDK running deterministic AST-scanned workflows.
2. **The Cognitive Engine:** SGLang routing for sub-millisecond constrained tensor inference.
3. **The Kinetic Sandbox:** Extism executing `.wasm` tools with zero-trust lattices.
4. **The Epistemic Store:** LanceDB & Polars managing long-term vectors and ETL metrics.
5. **The Universal Asset Forge:** A decoupled MCP channel connecting strictly to the `coreason-meta-engineering` Fabrication Lines to physically synthesize assets via the Bipartite generation pipeline.
For a deep dive into the cybernetic loop, read the [Architecture Documentation](docs/architecture.md).
-----
## 📜 License
This software is proprietary and dual-licensed under the **Prosperity Public License 3.0**.
Commercial use beyond a 30-day trial requires a separate commercial license. See the `LICENSE` file for details.
Copyright (c) 2026 CoReason, Inc.