Metadata-Version: 2.4
Name: buddhi-ai
Version: 2.0.0b7
Summary: Buddhi AI - Intelligent Development Assistant
Author-email: Buddhi Kavindra <info@buddhilive.com>
License-Expression: MIT
Project-URL: documentation, https://github.com/Buddhilive/buddhi-ai#readme
Project-URL: homepage, https://buddhilive.com
Project-URL: issues, https://github.com/Buddhilive/buddhi-ai/issues
Project-URL: repository, https://github.com/Buddhilive/buddhi-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.47.0
Requires-Dist: pydantic-settings>=2.2.1
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: litert-lm-api
Requires-Dist: huggingface_hub[cli]
Requires-Dist: httpx>=0.27.0
Requires-Dist: streamlit>=1.35.0
Requires-Dist: mcp>=0.1.0
Requires-Dist: networkx>=3.0
Requires-Dist: tree-sitter>=0.21.3
Requires-Dist: tree-sitter-languages>=1.10.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter-go>=0.21.0
Requires-Dist: tree-sitter-java>=0.21.0
Requires-Dist: tree-sitter-rust>=0.21.0
Requires-Dist: tree-sitter-c>=0.21.0
Requires-Dist: tree-sitter-cpp>=0.21.0
Requires-Dist: tree-sitter-ruby>=0.21.0
Requires-Dist: tree-sitter-c-sharp>=0.21.0
Requires-Dist: tree-sitter-kotlin>=0.3.0
Requires-Dist: tree-sitter-php>=0.22.0
Requires-Dist: tree-sitter-bash>=0.21.0
Requires-Dist: tree-sitter-scala>=0.21.0
Requires-Dist: tree-sitter-elixir>=0.2.0
Requires-Dist: langgraph>=0.1.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: langchain-openai>=0.1.0
Requires-Dist: openai>=1.0.0
Requires-Dist: tiktoken>=0.6.0
Dynamic: license-file

# Buddhi AI

<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-ai?style=flat-square" alt="License" />
  </a>
  <img src="https://img.shields.io/badge/MCP-Compatible-green?style=flat-square" alt="MCP Compatible" />
</p>

<p align="center">
   <img src="https://raw.githubusercontent.com/Buddhilive/buddhi-ai/refs/heads/main/public/icons/icon-128x128.png" alt="BuddhiAI Logo" />
</p>

Buddhi AI is a local AI inference server, interactive web interface, and Model Context Protocol (MCP) server designed to supercharge developer workspaces.

The backend is powered by FastAPI and LiteRT-LM, providing an ultra-fast, OpenAI-compatible local API endpoint. The frontend is built with Streamlit. Additionally, Buddhi integrates a highly-optimized MCP server (`CodeGraph`) that compiles your codebase into an AST & call-graph SQLite database for token-saving workspace exploration and command execution.

## Tech Stack

- **Backend:** Python, FastAPI, LiteRT-LM, Uvicorn
- **Frontend:** Streamlit
- **Code Graph & MCP:** SQLite, FastMCP (StdIO transport)
- **Package Management:** `uv` (Python)

## Prerequisites

Before you begin, ensure you have the following installed:

- **Python 3.10+**: Recommended to use [uv](https://github.com/astral-sh/uv) for fast, reliable dependency management.

---

## Setup & Quick Start

### 1. Backend Setup

Clone the repository and install all dependencies:

```bash
uv sync
```

### 2. Download the Model

Buddhi AI downloads models locally to the user's home directory (`~/.buddhi/models/`) to preserve space and enable shared reuse. Run the setup command:

```bash
# Downloads the gemma-4-E4B-it.litertlm model from HuggingFace
buddhi setup
```

### 3. Initialize the Workspace (MCP Server Integration)

Configure your active development environment (such as Cursor or Antigravity) to use the Buddhi MCP server by initializing the workspace:

```bash
buddhi init
```

This command will:
- Add dynamic agent workspace instruction block to `AGENTS.md`.
- Create or update `.agent/mcp_config.json` registering `buddhi-mcp`.
- Re-index your codebase AST structures and call graph automatically into SQLite.

### 4. Start the Server and UI

To run both the backend server and Streamlit interface concurrently:

```bash
buddhi live
```

- **Inference API endpoint:** `http://127.0.0.1:58421/v1`
- **Health check:** `http://127.0.0.1:58421/health`
- **Streamlit UI:** `http://127.0.0.1:58422`

---

## CLI Reference

Buddhi provides a CLI command suite:

| Command | Description |
|---------|-------------|
| `buddhi setup` | Downloads the local edge inference model. |
| `buddhi init` | Configures `AGENTS.md` and `.agent/mcp_config.json` and indexes the codebase. |
| `buddhi update` | Explicitly scans the workspace and updates the CodeGraph database. |
| `buddhi live` | Launches the FastAPI server and Streamlit chat UI concurrently. |
| `buddhi server` | Launches the FastAPI backend server only (no Streamlit UI). |
| `buddhi mcp` | Starts the FastMCP server over StdIO transport. |

---

## CodeGraph MCP Tools

The `buddhi mcp` server exposes highly optimized tools that save context tokens during AI agent interactions:

1. **`get_codebase_summary`**
   - Retrieves all classes, files, and main modules grouped by functional community clusters.
   - *Use case:* Faster high-level codebase understanding upon startup.

2. **`find_relevant_symbols`**
   - Performs exact semantic search (FTS5 SQLite search) over symbol names and AST docstrings.
   - *Use case:* Pinpoint specific functions/classes without messy, line-by-line grep output.

3. **`get_symbol_implementation`**
   - Retrieves exact source code for a symbol with a built-in guardrail: if the implementation exceeds 150 lines, it returns only the signature, docstring, and method outlines to prevent context window blowout.
   - *Use case:* Safely inspect class or method implementations.

4. **`trace_impact_radius`**
   - Recursively traces upstream call graph chains up to 3 levels deep starting at a specific symbol.
   - *Use case:* Identify the blast-radius before modifying/refactoring code.

5. **`update_codegraph`**
   - Rebuilds and updates the SQLite symbol and call dependency database.
   - *Use case:* Call this tool immediately after every successful code change or implementation to keep the symbol graph fully up to date.

6. **`index_codebase`**
   - Re-builds/syncs the SQLite symbol and call dependency database.
   - *Use case:* Run at startup or after major edits to ensure symbol synchronization.

7. **`execute_command_optimized`**
   - Executes local terminal commands and utilizes local Gemma models to summarize and format stdout/stderr into token-saving JSON.
   - *Use case:* Compile, build, and test execution analysis.

---

## Development Workflow

### Backend & CLI

- **Main Server Entry:** `server/main.py`
- **API Routes:** `server/api/routes/`
- **CLI Entry:** `cli/main.py`
- **MCP Server Entry:** `mcp/server.py`

### Frontend

- **Main App:** `ui/app.py`

---

## PyPI Publishing

To build and publish the `buddhi` CLI tool to PyPI:

1. **Build the package:**
   ```bash
   uv build
   ```

2. **Publish to PyPI:**
   ```bash
   uv publish
   ```
