okstra 0.130.3 → 0.131.0

package/runtime/python/okstra_vendor/graphify/transcribe.py

@@ -1,182 +0,0 @@
-# Video transcription using faster-whisper
-# Converts video/audio files to text transcripts for graph extraction
-from __future__ import annotations
-
-import os
-from pathlib import Path
-
-
-VIDEO_EXTENSIONS = {'.mp4', '.mov', '.webm', '.mkv', '.avi', '.m4v', '.mp3', '.wav', '.m4a', '.ogg'}
-URL_PREFIXES = ('http://', 'https://', 'www.')
-
-_DEFAULT_MODEL = "base"
-_TRANSCRIPTS_DIR = "graphify-out/transcripts"
-_FALLBACK_PROMPT = "Use proper punctuation and paragraph breaks."
-
-
-def _model_name() -> str:
-    return os.environ.get("GRAPHIFY_WHISPER_MODEL", _DEFAULT_MODEL)
-
-
-def _get_whisper():
-    try:
-        from faster_whisper import WhisperModel
-        return WhisperModel
-    except ImportError as exc:
-        raise ImportError(
-            "Video transcription requires faster-whisper. "
-            "Run: pip install 'graphifyy[video]'"
-        ) from exc
-
-
-def _get_yt_dlp():
-    try:
-        import yt_dlp
-        return yt_dlp
-    except ImportError as exc:
-        raise ImportError(
-            "YouTube/URL download requires yt-dlp. "
-            "Run: pip install 'graphifyy[video]'"
-        ) from exc
-
-
-def is_url(path: str) -> bool:
-    """Return True if the string looks like a URL rather than a file path."""
-    return any(path.startswith(p) for p in URL_PREFIXES)
-
-
-def download_audio(url: str, output_dir: Path) -> Path:
-    """Download audio-only stream from a URL using yt-dlp.
-
-    Returns the path to the downloaded audio file (.m4a or .opus).
-    Uses cached file if already downloaded.
-    """
-    yt_dlp = _get_yt_dlp()
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    # yt-dlp uses %(title)s which can be long/weird — use a stable name based on URL hash
-    import hashlib
-    url_hash = hashlib.sha1(url.encode()).hexdigest()[:12]
-    out_template = str(output_dir / f"yt_{url_hash}.%(ext)s")
-
-    # Check for already-downloaded file
-    for ext in ('.m4a', '.opus', '.mp3', '.ogg', '.wav', '.webm'):
-        candidate = output_dir / f"yt_{url_hash}{ext}"
-        if candidate.exists():
-            print(f"  cached audio: {candidate.name}")
-            return candidate
-
-    ydl_opts = {
-        'format': 'bestaudio[ext=m4a]/bestaudio/best',
-        'outtmpl': out_template,
-        'quiet': True,
-        'no_warnings': True,
-        'noplaylist': True,
-        'postprocessors': [],  # no ffmpeg needed — use native audio
-    }
-
-    print(f"  downloading audio: {url[:80]} ...", flush=True)
-    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
-        info = ydl.extract_info(url, download=True)
-        ext = info.get('ext', 'm4a')
-        downloaded = output_dir / f"yt_{url_hash}.{ext}"
-        if not downloaded.exists():
-            # yt-dlp may have picked a different extension
-            for p in output_dir.glob(f"yt_{url_hash}.*"):
-                downloaded = p
-                break
-        return downloaded
-
-
-def build_whisper_prompt(god_nodes: list[dict]) -> str:
-    """Build a domain hint for Whisper from god nodes extracted from the corpus.
-
-    Formats the top god node labels into a topic string for Whisper.
-    The coding agent (Claude Code, Codex, etc.) generates the actual one-sentence
-    domain hint from these labels and passes it via GRAPHIFY_WHISPER_PROMPT or
-    as initial_prompt — no separate API call needed here.
-    """
-    if not god_nodes:
-        return _FALLBACK_PROMPT
-
-    override = os.environ.get("GRAPHIFY_WHISPER_PROMPT")
-    if override:
-        return override
-
-    labels = [n.get("label", "") for n in god_nodes[:10] if n.get("label")]
-    if not labels:
-        return _FALLBACK_PROMPT
-
-    topics = ", ".join(labels[:5])
-    return f"Technical discussion about {topics}. Use proper punctuation and paragraph breaks."
-
-
-def transcribe(
-    video_path: Path | str,
-    output_dir: Path | None = None,
-    initial_prompt: str | None = None,
-    force: bool = False,
-) -> Path:
-    """Transcribe a video/audio file or URL to a .txt transcript.
-
-    If video_path is a URL, audio is downloaded first via yt-dlp.
-    Returns the path to the saved transcript file.
-    Uses cached transcript if it exists unless force=True.
-
-    initial_prompt: domain hint for Whisper (built from corpus god nodes).
-    force: re-transcribe even if transcript already exists.
-    """
-    out_dir = Path(output_dir) if output_dir else Path(_TRANSCRIPTS_DIR)
-    out_dir.mkdir(parents=True, exist_ok=True)
-
-    if is_url(str(video_path)):
-        audio_path = download_audio(str(video_path), out_dir / "downloads")
-    else:
-        audio_path = Path(video_path)
-
-    transcript_path = out_dir / (audio_path.stem + ".txt")
-    if transcript_path.exists() and not force:
-        return transcript_path
-
-    WhisperModel = _get_whisper()
-    model_name = _model_name()
-    prompt = initial_prompt or _FALLBACK_PROMPT
-
-    print(f"  transcribing {audio_path.name} (model={model_name}) ...", flush=True)
-    model = WhisperModel(model_name, device="cpu", compute_type="int8")
-    segments, info = model.transcribe(
-        str(audio_path),
-        beam_size=5,
-        initial_prompt=prompt,
-    )
-
-    lines = [segment.text.strip() for segment in segments if segment.text.strip()]
-    transcript = "\n".join(lines)
-
-    transcript_path.write_text(transcript, encoding="utf-8")
-    lang = info.language if hasattr(info, "language") else "unknown"
-    print(f"  transcript saved -> {transcript_path} (lang={lang}, {len(lines)} segments)")
-    return transcript_path
-
-
-def transcribe_all(
-    video_files: list[str],
-    output_dir: Path | None = None,
-    initial_prompt: str | None = None,
-) -> list[str]:
-    """Transcribe a list of video/audio files or URLs, return paths to transcript .txt files.
-
-    Already-transcribed files are returned from cache instantly.
-    initial_prompt is shared across all files — built once from corpus god nodes.
-    """
-    if not video_files:
-        return []
-
-    transcript_paths = []
-    for vf in video_files:
-        try:
-            t = transcribe(vf, output_dir, initial_prompt=initial_prompt)
-            transcript_paths.append(str(t))
-        except Exception as exc:
-            print(f"  warning: could not transcribe {vf}: {exc}")
-    return transcript_paths

