codeboarding 0.14.2__tar.gz → 0.14.5__tar.gz

{codeboarding-0.14.2/codeboarding.egg-info → codeboarding-0.14.5}/PKG-INFO

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

codeboarding-0.14.5/README.md

@@ -0,0 +1,282 @@
+# CodeBoarding
+
+**Review the change, not the diff.**
+
+See what a pull request does to your system before you merge it. CodeBoarding turns code into interactive architecture maps so you can explore components, follow their dependencies, and review analyzed pull requests alongside code diffs.
+
+This repository contains the open-source analysis engine and CLI. Static analysis extracts code relationships; language models help name and describe the components. Use the resulting map in the web platform, your editor, CI, or generated documentation.
+
+[Discord](https://discord.gg/T5zHTJYFuy) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img alt="" referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img alt="" referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" /> · [Web platform](https://app.codeboarding.org) · [Website](https://codeboarding.org) <img alt="" referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" /> · [Getting started](https://codeboarding.org/getting-started)
+
+[![Website animation: a pull-request diff becomes a six-component system map, revealing a new dependency from Payments to Identity.](docs/images/codeboarding-story.gif)](https://codeboarding.org)
+
+*The website's illustrative animation (plays once, about 18 seconds). [View the static map](docs/images/codeboarding-story-static.png) or [replay the interactive story on the website](https://codeboarding.org).*
+
+The example starts with a large pull-request diff, then shows the six components it touches. Identity and Payments have changed: a new dependency means a Google sign-in outage can block card payments.
+
+[![JavaScript](https://img.shields.io/badge/JavaScript-222222?style=flat-square&logo=javascript&logoColor=F7DF1E)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Java](https://img.shields.io/badge/Java-E76F00?style=flat-square&logo=openjdk&logoColor=white)](https://www.java.com/)
+[![Python](https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
+[![Go](https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white)](https://go.dev/)
+[![PHP](https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white)](https://www.php.net/)
+[![Rust](https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white)](https://www.rust-lang.org/)
+[![C#](https://custom-icon-badges.demolab.com/badge/C%23-512BD4.svg?style=flat-square&logo=cshrp&logoColor=white)](https://learn.microsoft.com/en-us/dotnet/csharp/)
+
+## Explore the system. Review the change
+
+- **Explore:** start with the architecture map, expand components, and navigate to the source behind them. Open prepared public repositories without signing in.
+- **Review:** see changed components and dependencies, read changes grouped by component, and inspect code diffs. PR review requires an available analysis from the GitHub Action; architecture comparisons also need a baseline.
+- **Bring your own analysis:** open an `analysis.json` or compare two local analysis files. Files are parsed and compared in your browser.
+- **Share context:** use component descriptions and diagrams in documentation, reviews, and your coding agent's next prompt.
+
+## What CodeBoarding generates
+
+- An `analysis.json` containing the architecture, component descriptions, relationships, and source references.
+- Nested component diagrams for exploring subsystems.
+- Markdown with Mermaid diagrams, HTML, MDX, or reStructuredText documentation when you request rendering.
+- Incremental updates against a previous analysis, or updates to a selected component.
+
+## How it works
+
+1. **Analyze the code.** The engine scans the repository and extracts symbols and relationships with static analysis.
+2. **Build the map.** It groups code into components and uses your configured model provider to describe their responsibilities. Analysis can send code excerpts to that provider.
+3. **Explore or review.** Load the analysis in the web platform or editor, render it as documentation, or use the GitHub Action to publish architecture changes on pull requests.
+
+The engine's top-level architecture, generated from the [committed analysis](https://github.com/CodeBoarding/CodeBoarding/blob/58291a48b2a609f68e0d19dccd0f3a605907ed28/.codeboarding/analysis.json) dated September 21, 2026:
+
+```mermaid
+graph LR
+    Static_Analysis_Engine["Static Analysis Engine"]
+    Diagram_Generation_and_Health_Orchestration["Diagram Generation and Health Orchestration"]
+    LLM_Planning_and_Analysis_Agents["LLM Planning and Analysis Agents"]
+    CLI_Workflows_and_Output_Generators["CLI, Workflows, and Output Generators"]
+    Repository_and_File_Utilities["Repository and File Utilities"]
+    Application_Entry_Points_and_Runtime_Configuration["Application Entry Points and Runtime Configuration"]
+    Execution_Monitoring_and_Metrics["Execution Monitoring and Metrics"]
+    Tool_Registry_and_Environment_Installer["Tool Registry and Environment Installer"]
+    Static_Analysis_Engine -- "tracks telemetry events" --> Diagram_Generation_and_Health_Orchestration
+    Static_Analysis_Engine -- "checks repository ignores and git changes" --> Repository_and_File_Utilities
+    Static_Analysis_Engine -- "locates tool binaries and runtime directories" --> Tool_Registry_and_Environment_Installer
+    Static_Analysis_Engine -- "builds agent insight models" --> LLM_Planning_and_Analysis_Agents
+    Static_Analysis_Engine -- "formats cluster identifiers" --> Application_Entry_Points_and_Runtime_Configuration
+    Diagram_Generation_and_Health_Orchestration -- "queries static analysis graphs and specs" --> Static_Analysis_Engine
+    Diagram_Generation_and_Health_Orchestration -- "configures LLMs and models file index entries" --> LLM_Planning_and_Analysis_Agents
+    Diagram_Generation_and_Health_Orchestration -- "normalizes paths and checks git changes" --> Repository_and_File_Utilities
+    Diagram_Generation_and_Health_Orchestration -- "resolves cluster hierarchy and ordering" --> Application_Entry_Points_and_Runtime_Configuration
+    Diagram_Generation_and_Health_Orchestration -- "initializes stats writers and logs runs" --> Execution_Monitoring_and_Metrics
+    Diagram_Generation_and_Health_Orchestration -- "executes plugin health checks" --> CLI_Workflows_and_Output_Generators
+    LLM_Planning_and_Analysis_Agents -- "reads call graph edges and nodes" --> Static_Analysis_Engine
+    LLM_Planning_and_Analysis_Agents -- "filters repository files and normalizes paths" --> Repository_and_File_Utilities
+    LLM_Planning_and_Analysis_Agents -- "checks cluster hierarchy and loads user configuration" --> Application_Entry_Points_and_Runtime_Configuration
+    LLM_Planning_and_Analysis_Agents -- "attaches monitoring callbacks and mixins" --> Execution_Monitoring_and_Metrics
+    CLI_Workflows_and_Output_Generators -- "resolves execution context and loads analysis metadata" --> Diagram_Generation_and_Health_Orchestration
+    CLI_Workflows_and_Output_Generators -- "initializes LLM credentials and computes source hashes" --> LLM_Planning_and_Analysis_Agents
+    CLI_Workflows_and_Output_Generators -- "manages ignore files and repository git operations" --> Repository_and_File_Utilities
+    CLI_Workflows_and_Output_Generators -- "loads user configuration and sets up logging" --> Application_Entry_Points_and_Runtime_Configuration
+    CLI_Workflows_and_Output_Generators -- "wraps workflow execution in monitoring context" --> Execution_Monitoring_and_Metrics
+    CLI_Workflows_and_Output_Generators -- "ensures required tool binaries are installed" --> Tool_Registry_and_Environment_Installer
+    CLI_Workflows_and_Output_Generators -- "retrieves node type definitions for output rendering" --> Static_Analysis_Engine
+    Repository_and_File_Utilities -- "builds tool configurations from manifest" --> Tool_Registry_and_Environment_Installer
+    Repository_and_File_Utilities -- "reads fingerprint data for change detection" --> Diagram_Generation_and_Health_Orchestration
+    Repository_and_File_Utilities -- "hashes repository source files for fingerprint comparison" --> LLM_Planning_and_Analysis_Agents
+    Application_Entry_Points_and_Runtime_Configuration -- "loads analysis metadata and resolves run context" --> Diagram_Generation_and_Health_Orchestration
+    Application_Entry_Points_and_Runtime_Configuration -- "triggers incremental analysis and renders documentation formats" --> CLI_Workflows_and_Output_Generators
+    Application_Entry_Points_and_Runtime_Configuration -- "clones and checks out repositories in temporary folders" --> Repository_and_File_Utilities
+    Execution_Monitoring_and_Metrics -- "resolves project root directory for monitoring storage" --> Repository_and_File_Utilities
+    Tool_Registry_and_Environment_Installer -- "inspects language definitions and runtime environments" --> Static_Analysis_Engine
+    Tool_Registry_and_Environment_Installer -- "locates executable runnables and initializes configuration templates" --> Application_Entry_Points_and_Runtime_Configuration
+```
+
+For the engine's own architecture, [open its interactive map](https://app.codeboarding.org/CodeBoarding/CodeBoarding).
+
+## Quick start
+
+To try the product without installing anything, [open a public map](https://app.codeboarding.org/CodeBoarding/CodeBoarding). To connect your own repositories, [sign in to the web platform](https://app.codeboarding.org) and choose which repositories CodeBoarding can access. See the [getting-started guide](https://codeboarding.org/getting-started) for the GitHub and editor workflows.
+
+To run the analysis engine yourself, use either option below. Both require **Python 3.12** and a [configured model provider](#configuration).
+
+### Run from source
+
+```bash
+git clone https://github.com/CodeBoarding/CodeBoarding.git
+cd CodeBoarding
+uv sync --frozen
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python install.py
+python main.py full --local /path/to/repo
+```
+
+### Use the packaged CLI
+
+The recommended install method is [pipx](https://pipx.pypa.io), which keeps the CLI in its own isolated environment:
+
+```bash
+pipx install codeboarding --python python3.12
+codeboarding-setup
+codeboarding full --local /path/to/repo
+```
+
+Or, if you prefer pip, install into a virtual environment (not the global Python):
+
+```bash
+pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
+codeboarding-setup
+codeboarding full --local /path/to/repo
+```
+
+Output is written to `/path/to/repo/.codeboarding/`. To explore it interactively, open the
+[web platform](https://app.codeboarding.org) and load the generated `analysis.json` through
+the viewer's **Switch source** → **File** picker.
+Local analysis files are parsed and compared in your browser; this is separate from generating
+the analysis with your configured model provider.
+
+To also generate `overview` and one file per expanded component, pass `--render` with one of
+`md`, `html`, `mdx`, or `rst`. Rendering is available after full, incremental, and partial local analyses;
+previously generated files for the selected format are reconciled from a renderer-owned manifest:
+
+```bash
+codeboarding full --local /path/to/repo --render md
+codeboarding incremental --local /path/to/repo --render html
+codeboarding partial --local /path/to/repo --component-id "1.2" --render rst
+```
+
+You can render an existing analysis without rerunning analysis or configuring an LLM:
+
+```bash
+codeboarding-render /path/to/repo/.codeboarding/analysis.json
+# Select a format or output directory:
+codeboarding-render /path/to/analysis.json --format mdx --output-dir /path/to/docs
+
+# From a source checkout in development:
+python codeboarding_cli/render.py ../../demo/markitdown/.codeboarding/analysis.json --format md
+```
+
+`python install.py` 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.
+
+## Configuration
+
+On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provider there or use environment variables.
+
+```toml
+[provider]
+# openai_api_key            = "sk-..."
+# openai_base_url           = "https://api.example.com/v1"  # any OpenAI-compatible gateway
+# anthropic_api_key         = "sk-ant-..."
+# anthropic_base_url        = "https://resource.services.ai.azure.com/anthropic"  # Azure Foundry
+# google_api_key            = "AIza..."
+# vercel_api_key            = "vck_..."
+# aws_bearer_token_bedrock  = "..."
+# ollama_base_url           = "http://localhost:11434"
+# 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)
+# litellm_base_url          = "http://localhost:4000"  # LiteLLM proxy server URL (required)
+# litellm_api_key           = "sk-..."           # LiteLLM proxy server key (optional)
+
+[llm]
+# agent_model = "gemini-3.8-flash"
+```
+
+`openai_base_url` points CodeBoarding at any OpenAI-compatible gateway, including LM Studio. Set its model ID with `agent_model`; CodeBoarding adapts its prompts for the model families already represented by its provider defaults, including Qwen. The equivalent shell variables are `OPENAI_BASE_URL`, `OPENAI_API_KEY`, and `AGENT_MODEL`.
+
+`anthropic_base_url` points the Anthropic client at a compatible Messages API, including Azure Foundry Claude deployments. Set the deployment key as `anthropic_api_key` and use canonical Anthropic model IDs such as `claude-sonnet-5` for `agent_model` so CodeBoarding selects the correct model capabilities and prompts.
+
+Shell environment variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, and `OLLAMA_BASE_URL` take precedence over the config file. For private repositories, set `GITHUB_TOKEN` in your environment.
+
+Two environment variables tune the static analysis itself:
+
+| Variable | Effect |
+| --- | --- |
+| `CODEBOARDING_LSP_REQUEST_TIMEOUT` | Seconds a language-server request may block *when it uses the per-language default* (120s for C#, 60s elsewhere). Not a hard cap on every request: the indexing and didOpen-drain probes pass their own scaled budget (60s plus 2s per file, capped at 1800s) and are unaffected. Applies to every language in the run. Unset or empty leaves the defaults alone; any other unusable value fails the run rather than falling back. |
+| `CODEBOARDING_MAX_CONCURRENT_ENGINES` | How many language servers may be resident at once. `0` (the default) leaves the bound off. |
+
+## Common commands
+
+```bash
+# Analyze a local repository
+python main.py full --local ./my-project
+
+# Raise the depth ceiling to auto-expand deeper (rarely needed — a component that
+# outgrows the leaf ceiling is flagged expandable at whatever depth the run stops
+# and can be expanded on demand; --depth-cap is a safety-valve cap, default 3)
+python main.py full --local ./my-project --depth-cap 5
+
+# Re-analyze only changed parts when possible
+python main.py incremental --local ./my-project
+
+# Update a single component by ID
+python main.py partial --local ./my-project --component-id "1.2"
+
+# Analyze a remote GitHub repository
+python main.py full https://github.com/pytorch/pytorch
+```
+
+`--depth-cap` configures `metadata.depth_cap`; `metadata.depth_level` records the
+depth actually reached. The cap is a maximum, not a target depth. `--depth-level`
+is rejected; there is no compatibility alias.
+
+Python callers must use `run_full(..., depth_cap=...)`,
+`build_generator(..., depth_cap=...)`, and `DiagramGenerator(..., depth_cap=...)`.
+The generator attribute is `depth_cap` and the exported default is
+`diagram_analysis.DEFAULT_DEPTH_CAP` (3). The GitHub helper uses `DIAGRAM_DEPTH_CAP`
+and rejects `DIAGRAM_DEPTH_LEVEL`. Telemetry reports configured `depth_cap`, not
+`depth_level`. Readers of analysis results must keep reading `metadata.depth_level`
+for the actual depth. Existing baseline loading behavior is unchanged: prefer
+`metadata.depth_cap`, fall back to legacy `metadata.depth_level`, then use
+`DEFAULT_DEPTH_CAP` if neither exists. This metadata fallback is not a CLI alias.
+
+> **Incremental needs a baseline.** `incremental` diffs the working tree against the previous
+> analysis in `.codeboarding/` (`analysis.json` + `fingerprint.json`). That baseline can live
+> purely locally — a prior `full`/`incremental` run in the same output dir is enough. Commit
+> `.codeboarding/` only if you want the baseline to travel with the branch (so a teammate or a
+> fresh checkout can run incremental too). With no baseline at all — or one that predates content
+> versioning — `incremental` fails fast with "run a full analysis first" rather than silently
+> doing a full run. Static-analysis caches are versioned but not migrated; after a cache-version
+> upgrade, run a full analysis once to reindex.
+
+## Where to use it
+
+- **CLI:** [CodeBoarding CLI](#quick-start) — this repository — for local analysis, automation, and documentation generation.
+- **Browser:** [web platform](https://app.codeboarding.org) for Explore and Review, public maps, and local analysis files.
+- **Editor:** [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) or [Open VSX](https://open-vsx.org/extension/CodeBoarding/codeboarding) for in-editor architecture exploration.
+- **CI:** [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) to keep analysis updated and post architecture change maps on pull requests.
+
+## Supported stack
+
+- Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, OrcaRouter, Requesty, LiteLLM proxy, and more.
+
+## Examples
+
+- [Explore CodeBoarding's architecture](https://app.codeboarding.org/CodeBoarding/CodeBoarding) — the engine, drawn from its own code.
+- [Review CodeBoarding pull request #586](https://app.codeboarding.org/CodeBoarding/CodeBoarding/pull/586) — component changes and code diffs together.
+- [Browse example diagrams](https://codeboarding.org/diagrams).
+- [Awesome Architecture MDs](https://github.com/CodeBoarding/awesome-architecture-mds) — generated architecture documentation for open-source repositories (formerly GeneratedOnBoardings).
+
+Public maps need a committed `.codeboarding/analysis.json` at the selected branch or commit.
+Open one at `https://app.codeboarding.org/<owner>/<repo>` without signing in; opening a URL does not generate a new analysis.
+
+## Telemetry
+
+CodeBoarding collects usage telemetry (which command ran, success/failure,
+duration, token cost, repository size and languages, and the account the
+repository belongs to) to help us improve the tool. It is on by default and
+never collects source code, file names, repository names, paths, prompts, model
+outputs, or API keys. Opt out anytime:
+
+```bash
+export CODEBOARDING_TELEMETRY=false   # or: export DO_NOT_TRACK=1
+```
+
+See [TELEMETRY.md](TELEMETRY.md) for the full list of events and properties.
+
+## Contributing
+
+If you want to improve CodeBoarding, open an [issue](https://github.com/CodeBoarding/CodeBoarding/issues) or send a pull request. We welcome improvements to analysis quality, output generators, integrations, and developer experience.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and testing guidance.
+
+## License
+
+The analysis engine and CLI in this repository are released under the [MIT License](LICENSE).

{codeboarding-0.14.2 → codeboarding-0.14.5}/agents/llm_config.py

@@ -294,6 +294,19 @@ LLM_PROVIDERS = {
             "max_retries": 0,
         },
     ),
+    "requesty": LLMConfig(
+        chat_class=ChatOpenAI,
+        selection_envs=["REQUESTY_API_KEY"],
+        api_key_env="REQUESTY_API_KEY",
+        agent_model="gemini-3.8-flash",
+        base_url_env="REQUESTY_BASE_URL",
+        default_base_url="https://router.requesty.ai/v1",
+        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
@@ -463,6 +476,15 @@ def get_current_prompt_profile(llm: BaseChatModel | None = None) -> PromptProfil
     return resolve_prompt_profile(get_current_agent_model_ref())
 
 
+#: What CodeBoarding-action writes as ``OPENROUTER_API_KEY`` for hosted credentials: a placeholder its
+#: local relay swaps for a GitHub OIDC token. Keep in step with the action's ``configure-auth.sh``.
+OIDC_RELAY_PLACEHOLDER_KEY = "github-actions-oidc-relay"
+
+#: ``key_tail`` for a run on hosted credentials: the placeholder's last four characters name no key
+#: the user holds, so an auth error must not ask them to check it.
+CODEBOARDING_KEY_TAIL = "hosted"
+
+
 def current_provider_key_context() -> tuple[str, str]:
     """The selected provider name and a masked key tail, for auth-error messages.
 
@@ -476,6 +498,8 @@ def current_provider_key_context() -> tuple[str, str]:
         return "unknown", "unknown"
     name = selected[0]
     key = LLM_PROVIDERS[name].get_api_key()
+    if key == OIDC_RELAY_PLACEHOLDER_KEY:
+        return name, CODEBOARDING_KEY_TAIL
     key_tail = key[-4:] if key and len(key) >= 4 else "unknown"
     return name, key_tail
 

{codeboarding-0.14.2 → codeboarding-0.14.5}/agents/llm_errors.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 import logging
 import re
 
-from agents.llm_config import current_provider_key_context
+from agents.llm_config import CODEBOARDING_KEY_TAIL, current_provider_key_context
 
 logger = logging.getLogger(__name__)
 
@@ -28,6 +28,9 @@ logger = logging.getLogger(__name__)
 # import it without pulling in Core's whole CLI module.
 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
+
 # Class names, across SDKs, that always mean "credentials were rejected".
 # openai/anthropic/cerebras raise ``AuthenticationError``; google raises
 # ``Unauthenticated``/``PermissionDenied``; Bedrock (botocore) surfaces
@@ -48,6 +51,8 @@ _AUTH_MESSAGE_PATTERNS = (
     re.compile(r"invalid[\s_-]*x?[\s_-]*api[\s_-]*key", re.IGNORECASE),
     re.compile(r"incorrect api key", re.IGNORECASE),
     re.compile(r"api key.*invalid", re.IGNORECASE),
+    # Google: "API key not valid" or reason API_KEY_INVALID.
+    re.compile(r"api[\s_]*key[\s_]*(?:not[\s_]*valid|invalid)", re.IGNORECASE),
     re.compile(r"authentication[\s_]*error", re.IGNORECASE),
     re.compile(r"authentication fails", re.IGNORECASE),
     re.compile(r"\bunauthorized\b", re.IGNORECASE),
@@ -57,6 +62,33 @@ _AUTH_MESSAGE_PATTERNS = (
 )
 
 
+# What each provider says when the prompt is over the model's context window: Google, OpenAI, Anthropic.
+_CONTEXT_OVERFLOW_PATTERNS = (
+    re.compile(r"exceeds the maximum number of tokens", re.IGNORECASE),
+    re.compile(r"maximum context length|context_length_exceeded", re.IGNORECASE),
+    re.compile(r"prompt is too long", re.IGNORECASE),
+)
+
+
+class ScopeContextTooLargeError(RuntimeError):
+    """A scope's context does not fit the model's budget even after every trim.
+
+    Why: sent anyway, the provider rejects it with a 400 worded differently by each provider — and
+    OpenRouter's embeds an upstream 401 that used to be read as a rejected key. Stopping before the
+    call names the real limit.
+    """
+
+    def __init__(self, scope_id: str, needed_tokens: int, allowed_tokens: int):
+        super().__init__(
+            f"Scope {scope_id!r} needs about {needed_tokens:,} tokens of context after trimming, over the "
+            f"{allowed_tokens:,} this model allows a scope. Use a model with a larger context window, or "
+            "narrow the analysis with .codeboardingignore."
+        )
+        self.scope_id = scope_id
+        self.needed_tokens = needed_tokens
+        self.allowed_tokens = allowed_tokens
+
+
 class LLMAuthError(RuntimeError):
     """An LLM provider rejected our credentials (HTTP 401 or equivalent).
 
@@ -88,9 +120,10 @@ def _status_code(exc: BaseException) -> int | None:
 
 
 def _is_auth_failure(exc: BaseException) -> bool:
-    """True when *exc* represents rejected credentials, across providers."""
-    if _status_code(exc) in (401, 403):
-        return True
+    """Detect rejected credentials, preferring the response status over embedded upstream errors."""
+    status = _status_code(exc)
+    if status is not None:
+        return status in (401, 403)
     if type(exc).__name__ in _AUTH_TYPE_NAMES:
         return True
     text = str(exc)
@@ -110,11 +143,16 @@ def detect_auth_error(exc: BaseException, *, provider: str, key_tail: str) -> LL
 
     status = _status_code(exc)
     provider_message = str(exc)
-    friendly = (
-        f"Your {provider} API key was rejected"
-        + (f" (HTTP {status})" if status is not None else "")
-        + f". Verify the key ending in '…{key_tail}' and try again."
-    )
+    status_note = f" (HTTP {status})" if status is not None else ""
+    if key_tail == CODEBOARDING_KEY_TAIL:
+        friendly = (
+            f"CodeBoarding's hosted {provider} credentials were rejected{status_note}. This run used no key of "
+            "yours: check that the workflow grants `id-token: write`, then re-run."
+        )
+    else:
+        friendly = (
+            f"Your {provider} API key was rejected{status_note}. Verify the key ending in '…{key_tail}' and try again."
+        )
     telemetry_properties = {
         "error_type": "auth",
         "error_provider": provider,
@@ -130,6 +168,25 @@ def detect_auth_error(exc: BaseException, *, provider: str, key_tail: str) -> LL
     )
 
 
+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.
+    """
+    status = _status_code(exc)
+    quota = status == 402 or (status == 429 and "insufficient_quota" in str(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,
+        "error_message": str(exc)[:500],
+    }
+
+
 def raise_if_auth_error(exc: Exception) -> None:
     """Raise a typed terminal error when a provider rejected its credentials."""
     provider, key_tail = current_provider_key_context()

{codeboarding-0.14.2 → codeboarding-0.14.5}/agents/llm_renderers/scope.py

@@ -3,21 +3,30 @@
 from __future__ import annotations
 
 import json
+import logging
 from collections import defaultdict
 from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
 
 from agents.agent_responses import AnalysisInsights
+from agents.constants import ModelCapabilities
+from agents.llm_errors import ScopeContextTooLargeError
 from repo_utils.path_utils import normalize_repo_path
 from static_analyzer.cfg.edge import EdgeKind
 from static_analyzer.clustering import ClusterConnectionEdge, ClusterGroup, ClusterScopeResult
 from static_analyzer.node import Node
 
+logger = logging.getLogger(__name__)
+
 #: Example edges per directed group pair; the count is always given, the examples let
 #: a relation's ``key_edges`` cite exact symbols.
 MAX_EXAMPLE_EDGES = 5
 
+#: The reason a file gets when no rule placed it. Most files carry it, so it is left out rather than
+#: repeated: the prompt says a file without a reason is a plain member.
+DEFAULT_GROUPING_REASON = "member of the deterministic group"
+
 
 def render_scope_context(
     scope: ClusterScopeResult,
@@ -28,11 +37,16 @@ def render_scope_context(
     changed_files: set[str] | frozenset[str],
     incremental: bool,
     enclosing_names: Sequence[str] = (),
+    max_tokens: int = ModelCapabilities.FALLBACK_INPUT,
 ) -> str:
     """Return complete group files, boundary candidates, and known calls as JSON.
 
     ``enclosing_names``: the components this scope sits inside, outermost first, so the
     model does not name a child after its parent.
+
+    ``max_tokens``: the most this context may take. Over it, the least load-bearing parts are trimmed
+    in order; if it still does not fit, :class:`ScopeContextTooLargeError` is raised instead of
+    sending a prompt the provider will reject.
     """
     boundary_reasons = _boundary_reasons(scope, repo_dir)
     components = {component.component_id: component for component in analysis.components}
@@ -46,11 +60,9 @@ def render_scope_context(
                 "status": "changed" if group.group_id in editable_group_ids else "unchanged",
                 "name_locked": group.group_id in locked_name_ids,
                 "files": [
-                    {
-                        "path": file_path,
-                        "grouping_reason": reason,
-                        "changed": file_path in changed_files,
-                    }
+                    {"path": file_path}
+                    | ({"grouping_reason": reason} if reason != DEFAULT_GROUPING_REASON else {})
+                    | ({"changed": file_path in changed_files} if incremental else {})
                     for file_path, reason in file_reasons.items()
                 ],
                 "bordering_files": [
@@ -87,7 +99,68 @@ def render_scope_context(
             if relation.src_id and relation.dst_id
         ],
     }
-    return json.dumps(payload, indent=2, sort_keys=True)
+    text = _dump(payload)
+    for trim, what in _TRIMS:
+        if _tokens(text) <= max_tokens:
+            return text
+        logger.warning(
+            "Scope %s context is ~%d tokens, over its %d budget: %s",
+            scope.scope_id,
+            _tokens(text),
+            max_tokens,
+            what,
+        )
+        trim(payload)
+        text = _dump(payload)
+    if _tokens(text) > max_tokens:
+        raise ScopeContextTooLargeError(scope.scope_id, _tokens(text), max_tokens)
+    return text
+
+
+def _dump(payload: dict[str, Any]) -> str:
+    """Why: nobody reads this JSON but the model, and indentation was a third of its size."""
+    return json.dumps(payload, separators=(",", ":"), sort_keys=True)
+
+
+def _tokens(text: str) -> int:
+    return int(len(text) / ModelCapabilities.CHARS_PER_TOKEN)
+
+
+def _drop_bordering_files(payload: dict[str, Any]) -> None:
+    for group in payload["groups"]:
+        references = sorted(
+            {
+                reason
+                for entry in group.pop("bordering_files", [])
+                for reason in entry["reasons"]
+                if " reference " in reason
+            }
+        )
+        if references:
+            group["boundary_references"] = references
+
+
+def _one_example_without_locations(payload: dict[str, Any]) -> None:
+    for connection in payload["known_connections"]:
+        connection["examples"] = [
+            {"source": example["source"], "target": example["target"]} for example in connection["examples"][:1]
+        ]
+
+
+def _files_by_path_only(payload: dict[str, Any]) -> None:
+    for group in payload["groups"]:
+        group["files"] = [
+            {"path": entry["path"], "changed": True} if entry.get("changed") else entry["path"]
+            for entry in group["files"]
+        ]
+
+
+#: Trim optional detail in order, preserving structural references and changed-file markers.
+_TRIMS = (
+    (_drop_bordering_files, "compacting boundary evidence"),
+    (_one_example_without_locations, "keeping one example per connection, without locations"),
+    (_files_by_path_only, "listing files by path only"),
+)
 
 
 def scope_file_paths(scope: ClusterScopeResult, repo_dir: Path) -> frozenset[str]:
@@ -121,7 +194,7 @@ def _group_file_reasons(
         if name in scope.graphs_by_language[language].nodes
     }
     for file_path in files:
-        reasons.setdefault(file_path, "member of the deterministic group")
+        reasons.setdefault(file_path, DEFAULT_GROUPING_REASON)
     return dict(sorted(reasons.items()))
 
 

{codeboarding-0.14.2 → codeboarding-0.14.5}/agents/prompts/shared.py

@@ -31,7 +31,10 @@ SCOPE_ANALYSIS_SYSTEM_MESSAGE = """You name and describe fixed, deterministic co
 The supplied group IDs, file membership, hierarchy, and known directed calls are authoritative. Never merge,
 split, move, add, or remove groups. Work at the supplied scope exactly the same way whether it is root or nested.
 
-Use the supplied files, grouping reasons, bordering files, and known connections before calling tools. A known
+Use the supplied files, grouping reasons, bordering files, and known connections before calling tools. A file
+listed without a `grouping_reason` is a plain member of its group. Compact file lists retain `changed: true`
+on modified files. `boundary_references` summarizes directed structural references between groups when
+per-file boundary details are omitted. A known
 connection gives the number of distinct calls from one group to another and a few of them in full; cite only
 symbols that appear in the input. Never reuse a name listed under `enclosing_components`: those are the
 components this scope sits inside, and a child named after its parent overwrites its document. `readFile`