===============
LIBRARY RULES
===============
From library maintainers:
- Use MessageType.DATA for normal data messages, MessageType.CONTROL for control signals, MessageType.ERROR for error reporting
- Always specify name parameter when creating Node and Subgraph instances
- Define proper input/output ports with PortSpec including type hints for validation
- Use _handle_tick() method for periodic work, not on_tick() - this is the override method
- Use _handle_message() method for message processing, not on_message() - this is the override method
- Implement proper backpressure handling with bounded edges and overflow policies (Block, Drop, Latest, Coalesce)
- Use structured logging with event keys and contextual fields via with_context()
- Follow the Node lifecycle: on_start, on_message, on_tick, on_stop (these are hooks, not overrides)
- Use uv for package management and development workflow
- Implement proper error handling without exposing sensitive data in logs
- Use PortSpec with type hints for proper validation
- Connect nodes using Subgraph.connect(('source', 'port'), ('target', 'port'))
- Use Scheduler.run() for execution, not manual step-by-step approaches
- Configure observability with ObservabilityConfig before using logging/metrics/tracing
- Use Message constructor with type parameter: Message(type=MessageType.DATA, payload=...)
- Always call super().__init__() in Node subclasses with name and ports parameters
- Use Port constructor with direction and spec: Port('name', PortDirection.INPUT, spec=PortSpec('name', type))
- Handle backpressure by catching RuntimeError from emit() calls when edges are full
- Use control-plane priorities for critical messages by setting edge priorities
- Implement error handling with MessageType.ERROR and structured error payloads
- Use contextual logging with with_context() for trace_id, node, edge_id, port enrichment
- Configure metrics with proper namespacing and labels for observability
- Use SchedulerConfig for tuning scheduler behavior (tick_interval_ms, fairness_ratio, etc.)
- Validate subgraphs before execution using subgraph.validate()
- Use proper capacity values for edges based on expected load and backpressure requirements
- Implement graceful shutdown by calling scheduler.shutdown()
- Use trace_id propagation for distributed tracing across nodes
- Handle message validation failures gracefully with proper error messages
- Use factory functions for policies: block(), drop(), latest(), coalesce(fn)
- Configure observability once at application startup, not per-node

### Running the Hello World Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Instructions on how to save and execute the basic Producer-Consumer graph example.

```bash
# Save the code above to a file, e.g., hello.py
# Execute it in your environment:

uv run python hello.py
```

--------------------------------

### Running the Setup Verification Test

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Instructions on how to execute the setup verification test script.

```bash
uv run python test_setup.py
```

--------------------------------

### Start Example Graph

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/templates/guide-template.md

Starts a minimal Meridian graph example and shows expected log output.

```bash
uv run python -m examples.hello_graph.main
```

--------------------------------

### Quickstart Commands Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/quality-pass.md

Provides copy-pasteable commands for the Quickstart guide, ensuring users can easily set up and run the project using `uv`.

```bash
# Install project dependencies using uv
uv pip install --system

# Install project in editable mode
uv pip install --editable .

# Run the Meridian runtime
meridian-runtime start --config /path/to/config.yaml
```

--------------------------------

### Run Demo Examples

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Demonstrates how to run example pipelines provided with Meridian Runtime, such as the sentiment analysis and streaming coalesce examples. Includes options for human-readable output and timeout settings.

```bash
# Sentiment pipeline
python examples/sentiment/main.py --human --timeout-s 6.0

# Streaming coalesce
python examples/streaming_coalesce/main.py --human --timeout-s 5.0
```

--------------------------------

### Setup Verification Test

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

A simple test node to verify the Meridian Runtime installation. It receives a string, prints a success message, and emits a success signal.

```python
# test_setup.py
from meridian.core import Node, Message, MessageType, Subgraph, Scheduler
from meridian.core.ports import Port, PortDirection, PortSpec

class TestNode(Node):
    def __init__(self):
        super().__init__(
            "test",
            inputs=[Port("in", PortDirection.INPUT, spec=PortSpec("in", str))],
            outputs=[Port("out", PortDirection.OUTPUT, spec=PortSpec("out", str))],
        )
    
    def _handle_message(self, port: str, msg: Message) -> None:
        if port == "in":
            print(f"✓ Setup working! Received: {msg.payload}")
            self.emit("out", Message(type=MessageType.DATA, payload="success"))

# Create and run a simple test
sg = Subgraph.from_nodes("test", [TestNode()])
sg.connect(("test", "out"), ("test", "in"), capacity=1)  # Self-loop for testing

sch = Scheduler()
sch.register(sg)

# Send initial message
test_node = sg.nodes[0]
test_node.emit("in", Message(type=MessageType.DATA, payload="Hello Meridian!"))

sch.run()
```

