pystdoc 0.2.0__tar.gz

pystdoc-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tab4moji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pystdoc-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: pystdoc
+Version: 0.2.0
+Summary: Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator.
+Author: tab4moji
+License: MIT
+Keywords: documentation,llm,ast,clang,architecture,topological,dag,pystdoc,mermaid
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: libclang>=16.0.0
+Dynamic: license-file
+
+# pystdoc: Python Structural & Topological Documentation Engine
+
+**pystdoc** (*Python Structural & Topological Documentation Engine*) is an enterprise-grade, high-precision codebase and architectural documentation generator powered by LLMs, AST parsing, and `libclang`.
+
+It analyzes codebases in **bottom-up + top-down topological passes**, constructs hierarchical execution/data models, and synthesizes clean, human-centric Markdown and Mermaid diagrams within a **16K context window**.
+
+---
+
+## 📁 Output Directory: `.docgen/`
+
+> [!IMPORTANT]
+> **All generated documentation, architecture designs, and caches are automatically centralized inside the `.docgen/` directory of your target project.**
+> Your existing source code files are never modified.
+
+When `pystdoc` finishes, you can explore the complete documentation suite starting from `.docgen/README.md`:
+
+```text
+your_project/
+├── .docgen/                          # <-- Centralized output directory
+│   ├── README.md                     # Executive summary: "What does this project actually do?"
+│   ├── design/                       # System architecture and design documentation
+│   │   ├── overview.md               # Architecture overview & inter-module Mermaid diagram
+│   │   ├── data_models.md            # Data structure design, models, lifecycle & integrity
+│   │   ├── execution_model.md        # Runtime execution model, paradigms, & control flow
+│   │   └── modules/                  # Module-by-module detailed design documents
+│   │       ├── module_a.md
+│   │       └── ...
+│   ├── documents/                    # Granular symbol & source code documentation
+│   │   ├── src/main.c.md             # File-level overview and symbol list
+│   │   ├── src/main.c.fn.main.md     # Individual symbol document (with call graph & context)
+│   │   └── ...
+│   ├── files.txt                     # List of scanned source files
+│   └── index.db                      # SQLite WAL database for instantaneous incremental caching
+├── src/
+└── ...
+```
+
+---
+
+## 🌟 Key Features
+
+1. **Topological & Structural Ordering (Tarjan SCC + Kahn DAG)**:
+   - Evaluates call graphs in $O(V+E)$ linear time.
+   - Automatically breaks cyclic mutual recursions and organizes code symbols into dependency-safe execution levels.
+   - Level-by-level parallel LLM execution guarantees context-rich bottom-up summaries without race conditions.
+2. **3-in-1 Unified Documentation Pipeline**:
+   - `docgen`: Bottom-up & top-down symbol-level documentation with SHA-256 and SQLite caching (`.docgen/documents/`).
+   - `designgen`: Map-Reduce architectural synthesis (`.docgen/design/`).
+   - `reportgen` / `pystdoc`: Executive summary README (`.docgen/README.md`) answering *"What does this project actually do?"*
+3. **C/C++, Python & Shell Deep Understanding**:
+   - **`compile_commands.json` Integration**: Full include path resolution and macro expansion via `libclang`.
+   - **Fully Qualified Domain Names (FQDN)**: Disambiguates identical symbol names across large monorepos.
+4. **Standard LLM Options & Multi-Language Support**:
+   - Works with **Ollama, LiteRT-LM, vLLM, and OpenAI API**.
+   - Supports `--host`, `--model`, `--token` / `--api-key`, `--context-size`, and `--language` (e.g. `English`, `Japanese`, `日本語`).
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+```bash
+pip install pystdoc
+```
+
+### Basic Usage
+
+#### 1. Generate Full Documentation & README (One Command)
+```bash
+pystdoc --dir ./my_project/
+```
+*Output will be created at `./my_project/.docgen/README.md`.*
+
+#### 2. Generate in Japanese
+```bash
+pystdoc --dir ./my_project/ --language 日本語
+```
+
+#### 3. Run Individual Steps
+```bash
+# Generate symbol-level docs into .docgen/documents/
+docgen --dir ./my_project/ -j 4
+
+# Synthesize architecture design docs into .docgen/design/
+designgen --dir ./my_project/
+```
+
+---
+
+## ⚙️ CLI Options
+
+| Option | Alias / Env | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir` | | `./` | Target project directory path |
+| `--language` | `-l` | `English` | Output documentation language (`English`, `Japanese`, `日本語`) |
+| `--host` | `-H`, `--base-url` | `http://127.0.0.1:11434` | LLM server host endpoint URL |
+| `--model` | `-m`, `LLM_MODEL` | `gemma4-26b-a4b` | LLM model identifier |
+| `--token` | `--api-key`, `OPENAI_API_KEY` | `None` | API Bearer token |
+| `--context-size` | `--ctx-size` | `16384` | Context window size |
+| `--concurrency` | `-j` | `4` | Number of parallel LLM workers |
+| `--force` | `-f` | `false` | Force regenerate all documents ignoring cache |
+| `--compile-commands` | | `None` | Path to `compile_commands.json` |
+
+---
+
+## 📄 License
+MIT License. Author: **tab4moji**.

