codeboarding 0.15.1__tar.gz → 0.15.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.1
+Version: 0.15.2
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.15.1 → codeboarding-0.15.2}/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.2}/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.2}/codeboarding.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.15.1
+Version: 0.15.2
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.15.1 → codeboarding-0.15.2}/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.2}/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.2}/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.2}/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

{codeboarding-0.15.1 → codeboarding-0.15.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeboarding"
-version = "0.15.1"
+version = "0.15.2"
 description = "Interactive Diagrams for Code"
 readme = "PYPI.md"
 license = "MIT"