codeboarding 0.9.4__tar.gz → 0.9.6__tar.gz

{codeboarding-0.9.4/codeboarding.egg-info → codeboarding-0.9.6}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.9.4
+Version: 0.9.6
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
-License: MIT
+License-Expression: MIT
 Project-URL: Repository, https://github.com/CodeBoarding/CodeBoarding
 Project-URL: Documentation, https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/overview.md
 Keywords: code-understanding,code-visualization,code-analysis,diagrams,documentation,llm,static-analysis,mermaid,onboarding
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Documentation
@@ -17,23 +16,14 @@ Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: <3.14,>=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: asgiref>=3.9
-Requires-Dist: async-timeout>=4.0
 Requires-Dist: docker>=7.1
 Requires-Dist: dotenv>=0.9
 Requires-Dist: duckdb>=1.3
 Requires-Dist: dulwich>=0.22
-Requires-Dist: email-validator>=2.2
-Requires-Dist: exceptiongroup>=1.2
 Requires-Dist: fastapi>=0.115
 Requires-Dist: filelock>=3.12
 Requires-Dist: gitpython>=3.1
 Requires-Dist: google-api-core>=2.10
-Requires-Dist: google-genai>=1.10
-Requires-Dist: gql>=3.5
-Requires-Dist: injector>=0.21
-Requires-Dist: ipykernel>=6.29
-Requires-Dist: isort>=6.0
 Requires-Dist: jsonschema>=4.25
 Requires-Dist: langchain>=1.2
 Requires-Dist: langchain-anthropic>=1.3
@@ -46,21 +36,13 @@ Requires-Dist: langchain-openai>=1.1
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
-Requires-Dist: matplotlib>=3.10
 Requires-Dist: networkx>=3.4
-Requires-Dist: openpyxl>=3.1
-Requires-Dist: pandas>=2.2
 Requires-Dist: pathspec>=0.12
-Requires-Dist: pydot>=3.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11
 Requires-Dist: rich>=12.6
-Requires-Dist: seaborn>=0.13
-Requires-Dist: tomli>=2.2
 Requires-Dist: trustcall>=0.0.39
-Requires-Dist: typer>=0.9
 Requires-Dist: uvicorn>=0.23
-Requires-Dist: wcwidth>=0.2.13
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3; extra == "dev"
 Requires-Dist: pytest-cov>=7.0; extra == "dev"
@@ -91,12 +73,26 @@ Dynamic: license-file
 
 ---
 
+## Requirements
+
+- **Python 3.12 or 3.13** — other versions are currently not supported.
+
 ## Installation
 
+The recommended way to install the CLI is with [pipx](https://pipx.pypa.io), which automatically creates an isolated environment:
+
+```bash
+pipx install codeboarding --python python3.12
+```
+
+Alternatively, install into an existing virtual environment with pip:
+
 ```bash
 pip install codeboarding
 ```
 
+> Installing into the global Python environment with `pip` is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.
+
 Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):
 
 ```bash

{codeboarding-0.9.4 → codeboarding-0.9.6}/PYPI.md

@@ -14,12 +14,26 @@
 
 ---
 
+## Requirements
+
+- **Python 3.12 or 3.13** — other versions are currently not supported.
+
 ## Installation
 
+The recommended way to install the CLI is with [pipx](https://pipx.pypa.io), which automatically creates an isolated environment:
+
+```bash
+pipx install codeboarding --python python3.12
+```
+
+Alternatively, install into an existing virtual environment with pip:
+
 ```bash
 pip install codeboarding
 ```
 
+> Installing into the global Python environment with `pip` is not recommended — it can cause dependency conflicts and will fail if the system Python is not 3.12 or 3.13.
+
 Language server binaries are downloaded automatically on first use. To pre-install them explicitly (useful in CI or restricted environments):
 
 ```bash

codeboarding-0.9.6/README.md

