Metadata-Version: 2.4
Name: kinrg
Version: 1.0.4
Summary: The Context Engine for AI Coding: Persistent incremental knowledge graph for token-efficient, context-aware reviews
Project-URL: Homepage, https://kindy.ai
Project-URL: Repository, https://github.com/hotienky/kinrg
Project-URL: Documentation, https://github.com/hotienky/kinrg/blob/main/docs/INDEX.md
Project-URL: Changelog, https://github.com/hotienky/kinrg/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/hotienky/kinrg/issues
Author: kindy
License-Expression: MIT
License-File: LICENSE
Keywords: ai-coding,claude-code,code-analysis,cursor-ai,knowledge-graph,mcp-server,token-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.14.0
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: networkx<4,>=3.2
Requires-Dist: tree-sitter-language-pack<1,>=0.3.0
Requires-Dist: tree-sitter<1,>=0.23.0
Requires-Dist: watchdog<6,>=4.0.0
Provides-Extra: all
Requires-Dist: igraph>=0.11.0; extra == 'all'
Requires-Dist: matplotlib>=3.7.0; extra == 'all'
Requires-Dist: numpy<3,>=1.26; extra == 'all'
Requires-Dist: ollama>=0.1.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: sentence-transformers<4,>=3.0.0; extra == 'all'
Provides-Extra: communities
Requires-Dist: igraph>=0.11.0; extra == 'communities'
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
Requires-Dist: pytest-cov<8,>=4.0; extra == 'dev'
Requires-Dist: pytest<9,>=8.0; extra == 'dev'
Requires-Dist: ruff<1,>=0.3.0; extra == 'dev'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: numpy<3,>=1.26; extra == 'embeddings'
Requires-Dist: sentence-transformers<4,>=3.0.0; extra == 'embeddings'
Provides-Extra: eval
Requires-Dist: matplotlib>=3.7.0; extra == 'eval'
Requires-Dist: pyyaml>=6.0; extra == 'eval'
Provides-Extra: google-embeddings
Requires-Dist: google-generativeai<1,>=0.8.0; extra == 'google-embeddings'
Provides-Extra: wiki
Requires-Dist: ollama>=0.1.0; extra == 'wiki'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/kinrg_logo.png" alt="Kinrg Logo" width="160">
</p>

<h1 align="center">Kinrg: The Intelligence OS for Code Context</h1>

<p align="center">
  <strong>"Stop letting AI guess. Let AI truly understand your codebase."</strong>
</p>

<p align="center">
  <a href="https://kinrg.com"><img src="https://img.shields.io/badge/website-kinrg.com-blue?style=flat-square" alt="Website"></a>
  <a href="https://pypi.org/project/kinrg/"><img src="https://img.shields.io/pypi/v/kinrg.svg?style=flat-square" alt="PyPI"></a>
  <a href="https://github.com/hotienky/kinrg/stargazers"><img src="https://img.shields.io/github/stars/hotienky/kinrg?style=flat-square" alt="Stars"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT License"></a>
</p>

---

### 🌑 The Problem: AI is lost in your code

Most current AI tools read code linearly. In a large project (Monorepo), AI faces three hurdles:

1. **Noise**: Reading thousands of irrelevant lines, wasting tokens.
2. **Oversight**: Missing critical dependencies located in other files.
3. **Hallucination**: Providing incorrect solutions due to a lack of overall architectural understanding.

### 🔥 The Breakthrough: Graph Intelligence Layer

`kinrg` is a **Context Engine** that transforms your source code into a living Knowledge Graph. It allows your AI Agent to "see":

- **Blast Radius**: Precisely identify the impact zone of any code change.
- **Logic Flows**: Understand how data flows from entry points to core logic.
- **Smart Pruning**: Automatically strip away 95% of context noise so AI focuses on the right issue.

---

## 💎 Core Pillars

| 🚀 ULTIMATE PERFORMANCE                                                                           | 🧠 DEEP AST TECHNOLOGY                                                                          | 🌐 OPEN ECOSYSTEM                                                                               |
| :------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------- |
| **Save up to 27x Tokens** through intelligent context filtering, sending only what truly matters. | Powered by **Tree-sitter** to understand source code like a real compiler (19+ languages).      | Automatic MCP configuration for **Cursor, Claude Code, Windsurf, Zed, Continue, and OpenCode**. |
| **Updates in < 2s** even for projects with thousands of files, thanks to incremental algorithms.  | **Hybrid Search**: The perfect blend of Keyword (FTS5) and Semantic Vector Search (Embeddings). | Deeply integrated into Anthropic's **Model Context Protocol (MCP)**.                            |

---

## 🔌 Supported AI Ecosystem

With a single `kinrg install` command, you can upgrade the intelligence of:
**Cursor** • **Claude Code** • **Windsurf** • **Zed** • **Continue** • **OpenCode** • **Antigravity**

---

## ⚙️ Installation & Setup

### 1. Requirements

- **Python**: Version 3.10 or higher.
- **IDEs**: Best compatible with tools supporting MCP (Cursor, Claude Code, etc.)

### 2. Installation Methods

You can install `kinrg` flexibly via popular package managers:

```bash
# Standard installation via pip
pip install kinrg

# Install via pipx (Recommended to avoid dependency conflicts)
pipx install kinrg

# Use uv for maximum installation performance
uv tool install kinrg
```

### 3. Advanced Features (Optional)

Unlock the full power of `kinrg` by installing extension modules:

