compmech-reference-pack 0.3.1__py3-none-any.whl

compmech_reference_pack/__init__.py

@@ -0,0 +1,22 @@
+"""compmech_reference_pack — Tier-2 computational-mechanics companion adapter.
+
+Bridges AKMS ``akms_learn`` Learning Source Packet (LSP) excerpts to the
+MechDSL Tier-1 ``mechdsl.integration`` façade: it normalises human-authored
+algpseudocode into algo2code-grammar-clean form, then emits executable Python
+and/or compiled-solver summaries with provenance.
+
+This package depends on **both** ``akms-learn`` and ``mechdsl-core`` (plus
+``algo2code``, MechDSL's transpiler backend). It registers the
+``executable_bridge`` adapter so ``akms_learn`` reports
+``executable_bridge_adapter = available``.
+
+Companion-adapter pattern: MechDSL stays AKMS-unaware; this package is the only
+place that knows about both sides. The public surface is populated across the
+the executable-bridge tier.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__: list[str] = []

compmech_reference_pack/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""compmech_reference_pack adapters — the executable-bridge runner (Tier 2)."""
+
+from __future__ import annotations
+
+from compmech_reference_pack.adapters.mechdsl_runner import (
+    MechDSLRunner,
+    adapter_registry_overrides,
+    available_adapter_registry,
+)
+
+__all__ = [
+    "MechDSLRunner",
+    "adapter_registry_overrides",
+    "available_adapter_registry",
+]

compmech_reference_pack/adapters/mechdsl_runner.py

