Metadata-Version: 2.4
Name: karna
Version: 0.1.0
Summary: Self-healing identity graph for AI agents. Know your code before your agent reads a single line.
Project-URL: Homepage, https://github.com/shailesht003/karna-ai
Project-URL: Documentation, https://karna.dev/docs
Project-URL: Repository, https://github.com/shailesht003/karna-ai
Author-email: Shailesh Tripathi <shailesh.tripathi003@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,claude-code,code-intelligence,cursor,developer-tools,entity-resolution,gemini-cli,mcp,token-savings
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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 :: Code Generators
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: fastmcp>=2.0
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=24.0
Requires-Dist: websockets>=14.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/karna-live-view.png" alt="Karna Live View — 3D knowledge graph visualization" width="100%">
</p>

<h1 align="center">Karna</h1>

<p align="center">
  <strong>Your codebase, as a knowledge graph. For AI agents that don't waste tokens.</strong>
</p>

<p align="center">
  <a href="https://github.com/shailesht003/karna-ai/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>&nbsp;
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>&nbsp;
  <a href="https://doi.org/10.5281/zenodo.19433427"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.19433427.svg" alt="DOI"></a>&nbsp;
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green.svg" alt="MCP Compatible"></a>
</p>

<br>

<p align="center">
  <code>pip install karna && karna serve .</code>
</p>
<p align="center">
  One command. Your AI agent now understands your entire codebase.
</p>

---

<br>

## The Problem

Every time an AI coding agent starts a task, it reads files from scratch. Each file-read stays in the conversation history and gets **retransmitted on every subsequent turn**. We call this the *Conversation History Tax* -- and it grows **quadratically** with turn count.

> An 8-turn coding session doesn't cost 8x a single turn. It costs **36x.**

The result? You're burning tokens (and money) on context the agent already saw.

<br>

## The Solution

Karna builds a **persistent knowledge graph** of your codebase -- every class, function, method, import, call, test, and contributor -- indexed and queryable in sub-second time. Instead of reading files turn after turn, your agent calls one tool and gets everything it needs.

<table>
<tr>
<td width="50%">

**Without Karna**

```
Turn 1: list_directory → 2,100 tokens
Turn 2: grep_search → 3,400 tokens
Turn 3: read_file → 4,200 tokens
Turn 4: read_file → 3,800 tokens
Turn 5: read_file → 2,900 tokens
Turn 6: read_file → 1,800 tokens
Turn 7: grep_search → 1,200 tokens
Turn 8: final answer → 1,400 tokens
────────────────────────────
Total input: ~20,800 tokens
```

</td>
<td width="50%">

**With Karna**

```
Turn 1: karna_task_context → 8,700 tokens
Turn 2: final answer → done
────────────────────────────
Total input: ~8,700 tokens



                    58% saved.



```

</td>
</tr>
</table>

<br>

## Proven Results

This isn't a benchmark game. We ran a **real agent A/B study** -- Claude Sonnet 4, live API calls, actual coding tasks on a 1,125-file production codebase (FastAPI).

| Task | Baseline | Karna | Savings |
|---|---:|---:|---:|
| Add rate limiting middleware | 17,243 | 8,613 | **50.0%** |
| Fix WebSocket authentication bug | 21,950 | 9,077 | **58.6%** |
| Refactor dependency injection | 17,096 | 8,013 | **53.1%** |
| Add response caching layer | 17,188 | 8,623 | **49.8%** |
| Improve OpenAPI generation | 30,274 | 9,403 | **68.9%** |
| | | | |
| **Mean** | **20,750** | **8,746** | **57.9%** |