--------------------------------

### Install Meridian Runtime

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Installs the Meridian Runtime library using `uv pip`.

```bash
uv pip install meridian-runtime
```

--------------------------------

### Meridian Runtime Quickstart Commands

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/examples-and-documentation.md

Provides essential commands for setting up and running the Meridian Runtime examples. Includes initialization, dependency locking, synchronization, and running the core examples.

```bash
uv init
uv lock
uv sync
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
uv run python examples/hello_graph/main.py
uv run python examples/pipeline_demo/main.py
```

--------------------------------

### Running the Minimal Hello Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/minimal-hello.md

Command to execute the minimal hello example from the Meridian runtime examples directory. This will start the producer and consumer nodes and demonstrate the graph wiring and lifecycle.

```bash
python examples/minimal_hello/main.py
```

--------------------------------

### Running the Hello Graph Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/hello-graph.md

Command to execute the Hello Graph example from the examples repository root. This will start the producer and consumer nodes, demonstrating message flow and logging.

```bash
python examples/hello_graph/main.py
```

--------------------------------

### Running Examples

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Demonstrates how to run various examples provided by the Meridian Runtime project. This allows developers to test specific functionalities and features.

```bash
# Direct execution
python examples/minimal_hello/main.py
python examples/hello_graph/main.py
python examples/sentiment/main.py --human --timeout-s 6.0
python examples/streaming_coalesce/main.py --human --timeout-s 5.0
python examples/pipeline_demo/main.py
```

--------------------------------

### Run Meridian Runtime Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/quickstart.md

Clones the Meridian Runtime examples repository and runs the sentiment analysis example using uv, with options for human interaction and a timeout.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
uv run python examples/sentiment/main.py --human --timeout-s 6.0
```

--------------------------------

### MkDocs Local Setup

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Commands to set up MkDocs locally for building documentation. Includes installing necessary packages and building the documentation strictly.

```bash
pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
mkdocs build --strict
```

--------------------------------

### Troubleshooting Installation Issues

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Steps to resolve installation problems, including checking Python version, updating `uv`, and clearing the cache.

```bash
# Check Python version
python --version

# Update uv
pip install -U uv

# Clear cache
uv cache clean
```

--------------------------------

### Repository Setup and Dependency Installation

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Clones the Meridian Runtime repository and installs project dependencies using `uv` (preferred) or `pip`. This ensures the development environment is correctly configured.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime.git
cd meridian-runtime

# Create a virtual environment and install dependencies with uv (preferred)
uv sync

# Alternatively, using pip:
# python -m venv .venv
# source .venv/bin/activate
# pip install -U pip
# pip install -e ".[dev]"
```

--------------------------------

### Minimal Hello Graph Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

A basic Python example demonstrating the core components of Meridian Runtime: Nodes, Edges, and Subgraphs. It shows how to define and connect two nodes using a typed, bounded edge.

```python
# Minimal "Hello Graph" with two nodes connected by a typed, bounded edge.

from meridian.core import Subgraph, Scheduler, Message, MessageType, Node, PortSpec
from meridian.core.ports import Port, PortDirection

```

--------------------------------

### Minimal Hello World Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/index.md

Demonstrates the absolute basics of wiring two nodes, sending integer messages, and seeing output. It showcases the core API including Node, Subgraph, Scheduler, typed ports, and bounded edges. This example serves as a basic installation check.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
python examples/minimal_hello/main.py
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/templates/guide-template.md

Clones the Meridian Runtime repository and installs project dependencies using uv.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime.git
cd meridian-runtime
uv sync
```

--------------------------------

### Environment Setup and Dependency Installation

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/support/TROUBLESHOOTING.md

Ensures the correct Python version and dependencies are installed for running Meridian Runtime and its examples. This includes activating a virtual environment and installing development dependencies.

```bash
source .venv/bin/activate
uv sync
python --version
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git && cd meridian-runtime-examples && uv run python examples/hello_graph/main.py
```

--------------------------------

### Test Meridian Runtime Setup

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/quickstart.md

Creates and runs a Python script to test the Meridian Runtime setup. The script defines a simple node that receives a message, prints it, and emits a success message. It then runs this script using uv.

```python
from meridian.core import Node, Message, MessageType, Subgraph, Scheduler
from meridian.core.ports import Port, PortDirection, PortSpec