@@ -0,0 +1,321 @@
+"""mechdsl_runner.py — MechDSLRunner, the executable_bridge adapter.
+
+Bridges a bounded AKMS LSP excerpt to the MechDSL Tier-1 façade
+(``mechdsl.integration``) and assembles a provenance-carrying artefact dict.
+
+Contract (the real one, NOT the spec's ``build_artifacts``)::
+
+    build_executable(excerpt: dict, *, options: dict | None = None) -> dict
+
+Behaviour
+---------
+- **Emit-only by default.** ``build_executable`` normalises the node's
+  ``extracted["implementation"]`` (algpseudocode) and calls Tier-1
+  ``transpile_algorithm``, and — when a ``% mechanics`` problem source plus an
+  energy ``derivation`` are present — Tier-1 ``compile_from_sources``. Both are
+  Taichi-free.
+- **Taichi only on demand.** Tier-1 ``verify`` is called **only** when
+  ``options["run_verify"]`` is truthy; that is the single Taichi-paying branch.
+- **Never invalidates the packet** (spec 09 §7 rule 5): a transpile/compile
+  failure is captured into ``warnings`` and reported as ``status="error"``
+  only when the caller explicitly required executable output
+  (``options["require_executable"]``); otherwise ``status`` stays ``"ok"``.
+
+No-mutation invariant: this adapter never writes to any AKMS path.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from akms_learn.adapters.status import AdapterStatus, adapter_registry
+
+ADAPTER_ID = "compmech.mechdsl_runner"
+
+__all__ = [
+    "ADAPTER_ID",
+    "MechDSLRunner",
+    "adapter_registry_overrides",
+    "available_adapter_registry",
+]
+
+
+def adapter_registry_overrides() -> dict[str, AdapterStatus]:
+    """Registry override that marks the executable bridge available."""
+    return {"executable_bridge_adapter": AdapterStatus.available}
+
+
+def available_adapter_registry() -> dict[str, AdapterStatus]:
+    """Return the akms_learn adapter registry with this adapter marked available."""
+    return adapter_registry(adapter_registry_overrides())
+
+
+def _algo_name_from_node_id(node_id: str) -> str:
+    """Derive a safe algo2code algorithm name from a node id."""
+    tail = node_id.rsplit(".", 1)[-1].rsplit("/", 1)[-1]
+    cleaned = re.sub(r"[^0-9A-Za-z_]", "_", tail).strip("_")
+    return cleaned or "algorithm"
+
+
+class MechDSLRunner:
+    """ExecutableBridgeAdapter implementation backed by MechDSL Tier-1.
+
+    Satisfies ``akms_learn.adapters.protocols.ExecutableBridgeAdapter`` via
+    structural subtyping (the protocol is ``@runtime_checkable``).
+    """
+
+    adapter_id = ADAPTER_ID
+
+    # -- protocol surface ---------------------------------------------------
+
+    def build_executable(
+        self, excerpt: dict[str, Any], *, options: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Build an executable artefact from a bounded LSP excerpt.
+
+        Returns the 8-key contract dict ``{adapter, status, emitted_source,
+        transpiled, normalized_input, provenance, vv_plan, warnings}``. When
+        ``options["run_verify"]`` is truthy a 9th key ``verification`` (the
+        Tier-1 ``verify`` result) is added — that opt-in path is the only one
+        that pays the Taichi cost. Never raises on a malformed excerpt.
+        """
+        options = options or {}
+        run_verify = bool(options.get("run_verify", False))
+        require_executable = bool(options.get("require_executable", False))
+
+        node = self._select_node(excerpt)
+        node_id = str(node.get("node_id") or excerpt.get("node_id") or "<unknown>")
+        extracted = node.get("extracted")
+        if not isinstance(extracted, dict):
+            extracted = {}
+        implementation = extracted.get("implementation")
+        derivation = extracted.get("derivation")
+        problem = extracted.get("problem")
+
+        warnings: list[str] = []
+        status = "ok"
+        normalized_input: str | None = None
+        transpiled: dict[str, Any] | None = None
+        emitted_source: str | None = None
+
+        # --- implementation -> normalize -> Tier-1 transpile (Taichi-free) ---
+        if implementation:
+            from compmech_reference_pack.normalize import normalize
+
+            norm = normalize(
+                implementation, algorithm_name=_algo_name_from_node_id(node_id)
+            )
+            normalized_input = norm.normalized
+            warnings.extend(norm.warnings)
+            if norm.algorithmic_block_found:
+                try:
+                    from mechdsl.integration import transpile_algorithm
+                except ImportError as exc:
+                    warnings.append(
+                        "MechDSL backend unavailable; install "
+                        '"compmech-reference-pack[mechdsl]" '
+                        f"({type(exc).__name__}: {exc})"
+                    )
+                    if require_executable:
+                        status = "error"
+                else:
+                    try:
+                        transpiled = transpile_algorithm(
+                            norm.normalized, backend="taichi"
+                        )
+                        if not transpiled.get("valid_python", False):
+                            warnings.append(
+                                "transpiled code did not compile as valid Python"
+                            )
+                            if require_executable:
+                                status = "error"
+                    except Exception as exc:
+                        warnings.append(
+                            f"transpile failed: {type(exc).__name__}: {exc}"
+                        )
+                        if require_executable:
+                            status = "error"
+
+        # --- derivation (+ problem) -> Tier-1 compile (Taichi-free) ----------
+        if derivation and problem:
+            try:
+                from mechdsl.integration import compile_from_sources
+            except ImportError as exc:
+                warnings.append(
+                    "MechDSL backend unavailable; install "
+                    '"compmech-reference-pack[mechdsl]" '
+                    f"({type(exc).__name__}: {exc})"
+                )
+                if require_executable:
+                    status = "error"
+            else:
+                try:
+                    compiled = compile_from_sources(
+                        problem_source=problem, energy_source=derivation
+                    )
+                    emitted_source = compiled["emitted_source"]
+                except Exception as exc:
+                    warnings.append(
+                        f"compile_from_sources failed: {type(exc).__name__}: {exc}"
+                    )
+                    if require_executable:
+                        status = "error"
+        elif derivation and not problem:
+            warnings.append(
+                "node carries a derivation but no '% mechanics' problem source; "
+                "skipping compile_from_sources (provide extracted['problem'] to compile)"
+            )
+
+        if implementation is None and derivation is None:
+            status = "error"
+            warnings.append(
+                f"excerpt node {node_id!r} carries neither an implementation nor a "
+                "derivation; nothing to build"
+            )
+
+        result: dict[str, Any] = {
+            "adapter": ADAPTER_ID,
+            "status": status,
+            "emitted_source": emitted_source,
+            "transpiled": transpiled,
+            "normalized_input": normalized_input,
+            "provenance": {
+                node_id: {
+                    "sections": self._sections(node),
+                    "references": self._references(node_id, node, excerpt),
+                }
+            },
+            "vv_plan": self._vv_plan(node_id, node, excerpt, options),
+            "warnings": warnings,
+        }
+
+        # --- the only Taichi-paying branch ----------------------------------
+        if run_verify:
+            result["verification"] = self._run_verify(options, warnings)
+
+        return result
+
+    # -- extra surface (per plan: status() / can_handle()) ------------------
+
+    def status(self) -> dict[str, Any]:
+        """Lightweight, Taichi-free availability descriptor for status routes."""
+        return {
+            "adapter": ADAPTER_ID,
+            "available": True,
+            "companion_role": "executable_bridge",
+            "taichi_required_for": ["verify"],
+        }
+
+    def can_handle(self, excerpt: dict[str, Any]) -> bool:
+        """True when the excerpt has a node carrying implementation/derivation.
+
+        Total: returns ``False`` (never raises) for any malformed excerpt
+        shape — missing ``nodes``, non-dict nodes, non-dict ``extracted``.
+        """
+        node = self._select_node(excerpt)
+        extracted = node.get("extracted")
+        if not isinstance(extracted, dict):
+            return False
+        return bool(extracted.get("implementation") or extracted.get("derivation"))
+
+    # -- internals ----------------------------------------------------------
+
+    @staticmethod
+    def _select_node(excerpt: dict[str, Any]) -> dict[str, Any]:
+        """Pick the node dict to build from.
+
+        Accepts a node-shaped excerpt directly, a ``{"nodes": [...]}`` excerpt
+        (first node carrying implementation/derivation, else the first node),
+        or any dict (treated as the node).
+        """
+        nodes = excerpt.get("nodes")
+        if isinstance(nodes, list):
+            dict_nodes = [n for n in nodes if isinstance(n, dict)]
+            for node in dict_nodes:
+                extracted = node.get("extracted")
+                if isinstance(extracted, dict) and (
+                    extracted.get("implementation") or extracted.get("derivation")
+                ):
+                    return node
+            # No build-bearing node — return the first dict node, or {} so
+            # callers never touch a non-dict (None, str, …).
+            return dict_nodes[0] if dict_nodes else {}
+        return excerpt
+
+    @staticmethod
+    def _sections(node: dict[str, Any]) -> Any:
+        return node.get("included_sections") or node.get("sections") or []
+
+    @staticmethod
+    def _references(
+        node_id: str, node: dict[str, Any], excerpt: dict[str, Any]
+    ) -> list[Any]:
+        """Collect references attributable to this node.
+
+        Prefers node-local references; otherwise filters packet-level
+        references by ``source_node_ids`` membership (falling back to all).
+        """
+        node_refs = node.get("references")
+        if isinstance(node_refs, list) and node_refs:
+            return list(node_refs)
+
+        packet_refs = excerpt.get("references")
+        if not isinstance(packet_refs, list):
+            return []
+        scoped = [
+            ref
+            for ref in packet_refs
+            if isinstance(ref, dict) and node_id in (ref.get("source_node_ids") or [])
+        ]
+        return scoped or list(packet_refs)
+
+    @classmethod
+    def _vv_plan(
+        cls,
+        node_id: str,
+        node: dict[str, Any],
+        excerpt: dict[str, Any],
+        options: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Assemble a verification-and-validation plan {benchmark, citation}.
+
+        The citation is drawn from the same node-scoped reference list used for
+        provenance (via :meth:`_references`), so the two never disagree.
+        """
+        extracted = node.get("extracted")
+        if not isinstance(extracted, dict):
+            extracted = {}
+        benchmark = (
+            options.get("benchmark")
+            or extracted.get("benchmark")
+            or excerpt.get("benchmark")
+        )
+        citation: Any = None
+        for ref in cls._references(node_id, node, excerpt):
+            if isinstance(ref, dict):
+                citation = ref.get("citation") or ref.get("title")
+                if citation:
+                    break
+        return {"benchmark": benchmark, "citation": citation}
+
+    @staticmethod
+    def _run_verify(options: dict[str, Any], warnings: list[str]) -> dict[str, Any]:
+        """Run the single Taichi-paying Tier-1 verify branch."""
+        kind = options.get("verify_kind", "patch_test")
+        params = options.get("verify_params", {})
+
+        try:
+            from mechdsl.integration import verify
+
+            return verify(kind, params)
+        except ImportError as exc:
+            warnings.append(
+                "MechDSL backend unavailable; install "
+                '"compmech-reference-pack[mechdsl]" '
+                f"({type(exc).__name__}: {exc})"
+            )
+            return {"kind": kind, "passed": False, "details": {"error": str(exc)}}
+        except Exception as exc:
+            warnings.append(f"verify failed: {type(exc).__name__}: {exc}")
+            return {"kind": kind, "passed": False, "details": {"error": str(exc)}}

compmech_reference_pack/capabilities.py

@@ -0,0 +1,67 @@
+"""Capability declarations for compmech_reference_pack.
+
+`CEmM2/Logic-Loom <https://github.com/CEmM2/Logic-Loom>`_ imports this package
+from its ``GET /api/mechdsl/status`` route and reads the capability surface to
+decide whether to expose the MechDSL gate.
+This module is deliberately import-light and **Taichi-free**: it declares
+*what* the package offers; it never runs a solve or initialises Taichi.
+
+Two capabilities are declared:
+
+- ``executable_bridge_adapter`` — the package registers ``MechDSLRunner`` as
+  the ``executable_bridge`` adapter (``akms_learn`` reports it available).
+- ``code_mirror_provenance`` — ``build_executable`` attaches per-node
+  provenance (source sections + references) to every emitted artefact.
+"""
+
+from __future__ import annotations
+
+from compmech_reference_pack import __version__
+
+__all__ = [
+    "ADAPTER_ID",
+    "CODE_MIRROR_PROVENANCE",
+    "EXECUTABLE_BRIDGE_ADAPTER",
+    "capabilities",
+]
+
+#: Stable id of the executable-bridge adapter this package registers.
+ADAPTER_ID = "compmech.mechdsl_runner"
+
+#: Capability keys (also the akms_learn adapter-registry capability names).
+EXECUTABLE_BRIDGE_ADAPTER = "executable_bridge_adapter"
+CODE_MIRROR_PROVENANCE = "code_mirror_provenance"
+
+
+def capabilities() -> dict:
+    """Return the machine-readable capability surface for status discovery.
+
+    Shape consumed by Logic-Loom's status route::
+
+        {package, version, domain_pack, adapter_id, capabilities: {...}}
+
+    The dict is JSON-serialisable and contains no runtime objects.
+    """
+    return {
+        "package": "compmech_reference_pack",
+        "version": __version__,
+        "domain_pack": "compmech.reference",
+        "adapter_id": ADAPTER_ID,
+        "capabilities": {
+            EXECUTABLE_BRIDGE_ADAPTER: {
+                "available": True,
+                "adapter_id": ADAPTER_ID,
+                "companion_role": "executable_bridge",
+                "actions": ["emit", "transpile", "verify"],
+                # Mirrors the Tier-1 contract: only ``verify`` pays Taichi.
+                "taichi_required_for": ["verify"],
+            },
+            CODE_MIRROR_PROVENANCE: {
+                "available": True,
+                "source_pack_id": "compmech.mechdsl",
+                "repo": "CEmM2/MechDSL",
+                # build_executable attaches {node_id: {sections, references}}.
+                "provenance_keys": ["sections", "references"],
+            },
+        },
+    }

compmech_reference_pack/domain_pack/domain_pack.yaml

@@ -0,0 +1,49 @@
+domain_pack_schema: akms-learn-domain-pack/v1
+domain_id: compmech
+pack_id: compmech.reference
+name: Computational Mechanics Reference Pack
+version: "0.1.0"
+status: reference
+summary: >-
+  Reference computational-mechanics domain pack for AKMS Learn. Promoted from
+  the AKMS_learn test fixture by compmech_reference_pack (Tier-2 executable
+  bridge); the MechDSL companion is now an available executable runner.
+compatibility:
+  akms_learn_schema_min: learn/v0.1
+  akms_learn_schema_max: learn/v0.1
+roots:
+  nodes: nodes/compmech
+  code_mirror: code-mirror/compmech
+  examples: learning_examples/compmech
+  bundles: lesson_bundles/compmech
+capabilities:
+  static_markdown: true
+  static_notebook: true
+  executable_notebook: false
+  external_runner: true
+  code_mirror: true
+# `constkit` and `symbolic_fem_workbench` stay `planned`: their adapters are
+# not written. Their source is public — both live under
+# https://github.com/SOSOVSKI/Teaching-materials — so `planned` here describes
+# the adapter, not the availability of the material.
+companion_roles:
+  - id: constkit
+    package_name: compmech.constkit
+    runtime_hint: optional
+    capability_status: planned
+  - id: symbolic_fem_workbench
+    package_name: compmech.symbolic_fem_workbench
+    runtime_hint: optional
+    capability_status: planned
+  - id: mechdsl
+    package_name: compmech.mechdsl
+    runtime_hint: required
+    capability_status: available
+source_packs:
+  - source_packs/constkit.yaml
+  - source_packs/symbolic_fem_workbench.yaml
+  - source_packs/mechdsl.yaml
+provenance:
+  source_repos: []
+  generated_vault_ref: null
+  zotero_collection_refs: []

compmech_reference_pack/domain_pack/source_packs/constkit.yaml

@@ -0,0 +1,28 @@
+source_pack_schema: akms-learn-source-pack/v1
+source_pack_id: compmech.constkit
+name: ConstKit Concept Helpers
+version: "0.1.0"
+companion_role: concept_kit
+# The source is public and obtainable; the adapter that would consume it is
+# not written yet. `planned` describes the adapter, not the availability of
+# the material.
+capability_status: planned
+repo:
+  kind: github
+  name: SOSOVSKI/Teaching-materials
+  ref: main
+roots:
+  docs: packages/constkit/docs
+  code: packages/constkit/src/constkit
+  tests: packages/constkit/tests
+capabilities:
+  static_code_mirror: true
+  static_lessons: true
+  notebook_cells: false
+  executable_runner: false
+runtime:
+  required_python: ">=3.12,<3.13"
+  dependencies: []
+adapter:
+  adapter_id: compmech.constkit_adapter
+  status: planned

compmech_reference_pack/domain_pack/source_packs/mechdsl.yaml

@@ -0,0 +1,26 @@
+source_pack_schema: akms-learn-source-pack/v1
+source_pack_id: compmech.mechdsl
+name: MechDSL Executable Bridge
+version: "0.1.0"
+companion_role: executable_bridge
+capability_status: available
+repo:
+  kind: github
+  name: CEmM2/MechDSL
+  ref: main
+roots:
+  docs: dev/design_docs
+  code: packages/mechdsl-core/src/mechdsl
+  examples: dev/examples
+  tests: packages/mechdsl-core/tests
+capabilities:
+  static_code_mirror: true
+  static_lessons: true
+  notebook_cells: false
+  executable_runner: true
+runtime:
+  required_python: ">=3.12,<3.13"
+  dependencies: []
+adapter:
+  adapter_id: compmech.mechdsl_runner
+  status: available

compmech_reference_pack/domain_pack/source_packs/symbolic_fem_workbench.yaml

@@ -0,0 +1,29 @@
+source_pack_schema: akms-learn-source-pack/v1
+source_pack_id: compmech.symbolic_fem_workbench
+name: Symbolic FEM Workbench
+version: "0.1.0"
+companion_role: pedagogical_workbench
+# The source is public and obtainable; the adapter that would consume it is
+# not written yet. `planned` describes the adapter, not the availability of
+# the material.
+capability_status: planned
+repo:
+  kind: github
+  name: SOSOVSKI/Teaching-materials
+  ref: main
+roots:
+  docs: packages/symbolic-fem-workbench/docs
+  code: packages/symbolic-fem-workbench/src/symbolic_fem_workbench
+  examples: packages/symbolic-fem-workbench/notebooks
+  tests: packages/symbolic-fem-workbench/tests
+capabilities:
+  static_code_mirror: true
+  static_lessons: true
+  notebook_cells: true
+  executable_runner: false
+runtime:
+  required_python: ">=3.12,<3.13"
+  dependencies: []
+adapter:
+  adapter_id: compmech.symbolic_fem_workbench_adapter
+  status: planned

compmech_reference_pack/normalize.py

@@ -0,0 +1,192 @@
+"""normalize.py — rewrite human-authored algpseudocode into algo2code-clean form.
+
+The Tier-2 adapter's pre-processing core. An LSP node's
+``extracted["implementation"]`` is human/markdown-authored algpseudocode;
+``algo2code.transpile`` expects an ``algorithmic`` block optionally preceded by
+``% algorithm/backend/args/type`` directive lines.
+
+What this pass actually does
+----------------------------
+Empirically, MechDSL's current ``algo2code`` expression grammar already
+subsumes the rewrites the original plan anticipated (``\\sqrt{3/2}``,
+``\\frac{a}{b}``, ``\\cdot``, ``\\left/\\right``, Greek letters, ``^{...}``,
+and ``\\If/\\Else/\\ElsIf/\\While/\\For`` control flow all transpile as-is).
+So the genuinely-useful work here is:
+
+1. **Extract** the ``\\begin{algorithmic} … \\end{algorithmic}`` block out of
+   surrounding markdown (prose, code fences) so the source is bounded and the
+   *absence* of an algorithm is detectable (``algo2code`` silently emits an
+   empty function otherwise).
+2. **Synthesise directives** — prepend ``% algorithm <name>`` / ``% backend
+   taichi`` when the author didn't, so the emitted function is meaningfully
+   named instead of the ``algo2code`` default ``algorithm``; author-supplied
+   directives are preserved.
+3. **Surface parser failures as structured warnings, never raise** — per spec
+   09 §7 rule 5 (a failed adapter must not invalidate the packet unless
+   executable output was explicitly required).
+
+The public deliverable is :func:`normalize_algpseudocode` (``str -> str``);
+:func:`normalize` wraps it with a trial parse and the warning report the
+adapter consumes.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = [
+    "NormalizationResult",
+    "extract_algorithmic_block",
+    "normalize",
+    "normalize_algpseudocode",
+]
+
+_ALGORITHMIC_RE = re.compile(
+    r"\\begin\{algorithmic\}(?:\[[^\]]*\])?(?P<body>.*?)\\end\{algorithmic\}",
+    re.DOTALL,
+)
+_FENCE_RE = re.compile(r"^[ \t]*```[^\n]*$", re.MULTILINE)
+# ":=" is the only assignment arrow algo2code does not accept; "\gets" and
+# "\leftarrow" parse natively but we canonicalise all three to "=".
+_ARROW_RE = re.compile(r":=|\\gets|\\leftarrow")
+_DIRECTIVE_KEYWORDS = frozenset({"algorithm", "backend", "args", "type"})
+
+
+@dataclass(frozen=True)
+class NormalizationResult:
+    """Outcome of normalising one implementation excerpt.
+
+    Attributes
+    ----------
+    normalized:
+        algo2code-ready source (synthesised directives + algorithmic block).
+    algorithmic_block_found:
+        Whether an ``\\begin{algorithmic}`` block was present in the input.
+    parses:
+        Whether ``algo2code.parse_algorithm`` accepted the normalised source.
+    warnings:
+        Structured, human-readable warnings (missing block, parse errors).
+        Never empty when ``parses`` is ``False`` or the block was absent.
+    """
+
+    normalized: str
+    algorithmic_block_found: bool
+    parses: bool
+    warnings: tuple[str, ...] = ()
+
+
+def extract_algorithmic_block(impl_md: str) -> str | None:
+    """Return the inner body of the first ``algorithmic`` block, or ``None``.
+
+    Markdown code fences are stripped first so a fenced ``\\begin{algorithmic}``
+    is still found. The returned body excludes the ``\\begin``/``\\end`` markers.
+    """
+    if not impl_md:
+        return None
+    text = _FENCE_RE.sub("", impl_md)
+    match = _ALGORITHMIC_RE.search(text)
+    if match is None:
+        return None
+    return match.group("body").strip("\n")
+
+
+def _sanitize_identifier(name: str) -> str:
+    """Coerce an arbitrary string into a safe algo2code algorithm identifier."""
+    cleaned = re.sub(r"[^0-9A-Za-z_]", "_", name).strip("_")
+    if not cleaned:
+        return "algorithm"
+    if cleaned[0].isdigit():
+        cleaned = f"a_{cleaned}"
+    return cleaned
+
+
+def _collect_directives(impl_md: str) -> list[str]:
+    """Collect author-supplied ``% algorithm/backend/args/type`` directives.
+
+    Only lines *before* the algorithmic block are considered, so ``%`` lines
+    that happen to live inside the block are not mistaken for directives.
+    """
+    head = impl_md
+    begin = impl_md.find(r"\begin{algorithmic}")
+    if begin != -1:
+        head = impl_md[:begin]
+    directives: list[str] = []
+    for raw in head.splitlines():
+        stripped = raw.strip()
+        if not stripped.startswith("%"):
+            continue
+        content = stripped[1:].strip()
+        first = content.split(None, 1)[0] if content else ""
+        if first in _DIRECTIVE_KEYWORDS:
+            directives.append(content)
+    return directives
+
+
+def normalize_algpseudocode(impl_md: str, *, algorithm_name: str | None = None) -> str:
+    """Rewrite a human-authored implementation excerpt into algo2code source.
+
+    Extracts the ``algorithmic`` block, canonicalises assignment arrows, and
+    prepends synthesised ``% algorithm``/``% backend`` directives (preserving
+    any the author already supplied). Never raises: a missing block yields an
+    empty algorithmic shell, which :func:`normalize` flags as a warning.
+    """
+    body = extract_algorithmic_block(impl_md)
+    if body is None:
+        body = ""
+    body = _ARROW_RE.sub("=", body)
+
+    existing = _collect_directives(impl_md)
+    # Match both "algorithm <name>" and a bare "algorithm" directive so a
+    # name-less author directive doesn't get a synthesised one appended too.
+    has_name = any(d == "algorithm" or d.startswith("algorithm ") for d in existing)
+    has_backend = any(d == "backend" or d.startswith("backend ") for d in existing)
+
+    lines: list[str] = []
+    if not has_name:
+        lines.append(
+            f"% algorithm {_sanitize_identifier(algorithm_name or 'algorithm')}"
+        )
+    if not has_backend:
+        lines.append("% backend taichi")
+    lines.extend(f"% {d}" for d in existing)
+    lines.append(r"\begin{algorithmic}")
+    if body:
+        lines.append(body)
+    lines.append(r"\end{algorithmic}")
+    return "\n".join(lines)
+
+
+def normalize(
+    impl_md: str, *, algorithm_name: str | None = None
+) -> NormalizationResult:
+    """Normalise an excerpt and report parse status + structured warnings.
+
+    Wraps :func:`normalize_algpseudocode` with a trial ``algo2code`` parse so
+    the adapter can attach warnings without ever crashing the packet.
+    """
+    found = extract_algorithmic_block(impl_md) is not None
+    normalized = normalize_algpseudocode(impl_md, algorithm_name=algorithm_name)
+
+    warnings: list[str] = []
+    if not found:
+        warnings.append(
+            r"no \begin{algorithmic} block found in implementation excerpt; "
+            "emitted source will be an empty function"
+        )
+
+    parses = False
+    try:
+        from algo2code import parse_algorithm
+
+        parse_algorithm(normalized)
+        parses = True
+    except Exception as exc:
+        warnings.append(f"algo2code parse failed: {type(exc).__name__}: {exc}")
+
+    return NormalizationResult(
+        normalized=normalized,
+        algorithmic_block_found=found,
+        parses=parses,
+        warnings=tuple(warnings),
+    )

compmech_reference_pack/paths.py

@@ -0,0 +1,30 @@
+"""Filesystem accessors for the promoted compmech domain pack.
+
+The domain pack and its source packs ship as package data under
+``compmech_reference_pack/domain_pack/``. These helpers return concrete
+``Path`` objects so the ``akms_learn`` descriptor loaders — and the
+`CEmM2/Logic-Loom <https://github.com/CEmM2/Logic-Loom>`_ status route — can
+read them without hardcoding the install layout.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["domain_pack_dir", "domain_pack_path", "source_pack_path"]
+
+
+def domain_pack_dir() -> Path:
+    """Absolute path to the packaged ``domain_pack/`` data directory."""
+    return Path(str(resources.files("compmech_reference_pack") / "domain_pack"))
+
+
+def domain_pack_path() -> Path:
+    """Absolute path to the promoted ``domain_pack.yaml``."""
+    return domain_pack_dir() / "domain_pack.yaml"
+
+
+def source_pack_path(name: str) -> Path:
+    """Absolute path to a source-pack yaml by stem (e.g. ``"mechdsl"``)."""
+    return domain_pack_dir() / "source_packs" / f"{name}.yaml"

compmech_reference_pack-0.3.1.dist-info/METADATA

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: compmech-reference-pack
+Version: 0.3.1
+Summary: Computational-mechanics companion adapter — bridges AKMS LSP excerpts to the MechDSL executable backend.
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: akms-learn
+Provides-Extra: mechdsl
+Requires-Dist: mechdsl-core; extra == "mechdsl"
+Requires-Dist: algo2code; extra == "mechdsl"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.2; extra == "dev"
+Requires-Dist: compmech-reference-pack[mechdsl]; extra == "dev"
+
+# compmech-reference-pack
+
+The computational-mechanics companion adapter for
+[AKMS](https://github.com/CEmM2/AKMS). It bridges `akms-learn` Learning Source
+Packet excerpts to the [MechDSL](https://github.com/CEmM2/MechDSL) executable
+backend, so an algorithm described in a knowledge node can be transpiled and
+compiled rather than only read.
+
+It ships the `compmech` domain pack — the descriptor and source packs that tell
+`akms-learn` which companions exist and what each can do.
+
+## Install
+
+```bash
+pip install compmech-reference-pack
+```
+
+That gives you the domain pack and the adapter's declared capability surface,
+and pulls in `akms-learn`. It does **not** pull in the MechDSL backend: every
+`mechdsl` and `algo2code` import in this package is function-scoped, so it
+installs and imports cleanly without them.
+
+To enable the actual compile, transpile and verify path:
+
+```bash
+pip install "compmech-reference-pack[mechdsl]"
+```
+
+The extra exists so a downstream consumer can depend on this package without
+dragging the executable backend — and transitively Taichi — into its
+resolution.
+
+## What it provides
+
+- **`MechDSLRunner`** — the `executable_bridge` adapter. Given an LSP excerpt
+  it normalises the algorithmic block, derives a safe algorithm name, and
+  delegates to MechDSL's `transpile_algorithm` / `compile_from_sources`.
+  Provenance is preserved from node to generated artefact.
+- **`capabilities()`** — a declaration of what the package offers, kept
+  deliberately import-light and Taichi-free so a caller can ask without paying
+  for a backend it may not use.
+- **The `compmech` domain pack** — `domain_pack.yaml` plus the source packs
+  under `domain_pack/source_packs/`, addressed through
+  `compmech_reference_pack.paths`.
+
+## Companion status
+
+| Companion | Role | Status |
+|---|---|---|
+| `mechdsl` | executable bridge | available |
+| `constkit` | concept kit | planned |
+| `symbolic_fem_workbench` | pedagogical workbench | planned |
+
+`planned` describes the adapter, not the source: the material for both planned
+companions is public, in
+[SOSOVSKI/Teaching-materials](https://github.com/SOSOVSKI/Teaching-materials).
+
+## Licence
+
+Apache-2.0, matching AKMS.

compmech_reference_pack-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+compmech_reference_pack/__init__.py,sha256=elyoLBFm-eP7OpO4rSDdGr8I85U-I3n3zeYbMDWzdVM,873
+compmech_reference_pack/capabilities.py,sha256=3M-VtSJ08J5DHMsdogVbvdXhjHGG5HackgZUPjsdF-M,2452
+compmech_reference_pack/normalize.py,sha256=ro8aXcVEdGjdT7nvUFdQuvOkOEqmsB2VSaaCaDNN1ew,7084
+compmech_reference_pack/paths.py,sha256=uQxVxnwgBxeSZOyIpP9NzvGqMYWNT2YIbowaz-PInac,1082
+compmech_reference_pack/adapters/__init__.py,sha256=H1MFitiM4TJm7X3JAu4LV3urONw6nP9h5xgeKfejdos,370
+compmech_reference_pack/adapters/mechdsl_runner.py,sha256=MaOKRGIgvtT8kmoqebQuj_kkXXq3aZYNisgmyEHohAk,12759
+compmech_reference_pack/domain_pack/domain_pack.yaml,sha256=1lFR1poc-BmbirLOZBa6MiIFhKIH_sKGUFOhCS6o4Ec,1630
+compmech_reference_pack/domain_pack/source_packs/constkit.yaml,sha256=MTC1nA1SVC63VSlvkRebHouUJ6BkRwJ5lEcgrJXSSyQ,774
+compmech_reference_pack/domain_pack/source_packs/mechdsl.yaml,sha256=iD-woiDkEyHo_5nWDF1a7nUt4c4RWOKRRF1N_HZWQgs,624
+compmech_reference_pack/domain_pack/source_packs/symbolic_fem_workbench.yaml,sha256=UNzr8L5tcXx17qIs1ayCdgRAnVZ7QChK2j-Rv3RM2X4,919
+compmech_reference_pack-0.3.1.dist-info/METADATA,sha256=P0FUlJqk4I0zt-U2FNs-Is1w3jkZDHhCsziEeXqO12E,2726
+compmech_reference_pack-0.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+compmech_reference_pack-0.3.1.dist-info/top_level.txt,sha256=riOWv2q4eOyjzwjlSg7oOsCT_jfRzISqSr8V3jECeyk,24
+compmech_reference_pack-0.3.1.dist-info/RECORD,,

compmech_reference_pack-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

compmech_reference_pack-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+compmech_reference_pack