codeboarding 0.15.1__tar.gz → 0.15.3__tar.gz

{codeboarding-0.15.1 → codeboarding-0.15.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.1
+Version: 0.15.3
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -112,7 +112,7 @@ pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 
 > Installing into the global Python environment with `pip` is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.
 
-Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):
+Each analysis downloads the language servers its repository's languages need, on first use. To pre-install all of them (useful in CI or restricted environments):
 
 ```bash
 codeboarding-setup

{codeboarding-0.15.1 → codeboarding-0.15.3}/PYPI.md

@@ -38,7 +38,7 @@ pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 
 > Installing into the global Python environment with `pip` is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.
 
-Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):
+Each analysis downloads the language servers its repository's languages need, on first use. To pre-install all of them (useful in CI or restricted environments):
 
 ```bash
 codeboarding-setup

{codeboarding-0.15.1 → codeboarding-0.15.3}/README.md

@@ -153,7 +153,7 @@ codeboarding-render /path/to/analysis.json --format mdx --output-dir /path/to/do
 python codeboarding_cli/render.py ../../demo/markitdown/.codeboarding/analysis.json --format md
 ```
 
-`python -m infra.install` and `codeboarding-setup` download language server binaries to `~/.codeboarding/servers/`, shared across projects. Node.js (and its bundled `npm`) is required for the Python, TypeScript, JavaScript, and PHP language servers; if neither `node` nor `CODEBOARDING_NODE_PATH` is set, setup downloads a pinned Node.js runtime into `~/.codeboarding/servers/nodeenv/` automatically.
+An analysis downloads the language servers its repository's languages need into `~/.codeboarding/servers/` the first time it needs them, shared across projects; `python -m infra.install` and `codeboarding-setup` download all of them up front. Node.js (and its bundled `npm`) is required for the Python, TypeScript, JavaScript, and PHP language servers; if neither `node` nor `CODEBOARDING_NODE_PATH` is set, setup downloads a pinned Node.js runtime into `~/.codeboarding/servers/nodeenv/` automatically.
 
 ## Configuration
 
@@ -172,6 +172,7 @@ On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provid
 # openrouter_api_key        = "sk-..."
 # orcarouter_api_key        = "sk-orca-..."   # model routing gateway (https://www.orcarouter.ai)
 # requesty_api_key          = "rqsty-..."     # LLM gateway (https://www.requesty.ai)
+# opper_api_key             = "..."           # EU-hosted AI gateway (https://opper.ai)
 # litellm_base_url          = "http://localhost:4000"  # LiteLLM proxy server URL (required)
 # litellm_api_key           = "sk-..."           # LiteLLM proxy server key (optional)
 
@@ -249,7 +250,7 @@ for the actual depth. Existing baseline loading behavior is unchanged: prefer
 - Languages: Python, TypeScript, JavaScript, Java, Kotlin, Go, PHP, Rust, C#.
   - Java needs a JDK (21 recommended).
   - Kotlin is analysed with JetBrains' [kotlin-lsp](https://github.com/Kotlin/kotlin-lsp) (about 360 MB with its own Java runtime, under the [JetBrains Free Plugin License](https://github.com/Kotlin/kotlin-lsp/blob/main/kotlin-vscode/LICENSE.txt)) and needs glibc 2.34 or newer on Linux. Kotlin calls into Java are not drawn yet.
-- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, LiteLLM proxy, and more.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, Opper, LiteLLM proxy, and more.
 
 ## Examples
 

{codeboarding-0.15.1 → codeboarding-0.15.3}/agents/llm_config.py

@@ -302,6 +302,19 @@ LLM_PROVIDERS = {
             "max_retries": 0,
         },
     ),
+    "opper": LLMConfig(
+        chat_class=ChatOpenAI,
+        selection_envs=["OPPER_API_KEY"],
+        api_key_env="OPPER_API_KEY",
+        agent_model="gemini-3.8-flash",
+        base_url_env="OPPER_BASE_URL",
+        default_base_url="https://api.opper.ai/v3/compat",
+        extra_args={
+            "max_tokens": None,
+            "timeout": LLMDefaults.REQUEST_TIMEOUT_SECONDS,
+            "max_retries": 0,
+        },
+    ),
     "litellm": LLMConfig(
         chat_class=ChatOpenAI,
         # Base URL only: a key alone must not select litellm, since there is no

{codeboarding-0.15.1 → codeboarding-0.15.3}/agents/llm_errors.py

@@ -1,17 +1,4 @@
-"""Provider-agnostic detection and typing of LLM authentication failures.
-
-A rejected API key (HTTP 401, or a provider's equivalent auth/permission
-error) is *permanent* for the run: retrying it wastes minutes of backoff and
-floods telemetry with identical ``$exception`` events. The agent retry loop and
-the CLI both need to recognize one when they see it, regardless of which SDK
-raised it.
-
-``detect_auth_error`` maps a raw provider exception to an :class:`LLMAuthError`
-(or ``None`` when it isn't an auth failure). The typed error carries the
-provider, a masked key tail, and the provider's own message, and forwards them
-as ``telemetry_properties`` so the PostHog ``$exception`` event — and the
-dashboard's structured ``error`` columns — populate instead of staying null.
-"""
+"""Provider-agnostic LLM failure classification, exceptions, and retry helpers."""
 
 from __future__ import annotations
 
@@ -33,6 +20,11 @@ EXIT_AUTH_ERROR = 2
 # Process exit code for an exhausted token or credit quota: the key is fine, the account is not.
 EXIT_QUOTA_EXHAUSTED = 3
 
+CODEBOARDING_QUOTA_CODE = "free_credits_exhausted"
+# Response contract: licensing-aws/gha_proxy/handler.py.
+PROXY_ERROR_TYPE = "gha_proxy"
+PROXY_QUOTA_MESSAGE = "Resource exhausted: token limit reached"
+
 # Class names, across SDKs, that always mean "credentials were rejected".
 # openai/anthropic/cerebras raise ``AuthenticationError``; google raises
 # ``Unauthenticated``/``PermissionDenied``; Bedrock (botocore) surfaces
@@ -114,6 +106,65 @@ class LLMAuthError(RuntimeError):
         self.telemetry_properties = telemetry_properties
 
 
+class LLMQuotaError(RuntimeError):
+    """An LLM quota is exhausted, with recovery guidance and failure telemetry."""
+
+    def __init__(self, error: BaseException):
+        self.telemetry_properties = llm_failure_properties(error)
+        self.is_codeboarding_quota = _is_codeboarding_quota(error)
+        _, key_tail = current_provider_key_context()
+        if self.is_codeboarding_quota:
+            message = (
+                "Your CodeBoarding quota is exhausted. "
+                "Buy a CodeBoarding license at https://codeboarding.org/pricing, "
+                "or wait for your weekly reset."
+            )
+        elif key_tail == CODEBOARDING_KEY_TAIL:
+            message = (
+                "The hosted LLM provider's quota is exhausted. "
+                "This is a CodeBoarding service issue. Please try again later or contact CodeBoarding support."
+            )
+        else:
+            message = (
+                "The LLM provider's token or credit quota is exhausted. "
+                "Add credits or raise the quota for this provider, then re-run."
+            )
+        super().__init__(message)
+
+
+def llm_failure_properties(exc: BaseException) -> dict:
+    """Classify a failed LLM call for exception telemetry."""
+    quota = is_quota_exhausted(exc)
+    context = isinstance(exc, ScopeContextTooLargeError) or any(p.search(str(exc)) for p in _CONTEXT_OVERFLOW_PATTERNS)
+    provider, _key_tail = current_provider_key_context()
+    properties = {
+        "error_type": "quota" if quota else "context" if context else "llm",
+        "error_provider": provider,
+        "error_status_code": _status_code(exc),
+        "error_message": str(exc)[:500],
+    }
+    if _is_codeboarding_quota(exc):
+        properties["error_code"] = CODEBOARDING_QUOTA_CODE
+    return properties
+
+
+def is_quota_exhausted(exc: BaseException) -> bool:
+    status = _status_code(exc)
+    quota_code = getattr(exc, "code", None) == "insufficient_quota" or "insufficient_quota" in str(exc)
+    return status == 402 or (status == 429 and quota_code)
+
+
+def _is_codeboarding_quota(exc: BaseException) -> bool:
+    body = getattr(exc, "body", {})
+    error = body.get("error", body) if isinstance(body, dict) else {}
+    return (
+        _status_code(exc) == 402
+        and isinstance(error, dict)
+        and error.get("type") == PROXY_ERROR_TYPE
+        and error.get("message") == PROXY_QUOTA_MESSAGE
+    )
+
+
 def _status_code(exc: BaseException) -> int | None:
     code = getattr(exc, "status_code", None)
     if code is None:
@@ -183,30 +234,6 @@ def detect_auth_error(exc: BaseException, *, provider: str, key_tail: str) -> LL
     )
 
 
-def _is_quota_exhausted(exc: BaseException) -> bool:
-    status = _status_code(exc)
-    quota_code = getattr(exc, "code", None) == "insufficient_quota" or "insufficient_quota" in str(exc)
-    return status == 402 or (status == 429 and quota_code)
-
-
-def llm_failure_properties(exc: BaseException) -> dict:
-    """``$exception`` properties for a failed LLM call, telling an exhausted quota or an oversized prompt
-    apart from other failures.
-
-    Why: the hosted proxy's paywall is a 402, and OpenAI reports an empty balance as a 429 ``insufficient_quota``.
-    An oversized prompt is ours to fix, not the provider's, so it gets its own type on the dashboard.
-    """
-    quota = _is_quota_exhausted(exc)
-    context = isinstance(exc, ScopeContextTooLargeError) or any(p.search(str(exc)) for p in _CONTEXT_OVERFLOW_PATTERNS)
-    provider, _key_tail = current_provider_key_context()
-    return {
-        "error_type": "quota" if quota else "context" if context else "llm",
-        "error_provider": provider,
-        "error_status_code": _status_code(exc),
-        "error_message": str(exc)[:500],
-    }
-
-
 def is_transient_llm_error(exc: BaseException) -> bool:
     """Whether the same request may succeed if sent again: throttled, a server error, or no answer at all.
 
@@ -216,7 +243,7 @@ def is_transient_llm_error(exc: BaseException) -> bool:
     """
     status = _status_code(exc)
     if status is not None:
-        return status in (408, 429) and not _is_quota_exhausted(exc) or status >= 500
+        return status in (408, 429) and not is_quota_exhausted(exc) or status >= 500
     return any(cls.__name__ in _TRANSIENT_TYPE_NAMES for cls in type(exc).__mro__)
 
 

{codeboarding-0.15.1 → codeboarding-0.15.3}/agents/tree_planner_agent.py

@@ -16,7 +16,7 @@ from langchain_core.prompts import PromptTemplate
 from agents.agent_responses import PlannedGroup, TreePlanInsights
 from agents.llm_config import get_current_prompt_profile, supports_json_mode
 from infra.monitoring.callbacks import MONITORING_CALLBACK
-from agents.llm_errors import LLMAuthError, raise_if_auth_error
+from agents.llm_errors import LLMAuthError, LLMQuotaError, is_quota_exhausted, raise_if_auth_error
 from agents.prompts import get_tree_plan_prompts
 from agents.retry import LLM_MAX_ATTEMPTS, RetryAction, RetryDecision, classify_llm_error, with_retries
 from infra.monitoring import trace
@@ -103,7 +103,7 @@ class TreePlannerAgent(MonitoringMixin):
         return folded
 
     def _draw(self, prompt: str, labelled: dict[str, CandidateGroup]) -> list[TreePlanInsights]:
-        """``draws`` answers to one prompt, drawn concurrently; a draw that fails is dropped."""
+        """Draw concurrently, dropping failed draws unless credentials or quota prevent further work."""
         # Not ``with``: its ``__exit__`` waits for a stalled draw; a copied context carries the
         # monitoring step into each worker.
         pool = ThreadPoolExecutor(max_workers=self.draws)
@@ -117,6 +117,8 @@ class TreePlannerAgent(MonitoringMixin):
                 except LLMAuthError:
                     raise
                 except Exception as exc:
+                    if is_quota_exhausted(exc):
+                        raise LLMQuotaError(exc) from exc
                     failures.append(exc)
                     logger.warning("[Planner] draw failed: %s", exc)
         finally:

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.1
+Version: 0.15.3
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -112,7 +112,7 @@ pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 
 > Installing into the global Python environment with `pip` is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.
 
-Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):
+Each analysis downloads the language servers its repository's languages need, on first use. To pre-install all of them (useful in CI or restricted environments):
 
 ```bash
 codeboarding-setup

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding.egg-info/SOURCES.txt

