graphmind-rj 0.1.0

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

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

pip install graphmind

Quick Start

Start Backend API

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

Run Pipeline on Directory

graphmind run .

Upload Files

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

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

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

Run Tests

pytest tests/

Build Documentation

See PUBLISH.md for PyPI publishing guide.

Configuration

Create graphmind.toml or graphmind.yaml to customize:

# 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
• 🐛 Issue Tracker
• 💬 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