knowledgetree-rag 0.1.0__py3-none-any.whl

knowledgetree_rag-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+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

knowledgetree_rag-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+knowledgetree_rag-0.1.0.dist-info/licenses/LICENSE,sha256=lzv8ZruH3OjN-UbQbSl7Qf0MEtQgaoZbV_-BdWuUwKo,1071
+tests/test_config.py,sha256=ib1MJj8Cf292Hz8Cs8VfRaQP4xsJH_e3q_G4VGMQP0M,323
+tests/test_kt_client.py,sha256=vCoPpp_9IM1xd_goBVUcQkeYFPikNuQ5ivsu8StHB3M,453
+tests/test_kt_client_async.py,sha256=7GNmmpiPT-MKli0FbAMg8eLC_EzG_JcYnTK3ifoAqZY,4419
+tests/test_metadata_filter.py,sha256=NCfTf2cc9xyQr8fP_Ttd9IqEEE89Uqqo81MsqkPiF1E,2147
+tests/test_query.py,sha256=pjuEm92i4-A3wZ740H4t99mYsAha2k8rnlYbIhesnHU,4316
+tests/test_rag_factory.py,sha256=prcL0r03ELdgLYbPRmmmyGby-myqdIUG7Mgwwtv6ueQ,1290
+tests/test_scorer.py,sha256=Ydlr0QeygpgliB7zsV0j-8Sd6Jm4wBZqgszeAeMtS5U,2794
+tests/test_seed.py,sha256=-C1YRcogpNQzWkvLFroV1wo5la98kMcVS6-rwwLFOaU,1062
+tests/test_seed_async.py,sha256=eZv1usiiTOqiIHs_lUlOna3t0jIs8cjFAyHuM3-QnO8,3310
+tests/test_sync.py,sha256=qyrYhTF06X0uxdQEIf_d314acoELR7dTF0FrFlINrOA,370
+tests/test_sync_async.py,sha256=Zrg0PtzGnityjE7uKQ70B1W37Zf6x3Z5ZBzU_ifXq7I,3215
+tests/test_sync_service.py,sha256=uZ38Jpvv3BXTh_mj-exaCHhqb_adoJNILBxYDr5tvpA,1777
+knowledgetree_rag-0.1.0.dist-info/METADATA,sha256=vVR7uwFDcVKAy90Sz0Vjg2hG16RhI8I6dW2v9NNRNuE,7879
+knowledgetree_rag-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+knowledgetree_rag-0.1.0.dist-info/entry_points.txt,sha256=B-5MVjker0KsIEx5tv6Vr8y7STxfeaHinu63U-WKDdw,96
+knowledgetree_rag-0.1.0.dist-info/top_level.txt,sha256=EdW7283x-lr_cbuivW8Ij7ANAP-ZJ9sLtILQseEPxXg,6
+knowledgetree_rag-0.1.0.dist-info/RECORD,,

knowledgetree_rag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

knowledgetree_rag-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+kt-rag-query = query:main
+kt-rag-seed = seed:main
+kt-rag-server = server:main

knowledgetree_rag-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Knowledge Tree
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

knowledgetree_rag-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tests

tests/test_config.py

@@ -0,0 +1,13 @@
+"""Tests for config module."""
+
+from __future__ import annotations
+
+from config import Config
+
+
+def test_config_defaults():
+    """Config returns sensible defaults when env vars are unset."""
+    cfg = Config()
+    assert cfg.llm_binding == "openai"
+    assert cfg.lightrag_port == 8085
+    assert cfg.sync_interval == 300

tests/test_kt_client.py

@@ -0,0 +1,16 @@
+"""Tests for kt_client module."""
+
+from __future__ import annotations
+
+import pytest
+
+from kt_client import KTClient, KTResource, KTEdge
+
+
+@pytest.mark.asyncio
+async def test_kt_client_initialization():
+    """Client can be initialized with default or custom URLs."""
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    assert client.base_url == "http://test:8080"
+    assert client.token == "test-token"
+    await client.close()