@@ -187,6 +187,7 @@ static_analyzer/lsp_client/__init__.py
 static_analyzer/lsp_client/diagnostics.py
 static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/index.js
 static_analyzer/typescript_plugin/node_modules/codeboarding-workspace-sources/package.json
+tests/test_devcontainer.py
 tests/test_persisted_analysis_artifacts.py
 tests/test_pyproject_packages.py
 tests/test_view_instructions.py

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding_cli/bootstrap.py

@@ -5,7 +5,7 @@ from pathlib import Path
 from agents.llm_config import configure_models, validate_api_key_provided
 from health.plugins import get_registries, load_plugins
 from diagram_analysis.run_context import RunPaths
-from infra.install import ensure_tools
+from infra.install import enable_on_demand_install, ensure_tools
 from infra.logging_config import setup_logging
 from infra.user_config import ensure_config_template, load_user_config
 from infra.utils import CODEBOARDING_DIR_NAME
@@ -41,4 +41,6 @@ def bootstrap_environment(output_dir: Path, binary_location: Path | None) -> Non
         # repairs a deleted ~/.codeboarding/servers/nodeenv/ independently of the
         # fingerprint check. Pre-gating with needs_install() here would skip that
         # repair when binaries look current but the runtime directory was deleted.
-        ensure_tools(auto_install_npm=True, auto_install_vcpp=True)
+        # Only the base tools here: the analysis installs its languages' servers once it has found them.
+        ensure_tools(auto_install_npm=True, auto_install_vcpp=True, languages=())
+        enable_on_demand_install(auto_install_npm=True, auto_install_vcpp=True)

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding_cli/commands/full_analysis.py

