akms-learn 0.3.0__py3-none-any.whl

akms_learn/__init__.py

@@ -0,0 +1,155 @@
+"""akms_learn: Learning Source Packet compiler and exporters for AKMS."""
+
+from akms_learn.cli import main
+from akms_learn.compiler import (
+    STAGES,
+    CompileResult,
+    compile_learning_source,
+)
+from akms_learn.domain_packs import (
+    CapabilityStatus,
+    CompanionRole,
+    DomainPackDescriptor,
+    DomainPackRegistry,
+    DomainPackWarning,
+    LearningCapabilityError,
+    RuntimeHint,
+    SourcePackDescriptor,
+    build_registry_from_paths,
+    load_descriptor_from_yaml,
+    load_source_pack_from_yaml,
+    warn_planned_companion,
+)
+from akms_learn.exporters.bundle import MANIFEST_VERSION
+from akms_learn.exporters.bundle import export as bundle_export
+from akms_learn.exporters.markdown import export as markdown_export
+from akms_learn.graph_import import (
+    GraphSlice,
+    compute_graph_hash,
+    fixture_graph,
+    load_graph,
+)
+from akms_learn.modes.anthology import (
+    TEACHING_SECTIONS,
+    AnthologyEntry,
+    anthology_mode,
+)
+from akms_learn.modes.bundle_source import bundle_source_mode
+from akms_learn.modes.outline import outline_mode
+from akms_learn.modes.pitfall import (
+    PITFALL_EDGE_TYPES,
+    STRUCTURED_FIELDS,
+    pitfall_mode,
+)
+from akms_learn.models import (
+    AssessmentView,
+    CodeLinkView,
+    CompilerInfo,
+    LearningEdgeView,
+    LearningNodeView,
+    LearningRequestInfo,
+    LearningSourcePacket,
+    LearningWarning,
+    PacketBody,
+    PitfallView,
+    ReferenceView,
+    SourceInfo,
+)
+from akms_learn.ordering import LEARNING_BUCKETS, order_nodes
+from akms_learn.requests import (
+    LearningRequest,
+    normalize_request,
+    request_hash,
+    to_canonical_dict,
+)
+from akms_learn.section_extraction import (
+    APPROVED_HEADINGS,
+    EXCERPT_MAX_CHARS,
+    ExtractedSection,
+    ExtractionMethod,
+    extract_sections_from_node,
+    extract_sections_from_nodes,
+)
+from akms_learn.sections import APPROVED_SECTIONS, SectionView, extract_sections
+from akms_learn.validation import PacketValidationError, validate_packet
+from akms_learn.warnings import (
+    WarningAccumulator,
+    emit_dangling_reference_warning,
+    emit_missing_section_warning,
+)
+
+__all__ = [
+    # Compiler
+    "STAGES",
+    "CompileResult",
+    "compile_learning_source",
+    # Graph import
+    "GraphSlice",
+    "load_graph",
+    "compute_graph_hash",
+    "fixture_graph",
+    # Ordering
+    "LEARNING_BUCKETS",
+    "order_nodes",
+    # Sections
+    "APPROVED_SECTIONS",
+    "SectionView",
+    "extract_sections",
+    # Node-level section extraction
+    "APPROVED_HEADINGS",
+    "EXCERPT_MAX_CHARS",
+    "ExtractedSection",
+    "ExtractionMethod",
+    "extract_sections_from_node",
+    "extract_sections_from_nodes",
+    # LSP models
+    "LearningSourcePacket",
+    "CompilerInfo",
+    "SourceInfo",
+    "LearningRequestInfo",
+    "PacketBody",
+    "LearningNodeView",
+    "LearningEdgeView",
+    "PitfallView",
+    "CodeLinkView",
+    "AssessmentView",
+    "ReferenceView",
+    "LearningWarning",
+    "LearningRequest",
+    "normalize_request",
+    "request_hash",
+    "to_canonical_dict",
+    "WarningAccumulator",
+    "emit_missing_section_warning",
+    "emit_dangling_reference_warning",
+    "PacketValidationError",
+    "validate_packet",
+    # Domain-pack foundation
+    "CapabilityStatus",
+    "CompanionRole",
+    "DomainPackDescriptor",
+    "DomainPackRegistry",
+    "DomainPackWarning",
+    "LearningCapabilityError",
+    "RuntimeHint",
+    "SourcePackDescriptor",
+    "build_registry_from_paths",
+    "load_descriptor_from_yaml",
+    "load_source_pack_from_yaml",
+    "warn_planned_companion",
+    # Exporters
+    "markdown_export",
+    "bundle_export",
+    "MANIFEST_VERSION",
+    # Structured modes
+    "outline_mode",
+    "anthology_mode",
+    "AnthologyEntry",
+    "TEACHING_SECTIONS",
+    "pitfall_mode",
+    "PITFALL_EDGE_TYPES",
+    "STRUCTURED_FIELDS",
+    "bundle_source_mode",
+    # CLI
+    "main",
+]

