codedocent 0.3.0__tar.gz → 0.5.0__tar.gz

codedocent-0.5.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.1
+Name: codedocent
+Version: 0.5.0
+Summary: Code visualization for non-programmers
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+License-File: LICENSE
+
+# codedocent
+
+<img width="1658" height="2158" alt="Screenshot_2026-02-09_13-17-06" src="https://github.com/user-attachments/assets/ff097ead-69ec-4618-b7b7-2b99c60ac57e" />
+
+**Code visualization for non-programmers.**
+
+A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
+
+## The problem
+
+You're staring at a codebase you didn't write — maybe thousands of files across dozens of directories — and you need to understand what it does. Reading every file isn't realistic. You need a way to visualize the code structure, get a high-level map of what's where, and drill into the parts that matter without losing context.
+
+Codedocent parses the codebase into a navigable, visual block structure and explains each piece in plain English. It's an AI code analysis tool — use a cloud provider for speed or run locally through Ollama for full privacy. Point it at any codebase and get a structural overview you can explore interactively, understand quickly, and share as a static HTML file.
+
+## Who this is for
+
+- **Developers onboarding onto an unfamiliar codebase** — get oriented in minutes instead of days
+- **Non-programmers** (managers, designers, PMs) who need to understand what code does without reading it
+- **Solo developers inheriting legacy code** — map out the structure before making changes
+- **Code reviewers** who want a high-level overview before diving into details
+- **Security reviewers** who need a structural map of an application
+- **Students** learning to read and navigate real-world codebases
+
+## What you see
+
+Nested, color-coded blocks representing directories, files, classes, and functions — the entire structure of a codebase laid out visually. Each block shows a plain English summary, a pseudocode translation, and quality warnings (green/yellow/red). Click any block to drill down; breadcrumbs navigate you back up. You can export code from any block or paste replacement code back into the source file. AI explanations come from your choice of cloud provider or local Ollama.
+
+## Install
+
+```bash
+pip install codedocent
+```
+
+Requires Python 3.10+. Cloud AI needs an API key set in an env var (e.g. `OPENAI_API_KEY`). Local AI needs [Ollama](https://ollama.com) running. `--no-ai` skips AI entirely.
+
+## Quick start
+
+```bash
+codedocent                         # setup wizard — walks you through everything
+codedocent /path/to/code           # interactive mode (recommended)
+codedocent /path/to/code --full    # full analysis, static HTML output
+codedocent --gui                   # graphical launcher
+codedocent /path/to/code --cloud openai    # use OpenAI
+codedocent /path/to/code --cloud groq      # use Groq
+codedocent /path/to/code --cloud custom --endpoint https://my-llm/v1/chat/completions
+```
+
+## How it works
+
+Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a cloud AI provider or local Ollama model for plain English summaries and pseudocode. Interactive mode analyzes on click — typically 1-2 seconds per block. Full mode analyzes everything upfront into a self-contained HTML file you can share.
+
+## AI options
+
+- **Cloud AI** — send code to OpenAI, OpenRouter, Groq, or any OpenAI-compatible endpoint. Fast, no local setup. Your code is sent to that service. API keys are read from env vars (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `GROQ_API_KEY`, `CODEDOCENT_API_KEY` for custom endpoints).
+- **Local AI** — [Ollama](https://ollama.com) on your machine. Code never leaves your laptop. No API keys, no accounts.
+- **No AI** (`--no-ai`) — structure and quality scores only.
+
+The setup wizard (`codedocent` with no args) walks you through choosing.
+
+## Supported languages
+
+Full AST parsing for Python and JavaScript/TypeScript (functions, classes, methods, imports). File-level detection for 23 extensions including C, C++, Rust, Go, Java, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, and config formats.
+
+## License
+
+MIT

codedocent-0.5.0/README.md

@@ -0,0 +1,66 @@
+# codedocent
+
+<img width="1658" height="2158" alt="Screenshot_2026-02-09_13-17-06" src="https://github.com/user-attachments/assets/ff097ead-69ec-4618-b7b7-2b99c60ac57e" />
+
+**Code visualization for non-programmers.**
+
+A docent is a guide who explains things to people who aren't experts. Codedocent does that for code.
+
+## The problem
+
+You're staring at a codebase you didn't write — maybe thousands of files across dozens of directories — and you need to understand what it does. Reading every file isn't realistic. You need a way to visualize the code structure, get a high-level map of what's where, and drill into the parts that matter without losing context.
+
+Codedocent parses the codebase into a navigable, visual block structure and explains each piece in plain English. It's an AI code analysis tool — use a cloud provider for speed or run locally through Ollama for full privacy. Point it at any codebase and get a structural overview you can explore interactively, understand quickly, and share as a static HTML file.
+
+## Who this is for
+
+- **Developers onboarding onto an unfamiliar codebase** — get oriented in minutes instead of days
+- **Non-programmers** (managers, designers, PMs) who need to understand what code does without reading it
+- **Solo developers inheriting legacy code** — map out the structure before making changes
+- **Code reviewers** who want a high-level overview before diving into details
+- **Security reviewers** who need a structural map of an application
+- **Students** learning to read and navigate real-world codebases
+
+## What you see
+
+Nested, color-coded blocks representing directories, files, classes, and functions — the entire structure of a codebase laid out visually. Each block shows a plain English summary, a pseudocode translation, and quality warnings (green/yellow/red). Click any block to drill down; breadcrumbs navigate you back up. You can export code from any block or paste replacement code back into the source file. AI explanations come from your choice of cloud provider or local Ollama.
+
+## Install
+
+```bash
+pip install codedocent
+```
+
+Requires Python 3.10+. Cloud AI needs an API key set in an env var (e.g. `OPENAI_API_KEY`). Local AI needs [Ollama](https://ollama.com) running. `--no-ai` skips AI entirely.
+
+## Quick start
+
+```bash
+codedocent                         # setup wizard — walks you through everything
+codedocent /path/to/code           # interactive mode (recommended)
+codedocent /path/to/code --full    # full analysis, static HTML output
+codedocent --gui                   # graphical launcher
+codedocent /path/to/code --cloud openai    # use OpenAI
+codedocent /path/to/code --cloud groq      # use Groq
+codedocent /path/to/code --cloud custom --endpoint https://my-llm/v1/chat/completions
+```
+
+## How it works
+
+Parses code structure with tree-sitter, scores quality with static analysis, and sends individual blocks to a cloud AI provider or local Ollama model for plain English summaries and pseudocode. Interactive mode analyzes on click — typically 1-2 seconds per block. Full mode analyzes everything upfront into a self-contained HTML file you can share.
+
+## AI options
+
+- **Cloud AI** — send code to OpenAI, OpenRouter, Groq, or any OpenAI-compatible endpoint. Fast, no local setup. Your code is sent to that service. API keys are read from env vars (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `GROQ_API_KEY`, `CODEDOCENT_API_KEY` for custom endpoints).
+- **Local AI** — [Ollama](https://ollama.com) on your machine. Code never leaves your laptop. No API keys, no accounts.
+- **No AI** (`--no-ai`) — structure and quality scores only.
+
+The setup wizard (`codedocent` with no args) walks you through choosing.
+
+## Supported languages
+
+Full AST parsing for Python and JavaScript/TypeScript (functions, classes, methods, imports). File-level detection for 23 extensions including C, C++, Rust, Go, Java, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, and config formats.
+
+## License
+
+MIT

{codedocent-0.3.0 → codedocent-0.5.0}/codedocent/analyzer.py

@@ -115,13 +115,49 @@ def _parse_ai_response(text: str) -> tuple[str, str]:
 _AI_TIMEOUT = 120
 
 
+def _summarize_with_cloud(
+    node: CodeNode, ai_config: dict,
+) -> tuple[str, str] | None:
+    """Call a cloud AI endpoint for summary and pseudocode.
+
+    Returns ``None`` if the call times out.
+    Raises ``RuntimeError`` on API errors.
+    """
+    from codedocent.cloud_ai import cloud_chat  # pylint: disable=import-outside-toplevel  # noqa: E501
+
+    prompt = _build_prompt(node, ai_config["model"])
+    pool = ThreadPoolExecutor(max_workers=1)
+    future = pool.submit(
+        cloud_chat,
+        prompt, ai_config["endpoint"],
+        ai_config["api_key"], ai_config["model"],
+    )
+    try:
+        raw = future.result(timeout=_AI_TIMEOUT)
+    except TimeoutError:
+        future.cancel()
+        pool.shutdown(wait=False, cancel_futures=True)
+        return None
+    pool.shutdown(wait=False)
+    raw = _strip_think_tags(raw)
+    if not raw or len(raw) < 10:
+        return ("Could not generate summary", "")
+    summary, pseudocode = _parse_ai_response(raw)
+    if not summary or len(summary) < 5:
+        summary = "Could not generate summary"
+    return summary, pseudocode
+
+
 def _summarize_with_ai(
-    node: CodeNode, model: str
+    node: CodeNode, model: str, ai_config: dict | None = None,
 ) -> tuple[str, str] | None:
-    """Call ollama to get summary and pseudocode for a node.
+    """Call ollama (or cloud) to get summary and pseudocode for a node.
 
     Returns ``None`` if the AI call times out.
     """
+    if ai_config and ai_config.get("backend") == "cloud":
+        return _summarize_with_cloud(node, ai_config)
+
     prompt = _build_prompt(node, model)
     pool = ThreadPoolExecutor(max_workers=1)
     future = pool.submit(
@@ -151,6 +187,13 @@ def _summarize_with_ai(
     return summary, pseudocode
 
 
+def _cache_model_id(model: str, ai_config: dict | None = None) -> str:
+    """Return a cache-key model identifier."""
+    if ai_config and ai_config.get("backend") == "cloud":
+        return f"cloud:{ai_config['provider']}:{ai_config['model']}"
+    return model
+
+
 # ---------------------------------------------------------------------------
 # Cache
 # ---------------------------------------------------------------------------
@@ -235,12 +278,16 @@ def assign_node_ids(root: CodeNode) -> dict[str, CodeNode]:
 # ---------------------------------------------------------------------------
 
 
-def analyze_single_node(node: CodeNode, model: str, cache_dir: str) -> None:
+def analyze_single_node(  # pylint: disable=too-many-locals
+    node: CodeNode, model: str, cache_dir: str,
+    *, ai_config: dict | None = None,
+) -> None:
     """Run quality scoring + AI analysis on a single node.
 
     Reads/writes the cache. Applies min-lines guard and garbage fallback.
     """
-    if ollama is None:
+    is_cloud = ai_config and ai_config.get("backend") == "cloud"
+    if not is_cloud and ollama is None:
         node.summary = "AI unavailable (ollama not installed)"
         return
 
@@ -263,8 +310,9 @@ def analyze_single_node(node: CodeNode, model: str, cache_dir: str) -> None:
     cache_path = os.path.join(cache_dir, CACHE_FILENAME)
     cache = _load_cache(cache_path)
 
-    if cache.get("model") != model:
-        cache = {"version": 1, "model": model, "entries": {}}
+    model_id = _cache_model_id(model, ai_config)
+    if cache.get("model") != model_id:
+        cache = {"version": 1, "model": model_id, "entries": {}}
 
     key = _cache_key(node)
     if key in cache["entries"]:
@@ -274,7 +322,7 @@ def analyze_single_node(node: CodeNode, model: str, cache_dir: str) -> None:
         return
 
     try:
-        result = _summarize_with_ai(node, model)
+        result = _summarize_with_ai(node, model, ai_config=ai_config)
         if result is None:
             node.summary = "Summary timed out"
             return
@@ -287,7 +335,8 @@ def analyze_single_node(node: CodeNode, model: str, cache_dir: str) -> None:
         ConnectionError, RuntimeError, ValueError,
         OSError, AttributeError, TypeError,
     ) as e:
-        node.summary = f"Summary generation failed: {e}"
+        print(f"  AI error for {node.name}: {e}", file=sys.stderr)
+        node.summary = "Summary generation failed"
 
 
 # ---------------------------------------------------------------------------
@@ -359,6 +408,7 @@ def _run_ai_batch(
     model: str,
     cache: dict,
     workers: int,
+    ai_config: dict | None = None,
 ) -> int:
     """Phases 2 & 3: AI-analyze files then code nodes."""
     total, counter = len(all_nodes), [0]
@@ -384,7 +434,7 @@ def _run_ai_batch(
                 return
         _progress(f"Analyzing {node.name}")
         try:
-            result = _summarize_with_ai(node, model)
+            result = _summarize_with_ai(node, model, ai_config=ai_config)
             if result is None:
                 node.summary = "Summary timed out"
                 return
@@ -425,13 +475,16 @@ def _require_ollama() -> None:
         sys.exit(1)
 
 
-def _init_cache(root: CodeNode, model: str) -> tuple[str, dict]:
+def _init_cache(
+    root: CodeNode, model: str, ai_config: dict | None = None,
+) -> tuple[str, dict]:
     """Load (or reset) the analysis cache for *model*."""
     cache_dir = root.filepath or "."
     cache_path = os.path.join(cache_dir, CACHE_FILENAME)
     cache = _load_cache(cache_path)
-    if cache.get("model") != model:
-        cache = {"version": 1, "model": model, "entries": {}}
+    model_id = _cache_model_id(model, ai_config)
+    if cache.get("model") != model_id:
+        cache = {"version": 1, "model": model_id, "entries": {}}
     return cache_path, cache
 
 
@@ -439,11 +492,15 @@ def analyze(
     root: CodeNode,
     model: str = "qwen3:14b",
     workers: int = 1,
+    *,
+    ai_config: dict | None = None,
 ) -> CodeNode:
     """Analyze the full tree with AI summaries and quality scoring."""
-    _require_ollama()
+    is_cloud = ai_config and ai_config.get("backend") == "cloud"
+    if not is_cloud:
+        _require_ollama()
 
-    cache_path, cache = _init_cache(root, model)
+    cache_path, cache = _init_cache(root, model, ai_config=ai_config)
     all_nodes = _collect_nodes(root)
     start_time = time.monotonic()
 
@@ -451,7 +508,9 @@ def analyze(
     _rollup_file_quality(all_nodes)
 
     try:
-        ai_count = _run_ai_batch(all_nodes, model, cache, workers)
+        ai_count = _run_ai_batch(
+            all_nodes, model, cache, workers, ai_config=ai_config,
+        )
     except ConnectionError as e:
         print(
             f"\nError: Could not connect to ollama: {e}\n"
@@ -460,6 +519,14 @@ def analyze(
             file=sys.stderr,
         )
         sys.exit(1)
+    except RuntimeError as e:
+        print(
+            f"\nError: Cloud AI request failed: {e}\n"
+            "Check your API key and endpoint, or use --no-ai"
+            " to skip AI analysis.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
 
     _summarize_directories(all_nodes)
     _save_cache(cache_path, cache)

{codedocent-0.3.0 → codedocent-0.5.0}/codedocent/cli.py

@@ -6,6 +6,9 @@ import argparse
 import os
 import sys
 
+from codedocent.cloud_ai import (
+    CLOUD_PROVIDERS, validate_cloud_config, _MaskedSecret,
+)
 from codedocent.ollama_utils import check_ollama, fetch_ollama_models
 from codedocent.parser import CodeNode, parse_directory
 from codedocent.scanner import scan_directory
@@ -88,28 +91,111 @@ def _pick_model(models: list[str]) -> str:
     return models[0]
 
 
+def _wizard_cloud_setup() -> dict | None:
+    """Handle the cloud AI setup sub-flow of the wizard.
+
+    Returns an ai_config dict on success, or None if the user
+    cannot proceed (exits with instructions).
+    """
+    print("\nWhich cloud provider?")
+    providers = ["openai", "openrouter", "groq", "custom"]
+    for i, p in enumerate(providers, 1):
+        print(f"  {i}. {CLOUD_PROVIDERS[p]['name']}")
+    choice = _safe_input("Provider [1]: ").strip()
+    try:
+        idx = int(choice) - 1 if choice else 0
+        if not 0 <= idx < len(providers):
+            idx = 0
+    except ValueError:
+        idx = 0
+    provider = providers[idx]
+
+    info = CLOUD_PROVIDERS[provider]
+    endpoint = info["endpoint"]
+
+    if provider == "custom":
+        endpoint = _safe_input("Endpoint URL: ").strip()
+        if not endpoint:
+            print("Error: custom provider requires an endpoint URL.")
+            sys.exit(1)
+
+    env_var = info["env_var"]
+    api_key = os.environ.get(env_var, "")
+    if api_key:
+        print(f"API key found in ${env_var}")
+    else:
+        print(
+            f"\nAPI key not found. Set it with:\n"
+            f"  export {env_var}=your-key-here\n"
+            f"Then run codedocent again."
+        )
+        sys.exit(1)
+
+    # Model picker
+    models = info["models"]
+    if models:
+        model = _pick_model(models)
+    else:
+        model = _safe_input("Model name: ").strip()
+        if not model:
+            print("Error: model name is required.")
+            sys.exit(1)
+
+    # Validate
+    print("Testing connection...", end=" ", flush=True)
+    ok, err = validate_cloud_config(provider, endpoint, api_key, model)
+    if ok:
+        print("success!")
+    else:
+        print(f"failed: {err}")
+        sys.exit(1)
+
+    return {
+        "backend": "cloud",
+        "provider": provider,
+        "endpoint": endpoint,
+        "api_key": _MaskedSecret(api_key),
+        "model": model,
+    }
+
+
 def _run_wizard() -> argparse.Namespace:
     """Interactive setup wizard for codedocent."""
     print("\ncodedocent \u2014 code visualization for humans\n")
 
     path = _ask_folder()
 
-    # --- Ollama check ---
+    # --- Backend choice ---
     model = "qwen3:14b"
     no_ai = False
-
-    print("Checking for Ollama...", end=" ", flush=True)
-    if _check_ollama():
-        print("found!")
-        models = _fetch_ollama_models()
-        if models:
-            model = _pick_model(models)
+    ai_config = None
+
+    print("How would you like Codedocent to understand your code?")
+    print("  [1] Cloud AI \u2014 Uses a service like OpenAI or OpenRouter.")
+    print("  [2] Local AI \u2014 Uses Ollama running on your machine.")
+    print("  [3] No AI \u2014 Just show code structure and quality scores.")
+    backend_choice = _safe_input("Choice [2]: ").strip()
+
+    if backend_choice == "1":
+        ai_config = _wizard_cloud_setup()
+        if ai_config:
+            model = ai_config["model"]
+    elif backend_choice == "3":
+        no_ai = True
+    else:
+        # Default: Local AI (Ollama)
+        print("Checking for Ollama...", end=" ", flush=True)
+        if _check_ollama():
+            print("found!")
+            models = _fetch_ollama_models()
+            if models:
+                model = _pick_model(models)
+            else:
+                print("No models found.")
+                no_ai = _ask_no_ai_fallback()
         else:
-            print("No models found.")
+            print("not found.")
             no_ai = _ask_no_ai_fallback()
-    else:
-        print("not found.")
-        no_ai = _ask_no_ai_fallback()
 
     # --- Mode ---
     print("\nHow do you want to view it?")
@@ -133,6 +219,10 @@ def _run_wizard() -> argparse.Namespace:
         port=None,
         workers=1,
         gui=False,
+        cloud=ai_config["provider"] if ai_config else None,
+        endpoint=ai_config["endpoint"] if ai_config else None,
+        api_key_env=None,
+        ai_config=ai_config,
     )
 
 
@@ -156,7 +246,7 @@ def _build_arg_parser() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--model", default="qwen3:14b",
-        help="Ollama model for AI summaries (default: qwen3:14b)",
+        help="AI model for summaries (default: qwen3:14b)",
     )
     parser.add_argument(
         "--no-ai", action="store_true",
@@ -178,9 +268,71 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         "--gui", action="store_true",
         help="Open GUI launcher",
     )
+    parser.add_argument(
+        "--cloud",
+        choices=["openai", "openrouter", "groq", "custom"],
+        default=None,
+        help="Use cloud AI provider instead of Ollama",
+    )
+    parser.add_argument(
+        "--endpoint", default=None,
+        help="Custom endpoint URL (required with --cloud custom)",
+    )
+    parser.add_argument(
+        "--api-key-env", default=None,
+        help="Override environment variable name for the API key",
+    )
     return parser
 
 
+def _build_ai_config(args: argparse.Namespace) -> dict | None:
+    """Build an ai_config dict from parsed CLI args, or None for ollama."""
+    if args.cloud is None:
+        return None
+
+    provider = args.cloud
+    info = CLOUD_PROVIDERS[provider]
+
+    # Endpoint
+    if provider == "custom":
+        if not args.endpoint:
+            print(
+                "Error: --endpoint is required with --cloud custom",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        endpoint = args.endpoint
+    else:
+        endpoint = args.endpoint or info["endpoint"]
+
+    # Validate endpoint
+    from codedocent.cloud_ai import _validate_endpoint  # pylint: disable=import-outside-toplevel  # noqa: E501
+    try:
+        _validate_endpoint(endpoint)
+    except ValueError:
+        print("Error: Invalid endpoint URL", file=sys.stderr)
+        sys.exit(1)
+
+    # API key
+    env_var = args.api_key_env or info["env_var"]
+    api_key = os.environ.get(env_var, "")
+    if not api_key:
+        print(
+            f"Error: API key not found. Set it with:\n"
+            f"  export {env_var}=your-key-here",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    return {
+        "backend": "cloud",
+        "provider": provider,
+        "endpoint": endpoint,
+        "api_key": _MaskedSecret(api_key),
+        "model": args.model,
+    }
+
+
 def _run_text_mode(tree: CodeNode) -> None:
     """Text mode: quality score only, print tree."""
     from codedocent.analyzer import analyze_no_ai  # pylint: disable=import-outside-toplevel  # noqa: E501
@@ -201,18 +353,20 @@ def _run_no_ai_mode(tree: CodeNode, output: str) -> None:
 
 def _run_full_mode(
     tree: CodeNode, model: str, workers: int, output: str,
+    ai_config: dict | None = None,
 ) -> None:
     """Full mode: upfront AI analysis, static HTML."""
     from codedocent.analyzer import analyze  # pylint: disable=import-outside-toplevel  # noqa: E501
     from codedocent.renderer import render  # pylint: disable=import-outside-toplevel  # noqa: E501
 
-    analyze(tree, model=model, workers=workers)
+    analyze(tree, model=model, workers=workers, ai_config=ai_config)
     render(tree, output)
     print(f"HTML output written to {output}")
 
 
 def _run_interactive_mode(
     tree: CodeNode, model: str, port: int | None,
+    ai_config: dict | None = None,
 ) -> None:
     """Default lazy mode: interactive server."""
     from codedocent.analyzer import analyze_no_ai, assign_node_ids  # pylint: disable=import-outside-toplevel  # noqa: E501
@@ -220,7 +374,8 @@ def _run_interactive_mode(
 
     analyze_no_ai(tree)
     node_lookup = assign_node_ids(tree)
-    start_server(tree, node_lookup, model=model, port=port)
+    start_server(tree, node_lookup, model=model, port=port,
+                 ai_config=ai_config)
 
 
 def main() -> None:
@@ -236,6 +391,9 @@ def main() -> None:
 
     if args.path is None:
         args = _run_wizard()
+        ai_config = getattr(args, "ai_config", None)
+    else:
+        ai_config = _build_ai_config(args)
 
     scanned = scan_directory(args.path)
     tree = parse_directory(scanned, root=args.path)
@@ -245,9 +403,11 @@ def main() -> None:
     elif args.no_ai:
         _run_no_ai_mode(tree, args.output)
     elif args.full:
-        _run_full_mode(tree, args.model, args.workers, args.output)
+        _run_full_mode(tree, args.model, args.workers, args.output,
+                       ai_config=ai_config)
     else:
-        _run_interactive_mode(tree, args.model, args.port)
+        _run_interactive_mode(tree, args.model, args.port,
+                              ai_config=ai_config)
 
 
 if __name__ == "__main__":