tests/test_kt_client_async.py

@@ -0,0 +1,147 @@
+"""Async tests for KTClient methods — HTTP calls mocked."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+
+@pytest.fixture
+def mock_http_client():
+    """Return a patched async HTTP client so no real connection is made."""
+    with patch("httpx.AsyncClient") as mock:
+        instance = AsyncMock()
+        mock.return_value = instance
+        yield instance
+
+
+def _mock_response(data: dict, status: int = 200):
+    """Build a mock httpx.Response — .json() is synchronous in httpx."""
+    resp = MagicMock(spec=httpx.Response)
+    resp.json.return_value = data
+    resp.raise_for_status.return_value = None
+    resp.status_code = status
+    return resp
+
+
+@pytest.mark.asyncio
+async def test_get_graph_export_parses_nodes_and_edges(mock_http_client):
+    """get_graph_export() returns correct KTGraph from API response."""
+    from kt_client import KTClient
+
+    mock_http_client.get.return_value = _mock_response({
+        "data": {
+            "nodes": [
+                {
+                    "id": "github:repo:test/a",
+                    "type": "github.repository",
+                    "name": "repo-a",
+                    "provider": "github",
+                    "properties": {"visibility": "public"},
+                    "tags": ["production"],
+                },
+            ],
+            "edges": [
+                {
+                    "source_id": "github:repo:test/a",
+                    "target_id": "github:org:test",
+                    "type": "BELONGS_TO",
+                },
+            ],
+        }
+    })
+
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    graph = await client.get_graph_export()
+
+    assert len(graph.resources) == 1
+    assert graph.resources[0].id == "github:repo:test/a"
+    assert graph.resources[0].type == "github.repository"
+
+    assert len(graph.edges) == 1
+    assert graph.edges[0].type == "BELONGS_TO"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_get_graph_export_handles_wrapped_body(mock_http_client):
+    """get_graph_export() works when API returns data directly (no wrapper)."""
+    from kt_client import KTClient
+
+    mock_http_client.get.return_value = _mock_response({
+        "nodes": [
+            {"id": "github:repo:a", "type": "github.repository", "name": "a", "provider": "github"},
+        ],
+        "edges": [],
+    })
+
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    graph = await client.get_graph_export()
+    assert len(graph.resources) == 1
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_get_resources_returns_resource_list(mock_http_client):
+    """get_resources() parses paginated resource results."""
+    from kt_client import KTClient
+
+    mock_http_client.get.return_value = _mock_response({
+        "data": {
+            "results": [
+                {
+                    "id": "github:repo:b",
+                    "type": "github.repository",
+                    "name": "repo-b",
+                    "provider": "github",
+                    "properties": {},
+                },
+            ],
+        }
+    })
+
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    resources = await client.get_resources()
+    assert len(resources) == 1
+    assert resources[0].name == "repo-b"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_get_changes_returns_change_list(mock_http_client):
+    """get_changes() returns raw change dicts."""
+    from kt_client import KTClient
+
+    mock_http_client.get.return_value = _mock_response({
+        "data": [
+            {"resourceName": "github:repo:a", "changeType": "UPDATED"},
+        ],
+    })
+
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    changes = await client.get_changes(since="2026-01-01")
+    assert len(changes) == 1
+    assert changes[0]["changeType"] == "UPDATED"
+
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_client_http_error_raises(mock_http_client):
+    """KTClient raises on HTTP errors."""
+    from kt_client import KTClient
+
+    mock_http_client.get.side_effect = httpx.HTTPStatusError(
+        "404", request=MagicMock(), response=MagicMock()
+    )
+
+    client = KTClient(base_url="http://test:8080", token="test-token")
+    with pytest.raises(httpx.HTTPStatusError):
+        await client.get_graph_export()
+
+    await client.close()

tests/test_metadata_filter.py

@@ -0,0 +1,65 @@
+"""Tests for metadata_filter module."""
+
+from __future__ import annotations
+
+import pytest
+
+from metadata_filter import MetadataFilter, ResourceMeta
+
+
+@pytest.fixture
+def populated_filter():
+    """A MetadataFilter loaded with a few test resources."""
+    mf = MetadataFilter()
+    resources = [
+        ResourceMeta(id="github:repo:a", provider="github", type="github.repository", tags={"production"}),
+        ResourceMeta(id="github:repo:b", provider="github", type="github.repository", tags={"staging"}),
+        ResourceMeta(id="aws:ec2:i-123", provider="aws", type="aws.ec2", region="eu-west-1", tags={"production"}),
+        ResourceMeta(id="aws:rds:db-456", provider="aws", type="aws.rds", region="eu-west-1", tags={"production"}),
+    ]
+    # synchronous load bypass
+    mf._resources = {r.id: r for r in resources}
+    return mf
+
+
+@pytest.mark.asyncio
+async def test_filter_by_provider(populated_filter):
+    ids = populated_filter.filter(provider="github")
+    assert ids == {"github:repo:a", "github:repo:b"}
+
+
+@pytest.mark.asyncio
+async def test_filter_by_type(populated_filter):
+    ids = populated_filter.filter(type_prefix="aws.ec2")
+    assert ids == {"aws:ec2:i-123"}
+
+
+@pytest.mark.asyncio
+async def test_filter_by_tags(populated_filter):
+    ids = populated_filter.filter(tags=["production"])
+    assert ids == {"github:repo:a", "aws:ec2:i-123", "aws:rds:db-456"}
+
+
+@pytest.mark.asyncio
+async def test_filter_by_region(populated_filter):
+    ids = populated_filter.filter(region="eu-west-1")
+    assert ids == {"aws:ec2:i-123", "aws:rds:db-456"}
+
+
+@pytest.mark.asyncio
+async def test_filter_combined(populated_filter):
+    ids = populated_filter.filter(provider="aws", tags=["production"])
+    assert ids == {"aws:ec2:i-123", "aws:rds:db-456"}
+
+
+@pytest.mark.asyncio
+async def test_filter_no_match(populated_filter):
+    ids = populated_filter.filter(provider="azure")
+    assert ids == set()
+
+
+@pytest.mark.asyncio
+async def test_filter_no_args(populated_filter):
+    """No filters returns all IDs."""
+    ids = populated_filter.filter()
+    assert ids == {"github:repo:a", "github:repo:b", "aws:ec2:i-123", "aws:rds:db-456"}

tests/test_query.py

@@ -0,0 +1,136 @@
+"""Tests for query module — all externals mocked."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_ask_empty_filter_returns_early():
+    """ask() returns early when filter matches nothing."""
+    mock_filter = MagicMock()
+    mock_filter.filter.return_value = set()
+
+    import query as q
+
+    q._filter = mock_filter
+    q._scorer = MagicMock()
+
+    text, score, meta = await q.ask("test question", filter_by={"provider": "nonexistent"})
+    assert "No resources match" in text
+    assert score == 0.0
+    assert meta["matched"] == 0
+
+
+@pytest.mark.asyncio
+async def test_ask_passes_filter_to_lightrag():
+    """ask() sends filtered IDs as context to LightRAG query."""
+    mock_filter = MagicMock()
+    mock_filter.filter.return_value = {"github:repo:a", "github:repo:b"}
+
+    mock_scorer = MagicMock()
+    mock_scorer.score = AsyncMock()
+    score_result = MagicMock()
+    score_result.overall = 0.9
+    score_result.label = "high"
+    score_result.components = {"retrieval": 0.9, "coverage": 0.9, "factual": 0.9}
+    score_result.sources = []
+    mock_scorer.score.return_value = score_result
+
+    with patch("query.create_rag") as mock_create_rag:
+        mock_rag = MagicMock()
+        mock_rag.aquery = AsyncMock(return_value="repo-a and repo-b are related")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        import query as q
+
+        q._filter = mock_filter
+        q._scorer = mock_scorer
+
+        text, score, meta = await q.ask(
+            "which repos are related?",
+            filter_by={"provider": "github"},
+        )
+
+        # IDs should be in the query text sent to LightRAG
+        call_text = mock_rag.aquery.call_args[0][0]
+        assert "github:repo:a" in call_text
+        assert "Only consider these resource IDs" in call_text
+
+
+@pytest.mark.asyncio
+async def test_ask_returns_high_confidence():
+    """ask() returns response unchanged for high confidence."""
+    mock_filter = MagicMock()
+    mock_filter.filter.return_value = {"github:repo:a"}
+
+    mock_scorer = MagicMock()
+    score_result = MagicMock()
+    score_result.overall = 0.85
+    score_result.label = "high"
+    score_result.components = {"retrieval": 0.9, "coverage": 0.8, "factual": 0.85}
+    score_result.sources = ["github:repo:a"]
+    mock_scorer.score = AsyncMock(return_value=score_result)
+
+    import query as q
+
+    q._filter = mock_filter
+    q._scorer = mock_scorer
+
+    with patch("query.create_rag") as mock_create_rag:
+        mock_rag = MagicMock()
+        mock_rag.aquery = AsyncMock(return_value="repo-a is the main repository")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        text, score, meta = await q.ask("what is repo-a?")
+
+        assert "repo-a is the main repository" in text
+        assert "Uncertainty note" not in text
+        assert score == 0.85
+        assert meta["label"] == "high"
+
+
+@pytest.mark.asyncio
+async def test_ask_low_confidence_adds_warning():
+    """ask() returns a disclaimer for low confidence responses."""
+    mock_filter = MagicMock()
+    mock_filter.filter.return_value = {"github:repo:a"}
+
+    mock_scorer = MagicMock()
+    score_result = MagicMock()
+    score_result.overall = 0.3
+    score_result.label = "low"
+    score_result.components = {"retrieval": 0.2, "coverage": 0.0, "factual": 0.5}
+    score_result.sources = []
+    mock_scorer.score = AsyncMock(return_value=score_result)
+
+    import query as q
+
+    q._filter = mock_filter
+    q._scorer = mock_scorer
+
+    with patch("query.create_rag") as mock_create_rag:
+        mock_rag = MagicMock()
+        mock_rag.aquery = AsyncMock(return_value="some vague answer")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        text, score, meta = await q.ask("what is repo-a?")
+
+        assert text.startswith("I'm not sure")
+        assert "some vague answer" in text
+
+
+def test_main_missing_args():
+    """main() exits with usage when no args given."""
+    import sys
+    from query import main
+
+    with patch.object(sys, "argv", ["query.py"]):
+        with pytest.raises(SystemExit) as exc:
+            main()
+        assert exc.value.code == 1