akms_learn/_code_links.py

@@ -0,0 +1,154 @@
+"""Shared helpers for code-link extraction.
+
+Promoted from ``compiler.py`` and ``modes/implementation_first.py`` to
+remove duplication. Lives at the package
+top level so both the compiler stage and the ``implementation_first`` mode
+can call into the same authoritative implementation.
+
+Surface
+-------
+* :data:`MISSING_SOURCE_PATH_SENTINELS` — frozenset of placeholder strings
+  that count as "no usable source path" (``"", "unknown", "none", "null"``).
+* :func:`is_missing_source_path` — predicate over a raw ``source_path``
+  value; case-insensitive, whitespace-tolerant, None-safe.
+* :func:`coerce_line_range` — best-effort coercion of a node/edge
+  ``line_range`` value into a ``(start, end)`` integer tuple.
+* :func:`build_code_links` — walks ``implements`` edges and emits one
+  :class:`CodeLinkView` per edge. Optionally invokes a missing-source
+  callback so the compiler can emit ``code_mirror_missing_source_path``
+  warnings while the mode keeps its own simpler warning path.
+
+Callers
+-------
+* ``compiler._build_code_links`` thin-wraps :func:`build_code_links`
+  passing the WarningAccumulator-driven callback.
+* ``implementation_first._build_code_references`` uses the no-callback
+  form; it emits ``implementation_anchor_missing_source`` separately
+  via :func:`implementation_first._emit_anchor_missing_source_warnings`.
+
+The module has no LLM imports.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from akms_learn.models import CodeLinkView
+
+__all__ = [
+    "MISSING_SOURCE_PATH_SENTINELS",
+    "is_missing_source_path",
+    "coerce_line_range",
+    "build_code_links",
+]
+
+
+MISSING_SOURCE_PATH_SENTINELS: frozenset[str] = frozenset(
+    {"", "unknown", "none", "null"}
+)
+
+
+def is_missing_source_path(value: Any) -> bool:
+    """Return True if *value* is an unusable placeholder source path.
+
+    Treats ``None``, empty string, and the canonical sentinels
+    (``"unknown"`` / ``"none"`` / ``"null"``) as missing. Comparison is
+    case-insensitive after stripping whitespace.
+    """
+    if value is None:
+        return True
+    text = str(value).strip().lower()
+    return text in MISSING_SOURCE_PATH_SENTINELS
+
+
+def coerce_line_range(value: Any) -> tuple[int, int]:
+    """Best-effort coercion of a node/edge ``line_range`` to ``(start, end)``.
+
+    Returns ``(0, 0)`` for any malformed input (non-list, wrong length,
+    non-integer elements). The placeholder pair is recognised by callers
+    that want to skip uninformative line ranges.
+    """
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        try:
+            return (int(value[0]), int(value[1]))
+        except (TypeError, ValueError):
+            pass
+    return (0, 0)
+
+
+def build_code_links(
+    edges: tuple[dict[str, Any], ...] | list[dict[str, Any]],
+    nodes_by_id: dict[str, dict[str, Any]],
+    on_missing_mirror_source: Optional[Callable[[str, str], None]] = None,
+) -> list[CodeLinkView]:
+    """Walk ``implements`` edges and emit one :class:`CodeLinkView` per edge.
+
+    Behaviour:
+
+    * One :class:`CodeLinkView` per edge with ``type == "implements"``.
+    * ``source_node_id`` is the edge's ``from`` endpoint.
+    * ``target`` resolves to the target node id (always set when present).
+    * ``relation`` is fixed to ``"implements"``.
+    * ``file_path`` and ``line_range`` come from the target node when the
+      target has a usable ``source_path``; otherwise the fields stay
+      ``None``.
+    * When *on_missing_mirror_source* is supplied AND the target node is a
+      ``code_mirror`` with a missing/sentinel ``source_path``, the callback
+      is invoked once per such edge with ``(mirror_node_id, edge_id)``.
+      The mode-level caller (``implementation_first``) passes ``None`` so
+      it can emit its own ``implementation_anchor_missing_source`` warning
+      via a separate code path.
+
+    The collector is order-stable: edges are processed in the order they
+    arrive in (assumed already sorted by the caller) and the returned list
+    preserves that order.
+    """
+    code_links: list[CodeLinkView] = []
+    for edge in edges:
+        if edge.get("type") != "implements":
+            continue
+
+        source_id = str(edge.get("from") or "")
+        target_id = str(edge.get("to") or "")
+        edge_id = str(edge.get("edge_id") or "")
+
+        target_node = nodes_by_id.get(target_id) or {}
+        target_source_path = target_node.get("source_path")
+        line_range_raw = target_node.get("line_range")
+
+        usable_path: Optional[str] = (
+            None
+            if is_missing_source_path(target_source_path)
+            else str(target_source_path)
+        )
+        usable_line_range: Optional[tuple[int, int]] = None
+        if usable_path is not None and line_range_raw is not None:
+            coerced = coerce_line_range(line_range_raw)
+            if coerced != (0, 0):
+                usable_line_range = coerced
+
+        target_value = target_id or (usable_path or "")
+
+        code_links.append(
+            CodeLinkView(
+                node_id=source_id or target_id or edge_id,
+                source_file=usable_path or "unknown",
+                source_node_id=source_id or None,
+                target=target_value or None,
+                relation="implements",
+                file_path=usable_path,
+                line_range=usable_line_range,
+                mirror_node_id=(
+                    target_id if target_node.get("kind") == "code_mirror" else None
+                ),
+            )
+        )
+
+        if (
+            on_missing_mirror_source is not None
+            and target_node.get("kind") == "code_mirror"
+            and is_missing_source_path(target_source_path)
+        ):
+            on_missing_mirror_source(target_id, edge_id)
+
+    return code_links

akms_learn/adapters/__init__.py

@@ -0,0 +1,38 @@
+"""Adapter protocols package for akms-learn.
+
+This package defines pure-Python protocol surfaces for four advanced-companion
+adapters.  No real adapter implementations ship here; all concrete
+implementations are provided by downstream packages.
+
+No-mutation invariant
+---------------------
+Adapters in this package MUST NOT:
+- Write to the AKMS global vault or any AKMS-owned path.
+- Mutate any AKMS graph object passed to them.
+- Write files via any file-write API targeting AKMS-owned paths.
+
+Public surface
+--------------
+``protocols``   — the four runtime_checkable Protocol classes.
+``status``      — AdapterStatus enum + adapter_registry() accessor.
+``fake_adapter``— Fake implementations for use in tests ONLY.
+"""
+
+from akms_learn.adapters.protocols import (
+    ConceptKitAdapter,
+    ExecutableBridgeAdapter,
+    NotebookExecutionAdapter,
+    PedagogicalWorkbenchAdapter,
+)
+from akms_learn.adapters.status import AdapterStatus, adapter_registry
+
+__all__ = [
+    # Protocols
+    "ConceptKitAdapter",
+    "ExecutableBridgeAdapter",
+    "NotebookExecutionAdapter",
+    "PedagogicalWorkbenchAdapter",
+    # Status
+    "AdapterStatus",
+    "adapter_registry",
+]

akms_learn/adapters/fake_adapter.py

@@ -0,0 +1,172 @@
+"""Fake adapter implementations for tests ONLY.
+
+WARNING: These classes are for use in tests ONLY.  They are intentionally
+trivial; they return hard-coded stub payloads and do NOT perform any real
+computation.  Never import fake_adapter in production code.
+
+No-mutation invariant
+---------------------
+Fake adapters MUST NOT write to any AKMS path.  All output is returned in
+memory as plain Python dicts.
+
+Protocol conformance
+--------------------
+Each class satisfies its corresponding Protocol via structural subtyping.
+Because the Protocols are ``@runtime_checkable``, the isinstance checks::
+
+    isinstance(FakeConceptKit(), ConceptKitAdapter)
+    isinstance(FakePedagogicalWorkbench(), PedagogicalWorkbenchAdapter)
+    isinstance(FakeExecutableBridge(), ExecutableBridgeAdapter)
+    isinstance(FakeNotebookExecution(), NotebookExecutionAdapter)
+
+all return True.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from akms_learn.adapters.protocols import (
+    ConceptKitAdapter,
+    ExecutableBridgeAdapter,
+    NotebookExecutionAdapter,
+    PedagogicalWorkbenchAdapter,
+)
+
+__all__ = [
+    "FakeConceptKit",
+    "FakeExecutableBridge",
+    "FakeNotebookExecution",
+    "FakePedagogicalWorkbench",
+]
+
+
+class FakeConceptKit:
+    """Fake ConceptKitAdapter — returns a deterministic stub payload.
+
+    Satisfies :class:`~akms_learn.adapters.protocols.ConceptKitAdapter`
+    structurally (and via ``isinstance`` due to ``@runtime_checkable``).
+    """
+
+    def generate_concept_kit(
+        self,
+        excerpt: dict[str, Any],
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Return a deterministic stub concept-kit payload."""
+        return {
+            "adapter": "FakeConceptKit",
+            "status": "ok",
+            "concepts": ["stub_concept_A", "stub_concept_B"],
+            "excerpt_keys": sorted(excerpt.keys()),
+            "options_received": options is not None,
+        }
+
+
+class FakePedagogicalWorkbench:
+    """Fake PedagogicalWorkbenchAdapter — returns a deterministic stub payload.
+
+    Satisfies :class:`~akms_learn.adapters.protocols.PedagogicalWorkbenchAdapter`
+    structurally (and via ``isinstance`` due to ``@runtime_checkable``).
+    """
+
+    def analyse_pedagogy(
+        self,
+        excerpt: dict[str, Any],
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Return a deterministic stub pedagogical analysis payload."""
+        return {
+            "adapter": "FakePedagogicalWorkbench",
+            "status": "ok",
+            "objectives": ["stub_objective_1"],
+            "difficulty": "intermediate",
+            "excerpt_keys": sorted(excerpt.keys()),
+            "options_received": options is not None,
+        }
+
+
+class FakeExecutableBridge:
+    """Fake ExecutableBridgeAdapter — returns a deterministic stub payload.
+
+    Satisfies :class:`~akms_learn.adapters.protocols.ExecutableBridgeAdapter`
+    structurally (and via ``isinstance`` due to ``@runtime_checkable``).
+    """
+
+    def build_executable(
+        self,
+        excerpt: dict[str, Any],
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Return a deterministic stub executable-artefact payload."""
+        return {
+            "adapter": "FakeExecutableBridge",
+            "status": "ok",
+            "executable_type": "stub",
+            "source": "# stub source",
+            "excerpt_keys": sorted(excerpt.keys()),
+            "options_received": options is not None,
+        }
+
+
+class FakeNotebookExecution:
+    """Fake NotebookExecutionAdapter — returns a deterministic stub payload.
+
+    Satisfies :class:`~akms_learn.adapters.protocols.NotebookExecutionAdapter`
+    structurally (and via ``isinstance`` due to ``@runtime_checkable``).
+
+    The stub cells include all three notebook-metadata keys described in the
+    ``NotebookExecutionAdapter`` docstring (``no_execute``,
+    ``illustrative_only``, ``adapter_executable``) so that downstream
+    notebook-exporter tests can rely on them.
+    """
+
+    def build_notebook(
+        self,
+        excerpt: dict[str, Any],
+        *,
+        options: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Return a deterministic stub notebook payload."""
+        stub_cell = {
+            "cell_type": "code",
+            "source": "# stub cell",
+            "metadata": {
+                "no_execute": False,
+                "illustrative_only": True,
+                "adapter_executable": False,
+            },
+            "outputs": [],
+        }
+        return {
+            "adapter": "FakeNotebookExecution",
+            "status": "ok",
+            "nbformat": 4,
+            "nbformat_minor": 5,
+            "cells": [stub_cell],
+            "excerpt_keys": sorted(excerpt.keys()),
+            "options_received": options is not None,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Runtime isinstance-compatibility assertions (module-level, evaluated once).
+# ---------------------------------------------------------------------------
+# These raise AssertionError at import time if the structural subtyping is
+# accidentally broken, making test failures loud and immediate.
+
+assert isinstance(FakeConceptKit(), ConceptKitAdapter), (
+    "FakeConceptKit must satisfy ConceptKitAdapter protocol"
+)
+assert isinstance(FakePedagogicalWorkbench(), PedagogicalWorkbenchAdapter), (
+    "FakePedagogicalWorkbench must satisfy PedagogicalWorkbenchAdapter protocol"
+)
+assert isinstance(FakeExecutableBridge(), ExecutableBridgeAdapter), (
+    "FakeExecutableBridge must satisfy ExecutableBridgeAdapter protocol"
+)
+assert isinstance(FakeNotebookExecution(), NotebookExecutionAdapter), (
+    "FakeNotebookExecution must satisfy NotebookExecutionAdapter protocol"
+)