Metadata-Version: 2.4
Name: knowledgetree-rag
Version: 0.1.0
Summary: Knowledge-graph-powered RAG sidecar for infrastructure querying
Author: Knowledge Tree
License-Expression: MIT
Project-URL: Homepage, https://github.com/knowledgetree-dev/kt-rag
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lightrag-hku[api]>=1.4.0
Requires-Dist: sentence-transformers>=3.0.0
Requires-Dist: transformers>=4.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: asyncpg>=0.29.0
Dynamic: license-file

<div align="center">
  <h1>kt-rag</h1>
  <p>Knowledge-graph-powered RAG sidecar for infrastructure querying</p>
</div>

<p align="center">
  <a href="https://github.com/knowledgetree-dev/kt-rag/releases"><img src="https://img.shields.io/github/v/release/knowledgetree-dev/kt-rag?style=flat&label=version" alt="Version"></a>
  <a href="https://github.com/knowledgetree-dev/kt-rag/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/knowledgetree-dev/kt-rag/ci.yml?branch=main&style=flat&label=CI" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="MIT License"></a>
  <a href="https://pypi.org/project/knowledgetree-rag/"><img src="https://img.shields.io/pypi/v/knowledgetree-rag?style=flat&label=PyPI" alt="PyPI"></a>
</p>

---

Turn your infrastructure graph into a searchable knowledge base. kt-rag feeds discovered infrastructure data — services, databases, Kubernetes clusters, DNS zones, CI/CD pipelines — into a [LightRAG](https://github.com/HKUDS/LightRAG) knowledge graph, then lets you ask questions in plain English.

**What you can do:**

- "Which services depend on Postgres?" — get a structured answer with confidence scoring
- "What's the blast radius if us-east-1 goes down?" — trace dependencies across providers
- "Show me all EC2 instances tagged `production` in eu-west-1" — filter by metadata
- "Generate a runbook for the auth service" — auto-document from live graph data
- "What changed in my infrastructure since last week?" — incremental sync awareness

## How It Works

```
┌─────────────┐    ┌──────────┐    ┌──────────┐    ┌──────┐
│ Discovery   │───▶│ kt-rag   │───▶│ LightRAG │───▶│ LLM  │
│ Plugins     │    │ seed/sync│    │ KG Store │    │      │
└─────────────┘    └──────────┘    └──────────┘    └──────┘
                        │                                
                   ┌────┴────┐                    ┌─────┴──────┐
                   │   API   │                    │  Query CLI  │
                   │  Server │                    │  / Library  │
                   └─────────┘                    └─────────────┘
```

1. **Plugins discover** your infrastructure (AWS, GitHub, K8s, etc.)
2. **kt-rag seeds** entities and relationships into LightRAG's graph store
3. **LightRAG** indexes everything for hybrid search (graph + vector)
4. **Your question** triggers retrieval-augmented generation through an LLM

## Quick Start

### Install

```bash
pip install knowledgetree-rag
```

Or from source:

```bash
git clone https://github.com/knowledgetree-dev/kt-rag.git
cd kt-rag
pip install -e .
```

### Configure

Copy the template and set your LLM API key:

```bash
cp .env.example .env
# Edit .env with your LLM provider and API key
```

Minimal `.env`:

```ini
LLM_BINDING_API_KEY=sk-...
```

### Seed the graph

Populate LightRAG from your infrastructure data:

```bash
kt-rag-seed
```

### Query

```bash
kt-rag-query "which services depend on postgres?"
```

Example output:

```
Response: The following services depend on Postgres:
  - auth-service (production, us-east-1)
  - user-api (staging, eu-west-1)
  - analytics-backend (production, us-west-2)
  - docs-service (production, us-east-1)

Confidence: 0.82
```

### Start the API server

```bash
kt-rag-server
# Listening on http://0.0.0.0:8085
```

```bash
curl -s http://localhost:8085/api/v1/rag/health
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `kt-rag-seed` | Full seed from Knowledge Tree into LightRAG |
| `kt-rag-query "..."` | Natural-language query (supports `--filter`, `--min-score`, `--profile`) |
| `kt-rag-server` | REST API on port 8085 |

## API

### Query

```json
POST /api/v1/rag/query
{
  "question": "which services depend on postgres?",
  "mode": "hybrid",
  "filter": {"provider": "aws", "region": "us-east-1"},
  "profile_name": "claude"
}
```

**Response:**

```json
{
  "response": "The following services depend on Postgres...",
  "confidence": 0.82,
  "metadata": {
    "mode": "hybrid",
    "profile": "claude",
    "tokens_used": 1247
  }
}
```

### Profile Management

```bash
# List profiles
GET /api/v1/rag/profiles

# Create profile
POST /api/v1/rag/profiles
{
  "name": "claude",
  "provider": "anthropic",
  "api_key": "sk-ant-...",
  "model": "claude-sonnet-4-20250514"
}

# Delete profile
DELETE /api/v1/rag/profiles/{name}
```

## Multi-LLM Profiles

Switch between LLM providers at query time:

```bash
# Named profiles (persisted)
kt-rag-query "what's my blast radius?" --profile claude

# Ad-hoc via headers (server mode)
curl -H "X-KT-LLM-Provider: anthropic" \
     -H "X-KT-LLM-Api-Key: sk-ant-..." \
     -d '{"question": "..."}' \
     http://localhost:8085/api/v1/rag/query
```

## Configuration

All config via environment variables or `.env`:

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_BINDING` | `openai` | LLM provider (`openai`, `anthropic`, `ollama`, `azure`) |
| `LLM_BINDING_API_KEY` | — | API key |
| `LLM_BINDING_MODEL` | `gpt-4o` | Model name |
| `EMBEDDING_BINDING` | `openai` | Embedding provider |
| `EMBEDDING_BINDING_MODEL` | `text-embedding-3-small` | Embedding model |
| `LIGHTRAG_DIR` | `./output` | LightRAG working directory |
| `LIGHTRAG_PORT` | `8085` | API server port |
| `KT_API_URL` | `http://localhost:8080` | Knowledge Tree API URL |
| `KT_API_TOKEN` | — | Knowledge Tree auth token |
| `PG_URI` | `postgresql://localhost:5432/knowledgetree` | Database (read-only seed) |
| `SYNC_INTERVAL` | `300` | Sync interval in seconds |

## Confidence Scoring

Every query response includes a 0.0–1.0 confidence score based on:

- **Retrieval quality** (30%) — how well the query matched stored entities
- **Context coverage** (30%) — how completely the retrieved data covers the question
- **Factual support** (40%) — whether the LLM's answer is grounded in retrieved facts

Set a minimum threshold:

```bash
kt-rag-query "what repos are production?" --min-score 0.6
```

## Contributing

PRs are welcome. For feature requests or major changes, open an issue first.

```bash
# Dev setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --tb=short

# Type check
mypy .
```

## Project Structure

```
├── seed.py              # Full graph seed
├── sync.py              # Incremental sync
├── query.py             # CLI query entry point
├── server.py            # FastAPI server
├── config.py            # Environment config loader
├── profile_store.py     # LLM provider profile persistence
├── scorer.py            # Confidence scoring
├── kt_client.py         # Knowledge Tree API client
├── tests/               # Test suite
└── .env.example         # Config template
```

## License

MIT
