Metadata-Version: 2.3
Name: buddhi-ai
Version: 1.0.0b5
Summary: Buddhi AI CLI
Keywords: ast,tree-sitter,mcp,cli,code-search,boilerplate
Author: Buddhi Kavindra
Author-email: Buddhi Kavindra <info@buddhilive.com>
License: Copyright (c) 2026 BuddhiLive.com
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: igraph>=1.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: tree-sitter>=0.25.2
Requires-Dist: tree-sitter-c-sharp>=0.23.5
Requires-Dist: tree-sitter-go>=0.25.0
Requires-Dist: tree-sitter-haskell>=0.23.1
Requires-Dist: tree-sitter-java>=0.23.5
Requires-Dist: tree-sitter-javascript>=0.25.0
Requires-Dist: tree-sitter-kotlin>=1.1.0
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.2
Requires-Dist: tree-sitter-swift>=0.7.2
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tiktoken>=0.9.0
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/Buddhilive/buddhi-cli
Project-URL: Repository, https://github.com/Buddhilive/buddhi-cli.git
Project-URL: Issues, https://github.com/Buddhilive/buddhi-cli/issues
Description-Content-Type: text/markdown

# Buddhi AI CLI

<p align="center">
<a href="https://pypi.org/project/buddhi-ai/">
    <img src="https://img.shields.io/pypi/v/buddhi-ai?style=flat-square&logo=pypi" alt="PyPI Version" />
  </a>
  <a href="https://pypi.org/project/buddhi-ai/">
    <img src="https://img.shields.io/pypi/dm/buddhi-ai?style=flat-square" alt="PyPI Downloads" />
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/github/license/Buddhilive/buddhi-cli?style=flat-square" alt="License" />
  </a>
  <img src="https://img.shields.io/badge/MCP-Compatible-green?style=flat-square" alt="MCP Compatible" />
</p>

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:
   ```bash
   git clone <repository_url>
   cd buddhi-cli
   ```

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

3. Activate the virtual environment:
   ```bash
   source .venv/bin/activate
   ```
   *(On Windows, use `.venv\Scripts\activate`)*

### From Source (Using `pip`)

Alternatively, install it in editable mode:
```bash
pip install -e .
```

---

## Usage

### 1. The `buddhi` CLI

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

```bash
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):

```bash
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:
```bash
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`:
```bash
uv build
uv tool install dist/buddhi_ai-<version>-py3-none-any.whl --force
```
To uninstall later:
```bash
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:
```bash
uv tool install -e .
```
To uninstall:
```bash
uv tool uninstall buddhi-ai
```
