codeboarding 0.10.3__tar.gz → 0.11.0__tar.gz

{codeboarding-0.10.3/codeboarding.egg-info → codeboarding-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.10.3
+Version: 0.11.0
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -24,6 +24,7 @@ Requires-Dist: fastapi>=0.115
 Requires-Dist: filelock>=3.12
 Requires-Dist: gitpython>=3.1
 Requires-Dist: google-api-core>=2.10
+Requires-Dist: jsonpatch>=1.33
 Requires-Dist: jsonschema>=4.25
 Requires-Dist: langchain>=1.2
 Requires-Dist: langchain-anthropic>=1.3
@@ -42,6 +43,15 @@ Requires-Dist: pathspec>=0.12
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11
 Requires-Dist: rich>=12.6
+Requires-Dist: tree-sitter>=0.23
+Requires-Dist: tree-sitter-c-sharp>=0.23
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: tree-sitter-java>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-php>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-rust>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
 Requires-Dist: trustcall>=0.0.39
 Requires-Dist: uvicorn>=0.23
 Provides-Extra: dev
@@ -110,10 +120,10 @@ codeboarding-setup
 
 ```bash
 # Analyze a local repository (output goes to /path/to/repo/.codeboarding/)
-codeboarding --local /path/to/repo
+codeboarding full --local /path/to/repo
 
 # Analyze a remote GitHub repository (cloned to cwd/repo_name/, output to cwd/repo_name/.codeboarding/)
-codeboarding https://github.com/user/repo
+codeboarding full https://github.com/user/repo
 ```
 
 ### Python API
@@ -188,19 +198,21 @@ Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always
 ## CLI Reference
 
 ```
-codeboarding [REPO_URL ...]           # remote: clone + analyze
-codeboarding --local PATH             # local: analyze in-place
+codeboarding full [REPO_URL ...]           # remote: clone + analyze
+codeboarding full --local PATH             # local: analyze in-place
+codeboarding incremental --local PATH      # re-analyze only changed parts
+codeboarding partial --local PATH --component-id ID   # update one component
 ```
 
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
 | `--depth-level INT` | Diagram depth (default: 1) |
-| `--incremental` | Smart incremental update (only re-analyze changed files) |
-| `--full` | Force full reanalysis, skip incremental detection |
-| `--partial-component-id ID` | Update a single component by its ID |
+| `--force` | (full only) Force full reanalysis, skip cached static analysis |
+| `--base-ref REF` / `--target-ref REF` | (incremental only) Git refs to diff |
+| `--component-id ID` | (partial only) ID of the component to update |
 | `--binary-location PATH` | Custom path to language server binaries (overrides `~/.codeboarding/servers/`) |
-| `--upload` | Upload results to GeneratedOnBoardings repo (remote only) |
+| `--upload` | (full, remote only) Upload results to GeneratedOnBoardings repo |
 | `--enable-monitoring` | Enable run monitoring |
 
 ---

{codeboarding-0.10.3 → codeboarding-0.11.0}/PYPI.md

@@ -50,10 +50,10 @@ codeboarding-setup
 
 ```bash
 # Analyze a local repository (output goes to /path/to/repo/.codeboarding/)
-codeboarding --local /path/to/repo
+codeboarding full --local /path/to/repo
 
 # Analyze a remote GitHub repository (cloned to cwd/repo_name/, output to cwd/repo_name/.codeboarding/)
-codeboarding https://github.com/user/repo
+codeboarding full https://github.com/user/repo
 ```
 
 ### Python API
@@ -128,19 +128,21 @@ Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always
 ## CLI Reference
 
 ```
-codeboarding [REPO_URL ...]           # remote: clone + analyze
-codeboarding --local PATH             # local: analyze in-place
+codeboarding full [REPO_URL ...]           # remote: clone + analyze
+codeboarding full --local PATH             # local: analyze in-place
+codeboarding incremental --local PATH      # re-analyze only changed parts
+codeboarding partial --local PATH --component-id ID   # update one component
 ```
 
 | Option | Description |
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
 | `--depth-level INT` | Diagram depth (default: 1) |
-| `--incremental` | Smart incremental update (only re-analyze changed files) |
-| `--full` | Force full reanalysis, skip incremental detection |
-| `--partial-component-id ID` | Update a single component by its ID |
+| `--force` | (full only) Force full reanalysis, skip cached static analysis |
+| `--base-ref REF` / `--target-ref REF` | (incremental only) Git refs to diff |
+| `--component-id ID` | (partial only) ID of the component to update |
 | `--binary-location PATH` | Custom path to language server binaries (overrides `~/.codeboarding/servers/`) |
-| `--upload` | Upload results to GeneratedOnBoardings repo (remote only) |
+| `--upload` | (full, remote only) Upload results to GeneratedOnBoardings repo |
 | `--enable-monitoring` | Enable run monitoring |
 
 ---

{codeboarding-0.10.3 → codeboarding-0.11.0}/README.md

@@ -70,7 +70,7 @@ For a deeper architecture walkthrough, see [`.codeboarding/overview.md`](.codebo
 uv sync --frozen
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 python install.py
-python main.py --local /path/to/repo
+python main.py full --local /path/to/repo
 ```
 
 ### Use the packaged CLI
@@ -80,7 +80,7 @@ Requires **Python 3.12 or 3.13**. The recommended install method is [pipx](https
 ```bash
 pipx install codeboarding --python python3.12
 codeboarding-setup
-codeboarding --local /path/to/repo
+codeboarding full --local /path/to/repo
 ```
 
 Or, if you prefer pip, install into a virtual environment (not the global Python):
@@ -88,7 +88,7 @@ Or, if you prefer pip, install into a virtual environment (not the global Python
 ```bash
 pip install codeboarding
 codeboarding-setup
-codeboarding --local /path/to/repo
+codeboarding full --local /path/to/repo
 ```
 
 Output is written to `/path/to/repo/.codeboarding/`.
@@ -120,19 +120,19 @@ Shell environment variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOG
 
 ```bash
 # Analyze a local repository
-python main.py --local ./my-project
+python main.py full --local ./my-project
 
 # Increase diagram depth
-python main.py --local ./my-project --depth-level 2
+python main.py full --local ./my-project --depth-level 2
 
 # Re-analyze only changed parts when possible
-python main.py --local ./my-project --incremental
+python main.py incremental --local ./my-project
 
 # Update a single component by ID
-python main.py --local ./my-project --partial-component-id "1.2"
+python main.py partial --local ./my-project --component-id "1.2"
 
 # Analyze a remote GitHub repository
-python main.py https://github.com/pytorch/pytorch
+python main.py full https://github.com/pytorch/pytorch
 ```
 
 ## Where to use it

{codeboarding-0.10.3 → codeboarding-0.11.0}/agents/abstraction_agent.py

@@ -70,8 +70,20 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         programming_langs = self.static_analysis.get_languages()
 
-        # Build cluster string using the pre-computed cluster results
-        cluster_str = self._build_cluster_string(programming_langs, cluster_results)
+        # Measure everything that wraps cfg_clusters (system message + rendered
+        # template with an empty slot) so the skip planner can back it out of
+        # the input window before budgeting the cluster string.
+        overhead_chars = len(str(self.system_message.content)) + len(
+            self.prompts["group_clusters"].format(
+                project_name=self.project_name,
+                cfg_clusters="",
+                meta_context=meta_context_str,
+                project_type=project_type,
+            )
+        )
+        cluster_str = self._build_cluster_string(
+            programming_langs, cluster_results, prompt_overhead_chars=overhead_chars
+        )
 
         prompt = self.prompts["group_clusters"].format(
             project_name=self.project_name,

{codeboarding-0.10.3 → codeboarding-0.11.0}/agents/agent.py

@@ -1,6 +1,5 @@
 import json
 import logging
-import time
 from pathlib import Path
 
 from google.api_core.exceptions import ResourceExhausted
@@ -15,6 +14,7 @@ from pydantic import ValidationError
 from trustcall import create_extractor
 
 from agents.prompts import get_validation_feedback_message
+from agents.retry import RetryAction, RetryDecision, default_backoff, with_retries
 from agents.tools.base import RepoContext
 from agents.tools.toolkit import CodeBoardingToolkit
 from agents.validation import ValidationResult, score_validation_results, VALIDATOR_WEIGHTS, DEFAULT_VALIDATOR_WEIGHT
@@ -96,86 +96,69 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
     def _invoke(self, prompt, callbacks: list | None = None) -> str:
         """Unified agent invocation method with timeout and exponential backoff.
 
-        Uses exponential backoff based on total attempts, with different multipliers
-        for different error types. This ensures backoff increases appropriately even
-        when errors alternate between types.
+        Classification applied per exception:
+        - ``TimeoutError``: backoff ``min(10·2^n, 120)``, raise on exhaustion.
+        - ``ResourceExhausted``: backoff ``min(30·2^n, 300)``, raise on exhaustion.
+        - ``status_code == 404``: raise immediately (retired model ID, etc.).
+        - Other exceptions: backoff ``min(10·2^n, 120)``, return fallback string
+          on exhaustion (non-raising — callers treat the fallback as a failed run).
         """
-        max_retries = 5
-
-        for attempt in range(max_retries):
+        max_attempts = 5
+        # Counter captured by the closure so we can vary the per-attempt timeout
+        # without reaching into the retry helper.
+        attempt_counter = [0]
+
+        def call_once() -> str:
+            attempt = attempt_counter[0]
+            attempt_counter[0] += 1
             timeout_seconds = 300 if attempt == 0 else 600
-            try:
-                callback_list = callbacks or []
-                # Always append monitoring callback - logging config controls output
-                callback_list.append(MONITORING_CALLBACK)
-                callback_list.append(self.agent_monitoring_callback)
-
-                logger.info(
-                    f"Starting agent.invoke() [attempt {attempt + 1}/{max_retries}] with prompt length: {len(prompt)}, timeout: {timeout_seconds}s"
-                )
-
-                response = self._invoke_with_timeout(
-                    timeout_seconds=timeout_seconds, callback_list=callback_list, prompt=prompt
-                )
-
-                logger.info(
-                    f"Completed agent.invoke() - message count: {len(response['messages'])}, last message type: {type(response['messages'][-1])}"
+            callback_list = (callbacks or []) + [MONITORING_CALLBACK, self.agent_monitoring_callback]
+            logger.info(
+                f"Starting agent.invoke() [attempt {attempt + 1}/{max_attempts}] with prompt length: {len(prompt)}, timeout: {timeout_seconds}s"
+            )
+            response = self._invoke_with_timeout(
+                timeout_seconds=timeout_seconds, callback_list=callback_list, prompt=prompt
+            )
+            logger.info(
+                f"Completed agent.invoke() - message count: {len(response['messages'])}, last message type: {type(response['messages'][-1])}"
+            )
+            agent_response = response["messages"][-1]
+            assert isinstance(agent_response, AIMessage), f"Expected AIMessage, but got {type(agent_response)}"
+            if isinstance(agent_response.content, str):
+                return agent_response.content
+            if isinstance(agent_response.content, list):
+                return "".join(str(m) if not isinstance(m, str) else m for m in agent_response.content)
+            return ""  # unreachable for AIMessage but satisfies typing
+
+        def classify(exc: Exception, attempt: int) -> RetryDecision:
+            if getattr(exc, "status_code", None) == 404:
+                logger.error(f"Permanent HTTP 404 — not retrying: {type(exc).__name__}: {exc}")
+                return RetryDecision(action=RetryAction.GIVE_UP)
+            if isinstance(exc, ResourceExhausted):
+                return RetryDecision(
+                    action=RetryAction.RETRY,
+                    backoff_s=default_backoff(attempt, initial_s=30.0, multiplier=2.0, max_s=300.0),
                 )
+            # TimeoutError + generic Exception share the same backoff.
+            return RetryDecision(
+                action=RetryAction.RETRY,
+                backoff_s=default_backoff(attempt, initial_s=10.0, multiplier=2.0, max_s=120.0),
+            )
 
-                agent_response = response["messages"][-1]
-                assert isinstance(agent_response, AIMessage), f"Expected AIMessage, but got {type(agent_response)}"
-                if isinstance(agent_response.content, str):
-                    return agent_response.content
-                if isinstance(agent_response.content, list):
-                    return "".join(
-                        [
-                            str(message) if not isinstance(message, str) else message
-                            for message in agent_response.content
-                        ]
-                    )
-
-            except TimeoutError as e:
-                if attempt < max_retries - 1:
-                    # Exponential backoff: 10s * 2^attempt (10s, 20s, 40s, 80s)
-                    delay = min(10 * (2**attempt), 120)
-                    logger.warning(
-                        f"Agent invocation timed out after {timeout_seconds}s, retrying in {delay}s... (attempt {attempt + 1}/{max_retries})"
-                    )
-                    time.sleep(delay)
-                else:
-                    logger.error(f"Agent invocation timed out after {timeout_seconds}s on final attempt")
-                    raise
-
-            except ResourceExhausted as e:
-                if attempt < max_retries - 1:
-                    # Longer backoff for rate limits: 30s * 2^attempt (30s, 60s, 120s, 240s)
-                    delay = min(30 * (2**attempt), 300)
-                    logger.warning(
-                        f"ResourceExhausted (rate limit): {e}\n"
-                        f"Retrying in {delay}s... (attempt {attempt + 1}/{max_retries})"
-                    )
-                    time.sleep(delay)
-                else:
-                    logger.error(f"Max retries ({max_retries}) reached. ResourceExhausted: {e}")
-                    raise
-
-            except Exception as e:
-                # HTTP 404 (e.g. retired model ID) is permanent — retrying won't help.
-                if getattr(e, "status_code", None) == 404:
-                    logger.error(f"Permanent HTTP 404 — not retrying: {type(e).__name__}: {e}")
-                    raise
-
-                # Other errors (network, parsing, etc.) get standard exponential backoff
-                if attempt < max_retries - 1:
-                    delay = min(10 * (2**attempt), 120)
-                    logger.warning(
-                        f"Agent error: {type(e).__name__}: {e}, retrying in {delay}s... (attempt {attempt + 1}/{max_retries})"
-                    )
-                    time.sleep(delay)
-                # On final attempt, fall through to return error message below
-
-        logger.error("Max retries reached. Failed to get response from the agent.")
-        return "Could not get response from the agent."
+        def on_exhausted(exc: Exception) -> str:
+            # Typed exceptions surface the original error; only generic falls through
+            # to the historic fallback string that callers have long relied on.
+            if isinstance(exc, (TimeoutError, ResourceExhausted)):
+                raise exc
+            return "Could not get response from the agent."
+
+        return with_retries(
+            call_once,
+            max_attempts=max_attempts,
+            classify=classify,
+            on_exhausted=on_exhausted,
+            log_prefix="Agent invocation",
+        )
 
     def _invoke_with_timeout(self, timeout_seconds: int, callback_list: list, prompt: str):
         """Invoke agent with a timeout using threading."""
@@ -336,18 +319,27 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         return best_result
 
     def _parse_response(self, prompt, response, return_type, max_retries=5, attempt=0):
-        if attempt >= max_retries:
-            logger.error(f"Max retries ({max_retries}) reached for parsing response: {response}")
-            raise Exception(f"Max retries reached for parsing response: {response}")
-
-        extractor = create_extractor(self.parsing_llm, tools=[return_type], tool_choice=return_type.__name__)
         if response is None or response.strip() == "":
             logger.error(f"Empty response for prompt: {prompt}")
-        try:
-            result = extractor.invoke(
-                return_type.extractor_str() + response,
-                config={"callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback]},
-            )
+
+        def call_once():
+            # Extractor is rebuilt on every attempt — previous trustcall state
+            # may have corrupted attributes (see the tool_call_id bug below).
+            extractor = create_extractor(self.parsing_llm, tools=[return_type], tool_choice=return_type.__name__)
+            try:
+                result = extractor.invoke(
+                    return_type.extractor_str() + response,
+                    config={"callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback]},
+                )
+            except AttributeError as e:
+                # Trustcall bug: https://github.com/hinthornw/trustcall/issues/47
+                # 'ExtractionState' object has no attribute 'tool_call_id' during validation retry.
+                # Treat as a non-retriable fallback to the Pydantic parser.
+                if "tool_call_id" in str(e):
+                    logger.warning(f"Trustcall bug encountered, falling back to Pydantic parser: {e}")
+                    parser = PydanticOutputParser(pydantic_object=return_type)
+                    return self._try_parse(response, parser)
+                raise
             if "responses" in result and len(result["responses"]) != 0:
                 return return_type.model_validate(result["responses"][0])
             if "messages" in result and len(result["messages"]) != 0:
@@ -358,38 +350,36 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
                 return self._try_parse(message, parser)
             parser = PydanticOutputParser(pydantic_object=return_type)
             return self._try_parse(response, parser)
-        except EmptyExtractorMessageError as e:
-            logger.warning(f"{e} (attempt {attempt + 1}/{max_retries})")
-            return self._parse_response(prompt, response, return_type, max_retries, attempt + 1)
-        except AttributeError as e:
-            # Workaround for trustcall bug: https://github.com/hinthornw/trustcall/issues/47
-            # 'ExtractionState' object has no attribute 'tool_call_id' occurs during validation retry
-            if "tool_call_id" in str(e):
-                logger.warning(f"Trustcall bug encountered, falling back to Pydantic parser: {e}")
-                parser = PydanticOutputParser(pydantic_object=return_type)
-                return self._try_parse(response, parser)
-            raise
-        except IndexError as e:
-            # try to parse with the json parser if possible
-            logger.warning(f"IndexError while parsing response (attempt {attempt + 1}/{max_retries}): {e}")
-            return self._parse_response(prompt, response, return_type, max_retries, attempt + 1)
-        except (json.JSONDecodeError, ValueError) as e:
-            logger.warning(f"Parse error (attempt {attempt + 1}/{max_retries}): {e}")
-            return self._parse_response(prompt, response, return_type, max_retries, attempt + 1)
-        except ResourceExhausted as e:
-            # Parsing uses exponential backoff for rate limits
-            if attempt < max_retries - 1:
-                # Exponential backoff: 30s * 2^attempt, capped at 300s
-                delay = min(30 * (2**attempt), 300)
-                logger.warning(
-                    f"ResourceExhausted during parsing (rate limit): {e}\n"
-                    f"Retrying in {delay}s... (attempt {attempt + 1}/{max_retries})"
+
+        def classify(exc: Exception, attempt: int) -> RetryDecision:
+            if isinstance(exc, ResourceExhausted):
+                return RetryDecision(
+                    action=RetryAction.RETRY,
+                    backoff_s=default_backoff(attempt, initial_s=30.0, multiplier=2.0, max_s=300.0),
                 )
-                time.sleep(delay)
-                return self._parse_response(prompt, response, return_type, max_retries, attempt + 1)
-            else:
-                logger.error(f"Resource exhausted on final parsing attempt: {e}")
-                raise
+            if isinstance(exc, (EmptyExtractorMessageError, IndexError, json.JSONDecodeError, ValueError)):
+                return RetryDecision(action=RetryAction.RETRY_NOW)
+            # AttributeError (non-tool_call_id) and any other exception: give up.
+            return RetryDecision(action=RetryAction.GIVE_UP)
+
+        def on_exhausted(exc: Exception):
+            # Preserve historic shape: ResourceExhausted surfaces the original exception;
+            # parse-error exhaustion wraps with a descriptive message naming the response.
+            if isinstance(exc, ResourceExhausted):
+                logger.error(f"Resource exhausted on final parsing attempt: {exc}")
+                raise exc
+            logger.error(f"Max retries ({max_retries}) reached for parsing response: {response}")
+            raise Exception(f"Max retries reached for parsing response: {response}")
+
+        # ``attempt`` kwarg kept for backwards-compat with callers that passed it;
+        # the effective attempt count is ``max_retries - attempt``.
+        return with_retries(
+            call_once,
+            max_attempts=max(1, max_retries - attempt),
+            classify=classify,
+            on_exhausted=on_exhausted,
+            log_prefix="Parse response",
+        )
 
     def _try_parse(self, message_content, parser):
         try:

{codeboarding-0.10.3 → codeboarding-0.11.0}/agents/agent_responses.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import abc
 import logging
 from abc import abstractmethod
@@ -6,8 +8,6 @@ from typing import get_origin, Optional
 
 from pydantic import BaseModel, Field
 
-from agents.change_status import ChangeStatus
-
 logger = logging.getLogger(__name__)
 
 
@@ -142,10 +142,6 @@ class MethodEntry(BaseModel):
     start_line: int = Field(description="Starting line number in the file.")
     end_line: int = Field(description="Ending line number in the file.")
     node_type: str = Field(description="Node type name matching NodeType enum (e.g. METHOD, FUNCTION, CLASS).")
-    status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this method: added, modified, deleted, or unchanged.",
-    )
 
     def __hash__(self) -> int:
         return hash(self.qualified_name)
@@ -156,13 +152,22 @@ class MethodEntry(BaseModel):
         return self.qualified_name == other.qualified_name
 
     @classmethod
-    def from_method_change(cls, method_change, *, status_override: ChangeStatus | None = None) -> "MethodEntry":
+    def from_method_change(cls, method_change) -> MethodEntry:
         return cls(
             qualified_name=method_change.qualified_name,
             start_line=method_change.start_line,
             end_line=method_change.end_line,
             node_type=method_change.node_type,
-            status=status_override or method_change.change_type,
+        )
+
+    @classmethod
+    def from_node(cls, node) -> MethodEntry:
+        """Build from a ``static_analyzer.Node``. Accepts ``Any`` to avoid a hard dep."""
+        return cls(
+            qualified_name=node.fully_qualified_name,
+            start_line=node.line_start,
+            end_line=node.line_end,
+            node_type=node.type.name,
         )
 
 
@@ -170,10 +175,6 @@ class FileMethodGroup(BaseModel):
     """All methods/functions belonging to a component within a single file."""
 
     file_path: str = Field(description="Relative path to the source file.")
-    file_status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this file: added, modified, deleted, renamed, or unchanged.",
-    )
     methods: list[MethodEntry] = Field(
         default_factory=list,
         description="Methods and functions in this file that belong to the component, sorted by start_line.",
@@ -183,10 +184,6 @@ class FileMethodGroup(BaseModel):
 class FileEntry(BaseModel):
     """Single source of truth for methods in one file."""
 
-    file_status: ChangeStatus = Field(
-        default=ChangeStatus.UNCHANGED,
-        description="Diff status of this file: added, modified, deleted, renamed, or unchanged.",
-    )
     methods: list[MethodEntry] = Field(
         default_factory=list,
         description="Methods and functions in this file, sorted by start line.",