@@ -5,7 +5,8 @@ from pathlib import Path
 from tqdm import tqdm
 
 from agents.llm_config import LLMConfigError
-from agents.llm_errors import LLMAuthError
+from agents.llm_errors import LLMAuthError, LLMQuotaError
+from diagram_analysis.exceptions import ScopeSemanticsError
 from codeboarding_cli.bootstrap import bootstrap_environment, resolve_local_run_paths
 from codeboarding_cli.view_instructions import print_view_instructions
 from codeboarding_workflows.analysis import run_full
@@ -13,7 +14,6 @@ from codeboarding_workflows.orchestration import run_analysis_pipeline
 from codeboarding_workflows.sources import SourceContext, local_source, remote_source
 from infra.constants import CLI_ROOT_DOCUMENT_NAME
 from diagram_analysis import DEFAULT_DEPTH_CAP, RunContext, RunPaths
-from diagram_analysis.exceptions import ScopeSemanticsError
 from infra.monitoring import monitor_execution
 from infra.monitoring.paths import get_monitoring_run_dir
 from output_generators.rendering import render_docs
@@ -161,7 +161,7 @@ def _run_remote(args: argparse.Namespace) -> None:
                 upload=args.upload,
                 should_monitor=should_monitor,
             )
-        except (LLMAuthError, ScopeSemanticsError):
+        except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
             # The next repository would fail the same way, so stop the run.
             raise
         except Exception:

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding_cli/commands/incremental_analysis.py

