runtime
Contract-driven Mealy kernel for LLM agents.
Objective
mas-runtime is the core runtime library of MAS Lab. It provides contract
interfaces (tool, context, memory, control, recorder, …), a v2 kernel with
seven-symbol egress/ingress envelopes, design-pattern plugins (ReAct, Plan-Execute,
…), and governance chokepoints — all framework-agnostic.
The runtime instruments agents without replacing your orchestration framework. Governance and observability run at kernel chokepoints so policies apply consistently across LangChain, LangGraph, AutoGen, and custom loops.
Stack position
mas-runtime ← embeddable Mealy kernel (library only — no CLI)
mas-ctl ← control plane: compose, chat, run-mas, validate (instantiates runtime)
mas-lab ← evaluation: benchmarks, pipelines, controller UI
All CLIs: mas-ctl (agents) and mas-lab (benchmarks). Use mas-ctl chat for interactive and headless scripted runs (-q).
Setup
Install (from source)
uv sync --all-packages # full monorepo; wheel names are in docs/packages-reference.md
Credentials
Secrets are never embedded in manifests. Set environment variables or use a
.env file (see docs/user-config.md):
export OPENAI_API_KEY=sk-...
Infrastructure and flavours
Manifests reference infra bundles and flavours from library-standard
(local, mock, local-benchmark, …). Only secret names appear in YAML
(api_key_env: OPENAI_API_KEY).
Plugin aliases
library-standard ships the canonical built-in plugin implementations and the runtime alias defaults.
The runtime registry maps human-friendly names and aliases such as react or planner to canonical URNs
such as mas.dp.react.
Runtime alias defaults live in src/mas/runtime/aliases.yaml.
The schema is src/mas/runtime/aliases.schema.yaml, and
mas.runtime.registry.aliases.validate_alias_manifest() validates both the package manifest and
config.yaml alias overrides.
See docs/plugin-aliases.md for discovery order, alias resolution, and configuration examples.
Quickstart
Recommended (interactive):
mas-ctl validate agent.yaml
mas-ctl chat agent.yaml -q "What is the capital of France?"
Headless / Docker / CI:
mas-ctl chat agent.yaml -q "What is the capital of France?"
Library API:
from mas.ctl.session.bootstrap import InstantiationOptions, instantiate_runtime
from mas.ctl.session.controller import SessionController, run_session_loop
from mas.ctl.ui.stdout import StdoutConversationDisplay
opts = InstantiationOptions.from_manifest_path("agent.yaml")
instance, _ = instantiate_runtime(opts)
controller = SessionController(instance=instance, display=StdoutConversationDisplay())
run_session_loop(controller, scripted=["Hello"])
Core concepts
| Layer | What it does |
|---|---|
| Kernel | RuntimeKernel + KernelDriver — schedules egress, runs envelopes |
| Envelope | Authorize → execute → validate on every LLM_CALL / TOOL_CALL |
| Design patterns | ReactPlugin, PlanExecutePlugin, … via evaluate_next / handle_event |
| Contracts | Stable plugin boundaries — see contracts-reference.md |
| Governance | Policy at egress chokepoints — see governance-policy-engine.md |
Status checklist: docs/mealy-envelope.md.
Tutorials
Primary learning path (MkDocs): docs/tutorials/index.md at the repository root — Tutorials 0–3 cover environment, agent, MAS, and experiments.
Runtime deep-dives (contributor-oriented, in this tree):
| Topic | Document |
|---|---|
| Design patterns | design-patterns.md |
| Plugin flavours | plugin-flavours.md |
| Plugin authoring | plugin-and-tool-authoring.md |
| Mealy product model | automaton-product-model.md |
Examples
| Path | Description |
|---|---|
| library-samples/apps/ | Trip planner, Q&A, and other sample apps |
| docs/tutorials/01-building-an-agent/ | Step-by-step agent tutorial (MkDocs) |
Documentation
Users
| Document | Answers |
|---|---|
| docs/user-guide.md | Install, run, integrate |
| docs/contracts-reference.md | Which contract to implement |
| docs/plugin-flavours.md | Dev vs prod configuration |
| docs/design-patterns.md | CoT / ReAct / Plan-Execute |
| docs/context-segmentation.md | Context assembly and provenance |
| docs/semantic-protocols.md | Governance scopes and URNs |
| docs/naming-standards.md | Naming conventions |
Contributors
| Document | Covers |
|---|---|
| docs/index.md | Documentation hub |
| docs/production-path.md | Kernel execution path |
| docs/mealy-envelope.md | Envelope implementation status |
| docs/automaton-product-model.md | Formal product model (design + map) |
| docs/developer-guide.md | Plugin and test workflow |
| docs/trajectory-schema.md | Event / trace schema |
Testing
uv run pytest runtime/tests/ -q
uv run pytest runtime/tests/ --cov=mas.runtime --cov-report=term-missing
Related packages
| Package | Role |
|---|---|
mas-ctl |
Compose, chat, run-mas, validate |
mas-lab |
Benchmarks, pipelines, UI |
library-standard |
Flavours, overlays, infra bundles |
Metadata
Release files for mas-lab-runtime 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mas_lab_runtime-0.2.0.tar.gz | 522.9 kB | With provenance | Details for mas_lab_runtime-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mas_lab_runtime-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mas_lab_runtime-0.2.0-py3-none-any.whl |
Total release size: 918.1 kB
Release files / mas_lab_runtime-0.2.0.tar.gz
| Download URL | mas_lab_runtime-0.2.0.tar.gz |
|---|---|
| Size | 522.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ddf5fde8b978856dfe79b20ca3f4bd09f72ffb2a558f18c1a5509c286ffbcf77
|
|
BLAKE2b-256 checksum How to use checksums |
701103e53b1827cb1226f117a4bfd449c4fd38673184fceeb5e3cec3142febbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / mas_lab_runtime-0.2.0-py3-none-any.whl
| Download URL | mas_lab_runtime-0.2.0-py3-none-any.whl |
|---|---|
| Size | 395.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81f9e77bdc296536e07838a6e2e1ae0144e09e3ee3209befe0a8fdcb0a774c51
|
|
BLAKE2b-256 checksum How to use checksums |
8a86d74f74fc294c344d7377ceb9ef13d747e3dfeed30fd26b5abdcad277f742
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for mas-lab-runtime 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mas_lab_runtime-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.