class TestNode(Node):
    def __init__(self):
        super().__init__(
            "test",
            inputs=[Port("in", PortDirection.INPUT, spec=PortSpec("in", str))],
            outputs=[Port("out", PortDirection.OUTPUT, spec=PortSpec("out", str))],
        )
    
    def _handle_message(self, port: str, msg: Message) -> None:
        if port == "in":
            print(f"✓ Setup working! Received: {msg.payload}")
            self.emit("out", Message(type=MessageType.DATA, payload="success"))

sg = Subgraph.from_nodes("test", [TestNode()])
sg.connect(("test", "out"), ("test", "in"), capacity=1)

sch = Scheduler()
sch.register(sg)
test_node = sg.nodes[0]
test_node.emit("in", Message(type=MessageType.DATA, payload="Hello Meridian!"))
sch.run()
```

--------------------------------

### Python Module Execution Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/docs-conventions.md

Demonstrates how to execute a Python module for runtime behavior, including cloning a repository and using `uv` for execution. This is the preferred method for showcasing runtime examples.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
uv run python examples/hello_graph/main.py
```

--------------------------------

### Project Structure

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Overview of the Meridian Runtime project directory layout, highlighting key components and their locations.

```text
src/meridian/
  core/           # nodes, edges, subgraphs, scheduler, policies
  observability/  # logging/metrics/tracing hooks
examples/
  sentiment/
  streaming_coalesce/
tests/
  unit/
  integration/
  soak/
scripts/
  verify.sh       # one-shot verification gate (tests + coverage)
```

--------------------------------

### Expected Log Output for Example Graph

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/templates/guide-template.md

Abridged expected log output when starting the example graph, showing scheduler and node initialization and processing.

```text
INFO scheduler Started
INFO node.hello Initialized
INFO node.hello Processed 10 messages
```

--------------------------------

### Verify Meridian Runtime Installation

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/quickstart.md

Executes a verification script using uv to check the Meridian Runtime installation.

```bash
uv run bash scripts/verify.sh
```

--------------------------------

### MkDocs Installation and Build

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Installs the necessary MkDocs packages and builds the documentation site. This is a prerequisite for viewing or building the project's documentation.

```bash
pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
mkdocs build --strict
```

--------------------------------

### Parallel Examples (Bash/PowerShell)

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/docs-conventions.md

Demonstrates how to use tabbed blocks for multi-language or platform variants of code examples. This ensures that users can easily switch between different execution environments.

```bash
uv lock
uv sync
uv run pytest -q
```

```powershell
uv lock
uv sync
uv run pytest -q
```

--------------------------------

### Run Pipeline Demo

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/pipeline-demo.md

Command to execute the pipeline demo from the examples repository root. It starts the graph wiring, node startup, and demonstrates pipeline execution, shutdown signal processing, and backpressure simulation.

```bash
python examples/pipeline_demo/main.py
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Starts a local development server for viewing the documentation. It binds to a specific IP address and port.

```bash
mkdocs serve -a 127.0.0.1:8000
```

--------------------------------

### Serving Documentation Locally

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Starts a local server to preview the project's documentation with live reloading. This facilitates iterative development of documentation content.

```bash
make docs-serve
```

--------------------------------

### MkDocs Configuration (nav example)

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Example snippet from mkdocs.yml showing navigation structure. Used to identify and fix missing pages in the documentation build.

```yaml
nav:
  - Home: index.md
  - Quickstart: quickstart.md
  - API:
    - Overview: api/index.md
    - Authentication: api/auth.md
```

--------------------------------

### Command and Output Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/docs-conventions.md

Shows how to separate commands and their corresponding output into distinct code blocks, using titles for clarity.

```bash
uv run pytest -q
```

```text
================== test session starts ==================
collected 34 items
...

```

--------------------------------

### observability_demo Example Specification

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/examples-and-documentation.md

Outlines the 'observability_demo' example, focusing on enabling metrics and optional tracing with minimal performance impact. It specifies event-driven updates for counters and histograms, and behavior when tracing is not installed.

```python
# observability_demo (optional)