@@ -5,12 +5,12 @@ import sys
 from typing import Any
 
 from agents.llm_config import LLMConfigError
-from agents.llm_errors import LLMAuthError
+from agents.llm_errors import LLMAuthError, LLMQuotaError
+from diagram_analysis.exceptions import ScopeSemanticsError
 from codeboarding_cli.bootstrap import bootstrap_environment, resolve_local_run_paths
 from codeboarding_cli.view_instructions import print_view_instructions
 from codeboarding_workflows.analysis import BaselineUnavailableError, run_incremental
 from diagram_analysis import RunContext
-from diagram_analysis.exceptions import ScopeSemanticsError
 from diagram_analysis.run_mode import RunMode
 from infra.utils import monitoring_enabled
 
@@ -61,7 +61,7 @@ def run_from_args(args: argparse.Namespace, parser: argparse.ArgumentParser) ->
         # to prompt for a full run; no stack trace needed.
         logger.info("Incremental unavailable: %s", exc)
         _emit_error(str(exc))
-    except (LLMAuthError, ScopeSemanticsError):
+    except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
         # A full run would fail the same way, so don't ask for one.
         raise
     except Exception as exc:

{codeboarding-0.15.1 → codeboarding-0.15.3}/codeboarding_cli/main.py

@@ -1,18 +1,20 @@
 import argparse
+import logging
 import os
 import sys
-import traceback
 from pathlib import Path
 
 from agents.llm_config import CODEBOARDING_KEY_TAIL
