docs(standards): vendor template into MCP bundle; add component tools + start_app prompt

This commit is contained in:
2026-10-12 21:24:10 +05:30
parent 715bfd8022
commit 2d1278911c
68 changed files with 2044 additions and 102 deletions

View File

@@ -0,0 +1,5 @@
"""# Summary
Shared pipeline scaffolding — ports, loader, and registry reused by every
pipeline family. See standards "06_pipeline_scaffold".
"""

View 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 {})

View 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``."""

View 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]