kgmodule-utils 0.3.0__tar.gz → 0.3.1__tar.gz

kgmodule_utils-0.3.1/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: kgmodule-utils
+Version: 0.3.1
+Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
+License: Elastic-2.0
+License-File: LICENSE
+Keywords: knowledge-graph,kgmodule,sdk,types,snapshots
+Author: Eric G. Suchanek, PhD
+Author-email: suchanek@flux-frontiers.com
+Requires-Python: >=3.12,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: semantic
+Requires-Dist: lancedb (>=0.19.0) ; extra == "semantic"
+Requires-Dist: numpy (>=1.24.0) ; extra == "semantic"
+Requires-Dist: sentence-transformers (>=5.4.1) ; extra == "semantic"
+Requires-Dist: torch (>=2.5.1) ; extra == "semantic"
+Requires-Dist: transformers (>=4.40.0,<4.57) ; extra == "semantic"
+Project-URL: Repository, https://github.com/Flux-Frontiers/kg_utils
+Description-Content-Type: text/markdown
+
+
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
+[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
+[![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+
+# kgmodule-utils
+
+**kgmodule-utils** — Shared graph store, semantic index, pipeline base, and snapshot infrastructure for the KGModule SDK.
+
+*Author: Eric G. Suchanek, PhD*
+
+*Flux-Frontiers, Liberty TWP, OH*
+
+---
+
+## Overview
+
+kgmodule-utils is the **shared SDK layer** for the Flux-Frontiers knowledge-graph ecosystem. It provides everything a domain KG module needs — from type abstractions and SQLite graph storage through LanceDB vector indexing and a full build/query/pack pipeline — so domain authors implement only what is specific to their source domain.
+
+Every KGModule implementation — [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [DocKG](https://github.com/Flux-Frontiers/doc_kg), and others — subclasses `KGModule` from here and implements exactly three methods: `make_extractor()`, `kind()`, and `analyze()`.
+
+---
+
+## Features
+
+- **`kg_utils.specs`** — `NodeSpec`, `EdgeSpec`, `BuildStats`, `QueryResult`, `SnippetPack` dataclasses
+- **`kg_utils.extractor`** — `KGExtractor` ABC: `extract()`, `node_kinds()`, `edge_kinds()`, `coverage_metric()`
+- **`kg_utils.store`** — `GraphStore`: SQLite-backed node/edge store with BFS expansion, symbol resolution, caller lookup, and provenance recording
+- **`kg_utils.semantic`** — `SemanticIndex` (LanceDB), `SentenceTransformerEmbedder`, `SeedHit`, model registry, `resolve_model_path()`
+- **`kg_utils.pipeline`** — `KGModule`: full build → query → pack pipeline base with hybrid semantic + lexical reranking and snippet extraction
+- **`kg_utils.embedder`** — `get_embedder()`, `wrap_embedder()`, `load_sentence_transformer()` factory functions
+- **`kg_utils.embed`** — `Embedder` protocol, `DEFAULT_MODEL`, `KNOWN_MODELS`, `resolve_model_path()`
+- **`kg_utils.snapshots`** — `Snapshot`, `SnapshotManager`, `SnapshotManifest` for temporal metric tracking
+
+---
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, < 3.14
+
+### Core only (stdlib, no optional deps)
+
+```bash
+pip install kgmodule-utils
+```
+
+### With semantic search (LanceDB + sentence-transformers)
+
+```bash
+pip install 'kgmodule-utils[semantic]'
+```
+
+### In a Poetry project
+
+```toml
+[tool.poetry.dependencies]
+kgmodule-utils = { version = ">=0.3.1", extras = ["semantic"] }
+```
+
+---
+
+## Quick Start
+
+### Build a domain KG module
+
+```python
+from collections.abc import Iterator
+from pathlib import Path
+
+from kg_utils.extractor import KGExtractor
+from kg_utils.pipeline import KGModule
+from kg_utils.specs import EdgeSpec, NodeSpec
+
+
+class MyExtractor(KGExtractor):
+    def node_kinds(self) -> list[str]:
+        return ["document", "section"]
+
+    def edge_kinds(self) -> list[str]:
+        return ["CONTAINS"]
+
+    def meaningful_node_kinds(self) -> list[str]:
+        return ["section"]
+
+    def extract(self) -> Iterator[NodeSpec | EdgeSpec]:
+        for doc in self.repo_path.glob("**/*.md"):
+            doc_id = f"document:{doc}"
+            yield NodeSpec(node_id=doc_id, kind="document",
+                           name=doc.stem, qualname=doc.stem,
+                           source_path=str(doc))
+            # … yield sections and CONTAINS edges
+
+
+class MyKG(KGModule):
+    _default_dir = ".mykg"
+
+    def make_extractor(self) -> KGExtractor:
+        return MyExtractor(self.repo_root)
+
+    def kind(self) -> str:
+        return "my"
+
+    def analyze(self) -> str:
+        s = self.stats()
+        return f"# MyKG\nnodes={s['total_nodes']}"
+
+
+# Build and query
+kg = MyKG("/path/to/repo")
+kg.build(wipe=True)
+
+result = kg.query("authentication flow", k=8, hop=1)
+pack   = kg.pack("error handling", max_nodes=10)
+print(pack.to_markdown())
+```
+
+### Track metrics over time
+
+```python
+from kg_utils.snapshots import SnapshotManager
+
+mgr = SnapshotManager(".mykg/snapshots", package_name="my-kg")
+
+snapshot = mgr.capture(
+    version="1.0.0",
+    branch="main",
+    graph_stats_dict=kg.stats(),
+)
+mgr.save_snapshot(snapshot)
+
+snaps = mgr.list_snapshots(limit=5)
+delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
+```
+
+---
+
+## API Reference
+
+### `kg_utils.specs`
+
+| Class | Description |
+|---|---|
+| `NodeSpec` | Graph node: `node_id`, `kind`, `name`, `qualname`, `source_path`, `lineno`, `end_lineno`, `docstring`, `metadata` |
+| `EdgeSpec` | Graph edge: `source_id`, `target_id`, `relation`, `weight`, `metadata` |
+| `BuildStats` | Build result: node/edge counts, indexed rows, embedding dim |
+| `QueryResult` | Query result: nodes, edges, seeds, hop, relevance metadata |
+| `SnippetPack` | Pack result: nodes with snippets, `to_markdown()`, `to_json()`, `save()` |
+
+### `kg_utils.extractor`
+
+| Class | Description |
+|---|---|
+| `KGExtractor` | ABC — implement `node_kinds()`, `edge_kinds()`, `extract()` |
+
+### `kg_utils.store`
+
+| Class | Description |
+|---|---|
+| `GraphStore` | SQLite persistence: `write()`, `expand()`, `query_nodes()`, `resolve_symbols()`, `callers_of()`, `stats()` |
+
+### `kg_utils.semantic`
+
+| Class / function | Description |
+|---|---|
+| `SemanticIndex` | LanceDB vector index: `build()`, `search()` |
+| `SentenceTransformerEmbedder` | Local embedding via sentence-transformers |
+| `resolve_model_path()` | Resolve model name / alias to local cache path |
+| `suppress_ingestion_logging()` | Silence verbose HF / tqdm output during ingestion |
+
+### `kg_utils.pipeline`
+
+| Class | Description |
+|---|---|
+| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()` for free |
+
+### `kg_utils.snapshots`
+
+| Class | Description |
+|---|---|
+| `Snapshot` | Temporal snapshot keyed by git tree hash with metrics and deltas |
+| `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
+| `SnapshotManifest` | Fast-lookup index with format versioning |
+
+---
+
+## Project Structure
+
+```
+KG_utils/
+├── pyproject.toml
+├── src/
+│   └── kg_utils/
+│       ├── __init__.py
+│       ├── specs.py          # NodeSpec, EdgeSpec, BuildStats, QueryResult, SnippetPack
+│       ├── extractor.py      # KGExtractor ABC
+│       ├── store.py          # GraphStore (SQLite)
+│       ├── semantic.py       # SemanticIndex, SentenceTransformerEmbedder, SeedHit
+│       ├── pipeline.py       # KGModule concrete base class
+│       ├── module.py         # Re-export shim
+│       ├── embed.py          # Embedder protocol, model registry
+│       ├── embedder.py       # SentenceTransformerEmbedder factory functions
+│       └── snapshots/
+│           ├── __init__.py
+│           ├── models.py     # Snapshot, SnapshotManifest, PruneResult
+│           └── manager.py    # SnapshotManager
+└── tests/
+    ├── test_store.py          # GraphStore unit tests
+    ├── test_pipeline_utils.py # Pipeline utility function tests
+    ├── test_pipeline_module.py # End-to-end integration tests (--integration)
+    ├── test_types.py          # Spec dataclass and KGExtractor tests
+    ├── test_snapshots.py      # Snapshot lifecycle tests
+    └── test_integration.py    # Cross-module integration tests
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Flux-Frontiers/KG_utils.git
+cd KG_utils
+poetry install --with dev
+```
+
+Run the fast test suite (no model downloads):
+
+```bash
+poetry run pytest -m "not integration"
+```
+
+Run all tests including semantic/integration (requires `[semantic]` extra):
+
+```bash
+poetry run pytest
+```
+
+---
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
+
+Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial use internally is permitted.
+

kgmodule_utils-0.3.1/README.md

@@ -0,0 +1,245 @@
+
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
+[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
+[![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
+[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
+
+# kgmodule-utils
+
+**kgmodule-utils** — Shared graph store, semantic index, pipeline base, and snapshot infrastructure for the KGModule SDK.
+
+*Author: Eric G. Suchanek, PhD*
+
+*Flux-Frontiers, Liberty TWP, OH*
+
+---
+
+## Overview
+
+kgmodule-utils is the **shared SDK layer** for the Flux-Frontiers knowledge-graph ecosystem. It provides everything a domain KG module needs — from type abstractions and SQLite graph storage through LanceDB vector indexing and a full build/query/pack pipeline — so domain authors implement only what is specific to their source domain.
+
+Every KGModule implementation — [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [DocKG](https://github.com/Flux-Frontiers/doc_kg), and others — subclasses `KGModule` from here and implements exactly three methods: `make_extractor()`, `kind()`, and `analyze()`.
+
+---
+
+## Features
+
+- **`kg_utils.specs`** — `NodeSpec`, `EdgeSpec`, `BuildStats`, `QueryResult`, `SnippetPack` dataclasses
+- **`kg_utils.extractor`** — `KGExtractor` ABC: `extract()`, `node_kinds()`, `edge_kinds()`, `coverage_metric()`
+- **`kg_utils.store`** — `GraphStore`: SQLite-backed node/edge store with BFS expansion, symbol resolution, caller lookup, and provenance recording
+- **`kg_utils.semantic`** — `SemanticIndex` (LanceDB), `SentenceTransformerEmbedder`, `SeedHit`, model registry, `resolve_model_path()`
+- **`kg_utils.pipeline`** — `KGModule`: full build → query → pack pipeline base with hybrid semantic + lexical reranking and snippet extraction
+- **`kg_utils.embedder`** — `get_embedder()`, `wrap_embedder()`, `load_sentence_transformer()` factory functions
+- **`kg_utils.embed`** — `Embedder` protocol, `DEFAULT_MODEL`, `KNOWN_MODELS`, `resolve_model_path()`
+- **`kg_utils.snapshots`** — `Snapshot`, `SnapshotManager`, `SnapshotManifest` for temporal metric tracking
+
+---
+
+## Installation
+
+**Requirements:** Python ≥ 3.12, < 3.14
+
+### Core only (stdlib, no optional deps)
+
+```bash
+pip install kgmodule-utils
+```
+
+### With semantic search (LanceDB + sentence-transformers)
+
+```bash
+pip install 'kgmodule-utils[semantic]'
+```
+
+### In a Poetry project
+
+```toml
+[tool.poetry.dependencies]
+kgmodule-utils = { version = ">=0.3.1", extras = ["semantic"] }
+```
+
+---
+
+## Quick Start
+
+### Build a domain KG module
+
+```python
+from collections.abc import Iterator
+from pathlib import Path
+
+from kg_utils.extractor import KGExtractor
+from kg_utils.pipeline import KGModule
+from kg_utils.specs import EdgeSpec, NodeSpec
+
+
+class MyExtractor(KGExtractor):
+    def node_kinds(self) -> list[str]:
+        return ["document", "section"]
+
+    def edge_kinds(self) -> list[str]:
+        return ["CONTAINS"]
+
+    def meaningful_node_kinds(self) -> list[str]:
+        return ["section"]
+
+    def extract(self) -> Iterator[NodeSpec | EdgeSpec]:
+        for doc in self.repo_path.glob("**/*.md"):
+            doc_id = f"document:{doc}"
+            yield NodeSpec(node_id=doc_id, kind="document",
+                           name=doc.stem, qualname=doc.stem,
+                           source_path=str(doc))
+            # … yield sections and CONTAINS edges
+
+
+class MyKG(KGModule):
+    _default_dir = ".mykg"
+
+    def make_extractor(self) -> KGExtractor:
+        return MyExtractor(self.repo_root)
+
+    def kind(self) -> str:
+        return "my"
+
+    def analyze(self) -> str:
+        s = self.stats()
+        return f"# MyKG\nnodes={s['total_nodes']}"
+
+
+# Build and query
+kg = MyKG("/path/to/repo")
+kg.build(wipe=True)
+
+result = kg.query("authentication flow", k=8, hop=1)
+pack   = kg.pack("error handling", max_nodes=10)
+print(pack.to_markdown())
+```
+
+### Track metrics over time
+
+```python
+from kg_utils.snapshots import SnapshotManager
+
+mgr = SnapshotManager(".mykg/snapshots", package_name="my-kg")
+
+snapshot = mgr.capture(
+    version="1.0.0",
+    branch="main",
+    graph_stats_dict=kg.stats(),
+)
+mgr.save_snapshot(snapshot)
+
+snaps = mgr.list_snapshots(limit=5)
+delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
+```
+
+---
+
+## API Reference
+
+### `kg_utils.specs`
+
+| Class | Description |
+|---|---|
+| `NodeSpec` | Graph node: `node_id`, `kind`, `name`, `qualname`, `source_path`, `lineno`, `end_lineno`, `docstring`, `metadata` |
+| `EdgeSpec` | Graph edge: `source_id`, `target_id`, `relation`, `weight`, `metadata` |
+| `BuildStats` | Build result: node/edge counts, indexed rows, embedding dim |
+| `QueryResult` | Query result: nodes, edges, seeds, hop, relevance metadata |
+| `SnippetPack` | Pack result: nodes with snippets, `to_markdown()`, `to_json()`, `save()` |
+
+### `kg_utils.extractor`
+
+| Class | Description |
+|---|---|
+| `KGExtractor` | ABC — implement `node_kinds()`, `edge_kinds()`, `extract()` |
+
+### `kg_utils.store`
+
+| Class | Description |
+|---|---|
+| `GraphStore` | SQLite persistence: `write()`, `expand()`, `query_nodes()`, `resolve_symbols()`, `callers_of()`, `stats()` |
+
+### `kg_utils.semantic`
+
+| Class / function | Description |
+|---|---|
+| `SemanticIndex` | LanceDB vector index: `build()`, `search()` |
+| `SentenceTransformerEmbedder` | Local embedding via sentence-transformers |
+| `resolve_model_path()` | Resolve model name / alias to local cache path |
+| `suppress_ingestion_logging()` | Silence verbose HF / tqdm output during ingestion |
+
+### `kg_utils.pipeline`
+
+| Class | Description |
+|---|---|
+| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()` for free |
+
+### `kg_utils.snapshots`
+
+| Class | Description |
+|---|---|
+| `Snapshot` | Temporal snapshot keyed by git tree hash with metrics and deltas |
+| `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
+| `SnapshotManifest` | Fast-lookup index with format versioning |
+
+---
+
+## Project Structure
+
+```
+KG_utils/
+├── pyproject.toml
+├── src/
+│   └── kg_utils/
+│       ├── __init__.py
+│       ├── specs.py          # NodeSpec, EdgeSpec, BuildStats, QueryResult, SnippetPack
+│       ├── extractor.py      # KGExtractor ABC
+│       ├── store.py          # GraphStore (SQLite)
+│       ├── semantic.py       # SemanticIndex, SentenceTransformerEmbedder, SeedHit
+│       ├── pipeline.py       # KGModule concrete base class
+│       ├── module.py         # Re-export shim
+│       ├── embed.py          # Embedder protocol, model registry
+│       ├── embedder.py       # SentenceTransformerEmbedder factory functions
+│       └── snapshots/
+│           ├── __init__.py
+│           ├── models.py     # Snapshot, SnapshotManifest, PruneResult
+│           └── manager.py    # SnapshotManager
+└── tests/
+    ├── test_store.py          # GraphStore unit tests
+    ├── test_pipeline_utils.py # Pipeline utility function tests
+    ├── test_pipeline_module.py # End-to-end integration tests (--integration)
+    ├── test_types.py          # Spec dataclass and KGExtractor tests
+    ├── test_snapshots.py      # Snapshot lifecycle tests
+    └── test_integration.py    # Cross-module integration tests
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Flux-Frontiers/KG_utils.git
+cd KG_utils
+poetry install --with dev
+```
+
+Run the fast test suite (no model downloads):
+
+```bash
+poetry run pytest -m "not integration"
+```
+
+Run all tests including semantic/integration (requires `[semantic]` extra):
+
+```bash
+poetry run pytest
+```
+
+---
+
+## License
+
+[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
+
+Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial use internally is permitted.

{kgmodule_utils-0.3.0 → kgmodule_utils-0.3.1}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "kgmodule-utils"
-version = "0.3.0"
+version = "0.3.1"
 description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
 readme = "README.md"
 license = { text = "Elastic-2.0" }

{kgmodule_utils-0.3.0 → kgmodule_utils-0.3.1}/src/kg_utils/__init__.py

@@ -1,8 +1,8 @@
 """kg_utils — Shared types, store, semantic index, and pipeline base for the KGModule SDK.
 
 Sub-packages / modules:
-    kg_utils.types      — NodeSpec, EdgeSpec, BuildStats, QueryResult, SnippetPack,
-                          KGExtractor (abstract), KGModule (abstract interface).
+    kg_utils.specs      — NodeSpec, EdgeSpec, BuildStats, QueryResult, SnippetPack.
+    kg_utils.extractor  — KGExtractor abstract base class.
     kg_utils.store      — GraphStore: SQLite-backed authoritative node/edge store.
     kg_utils.semantic   — Embedder, SentenceTransformerEmbedder, SemanticIndex, SeedHit.
     kg_utils.pipeline   — KGModule: concrete base class with full build/query/pack pipeline.
@@ -17,4 +17,4 @@ Optional extras
     pip install 'kgmodule-utils[semantic]'   # lancedb + sentence-transformers
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"

kgmodule_utils-0.3.0/PKG-INFO

@@ -1,216 +0,0 @@
-Metadata-Version: 2.4
-Name: kgmodule-utils
-Version: 0.3.0
-Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
-License: Elastic-2.0
-License-File: LICENSE
-Keywords: knowledge-graph,kgmodule,sdk,types,snapshots
-Author: Eric G. Suchanek, PhD
-Author-email: suchanek@flux-frontiers.com
-Requires-Python: >=3.12,<3.14
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Provides-Extra: semantic
-Requires-Dist: lancedb (>=0.19.0) ; extra == "semantic"
-Requires-Dist: numpy (>=1.24.0) ; extra == "semantic"
-Requires-Dist: sentence-transformers (>=5.4.1) ; extra == "semantic"
-Requires-Dist: torch (>=2.5.1) ; extra == "semantic"
-Requires-Dist: transformers (>=4.40.0,<4.57) ; extra == "semantic"
-Project-URL: Repository, https://github.com/Flux-Frontiers/kg_utils
-Description-Content-Type: text/markdown
-
-
-[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
-[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
-[![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
-[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-
-# kgmodule-utils
-
-**kgmodule-utils** — Shared types and snapshot infrastructure for the KGModule SDK.
-
-*Author: Eric G. Suchanek, PhD*
-
-*Flux-Frontiers, Liberty TWP, OH*
-
----
-
-## Overview
-
-kgmodule-utils is the **zero-dependency foundation package** for the Flux-Frontiers knowledge-graph ecosystem. It provides the canonical type abstractions and temporal snapshot infrastructure that all KGModule implementations — [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [FTreeKG](https://github.com/Flux-Frontiers/ftree_kg), [DocKG](https://github.com/Flux-Frontiers/doc_kg), [AgentKG](https://github.com/Flux-Frontiers/agent_kg) — depend on.
-
-Every KGModule shares the same `NodeSpec`, `EdgeSpec`, `KGExtractor`, and `KGModule` base classes defined here, ensuring consistent interfaces across the ecosystem. The snapshot subsystem enables temporal metric tracking, delta comparison, and pruning across git commits.
-
----
-
-## Features
-
-- **Core type abstractions** — `NodeSpec`, `EdgeSpec`, `QueryResult`, `SnippetPack` dataclasses for knowledge-graph nodes, edges, and query results
-- **KGExtractor base class** — Abstract interface for domain-specific extractors with `extract()`, `node_kinds()`, `edge_kinds()`, and `coverage_metric()`
-- **KGModule base class** — Abstract interface for knowledge-graph modules with `build()`, `query()`, `pack()`, `stats()`, and `analyze()`
-- **Snapshot models** — `Snapshot` dataclass keyed by git tree hash with free-form metrics, hotspots, issues, and delta tracking
-- **SnapshotManager** — Capture, persist, load, list, diff, and prune snapshots with automatic deduplication and delta computation
-- **SnapshotManifest** — Fast-lookup index of all snapshots with format versioning
-- **Zero dependencies** — Stdlib-only; no external packages required at runtime
-
----
-
-## Installation
-
-**Requirements:** Python ≥ 3.12, < 3.14
-
-### Standalone (pip)
-
-```bash
-pip install kgmodule-utils
-```
-
-### Existing Poetry project
-
-```bash
-poetry add kgmodule-utils
-```
-
-Or declare it directly in your `pyproject.toml`:
-
-```toml
-[tool.poetry.dependencies]
-kgmodule-utils = "^0.2.0"
-```
-
----
-
-## Quick Start
-
-### Types — Define a KGModule
-
-```python
-from kg_utils.types import NodeSpec, EdgeSpec, KGExtractor, KGModule
-
-class MyExtractor(KGExtractor):
-    def node_kinds(self) -> list[str]:
-        return ["module", "function", "class"]
-
-    def edge_kinds(self) -> list[str]:
-        return ["CONTAINS", "CALLS", "IMPORTS"]
-
-    def extract(self, source_root: str):
-        # Yield NodeSpec and EdgeSpec objects from your domain
-        yield NodeSpec(
-            node_id="fn:main:hello",
-            kind="function",
-            name="hello",
-            qualname="main.hello",
-            source_path="main.py",
-            docstring="Greet the user.",
-        )
-        yield EdgeSpec(
-            source_id="mod:main",
-            target_id="fn:main:hello",
-            relation="CONTAINS",
-        )
-```
-
-### Snapshots — Track metrics over time
-
-```python
-from kg_utils.snapshots import SnapshotManager
-
-mgr = SnapshotManager(snapshots_dir=".my_kg/snapshots", package_name="my-kg")
-
-# Capture a snapshot from current metrics
-snapshot = mgr.capture(metrics={
-    "total_nodes": 142,
-    "total_edges": 387,
-    "coverage": 0.78,
-})
-
-# Save with automatic deduplication
-mgr.save_snapshot(snapshot)
-
-# List and compare
-snaps = mgr.list_snapshots(limit=5)
-delta = mgr.diff_snapshots(key_a=snaps[0].key, key_b=snaps[-1].key)
-```
-
----
-
-## API Reference
-
-### `kg_utils.types`
-
-| Class | Description |
-|---|---|
-| `NodeSpec` | Dataclass for KG nodes: `node_id`, `kind`, `name`, `qualname`, `source_path`, `docstring` |
-| `EdgeSpec` | Dataclass for KG edges: `source_id`, `target_id`, `relation` |
-| `QueryResult` | Container for query responses with nodes, edges, and metadata |
-| `SnippetPack` | Extended result container with source-code snippets |
-| `KGExtractor` | Abstract base class for domain extractors |
-| `KGModule` | Abstract base class for knowledge-graph modules |
-
-### `kg_utils.snapshots`
-
-| Class | Description |
-|---|---|
-| `Snapshot` | Temporal snapshot keyed by git tree hash with free-form metrics and deltas |
-| `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
-| `SnapshotManifest` | Index of all snapshots with format versioning and fast lookup |
-| `PruneResult` | Summary of pruning operations: removed, orphaned, broken entries |
-
----
-
-## Project Structure
-
-```
-KG_utils/
-├── LICENSE
-├── README.md
-├── pyproject.toml
-├── pytest.ini
-├── src/
-│   └── kg_utils/
-│       ├── __init__.py
-│       ├── py.typed                  # PEP 561 marker
-│       ├── types/
-│       │   ├── __init__.py           # Public re-exports
-│       │   ├── specs.py              # NodeSpec, EdgeSpec, QueryResult, SnippetPack
-│       │   ├── extractor.py          # KGExtractor ABC
-│       │   └── module.py             # KGModule ABC
-│       └── snapshots/
-│           ├── __init__.py           # Public re-exports
-│           ├── models.py             # Snapshot, SnapshotManifest, PruneResult
-│           └── manager.py            # SnapshotManager
-└── tests/
-    ├── __init__.py
-    ├── test_types.py
-    └── test_snapshots.py
-```
-
----
-
-## Development
-
-```bash
-git clone https://github.com/Flux-Frontiers/KG_utils.git
-cd KG_utils
-poetry install --with dev
-```
-
-Run the test suite:
-
-```bash
-poetry run pytest
-```
-
----
-
-## License
-
-[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
-
-Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial use internally is permitted.
-

kgmodule_utils-0.3.0/README.md

@@ -1,191 +0,0 @@
-
-[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/)
-[![License: Elastic-2.0](https://img.shields.io/badge/License-Elastic%202.0-blue.svg)](https://www.elastic.co/licensing/elastic-license)
-[![Version](https://img.shields.io/badge/version-0.2.0-blue.svg)](https://github.com/Flux-Frontiers/KG_utils/releases)
-[![CI](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml/badge.svg)](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
-[![Poetry](https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json)](https://python-poetry.org/)
-
-# kgmodule-utils
-
-**kgmodule-utils** — Shared types and snapshot infrastructure for the KGModule SDK.
-
-*Author: Eric G. Suchanek, PhD*
-
-*Flux-Frontiers, Liberty TWP, OH*
-
----
-
-## Overview
-
-kgmodule-utils is the **zero-dependency foundation package** for the Flux-Frontiers knowledge-graph ecosystem. It provides the canonical type abstractions and temporal snapshot infrastructure that all KGModule implementations — [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [FTreeKG](https://github.com/Flux-Frontiers/ftree_kg), [DocKG](https://github.com/Flux-Frontiers/doc_kg), [AgentKG](https://github.com/Flux-Frontiers/agent_kg) — depend on.
-
-Every KGModule shares the same `NodeSpec`, `EdgeSpec`, `KGExtractor`, and `KGModule` base classes defined here, ensuring consistent interfaces across the ecosystem. The snapshot subsystem enables temporal metric tracking, delta comparison, and pruning across git commits.
-
----
-
-## Features
-
-- **Core type abstractions** — `NodeSpec`, `EdgeSpec`, `QueryResult`, `SnippetPack` dataclasses for knowledge-graph nodes, edges, and query results
-- **KGExtractor base class** — Abstract interface for domain-specific extractors with `extract()`, `node_kinds()`, `edge_kinds()`, and `coverage_metric()`
-- **KGModule base class** — Abstract interface for knowledge-graph modules with `build()`, `query()`, `pack()`, `stats()`, and `analyze()`
-- **Snapshot models** — `Snapshot` dataclass keyed by git tree hash with free-form metrics, hotspots, issues, and delta tracking
-- **SnapshotManager** — Capture, persist, load, list, diff, and prune snapshots with automatic deduplication and delta computation
-- **SnapshotManifest** — Fast-lookup index of all snapshots with format versioning
-- **Zero dependencies** — Stdlib-only; no external packages required at runtime
-
----
-
-## Installation
-
-**Requirements:** Python ≥ 3.12, < 3.14
-
-### Standalone (pip)
-
-```bash
-pip install kgmodule-utils
-```
-
-### Existing Poetry project
-
-```bash
-poetry add kgmodule-utils
-```
-
-Or declare it directly in your `pyproject.toml`:
-
-```toml
-[tool.poetry.dependencies]
-kgmodule-utils = "^0.2.0"
-```
-
----
-
-## Quick Start
-
-### Types — Define a KGModule
-
-```python
-from kg_utils.types import NodeSpec, EdgeSpec, KGExtractor, KGModule
-
-class MyExtractor(KGExtractor):
-    def node_kinds(self) -> list[str]:
-        return ["module", "function", "class"]
-
-    def edge_kinds(self) -> list[str]:
-        return ["CONTAINS", "CALLS", "IMPORTS"]
-
-    def extract(self, source_root: str):
-        # Yield NodeSpec and EdgeSpec objects from your domain
-        yield NodeSpec(
-            node_id="fn:main:hello",
-            kind="function",
-            name="hello",
-            qualname="main.hello",
-            source_path="main.py",
-            docstring="Greet the user.",
-        )
-        yield EdgeSpec(
-            source_id="mod:main",
-            target_id="fn:main:hello",
-            relation="CONTAINS",
-        )
-```
-
-### Snapshots — Track metrics over time
-
-```python
-from kg_utils.snapshots import SnapshotManager
-
-mgr = SnapshotManager(snapshots_dir=".my_kg/snapshots", package_name="my-kg")
-
-# Capture a snapshot from current metrics
-snapshot = mgr.capture(metrics={
-    "total_nodes": 142,
-    "total_edges": 387,
-    "coverage": 0.78,
-})
-
-# Save with automatic deduplication
-mgr.save_snapshot(snapshot)
-
-# List and compare
-snaps = mgr.list_snapshots(limit=5)
-delta = mgr.diff_snapshots(key_a=snaps[0].key, key_b=snaps[-1].key)
-```
-
----
-
-## API Reference
-
-### `kg_utils.types`
-
-| Class | Description |
-|---|---|
-| `NodeSpec` | Dataclass for KG nodes: `node_id`, `kind`, `name`, `qualname`, `source_path`, `docstring` |
-| `EdgeSpec` | Dataclass for KG edges: `source_id`, `target_id`, `relation` |
-| `QueryResult` | Container for query responses with nodes, edges, and metadata |
-| `SnippetPack` | Extended result container with source-code snippets |
-| `KGExtractor` | Abstract base class for domain extractors |
-| `KGModule` | Abstract base class for knowledge-graph modules |
-
-### `kg_utils.snapshots`
-
-| Class | Description |
-|---|---|
-| `Snapshot` | Temporal snapshot keyed by git tree hash with free-form metrics and deltas |
-| `SnapshotManager` | Capture, persist, load, list, diff, and prune snapshots |
-| `SnapshotManifest` | Index of all snapshots with format versioning and fast lookup |
-| `PruneResult` | Summary of pruning operations: removed, orphaned, broken entries |
-
----
-
-## Project Structure
-
-```
-KG_utils/
-├── LICENSE
-├── README.md
-├── pyproject.toml
-├── pytest.ini
-├── src/
-│   └── kg_utils/
-│       ├── __init__.py
-│       ├── py.typed                  # PEP 561 marker
-│       ├── types/
-│       │   ├── __init__.py           # Public re-exports
-│       │   ├── specs.py              # NodeSpec, EdgeSpec, QueryResult, SnippetPack
-│       │   ├── extractor.py          # KGExtractor ABC
-│       │   └── module.py             # KGModule ABC
-│       └── snapshots/
-│           ├── __init__.py           # Public re-exports
-│           ├── models.py             # Snapshot, SnapshotManifest, PruneResult
-│           └── manager.py            # SnapshotManager
-└── tests/
-    ├── __init__.py
-    ├── test_types.py
-    └── test_snapshots.py
-```
-
----
-
-## Development
-
-```bash
-git clone https://github.com/Flux-Frontiers/KG_utils.git
-cd KG_utils
-poetry install --with dev
-```
-
-Run the test suite:
-
-```bash
-poetry run pytest
-```
-
----
-
-## License
-
-[Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — see [LICENSE](LICENSE).
-
-Free to use, modify, and distribute. You may not offer the software as a hosted or managed service to third parties. Commercial use internally is permitted.

kgmodule_utils-0.3.0/src/kg_utils/types/__init__.py

@@ -1,14 +0,0 @@
-"""kg_utils.types — Core dataclasses and base classes for the KGModule SDK."""
-
-from kg_utils.types.specs import EdgeSpec, NodeSpec, QueryResult, SnippetPack
-from kg_utils.types.extractor import KGExtractor
-from kg_utils.types.module import KGModule
-
-__all__ = [
-    "EdgeSpec",
-    "KGExtractor",
-    "KGModule",
-    "NodeSpec",
-    "QueryResult",
-    "SnippetPack",
-]

kgmodule_utils-0.3.0/src/kg_utils/types/extractor.py

@@ -1,68 +0,0 @@
-"""kg_utils/types/extractor.py — Abstract base class for KG extractors."""
-
-from __future__ import annotations
-
-from collections.abc import Iterator
-from pathlib import Path
-from typing import Any
-
-from kg_utils.types.specs import EdgeSpec, NodeSpec
-
-
-class KGExtractor:
-    """Base class for knowledge-graph extractors.
-
-    Subclasses must implement :meth:`node_kinds`, :meth:`edge_kinds`,
-    and :meth:`extract`.
-
-    :param repo_path: Absolute path to the repository or corpus root.
-    :param config: Optional domain-specific configuration dict.
-    """
-
-    def __init__(self, repo_path: Path, config: dict[str, Any] | None = None) -> None:
-        self.repo_path = repo_path
-        self.config = config or {}
-
-    def node_kinds(self) -> list[str]:
-        """Return canonical node kind names.
-
-        :return: List of node kind strings.
-        """
-        raise NotImplementedError
-
-    def edge_kinds(self) -> list[str]:
-        """Return canonical edge relation types.
-
-        :return: List of edge relation strings.
-        """
-        raise NotImplementedError
-
-    def meaningful_node_kinds(self) -> list[str]:
-        """Return node kinds included in the vector index and coverage metrics.
-
-        Override to exclude structural stubs from the default (all node_kinds).
-
-        :return: Subset of node_kinds() to index semantically.
-        """
-        return self.node_kinds()
-
-    def coverage_metric(self, nodes: list[NodeSpec]) -> float:
-        """Compute a domain coverage quality metric.
-
-        Default: fraction of meaningful nodes with a non-empty docstring.
-
-        :param nodes: All extracted NodeSpec objects.
-        :return: Coverage score in [0.0, 1.0].
-        """
-        meaningful = [n for n in nodes if n.kind in self.meaningful_node_kinds()]
-        if not meaningful:
-            return 0.0
-        covered = sum(1 for n in meaningful if n.docstring.strip())
-        return covered / len(meaningful)
-
-    def extract(self) -> Iterator[NodeSpec | EdgeSpec]:
-        """Traverse the source and yield NodeSpec / EdgeSpec objects.
-
-        :return: Iterator of NodeSpec and EdgeSpec objects.
-        """
-        raise NotImplementedError

kgmodule_utils-0.3.0/src/kg_utils/types/module.py

@@ -1,87 +0,0 @@
-"""kg_utils/types/module.py — Abstract base class for KG modules."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from kg_utils.types.extractor import KGExtractor
-from kg_utils.types.specs import QueryResult, SnippetPack
-
-
-class KGModule:
-    """Base class for knowledge-graph modules.
-
-    Subclasses must implement :meth:`make_extractor`, :meth:`kind`,
-    and should override :meth:`build`, :meth:`query`, :meth:`stats`,
-    :meth:`pack`, and :meth:`analyze` with domain-specific logic.
-
-    :param repo_root: Absolute path to the repository or corpus root.
-    :param db_path: Path for the SQLite graph database.
-    :param lancedb_dir: Path for the LanceDB vector index directory.
-    :param config: Optional domain-specific configuration dict.
-    """
-
-    def __init__(
-        self,
-        repo_root: Path,
-        db_path: Path | None = None,
-        lancedb_dir: Path | None = None,
-        config: dict[str, Any] | None = None,
-    ) -> None:
-        self.repo_root = repo_root
-        self.db_path = db_path
-        self.lancedb_dir = lancedb_dir
-        self.config = config or {}
-
-    def make_extractor(self) -> KGExtractor:
-        """Return the domain extractor for this module.
-
-        :return: KGExtractor subclass instance.
-        """
-        raise NotImplementedError
-
-    def kind(self) -> str:
-        """Return the KGKind string for this module.
-
-        :return: Kind string (e.g. "code", "meta", "doc").
-        """
-        raise NotImplementedError
-
-    def build(self, wipe: bool = False) -> None:
-        """Build the knowledge graph index.
-
-        :param wipe: If True, delete existing index before building.
-        """
-        raise NotImplementedError
-
-    def query(self, q: str, k: int = 8, **kwargs: Any) -> QueryResult:
-        """Query the knowledge graph.
-
-        :param q: Natural-language query string.
-        :param k: Number of results to return.
-        :return: QueryResult with matched nodes and edges.
-        """
-        raise NotImplementedError
-
-    def stats(self) -> dict[str, Any]:
-        """Return statistics about the knowledge graph.
-
-        :return: Dict with keys like total_nodes, total_edges, etc.
-        """
-        raise NotImplementedError
-
-    def pack(self, q: str, **kwargs: Any) -> SnippetPack:
-        """Pack query results with source context.
-
-        :param q: Natural-language query string.
-        :return: SnippetPack with nodes, edges, and snippets.
-        """
-        raise NotImplementedError
-
-    def analyze(self) -> str:
-        """Run full analysis and return a Markdown report.
-
-        :return: Markdown-formatted analysis report.
-        """
-        raise NotImplementedError

kgmodule_utils-0.3.0/src/kg_utils/types/specs.py

@@ -1,90 +0,0 @@
-"""kg_utils/types/specs.py — Core dataclasses shared by all KG modules."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any
-
-
-@dataclass
-class NodeSpec:
-    """Specification for a knowledge-graph node.
-
-    :param node_id: Unique identifier, typically ``<kind>:<path>:<qualname>``.
-    :param kind: Node kind (e.g. "file", "function", "class", "directory").
-    :param name: Short display name.
-    :param qualname: Fully-qualified name or relative path.
-    :param source_path: Path to the source file (relative to repo root).
-    :param docstring: Semantic content for vector indexing.
-    """
-
-    node_id: str
-    kind: str
-    name: str
-    qualname: str
-    source_path: str
-    docstring: str = ""
-
-
-@dataclass
-class EdgeSpec:
-    """Specification for a knowledge-graph edge.
-
-    :param source_id: Node ID of the edge source.
-    :param target_id: Node ID of the edge target.
-    :param relation: Relation type (e.g. "CONTAINS", "CALLS", "IMPORTS").
-    """
-
-    source_id: str
-    target_id: str
-    relation: str
-
-
-@dataclass
-class QueryResult:
-    """Result container returned by KGModule.query().
-
-    :param nodes: List of matched node dicts.
-    :param edges: List of matched edge dicts.
-    :param seeds: Number of seed nodes from vector search.
-    :param expanded_nodes: Number of nodes after graph expansion.
-    :param returned_nodes: Number of nodes actually returned.
-    :param hop: Number of hops used in graph expansion.
-    :param rels: Relation types used in expansion.
-    """
-
-    nodes: list[dict[str, Any]] = field(default_factory=list)
-    edges: list[dict[str, Any]] = field(default_factory=list)
-    seeds: int = 0
-    expanded_nodes: int = 0
-    returned_nodes: int = 0
-    hop: int = 0
-    rels: list[str] = field(default_factory=list)
-
-
-@dataclass
-class SnippetPack:
-    """Result container returned by KGModule.pack().
-
-    :param query: The original query string.
-    :param seeds: Number of seed nodes from vector search.
-    :param expanded_nodes: Number of nodes after graph expansion.
-    :param returned_nodes: Number of nodes actually returned.
-    :param hop: Number of hops used in expansion.
-    :param rels: Relation types used in expansion.
-    :param model: Embedding model identifier.
-    :param nodes: Node dicts included in the pack.
-    :param edges: Edge dicts included in the pack.
-    :param snippets: Source-code snippets (for code KGs).
-    """
-
-    query: str
-    seeds: int = 0
-    expanded_nodes: int = 0
-    returned_nodes: int = 0
-    hop: int = 0
-    rels: list[str] = field(default_factory=list)
-    model: str = ""
-    nodes: list[Any] = field(default_factory=list)
-    edges: list[Any] = field(default_factory=list)
-    snippets: list[Any] = field(default_factory=list)