docs(standards): vendor template into MCP bundle; add component tools + start_app prompt
This commit is contained in:
0
standards/mcp/templates/app/pipelines/__init__.py
Normal file
0
standards/mcp/templates/app/pipelines/__init__.py
Normal file
@@ -0,0 +1,7 @@
|
||||
"""# Summary
|
||||
|
||||
Example pipeline family — a reusable skeleton, not an app-specific pipeline.
|
||||
|
||||
Replace ``Example*`` names and the three stages with your family's stages. The
|
||||
shape (abc → impl → pipeline.yaml → resources/) stays the same.
|
||||
"""
|
||||
53
standards/mcp/templates/app/pipelines/example/abc.py
Normal file
53
standards/mcp/templates/app/pipelines/example/abc.py
Normal file
@@ -0,0 +1,53 @@
|
||||
"""# Summary
|
||||
|
||||
Example pipeline family — port contracts (stage interfaces + root interface).
|
||||
|
||||
Ports are declared as a DI tree: the root's annotated slots *are* the dependency
|
||||
decisions. The concrete subclass in ``impl.py`` pins the stage types.
|
||||
"""
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any
|
||||
|
||||
from pipelines.shared.ports import FinalizePort
|
||||
|
||||
|
||||
class IngestPort(ABC):
|
||||
"""Obtain the raw input as text/bytes."""
|
||||
|
||||
@abstractmethod
|
||||
def materialize(self, source: Any) -> str:
|
||||
"""Return the raw input materialized as text."""
|
||||
|
||||
|
||||
class ReadPort(ABC):
|
||||
"""Parse materialized input into records."""
|
||||
|
||||
@abstractmethod
|
||||
def read(self, content: str) -> list[dict[str, Any]]:
|
||||
"""Return parsed records."""
|
||||
|
||||
|
||||
class NormalizePort(ABC):
|
||||
"""Normalize raw records into the target shape."""
|
||||
|
||||
@abstractmethod
|
||||
def build(self, records: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
"""Return normalized records."""
|
||||
|
||||
|
||||
class ExamplePipelinePort(ABC):
|
||||
"""Root of the example family.
|
||||
|
||||
Notes:
|
||||
The slot annotations below are contracts. A concrete subclass re-annotates
|
||||
them with stage implementations; the DI container instantiates the tree.
|
||||
"""
|
||||
|
||||
ingest: IngestPort
|
||||
reader: ReadPort
|
||||
normalize: NormalizePort
|
||||
finalize: FinalizePort
|
||||
|
||||
@abstractmethod
|
||||
async def run(self, source: Any) -> list[dict[str, Any]]:
|
||||
"""Run the full stage chain and return the normalized records."""
|
||||
71
standards/mcp/templates/app/pipelines/example/impl.py
Normal file
71
standards/mcp/templates/app/pipelines/example/impl.py
Normal file
@@ -0,0 +1,71 @@
|
||||
"""# Summary
|
||||
|
||||
Example pipeline family — concrete stages, the wired root, and its registration.
|
||||
|
||||
The concrete subclass re-annotates each slot with a stage implementation; the DI
|
||||
container builds the whole tree. Register the family so the shared registry can
|
||||
resolve it by ``(kind, variant, mode)``.
|
||||
"""
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from pipelines.example.abc import (
|
||||
ExamplePipelinePort,
|
||||
IngestPort,
|
||||
NormalizePort,
|
||||
ReadPort,
|
||||
)
|
||||
from pipelines.shared.loader import build_pipeline
|
||||
from pipelines.shared.ports import FinalizePort
|
||||
from pipelines.shared.registry import register
|
||||
|
||||
|
||||
class TextIngest(IngestPort):
|
||||
"""Materialize any source as text."""
|
||||
|
||||
def materialize(self, source: Any) -> str:
|
||||
return source if isinstance(source, str) else str(source)
|
||||
|
||||
|
||||
class LineReader(ReadPort):
|
||||
"""Read one record per non-empty line."""
|
||||
|
||||
def read(self, content: str) -> list[dict[str, Any]]:
|
||||
return [{"line": line} for line in content.splitlines() if line.strip()]
|
||||
|
||||
|
||||
class PassthroughNormalize(NormalizePort):
|
||||
"""Return records unchanged (replace with real normalization)."""
|
||||
|
||||
def build(self, records: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
return records
|
||||
|
||||
|
||||
class NoopFinalize(FinalizePort):
|
||||
"""Drop records (replace with a service-backed finalize stage)."""
|
||||
|
||||
async def finalize(self, records: list[dict[str, Any]]) -> list[Any]:
|
||||
return records
|
||||
|
||||
|
||||
class ExamplePipeline(ExamplePipelinePort):
|
||||
"""Concrete example family — the dependency decisions live here."""
|
||||
|
||||
ingest: TextIngest
|
||||
reader: LineReader
|
||||
normalize: PassthroughNormalize
|
||||
finalize: NoopFinalize
|
||||
|
||||
async def run(self, source: Any) -> list[dict[str, Any]]:
|
||||
content = self.ingest.materialize(source)
|
||||
records = self.reader.read(content)
|
||||
return self.normalize.build(records)
|
||||
|
||||
|
||||
def get_example_pipeline() -> ExamplePipeline:
|
||||
"""Wire and return the example pipeline through the shared loader."""
|
||||
resources = Path(__file__).parent / "resources"
|
||||
return build_pipeline(ExamplePipeline, resources_dir=resources)
|
||||
|
||||
|
||||
register("example", "default", ExamplePipeline)
|
||||
18
standards/mcp/templates/app/pipelines/example/pipeline.yaml
Normal file
18
standards/mcp/templates/app/pipelines/example/pipeline.yaml
Normal file
@@ -0,0 +1,18 @@
|
||||
# Graph spec for the example family: nodes, edges, and the root.
|
||||
# Mirrors the port tree in abc.py. Replace with your family's graph.
|
||||
schema: ExampleRecord
|
||||
nodes:
|
||||
ingest:
|
||||
port: IngestPort
|
||||
reader:
|
||||
port: ReadPort
|
||||
normalize:
|
||||
port: NormalizePort
|
||||
finalize:
|
||||
port: FinalizePort
|
||||
edges:
|
||||
- ingest -> reader
|
||||
- reader -> normalize
|
||||
- normalize -> finalize
|
||||
roots:
|
||||
default: ExamplePipeline
|
||||
@@ -0,0 +1,4 @@
|
||||
# Pattern / rule fragments for the example family.
|
||||
# The loader merges every patterns/*.yaml into one registry by key.
|
||||
example:
|
||||
enabled: true
|
||||
@@ -0,0 +1,5 @@
|
||||
# Runtime spec consumed by the shared loader.
|
||||
kind: example
|
||||
variant: default
|
||||
mode: default
|
||||
patterns: []
|
||||
32
standards/mcp/templates/app/pipelines/item_sync.py
Normal file
32
standards/mcp/templates/app/pipelines/item_sync.py
Normal file
@@ -0,0 +1,32 @@
|
||||
"""# Summary
|
||||
|
||||
Item-sync pipeline — the demo pipeline axis of the blueprint.
|
||||
|
||||
Runs on the worker, consumes a pending job, and materializes its payload as an
|
||||
item. Steps are plain async functions here; once the chain branches or needs
|
||||
deterministic replay, wrap the steps in a dagpipe DAG (see standards
|
||||
"06_pipeline_scaffold").
|
||||
"""
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
async def run_item_sync(job, resources: dict) -> None:
|
||||
"""Materialize a pending job payload as an item.
|
||||
|
||||
Step 1: extract the payload from the job.
|
||||
Step 2: create the item through the item service.
|
||||
|
||||
Args:
|
||||
job: The pending job document.
|
||||
resources (dict): Wired services and adaptors.
|
||||
"""
|
||||
payload = job.payload or {}
|
||||
item_svc = resources["item_svc"]
|
||||
|
||||
await item_svc.create({
|
||||
"name": payload.get("name", job.name),
|
||||
"quantity": payload.get("quantity", 1),
|
||||
})
|
||||
logger.info("Created item from job %s", str(job.id))
|
||||
5
standards/mcp/templates/app/pipelines/shared/__init__.py
Normal file
5
standards/mcp/templates/app/pipelines/shared/__init__.py
Normal file
@@ -0,0 +1,5 @@
|
||||
"""# Summary
|
||||
|
||||
Shared pipeline scaffolding — ports, loader, and registry reused by every
|
||||
pipeline family. See standards "06_pipeline_scaffold".
|
||||
"""
|
||||
54
standards/mcp/templates/app/pipelines/shared/loader.py
Normal file
54
standards/mcp/templates/app/pipelines/shared/loader.py
Normal file
@@ -0,0 +1,54 @@
|
||||
"""# Summary
|
||||
|
||||
Pipeline loader — wire a family root through the DI library and attach the
|
||||
merged pattern registry from ``resources/patterns/*.yaml``.
|
||||
|
||||
All families share this loader so wiring is never hand-rolled.
|
||||
"""
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from hexa import build
|
||||
|
||||
|
||||
def load_patterns(resources_dir: str | Path) -> dict[str, Any]:
|
||||
"""Merge every pattern fragment under ``resources/patterns`` into one map.
|
||||
|
||||
Args:
|
||||
resources_dir (str | Path): Family resources directory.
|
||||
|
||||
Returns:
|
||||
dict[str, Any]: Merged pattern/rule fragments keyed by fragment name.
|
||||
"""
|
||||
registry: dict[str, Any] = {}
|
||||
patterns = Path(resources_dir) / "patterns"
|
||||
if patterns.is_dir():
|
||||
for path in sorted(patterns.glob("*.yaml")):
|
||||
data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
|
||||
registry.update(data)
|
||||
return registry
|
||||
|
||||
|
||||
def build_pipeline(
|
||||
root_cls,
|
||||
*,
|
||||
resources_dir: str | Path = "resources",
|
||||
instances: dict[str, Any] | None = None,
|
||||
config: dict[str, Any] | None = None,
|
||||
):
|
||||
"""Wire ``root_cls`` and inject the merged pattern registry.
|
||||
|
||||
Args:
|
||||
root_cls: The pipeline root class (a port tree).
|
||||
resources_dir (str | Path): Directory holding ``patterns/*.yaml``.
|
||||
instances (dict[str, Any] | None): Runtime objects injected by slot name.
|
||||
config (dict[str, Any] | None): Config values propagated by field name.
|
||||
|
||||
Returns:
|
||||
The fully wired pipeline root.
|
||||
"""
|
||||
merged_instances = dict(instances or {})
|
||||
merged_instances.setdefault("registry", load_patterns(resources_dir))
|
||||
return build(root_cls, instances=merged_instances, config=config or {})
|
||||
25
standards/mcp/templates/app/pipelines/shared/ports.py
Normal file
25
standards/mcp/templates/app/pipelines/shared/ports.py
Normal file
@@ -0,0 +1,25 @@
|
||||
"""# Summary
|
||||
|
||||
Shared pipeline ports — the contracts every pipeline family reuses.
|
||||
|
||||
A port is an abstract stage contract. Concrete families pin their implementations
|
||||
on a root's annotated slots; the DI library instantiates the tree.
|
||||
"""
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Any
|
||||
|
||||
|
||||
class FinalizePort(ABC):
|
||||
"""Terminal stage — turn normalized records into persisted resources."""
|
||||
|
||||
@abstractmethod
|
||||
async def finalize(self, records: list[dict[str, Any]]) -> list[Any]:
|
||||
"""Persist records and return the created resources."""
|
||||
|
||||
|
||||
class RegistryPort(ABC):
|
||||
"""Resolve a pattern / rule fragment by key."""
|
||||
|
||||
@abstractmethod
|
||||
def resolve(self, key: str) -> dict[str, Any]:
|
||||
"""Return the fragment registered under ``key``."""
|
||||
29
standards/mcp/templates/app/pipelines/shared/registry.py
Normal file
29
standards/mcp/templates/app/pipelines/shared/registry.py
Normal file
@@ -0,0 +1,29 @@
|
||||
"""# Summary
|
||||
|
||||
Family registry — resolve a ``(kind, variant, mode)`` triple to a root class.
|
||||
|
||||
A single lookup replaces hand-rolled ``if/else`` family selection.
|
||||
"""
|
||||
from typing import Dict, Type
|
||||
|
||||
# Populated by ``register`` as families import.
|
||||
_FAMILIES: Dict[str, Dict[str, Dict[str, Type]]] = {}
|
||||
|
||||
|
||||
def register(kind: str, variant: str, root_cls: Type, mode: str = "default") -> Type:
|
||||
"""Register ``root_cls`` for a ``(kind, variant, mode)`` triple.
|
||||
|
||||
Returns:
|
||||
Type: The registered class (so it can be used as a decorator).
|
||||
"""
|
||||
_FAMILIES.setdefault(kind, {}).setdefault(variant, {})[mode] = root_cls
|
||||
return root_cls
|
||||
|
||||
|
||||
def resolve_root(kind: str, variant: str, mode: str = "default") -> Type:
|
||||
"""Return the root class for a ``(kind, variant, mode)`` triple.
|
||||
|
||||
Raises:
|
||||
KeyError: When no family matches the triple.
|
||||
"""
|
||||
return _FAMILIES[kind][variant][mode]
|
||||
Reference in New Issue
Block a user