# - Ubiquitous: The example shall demonstrate enabling metrics and optional tracing with minimal overhead.
# - Event‑driven: When nodes process messages, counters and histograms shall update; tracing spans shall be created only if enabled.
# - Unwanted: If tracing is not installed, the example shall run with a no‑op provider without errors.

```

--------------------------------

### Development Loop Commands

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Provides commands for the typical development workflow in Meridian Runtime, including linting with Ruff, type-checking with MyPy, and running tests with coverage.

```bash
# Lint
uv run ruff check .

# Type-check
uv run mypy src

# Tests with coverage gate
uv run pytest --cov=src --cov-fail-under=80
```

--------------------------------

### Correct Node Initialization

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Shows the proper way to initialize a node by passing inputs and outputs to the superclass constructor, ensuring correct node lifecycle management.

```python
# Correct: pass inputs and outputs to super().__init__
super().__init__(
    name="my_node",
    inputs=[Port("in", PortDirection.INPUT, spec=PortSpec("in", int))],
    outputs=[Port("out", PortDirection.OUTPUT, spec=PortSpec("out", str))],
)
```

--------------------------------

### Documentation Updates

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/utilities-and-scaffolding.md

Recommendations for updating project documentation, specifically for scaffolding and utility functions, including installation examples, naming conventions, and CI integration.

```markdown
- `docs/scaffolding.md`:
    - Installation/usage examples for both generators.
    - Naming conventions: snake_case modules, PascalCase classes, short port names.
    - Examples of input/output type annotations and Policies usage in docstrings.
- `docs/utils.md`:
    - Quick reference for ids/time/validation helpers.
    - Examples integrating `validate_graph` into CI or pre-commit.
```

--------------------------------

### APIDOC: uv Command Reference

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Documentation for the `uv` command, a fast Python package installer and resolver. Covers commands for locking, syncing, and running tools.

```APIDOC
uv Command Reference:

- `uv lock`:
  - Description: Generates or updates the `uv.lock` file, locking the project's dependencies to specific versions.
  - Use Case: Ensures reproducible builds by pinning exact dependency versions.
  - When to run: After adding or updating dependencies, or for the first time to establish the lock file.

- `uv sync`:
  - Description: Installs the dependencies specified in the lock file (or `pyproject.toml` if no lock file exists) into the current environment.
  - Use Case: Sets up the project's development environment with the correct dependencies.
  - Related: `uv lock`, `uv run`.

- `uv run <command> [-- <args>...]`:
  - Description: Executes a command within the context of the project's virtual environment managed by uv.
  - Purpose: Ensures that tools like `ruff`, `black`, `mypy`, and `pytest` are run using the project's pinned dependencies.
  - Examples:
    - `uv run ruff check .`
    - `uv run pytest`
    - `uv run python src/my_module.py`
  - Related: `uv sync`.
```

--------------------------------

### Project Configuration (pyproject.toml)

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Example snippet from pyproject.toml showing configuration for tools like Ruff and Black. It specifies line length and other formatting rules.

```toml
[tool.black]
line-length = 100

[tool.ruff]
line-length = 100
select = ["E", "F", "W", "I", "UP"]
ignore = []

[tool.mypy]
ignore_missing_imports = true

```

--------------------------------

### Troubleshooting Verification Failures

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Advice for addressing failures in the verification script, such as flaky tests, coverage issues, or hanging examples.

```bash
# Run tests
uv run pytest -q

# Run specific test subsets
uv run pytest tests/unit -q

# Lower timeout for examples
--timeout-s <seconds>
```

--------------------------------

### GitHub Actions Workflow Snippet (Python Setup)

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Example of setting up Python in a GitHub Actions workflow with caching enabled for pip.

```yaml
steps:
  - name: Set up Python
    uses: actions/setup-python@v5
    with:
      python-version: '3.10'
      cache: 'pip'
```

--------------------------------

### Running Meridian Runtime Examples

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/index.md

Provides commands to run various Meridian Runtime examples from the cloned repository. It includes examples for minimal hello world, hello graph, simple web server simulation, sentiment pipeline, streaming coalesce, and pipeline demo. Append --help to any example to see supported flags.

```bash
# Minimal Hello World (start here!)
python examples/minimal_hello/main.py