package/runtime/python/okstra_vendor/graphify/validate.py

@@ -1,72 +0,0 @@
-# validate extraction JSON against the graphify schema before graph assembly
-from __future__ import annotations
-
-VALID_FILE_TYPES = {"code", "document", "paper", "image", "rationale"}
-VALID_CONFIDENCES = {"EXTRACTED", "INFERRED", "AMBIGUOUS"}
-REQUIRED_NODE_FIELDS = {"id", "label", "file_type", "source_file"}
-REQUIRED_EDGE_FIELDS = {"source", "target", "relation", "confidence", "source_file"}
-
-
-def validate_extraction(data: dict) -> list[str]:
-    """
-    Validate an extraction JSON dict against the graphify schema.
-    Returns a list of error strings - empty list means valid.
-    """
-    if not isinstance(data, dict):
-        return ["Extraction must be a JSON object"]
-
-    errors: list[str] = []
-
-    # Nodes
-    if "nodes" not in data:
-        errors.append("Missing required key 'nodes'")
-    elif not isinstance(data["nodes"], list):
-        errors.append("'nodes' must be a list")
-    else:
-        for i, node in enumerate(data["nodes"]):
-            if not isinstance(node, dict):
-                errors.append(f"Node {i} must be an object")
-                continue
-            for field in REQUIRED_NODE_FIELDS:
-                if field not in node:
-                    errors.append(f"Node {i} (id={node.get('id', '?')!r}) missing required field '{field}'")
-            if "file_type" in node and node["file_type"] not in VALID_FILE_TYPES:
-                errors.append(
-                    f"Node {i} (id={node.get('id', '?')!r}) has invalid file_type "
-                    f"'{node['file_type']}' - must be one of {sorted(VALID_FILE_TYPES)}"
-                )
-
-    # Edges - accept "links" (NetworkX <= 3.1) as fallback for "edges"
-    edge_list = data.get("edges") if "edges" in data else data.get("links")
-    if edge_list is None:
-        errors.append("Missing required key 'edges'")
-    elif not isinstance(edge_list, list):
-        errors.append("'edges' must be a list")
-    else:
-        node_ids = {n["id"] for n in data.get("nodes", []) if isinstance(n, dict) and "id" in n}
-        for i, edge in enumerate(edge_list):
-            if not isinstance(edge, dict):
-                errors.append(f"Edge {i} must be an object")
-                continue
-            for field in REQUIRED_EDGE_FIELDS:
-                if field not in edge:
-                    errors.append(f"Edge {i} missing required field '{field}'")
-            if "confidence" in edge and edge["confidence"] not in VALID_CONFIDENCES:
-                errors.append(
-                    f"Edge {i} has invalid confidence '{edge['confidence']}' "
-                    f"- must be one of {sorted(VALID_CONFIDENCES)}"
-                )
-            if "source" in edge and node_ids and edge["source"] not in node_ids:
-                errors.append(f"Edge {i} source '{edge['source']}' does not match any node id")
-            if "target" in edge and node_ids and edge["target"] not in node_ids:
-                errors.append(f"Edge {i} target '{edge['target']}' does not match any node id")
-
-    return errors
-
-
-def assert_valid(data: dict) -> None:
-    """Raise ValueError with all errors if extraction is invalid."""
-    errors = validate_extraction(data)
-    if errors:
-        msg = f"Extraction JSON has {len(errors)} error(s):\n" + "\n".join(f"  • {e}" for e in errors)
-        raise ValueError(msg)

