Skip to main content

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).

See docs/plugin-flavours.md.

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

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)

Source distribution for mas-lab-runtime 0.2.0
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)

Table of built distributions (wheels) for mas-lab-runtime 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page