codeboarding 0.11.0__tar.gz → 0.12.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.11.0
+Version: 0.12.2
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT
@@ -18,7 +18,6 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: docker>=7.1
 Requires-Dist: dotenv>=0.9
-Requires-Dist: duckdb>=1.3
 Requires-Dist: dulwich>=0.22
 Requires-Dist: fastapi>=0.115
 Requires-Dist: filelock>=3.12
@@ -34,12 +33,15 @@ Requires-Dist: langchain-community>=0.4
 Requires-Dist: langchain-google-genai>=3.1
 Requires-Dist: langchain-ollama>=1.0
 Requires-Dist: langchain-openai>=1.1
+Requires-Dist: leidenalg>=0.10
 Requires-Dist: markdown>=3.8
 Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: markitdown>=0.1
 Requires-Dist: networkx>=3.4
 Requires-Dist: nodeenv>=1.10.0
 Requires-Dist: pathspec>=0.12
+Requires-Dist: posthog>=3.7
+Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2024.11
 Requires-Dist: rich>=12.6
@@ -93,15 +95,17 @@ Dynamic: license-file
 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
+pipx install codeboarding --python python3.12 --pip-args="--extra-index-url https://pip.codeboarding.org/simple/"
 ```
 
 Alternatively, install into an existing virtual environment with pip:
 
 ```bash
-pip install codeboarding
+pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 ```
 
+
+
 > 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):

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

@@ -23,15 +23,17 @@
 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
+pipx install codeboarding --python python3.12 --pip-args="--extra-index-url https://pip.codeboarding.org/simple/"
 ```
 
 Alternatively, install into an existing virtual environment with pip:
 
 ```bash
-pip install codeboarding
+pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 ```
 
+
+
 > 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):

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

