codeboarding 0.13.11__tar.gz → 0.14.1__tar.gz

{codeboarding-0.13.11/codeboarding.egg-info → codeboarding-0.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.11
+Version: 0.14.1
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -22,7 +22,6 @@ Requires-Dist: fastapi>=0.115
 Requires-Dist: filelock>=3.12
 Requires-Dist: gitpython>=3.1
 Requires-Dist: google-api-core>=2.10
-Requires-Dist: igraph>=1.0
 Requires-Dist: jsonpatch>=1.33
 Requires-Dist: jsonschema>=4.25
 Requires-Dist: langchain>=1.2
@@ -35,7 +34,6 @@ Requires-Dist: langchain-google-genai>=3.1
 Requires-Dist: langchain-ollama>=1.0
 Requires-Dist: langchain-openai>=1.1
 Requires-Dist: langgraph>=1.0
-Requires-Dist: leidenalg>=0.10
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
@@ -48,7 +46,6 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11
 Requires-Dist: requests>=2.32
 Requires-Dist: rich>=12.6
-Requires-Dist: sqlalchemy>=2.0
 Requires-Dist: tqdm>=4.67
 Requires-Dist: tree-sitter==0.25.2
 Requires-Dist: tree-sitter-c-sharp==0.23.5
@@ -59,7 +56,6 @@ Requires-Dist: tree-sitter-php==0.24.1
 Requires-Dist: tree-sitter-python==0.25.0
 Requires-Dist: tree-sitter-rust==0.24.2
 Requires-Dist: tree-sitter-typescript==0.23.2
-Requires-Dist: trustcall>=0.0.39
 Requires-Dist: uvicorn>=0.23
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3; extra == "dev"
@@ -144,7 +140,7 @@ generated `.codeboarding/analysis.json` — it is parsed in your browser, nothin
 ```python
 import json
 from pathlib import Path
-from diagram_analysis import DiagramGenerator, configure_models
+from diagram_analysis import DiagramGenerator, RunContext, configure_models
 from diagram_analysis.analysis_json import parse_unified_analysis
 
 # Pass the key programmatically — shell env vars always take precedence if already set.
@@ -157,14 +153,17 @@ output_dir = repo_path / ".codeboarding"
 output_dir.mkdir(parents=True, exist_ok=True)
 
 # Generate the architectural diagram
+context = RunContext.resolve("my-project")
 generator = DiagramGenerator(
     repo_location=repo_path,
     temp_folder=output_dir,
     repo_name="my-project",
     output_dir=output_dir,
-    depth_level=3,  # safety-valve cap; a component that outgrows the leaf ceiling is flagged expandable and can be expanded on demand
+    depth_cap=3,  # Maximum hierarchy depth for automatic expansion, not a target.
+    run_id=context.run_id,
+    log_path=context.log_path,
 )
-[analysis_path] = generator.generate_analysis()
+analysis_path = generator.generate_analysis()
 
 # Read and inspect the results
 with open(analysis_path) as f:
@@ -201,8 +200,7 @@ LLM provider keys and model overrides are stored in `~/.codeboarding/config.toml
 
 [llm]
 # Optional: override the default model for your active provider
-# agent_model   = "gemini-3.7-flash"
-# parsing_model = "gemini-3.1-flash-lite"
+# agent_model = "gemini-3.8-flash"
 ```
 
 Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always take precedence over the config file, so CI/CD pipelines need no changes. For private repositories, set `GITHUB_TOKEN` in your environment.
@@ -226,7 +224,7 @@ codeboarding-render PATH/analysis.json --format FORMAT # render an existing anal
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
 | `--render {md,html,mdx,rst}` | Render overview and component files from the local `analysis.json` for full, incremental, or partial commands |
-| `--depth-level INT` | Safety-valve depth cap (default: 3) on how deep auto-expansion goes; a component that outgrows the leaf ceiling is flagged expandable regardless, and can be expanded on demand |
+| `--depth-cap INT` | Maximum allowed hierarchy depth for automatic expansion (default: 3), not a target. Components can still be expanded on demand. Configures `metadata.depth_cap`, not `metadata.depth_level` (the depth actually reached). No input alias is accepted. |
 | `--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 |

{codeboarding-0.13.11 → codeboarding-0.14.1}/PYPI.md

@@ -67,7 +67,7 @@ generated `.codeboarding/analysis.json` — it is parsed in your browser, nothin
 ```python
 import json
 from pathlib import Path
-from diagram_analysis import DiagramGenerator, configure_models
+from diagram_analysis import DiagramGenerator, RunContext, configure_models
 from diagram_analysis.analysis_json import parse_unified_analysis
 
 # Pass the key programmatically — shell env vars always take precedence if already set.
@@ -80,14 +80,17 @@ output_dir = repo_path / ".codeboarding"
 output_dir.mkdir(parents=True, exist_ok=True)
 
 # Generate the architectural diagram
+context = RunContext.resolve("my-project")
 generator = DiagramGenerator(
     repo_location=repo_path,
     temp_folder=output_dir,
     repo_name="my-project",
     output_dir=output_dir,
-    depth_level=3,  # safety-valve cap; a component that outgrows the leaf ceiling is flagged expandable and can be expanded on demand
+    depth_cap=3,  # Maximum hierarchy depth for automatic expansion, not a target.
+    run_id=context.run_id,
+    log_path=context.log_path,
 )
-[analysis_path] = generator.generate_analysis()
+analysis_path = generator.generate_analysis()
 
 # Read and inspect the results
 with open(analysis_path) as f:
@@ -124,8 +127,7 @@ LLM provider keys and model overrides are stored in `~/.codeboarding/config.toml
 
 [llm]
 # Optional: override the default model for your active provider
-# agent_model   = "gemini-3.7-flash"
-# parsing_model = "gemini-3.1-flash-lite"
+# agent_model = "gemini-3.8-flash"
 ```
 
 Shell environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) always take precedence over the config file, so CI/CD pipelines need no changes. For private repositories, set `GITHUB_TOKEN` in your environment.
@@ -149,7 +151,7 @@ codeboarding-render PATH/analysis.json --format FORMAT # render an existing anal
 |---|---|
 | `--local PATH` | Analyze a local repository (output: `PATH/.codeboarding/`) |
 | `--render {md,html,mdx,rst}` | Render overview and component files from the local `analysis.json` for full, incremental, or partial commands |
-| `--depth-level INT` | Safety-valve depth cap (default: 3) on how deep auto-expansion goes; a component that outgrows the leaf ceiling is flagged expandable regardless, and can be expanded on demand |
+| `--depth-cap INT` | Maximum allowed hierarchy depth for automatic expansion (default: 3), not a target. Components can still be expanded on demand. Configures `metadata.depth_cap`, not `metadata.depth_level` (the depth actually reached). No input alias is accepted. |
 | `--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 |

{codeboarding-0.13.11 → codeboarding-0.14.1}/README.md

@@ -138,13 +138,12 @@ On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provid
 # litellm_api_key           = "sk-..."           # LiteLLM proxy server key (optional)
 
 [llm]
-# agent_model   = "gemini-3.7-flash"
-# parsing_model = "gemini-3.1-flash-lite"
+# agent_model = "gemini-3.8-flash"
 ```
 
-`openai_base_url` points CodeBoarding at any OpenAI-compatible gateway. Set the gateway API key as `openai_api_key`, then choose its model IDs with `agent_model` and `parsing_model`. The equivalent shell variables are `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `AGENT_MODEL`, and `PARSING_MODEL`.
+`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` and `parsing_model` so CodeBoarding selects the correct model capabilities and prompts.
+`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.
 
@@ -156,8 +155,8 @@ 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-level is a safety-valve cap, default 3)
-python main.py full --local ./my-project --depth-level 5
+# 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
@@ -169,6 +168,20 @@ python main.py partial --local ./my-project --component-id "1.2"
 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-0.13.11 → codeboarding-0.14.1}/agents/agent_responses.py

@@ -5,10 +5,8 @@ import logging
 from abc import abstractmethod
 from collections.abc import Hashable
 from enum import StrEnum
-from typing import get_origin
 
 from pydantic import BaseModel, Field
-from pydantic.fields import FieldInfo
 
 from clustering_ids import ComponentId
 from agents.file_index_models import FileEntry, FileMethodGroup, MethodIndexEntry
@@ -18,112 +16,12 @@ logger = logging.getLogger(__name__)
 
 
 class LLMBaseModel(BaseModel, abc.ABC):
-    """Base model for LLM-parseable response types."""
+    """Base model for semantic response types with prompt rendering."""
 
     @abstractmethod
     def llm_str(self) -> str:
         raise NotImplementedError("LLM String has to be implemented.")
 
-    @classmethod
-    def _is_field_hidden(cls, fvalue: FieldInfo) -> bool:
-        if fvalue.exclude:
-            return True
-        extra = fvalue.json_schema_extra
-        if isinstance(extra, dict):
-            return bool(extra.get("hidden"))
-        return False
-
-    @classmethod
-    def _excluded_fields(cls, include_hidden: bool = False) -> set[str]:
-        if include_hidden:
-            return set()
-        names: set[str] = set()
-        for klass in cls.__mro__:
-            if hasattr(klass, "model_fields"):
-                for fname, finfo in klass.model_fields.items():
-                    if cls._is_field_hidden(finfo):
-                        names.add(fname)
-        return names
-
-    @classmethod
-    def _resolve_excluded_by_title(cls, include_hidden: bool = False) -> dict[str, set[str]]:
-        seen: set[type] = set()
-        result: dict[str, set[str]] = {}
-
-        def walk(model: type) -> None:
-            if model in seen or not hasattr(model, "model_fields"):
-                return
-            seen.add(model)
-            title = getattr(model, "__name__", "")
-            excluded = model._excluded_fields(include_hidden)  # type: ignore[attr-defined]
-            if excluded:
-                result[title] = excluded
-            for finfo in getattr(model, "model_fields", {}).values():
-                ann = finfo.annotation
-                for candidate in getattr(ann, "__args__", [ann]):
-                    if isinstance(candidate, type) and issubclass(candidate, LLMBaseModel):
-                        walk(candidate)  # type: ignore[arg-type]
-
-        walk(cls)
-        return result
-
-    @classmethod
-    def _extractor_fields(cls, indent: str = "  ", include_hidden: bool = False) -> str:
-        parts: list[str] = []
-        for fname, fvalue in cls.model_fields.items():
-            if cls._is_field_hidden(fvalue) and not include_hidden:
-                continue
-            ftype = fvalue.annotation
-            if get_origin(ftype) is list:
-                if ftype is not None and hasattr(ftype, "__args__"):
-                    inner = ftype.__args__[0]
-                    if isinstance(inner, type) and issubclass(inner, LLMBaseModel):
-                        parts.append(
-                            f"{indent}- {fname}: a list, where each item has:\n{inner._extractor_fields(indent + '  ', include_hidden)}"
-                        )
-                        continue
-                parts.append(f"{indent}- {fname}: {fvalue.description}")
-            elif isinstance(ftype, type) and issubclass(ftype, LLMBaseModel):
-                parts.append(ftype._extractor_fields(indent, include_hidden))
-            else:
-                parts.append(f"{indent}- {fname}: {fvalue.description}")
-        return "\n".join(parts)
-
-    @classmethod
-    def extractor_str(cls, include_hidden: bool = False) -> str:
-        title = cls.__name__
-        fields = cls._extractor_fields(include_hidden=include_hidden)
-        return (
-            f"You are a JSON extraction expert. "
-            f"Extract a valid JSON object of type `{title}` from the text below.\n"
-            f"The JSON must have these fields:\n{fields}\n\n"
-        )
-
-    @classmethod
-    def model_json_schema(
-        cls,
-        by_alias: bool = True,
-        ref_template: str = "#/$defs/{model}",
-        schema_generator: type | None = None,
-        mode: str = "validation",
-        include_hidden: bool = False,
-        **kwargs,
-    ) -> dict:
-        call_kwargs: dict = {"by_alias": by_alias, "ref_template": ref_template, "mode": mode}
-        if schema_generator is not None:
-            call_kwargs["schema_generator"] = schema_generator
-        call_kwargs.update(kwargs)
-        schema = super().model_json_schema(**call_kwargs)
-        excluded_by_title = cls._resolve_excluded_by_title(include_hidden)
-        for title, excluded in excluded_by_title.items():
-            defn = schema.get("$defs", {}).get(title)
-            if isinstance(defn, dict) and "properties" in defn:
-                defn["properties"] = {k: v for k, v in defn["properties"].items() if k not in excluded}
-        own_excluded = cls._excluded_fields(include_hidden)
-        if "properties" in schema:
-            schema["properties"] = {k: v for k, v in schema["properties"].items() if k not in own_excluded}
-        return schema
-
 
 class SourceCodeReference(LLMBaseModel):
     """Reference to source code including qualified name and file location."""
@@ -189,7 +87,6 @@ class RelationEdge(LLMBaseModel):
         default_factory=list,
         description="Call-site line and column pairs for this edge.",
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
 
     @classmethod
@@ -290,7 +187,6 @@ class Relation(LLMBaseModel):
         default_factory=list,
         description="All known source-to-target edges for this relation, populated deterministically when available.",
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
 
     @classmethod
@@ -385,30 +281,22 @@ class Component(LLMBaseModel):
         description="The most important/critical classes and methods that represent this component's core functionality. Pick 2-5 key entities."
     )
 
-    source_group_names: list[str] = Field(
-        description="Names of the cluster groups from the grouping analysis that this component encompasses.",
-        default_factory=list,
-    )
-
     source_cluster_ids: list[ComponentId] = Field(
-        description="List of cluster IDs from CFG analysis that this component encompasses (populated deterministically from source_group_names).",
+        description="List of cluster IDs from CFG analysis that this component encompasses.",
         default_factory=list,
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
 
     file_methods: list[FileMethodGroup] = Field(
         description="All methods/functions belonging to this component, grouped by file (populated deterministically from cluster results).",
         default_factory=list,
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
 
     component_id: str = Field(
         default="",
         description="Deterministic unique identifier for this component.",
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
 
     def file_paths(self) -> list[str]:
@@ -418,14 +306,11 @@ class Component(LLMBaseModel):
     def llm_str(self):
         n = f"**Component:** `{self.name}`"
         d = f"   - *Description*: {self.description}"
-        sg = ""
-        if self.source_group_names:
-            sg = f"   - *Source Group Names*: {', '.join(self.source_group_names)}"
         qn = ""
         if self.key_entities:
             qn += "   - *Key Entities*: "
             qn += ", ".join(f"`{q.llm_str()}`" for q in self.key_entities)
-        return "\n".join([n, d, sg, qn]).strip()
+        return "\n".join([n, d, qn]).strip()
 
 
 class AnalysisInsights(LLMBaseModel):
@@ -438,7 +323,6 @@ class AnalysisInsights(LLMBaseModel):
         default_factory=dict,
         description="Top-level file index keyed by relative file path. Contains all methods and statuses.",
         exclude=True,
-        json_schema_extra={"hidden": True},
     )
     components: list[Component] = Field(description="List of the components identified in the project.")
     components_relations: list[Relation] = Field(description="List of relations among the components.")
@@ -469,81 +353,6 @@ class AnalysisInsights(LLMBaseModel):
         return title + body + relations
 
 
-class ComponentArchitecture(LLMBaseModel):
-    """Component-only architecture before relation discovery."""
-
-    description: str = Field(
-        description="One paragraph explaining the functionality represented by this graph, its main flow, and purpose."
-    )
-    components: list[Component] = Field(description="List of the components identified in the project.")
-
-    def llm_str(self):
-        if not self.components:
-            return "No abstract components found."
-        title = "# Abstract Components Overview\n"
-        body = "\n".join(ac.llm_str() for ac in self.components)
-        return title + body
-
-
-class ComponentApiSurface(LLMBaseModel):
-    """The provided and consumed APIs for one component."""
-
-    component_name: str = Field(description="Exact component name this API surface describes.")
-    provided_interfaces: list[SourceCodeReference] = Field(
-        default_factory=list,
-        description="Methods/classes/config symbols this component exposes or uses as entrypoints.",
-    )
-    consumed_interfaces: list[SourceCodeReference] = Field(
-        default_factory=list,
-        description="Methods/classes/config symbols this component calls, configures, imports, or expects from others.",
-    )
-    incoming_api_paths: list[str] = Field(
-        default_factory=list,
-        description="How other components enter this component's API, such as direct calls, registry dispatch, REST, queues, plugins, files, or config.",
-    )
-    outgoing_api_paths: list[str] = Field(
-        default_factory=list,
-        description="How this component reaches other components' APIs, such as direct calls, registry dispatch, REST, queues, plugins, files, or config.",
-    )
-    notes: str = Field(default="", description="Short notes about the component's API role.")
-
-    def llm_str(self):
-        provided = ", ".join(ref.llm_str() for ref in self.provided_interfaces) or "none"
-        consumed = ", ".join(ref.llm_str() for ref in self.consumed_interfaces) or "none"
-        incoming = ", ".join(self.incoming_api_paths) or "none"
-        outgoing = ", ".join(self.outgoing_api_paths) or "none"
-        return (
-            f"**{self.component_name}**\n"
-            f"  Provided: {provided}\n"
-            f"  Consumed: {consumed}\n"
-            f"  Incoming API paths: {incoming}\n"
-            f"  Outgoing API paths: {outgoing}\n"
-            f"  Notes: {self.notes}"
-        )
-
-
-class ComponentApiSurfaces(LLMBaseModel):
-    """API surfaces for all components in a scope."""
-
-    api_surfaces: list[ComponentApiSurface] = Field(description="API surface for each component in this scope.")
-
-    def llm_str(self):
-        if not self.api_surfaces:
-            return "No component API surfaces found."
-        return "\n".join(surface.llm_str() for surface in self.api_surfaces)
-
-
-class ComponentRelations(LLMBaseModel):
-    """Relations discovered from component API surfaces."""
-
-    components_relations: list[Relation] = Field(description="List of relations among the components.")
-
-    def llm_str(self):
-        if not self.components_relations:
-            return "No component relations found."
-        return "\n".join(relation.llm_str() for relation in self.components_relations)
-
-
 def assign_component_ids(analysis: AnalysisInsights, parent_id: str = "", only_new: bool = False) -> None:
     """Assign hierarchical component IDs based on sibling index.
 
@@ -632,58 +441,27 @@ def index_components_by_id(
     return {c.component_id: c for c in iter_components(root_analysis, sub_analyses) if c.component_id}
 
 
-class MetaAnalysisInsights(LLMBaseModel):
-    """Insights from analyzing project metadata including type, domain, and architecture."""
+class PlannedGroup(LLMBaseModel):
+    """One component the planner proposes, as the candidate groups it gathers."""
 
-    project_type: str = Field(
-        description="Type/category of the project (e.g., web framework, data processing, ML library, etc.)"
+    name: str = Field(description="One responsibility; never two joined by 'and' or '&'")
+    members: list[str] = Field(description="Labels of the candidate groups this component gathers, e.g. ['G1', 'G4']")
+    owns: list[str] = Field(
+        default_factory=list, description="Domain words this component owns, as they appear in identifiers"
     )
-    domain: str = Field(
-        description="Domain or field the project belongs to (e.g., web development, data science, DevOps, etc.)"
-    )
-    architectural_patterns: list[str] = Field(description="Main architectural patterns typically used in such projects")
-    expected_components: list[str] = Field(description="Expected high-level components/modules based on project type")
-    technology_stack: list[str] = Field(description="Main technologies, frameworks, and libraries used")
-    architectural_bias: str = Field(
-        description="Guidance on how to interpret and organize components for this project type"
-    )
-
-    def llm_str(self):
-        title = "# Project Metadata Analysis\n"
-        content = f"""
-**Project Type:** {self.project_type}
-**Domain:** {self.domain}
-**Technology Stack:** {", ".join(self.technology_stack)}
-**Architectural Patterns:** {", ".join(self.architectural_patterns)}
-**Expected Components:** {", ".join(self.expected_components)}
-**Architectural Bias:** {self.architectural_bias}
-"""
-        return title + content
-
-
-class FileClassification(LLMBaseModel):
-    """Classification of a file to a component."""
-
-    component_name: str = Field(description="Name of the component or module")
-    file_path: str = Field(description="Path to the file")
 
     def llm_str(self):
-        return f"`{self.file_path}` -> Component: `{self.component_name}`"
+        return f"{self.name}: {', '.join(self.members)}"
 
 
-class ComponentFiles(LLMBaseModel):
-    """Collection of file classifications for components."""
+class TreePlanInsights(LLMBaseModel):
+    """How the candidate groups of one scope fold into components."""
 
-    file_paths: list[FileClassification] = Field(
-        description="All files with their classifications for each of the files assigned to a component."
-    )
+    groups: list[PlannedGroup] = Field(description="The components, each gathering one or more candidate groups")
+    notes: str = Field(default="", description="What the names say about this scope's shape")
 
     def llm_str(self):
-        if not self.file_paths:
-            return "No files classified."
-        title = "# Component File Classifications\n"
-        body = "\n".join(f"- `{fc.file_path}` -> Component: `{fc.component_name}`" for fc in self.file_paths)
-        return title + body
+        return "# Tree plan\n" + "\n".join(f"- {group.llm_str()}" for group in self.groups)
 
 
 class ScopeOperationAction(StrEnum):
@@ -712,7 +490,8 @@ class ScopeOperation(LLMBaseModel):
     cluster_refs: list[ScopedClusterRef] = Field(description="New-side clusters this operation accounts for.")
     component_id: str | None = Field(
         default=None,
-        description="Existing component id for update/delete/noop; null when creating a component.",
+        description="Existing component id for update/delete/noop; the id the tree specification "
+        "allocated when creating a component, or null to allocate the next sibling index.",
     )
     name: str | None = Field(default=None, description="Component name for create/update operations.")
     description: str | None = Field(default=None, description="Component description for create/update operations.")
@@ -739,7 +518,7 @@ class ScopeOperation(LLMBaseModel):
 
 
 class ScopeUpdateDecision(LLMBaseModel):
-    """LLM-selected operations for one incremental scope update."""
+    """Deterministic operations for one incremental scope update."""
 
     operations: list[ScopeOperation] = Field(description="Operations to apply to the current scope.")
 

{codeboarding-0.13.11 → codeboarding-0.14.1}/agents/component_ownership.py

@@ -2,21 +2,9 @@
 
 from __future__ import annotations
 
-from collections.abc import Collection
 from dataclasses import dataclass
 
-from agents.agent_responses import AnalysisInsights, Component, SourceCodeReference
-
-
-def group_ids_by_name(components: list[Component], valid_group_ids: Collection[str]) -> dict[str, str]:
-    """Map component source-group names to their authoritative live group IDs."""
-    valid_ids = set(valid_group_ids)
-    return {
-        name: component.component_id
-        for component in components
-        if component.component_id in valid_ids
-        for name in component.source_group_names
-    }
+from agents.agent_responses import AnalysisInsights, SourceCodeReference
 
 
 @dataclass(frozen=True)

{codeboarding-0.13.11 → codeboarding-0.14.1}/agents/constants.py

@@ -3,14 +3,10 @@
 
 class LLMDefaults:
     DEFAULT_AGENT_TEMPERATURE = 0
-    DEFAULT_PARSING_TEMPERATURE = 0
     AWS_MAX_TOKENS = 4096
-
-
-class FileStructureConfig:
-    MAX_LINES = 500
-    DEFAULT_MAX_DEPTH = 10
-    FALLBACK_MAX_LINES = 50000
+    # Why: the provider configs below pass this straight to the client. ``None`` there disables the
+    # SDK's own default, so a stalled socket hangs the whole analysis with nothing to interrupt it.
+    REQUEST_TIMEOUT_SECONDS = 300.0
 
 
 class ModelCapabilities: