codemble 0.3.0__py3-none-any.whl

codemble/graph/layout.py

@@ -0,0 +1,132 @@
+"""Deterministic layout metadata for pure render consumers."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections import defaultdict
+from dataclasses import replace
+
+from codemble.adapters.base import Graph, Node, Region, RegionEdge
+
+_GOLDEN_ANGLE = math.pi * (3.0 - math.sqrt(5.0))
+_SYSTEM_RING_CAPACITY = 12
+
+
+def layout_graph(graph: Graph) -> Graph:
+    """Return ``graph`` with stable galaxy and system coordinates filled.
+
+    Coordinates depend only on stable identifiers and sorted membership. No
+    clock, process hash seed, or random source participates in the result.
+    """
+
+    grouped: dict[str, list[Node]] = defaultdict(list)
+    for node in graph.nodes:
+        grouped[node.region].append(node)
+
+    region_order = sorted(grouped, key=lambda region_id: (_digest(region_id), region_id))
+    regions: list[Region] = []
+    positioned_nodes: list[Node] = []
+    node_by_id = {node.id: node for node in graph.nodes}
+
+    for region_index, region_id in enumerate(region_order):
+        members = sorted(
+            grouped[region_id],
+            key=lambda node: (node.kind != "module", node.id),
+        )
+        region_angle = region_index * _GOLDEN_ANGLE + _fraction(region_id, "phase") * 0.18
+        region_radius = 42.0 + 54.0 * math.sqrt(region_index)
+        region_x = _rounded(math.cos(region_angle) * region_radius)
+        region_y = _rounded(((_fraction(region_id, "height") * 2.0) - 1.0) * 28.0)
+        region_z = _rounded(math.sin(region_angle) * region_radius)
+
+        module_nodes = [node for node in members if node.kind == "module"]
+        loc = sum(node.loc for node in module_nodes) or sum(node.loc for node in members)
+        regions.append(
+            Region(
+                id=region_id,
+                language=members[0].language,
+                loc=loc,
+                centrality=sum(node.centrality for node in members),
+                node_count=len(members),
+                understood=bool(members) and all(node.understood for node in members),
+                home=any(node.id == graph.selected_entrypoint for node in members),
+                x=region_x,
+                y=region_y,
+                z=region_z,
+            )
+        )
+
+        for member_index, node in enumerate(members):
+            if member_index == 0:
+                positioned_nodes.append(
+                    replace(node, system_x=0.0, system_y=0.0, system_z=0.0)
+                )
+                continue
+            orbit_index = member_index - 1
+            ring = orbit_index // _SYSTEM_RING_CAPACITY
+            slot = orbit_index % _SYSTEM_RING_CAPACITY
+            ring_members = min(
+                _SYSTEM_RING_CAPACITY,
+                max(1, len(members) - 1 - ring * _SYSTEM_RING_CAPACITY),
+            )
+            angle = (2.0 * math.pi * slot / ring_members) + _fraction(node.id, "orbit") * 0.08
+            radius = 34.0 + ring * 24.0
+            positioned_nodes.append(
+                replace(
+                    node,
+                    system_x=_rounded(math.cos(angle) * radius),
+                    system_y=_rounded(((_fraction(node.id, "depth") * 2.0) - 1.0) * 8.0),
+                    system_z=_rounded(math.sin(angle) * radius),
+                )
+            )
+
+    routes: dict[tuple[str, str], list[bool]] = defaultdict(list)
+    for edge in graph.edges:
+        if edge.kind != "import" or edge.external:
+            continue
+        src_node = node_by_id.get(edge.src)
+        dst_node = node_by_id.get(edge.dst)
+        if src_node is None or dst_node is None or src_node.region == dst_node.region:
+            continue
+        routes[(src_node.region, dst_node.region)].append(edge.certain)
+
+    region_edges = tuple(
+        RegionEdge(src=src, dst=dst, weight=len(certainties), certain=all(certainties))
+        for (src, dst), certainties in sorted(routes.items())
+    )
+    return replace(
+        graph,
+        nodes=tuple(sorted(positioned_nodes, key=lambda node: node.id)),
+        regions=tuple(sorted(regions, key=lambda region: region.id)),
+        region_edges=region_edges,
+    )
+
+
+def with_entrypoint(graph: Graph, node_id: str) -> Graph:
+    """Select one parser-ranked candidate as Home without changing layout."""
+
+    if node_id not in graph.entrypoint_candidates:
+        raise ValueError(f"entrypoint is not a parser-ranked candidate: {node_id}")
+    node_by_id = {node.id: node for node in graph.nodes}
+    selected = node_by_id[node_id]
+    regions = tuple(
+        replace(region, home=region.id == selected.region) for region in graph.regions
+    )
+    return replace(graph, selected_entrypoint=node_id, regions=regions)
+
+
+def _digest(value: str, salt: str = "") -> bytes:
+    return hashlib.sha256(f"{salt}:{value}".encode()).digest()
+
+
+def _fraction(value: str, salt: str) -> float:
+    integer = int.from_bytes(_digest(value, salt)[:8], "big")
+    return integer / float((1 << 64) - 1)
+
+
+def _rounded(value: float) -> float:
+    return round(value, 6)
+
+
+__all__ = ["layout_graph", "with_entrypoint"]

codemble/lens/__init__.py

@@ -0,0 +1,18 @@
+"""Language lens: parser-detected idiom annotations to teachable notes."""
+
+from codemble.adapters.base import ConceptAnnotation
+from codemble.lens.javascript_typescript import javascript_typescript_lens_notes
+from codemble.lens.python import python_lens_notes
+
+
+def lens_notes(language: str, annotations: list[ConceptAnnotation]) -> list[dict[str, object]]:
+    """Route proven annotations to the matching language lens."""
+
+    if language == "python":
+        return python_lens_notes(annotations)
+    if language in {"javascript", "typescript"}:
+        return javascript_typescript_lens_notes(language, annotations)
+    return []
+
+
+__all__ = ["lens_notes"]

codemble/lens/javascript_typescript.py

@@ -0,0 +1,82 @@
+"""Teachable JS/TS notes keyed only by tree-sitter concept evidence."""
+
+from __future__ import annotations
+
+from codemble.adapters.base import ConceptAnnotation
+
+_NOTES = {
+    "async-await": (
+        "Async / await",
+        "This syntax pauses the current async flow until the awaited value settles without blocking the JavaScript event loop.",
+    ),
+    "arrow-function": (
+        "Arrow function",
+        "This compact function form captures `this` from its surrounding scope instead of creating its own `this` binding.",
+    ),
+    "destructuring": (
+        "Destructuring",
+        "This pattern binds selected array positions or object properties directly to local names.",
+    ),
+    "optional-chaining": (
+        "Optional chaining",
+        "This chain stops and yields `undefined` when the value before `?.` is `null` or `undefined`.",
+    ),
+    "nullish-coalescing": (
+        "Nullish coalescing",
+        "This expression uses its right side only when the left side is `null` or `undefined`, preserving values such as `0` and an empty string.",
+    ),
+    "module-syntax": (
+        "Module syntax",
+        "This declaration makes a dependency or exported binding explicit in the source module graph.",
+    ),
+    "type-annotation": (
+        "Type annotation",
+        "TypeScript uses this annotation for static checking and editor tooling; the annotation itself does not become a runtime check.",
+    ),
+    "interface": (
+        "Interface",
+        "This TypeScript declaration names a structural type contract for checking and tooling without creating a runtime value.",
+    ),
+    "generic": (
+        "Generic",
+        "This type parameter preserves a relationship between types while letting callers supply a concrete type.",
+    ),
+    "jsx": (
+        "JSX",
+        "This syntax describes an element or component tree that the configured toolchain transforms into JavaScript.",
+    ),
+}
+
+
+def javascript_typescript_lens_notes(
+    language: str,
+    annotations: list[ConceptAnnotation],
+) -> list[dict[str, object]]:
+    """Attach deterministic teaching copy to matching JS/TS annotations."""
+
+    if language not in {"javascript", "typescript"}:
+        return []
+    notes: list[dict[str, object]] = []
+    for annotation in annotations:
+        if annotation.language != language:
+            continue
+        note = _NOTES.get(annotation.concept)
+        if note is None:
+            continue
+        title, explanation = note
+        notes.append(
+            {
+                "node_id": annotation.node_id,
+                "language": annotation.language,
+                "concept": annotation.concept,
+                "title": title,
+                "note": explanation,
+                "line": annotation.lineno,
+                "end_line": annotation.end_lineno,
+                "snippet": annotation.snippet,
+            }
+        )
+    return notes
+
+
+__all__ = ["javascript_typescript_lens_notes"]

codemble/lens/python.py

@@ -0,0 +1,71 @@
+"""Teachable Python notes keyed only by parser-detected concept IDs."""
+
+from __future__ import annotations
+
+from codemble.adapters.base import ConceptAnnotation
+
+_PYTHON_NOTES = {
+    "decorator": (
+        "Decorator",
+        "Python evaluates this decorator while defining the structure and binds the returned object to its name.",
+    ),
+    "comprehension": (
+        "Comprehension",
+        "This expression builds a collection through inline iteration and optional filtering.",
+    ),
+    "generator": (
+        "Generator",
+        "This construct produces values lazily instead of building the complete sequence at once.",
+    ),
+    "context-manager": (
+        "Context manager",
+        "The `with` protocol brackets this block with managed setup and cleanup behavior.",
+    ),
+    "async-await": (
+        "Async / await",
+        "This construct participates in Python's asynchronous protocol and may yield control while work is pending.",
+    ),
+    "dunder-method": (
+        "Dunder method",
+        "Python calls this specially named method through a language protocol such as length, comparison, or display.",
+    ),
+    "exception-handling": (
+        "Exception handling",
+        "This construct makes failure part of explicit control flow by catching, grouping, or raising an exception.",
+    ),
+    "type-hint": (
+        "Type hint",
+        "This annotation communicates an expected type to readers and tooling; Python does not enforce it by default.",
+    ),
+}
+
+
+def python_lens_notes(
+    annotations: list[ConceptAnnotation],
+) -> list[dict[str, object]]:
+    """Attach deterministic teaching copy to proven Python annotations."""
+
+    notes: list[dict[str, object]] = []
+    for annotation in annotations:
+        if annotation.language != "python":
+            continue
+        note = _PYTHON_NOTES.get(annotation.concept)
+        if note is None:
+            continue
+        title, explanation = note
+        notes.append(
+            {
+                "node_id": annotation.node_id,
+                "language": annotation.language,
+                "concept": annotation.concept,
+                "title": title,
+                "note": explanation,
+                "line": annotation.lineno,
+                "end_line": annotation.end_lineno,
+                "snippet": annotation.snippet,
+            }
+        )
+    return notes
+
+
+__all__ = ["python_lens_notes"]

codemble/llm/__init__.py

@@ -0,0 +1,6 @@
+"""Grounded narration: provider adapters, validation, and file-hash cache."""
+
+from codemble.llm.providers import AnthropicProvider, OpenAIProvider
+from codemble.llm.study import StudyService
+
+__all__ = ["AnthropicProvider", "OpenAIProvider", "StudyService"]

codemble/llm/providers.py

@@ -0,0 +1,137 @@
+"""Direct BYO-key narration adapters for the supported external providers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Callable, Protocol
+from urllib import error, request
+
+from codemble import __version__
+
+JsonObject = dict[str, object]
+PostJson = Callable[[str, dict[str, str], JsonObject], JsonObject]
+
+
+class ProviderError(RuntimeError):
+    """A provider request failed without exposing credentials or response bodies."""
+
+
+class NarrationProvider(Protocol):
+    """The transport seam used by the study module."""
+
+    name: str
+    model: str
+
+    def complete(self, prompt: str) -> str:
+        """Return the provider's text response for one grounded prompt."""
+
+
+@dataclass(slots=True)
+class AnthropicProvider:
+    """Anthropic Messages adapter using the user's key directly."""
+
+    api_key: str
+    model: str = "claude-sonnet-5"
+    post_json: PostJson = field(default_factory=lambda: _post_json, repr=False)
+    name: str = field(default="anthropic", init=False)
+
+    def complete(self, prompt: str) -> str:
+        payload = self.post_json(
+            "https://api.anthropic.com/v1/messages",
+            {
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+                "x-api-key": self.api_key,
+            },
+            {
+                "model": self.model,
+                "max_tokens": 1200,
+                "messages": [{"role": "user", "content": prompt}],
+            },
+        )
+        content = payload.get("content")
+        if not isinstance(content, list):
+            raise ProviderError("Anthropic returned no text content.")
+        text = "".join(
+            str(block.get("text", ""))
+            for block in content
+            if isinstance(block, dict) and block.get("type") == "text"
+        ).strip()
+        if not text:
+            raise ProviderError("Anthropic returned an empty text response.")
+        return text
+
+
+@dataclass(slots=True)
+class OpenAIProvider:
+    """OpenAI Responses adapter using the user's key directly."""
+
+    api_key: str
+    model: str = "gpt-5.4-mini"
+    post_json: PostJson = field(default_factory=lambda: _post_json, repr=False)
+    name: str = field(default="openai", init=False)
+
+    def complete(self, prompt: str) -> str:
+        payload = self.post_json(
+            "https://api.openai.com/v1/responses",
+            {
+                "authorization": f"Bearer {self.api_key}",
+                "content-type": "application/json",
+            },
+            {
+                "model": self.model,
+                "input": prompt,
+                "max_output_tokens": 1200,
+                "store": False,
+            },
+        )
+        output = payload.get("output")
+        if not isinstance(output, list):
+            raise ProviderError("OpenAI returned no output items.")
+        text_parts: list[str] = []
+        for item in output:
+            if not isinstance(item, dict) or item.get("type") != "message":
+                continue
+            content = item.get("content")
+            if not isinstance(content, list):
+                continue
+            text_parts.extend(
+                str(block.get("text", ""))
+                for block in content
+                if isinstance(block, dict) and block.get("type") == "output_text"
+            )
+        text = "".join(text_parts).strip()
+        if not text:
+            raise ProviderError("OpenAI returned an empty text response.")
+        return text
+
+
+def _post_json(url: str, headers: dict[str, str], payload: JsonObject) -> JsonObject:
+    encoded = json.dumps(payload).encode("utf-8")
+    outbound = request.Request(
+        url,
+        data=encoded,
+        headers={**headers, "user-agent": f"Codemble/{__version__}"},
+        method="POST",
+    )
+    try:
+        with request.urlopen(outbound, timeout=60) as response:  # noqa: S310 - fixed HTTPS URLs
+            decoded = json.loads(response.read().decode("utf-8"))
+    except error.HTTPError as provider_error:
+        raise ProviderError(
+            f"The provider rejected the request with HTTP {provider_error.code}."
+        ) from provider_error
+    except (error.URLError, TimeoutError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ProviderError("The provider request could not be completed safely.") from exc
+    if not isinstance(decoded, dict):
+        raise ProviderError("The provider returned an unexpected response shape.")
+    return decoded
+
+
+__all__ = [
+    "AnthropicProvider",
+    "NarrationProvider",
+    "OpenAIProvider",
+    "ProviderError",
+]