docs/hexa/mcp/modules/hexa.json

{
  "module": "hexa",
  "content": {
    "path": "hexa",
    "docstring": "# Summary\n\nType-declared dependency injection for Python.\n\nHexa is a pattern and utility library for structuring complex hierarchical\npipelines. It rests on one core idea: a concrete class's annotated slot type\n*is* the dependency decision. Variation is expressed entirely as class\nannotations — never as imperative wiring, never as ``__init__`` parameters,\nnever as a composition root that assembles objects by hand.\n\nAll utilities serialize through a single shared model (``PortNode``):\n\n- ``parse_yaml`` / ``generate_yaml`` — between YAML specs and the model\n- ``parse_abc`` / ``generate_abc`` — between ABC Python modules and the model\n- ``check_matches`` — verify two representations describe the same tree\n- ``build`` — recursively instantiate a wired pipeline from annotations\n\n---\n# Installation\n\nInstall using pip:\n\n```bash\npip install hexa\n```\n\n---\n# Quick start\n\nDefine contracts, pin concrete types on the slots, and let ``build`` wire the\ntree from annotations:\n\n```python\nfrom hexa import build\n\nclass NumberPort(ABC):\n    @abstractmethod\n    def extract(self, line: str) -> float: ...\n\nclass ParserPort(ABC):\n    number: NumberPort\n\n    @abstractmethod\n    def parse(self, text: str) -> dict: ...\n\nclass RegexNumberPort(NumberPort):\n    def extract(self, line: str) -> float:\n        ...\n\nclass StandardParserPort(ParserPort):\n    number: RegexNumberPort  # <-- the dependency decision\n\n    def parse(self, text: str) -> dict:\n        return {\"value\": self.number.extract(text)}\n\npipeline = build(StandardParserPort)\nprint(pipeline.parse(\"Value: 42\"))\n```\n\n---\n# CLI usage\n\nConvert between YAML and ABC representations:\n\n```bash\nhexa parse-yaml spec.yaml\nhexa generate-abc spec.yaml --out spec_abc.py\nhexa parse-abc spec_abc.py\nhexa generate-yaml spec_abc.py --out spec.yaml\nhexa check spec.yaml spec_abc.py\n```\n\n---\n# Core concepts\n\n## Shared model\n``PortNode`` — the neutral tree every parser and generator serializes through.\n\n## Converters\nParsers and generators that translate between YAML specs and ABC Python\nmodules via the shared model.\n\n## Verification\n``check_matches`` — machine-check that two representations agree.\n\n## Container\n``build`` — recursively instantiate a full pipeline from class annotations.\n\n---\n# Notes\n\n- All utilities share a single model; any port tree fits.\n- Generators emit source text only; hexa performs no runtime code generation.",
    "objects": {
      "check_matches": {
        "name": "check_matches",
        "kind": "module",
        "path": "hexa.check_matches",
        "signature": null,
        "docstring": "# Summary\n\nVerify that two hexa representations agree.\n\n``check_matches`` parses two representations — one YAML spec and/or ABC Python\nmodule each — and reports whether they describe the same port tree.\n\n---\n# Notes\n\n- Uses ``PortNode.diff`` to produce human-readable difference strings.",
        "members": {
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.check_matches.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.check_matches.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.check_matches.PortNode.find",
                "signature": "find(name: str)",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.check_matches.PortNode.walk",
                "signature": "walk()",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.check_matches.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '')",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          },
          "parse_abc": {
            "name": "parse_abc",
            "kind": "function",
            "path": "hexa.check_matches.parse_abc",
            "signature": "parse_abc(module_or_path: str | Path | Any)",
            "docstring": "Parse an ABC Python module into a :class:`PortNode` tree.\n\nABC classes become port nodes.  A nested-struct attribute is expressed as a\n``@dataclass`` annotation on an ABC port (e.g. ``source: ExtractionSource``\nwhere ``ExtractionSource`` is a ``@dataclass``); the dataclass's fields are\nexpanded into a nested ``attributes`` entry.\n\nArgs:\n    module_or_path (str | Path | Any):\n        A file path to a ``.py`` file, a module import string, or a loaded\n        module.\n\nReturns:\n    PortNode:\n        The root node of the tree."
          },
          "parse_yaml": {
            "name": "parse_yaml",
            "kind": "function",
            "path": "hexa.check_matches.parse_yaml",
            "signature": "parse_yaml(path: str | Path)",
            "docstring": "Parse a hexa YAML spec file into a :class:`PortNode` tree.\n\nArgs:\n    path (str | Path):\n        Path to the ``.yaml`` file.\n\nReturns:\n    PortNode:\n        The root node of the parsed tree.\n\nRaises:\n    ValueError:\n        On structural errors in the YAML."
          },
          "check_matches": {
            "name": "check_matches",
            "kind": "function",
            "path": "hexa.check_matches.check_matches",
            "signature": "check_matches(path_a: str | Path, path_b: str | Path) -> bool | list[str]",
            "docstring": "Verify two representations agree.\n\nArgs:\n    path_a (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\n    path_b (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\nReturns:\n    bool | list[str]:\n        ``True`` if they match exactly, otherwise a list of difference\n        strings."
          }
        }
      },
      "build": {
        "name": "build",
        "kind": "function",
        "path": "hexa.build",
        "signature": "build(cls: type[T], *, instances: dict[str, Any] | None = None, config: dict[str, Any] | None = None)",
        "docstring": "Recursively instantiate the port tree from annotations.\n\nArgs:\n    cls (type[T]):\n        The root class to build (e.g. ``AxisExtractionPipeline``).\n\n    instances (dict[str, Any] | None):\n        ``{slot_name: object}`` injected verbatim into every node whose\n        annotations contain that name (runtime values — repos, handlers,\n        clients — that must not be re-constructed). Applied to the whole\n        tree by name.\n\n    config (dict[str, Any] | None):\n        ``{field_name: value}`` propagated by name to every node's\n        annotated config fields (non-port attributes), replacing the\n        default ``None``.\n\nReturns:\n    T:\n        A fully wired instance of ``cls`` and all its nested ports."
      },
      "generate_abc": {
        "name": "generate_abc",
        "kind": "module",
        "path": "hexa.generate_abc",
        "signature": null,
        "docstring": "# Summary\n\nGenerate ``_abc.py`` source from a hexa PortNode tree.",
        "members": {
          "NestedConfig": {
            "name": "NestedConfig",
            "kind": "attribute",
            "path": "hexa.generate_abc.NestedConfig",
            "signature": null,
            "docstring": null
          },
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.generate_abc.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.generate_abc.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.generate_abc.PortNode.find",
                "signature": "find(name: str)",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.generate_abc.PortNode.walk",
                "signature": "walk()",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.generate_abc.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '')",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          },
          "generate_abc": {
            "name": "generate_abc",
            "kind": "function",
            "path": "hexa.generate_abc.generate_abc",
            "signature": "generate_abc(node: PortNode, out_path: str | Path | None = None) -> str",
            "docstring": "Generate ABC Python source from a :class:`PortNode` tree.\n\nArgs:\n    node (PortNode):\n        The root of the parsed YAML (or generated) tree.\n\n    out_path (str | Path | None):\n        Optional file path to write the generated source to.\n\nReturns:\n    str:\n        The generated Python source code."
          }
        }
      },
      "generate_yaml": {
        "name": "generate_yaml",
        "kind": "module",
        "path": "hexa.generate_yaml",
        "signature": null,
        "docstring": "# Summary\n\nGenerate YAML spec (nested mapping form) from a hexa PortNode tree.",
        "members": {
          "MethodSpec": {
            "name": "MethodSpec",
            "kind": "class",
            "path": "hexa.generate_yaml.MethodSpec",
            "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
            "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.generate_yaml.MethodSpec.name",
                "signature": null,
                "docstring": null
              },
              "args": {
                "name": "args",
                "kind": "attribute",
                "path": "hexa.generate_yaml.MethodSpec.args",
                "signature": null,
                "docstring": null
              },
              "kwargs": {
                "name": "kwargs",
                "kind": "attribute",
                "path": "hexa.generate_yaml.MethodSpec.kwargs",
                "signature": null,
                "docstring": null
              }
            }
          },
          "NestedConfig": {
            "name": "NestedConfig",
            "kind": "attribute",
            "path": "hexa.generate_yaml.NestedConfig",
            "signature": null,
            "docstring": null
          },
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.generate_yaml.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.generate_yaml.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.generate_yaml.PortNode.find",
                "signature": "find(name: str)",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.generate_yaml.PortNode.walk",
                "signature": "walk()",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.generate_yaml.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '')",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          },
          "generate_yaml": {
            "name": "generate_yaml",
            "kind": "function",
            "path": "hexa.generate_yaml.generate_yaml",
            "signature": "generate_yaml(node: PortNode, out_path: str | Path | None = None) -> str",
            "docstring": "Generate YAML source from a :class:`PortNode` tree.\n\nArgs:\n    node (PortNode):\n        The root of the tree.\n\n    out_path (str | Path | None):\n        Optional file path to write the generated source to.\n\nReturns:\n    str:\n        The generated YAML source."
          }
        }
      },
      "MethodSpec": {
        "name": "MethodSpec",
        "kind": "class",
        "path": "hexa.MethodSpec",
        "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
        "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "hexa.MethodSpec.name",
            "signature": null,
            "docstring": null
          },
          "args": {
            "name": "args",
            "kind": "attribute",
            "path": "hexa.MethodSpec.args",
            "signature": null,
            "docstring": null
          },
          "kwargs": {
            "name": "kwargs",
            "kind": "attribute",
            "path": "hexa.MethodSpec.kwargs",
            "signature": null,
            "docstring": null
          }
        }
      },
      "PortNode": {
        "name": "PortNode",
        "kind": "class",
        "path": "hexa.PortNode",
        "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
        "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "hexa.PortNode.name",
            "signature": null,
            "docstring": null
          },
          "port_cls": {
            "name": "port_cls",
            "kind": "attribute",
            "path": "hexa.PortNode.port_cls",
            "signature": null,
            "docstring": null
          },
          "kind": {
            "name": "kind",
            "kind": "attribute",
            "path": "hexa.PortNode.kind",
            "signature": null,
            "docstring": null
          },
          "attributes": {
            "name": "attributes",
            "kind": "attribute",
            "path": "hexa.PortNode.attributes",
            "signature": null,
            "docstring": null
          },
          "children": {
            "name": "children",
            "kind": "attribute",
            "path": "hexa.PortNode.children",
            "signature": null,
            "docstring": null
          },
          "methods": {
            "name": "methods",
            "kind": "attribute",
            "path": "hexa.PortNode.methods",
            "signature": null,
            "docstring": null
          },
          "find": {
            "name": "find",
            "kind": "function",
            "path": "hexa.PortNode.find",
            "signature": "find(name: str)",
            "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
          },
          "walk": {
            "name": "walk",
            "kind": "function",
            "path": "hexa.PortNode.walk",
            "signature": "walk()",
            "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
          },
          "diff": {
            "name": "diff",
            "kind": "function",
            "path": "hexa.PortNode.diff",
            "signature": "diff(other: PortNode, path: str = '')",
            "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
          }
        }
      },
      "parse_abc": {
        "name": "parse_abc",
        "kind": "module",
        "path": "hexa.parse_abc",
        "signature": null,
        "docstring": "# Summary\n\nParse an ABC Python module into a hexa PortNode tree.\n\nABC classes become port nodes.  A nested-struct attribute is expressed as a\n``@dataclass`` annotation on an ABC port (e.g. ``source: ExtractionSource``\nwhere ``ExtractionSource`` is a ``@dataclass``); the dataclass's fields are\nexpanded into a nested ``attributes`` entry.\n\n---\n# Notes\n\n- Accepts a file path, a module import string, or an already-loaded module.",
        "members": {
          "ConfigValue": {
            "name": "ConfigValue",
            "kind": "attribute",
            "path": "hexa.parse_abc.ConfigValue",
            "signature": null,
            "docstring": null
          },
          "MethodSpec": {
            "name": "MethodSpec",
            "kind": "class",
            "path": "hexa.parse_abc.MethodSpec",
            "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
            "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.parse_abc.MethodSpec.name",
                "signature": null,
                "docstring": null
              },
              "args": {
                "name": "args",
                "kind": "attribute",
                "path": "hexa.parse_abc.MethodSpec.args",
                "signature": null,
                "docstring": null
              },
              "kwargs": {
                "name": "kwargs",
                "kind": "attribute",
                "path": "hexa.parse_abc.MethodSpec.kwargs",
                "signature": null,
                "docstring": null
              }
            }
          },
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.parse_abc.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.parse_abc.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.parse_abc.PortNode.find",
                "signature": "find(name: str)",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.parse_abc.PortNode.walk",
                "signature": "walk()",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.parse_abc.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '')",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          },
          "parse_abc": {
            "name": "parse_abc",
            "kind": "function",
            "path": "hexa.parse_abc.parse_abc",
            "signature": "parse_abc(module_or_path: str | Path | Any) -> PortNode",
            "docstring": "Parse an ABC Python module into a :class:`PortNode` tree.\n\nABC classes become port nodes.  A nested-struct attribute is expressed as a\n``@dataclass`` annotation on an ABC port (e.g. ``source: ExtractionSource``\nwhere ``ExtractionSource`` is a ``@dataclass``); the dataclass's fields are\nexpanded into a nested ``attributes`` entry.\n\nArgs:\n    module_or_path (str | Path | Any):\n        A file path to a ``.py`` file, a module import string, or a loaded\n        module.\n\nReturns:\n    PortNode:\n        The root node of the tree."
          }
        }
      },
      "parse_yaml": {
        "name": "parse_yaml",
        "kind": "module",
        "path": "hexa.parse_yaml",
        "signature": null,
        "docstring": "# Summary\n\nParse a hexa YAML spec into a :class:`PortNode` tree.\n\nThe YAML grammar uses a nested mapping format built from three member kinds:\n\n- **attribute**: a ``name: type`` scalar (e.g. ``source_type: str``)\n- **nested struct**: a ``name:`` mapping of sub-attributes (e.g. ``source:``)\n- **port**: a ``name:`` mapping whose single key is a class whose value is a\n  body, or a class key with a ``...`` body.  A port carries a class shape.\n\nDisambiguation of a mapping value:\n  A mapping with exactly one key whose value is a non-scalar body (a mapping,\n  ``...``, or a list) is a **port**.  Any other mapping (multiple keys, or all\n  scalar-typed values) is a **nested struct** of attributes.\n\n---\n# Examples\n\nParse a spec into a port tree:\n\n    ```python\n    from hexa import parse_yaml\n\n    node = parse_yaml(\"samples/minimal/sample.yaml\")\n    print(node)\n    ```\n\nThe YAML grammar:\n\n    ```yaml\n    RootClassName:\n      attr: type                 # scalar attribute\n      source:                    # nested struct (all scalar sub-attributes)\n        source_type: str\n        bank: str\n      methods:                   # reserved block of functions\n        run:\n          args: [a, b]\n      ingest:                    # port (single non-scalar class key)\n        IngestPort:\n          source_type: str\n          methods: {Method: ...}\n    ```\n\n---\n# Notes\n\n- See ``samples/minimal/sample.yaml`` and\n  ``samples/extraction_pipeline/extraction_pipeline.yaml`` for worked examples.",
        "members": {
          "ConfigValue": {
            "name": "ConfigValue",
            "kind": "attribute",
            "path": "hexa.parse_yaml.ConfigValue",
            "signature": null,
            "docstring": null
          },
          "MethodSpec": {
            "name": "MethodSpec",
            "kind": "class",
            "path": "hexa.parse_yaml.MethodSpec",
            "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
            "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.parse_yaml.MethodSpec.name",
                "signature": null,
                "docstring": null
              },
              "args": {
                "name": "args",
                "kind": "attribute",
                "path": "hexa.parse_yaml.MethodSpec.args",
                "signature": null,
                "docstring": null
              },
              "kwargs": {
                "name": "kwargs",
                "kind": "attribute",
                "path": "hexa.parse_yaml.MethodSpec.kwargs",
                "signature": null,
                "docstring": null
              }
            }
          },
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.parse_yaml.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.parse_yaml.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.parse_yaml.PortNode.find",
                "signature": "find(name: str)",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.parse_yaml.PortNode.walk",
                "signature": "walk()",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.parse_yaml.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '')",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          },
          "parse_yaml": {
            "name": "parse_yaml",
            "kind": "function",
            "path": "hexa.parse_yaml.parse_yaml",
            "signature": "parse_yaml(path: str | Path) -> PortNode",
            "docstring": "Parse a hexa YAML spec file into a :class:`PortNode` tree.\n\nArgs:\n    path (str | Path):\n        Path to the ``.yaml`` file.\n\nReturns:\n    PortNode:\n        The root node of the parsed tree.\n\nRaises:\n    ValueError:\n        On structural errors in the YAML."
          }
        }
      },
      "cli": {
        "name": "cli",
        "kind": "module",
        "path": "hexa.cli",
        "signature": null,
        "docstring": "# Summary\n\nCommand-line interface for hexa utilities.\n\n---\n# Usage\n\n    hexa parse-yaml PATH\n    hexa generate-abc PATH [--out FILE]\n    hexa parse-abc PATH\n    hexa generate-yaml PATH [--out FILE]\n    hexa check PATH_A PATH_B",
        "members": {
          "check_matches": {
            "name": "check_matches",
            "kind": "function",
            "path": "hexa.cli.check_matches",
            "signature": "check_matches(path_a: str | Path, path_b: str | Path)",
            "docstring": "Verify two representations agree.\n\nArgs:\n    path_a (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\n    path_b (str | Path):\n        Path to a ``.yaml`` or ``.py`` file.\n\nReturns:\n    bool | list[str]:\n        ``True`` if they match exactly, otherwise a list of difference\n        strings."
          },
          "generate_abc": {
            "name": "generate_abc",
            "kind": "function",
            "path": "hexa.cli.generate_abc",
            "signature": "generate_abc(node: PortNode, out_path: str | Path | None = None)",
            "docstring": "Generate ABC Python source from a :class:`PortNode` tree.\n\nArgs:\n    node (PortNode):\n        The root of the parsed YAML (or generated) tree.\n\n    out_path (str | Path | None):\n        Optional file path to write the generated source to.\n\nReturns:\n    str:\n        The generated Python source code."
          },
          "generate_yaml": {
            "name": "generate_yaml",
            "kind": "function",
            "path": "hexa.cli.generate_yaml",
            "signature": "generate_yaml(node: PortNode, out_path: str | Path | None = None)",
            "docstring": "Generate YAML source from a :class:`PortNode` tree.\n\nArgs:\n    node (PortNode):\n        The root of the tree.\n\n    out_path (str | Path | None):\n        Optional file path to write the generated source to.\n\nReturns:\n    str:\n        The generated YAML source."
          },
          "parse_abc": {
            "name": "parse_abc",
            "kind": "function",
            "path": "hexa.cli.parse_abc",
            "signature": "parse_abc(module_or_path: str | Path | Any)",
            "docstring": "Parse an ABC Python module into a :class:`PortNode` tree.\n\nABC classes become port nodes.  A nested-struct attribute is expressed as a\n``@dataclass`` annotation on an ABC port (e.g. ``source: ExtractionSource``\nwhere ``ExtractionSource`` is a ``@dataclass``); the dataclass's fields are\nexpanded into a nested ``attributes`` entry.\n\nArgs:\n    module_or_path (str | Path | Any):\n        A file path to a ``.py`` file, a module import string, or a loaded\n        module.\n\nReturns:\n    PortNode:\n        The root node of the tree."
          },
          "parse_yaml": {
            "name": "parse_yaml",
            "kind": "function",
            "path": "hexa.cli.parse_yaml",
            "signature": "parse_yaml(path: str | Path)",
            "docstring": "Parse a hexa YAML spec file into a :class:`PortNode` tree.\n\nArgs:\n    path (str | Path):\n        Path to the ``.yaml`` file.\n\nReturns:\n    PortNode:\n        The root node of the parsed tree.\n\nRaises:\n    ValueError:\n        On structural errors in the YAML."
          },
          "main": {
            "name": "main",
            "kind": "function",
            "path": "hexa.cli.main",
            "signature": "main() -> None",
            "docstring": null
          }
        }
      },
      "container": {
        "name": "container",
        "kind": "module",
        "path": "hexa.container",
        "signature": null,
        "docstring": "# Summary\n\nContainer to build a wired hexa pipeline from annotations.\n\n``build`` recursively instantiates the port tree implied by a root class's\nannotations, injecting provided runtime instances and config values by name.\n\n---\n# Notes\n\n- Runtime instances and config values are applied by name across the whole tree.",
        "members": {
          "T": {
            "name": "T",
            "kind": "attribute",
            "path": "hexa.container.T",
            "signature": null,
            "docstring": null
          },
          "build": {
            "name": "build",
            "kind": "function",
            "path": "hexa.container.build",
            "signature": "build(cls: type[T], *, instances: dict[str, Any] | None = None, config: dict[str, Any] | None = None) -> T",
            "docstring": "Recursively instantiate the port tree from annotations.\n\nArgs:\n    cls (type[T]):\n        The root class to build (e.g. ``AxisExtractionPipeline``).\n\n    instances (dict[str, Any] | None):\n        ``{slot_name: object}`` injected verbatim into every node whose\n        annotations contain that name (runtime values — repos, handlers,\n        clients — that must not be re-constructed). Applied to the whole\n        tree by name.\n\n    config (dict[str, Any] | None):\n        ``{field_name: value}`` propagated by name to every node's\n        annotated config fields (non-port attributes), replacing the\n        default ``None``.\n\nReturns:\n    T:\n        A fully wired instance of ``cls`` and all its nested ports."
          }
        }
      },
      "model": {
        "name": "model",
        "kind": "module",
        "path": "hexa.model",
        "signature": null,
        "docstring": "# Summary\n\nShared neutral model for hexa port trees.\n\nAll utilities (``parse_yaml``, ``generate_abc``, ``parse_abc``,\n``generate_yaml``, ``check_matches``) serialize through this single model.\n\n---\n# Notes\n\n- The model is NOT tied to any sample — any port tree fits.",
        "members": {
          "NestedConfig": {
            "name": "NestedConfig",
            "kind": "attribute",
            "path": "hexa.model.NestedConfig",
            "signature": null,
            "docstring": null
          },
          "ConfigValue": {
            "name": "ConfigValue",
            "kind": "attribute",
            "path": "hexa.model.ConfigValue",
            "signature": null,
            "docstring": null
          },
          "MethodSpec": {
            "name": "MethodSpec",
            "kind": "class",
            "path": "hexa.model.MethodSpec",
            "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
            "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.model.MethodSpec.name",
                "signature": null,
                "docstring": null
              },
              "args": {
                "name": "args",
                "kind": "attribute",
                "path": "hexa.model.MethodSpec.args",
                "signature": null,
                "docstring": null
              },
              "kwargs": {
                "name": "kwargs",
                "kind": "attribute",
                "path": "hexa.model.MethodSpec.kwargs",
                "signature": null,
                "docstring": null
              }
            }
          },
          "PortNode": {
            "name": "PortNode",
            "kind": "class",
            "path": "hexa.model.PortNode",
            "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
            "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
            "members": {
              "name": {
                "name": "name",
                "kind": "attribute",
                "path": "hexa.model.PortNode.name",
                "signature": null,
                "docstring": null
              },
              "port_cls": {
                "name": "port_cls",
                "kind": "attribute",
                "path": "hexa.model.PortNode.port_cls",
                "signature": null,
                "docstring": null
              },
              "kind": {
                "name": "kind",
                "kind": "attribute",
                "path": "hexa.model.PortNode.kind",
                "signature": null,
                "docstring": null
              },
              "attributes": {
                "name": "attributes",
                "kind": "attribute",
                "path": "hexa.model.PortNode.attributes",
                "signature": null,
                "docstring": null
              },
              "children": {
                "name": "children",
                "kind": "attribute",
                "path": "hexa.model.PortNode.children",
                "signature": null,
                "docstring": null
              },
              "methods": {
                "name": "methods",
                "kind": "attribute",
                "path": "hexa.model.PortNode.methods",
                "signature": null,
                "docstring": null
              },
              "find": {
                "name": "find",
                "kind": "function",
                "path": "hexa.model.PortNode.find",
                "signature": "find(name: str) -> PortNode | None",
                "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
              },
              "walk": {
                "name": "walk",
                "kind": "function",
                "path": "hexa.model.PortNode.walk",
                "signature": "walk() -> list[PortNode]",
                "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
              },
              "diff": {
                "name": "diff",
                "kind": "function",
                "path": "hexa.model.PortNode.diff",
                "signature": "diff(other: PortNode, path: str = '') -> list[str]",
                "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
              }
            }
          }
        }
      }
    }
  }
}