@@ -4,9 +4,9 @@ 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)
+[Website](https://codeboarding.org) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" /> · [Open VSX extension](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" /> · [Explore examples](https://codeboarding.org/diagrams) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> · [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) ·[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)
+[![CodeBoarding demo](https://gist.githubusercontent.com/ivanmilevtues/1c4f921066613516cfd7b938014a6877/raw/611aec7711556807860ff2e1679a5dc4c0c23fed/CodeBoarding_extension_demo.gif)](https://open-vsx.org/extension/CodeBoarding/codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=ce87464c-2792-46b0-9ea2-87eefe853d7e" width="0" height="0" />
 
 Install the extension from Open VSX.
 
@@ -86,7 +86,7 @@ codeboarding full --local /path/to/repo
 Or, if you prefer pip, install into a virtual environment (not the global Python):
 
 ```bash
-pip install codeboarding
+pip install codeboarding --extra-index-url https://pip.codeboarding.org/simple/
 codeboarding-setup
 codeboarding full --local /path/to/repo
 ```
@@ -108,6 +108,8 @@ On first run, CodeBoarding creates `~/.codeboarding/config.toml`. Set one provid
 # aws_bearer_token_bedrock  = "..."
 # ollama_base_url           = "http://localhost:11434"
 # openrouter_api_key        = "sk-..."
+# 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-flash"
@@ -138,19 +140,32 @@ python main.py full 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.
+- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8a3d26e0-6f6b-49c0-8482-114445de56a5" width="0" height="0" /> for in-editor visual architecture.
+- [GitHub Action](https://github.com/marketplace/actions/codeboarding-action) to keep diagrams updated in CI.
 
 ## Supported stack
 
-- Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust.
-- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, and more.
+- Languages: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#.
+- LLM providers: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter, LiteLLM proxy, 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).
+- Try the hosted explorer at [codeboarding.org/diagrams](https://codeboarding.org/diagrams) <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=0855d476-b2d0-44cc-b93d-69b47504719c" width="0" height="0" />.
+
+## Telemetry
+
+CodeBoarding collects anonymous, aggregate usage telemetry (which command ran,
+success/failure, duration, and token cost) to help us improve the tool. It is on
+by default and never collects source code, file names, repository names, paths,
+prompts, model outputs, API keys, or any personal information. 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
 
@@ -159,3 +174,5 @@ If you want to improve CodeBoarding, open an [issue](https://github.com/CodeBoar
 ## 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.
+
+<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=1942e7e7-0762-4cdd-9f08-024acc098071" />

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

@@ -5,7 +5,7 @@ from pathlib import Path
 from google.api_core.exceptions import ResourceExhausted
 from langchain_core.exceptions import OutputParserException
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, ToolMessage
 from langchain_core.output_parsers import PydanticOutputParser
 from langchain_core.prompts import PromptTemplate
 from langchain.agents import create_agent
@@ -20,6 +20,7 @@ from agents.tools.toolkit import CodeBoardingToolkit
 from agents.validation import ValidationResult, score_validation_results, VALIDATOR_WEIGHTS, DEFAULT_VALIDATOR_WEIGHT
 from monitoring.mixin import MonitoringMixin
 from repo_utils.ignore import RepoIgnoreManager
+from agents.agent_responses import LLMBaseModel
 from agents.llm_config import MONITORING_CALLBACK
 from static_analyzer.analysis_result import StaticAnalysisResults
 from static_analyzer.reference_resolve_mixin import ReferenceResolverMixin
@@ -43,10 +44,10 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         ReferenceResolverMixin.__init__(self, repo_dir, static_analysis)
         MonitoringMixin.__init__(self)
         self.parsing_llm = parsing_llm
+        self.agent_llm = agent_llm
         self.repo_dir = repo_dir
         self.ignore_manager = RepoIgnoreManager(repo_dir)
 
-        # Initialize the professional toolkit
         context = RepoContext(repo_dir=repo_dir, ignore_manager=self.ignore_manager, static_analysis=static_analysis)
         self.toolkit = CodeBoardingToolkit(context=context)
 
@@ -200,10 +201,10 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         except Empty:
             raise RuntimeError("Agent invocation completed but no result was returned")
 
-    def _parse_invoke(self, prompt: str, type: type):
+    def _parse_invoke(self, prompt: str, type: type, include_hidden: bool = False):
         response = self._invoke(prompt)
         assert isinstance(response, str), f"Expected a string as response type got {response}"
-        return self._parse_response(prompt, response, type)
+        return self._parse_response(prompt, response, type, include_hidden=include_hidden)
 
     def _score_result(self, result, validators: list, context) -> tuple[float, list[tuple[float, str]]]:
         """Run all validators on a result and return (score, prioritized_feedback).
@@ -233,7 +234,13 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         return score, weighted_feedback
 
     def _validation_invoke(
-        self, prompt: str, return_type: type, validators: list, context, max_validation_attempts: int = 1
+        self,
+        prompt: str,
+        return_type: type,
+        validators: list,
+        context,
+        max_validation_attempts: int = 1,
+        include_hidden: bool = False,
     ):
         """
         Invoke LLM with validation, feedback loop, and best-of-N selection.
@@ -261,7 +268,12 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         # Compute the maximum possible score so we can detect a perfect result
         max_possible_score = sum(VALIDATOR_WEIGHTS.get(v.__name__, DEFAULT_VALIDATOR_WEIGHT) for v in validators)
 
-        result = self._parse_invoke(prompt, return_type)
+        result = self._parse_invoke(prompt, return_type, include_hidden=include_hidden)
+        logger.info(
+            "[Validation] Parsed %s: %s",
+            return_type.__name__,
+            result.llm_str()[:500],
+        )
 
         # Track the best candidate across all attempts
         best_result = result
@@ -314,42 +326,33 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
                 f"[Validation] Preparing attempt {attempt + 1}/{max_validation_attempts} "
                 f"with {len(weighted_feedback)} feedback items"
             )
-            result = self._parse_invoke(feedback_prompt, return_type)
+            result = self._parse_invoke(feedback_prompt, return_type, include_hidden=include_hidden)
 
         return best_result
 
-    def _parse_response(self, prompt, response, return_type, max_retries=5, attempt=0):
+    def _parse_response(self, prompt, response, return_type, max_retries=5, attempt=0, include_hidden: bool = False):
         if response is None or response.strip() == "":
             logger.error(f"Empty response for prompt: {prompt}")
 
+        if include_hidden and issubclass(return_type, LLMBaseModel):
+            schema = return_type.model_json_schema(include_hidden=True)
+            parser = PydanticOutputParser(pydantic_object=return_type)
+            format_instructions = (
+                f"The output should be formatted as a JSON instance that conforms to the JSON schema below.\n"
+                f"Here is the output schema:\n```json\n{json.dumps(schema, indent=2)}\n```"
+            )
+        else:
+            parser = PydanticOutputParser(pydantic_object=return_type)
+            format_instructions = parser.get_format_instructions()
+
         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:
-                message = result["messages"][0].content
-                parser = PydanticOutputParser(pydantic_object=return_type)
-                if not message:
-                    raise EmptyExtractorMessageError("Extractor returned empty message content")
-                return self._try_parse(message, parser)
-            parser = PydanticOutputParser(pydantic_object=return_type)
-            return self._try_parse(response, parser)
+                result = self._structured_parse(response, parser, format_instructions=format_instructions)
+                logger.debug("[parse_response] structured_parse succeeded for %s", return_type.__name__)
+                return result
+            except Exception as e:
+                logger.warning("[parse_response] structured_parse failed for %s: %s", return_type.__name__, e)
+            return self._extractor_parse(response, return_type, parser, include_hidden=include_hidden)
 
         def classify(exc: Exception, attempt: int) -> RetryDecision:
             if isinstance(exc, ResourceExhausted):
@@ -359,20 +362,15 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
                 )
             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),
@@ -381,19 +379,21 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
             log_prefix="Parse response",
         )
 
-    def _try_parse(self, message_content, parser):
-        try:
-            prompt_template = """You are an JSON expert. Here you need to extract information in the following json format: {format_instructions}
+    def _structured_parse(self, message_content, parser, format_instructions: str | None = None):
+        if format_instructions is None:
+            format_instructions = parser.get_format_instructions()
+        prompt_template = """You are a JSON expert. Here you need to extract information in the following json format: {format_instructions}
 
-            Here is the content to parse and fix: {adjective}
+        Here is the content to parse and fix: {adjective}
 
-            Please provide only the JSON output without any additional text."""
-            prompt = PromptTemplate(
-                template=prompt_template,
-                input_variables=["adjective"],
-                partial_variables={"format_instructions": parser.get_format_instructions()},
-            )
-            chain = prompt | self.parsing_llm | parser
+        Please provide only the JSON output without any additional text."""
+        prompt = PromptTemplate(
+            template=prompt_template,
+            input_variables=["adjective"],
+            partial_variables={"format_instructions": format_instructions},
+        )
+        chain = prompt | self.parsing_llm | parser
+        try:
             return chain.invoke(
                 {"adjective": message_content},
                 config={"callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback]},
@@ -401,7 +401,28 @@ class CodeBoardingAgent(ReferenceResolverMixin, MonitoringMixin):
         except (ValidationError, OutputParserException):
             for _, v in json.loads(message_content).items():
                 try:
-                    return self._try_parse(json.dumps(v), parser)
+                    return self._structured_parse(json.dumps(v), parser)
                 except:
                     pass
         raise ValueError(f"Couldn't parse {message_content}")
+
+    def _extractor_parse(self, response, return_type, parser, include_hidden: bool = False):
+        extractor = create_extractor(self.parsing_llm, tools=[return_type], tool_choice=return_type.__name__)
+        try:
+            result = extractor.invoke(
+                return_type.extractor_str(include_hidden=include_hidden) + response,
+                config={"callbacks": [MONITORING_CALLBACK, self.agent_monitoring_callback]},
+            )
+        except AttributeError as e:
+            if "tool_call_id" in str(e):
+                logger.warning(f"Trustcall bug encountered: {e}")
+                raise
+            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:
+            message = result["messages"][0].content
+            if not message:
+                raise EmptyExtractorMessageError("Extractor returned empty message content")
+            return self._structured_parse(message, parser)
+        raise EmptyExtractorMessageError("Extractor returned no responses and no messages")