pystdoc-0.2.0/README.md

@@ -0,0 +1,107 @@
+# pystdoc: Python Structural & Topological Documentation Engine
+
+**pystdoc** (*Python Structural & Topological Documentation Engine*) is an enterprise-grade, high-precision codebase and architectural documentation generator powered by LLMs, AST parsing, and `libclang`.
+
+It analyzes codebases in **bottom-up + top-down topological passes**, constructs hierarchical execution/data models, and synthesizes clean, human-centric Markdown and Mermaid diagrams within a **16K context window**.
+
+---
+
+## 📁 Output Directory: `.docgen/`
+
+> [!IMPORTANT]
+> **All generated documentation, architecture designs, and caches are automatically centralized inside the `.docgen/` directory of your target project.**
+> Your existing source code files are never modified.
+
+When `pystdoc` finishes, you can explore the complete documentation suite starting from `.docgen/README.md`:
+
+```text
+your_project/
+├── .docgen/                          # <-- Centralized output directory
+│   ├── README.md                     # Executive summary: "What does this project actually do?"
+│   ├── design/                       # System architecture and design documentation
+│   │   ├── overview.md               # Architecture overview & inter-module Mermaid diagram
+│   │   ├── data_models.md            # Data structure design, models, lifecycle & integrity
+│   │   ├── execution_model.md        # Runtime execution model, paradigms, & control flow
+│   │   └── modules/                  # Module-by-module detailed design documents
+│   │       ├── module_a.md
+│   │       └── ...
+│   ├── documents/                    # Granular symbol & source code documentation
+│   │   ├── src/main.c.md             # File-level overview and symbol list
+│   │   ├── src/main.c.fn.main.md     # Individual symbol document (with call graph & context)
+│   │   └── ...
+│   ├── files.txt                     # List of scanned source files
+│   └── index.db                      # SQLite WAL database for instantaneous incremental caching
+├── src/
+└── ...
+```
+
+---
+
+## 🌟 Key Features
+
+1. **Topological & Structural Ordering (Tarjan SCC + Kahn DAG)**:
+   - Evaluates call graphs in $O(V+E)$ linear time.
+   - Automatically breaks cyclic mutual recursions and organizes code symbols into dependency-safe execution levels.
+   - Level-by-level parallel LLM execution guarantees context-rich bottom-up summaries without race conditions.
+2. **3-in-1 Unified Documentation Pipeline**:
+   - `docgen`: Bottom-up & top-down symbol-level documentation with SHA-256 and SQLite caching (`.docgen/documents/`).
+   - `designgen`: Map-Reduce architectural synthesis (`.docgen/design/`).
+   - `reportgen` / `pystdoc`: Executive summary README (`.docgen/README.md`) answering *"What does this project actually do?"*
+3. **C/C++, Python & Shell Deep Understanding**:
+   - **`compile_commands.json` Integration**: Full include path resolution and macro expansion via `libclang`.
+   - **Fully Qualified Domain Names (FQDN)**: Disambiguates identical symbol names across large monorepos.
+4. **Standard LLM Options & Multi-Language Support**:
+   - Works with **Ollama, LiteRT-LM, vLLM, and OpenAI API**.
+   - Supports `--host`, `--model`, `--token` / `--api-key`, `--context-size`, and `--language` (e.g. `English`, `Japanese`, `日本語`).
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+```bash
+pip install pystdoc
+```
+
+### Basic Usage
+
+#### 1. Generate Full Documentation & README (One Command)
+```bash
+pystdoc --dir ./my_project/
+```
+*Output will be created at `./my_project/.docgen/README.md`.*
+
+#### 2. Generate in Japanese
+```bash
+pystdoc --dir ./my_project/ --language 日本語
+```
+
+#### 3. Run Individual Steps
+```bash
+# Generate symbol-level docs into .docgen/documents/
+docgen --dir ./my_project/ -j 4
+
+# Synthesize architecture design docs into .docgen/design/
+designgen --dir ./my_project/
+```
+
+---
+
+## ⚙️ CLI Options
+
+| Option | Alias / Env | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `--dir` | | `./` | Target project directory path |
+| `--language` | `-l` | `English` | Output documentation language (`English`, `Japanese`, `日本語`) |
+| `--host` | `-H`, `--base-url` | `http://127.0.0.1:11434` | LLM server host endpoint URL |
+| `--model` | `-m`, `LLM_MODEL` | `gemma4-26b-a4b` | LLM model identifier |
+| `--token` | `--api-key`, `OPENAI_API_KEY` | `None` | API Bearer token |
+| `--context-size` | `--ctx-size` | `16384` | Context window size |
+| `--concurrency` | `-j` | `4` | Number of parallel LLM workers |
+| `--force` | `-f` | `false` | Force regenerate all documents ignoring cache |
+| `--compile-commands` | | `None` | Path to `compile_commands.json` |
+
+---
+
+## 📄 License
+MIT License. Author: **tab4moji**.