> Paired *t*-test: *t*(4) = 5.18, *p* < 0.007, Cohen's *d* = 2.96 (large effect).
> Full methodology and statistical analysis in [the paper](https://doi.org/10.5281/zenodo.19433427).

<br>

## Works With Every MCP-Compatible Editor

<details>
<summary><b>Cursor</b></summary>

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "karna": {
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}
```

</details>

<details>
<summary><b>Claude Code</b></summary>

Add to `.mcp.json`:

```json
{
  "mcpServers": {
    "karna": {
      "type": "stdio",
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}
```

</details>

<details>
<summary><b>Gemini CLI</b></summary>

Add to `settings.json`:

```json
{
  "mcpServers": {
    "karna": {
      "command": "karna",
      "args": ["serve", "--no-live-view", "."]
    }
  }
}
```

</details>

<br>

## What Karna Extracts

Karna parses your code into a richly-connected graph:

| Layer | What it captures |
|---|---|
| **Entities** | Classes, functions, methods, modules, files, tests, configs, packages, contributors |
| **Relationships** | `contains`, `imports`, `calls`, `defines`, `inherits`, `tested_by`, `owned_by`, `co_changed` |
| **Call graphs** | Intra-file function-to-function call edges |
| **Body previews** | First 10 lines of every function, class, and method |
| **Git history** | Authorship, file ownership, co-change patterns |
| **Entity resolution** | Automatically discovers implicit links -- test-to-implementation, cross-module dependencies |

Validated on 1,556 source files across three repositories with **zero parse errors**:

| Repository | Language | Files | Entities | Relationships |
|---|---|---:|---:|---:|
| FastAPI | Python | 1,125 | 6,488 | 8,200 |
| Zod | TypeScript | 391 | 1,431 | 2,911 |
| Karna | Python | 40 | 446 | 1,198 |

<br>

## MCP Tools

The star tool is `karna_task_context` -- complete context in one call, one turn, minimal tokens.

| Tool | What it does |
|---|---|
| `karna_task_context(task)` | **One-shot context**: entities, files to modify, tests, relationships, body previews |
| `karna_understand(topic)` | Lightweight overview of matching entities |
| `karna_plan(task)` | Planning mode: files to modify, tests to update |
| `karna_context_for(role, task)` | Role-specific context (implementer, test writer, reviewer) |
| `karna_files_to_edit(task)` | Targeted file list with line ranges |
| `karna_read_entity(name)` | Full entity detail with call graph and relationships |
| `karna_changed(file)` | Incremental re-parse after edits |
| `karna_status()` | Graph statistics |
| `karna_who(file)` | File ownership and connections |

<br>

## Architecture

```
Source Code ──> Parsers ──> Entity Resolution ──> SQLite + FTS5 ──> MCP Server ──> AI Agents
                  |               |                    |                |
                  |-- Python AST  |-- Blocking         |-- Entities     |-- Cursor
                  |-- TypeScript  |-- Scoring (6 dim)  |-- Relationships|-- Claude Code
                  |-- Git History |-- Union-Find        |-- FTS5 Index  |-- Gemini CLI
                  |-- Filesystem                                        |-- Any MCP client
```

<br>

## Live View

Karna ships with a real-time 3D visualization of your knowledge graph (shown in the hero image above). Watch your codebase as a living, breathing graph -- with entity types color-coded, relationships traced, and agent activity highlighted live.

```bash
karna live .
# Open http://localhost:3849
```

<br>

## CLI Reference

```bash
karna init [path]            # Build the knowledge graph
karna serve [path]           # Start MCP server (+ Live View)
karna live [path]            # Start Live View only
karna status [path]          # Show graph stats
karna query [path] "topic"   # Search from terminal
```

<br>

## Research Paper

> **Karna: Reducing LLM Coding Agent Token Consumption by 58% via Persistent Code Knowledge Graphs**
> Shailesh Tripathi, 2026.
> [Read on Zenodo](https://doi.org/10.5281/zenodo.19433427)

```bibtex
@article{tripathi2026karna,
  title   = {Karna: Reducing LLM Coding Agent Token Consumption
             by 58\% via Persistent Code Knowledge Graphs},
  author  = {Tripathi, Shailesh},
  journal = {Zenodo preprint, DOI: 10.5281/zenodo.19433427},
  year    = {2026}
}
```

<br>

## Contributing

```bash
git clone https://github.com/shailesht003/karna-ai
cd karna
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest   # 89 tests, all green
```

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

<br>

## License

Apache License 2.0. See [LICENSE](LICENSE).

---

<p align="center">
  <sub>Built by <a href="https://github.com/shailesht003">Shailesh Tripathi</a> &middot; Production-grade cloud version with universal language support at <a href="https://karna.ai">karna.ai</a></sub>
</p>
