Metadata-Version: 2.4
Name: mindretriever
Version: 0.2.1
Summary: Knowledge graph builder for code and product assets with token optimization for LLMs
Author-email: Ramesh J <ramesh@example.com>
Maintainer: Ramesh J
License-Expression: MIT
Project-URL: Homepage, https://github.com/RameshJajula/mindretriever
Project-URL: Repository, https://github.com/RameshJajula/mindretriever.git
Project-URL: Bug Tracker, https://github.com/RameshJajula/mindretriever/issues
Project-URL: Documentation, https://github.com/RameshJajula/mindretriever#readme
Keywords: knowledge-graph,code-analysis,llm,ast,context,token-optimization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: networkx>=3.2
Requires-Dist: fastapi>=0.111.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: sqlalchemy>=2.0.30
Requires-Dist: python-docx>=1.1.2
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.0; extra == "mcp"
Dynamic: requires-python

# mindretriever

Knowledge graph and context-pack tooling for AI-assisted software development.

[![PyPI version](https://img.shields.io/pypi/v/mindretriever)](https://pypi.org/project/mindretriever/)
[![Python](https://img.shields.io/pypi/pyversions/mindretriever)](https://pypi.org/project/mindretriever/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## What It Solves

Large codebases make LLM workflows noisy and expensive. Sending entire files to an assistant increases token usage, response time, and irrelevant context.

`mindretriever` solves this by:

- Building a local knowledge graph of your repo
- Selecting only task-relevant snippets for each question
- Returning a token-optimized context pack for bug fix, feature, refactor, test, review, and optimization workflows
- Tracking measurable token and cost savings over time

## Key Features

- Local-first architecture (no external indexing service required)
- Multi-language extraction across backend and frontend assets
- FastAPI service for automation and tool integration
- MCP server for native use in VS Code Copilot Chat and Cursor
- Incremental runs via file-hash cache
- Local SQLite history of runs, graph entities, and savings metrics

## Install

Basic install:

```bash
pip install mindretriever
```

Install with MCP support (recommended for VS Code/Cursor chat integration):

```bash
pip install "mindretriever[mcp]"
```

Verify CLI:

```bash
mindretriever --help
```

If command resolution fails on Windows:

```bash
python -m mindretriever --help
```

## Quick Start (CLI + API)

### 1) Analyze a repo

```bash
mindretriever run .
```

Windows-safe fallback:

```bash
python -m mindretriever run .
```

### 2) Start API

```bash
mindretriever-api
```

Windows-safe fallback:

```bash
python -m uvicorn mindretriever.api:app --host 0.0.0.0 --port 8000
```

Health check:

```bash
curl http://localhost:8000/health
```

### 3) Create a context pack for a question

```bash
curl -X POST http://localhost:8000/api/context-pack \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": 1,
    "task_type": "bug_fix",
    "query": "Why is checkout timing out after deployment?",
    "token_budget": 6000,
    "include_artifacts": true
  }'
```

### 4) Check savings proof

```bash
curl http://localhost:8000/api/savings
```

This returns:

- Per-query before/after token counts
- Estimated before/after input cost
- Aggregate total savings across all recorded queries

## Use Directly In VS Code And Cursor (MCP)

`mindretriever` includes an MCP server so chat assistants can call tools automatically while you ask normal questions.

### VS Code setup

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "mindretriever": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "graphmind.mcp_server"],
      "cwd": "${workspaceFolder}",
      "env": {}
    }
  }
}
```

### Cursor setup

Create `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mindretriever": {
      "command": "python",
      "args": ["-m", "graphmind.mcp_server"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

Then restart the editor and ask questions normally.

## MCP Tools

- `mindretriever_analyze(path=".")`
  - Builds graph and stores a run record
- `mindretriever_context(query, task_type="auto", run_id=None, token_budget=8000)`
  - Returns task-focused context pack
- `mindretriever_runs(limit=5)`
  - Lists recent analysis runs
- `mindretriever_savings(limit=20)`
  - Shows token and cost savings evidence from local history

## API Overview

| Method | Endpoint | Purpose |
|---|---|---|
| GET | `/health` | Service health |
| POST | `/api/run` | Run extraction + graph build |
| POST | `/api/upload` | Upload `.md`, `.docx`, `.sql` files |
| GET | `/api/runs` | List run history |
| GET | `/api/runs/{run_id}/graph` | Retrieve graph payload for a run |
| POST | `/api/context-pack` | Get token-aware context pack |
| GET | `/api/savings` | Show local token/cost savings history |

Upload field names:

- Preferred: `files`
- Compatibility alias: `file`

Example upload:

```bash
curl -F "files=@architecture.md" -F "files=@schema.sql" http://localhost:8000/api/upload
```

## Supported Inputs

### Detection and extraction support

| Extension group | Coverage |
|---|---|
| `.py` | Python AST extraction |
| `.sql` | SQL schema extraction |
| `.js`, `.jsx`, `.ts`, `.tsx` | TypeScript/JavaScript semantic extraction |
| `.vue`, `.svelte` | Section-aware Vue/Svelte semantic extraction |
| `.css`, `.scss` | CSS selector extraction |
| `.md`, `.txt`, `.rst` | Heading/concept extraction |
| `.docx` | Semantic extraction |
| `.go`, `.java` | Detected; deeper extraction planned |

### Vue/Svelte semantic coverage

- Script/template section-aware parsing
- Imports and component references
- Props (`defineProps`, `export let`)
- Emits (`defineEmits`)
- Stores (`$store` references)
- Slot usage (`<slot ...>`)

## CLI

```bash
mindretriever run [path] [--full]
```

- Default `path`: current directory
- Default mode: incremental
- `--full`: force full reprocessing

Legacy aliases kept for compatibility:

```bash
graphmind run .
graphmind-api
```

## Output Artifacts

Generated in `graphmind-out/`:

- `graph.json`: portable graph data
- `graph.html`: human-readable graph visualization
- `GRAPH_REPORT.md`: summary metrics
- `graphmind.db`: SQLite database (runs, nodes, edges, savings)
- `cache/file_hashes.json`: incremental cache
- `uploads/`: uploaded source documents
- `artifacts/`: cached context artifacts

## Token Savings Methodology

`mindretriever` records savings on each context request.

Definitions:

- `full_tokens`: tokens if all candidate project files were sent to the LLM
- `pack_tokens`: tokens in the generated context pack
- `saved_tokens = full_tokens - pack_tokens`
- `savings_pct = saved_tokens / full_tokens * 100`

Cost estimates:

- Uses input-token pricing table (default model: `gpt-4o`)
- Stored with each record and aggregated in `/api/savings` and `mindretriever_savings`

Token counting:

- Uses `tiktoken` when installed
- Falls back to `len(text) // 4` approximation otherwise

## Development

```bash
git clone https://github.com/RameshJajula/mindretriever.git
cd ramesh-graphmind
pip install -e ".[dev,mcp]"
python -m pytest tests -q
```

Build and validate package:

```bash
python -m build
python -m twine check dist/*
```

See [PUBLISH.md](PUBLISH.md) for release steps.

## Project Structure

```text
mindretriever/
  __init__.py
  __main__.py
  cli.py
  api.py
graphmind/
  api.py
  cli.py
  mcp_server.py
  token_counter.py
  pipeline.py
  detect.py
  db.py
  context_budget.py
  retrieval_planner.py
  prompt_templates.py
  extractors/
    python_ast.py
    sql_schema.py
    typescript_semantic.py
    vue_svelte_semantic.py
    text_semantic.py
    docx_semantic.py
  graph/
    builder.py
    analytics.py
  exporters/
    json_exporter.py
    html_exporter.py
```

## Compatibility Notes

- Python 3.10+
- SQLite is bundled with Python; no external DB required
- For Windows command resolution issues, use module invocation commands
- Legacy CLI aliases `graphmind` and `graphmind-api` remain available

## License

MIT. See [LICENSE](LICENSE).

## Links

- PyPI: https://pypi.org/project/mindretriever/
- Repository: https://github.com/RameshJajula/mindretriever
- Issues: https://github.com/RameshJajula/mindretriever/issues
