Metadata-Version: 2.4
Name: fittok
Version: 0.3.2
Summary: MCP server that retrieves the most relevant source code for a query, within a token budget
Project-URL: Homepage, https://github.com/likhithreddy/fittok
Project-URL: Repository, https://github.com/likhithreddy/fittok
Project-URL: Issues, https://github.com/likhithreddy/fittok/issues
Author: Fittok Contributors
License: MIT
License-File: LICENSE
Keywords: code-analysis,context,embeddings,llm,mcp,retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: diskcache>=5.0
Requires-Dist: llmlingua>=0.0.5
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: sentence-transformers>=2.2
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: transformers<5,>=4.41
Requires-Dist: tree-sitter-go>=0.22.0
Requires-Dist: tree-sitter-java>=0.22.0
Requires-Dist: tree-sitter-javascript>=0.22.0
Requires-Dist: tree-sitter-python>=0.22.0
Requires-Dist: tree-sitter-rust>=0.22.0
Requires-Dist: tree-sitter-typescript>=0.22.0
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: watchdog>=3.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: torch>=2.0; extra == 'gpu'
Provides-Extra: ui
Requires-Dist: gradio>=4.0; extra == 'ui'
Requires-Dist: pyvis>=0.3; extra == 'ui'
Description-Content-Type: text/markdown

# fittok

**Retrieve only the relevant source code for a question — instead of the model
reading whole files — so an LLM answers codebase questions on a small, focused
slice of context.** Less input = fewer tokens, lower cost, faster answers.

Works three ways from one install: an **MCP server**, a **CLI**, and a **Python
library** — plus a **Claude Code plugin** that injects context automatically.

---

## How it works

```
codebase ──▶ graphify ──▶ slurp ──▶ readable slice ──▶ LLM answers
             (parse)      (select)   (trim to budget)
```

1. **graphify** — parses the repo with tree-sitter into a knowledge graph of
   functions / classes / methods (Python, JS, JSX, TS, TSX, Java, Go, Rust).
2. **slurp** — scores every node against the question with **semantic embeddings
   + TF-IDF + PageRank**, then selects *only* the genuinely relevant nodes via a
   relevance cliff (no budget-padding with noise).
3. **readable output** — returns the **actual source code** of those nodes,
   top-ranked in full and the supporting tail as signatures, trimmed to a budget.
   The model answers directly from it.

> Note: an earlier design compressed the slice with LLMLingua, but that produced
> unreadable token-salad the model ignored (then re-read the files). fittok
> returns **real, readable code** instead. LLMLingua remains available only as the
> standalone `compress_context` tool.

Graphs and embeddings are cached on disk (`~/.cache/fittok`), keyed by content —
so after a code change only the changed functions re-embed.

---

## Install & use

fittok runs through **[`uv`](https://docs.astral.sh/uv/)** — one tool for everything
below, with no manual `pip install`. Install it once:
```bash
brew install uv                                  # macOS
# or any OS:  curl -LsSf https://astral.sh/uv/install.sh | sh
```

### As an MCP server (recommended — Claude Code / Cursor / Windsurf)

**Claude Code — one command:**
```bash
claude mcp add fittok -- uvx fittok      # add -s user to enable it in every project
```
Restart Claude Code, then run `/mcp` to confirm `fittok` shows **connected**.

**Cursor / Windsurf / any MCP client — add to its MCP config:**
```json
{ "mcpServers": { "fittok": { "command": "uvx", "args": ["fittok"] } } }
```

Then ask codebase questions normally. To make fittok trigger **without mentioning
it**, add one line to your client's `CLAUDE.md`:
> *"For any codebase question, call fittok first and answer from its output."*

### As a CLI (no MCP, no install — `uvx` fetches + runs it)
```bash
uvx fittok index <repo>                       # optional one-time pre-warm
uvx fittok query <repo> "how does auth work"  # prints the relevant code slice
```

### As a library
```bash
uv add fittok            # in a uv project   (or:  uv pip install fittok  in a venv)
```
```python
from fittok import optimize
result = optimize("/path/to/repo", "how does authentication work")
print(result["optimized_context"])
```

First query on a repo auto-indexes (~15s once, cached); after that it's instant.

---

## Token savings — honest numbers

fittok cuts the **input/exploration cost** of a codebase question. On a real
Next.js/TS repo (~5k functions) it returns a **~1.5–3.5k-token slice** instead of
the model reading **15–20k+ tokens** of files — an **~80–90% reduction on input**,
deterministic and reported in the tool's `savings` footer.

**How to measure it honestly:**
- ✅ Use the **`savings` footer** (e.g. `84% — 2,494 vs 15,631 tokens`) or your
  **API bill** (total tokens — which counts the subagent crawls fittok avoids).
- ⚠️ Do **not** judge by Claude Code's `/context` "Messages" number — it excludes
  subagent tokens and is dominated by the model's own reasoning, which fittok
  doesn't touch. On thorough models the real saving (e.g. ~84k → ~27k total
  tokens, by avoiding an Explore subagent) is invisible there but clear on the bill.

**Where it shines:** broad / multi-file questions, large files, unfamiliar repos,
and thorough models that would otherwise explore heavily. On a tiny question a
capable model can answer from one small file, so the win is marginal there.

---

## Configuration (env vars)

| Variable | Default | Purpose |
|---|---|---|
| `FITTOK_SHOW_SAVINGS` | `true` | Append a `🪙 saved X%` footer to answers; set to `false` to disable |
| `FITTOK_EMBED_MODEL` | `all-MiniLM-L6-v2` | Embedding model |
| `FITTOK_DEVICE` | `auto` | `auto` / `cuda` / `mps` / `cpu` |
| `FITTOK_CACHE_DIR` | `~/.cache/fittok` | Cache location |

## Requirements
Python ≥ 3.10. First run downloads a ~90 MB embedding model. Optional extras:
`uv pip install "fittok[ui]"` (graph visualizer), `"fittok[gpu]"` (torch/CUDA).

## License
MIT.
