kgmodule-utils 0.2.0__tar.gz

kgmodule_utils-0.2.0/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

kgmodule_utils-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: kgmodule-utils
+Version: 0.2.0
+Summary: Shared types and snapshot infrastructure 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 :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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.2.0/README.md

@@ -0,0 +1,191 @@
+
+[![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.2.0/pyproject.toml

@@ -0,0 +1,59 @@
+# pyproject.toml — kgmodule-utils: shared types and snapshot infrastructure for KG modules
+#
+# Zero-dependency (stdlib-only) package providing:
+#   kg_utils.types    — NodeSpec, EdgeSpec, KGExtractor, KGModule, etc.
+#   kg_utils.snapshots — Snapshot, SnapshotManager, SnapshotManifest, etc.
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "kgmodule-utils"
+version = "0.2.0"
+description = "Shared types and snapshot infrastructure for the KGModule SDK"
+readme = "README.md"
+license = { text = "Elastic-2.0" }
+authors = [
+    { name = "Eric G. Suchanek, PhD", email = "suchanek@flux-frontiers.com" }
+]
+keywords = ["knowledge-graph", "kgmodule", "sdk", "types", "snapshots"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.12,<3.14"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/Flux-Frontiers/kg_utils"
+
+[tool.poetry]
+packages = [{include = "kg_utils", from = "src"}]
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+pytest     = "^8.0.0"
+pytest-cov = "^5.0.0"
+black      = ">=22.0"
+ruff       = ">=0.4.0"
+mypy       = ">=1.10.0"
+
+[tool.black]
+line-length    = 100
+target-version = ["py312", "py313"]
+
+[tool.ruff]
+line-length    = 100
+target-version = "py312"
+
+[tool.mypy]
+python_version     = "3.12"
+strict             = true
+warn_unused_ignores = true
+disallow_untyped_defs = true

kgmodule_utils-0.2.0/src/kg_utils/__init__.py

@@ -0,0 +1,10 @@
+"""kg_utils — Shared types, snapshots, and embedding protocol for the KGModule SDK.
+
+Sub-packages:
+    kg_utils.types      — NodeSpec, EdgeSpec, KGExtractor, KGModule, etc.
+    kg_utils.snapshots  — Snapshot, SnapshotManager, SnapshotManifest, etc.
+    kg_utils.embed      — Embedder protocol, DEFAULT_MODEL, KNOWN_MODELS,
+                          kg_model_cache_dir(), resolve_model_path().
+"""
+
+__version__ = "0.1.0"

kgmodule_utils-0.2.0/src/kg_utils/embed.py

@@ -0,0 +1,131 @@
+"""
+kg_utils.embed — Shared embedding protocol and model-cache convention.
+
+Zero external dependencies (stdlib only).  Concrete implementations
+(SentenceTransformerEmbedder, LlamaCppEmbedder) live in each KG module and in
+kgrag; this module provides only the shared contract they all implement.
+
+Contents
+--------
+Embedder
+    Structural protocol: any object with ``embed_query(text) -> list[float]``
+    satisfies it.  KG modules, kgrag adapters, and tests can type-hint against
+    this without coupling to any specific implementation.
+
+DEFAULT_MODEL
+    Canonical default embedding model for the KGModule stack.
+    ``BAAI/bge-small-en-v1.5`` (384-dim, ~24 MB, no licence restrictions).
+
+KNOWN_MODELS
+    Short alias → HuggingFace repo ID mapping shared by all modules.
+    Lets users write ``"bge-small"`` instead of ``"BAAI/bge-small-en-v1.5"``.
+
+kg_model_cache_dir()
+    Return the system-wide model cache root (``~/.kgrag/models/`` by default).
+    Override with the ``KGRAG_MODEL_DIR`` environment variable.  All KG modules
+    should resolve their model paths through this function so that a single
+    ``KGRAG_MODEL_DIR`` setting redirects every module at once.
+
+    Local fallback convention for standalone use::
+
+        path = kg_model_cache_dir() / model_name.replace("/", "--")
+
+Author: Eric G. Suchanek, PhD
+License: Elastic 2.0
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# Shared protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Minimal embedding protocol for the KGModule stack.
+
+    Any object with an ``embed_query`` method satisfies this protocol and can
+    be injected into any KGModule-based KG backend (DocKG, MemoryKG, etc.).
+
+    :method embed_query: Embed a single query string into a float vector.
+    """
+
+    def embed_query(self, text: str) -> list[float]:
+        """Embed a single query string into a dense float vector.
+
+        :param text: The query string to embed.
+        :return: Dense float32 vector as a plain Python list.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Shared constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_MODEL: str = "BAAI/bge-small-en-v1.5"
+"""Canonical default embedding model for the KGModule stack (384-dim)."""
+
+KNOWN_MODELS: dict[str, str] = {
+    "default": "BAAI/bge-small-en-v1.5",
+    "bge-small": "BAAI/bge-small-en-v1.5",
+    "bge-small-en-v1.5": "BAAI/bge-small-en-v1.5",
+    "bge-large": "BAAI/bge-large-en-v1.5",
+    "bge-large-en-v1.5": "BAAI/bge-large-en-v1.5",
+    "all-MiniLM-L6-v2": "sentence-transformers/all-MiniLM-L6-v2",
+    "all-mpnet-base-v2": "sentence-transformers/all-mpnet-base-v2",
+    "nomic": "nomic-ai/nomic-embed-text-v1.5",
+    "nomic-v1.5": "nomic-ai/nomic-embed-text-v1.5",
+}
+"""Short alias → HuggingFace repo ID.  Shared by all KG modules and kgrag."""
+
+
+# ---------------------------------------------------------------------------
+# Shared cache path convention
+# ---------------------------------------------------------------------------
+
+
+def kg_model_cache_dir() -> Path:
+    """Return the system-wide embedding model cache root.
+
+    Default: ``~/.kgrag/models/``
+    Override: set ``KGRAG_MODEL_DIR`` environment variable.
+
+    All KG modules should resolve model paths through this function so that a
+    single env-var change redirects every module's cache at once.
+
+    :return: Absolute :class:`~pathlib.Path` to the model cache directory.
+    """
+    env = os.environ.get("KGRAG_MODEL_DIR")
+    if env:
+        return Path(env).resolve()
+    return Path.home() / ".kgrag" / "models"
+
+
+def resolve_model_path(model_name: str, local_fallback: Path | None = None) -> Path:
+    """Return the local cache path for *model_name*.
+
+    Checks the system-wide cache (``kg_model_cache_dir()``) first.  If
+    *local_fallback* is provided and the system cache env var is not set, uses
+    that instead — allowing standalone modules to keep their own local cache
+    while respecting a global override.
+
+    The model name is stored as ``<org>/<model>`` directory structure (matching
+    HuggingFace layout), e.g. ``BAAI/bge-small-en-v1.5`` →
+    ``~/.kgrag/models/BAAI/bge-small-en-v1.5/``.
+
+    :param model_name: HuggingFace model identifier or known alias.
+    :param local_fallback: Per-module fallback directory (used when
+        ``KGRAG_MODEL_DIR`` is not set).
+    :return: Absolute :class:`~pathlib.Path` to the model directory.
+    """
+    resolved = KNOWN_MODELS.get(model_name, model_name)
+    if os.environ.get("KGRAG_MODEL_DIR") or local_fallback is None:
+        return kg_model_cache_dir() / resolved.replace("/", os.sep)
+    return local_fallback / resolved.replace("/", "--")