# Hello Graph
python examples/hello_graph/main.py

# Simple web server (simulated)
python examples/simple_web_server/main.py

# Sentiment pipeline
python examples/sentiment/main.py --human --timeout-s 6.0

# Streaming coalesce
python examples/streaming_coalesce/main.py --human --timeout-s 5.0

# Pipeline Demo
python examples/pipeline_demo/main.py
```

--------------------------------

### Run Verification Script

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Executes a shell script to perform comprehensive verification of the Meridian Runtime installation. This includes running tests and checking coverage thresholds.

```bash
uv run bash scripts/verify.sh
```

--------------------------------

### Consumer Node Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Demonstrates a Consumer node that receives and prints integer payloads from an input port. It stores received values in a list and prints them to the console.

```python
class Consumer(Node):
    def __init__(self):
        super().__init__(
            "consumer",
            inputs=[Port("in", PortDirection.INPUT, spec=PortSpec("in", int))],
            outputs=[],
        )
        self.values = []
        
    def _handle_message(self, port: str, msg: Message) -> None:
        if port == "in":
            self.values.append(msg.payload)
            print(f"Received: {msg.payload}")
```

--------------------------------

### Producer Node Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Demonstrates a Producer node that emits an integer payload on each scheduler tick. It emits 5 messages and then stops. This is a fundamental building block for dataflow graphs.

```python
class Producer(Node):
    def __init__(self):
        super().__init__(
            "producer",
            inputs=[],
            outputs=[Port("output", PortDirection.OUTPUT, spec=PortSpec("output", int))],
        )
        self.count = 0
        
    def _handle_tick(self) -> None:
        if self.count < 5:  # Emit 5 messages then stop
            self.emit("output", Message(type=MessageType.DATA, payload=self.count))
            self.count += 1
```

--------------------------------

### Clone and Sync Meridian Runtime

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/quickstart.md

Clones the Meridian Runtime repository from GitHub and synchronizes its dependencies using uv.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime.git
cd meridian-runtime
uv sync
```

--------------------------------

### Project Setup with uv

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/bootstrap-and-ci.md

Demonstrates the commands to initialize, lock, and synchronize dependencies using uv for a Python project.

```bash
uv init
uv lock
uv sync
```

--------------------------------

### Running Hello Graph Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/examples.md

Instructions to save the 'Hello Graph' example as 'hello.py' and then execute it using 'uv run'.

```bash
uv run python hello.py

```

--------------------------------

### Hello Graph Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/examples/index.md

Demonstrates modular design with separate producer and consumer modules, comprehensive logging with contextual fields and metadata, and proper project structure for complex applications. It highlights production-ready code organization and observability integration.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
python examples/hello_graph/main.py
```

--------------------------------

### Create a simple pipeline with Producer, Map, and Consumer nodes

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Demonstrates building a basic data pipeline using `DataProducer`, `MapTransformer`, and `DataConsumer` nodes. It connects these nodes to form a subgraph, schedules and runs the pipeline, and prints the processed data.

```python
from meridian.core import Scheduler, SchedulerConfig, Subgraph
from meridian.nodes import DataProducer, MapTransformer, DataConsumer

p = DataProducer("p", data_source=lambda: iter(range(10)), interval_ms=0)
m = MapTransformer("m", transform_fn=lambda x: x * 2)
seen: list[int] = []
c = DataConsumer("c", handler=seen.append)

g = Subgraph.from_nodes("g", [p, m, c])
g.connect(("p", "output"), ("m", "input"))
g.connect(("m", "output"), ("c", "input"))

s = Scheduler(SchedulerConfig())
s.register(g)
import threading, time
th = threading.Thread(target=s.run, daemon=True)
th.start(); time.sleep(0.2); s.shutdown(); th.join()
print(seen)
```

--------------------------------

### Python API Usage Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/templates/reference-template.md

Provides a basic example of how to use the Meridian runtime in Python, including importing the Runtime and Node classes, initializing the runtime, and starting it.

```python
from meridian import Runtime, Node
rt = Runtime()
# ...
rt.start()
```

--------------------------------

### Python Message and PortSpec Examples

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/docs-conventions.md

Demonstrates consistent API usage for messages and port specifications, aligning with schema definitions. This ensures uniformity across examples and the API.

```python
from some_package import Message, MessageType, PortSpec