-from agents.llm_errors import EXIT_AUTH_ERROR, EXIT_QUOTA_EXHAUSTED, LLMAuthError
+from agents.llm_errors import EXIT_AUTH_ERROR, EXIT_QUOTA_EXHAUSTED, LLMAuthError, LLMQuotaError
 from codeboarding_cli.bootstrap import resolve_local_run_paths
 from codeboarding_cli.commands import full_analysis, incremental_analysis, partial_analysis
-from diagram_analysis.exceptions import ScopeSemanticsError
 from output_generators import SUPPORTED_FORMATS, render as render_output
 from infra.utils import ANALYSIS_FILENAME
 
 _SUBCOMMANDS = {"full", "incremental", "partial"}
+# CodeBoarding-action/scripts/analyze_repository.py parses this prefix; keep it stable.
+_ERROR_PREFIX = "CodeBoarding: "
+logger = logging.getLogger(__name__)
 
 
 def _build_shared_parser() -> argparse.ArgumentParser:
@@ -108,22 +110,15 @@ def _dispatch(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None
                     output_dir=run_paths.output_dir,
                 )
     except LLMAuthError as exc:
-        # A rejected API key is the user's to fix, not a crash: print one
-        # actionable line (no traceback) and exit with a distinct code.
-        print(f"\nCodeBoarding: {exc}", file=sys.stderr)
+        logger.error("%s%s", _ERROR_PREFIX, exc)
         if exc.key_tail != CODEBOARDING_KEY_TAIL:
-            print(
+            logger.error(
                 "Check your LLM provider API key (shell env or ~/.codeboarding/config.toml) and re-run.",
-                file=sys.stderr,
             )
         raise SystemExit(EXIT_AUTH_ERROR) from exc
-    except ScopeSemanticsError as exc:
-        if exc.telemetry_properties.get("error_type") != "quota":
-            raise
-        # Same exit as any failure, but with a code callers (the GitHub Action) can name.
-        traceback.print_exception(exc)
-        print("\nCodeBoarding: the LLM provider's token or credit quota is exhausted.", file=sys.stderr)
-        print("Add credits or raise the quota for this provider, then re-run.", file=sys.stderr)
+    except LLMQuotaError as exc:
+        logger.exception("LLM quota failure")
+        logger.error("%s%s", _ERROR_PREFIX, exc)
         raise SystemExit(EXIT_QUOTA_EXHAUSTED) from exc
 
 

{codeboarding-0.15.1 → codeboarding-0.15.3}/diagram_analysis/diagram_generator.py

@@ -30,7 +30,7 @@ from diagram_analysis.incremental_update import (
 from agents.incremental_results import RecursiveScopeUpdateResult
 from agents.file_index_models import FileEntry, FileMethodGroup, MethodEntry
 from agents.llm_config import initialize_agent_llm
-from agents.llm_errors import LLMAuthError, llm_failure_properties
+from agents.llm_errors import LLMAuthError, LLMQuotaError, is_quota_exhausted, llm_failure_properties
 from agents.relation_edges import (
     drop_misattributed_edges,
     index_relation_endpoints,
@@ -818,9 +818,11 @@ class DiagramGenerator:
                 incremental,
                 enclosing_names=enclosing_names,
             )
-        except LLMAuthError:
+        except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
             raise
         except Exception as error:
+            if is_quota_exhausted(error):
+                raise LLMQuotaError(error) from error
             raise ScopeSemanticsError(scope.scope_id, telemetry_properties=llm_failure_properties(error)) from error
         if semantics is None:
             with self._naming_counts_lock:
@@ -1120,7 +1122,7 @@ class DiagramGenerator:
             new_components = [child for child in analysis.components if child.component_id in preclustered_scopes]
 
             return component.component_id, analysis, new_components
-        except (LLMAuthError, ScopeSemanticsError):
+        except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
             # An LLM failure aborts the whole run rather than shipping this component with deterministic names.
             raise
         except Exception:
@@ -1335,7 +1337,7 @@ class DiagramGenerator:
                     stats["completed"] += 1
                     try:
                         outcomes.append((component, level, future.result()))
-                    except (LLMAuthError, ScopeSemanticsError):
+                    except (LLMAuthError, LLMQuotaError, ScopeSemanticsError):
                         for pending in future_to_task:
                             pending.cancel()
                         raise