package/runtime/python/okstra_vendor/graphify/watch.py

@@ -1,188 +0,0 @@
-# monitor a folder and auto-trigger --update when files change
-from __future__ import annotations
-import json
-import sys
-import time
-from pathlib import Path
-
-
-from graphify.detect import CODE_EXTENSIONS, DOC_EXTENSIONS, PAPER_EXTENSIONS, IMAGE_EXTENSIONS
-
-_WATCHED_EXTENSIONS = CODE_EXTENSIONS | DOC_EXTENSIONS | PAPER_EXTENSIONS | IMAGE_EXTENSIONS
-_CODE_EXTENSIONS = CODE_EXTENSIONS
-
-
-def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False) -> bool:
-    """Re-run AST extraction + build + cluster + report for code files. No LLM needed.
-
-    Returns True on success, False on error.
-    """
-    watch_path = watch_path.resolve()
-    try:
-        from graphify.extract import extract
-        from graphify.detect import detect
-        from graphify.build import build_from_json
-        from graphify.cluster import cluster, score_all
-        from graphify.analyze import god_nodes, surprising_connections, suggest_questions
-        from graphify.report import generate
-        from graphify.export import to_json, to_html
-
-        detected = detect(watch_path, follow_symlinks=follow_symlinks)
-        code_files = [Path(f) for f in detected['files']['code']]
-
-        if not code_files:
-            print("[graphify watch] No code files found - nothing to rebuild.")
-            return False
-
-        result = extract(code_files, cache_root=watch_path)
-
-        # Preserve semantic nodes/edges from a previous full run.
-        # AST-only rebuild replaces code nodes; doc/paper/image nodes are kept.
-        out = watch_path / "graphify-out"
-        existing_graph = out / "graph.json"
-        if existing_graph.exists():
-            try:
-                existing = json.loads(existing_graph.read_text(encoding="utf-8"))
-                code_ids = {n["id"] for n in existing.get("nodes", []) if n.get("file_type") == "code"}
-                sem_nodes = [n for n in existing.get("nodes", []) if n.get("file_type") != "code"]
-                sem_edges = [e for e in existing.get("links", existing.get("edges", []))
-                             if e.get("confidence") in ("INFERRED", "AMBIGUOUS")
-                             or (e.get("source") not in code_ids and e.get("target") not in code_ids)]
-                result = {
-                    "nodes": result["nodes"] + sem_nodes,
-                    "edges": result["edges"] + sem_edges,
-                    "hyperedges": existing.get("hyperedges", []),
-                    "input_tokens": 0,
-                    "output_tokens": 0,
-                }
-            except Exception:
-                pass  # corrupt graph.json - proceed with AST-only
-
-        detection = {
-            "files": {"code": [str(f) for f in code_files], "document": [], "paper": [], "image": []},
-            "total_files": len(code_files),
-            "total_words": detected.get("total_words", 0),
-        }
-
-        G = build_from_json(result)
-        communities = cluster(G)
-        cohesion = score_all(G, communities)
-        gods = god_nodes(G)
-        surprises = surprising_connections(G, communities)
-        labels = {cid: "Community " + str(cid) for cid in communities}
-        questions = suggest_questions(G, communities, labels)
-
-        out.mkdir(exist_ok=True)
-
-        report = generate(G, communities, cohesion, labels, gods, surprises, detection,
-                          {"input": 0, "output": 0}, str(watch_path), suggested_questions=questions)
-        (out / "GRAPH_REPORT.md").write_text(report, encoding="utf-8")
-        to_json(G, communities, str(out / "graph.json"))
-        to_html(G, communities, str(out / "graph.html"), community_labels=labels or None)
-
-        # clear stale needs_update flag if present
-        flag = out / "needs_update"
-        if flag.exists():
-            flag.unlink()
-
-        print(f"[graphify watch] Rebuilt: {G.number_of_nodes()} nodes, "
-              f"{G.number_of_edges()} edges, {len(communities)} communities")
-        print(f"[graphify watch] graph.json, graph.html and GRAPH_REPORT.md updated in {out}")
-        return True
-
-    except Exception as exc:
-        print(f"[graphify watch] Rebuild failed: {exc}")
-        return False
-
-
-def _notify_only(watch_path: Path) -> None:
-    """Write a flag file and print a notification (fallback for non-code-only corpora)."""
-    flag = watch_path / "graphify-out" / "needs_update"
-    flag.parent.mkdir(parents=True, exist_ok=True)
-    flag.write_text("1", encoding="utf-8")
-    print(f"\n[graphify watch] New or changed files detected in {watch_path}")
-    print("[graphify watch] Non-code files changed - semantic re-extraction requires LLM.")
-    print("[graphify watch] Run `/graphify --update` in Claude Code to update the graph.")
-    print(f"[graphify watch] Flag written to {flag}")
-
-
-def _has_non_code(changed_paths: list[Path]) -> bool:
-    return any(p.suffix.lower() not in _CODE_EXTENSIONS for p in changed_paths)
-
-
-def watch(watch_path: Path, debounce: float = 3.0) -> None:
-    """
-    Watch watch_path for new or modified files and auto-update the graph.
-
-    For code-only changes: re-runs AST extraction + rebuild immediately (no LLM).
-    For doc/paper/image changes: writes a needs_update flag and notifies the user
-    to run /graphify --update (LLM extraction required).
-
-    debounce: seconds to wait after the last change before triggering (avoids
-    running on every keystroke when many files are saved at once).
-    """
-    try:
-        from watchdog.observers import Observer
-        from watchdog.observers.polling import PollingObserver
-        from watchdog.events import FileSystemEventHandler
-    except ImportError as e:
-        raise ImportError("watchdog not installed. Run: pip install watchdog") from e
-
-    last_trigger: float = 0.0
-    pending: bool = False
-    changed: set[Path] = set()
-
-    class Handler(FileSystemEventHandler):
-        def on_any_event(self, event):
-            nonlocal last_trigger, pending
-            if event.is_directory:
-                return
-            path = Path(event.src_path)
-            if path.suffix.lower() not in _WATCHED_EXTENSIONS:
-                return
-            if any(part.startswith(".") for part in path.parts):
-                return
-            if "graphify-out" in path.parts:
-                return
-            last_trigger = time.monotonic()
-            pending = True
-            changed.add(path)
-
-    handler = Handler()
-    # Use polling observer on macOS — FSEvents can miss rapid saves in some editors
-    observer = PollingObserver() if sys.platform == "darwin" else Observer()
-    observer.schedule(handler, str(watch_path), recursive=True)
-    observer.start()
-
-    print(f"[graphify watch] Watching {watch_path.resolve()} - press Ctrl+C to stop")
-    print(f"[graphify watch] Code changes rebuild graph automatically. "
-          f"Doc/image changes require /graphify --update.")
-    print(f"[graphify watch] Debounce: {debounce}s")
-
-    try:
-        while True:
-            time.sleep(0.5)
-            if pending and (time.monotonic() - last_trigger) >= debounce:
-                pending = False
-                batch = list(changed)
-                changed.clear()
-                print(f"\n[graphify watch] {len(batch)} file(s) changed")
-                if _has_non_code(batch):
-                    _notify_only(watch_path)
-                else:
-                    _rebuild_code(watch_path)
-    except KeyboardInterrupt:
-        print("\n[graphify watch] Stopped.")
-    finally:
-        observer.stop()
-        observer.join()
-
-
-if __name__ == "__main__":
-    import argparse
-    parser = argparse.ArgumentParser(description="Watch a folder and auto-update the graphify graph")
-    parser.add_argument("path", nargs="?", default=".", help="Folder to watch (default: .)")
-    parser.add_argument("--debounce", type=float, default=3.0,
-                        help="Seconds to wait after last change before updating (default: 3)")
-    args = parser.parse_args()
-    watch(Path(args.path), debounce=args.debounce)