# Example usage:
message = Message(type=MessageType.DATA, payload={'key': 'value'})
port_spec = PortSpec("in", int)
```

--------------------------------

### Contributing an Example to Meridian Runtime

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/examples.md

Guidelines for contributing practical, self-contained examples to Meridian Runtime. Emphasizes clear node responsibilities, realistic policies, robust lifecycle management, and adherence to existing patterns.

```markdown
We welcome practical, self-contained examples that showcase:

- Clear node responsibilities and typed edges
- Realistic policies and scheduling decisions
- Robust lifecycle and logging
- Minimal dependencies and easy reproducibility

Before submitting:

- Verify with scripts/verify.sh
- Include a short README and run instructions
- Follow existing style and observability patterns
```

--------------------------------

### Overriding Example Parameters with Environment Variables

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Shows how to override default parameters for running examples by setting environment variables. This provides flexibility in testing different scenarios.

```bash
RATE_HZ=20 TICK_MS=10 python examples/sentiment/main.py --human
COAL_RATE_HZ=600 CAP_AGG_TO_SINK=8 python examples/streaming_coalesce/main.py --human
```

--------------------------------

### Lychee Ignore File Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Example of a .lycheeignore file used to exclude specific URLs or domains from link checking. This is useful for known flaky external links or private assets.

```toml
# Ignore flaky external domains
[External]
example.com = "Known to be flaky"
sub.example.org = "Occasional timeouts"

# Ignore private assets
[Private]
/internal/build-only/asset.pdf
```

--------------------------------

### Environment Initialization

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/examples.md

Command to initialize the development environment using 'uv sync'. This is a prerequisite for running the provided examples.

```bash
uv sync

```

--------------------------------

### Project Cross-References

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/CI-TRIAGE.md

Links to other important project files for further context on setup, workflow, and planning.

```markdown
- CONTRIBUTING.md: Setup, development workflow, pre-commit instructions.
- M99 Plan: Status and acceptance criteria for docs and CI stabilization.
```

--------------------------------

### Run Python Example with Bash

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/examples-migration.md

Clones the examples repository and runs a 'hello_graph' Python example using standard Python execution.

```bash
git clone https://github.com/GhostWeaselLabs/meridian-runtime-examples.git
cd meridian-runtime-examples
python examples/hello_graph/main.py
```

--------------------------------

### Build Documentation

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Builds the static documentation files for the project using MkDocs.

```bash
uv run mkdocs build
```

--------------------------------

### Common Make Targets

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/guides/local-development.md

Provides a list of common `make` targets for convenience, including running demos, building documentation, and checking links.

```bash
make help
make demo-minimal
make demo-sentiment
make demo-coalesce
make docs-serve
make docs-build
make docs-check-links
```

--------------------------------

### Python Versioning Example

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/contributing/RELEASING.md

Demonstrates how to access the package version in Python. This is crucial for verifying that the correct version is installed and running.

```python
import meridian

print(meridian.__version__)
```

--------------------------------

### Install and Import Core Primitives

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/reference/api.md

Demonstrates the installation process using `uv` and the import pattern for core types from the `meridian.core` module. This includes essential components for building data processing pipelines.

```bash
uv lock
uv sync
```

```python
from meridian.core import (
    Message, MessageType, Node, Subgraph, Scheduler, SchedulerConfig,
    Port, PortDirection, PortSpec, Edge, BackpressureStrategy, RetryPolicy, RoutingPolicy
)
```

--------------------------------

### Running Verification Gate

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Executes the verification script located in `scripts/verify.sh` to ensure the project meets quality standards before submission.

```bash
uv run bash scripts/verify.sh
```

--------------------------------

### Running Pytest Tests

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/getting-started/guide.md

Executes the project's test suite using Pytest with quiet output to verify functionality.

```bash
uv run pytest -q
```

--------------------------------

### Examples and Recipes Expansion

Source: https://github.com/ghostweasellabs/meridian-runtime/blob/main/docs/roadmap/future-roadmap.md

The repository includes curated examples for backpressure policies, redaction strategies, and controlled shutdown. Debug mode scripts with structured logs and metrics sinks are also provided.

```APIDOC
Repository:
  Examples:
    - Backpressure policies
    - Redaction strategies
    - Controlled shutdown
    - Debug mode scripts (structured logs, metrics sinks)
```