Metadata-Version: 2.4
Name: graphmind-rj
Version: 0.1.0
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/rameshj/graphmind-rj
Project-URL: Repository, https://github.com/rameshj/graphmind-rj.git
Project-URL: Bug Tracker, https://github.com/rameshj/graphmind-rj/issues
Project-URL: Documentation, https://github.com/rameshj/graphmind-rj#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"
Dynamic: requires-python

# GraphMind

**Knowledge graph builder for code and product assets with token optimization for LLMs.**

GraphMind extracts structural and semantic information from code, documentation, and data files, builds knowledge graphs, and optimizes context for LLM-assisted development in VS Code and Cursor.

## Features

- 🔍 **Multi-Language Extraction**: Python AST, SQL schemas, DOCX documents, markdown
- 📊 **Knowledge Graph Building**: NetworkX-based graph construction with community detection
- 🚀 **FastAPI Backend**: REST API for pipeline orchestration and history tracking
- 💾 **SQL Persistence**: SQLAlchemy ORM for reproducible runs
- 🧠 **Token Optimization**: Smart context packing for LLM queries (60-80% token savings)
- 📦 **CLI & API**: Command-line and REST interfaces

## Installation

```bash
pip install graphmind
```

## Quick Start

### Start Backend API

```bash
graphmind-api
# API running on http://localhost:8000
```

### Run Pipeline on Directory

```bash
graphmind run .
```

### Upload Files

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

## Architecture

### Backend Modules

- **api.py**: FastAPI service with 6+ endpoints (run, upload, history, graph, context-pack)
- **cli.py**: Command-line interface
- **pipeline.py**: Full orchestration (detect → extract → build → cluster → export)
- **extractors/**: Multi-language extraction registry
  - `python_ast.py`: Functions, classes, methods (Python)
  - `sql_schema.py`: Tables, columns, constraints (SQL)
  - `docx_semantic.py`: Structure and concepts (DOCX)
  - `text_semantic.py`: Headings and paragraphs (Markdown)
- **graph/**: Graph building and analysis
  - `builder.py`: NetworkX graph construction
  - `analytics.py`: Community detection, hub ranking
- **db.py**: SQLAlchemy ORM (RunRecord, NodeRecord, EdgeRecord)
- **context_budget.py**: Token allocation by priority tier
- **retrieval_planner.py**: Tiered context retrieval (graph → snippets → full files)
- **prompt_templates.py**: LLM-optimized templates for bug_fix, feature, refactor, test, review

### Frontend

- React + Vite dashboard for run management and visualization
- Located in `frontend/` directory

## API Endpoints

| Method | Endpoint | Purpose |
|--------|----------|---------|
| GET | `/health` | Health check |
| POST | `/api/run` | Run pipeline on directory |
| POST | `/api/upload` | Upload .md, .docx, .sql files |
| GET | `/api/runs` | List run history |
| GET | `/api/runs/{run_id}/graph` | Get graph for specific run |
| POST | `/api/context-pack` | Get optimized context for LLM |

## Example: Get Optimized Context

```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 authentication failing?",
    "token_budget": 6000
  }'
```

Response includes graph summary, code snippets, and prompt template.

## Token Savings

- **Graph Summary Tier**: ~500 tokens - graph structure only
- **Snippets Tier**: ~1500-3000 tokens - changed files + dependencies
- **Full Files Tier**: ~3000+ tokens - complete context (fallback)

Smart expansion prevents unnecessary token usage. Most queries stay in Tier 1-2.

## Development

### Install for Development

```bash
git clone https://github.com/rameshj/graphmind.git
cd graphmind
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest tests/
```

### Build Documentation

See [PUBLISH.md](PUBLISH.md) for PyPI publishing guide.

## Configuration

Create `graphmind.toml` or `graphmind.yaml` to customize:

```yaml
# Output directory
out_dir: graphmind-out

# Security settings
redact_secrets: true
redact_emails: true

# Extraction policy
extract_comments: true
extract_docstrings: true

# Graph building
min_edge_confidence: 0.5
```

## License

MIT - See LICENSE file

## Author

Ramesh J

## Support

- 📖 [GitHub](https://github.com/rameshj/graphmind)
- 🐛 [Issue Tracker](https://github.com/rameshj/graphmind/issues)
- 💬 [Discussions](https://github.com/rameshj/graphmind/discussions)
```

Backend runs on http://localhost:8000.

### 2) Start frontend

```bash
cd ramesh-graphmind/frontend
npm install
npm run dev
```

Frontend runs on http://localhost:5173.

## SQL data model

The backend stores:

1. runs: each pipeline execution summary
2. nodes: graph nodes linked to a run
3. edges: graph edges linked to a run

Database file is created at graphmind-out/graphmind.db.

## Ingestion behavior

- .md and .txt style docs: heading-based concept extraction
- .docx: paragraph and heading extraction using python-docx
- .sql: schema extraction from CREATE TABLE statements

## What to build next

1. Add auth and role-based access
2. Add migration tooling (Alembic)
3. Add richer SQL parsing for foreign keys and joins
4. Add graph diff views between runs