pystdoc-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pystdoc"
+version = "0.2.0"
+description = "Python Structural & Topological Documentation Engine (pystdoc): High-precision, LLM-powered hierarchical codebase and architecture documentation generator."
+readme = "README.md"
+authors = [
+    { name = "tab4moji" }
+]
+license = { text = "MIT" }
+keywords = ["documentation", "llm", "ast", "clang", "architecture", "topological", "dag", "pystdoc", "mermaid"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Documentation",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "libclang>=16.0.0",
+]
+
+[project.scripts]
+pystdoc = "pystdoc.cli:reportgen_main"
+reportgen = "pystdoc.cli:reportgen_main"
+docgen = "pystdoc.cli:docgen_main"
+designgen = "pystdoc.cli:designgen_main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

pystdoc-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pystdoc-0.2.0/src/pystdoc/__init__.py

@@ -0,0 +1,3 @@
+"""pystdoc: Python Structural & Topological Documentation Engine."""
+
+__version__ = "0.2.0"

pystdoc-0.2.0/src/pystdoc/cache.py

@@ -0,0 +1,38 @@
+"""Cache storage and atomic write operations with immediate disk sync."""
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def write_flushed_text(file_path: Path, text: str) -> None:
+    """Write text to file with immediate directory creation, flush, and fsync."""
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(text)
+        f.flush()
+        os.fsync(f.fileno())
+
+
+def save_symbol_cache(target_dir: Path, unique_id: str, data: Dict[str, Any]) -> Path:
+    """Save symbol LLM analysis result to json cache file with immediate sync."""
+    safe_name = re.sub(r"[^\w\-.]", "_", unique_id)
+    cache_dir = target_dir / ".docgen" / "cache"
+    cache_file = cache_dir / f"{safe_name}.json"
+    content = json.dumps(data, ensure_ascii=False, indent=2)
+    write_flushed_text(cache_file, content)
+    return cache_file
+
+
+def load_symbol_cache(target_dir: Path, unique_id: str) -> Optional[Dict[str, Any]]:
+    """Load cached LLM analysis data for a symbol."""
+    safe_name = re.sub(r"[^\w\-.]", "_", unique_id)
+    cache_file = target_dir / ".docgen" / "cache" / f"{safe_name}.json"
+    if cache_file.exists():
+        try:
+            return json.loads(cache_file.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+    return None

pystdoc-0.2.0/src/pystdoc/call_graph.py

@@ -0,0 +1,277 @@
+"""Call graph construction, Tarjan SCC cycle condensation, FQDN matching, and Level-by-Level DAG parallel ordering."""
+
+import re
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+from pystdoc.symbols import Symbol, get_kind_prefix
+
+
+@dataclass
+class SymbolNode:
+    symbol: Symbol
+    rel_path: Path
+    full_path: Path
+    unique_id: str
+    fqdn: str = ""
+    direct_callee_ids: Set[str] = field(default_factory=set)
+    scc_group_ids: List[str] = field(default_factory=list)
+    dag_level: int = 0
+
+
+def flatten_symbols(
+    symbols: List[Symbol],
+    rel_path: Path,
+    full_path: Path,
+    prefix: str = "",
+) -> List[SymbolNode]:
+    """Recursively collect all symbols into a flat list of SymbolNodes with FQDN and kind prefixes."""
+    nodes: List[SymbolNode] = []
+    for sym in symbols:
+        k_prefix = get_kind_prefix(sym.kind)
+        raw_name = f"{prefix}{sym.name}" if prefix else sym.name
+        identifier = f"{k_prefix}.{raw_name}"
+        uid = f"{rel_path.as_posix()}::{identifier}"
+
+        fqdn = sym.fqdn or f"{rel_path.with_suffix('').as_posix().replace('/', '.')}.{raw_name}"
+
+        node = SymbolNode(
+            symbol=sym,
+            rel_path=rel_path,
+            full_path=full_path,
+            unique_id=uid,
+            fqdn=fqdn,
+            direct_callee_ids=set(),
+            scc_group_ids=[],
+            dag_level=0,
+        )
+        nodes.append(node)
+        if sym.children:
+            child_nodes = flatten_symbols(
+                sym.children,
+                rel_path,
+                full_path,
+                prefix=f"{raw_name}.",
+            )
+            nodes.extend(child_nodes)
+    return nodes
+
+
+def link_variables_to_functions(nodes: List[SymbolNode]) -> None:
+    """Detect which functions directly reference each variable using FQDN and scope matching."""
+    fn_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "fn"]
+    var_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "var"]
+
+    for v_node in var_nodes:
+        v_name = v_node.symbol.name
+        ref_funcs: Set[str] = set()
+
+        for f_node in fn_nodes:
+            if f_node.rel_path == v_node.rel_path:
+                if f_node.symbol.line_start <= v_node.symbol.line_start <= f_node.symbol.line_end:
+                    ref_funcs.add(f"`{f_node.symbol.name}` (`{f_node.rel_path.name}`)")
+                    continue
+
+            try:
+                code_lines = f_node.full_path.read_text(encoding="utf-8", errors="replace").splitlines()
+                start = max(0, f_node.symbol.line_start - 1)
+                end = min(len(code_lines), f_node.symbol.line_end)
+                func_code = "\n".join(code_lines[start:end])
+
+                if re.search(rf"\b{re.escape(v_name)}\b", func_code):
+                    ref_funcs.add(f"`{f_node.symbol.name}` (`{f_node.rel_path.name}`)")
+            except Exception:
+                pass
+
+        v_node.symbol.referencing_functions = sorted(list(ref_funcs))
+
+
+def tarjan_scc(node_ids: List[str], adj: Dict[str, Set[str]]) -> List[List[str]]:
+    """Tarjan's strongly connected components algorithm in O(V+E) time."""
+    index = 0
+    indices: Dict[str, int] = {}
+    lowlinks: Dict[str, int] = {}
+    on_stack: Set[str] = set()
+    stack: List[str] = []
+    sccs: List[List[str]] = []
+
+    def strongconnect(v: str) -> None:
+        nonlocal index
+        indices[v] = index
+        lowlinks[v] = index
+        index += 1
+        stack.append(v)
+        on_stack.add(v)
+
+        for w in adj.get(v, set()):
+            if w not in indices:
+                strongconnect(w)
+                lowlinks[v] = min(lowlinks[v], lowlinks[w])
+            elif w in on_stack:
+                lowlinks[v] = min(lowlinks[v], indices[w])
+
+        if lowlinks[v] == indices[v]:
+            scc: List[str] = []
+            while True:
+                w = stack.pop()
+                on_stack.remove(w)
+                scc.append(w)
+                if w == v:
+                    break
+            sccs.append(scc)
+
+    for node_id in node_ids:
+        if node_id not in indices:
+            strongconnect(node_id)
+
+    return sccs
+
+
+def order_symbols_by_levels(nodes: List[SymbolNode]) -> List[List[SymbolNode]]:
+    """Partition symbol nodes into strictly dependency-safe levels for parallel processing."""
+    id_to_node: Dict[str, SymbolNode] = {n.unique_id: n for n in nodes}
+    fqdn_to_node_ids: Dict[str, List[str]] = defaultdict(list)
+    short_name_to_ids: Dict[str, List[str]] = defaultdict(list)
+
+    for node in nodes:
+        short_name_to_ids[node.symbol.name].append(node.unique_id)
+        if node.fqdn:
+            fqdn_to_node_ids[node.fqdn].append(node.unique_id)
+        if "::" in node.unique_id:
+            sym_part = node.unique_id.split("::", 1)[1]
+            raw_without_prefix = sym_part.split(".", 1)[-1] if "." in sym_part else sym_part
+            short_name_to_ids[raw_without_prefix].append(node.unique_id)
+
+    caller_to_callees: Dict[str, Set[str]] = {n.unique_id: set() for n in nodes}
+
+    for node in nodes:
+        prefix_type = get_kind_prefix(node.symbol.kind)
+        if prefix_type == "fn":
+            for callee_name in node.symbol.callees:
+                matched_ids = fqdn_to_node_ids.get(callee_name, [])
+                if not matched_ids:
+                    matched_ids = short_name_to_ids.get(callee_name, [])
+
+                for target_id in matched_ids:
+                    if target_id != node.unique_id and get_kind_prefix(id_to_node[target_id].symbol.kind) == "fn":
+                        caller_to_callees[node.unique_id].add(target_id)
+                        node.direct_callee_ids.add(target_id)
+
+    base_types_and_vars = [n for n in nodes if get_kind_prefix(n.symbol.kind) in ("const", "type", "var")]
+    for n in base_types_and_vars:
+        n.dag_level = 0
+
+    fn_nodes = [n for n in nodes if get_kind_prefix(n.symbol.kind) == "fn"]
+    fn_ids = [n.unique_id for n in fn_nodes]
+
+    # Tarjan SCC
+    sccs = tarjan_scc(fn_ids, caller_to_callees)
+
+    node_to_scc_idx: Dict[str, int] = {}
+    for scc_idx, scc_members in enumerate(sccs):
+        for member_id in scc_members:
+            node_to_scc_idx[member_id] = scc_idx
+            if len(scc_members) > 1:
+                id_to_node[member_id].scc_group_ids = [m for m in scc_members if m != member_id]
+
+    # Condensation DAG construction
+    scc_callees: Dict[int, Set[int]] = defaultdict(set)
+    scc_callers: Dict[int, Set[int]] = defaultdict(set)
+
+    for caller_id, callee_ids in caller_to_callees.items():
+        if caller_id not in node_to_scc_idx:
+            continue
+        c_scc = node_to_scc_idx[caller_id]
+        for callee_id in callee_ids:
+            if callee_id not in node_to_scc_idx:
+                continue
+            target_scc = node_to_scc_idx[callee_id]
+            if target_scc != c_scc:
+                scc_callees[c_scc].add(target_scc)
+                scc_callers[target_scc].add(c_scc)
+
+    # Bottom-up topological ranking
+    scc_rank: Dict[int, int] = {}
+    queue = deque([i for i in range(len(sccs)) if len(scc_callees[i]) == 0])
+    for i in queue:
+        scc_rank[i] = 0
+
+    resolved_sccs = set(queue)
+    while queue:
+        curr_scc = queue.popleft()
+        for parent_scc in scc_callers[curr_scc]:
+            if scc_callees[parent_scc].issubset(resolved_sccs):
+                max_child_rank = max(scc_rank[c] for c in scc_callees[parent_scc])
+                scc_rank[parent_scc] = max_child_rank + 1
+                resolved_sccs.add(parent_scc)
+                queue.append(parent_scc)
+
+    for i in range(len(sccs)):
+        if i not in scc_rank:
+            scc_rank[i] = 0
+
+    # Assign DAG levels
+    level_groups: Dict[int, List[SymbolNode]] = defaultdict(list)
+    if base_types_and_vars:
+        level_groups[0].extend(base_types_and_vars)
+
+    for scc_idx, members in enumerate(sccs):
+        rank = scc_rank[scc_idx]
+        node_level = rank + (1 if base_types_and_vars else 0)
+        for member_id in members:
+            node = id_to_node[member_id]
+            node.dag_level = node_level
+            level_groups[node_level].append(node)
+
+    max_lvl = max(level_groups.keys()) if level_groups else 0
+    levels_list = [level_groups[i] for i in range(max_lvl + 1) if level_groups[i]]
+    return levels_list
+
+
+def order_symbols_bottom_up(nodes: List[SymbolNode]) -> List[SymbolNode]:
+    """Flattened bottom-up order."""
+    levels = order_symbols_by_levels(nodes)
+    flat: List[SymbolNode] = []
+    for lvl in levels:
+        flat.extend(lvl)
+    return flat
+
+
+def build_callee_context_summary(
+    node: SymbolNode,
+    resolved_symbols: Dict[str, SymbolNode],
+) -> str:
+    """Build summary text of called low-level functions and mutual recursion peers for LLM prompt."""
+    lines: List[str] = []
+
+    if node.scc_group_ids:
+        peer_names = []
+        for peer_id in node.scc_group_ids:
+            peer_node = resolved_symbols.get(peer_id)
+            if peer_node:
+                peer_names.append(f"`{peer_node.symbol.name}` ({peer_node.rel_path.name})")
+        if peer_names:
+            lines.append("[Mutual Recursion Group]:")
+            lines.append(f"- Note: This function operates in mutual recursion with {', '.join(peer_names)}.")
+            lines.append("")
+
+    if node.direct_callee_ids:
+        lines.append("[Direct Callees Summary]:")
+        for callee_id in sorted(node.direct_callee_ids):
+            callee_node = resolved_symbols.get(callee_id)
+            if callee_node:
+                sym = callee_node.symbol
+                purpose = sym.purpose or "Executes operation"
+                inputs = sym.inputs_note or ", ".join(f"{p.name}: {p.type_hint}" for p in sym.parameters) or "None"
+                outputs = sym.outputs_note or sym.return_type or "None"
+                lines.append(f"- Function `{sym.name}` (FQDN: `{sym.fqdn or sym.name}`, File: `{callee_node.rel_path.name}`):")
+                lines.append(f"  - Purpose: {purpose}")
+                lines.append(f"  - Inputs: {inputs}")
+                lines.append(f"  - Outputs: {outputs}")
+                if sym.overview:
+                    first_lines = sym.overview.strip().splitlines()[:2]
+                    lines.append(f"  - Summary: {' / '.join(l.strip() for l in first_lines)}")
+
+    return "\n".join(lines)