buddhi-ai 1.0.0b5

Buddhi AI CLI

Buddhi AI CLI

Buddhi AI CLI (buddhi-ai) is a powerful command-line tool designed to map structural entities and filter boilerplate in your codebase. Built on top of AST parsing (Tree-sitter) and graph analysis (igraph), Buddhi AI creates a topology-driven retrieval pipeline. It also seamlessly integrates with the Model Context Protocol (MCP) to provide intelligent code search, reading, and shell execution capabilities for AI agents.

Key Features

• Structural Code Mapping: Uses Tree-sitter to parse source code into an Abstract Syntax Tree (AST) and maps it into a graph database (SQLite).
• Boilerplate Filtering: Employs Shannon entropy thresholds to filter out boilerplate lines and highlight critical code paths.
• Topology-Driven Search: Community-aware search that traverses neighborhoods and includes bridge nodes instead of standard keyword-only retrieval.
• Dynamic File Reading: Reads files using dynamic compression, AST pruning, and bounce prevention logic to prevent prompt thrashing.
• Native Fallback & Telemetry: Gracefully degrades to native search when necessary, while comprehensively tracking token savings and tool execution metrics.
• MCP Integration: Fully exposes search and read tools via the FastMCP server.

Architecture & Tech Stack

• Python 3.10+: Core language.
• Tree-sitter: Used for parsing various programming languages into ASTs.
• igraph: Handles complex graph-based topological searches and structural abstraction.
• FastMCP: Provides the Model Context Protocol server interface.
• uv: Dependency management and build backend.

Prerequisites

• Python: 3.10 or higher.
• (Recommended) uv: For fast Python package resolution and virtual environment management.

Installation

From Source (Using uv)

1. Clone the repository:

   git clone <repository_url>
   cd buddhi-cli
   

2. Sync dependencies using uv (or install via pip):

   uv sync
   

3. Activate the virtual environment:

   source .venv/bin/activate
   

   (On Windows, use .venv\Scripts\activate)

From Source (Using pip)

Alternatively, install it in editable mode:

pip install -e .

---

Usage

1. The buddhi CLI

Before using the tools, you need to initialize the project directory and scan the codebase.

buddhi init [OPTIONS]

Options:

• --entropy-threshold <FLOAT>: Shannon entropy threshold for filtering boilerplate lines. Default is 3.0.

This will parse your workspace and create the Buddhi graph database at .buddhi/graph.db.

Additional Commands:

• buddhi metrics [--days N] [--json] [--reset]: Show tool usage metrics and token savings.
• buddhi hook <name>: Run a named hook handler (e.g. gate-io, pre-invoke).

2. The MCP Server (buddhi-mcp)

Start the FastMCP server over standard input/output (StdIO):

buddhi-mcp [OPTIONS]

Options:

• --db-path <PATH>: Explicit path to the .buddhi/graph.db database. Overrides the auto-detection traversing upwards from the current working directory.

Available MCP Tools

Once the server is running, the following tools are exposed via the Model Context Protocol:

• buddhi_search(query, top_n=3, mode="full", include_bridges=True, budget=8000, cwd=None) Search the codebase using Buddhi's topology-driven retrieval. Replace keyword-only searches with community-aware context-optimized results. Features an automatic native fallback mechanism when graph database results are sparse.

• buddhi_read(filepath=None, query=None, mode="auto", task_intent=None, budget=4000, cwd=None) Read a file with dynamic compression, AST pruning, and bounce prevention logic, or search for files/symbols in the workspace. Mode options include 'auto', 'full', 'signatures', 'map', or 'entropy'.

Development & Contributing

• Linting & Formatting: Handled via ruff and mypy (defined in pyproject.toml dependency groups).
• Testing: Handled via pytest.

To run tests:

pytest tests/

Testing the CLI Locally

To test the CLI tool locally as if it were in production without publishing to PyPI:

Option 1: Global Installation (Recommended) Install the built .whl file globally using uv tool install:

uv build
uv tool install dist/buddhi_ai-<version>-py3-none-any.whl --force

To uninstall later:

uv tool uninstall buddhi-ai

Option 2: Editable Mode For active development, install the tool in editable mode so changes to the source code are reflected immediately:

uv tool install -e .

To uninstall:

uv tool uninstall buddhi-ai