okstra 0.108.0 → 0.109.0

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

@@ -0,0 +1,182 @@
+# 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

@@ -0,0 +1,72 @@
+# 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

@@ -0,0 +1,188 @@
+# 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

@@ -0,0 +1,214 @@
+# 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