@@ -0,0 +1,159 @@
+# CodeBoarding
+
+See what your AI is building before it breaks.
+
+CodeBoarding gives developers and coding agents a visual map of a codebase. It combines static analysis with LLM reasoning to generate architecture diagrams, component-level documentation, and navigable outputs you can use in your IDE, CI, and docs.
+
+[Website](https://codeboarding.org) · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) · [Explore examples](https://codeboarding.org/diagrams) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) · [GitHub Action](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation) ·[Discord](https://discord.gg/T5zHTJYFuy)
+
+[![CodeBoarding demo](https://gist.githubusercontent.com/ivanmilevtues/1c4f921066613516cfd7b938014a6877/raw/611aec7711556807860ff2e1679a5dc4c0c23fed/CodeBoarding_extension_demo.gif)](https://open-vsx.org/extension/CodeBoarding/codeboarding)
+
+Install the extension from Open VSX.
+
+[![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/)
+
+## Few use cases:
+
+- Keep architecture visible while agents code.
+- Review AI-generated changes with system context before they turn into hidden debt.
+- Understand large repositories faster with layered diagrams and component breakdowns.
+- Share the same visual model across local workflows, IDEs, pull requests, and docs.
+
+## What CodeBoarding generates
+
+- High-level system architecture diagrams.
+- Deeper component diagrams for important subsystems.
+- Markdown documentation in `.codeboarding/`.
+- Mermaid output that is easy to embed in docs and PRs.
+- Incremental updates when only part of the codebase changes.
+
+## How it works
+
+```mermaid
+graph LR
+    Application_Orchestrator_Repository_Manager["Application Orchestrator & Repository Manager"]
+    LLM_Agent_Core["LLM Agent Core"]
+    Static_Code_Analyzer["Static Code Analyzer"]
+    Agent_Tooling_Interface["Agent Tooling Interface"]
+    Incremental_Analysis_Engine["Incremental Analysis Engine"]
+    Documentation_Diagram_Generator["Documentation & Diagram Generator"]
+    Application_Orchestrator_Repository_Manager -- "Orchestrator initiates analysis workflow, leveraging incremental updates based on detected code changes." --> Incremental_Analysis_Engine
+    Application_Orchestrator_Repository_Manager -- "Orchestrator passes project context and triggers the main analysis workflow for the LLM Agent." --> LLM_Agent_Core
+    Incremental_Analysis_Engine -- "Incremental engine requests static analysis for specific code segments (new or changed)." --> Static_Code_Analyzer
+    Static_Code_Analyzer -- "Static analyzer provides analysis results to the incremental engine for caching." --> Incremental_Analysis_Engine
+    LLM_Agent_Core -- "LLM Agent invokes specialized tools to interact with the codebase and analysis data." --> Agent_Tooling_Interface
+    Agent_Tooling_Interface -- "Agent tools query the static analysis engine for detailed code insights." --> Static_Code_Analyzer
+    Static_Code_Analyzer -- "Static analysis engine provides requested data to the agent tools." --> Agent_Tooling_Interface
+    LLM_Agent_Core -- "LLM Agent delivers structured analysis insights for documentation and diagram generation." --> Documentation_Diagram_Generator
+    click Application_Orchestrator_Repository_Manager href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Application_Orchestrator_Repository_Manager.md" "Details"
+    click LLM_Agent_Core href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/LLM_Agent_Core.md" "Details"
+    click Static_Code_Analyzer href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Static_Code_Analyzer.md" "Details"
+    click Agent_Tooling_Interface href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Agent_Tooling_Interface.md" "Details"
+    click Incremental_Analysis_Engine href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Incremental_Analysis_Engine.md" "Details"
+    click Documentation_Diagram_Generator href "https://github.com/CodeBoarding/CodeBoarding/blob/main/.codeboarding/Documentation_Diagram_Generator.md" "Details"
+```
+
+For a deeper architecture walkthrough, see [`.codeboarding/overview.md`](.codeboarding/overview.md).
+
+## Quick start
+
+### Run from source
+
+```bash
+uv sync --frozen
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+python install.py
+python main.py --local /path/to/repo
+```
+
+### Use the packaged CLI
+
+Requires **Python 3.12 or 3.13**. 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 --local /path/to/repo
+```
+
+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
+```
+
+Output is written to `/path/to/repo/.codeboarding/`.
+
+`python install.py` and `codeboarding-setup` download language server binaries to `~/.codeboarding/servers/`, shared across projects. `npm` is required for Python, TypeScript, JavaScript, and PHP language servers; if it is missing, setup can install it via `nodeenv`.
+
+## Configuration
+
+On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provider there or use environment variables.
+
+```toml
+[provider]
+# openai_api_key            = "sk-..."
+# anthropic_api_key         = "sk-ant-..."
+# google_api_key            = "AIza..."
+# vercel_api_key            = "vck_..."
+# aws_bearer_token_bedrock  = "..."
+# ollama_base_url           = "http://localhost:11434"
+# openrouter_api_key        = "sk-..."
+
+[llm]
+# agent_model   = "gemini-3-flash"
+# parsing_model = "gemini-3-flash"
+```
+
+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.
+
+## Common commands
+
+```bash
+# Analyze a local repository
+python main.py --local ./my-project
+
+# Increase diagram depth
+python main.py --local ./my-project --depth-level 2
+
+# Re-analyze only changed parts when possible
+python main.py --local ./my-project --incremental
+
+# Update a single component by ID
+python main.py --local ./my-project --partial-component-id "1.2"
+
+# Analyze a remote GitHub repository
+python main.py https://github.com/pytorch/pytorch
+```
+
+## Where to use it
+
+- [CLI](https://github.com/CodeBoarding/CodeBoarding) for local analysis, automation, and CI workflows.
+- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) for in-editor visual architecture.
+- [GitHub Action](https://github.com/marketplace/actions/codeboarding-diagram-first-documentation) to keep diagrams updated in CI.
+
+## Supported stack
+
+- Languages: Python, TypeScript, JavaScript, Java, Go, PHP.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, and more.
+
+## Examples
+
+- Visualized 800+ open-source repositories.
+- Browse generated examples in [GeneratedOnBoardings](https://github.com/CodeBoarding/GeneratedOnBoardings).
+- Try the hosted explorer at [codeboarding.org/diagrams](https://codeboarding.org/diagrams).
+
+## 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.
+
+## Vision
+
+CodeBoarding is building an open standard for code understanding: a visual, accurate, high-level representation of a codebase that both humans and agents can use.

{codeboarding-0.9.4 → codeboarding-0.9.6}/agents/abstraction_agent.py

@@ -1,8 +1,8 @@
 import logging
 from pathlib import Path
 
-from langchain_core.prompts import PromptTemplate
 from langchain_core.language_models import BaseChatModel
+from langchain_core.prompts import PromptTemplate
 
 from agents.agent import CodeBoardingAgent
 from agents.agent_responses import (
@@ -11,24 +11,26 @@ from agents.agent_responses import (
     MetaAnalysisInsights,
     assign_component_ids,
 )
+from agents.cluster_methods_mixin import ClusterMethodsMixin
 from agents.prompts import (
-    get_system_message,
     get_cluster_grouping_message,
     get_final_analysis_message,
+    get_system_message,
 )
-from agents.cluster_methods_mixin import ClusterMethodsMixin
 from agents.validation import (
     ValidationContext,
     validate_cluster_coverage,
-    validate_component_relationships,
+    validate_group_name_coverage,
     validate_key_entities,
-    validate_cluster_ids_populated,
     validate_relation_component_names,
 )
 from monitoring import trace
 from static_analyzer.analysis_result import StaticAnalysisResults
+from static_analyzer.cluster_helpers import (
+    build_all_cluster_results,
+    get_all_cluster_ids,
+)
 from static_analyzer.graph import ClusterResult
-from static_analyzer.cluster_helpers import build_all_cluster_results, get_all_cluster_ids
 
 logger = logging.getLogger(__name__)
 
@@ -86,19 +88,20 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
                 cluster_results=cluster_results,
                 expected_cluster_ids=get_all_cluster_ids(cluster_results),
             ),
+            max_validation_attempts=3,
         )
         return cluster_analysis
 
     @trace
     def step_final_analysis(
-        self, cluster_analysis: ClusterAnalysis, cluster_results: dict[str, ClusterResult]
+        self, llm_cluster_analysis: ClusterAnalysis, cluster_results: dict[str, ClusterResult]
     ) -> AnalysisInsights:
         logger.info(f"[AbstractionAgent] Generating final analysis for: {self.project_name}")
 
         meta_context_str = self.meta_context.llm_str() if self.meta_context else "No project context available."
         project_type = self.meta_context.project_type if self.meta_context else "unknown"
 
-        cluster_str = cluster_analysis.llm_str() if cluster_analysis else "No cluster analysis available."
+        cluster_str = llm_cluster_analysis.llm_str() if llm_cluster_analysis else "No cluster analysis available."
 
         prompt = self.prompts["final_analysis"].format(
             project_name=self.project_name,
@@ -111,6 +114,8 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
         context = ValidationContext(
             cluster_results=cluster_results,
             cfg_graphs={lang: self.static_analysis.get_cfg(lang) for lang in self.static_analysis.get_languages()},
+            static_analysis=self.static_analysis,
+            llm_cluster_analysis=llm_cluster_analysis,
         )
 
         return self._validation_invoke(
@@ -118,11 +123,11 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
             AnalysisInsights,
             validators=[
                 validate_relation_component_names,
-                validate_component_relationships,
+                validate_group_name_coverage,
                 validate_key_entities,
-                validate_cluster_ids_populated,
             ],
             context=context,
+            max_validation_attempts=3,
         )
 
     def run(self):
@@ -134,17 +139,19 @@ class AbstractionAgent(ClusterMethodsMixin, CodeBoardingAgent):
 
         # Step 2: Generate abstract components from grouped clusters
         analysis = self.step_final_analysis(cluster_analysis, cluster_results)
-        # Step 3: Sanitize cluster IDs (remove invalid ones)
-        self._sanitize_component_cluster_ids(analysis, cluster_results=cluster_results)
-        # Step 4: Assign files to components (deterministic + LLM-based with validation)
-        self.classify_files(analysis, cluster_results, self.static_analysis.get_all_source_files())
-        # Step 5: Fix source code reference lines (resolves reference_file paths for key_entities)
+        # Step 3: Assign hierarchical component IDs ("1", "2", "3", ...)
+        assign_component_ids(analysis)
+        # Step 4: Resolve cluster IDs deterministically from group names
+        self._resolve_cluster_ids_from_groups(analysis, cluster_analysis)
+        # Step 5: Populate file_methods deterministically from cluster results + orphan assignment
+        self.populate_file_methods(analysis, cluster_results)
+
+        # Step 6: Build static inter-component relations from CFG edges
+        self.build_static_relations(analysis)
+
+        # Step 7: Fix source code reference lines (resolves reference_file paths for key_entities)
         analysis = self.fix_source_code_reference_lines(analysis)
-        # Step 6: Ensure unique key entities across components
+        # Step 8: Ensure unique key entities across components
         self._ensure_unique_key_entities(analysis)
-        # Step 7: Ensure unique file assignments across components
-        self._ensure_unique_file_assignments(analysis)
-        # Step 8: Assign deterministic component IDs
-        assign_component_ids(analysis)
 
         return analysis, cluster_results