```bash
# Enable Semantic Search (Vector Embeddings)
pip install "kinrg[embeddings]"

# Enable Community & Module Structure Analysis
pip install "kinrg[communities]"

# Enable Automated Wiki Documentation (requires LLM summaries)
pip install "kinrg[wiki]"

# Install all features in a single command
pip install "kinrg[all]"
```

### 4. Connect to your AI Editor

Use the `install` command to let `kinrg` automatically detect your installed IDEs and configure the MCP Server:

```bash
kinrg install
```

_Note: To configure for a specific platform, use: `kinrg install --platform [cursor|claude-code|zed|...]`._

---

## 💡 First-time Usage Guide

To get started, open your project in an IDE (like Cursor or VS Code) and follow these steps:

1. **Build the Graph**: Type in your AI chat: _"Build the source code graph using kinrg"_.
2. **Review Code**: When you have new changes, ask: _"Review my latest changes using kinrg"_.
3. **Search**: _"Find all functions related to login using semantic search"_.

`kinrg` will run in the background, providing all necessary data for the AI to work with maximum accuracy.

---

## 🛠️ Comprehensive Intelligence: 26 MCP Tools

Your AI Agent will automatically utilize these 26 specialized tools to assist with every programming task:

### 🔍 Analysis & Review (Review & Impact)

- `audit_diff_tool`: Risk analysis and precise change boundary identification based on Git diff.
- `trace_impact_tool`: Precisely identify the "impact radius" of code changes (Blast Radius).
- `prepare_review_tool`: Provide optimized code snippets for AI review, saving tokens.
- `quick_brief_tool`: Retrieve hyper-compressed context (~100 tokens) for any task.
- `check_complexity_tool`: Detect functions/classes that are too complex based on line count.

### 🌐 Search & Graph (Search & Query)

- `smart_search_tool`: Search code using natural language or meaning (Vector Search).
- `inspect_relationships_tool`: Query Callers, Callees, Imports, Tests, and Inheritance.
- `global_search_tool`: Search source code across multiple registered projects simultaneously.
- `fetch_stats_tool`: View detailed statistics on node counts, edges, and languages.

### 🌊 Execution Flow

- `explore_flows_tool`: List major execution flows (Entry points) sorted by criticality.
- `detail_flow_tool`: Step-by-step trace of a specific source code flow.
- `check_damaged_flows_tool`: Find user flows directly affected by the code you just modified.

### 🏛️ Architecture & Community

- `generate_blueprint_tool`: Overview architecture map and coupling dependency warnings.
- `cluster_modules_tool`: Automatically cluster source code into logic modules (Leiden algorithm).
- `inspect_module_tool`: View the boundaries and members of a specific code cluster.

### 📝 Documentation & Resources (Docs & Wiki)

- `build_wiki_tool`: Automatically generate a full Markdown Wiki for the project from the graph.
- `read_wiki_tool`: Retrieve documentation content for a specific module.
- `read_manual_tool`: Quickly access technical documentation sections for `kinrg`.

### 🔧 Refactor & Database

- `refactor_advisor_tool`: Preview wide-reaching renames and detect dead code for cleanup.
- `execute_refactor_tool`: Execute refactoring changes that have been previewed.
- `catalog_database_tool`: List all database tables (SQL, Prisma, Django, etc.).
- `inspect_table_tool`: Table schema details, foreign keys, and code files querying it.

### 🏗️ Administration (Core & Registry)

- `sync_knowledge_tool`: Initialize or update the project architectural graph (Full/Incremental).
- `optimize_graph_tool`: Re-run post-processing steps (Flows, Communities, FTS) for the graph.
- `vectorize_codebase_tool`: Compute vector embeddings for the entire codebase to enable semantic search.
- `manage_registry_tool`: Manage and list repositories registered in the multi-repo system.

---

## 💻 CLI Reference

Control `kinrg` directly from your terminal using the following command suite:

| Command               | Function                                                                |
| :-------------------- | :---------------------------------------------------------------------- |
| `kinrg install`       | Auto-detect and configure MCP for IDEs.                                 |
| `kinrg index`         | Scan and build the architectural graph for the first time (Full parse). |
| `kinrg sync`          | Fast update of the graph (Processes only changed files).                |
| `kinrg report`        | View detailed statistics on nodes, edges, and graph health.             |
| `kinrg monitor`       | Watch mode: Auto-update the graph immediately upon file save.           |
| `kinrg map`           | Launch the web interface to visualize the project graph.                |
| `kinrg docs`          | Automatically generate a Markdown Wiki based on code structure.         |
| `kinrg audit`         | Risk analysis of current changes compared to Git.                       |
| `kinrg attach <path>` | Register a new project into the multi-repo management system.           |
| `kinrg registry`      | List all repositories registered in the Registry.                       |
| `kinrg serve`         | Start the MCP server to connect with AI Agents.                         |

---

## ⚡ Slash Commands

When chatting with MCP-enabled AIs (like Cursor, Claude Code, OpenCode), you can use these shortcuts:

- **`/kinrg:build-graph`**: Ask AI to update the entire project architectural map.
- **`/kinrg:review-delta`**: AI will analyze and comment on your latest code changes.
- **`/kinrg:review-pr`**: Perform a full PR review process with deep risk analysis.

---

## 📝 License

MIT. All source code data is kept secure locally within the <code>.kinrg/</code> directory.

<p align="center">
  <br>
  <a href="https://kinrg.com">Website</a> • <a href="https://github.com/kindy/kinrg">GitHub</a>
  <br><br>
  <sub>Released under the MIT License. All source code data is kept secure locally within the <code>.kinrg/</code> directory.</sub>
</p>