tests/test_rag_factory.py

@@ -0,0 +1,45 @@
+"""Tests for rag_factory module."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def test_make_llm_func_openai():
+    """_make_llm_func returns a callable with openai binding."""
+    from rag_factory import _make_llm_func
+
+    func = _make_llm_func(api_key="sk-test", model="gpt-4o", base_url=None, binding="openai")
+    assert callable(func)
+
+
+def test_make_embedding_func_openai():
+    """_make_embedding_func returns an EmbeddingFunc instance."""
+    from rag_factory import _make_embedding_func
+
+    ef = _make_embedding_func(binding="openai", model="text-embedding-3-small")
+    assert callable(ef.func)
+    assert ef.embedding_dim > 0
+
+
+@patch("rag_factory.LightRAG")
+def test_create_rag_returns_lightrag_instance(mock_lightrag):
+    """create_rag() returns a LightRAG instance."""
+    from rag_factory import create_rag
+
+    mock_instance = MagicMock()
+    mock_lightrag.return_value = mock_instance
+
+    result = create_rag()
+
+    assert result is mock_instance
+    mock_lightrag.assert_called_once()
+
+    # Verify working_dir comes from config
+    call_kwargs = mock_lightrag.call_args.kwargs
+    assert "working_dir" in call_kwargs
+    assert "llm_model_func" in call_kwargs
+    assert "embedding_func" in call_kwargs

tests/test_scorer.py

@@ -0,0 +1,84 @@
+"""Tests for scorer module."""
+
+from __future__ import annotations
+
+from scorer import Scorer, SourceChunk, ScoreResult, apply_threshold
+
+
+def test_retrieval_score_high():
+    """High similarity chunks produce a high retrieval score."""
+    scorer = Scorer()
+    chunks = [
+        SourceChunk(text="repo A", similarity=0.92),
+        SourceChunk(text="repo B", similarity=0.88),
+        SourceChunk(text="repo C", similarity=0.85),
+    ]
+    score = scorer._compute_retrieval_score(chunks)
+    assert 0.85 <= score <= 0.95
+
+
+def test_retrieval_score_empty():
+    """Empty chunks produce zero retrieval score."""
+    scorer = Scorer()
+    assert scorer._compute_retrieval_score([]) == 0.0
+
+
+def test_coverage_score_all_valid():
+    """All cited IDs are known — full coverage."""
+    scorer = Scorer(known_ids={"github:repo:test/a", "github:repo:test/b"})
+    response = "depends on github:repo:test/a and github:repo:test/b"
+    score = scorer._compute_coverage_score(response)
+    assert score == 1.0
+
+
+def test_coverage_score_partial():
+    """Some cited IDs are unknown — partial coverage."""
+    scorer = Scorer(known_ids={"github:repo:test/a"})
+    response = "depends on github:repo:test/a and github:repo:fake/x"
+    score = scorer._compute_coverage_score(response)
+    assert score == 0.5
+
+
+def test_coverage_score_no_citations():
+    """No resource IDs in response — zero coverage."""
+    scorer = Scorer()
+    response = "this repo depends on postgres"
+    score = scorer._compute_coverage_score(response)
+    assert score == 0.0
+
+
+def test_apply_threshold_high():
+    """High confidence responses pass through unchanged."""
+    result = ScoreResult(overall=0.85, label="high", components={})
+    assert apply_threshold(result, "postgres is running") == "postgres is running"
+
+
+def test_apply_threshold_medium():
+    """Medium confidence appends a disclaimer."""
+    result = ScoreResult(
+        overall=0.65,
+        label="medium",
+        components={"retrieval": 0.7, "coverage": 0.6},
+    )
+    out = apply_threshold(result, "postgres is running")
+    assert "Uncertainty note" in out
+
+
+def test_apply_threshold_low():
+    """Low confidence returns a prefixed warning."""
+    result = ScoreResult(overall=0.3, label="low", components={})
+    out = apply_threshold(result, "postgres is running")
+    assert out.startswith("I'm not sure")
+
+
+def test_extract_resource_ids():
+    """Resource ID patterns are correctly extracted."""
+    text = "Check github:repo:simonbbbb/foo and aws:ec2:i-1234"
+    ids = Scorer._extract_resource_ids(text)
+    assert "github:repo:simonbbbb/foo" in ids
+    assert "aws:ec2:i-1234" in ids
+
+
+def test_extract_resource_ids_none():
+    """No resource IDs found returns empty set."""
+    assert Scorer._extract_resource_ids("plain text") == set()

tests/test_seed.py

@@ -0,0 +1,37 @@
+"""Tests for seed module."""
+
+from __future__ import annotations
+
+from seed import _resource_to_text
+from kt_client import KTResource, KTEdge
+
+
+def test_resource_to_text_basic():
+    """A resource with no edges produces a minimal text block."""
+    r = KTResource(
+        id="github:repo:test/repo",
+        type="github.repository",
+        name="test-repo",
+        provider="github",
+        properties={"language": "Go", "visibility": "public"},
+        tags=None,
+    )
+    text = _resource_to_text(r, [])
+    assert "test-repo" in text
+    assert "github.repository" in text
+    assert "Go" in text
+
+
+def test_resource_to_text_with_edges():
+    """A resource with relationships includes them in the text."""
+    r = KTResource(
+        id="github:repo:test/repo",
+        type="github.repository",
+        name="test-repo",
+        provider="github",
+        properties={},
+        tags=None,
+    )
+    edges = [KTEdge(source_id=r.id, target_id="github:org:test", type="BELONGS_TO")]
+    text = _resource_to_text(r, edges)
+    assert "BELONGS_TO" in text

tests/test_seed_async.py

@@ -0,0 +1,115 @@
+"""Async tests for seed module — all externals mocked."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from kt_client import KTEdge, KTGraph, KTResource
+
+
+@pytest.mark.asyncio
+async def test_seed_empty_graph():
+    """seed() returns early when the graph has no resources."""
+    with (
+        patch("seed.KTClient") as mock_kt_cls,
+        patch("seed.create_rag") as mock_create_rag,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_graph_export.return_value = KTGraph(resources=[], edges=[])
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        from seed import seed
+
+        await seed()
+
+        mock_kt.get_graph_export.assert_awaited_once()
+        mock_create_rag.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_seed_with_resources():
+    """seed() inserts each resource into LightRAG."""
+    resources = [
+        KTResource(
+            id="github:repo:test/a",
+            type="github.repository",
+            name="repo-a",
+            provider="github",
+            properties={"visibility": "public"},
+            tags=["production"],
+        ),
+        KTResource(
+            id="github:repo:test/b",
+            type="github.repository",
+            name="repo-b",
+            provider="github",
+            properties={"visibility": "private"},
+            tags=["staging"],
+        ),
+    ]
+    edges = [
+        KTEdge(source_id="github:repo:test/a", target_id="github:org:test", type="BELONGS_TO")
+    ]
+
+    with (
+        patch("seed.KTClient") as mock_kt_cls,
+        patch("seed.create_rag") as mock_create_rag,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_graph_export.return_value = KTGraph(resources=resources, edges=edges)
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        mock_rag = MagicMock()
+        mock_rag.ainsert = AsyncMock(return_value="doc-1")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        from seed import seed
+
+        await seed()
+
+        assert mock_rag.ainsert.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_seed_counts_insertions():
+    """seed() counts resources that return a truthy doc_id."""
+    resources = [
+        KTResource(
+            id="github:repo:test/a",
+            type="github.repository",
+            name="repo-a",
+            provider="github",
+            properties={},
+            tags=None,
+        ),
+        KTResource(
+            id="github:repo:test/b",
+            type="github.repository",
+            name="repo-b",
+            provider="github",
+            properties={},
+            tags=None,
+        ),
+    ]
+
+    with (
+        patch("seed.KTClient") as mock_kt_cls,
+        patch("seed.create_rag") as mock_create_rag,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_graph_export.return_value = KTGraph(resources=resources, edges=[])
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        mock_rag = MagicMock()
+        mock_rag.ainsert = AsyncMock(side_effect=["doc-1", ""])
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        from seed import seed
+
+        await seed()
+
+        assert mock_rag.ainsert.await_count == 2

tests/test_sync.py

@@ -0,0 +1,15 @@
+"""Tests for sync module."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_sync_noop_when_no_changes():
+    """Sync returns 0 when there are no changes."""
+    # Integration test — requires running KT + LightRAG
+    # from sync import sync
+    # count = await sync(since="2100-01-01")
+    # assert count == 0
+    assert True

tests/test_sync_async.py

@@ -0,0 +1,99 @@
+"""Async tests for sync module — all externals mocked."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from kt_client import KTResource
+
+
+@pytest.mark.asyncio
+async def test_sync_no_changes():
+    """sync() returns 0 when there are no changes."""
+    with (
+        patch("sync.create_rag") as mock_create_rag,
+        patch("sync.KTClient") as mock_kt_cls,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_changes.return_value = []
+        mock_kt.get_resources.return_value = []
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        mock_rag = MagicMock()
+        mock_rag.ainsert = AsyncMock(return_value="doc-1")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        from sync import sync
+
+        count = await sync(since="2100-01-01")
+        assert count == 0
+        mock_rag.ainsert.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_sync_with_changes():
+    """sync() inserts only changed resources."""
+    with (
+        patch("sync.create_rag") as mock_create_rag,
+        patch("sync.KTClient") as mock_kt_cls,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_changes.return_value = [
+            {"resourceName": "github:repo:test/a"},
+            {"resourceName": "github:repo:test/b"},
+        ]
+        mock_kt.get_resources.return_value = [
+            KTResource(
+                id="github:repo:test/a", type="github.repository",
+                name="repo-a", provider="github", properties={}, tags=None,
+            ),
+            KTResource(
+                id="github:repo:test/b", type="github.repository",
+                name="repo-b", provider="github", properties={}, tags=None,
+            ),
+            KTResource(
+                id="github:repo:test/c", type="github.repository",
+                name="repo-c", provider="github", properties={}, tags=None,
+            ),
+        ]
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        mock_rag = MagicMock()
+        mock_rag.ainsert = AsyncMock(return_value="doc-id")
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        from sync import sync
+
+        count = await sync(since="2100-01-01")
+        assert count == 2
+        assert mock_rag.ainsert.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_sync_default_since():
+    """sync() sets default since to 24 hours ago when not provided."""
+    with (
+        patch("sync.create_rag") as mock_create_rag,
+        patch("sync.KTClient") as mock_kt_cls,
+    ):
+        mock_kt = AsyncMock()
+        mock_kt.get_changes.return_value = []
+        mock_kt.get_resources.return_value = []
+        mock_kt_cls.return_value.__aenter__.return_value = mock_kt
+
+        mock_rag = MagicMock()
+        mock_rag.initialize_storages = AsyncMock()
+        mock_create_rag.return_value = mock_rag
+
+        from sync import sync
+
+        await sync()  # no since arg
+
+        # Should have been called with a recent ISO date
+        call_args = mock_kt.get_changes.call_args
+        call_since = call_args[1]["since"]
+        assert "T" in call_since

tests/test_sync_service.py

@@ -0,0 +1,70 @@
+"""Tests for sync_service module — daemon loop behavior."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+@pytest.fixture
+def mock_config():
+    """Patch sync_service.config with a mutable version."""
+    cfg = MagicMock()
+    cfg.sync_interval = 1  # short interval for tests
+    with patch("sync_service.config", cfg):
+        yield cfg
+
+
+@pytest.mark.asyncio
+async def test_sync_service_loop_calls_sync(mock_config):
+    """run_loop() calls sync() and stops."""
+    with patch("sync_service.sync") as mock_sync:
+        mock_sync.return_value = 0
+
+        import sync_service as svc
+
+        svc._running = True
+
+        from sync_service import run_loop
+
+        async def runner():
+            task = asyncio.create_task(run_loop())
+            await asyncio.sleep(0.15)
+            svc._running = False
+            await task
+
+        await runner()
+        mock_sync.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_sync_service_handles_exception(mock_config):
+    """run_loop() logs errors and continues on sync failure."""
+    with patch("sync_service.sync") as mock_sync:
+        mock_sync.side_effect = [ValueError("KT unreachable"), 0]
+
+        import sync_service as svc
+
+        svc._running = True
+        from sync_service import run_loop
+
+        async def runner():
+            task = asyncio.create_task(run_loop())
+            await asyncio.sleep(2.5)
+            svc._running = False
+            await task
+
+        await runner()
+
+        assert mock_sync.await_count >= 2
+
+
+def test_sync_service_shutdown_signal():
+    """_shutdown sets _running to False."""
+    import sync_service as svc
+
+    svc._running = True
+    svc._shutdown(2, None)
+    assert svc._running is False