package/runtime/python/okstra_vendor/graphify/wiki.py

@@ -1,214 +0,0 @@
-# Wiki export - Wikipedia-style markdown articles from the knowledge graph
-# Generates an agent-crawlable wiki: index.md + one article per community + god node articles
-from __future__ import annotations
-from collections import Counter
-from pathlib import Path
-import networkx as nx
-
-
-def _safe_filename(name: str) -> str:
-    return name.replace("/", "-").replace(" ", "_").replace(":", "-")
-
-
-def _cross_community_links(G: nx.Graph, nodes: list[str], own_cid: int, labels: dict[int, str]) -> list[tuple[str, int]]:
-    """Return (community_label, edge_count) pairs for cross-community connections, sorted descending."""
-    counts: dict[str, int] = Counter()
-    for nid in nodes:
-        for neighbor in G.neighbors(nid):
-            nd = G.nodes[neighbor]
-            ncid = nd.get("community")
-            if ncid is not None and ncid != own_cid:
-                counts[labels.get(ncid, f"Community {ncid}")] += 1
-    return sorted(counts.items(), key=lambda x: -x[1])
-
-
-def _community_article(
-    G: nx.Graph,
-    cid: int,
-    nodes: list[str],
-    label: str,
-    labels: dict[int, str],
-    cohesion: float | None,
-) -> str:
-    top_nodes = sorted(nodes, key=lambda n: G.degree(n), reverse=True)[:25]
-    cross = _cross_community_links(G, nodes, cid, labels)
-
-    # Edge confidence breakdown
-    conf_counts: Counter = Counter()
-    for nid in nodes:
-        for neighbor in G.neighbors(nid):
-            ed = G.edges[nid, neighbor]
-            conf_counts[ed.get("confidence", "EXTRACTED")] += 1
-    total_edges = sum(conf_counts.values()) or 1
-
-    sources = sorted({G.nodes[n].get("source_file", "") for n in nodes} - {""})
-
-    lines: list[str] = []
-    lines += [f"# {label}", ""]
-
-    meta_parts = [f"{len(nodes)} nodes"]
-    if cohesion is not None:
-        meta_parts.append(f"cohesion {cohesion:.2f}")
-    lines += [f"> {' · '.join(meta_parts)}", ""]
-
-    lines += ["## Key Concepts", ""]
-    for nid in top_nodes:
-        d = G.nodes[nid]
-        node_label = d.get("label", nid)
-        src = d.get("source_file", "")
-        degree = G.degree(nid)
-        src_str = f" — `{src}`" if src else ""
-        lines.append(f"- **{node_label}** ({degree} connections){src_str}")
-    remaining = len(nodes) - len(top_nodes)
-    if remaining > 0:
-        lines.append(f"- *... and {remaining} more nodes in this community*")
-    lines.append("")
-
-    lines += ["## Relationships", ""]
-    if cross:
-        for other_label, count in cross[:12]:
-            lines.append(f"- [[{other_label}]] ({count} shared connections)")
-    else:
-        lines.append("- No strong cross-community connections detected")
-    lines.append("")
-
-    if sources:
-        lines += ["## Source Files", ""]
-        for src in sources[:20]:
-            lines.append(f"- `{src}`")
-        lines.append("")
-
-    lines += ["## Audit Trail", ""]
-    for conf in ("EXTRACTED", "INFERRED", "AMBIGUOUS"):
-        n = conf_counts.get(conf, 0)
-        pct = round(n / total_edges * 100)
-        lines.append(f"- {conf}: {n} ({pct}%)")
-    lines.append("")
-
-    lines += ["---", "", "*Part of the graphify knowledge wiki. See [[index]] to navigate.*"]
-    return "\n".join(lines)
-
-
-def _god_node_article(G: nx.Graph, nid: str, labels: dict[int, str]) -> str:
-    d = G.nodes[nid]
-    node_label = d.get("label", nid)
-    src = d.get("source_file", "")
-    cid = d.get("community")
-    community_name = labels.get(cid, f"Community {cid}") if cid is not None else None
-
-    lines: list[str] = []
-    lines += [f"# {node_label}", ""]
-    lines += [f"> God node · {G.degree(nid)} connections · `{src}`", ""]
-
-    if community_name:
-        lines += [f"**Community:** [[{community_name}]]", ""]
-
-    # Group neighbors by relation type
-    by_relation: dict[str, list[str]] = {}
-    for neighbor in sorted(G.neighbors(nid), key=lambda n: G.degree(n), reverse=True):
-        nd = G.nodes[neighbor]
-        ed = G.edges[nid, neighbor]
-        rel = ed.get("relation", "related")
-        neighbor_label = nd.get("label", neighbor)
-        conf = ed.get("confidence", "")
-        conf_str = f" `{conf}`" if conf else ""
-        by_relation.setdefault(rel, []).append(f"[[{neighbor_label}]]{conf_str}")
-
-    lines += ["## Connections by Relation", ""]
-    for rel, targets in sorted(by_relation.items()):
-        lines.append(f"### {rel}")
-        for t in targets[:20]:
-            lines.append(f"- {t}")
-        lines.append("")
-
-    lines += ["---", "", "*Part of the graphify knowledge wiki. See [[index]] to navigate.*"]
-    return "\n".join(lines)
-
-
-def _index_md(
-    communities: dict[int, list[str]],
-    labels: dict[int, str],
-    god_nodes_data: list[dict],
-    total_nodes: int,
-    total_edges: int,
-) -> str:
-    lines: list[str] = [
-        "# Knowledge Graph Index",
-        "",
-        "> Auto-generated by graphify. Start here — read community articles for context, then drill into god nodes for detail.",
-        "",
-        f"**{total_nodes} nodes · {total_edges} edges · {len(communities)} communities**",
-        "",
-        "---",
-        "",
-        "## Communities",
-        "(sorted by size, largest first)",
-        "",
-    ]
-
-    for cid, nodes in sorted(communities.items(), key=lambda x: -len(x[1])):
-        label = labels.get(cid, f"Community {cid}")
-        lines.append(f"- [[{label}]] — {len(nodes)} nodes")
-    lines.append("")
-
-    if god_nodes_data:
-        lines += ["## God Nodes", "(most connected concepts — the load-bearing abstractions)", ""]
-        for node in god_nodes_data:
-            lines.append(f"- [[{node['label']}]] — {node['degree']} connections")
-        lines.append("")
-
-    lines += [
-        "---",
-        "",
-        "*Generated by [graphify](https://github.com/safishamsi/graphify)*",
-    ]
-    return "\n".join(lines)
-
-
-def to_wiki(
-    G: nx.Graph,
-    communities: dict[int, list[str]],
-    output_dir: str | Path,
-    community_labels: dict[int, str] | None = None,
-    cohesion: dict[int, float] | None = None,
-    god_nodes_data: list[dict] | None = None,
-) -> int:
-    """Generate a Wikipedia-style wiki from the graph.
-
-    Writes:
-      - index.md            — agent entry point, catalog of all articles
-      - <CommunityName>.md  — one article per community
-      - <GodNodeLabel>.md   — one article per god node
-
-    Returns the number of articles written (excluding index.md).
-    """
-    out = Path(output_dir)
-    out.mkdir(parents=True, exist_ok=True)
-
-    labels = community_labels or {cid: f"Community {cid}" for cid in communities}
-    cohesion = cohesion or {}
-    god_nodes_data = god_nodes_data or []
-
-    count = 0
-
-    # Community articles
-    for cid, nodes in communities.items():
-        label = labels.get(cid, f"Community {cid}")
-        article = _community_article(G, cid, nodes, label, labels, cohesion.get(cid))
-        (out / f"{_safe_filename(label)}.md").write_text(article)
-        count += 1
-
-    # God node articles
-    for node_data in god_nodes_data:
-        nid = node_data.get("id")
-        if nid and nid in G:
-            article = _god_node_article(G, nid, labels)
-            (out / f"{_safe_filename(node_data['label'])}.md").write_text(article)
-            count += 1
-
-    # Index
-    (out / "index.md").write_text(
-        _index_md(communities, labels, god_nodes_data, G.number_of_nodes(), G.number_of_edges())
-    )
-
-    return count