kgmodule-utils 0.28.0__tar.gz → 0.29.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/PKG-INFO +78 -21
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/README.md +74 -18
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/pyproject.toml +19 -10
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/__init__.py +7 -3
- kgmodule_utils-0.29.0/src/kg_utils/mcp/__init__.py +104 -0
- kgmodule_utils-0.29.0/src/kg_utils/mcp/_names.py +24 -0
- kgmodule_utils-0.29.0/src/kg_utils/mcp/cli.py +143 -0
- kgmodule_utils-0.29.0/src/kg_utils/mcp/server.py +761 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/pipeline.py +84 -63
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/semantic.py +7 -24
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/snapshots/manager.py +6 -2
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/specs.py +1 -1
- kgmodule_utils-0.29.0/src/kg_utils/stats.py +146 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/store.py +44 -1
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/vector_backend.py +23 -357
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/LICENSE +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/analysis/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/analysis/scores.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/corpus_embedder.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/devicepack.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/embed.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/embedder.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/extractor.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/ingest/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/ingest/converters.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/ingest/derived.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/ingest/manifest.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/ingest/pipeline.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/module.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/py.typed +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/retrieval/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/retrieval/hits.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/snapshots/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/snapshots/models.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/synthesis/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/synthesis/_config.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/synthesis/_image.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/synthesis/_text.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/synthesis/factory.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/temporal.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/validation.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz/graph_html.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz/theme.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz/tooltip.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz3d/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz3d/layout.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz3d/organic.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz3d/qt.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/viz3d/species.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/worker/__init__.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/worker/client.py +0 -0
- {kgmodule_utils-0.28.0 → kgmodule_utils-0.29.0}/src/kg_utils/worker/ops.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: kgmodule-utils
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.29.0
|
|
4
4
|
Summary: Shared types, graph store, semantic index, and pipeline base for the KGModule SDK
|
|
5
5
|
License-Expression: Elastic-2.0
|
|
6
6
|
License-File: LICENSE
|
|
@@ -14,7 +14,7 @@ Classifier: Programming Language :: Python :: 3
|
|
|
14
14
|
Classifier: Programming Language :: Python :: 3.12
|
|
15
15
|
Classifier: Programming Language :: Python :: 3.13
|
|
16
16
|
Provides-Extra: ingest
|
|
17
|
-
Provides-Extra:
|
|
17
|
+
Provides-Extra: mcp
|
|
18
18
|
Provides-Extra: pdf
|
|
19
19
|
Provides-Extra: semantic
|
|
20
20
|
Provides-Extra: sqlite-vec
|
|
@@ -25,10 +25,11 @@ Provides-Extra: viz3d
|
|
|
25
25
|
Provides-Extra: viz3d-qt
|
|
26
26
|
Provides-Extra: viz3d-render
|
|
27
27
|
Requires-Dist: PyQt5 (>=5.15.0) ; extra == "viz3d-qt"
|
|
28
|
+
Requires-Dist: click (>=8.1.0) ; extra == "mcp"
|
|
28
29
|
Requires-Dist: firecrawl-anydoc (>=0.1.9) ; extra == "ingest"
|
|
29
30
|
Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis"
|
|
30
31
|
Requires-Dist: httpx (>=0.27.0) ; extra == "synthesis-mflux"
|
|
31
|
-
Requires-Dist:
|
|
32
|
+
Requires-Dist: mcp (>=1.23.0,<2) ; extra == "mcp"
|
|
32
33
|
Requires-Dist: mflux (>=0.9.0) ; extra == "synthesis-mflux"
|
|
33
34
|
Requires-Dist: numpy (>=1.24.0) ; extra == "semantic"
|
|
34
35
|
Requires-Dist: numpy (>=1.24.0) ; extra == "viz3d"
|
|
@@ -56,7 +57,7 @@ Description-Content-Type: text/markdown
|
|
|
56
57
|
|
|
57
58
|
[](https://www.python.org/)
|
|
58
59
|
[](https://www.elastic.co/licensing/elastic-license)
|
|
59
|
-
[](https://github.com/Flux-Frontiers/KG_utils/releases)
|
|
60
61
|
[](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
|
|
61
62
|
[](https://python-poetry.org/)
|
|
62
63
|
[](https://doi.org/10.5281/zenodo.21284866)
|
|
@@ -73,7 +74,7 @@ Description-Content-Type: text/markdown
|
|
|
73
74
|
|
|
74
75
|
## Overview
|
|
75
76
|
|
|
76
|
-
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
|
|
77
|
+
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 vector indexing on sqlite-vec and a full build/query/pack pipeline — so domain authors implement only what is specific to their source domain.
|
|
77
78
|
|
|
78
79
|
Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [TypeScriptKG](https://github.com/Flux-Frontiers/tscode_kg), and [FTreeKG](https://github.com/Flux-Frontiers/ftree_kg) subclass `KGModule` from here and implement exactly three methods: `make_extractor()`, `kind()`, and `analyze()`. The rest — [DocKG](https://github.com/Flux-Frontiers/doc_kg), MemoryKG, MetaboKG, and others — keep their own pipelines and pull in the shared pieces they need: embedders, vector backends, snapshots, synthesis.
|
|
79
80
|
|
|
@@ -81,6 +82,13 @@ Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/p
|
|
|
81
82
|
|
|
82
83
|
## Latest News
|
|
83
84
|
|
|
85
|
+
- **0.29.0 (2026-10-25)** -- New `kg_utils.mcp`: one MCP server base for every
|
|
86
|
+
KG module (`mcp` extra), with the fleet's canonical tools (`stats`, `query`,
|
|
87
|
+
`pack`, `get_node`, `neighbors`) and the standard `<tool> mcp` command; new
|
|
88
|
+
`kg_utils.stats`: one shape for a KG's statistics, which `KGModule.stats()`
|
|
89
|
+
now returns; `KGModule.neighbors()`. **Breaking:** LanceDB support is gone
|
|
90
|
+
(sqlite-vec is the only backend), and `KGModule.stats()` no longer returns
|
|
91
|
+
the flat `total_nodes` / `node_counts` keys (`flat_stats()` gives them back).
|
|
84
92
|
- **0.28.0 (2026-10-23)** -- New `kg_utils.devicepack`: the on-device
|
|
85
93
|
search-pack format the Knowledge Press apps read (passage pack, vector
|
|
86
94
|
sidecar, manifest, golden rankings), lifted out of gutenberg_kg's
|
|
@@ -229,7 +237,7 @@ storage (`specs`, `extractor`, `store`, `pipeline`), semantic indexing over
|
|
|
229
237
|
pluggable vector backends (`semantic`, `vector_backend`, `embed`, `embedder`),
|
|
230
238
|
document ingestion (`ingest`), a shared temporal contract for dated nodes
|
|
231
239
|
(`temporal`), on-device search packs for the Knowledge Press apps
|
|
232
|
-
(`devicepack`), temporal snapshots (`snapshots`), text + image
|
|
240
|
+
(`devicepack`), one MCP server base for every module (`mcp`), one shape for a KG's statistics (`stats`), temporal snapshots (`snapshots`), text + image
|
|
233
241
|
synthesis (`synthesis`), centrality analysis (`analysis`), and a visualization
|
|
234
242
|
stack that runs from interactive HTML (`viz`) through 3-D layouts and organic
|
|
235
243
|
trees grown as species (`viz3d`, `viz3d.species`) to Looking Glass light-field
|
|
@@ -264,15 +272,13 @@ extra dependency at all.
|
|
|
264
272
|
pip install 'kgmodule-utils[ingest]'
|
|
265
273
|
```
|
|
266
274
|
|
|
267
|
-
### With
|
|
275
|
+
### With the MCP server base
|
|
268
276
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
if you have a pre-existing, un-migrated LanceDB store on disk; migrate when you
|
|
272
|
-
can.
|
|
277
|
+
Serves any `KGModule` to an AI agent over MCP, with the fleet's canonical tools
|
|
278
|
+
and the standard `<tool> mcp` command (`kg_utils.mcp`).
|
|
273
279
|
|
|
274
280
|
```bash
|
|
275
|
-
pip install 'kgmodule-utils[
|
|
281
|
+
pip install 'kgmodule-utils[mcp]'
|
|
276
282
|
```
|
|
277
283
|
|
|
278
284
|
### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
|
|
@@ -429,7 +435,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
429
435
|
|
|
430
436
|
| Class / function | Description |
|
|
431
437
|
|---|---|
|
|
432
|
-
| `SemanticIndex` | Vector index over
|
|
438
|
+
| `SemanticIndex` | Vector index over sqlite-vec (`VectorBackend` is the seam, `SqliteVecBackend` its one implementation): `build()`, `search()`, `close()` |
|
|
433
439
|
| `SentenceTransformerEmbedder` | Local embedding via sentence-transformers |
|
|
434
440
|
| `resolve_model_path()` | Resolve model name / alias to local cache path |
|
|
435
441
|
| `suppress_ingestion_logging()` | Silence verbose HF / tqdm output during ingestion |
|
|
@@ -438,7 +444,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
438
444
|
|
|
439
445
|
| Class | Description |
|
|
440
446
|
|---|---|
|
|
441
|
-
| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()` for free. `build_graph(wipe=True)` drops the vector index it invalidates; `drop_index()` does so on demand. `sync()` rewrites the graph and re-embeds only the nodes whose index text changed |
|
|
447
|
+
| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()`, `node()`, `neighbors()` for free. `build_graph(wipe=True)` drops the vector index it invalidates; `drop_index()` does so on demand. `sync()` rewrites the graph and re-embeds only the nodes whose index text changed |
|
|
442
448
|
|
|
443
449
|
### `kg_utils.snapshots`
|
|
444
450
|
|
|
@@ -600,6 +606,54 @@ server. Needs NumPy for vectors (`semantic` or `viz3d` extra).
|
|
|
600
606
|
| `read_vector_sidecar()` | Memory-map a sidecar; rejects a truncated or foreign file |
|
|
601
607
|
| `encode_vector()`, `rrf_fuse()`, `fts_phrase_expression()` | The pieces the search is built from |
|
|
602
608
|
|
|
609
|
+
### `kg_utils.mcp`
|
|
610
|
+
|
|
611
|
+
One MCP server base for every KG module (`mcp` extra). A module passes a
|
|
612
|
+
factory that opens its KG and adds its own domain tools; everything else is
|
|
613
|
+
shared. Plan of record: `kgrag_priv/docs/MCP_CENTRALIZATION_PLAN.md`.
|
|
614
|
+
|
|
615
|
+
| Class / function | Description |
|
|
616
|
+
|---|---|
|
|
617
|
+
| `make_server()` | Build a server for one KG with the canonical tools: `stats`, `query`, `pack`, `get_node`, `neighbors`. The KG opens per session and closes after; an unbuilt graph is refused, not served empty |
|
|
618
|
+
| `KGServer` | The `FastMCP` subclass it returns. Add domain tools with `@server.tool()`; replace a canonical tool with a richer version under the same name with `@server.canonical("query")`, refused at build time if it drops or retypes a canonical parameter; the instructions regenerate on every change |
|
|
619
|
+
| `kg_from()` | Inside a domain tool, the KG this session opened (declare `ctx: Context`) |
|
|
620
|
+
| `add_mcp_command()` | The standard `<tool> mcp [--repo] [--db] [--vectors] [--model] [--transport] [--host] [--port] [--manifest]`; relative `--db`/`--vectors` are taken from `--repo` |
|
|
621
|
+
| `manifest()`, `describe_tools()` | The tool list as JSON and as text, without opening the KG |
|
|
622
|
+
| `run()` | Serve over `stdio` (stdout reserved for the protocol, all other output sent to stderr) or `streamable-http`; `sse` is refused |
|
|
623
|
+
|
|
624
|
+
```python
|
|
625
|
+
from kg_utils.mcp import Context, add_mcp_command, kg_from, make_server
|
|
626
|
+
|
|
627
|
+
def build_server(repo, db, vectors, model):
|
|
628
|
+
kwargs = {"model": model} if model else {}
|
|
629
|
+
server = make_server(lambda: MyKG(repo, db, vectors, **kwargs), name="mykg", kind="my")
|
|
630
|
+
|
|
631
|
+
@server.tool()
|
|
632
|
+
def callers(node_id: str, ctx: Context) -> list[dict]:
|
|
633
|
+
"""Every node that calls this one."""
|
|
634
|
+
return kg_from(ctx).callers(node_id)
|
|
635
|
+
|
|
636
|
+
return server
|
|
637
|
+
|
|
638
|
+
add_mcp_command(cli, build_server)
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
### `kg_utils.stats`
|
|
642
|
+
|
|
643
|
+
The fleet's one shape for a KG's statistics. Every module's public `stats()`,
|
|
644
|
+
and so every server's canonical `stats` tool, returns `{"kind", "nodes":
|
|
645
|
+
{"total", "by_kind"}, "edges": {"total", "by_rel"}}` plus the module's own
|
|
646
|
+
measures as top-level extras. `KGModule.stats()` already does; a store's own
|
|
647
|
+
`stats()` keeps its flat `total_nodes` / `node_counts` keys, which snapshots
|
|
648
|
+
persist.
|
|
649
|
+
|
|
650
|
+
| Function | Description |
|
|
651
|
+
|---|---|
|
|
652
|
+
| `kg_stats()` | Build the shape from per-kind and per-relation counts; the totals are summed from them, so they cannot disagree |
|
|
653
|
+
| `stats_from_store()` | Reshape a store's flat `stats()`, keeping its other keys as extras |
|
|
654
|
+
| `flat_stats()` | The inverse: the flat keys, for a report or a snapshot |
|
|
655
|
+
| `stats_problems()` | Every way a dict departs from the shape; the `stats` tool reports them as a tool error |
|
|
656
|
+
|
|
603
657
|
### `kg_utils.analysis`
|
|
604
658
|
|
|
605
659
|
| Class / function | Description |
|
|
@@ -627,7 +681,7 @@ KG_utils/
|
|
|
627
681
|
│ ├── extractor.py # KGExtractor ABC
|
|
628
682
|
│ ├── store.py # GraphStore (SQLite)
|
|
629
683
|
│ ├── semantic.py # SemanticIndex, SentenceTransformerEmbedder, SeedHit
|
|
630
|
-
│ ├── vector_backend.py # VectorBackend protocol, SqliteVecBackend
|
|
684
|
+
│ ├── vector_backend.py # VectorBackend protocol, SqliteVecBackend
|
|
631
685
|
│ ├── pipeline.py # KGModule concrete base class
|
|
632
686
|
│ ├── module.py # Re-export shim
|
|
633
687
|
│ ├── embed.py # Embedder protocol, model registry
|
|
@@ -638,6 +692,10 @@ KG_utils/
|
|
|
638
692
|
│ │ ├── converters.py # Converter protocol, PassthroughConverter, AnydocConverter
|
|
639
693
|
│ │ ├── manifest.py # IngestRecord, IngestManifest, IngestStats — per-file provenance
|
|
640
694
|
│ │ └── pipeline.py # IngestPipeline: walk, convert, stage, dedup by content digest
|
|
695
|
+
│ ├── mcp/ # MCP server base for every KG module (mcp extra)
|
|
696
|
+
│ │ ├── __init__.py
|
|
697
|
+
│ │ ├── server.py # make_server, KGServer, canonical tools, manifest, run
|
|
698
|
+
│ │ └── cli.py # add_mcp_command: the standard `<tool> mcp`
|
|
641
699
|
│ ├── retrieval/ # Serialize + enrich KG hits (hit_to_dict, attach_content_by_sqlite)
|
|
642
700
|
│ │ ├── __init__.py
|
|
643
701
|
│ │ └── hits.py
|
|
@@ -762,16 +820,15 @@ git clone https://github.com/Flux-Frontiers/KG_utils.git
|
|
|
762
820
|
cd KG_utils
|
|
763
821
|
poetry env use python3.12
|
|
764
822
|
poetry install --with dev --extras "semantic" --extras "synthesis" --extras "viz" \
|
|
765
|
-
--extras "
|
|
823
|
+
--extras "viz3d-render" --extras "viz3d-qt" --extras "mcp"
|
|
766
824
|
```
|
|
767
825
|
|
|
768
826
|
**The extras are not optional for testing.** The core install is deliberately
|
|
769
827
|
zero-dependency (`dependencies = []`), so `poetry install --with dev` on its own
|
|
770
828
|
installs no runtime packages at all — pytest then aborts during *collection* on
|
|
771
829
|
missing `numpy` and `httpx` and runs nothing. The six extras above are what CI
|
|
772
|
-
installs
|
|
773
|
-
|
|
774
|
-
imports — and pre-commit runs ty, so install it locally.
|
|
830
|
+
installs, in both the test and the type-check job, and pre-commit runs ty, so
|
|
831
|
+
install them locally.
|
|
775
832
|
|
|
776
833
|
Run the fast test suite (no model downloads) — **750 passed, 1 skipped** (the
|
|
777
834
|
skip is a test that needs `doc_kg`, which the SDK cannot depend on):
|
|
@@ -809,7 +866,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
809
866
|
|
|
810
867
|
**APA**
|
|
811
868
|
|
|
812
|
-
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.
|
|
869
|
+
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.29.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
|
|
813
870
|
|
|
814
871
|
**BibTeX**
|
|
815
872
|
|
|
@@ -817,7 +874,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
817
874
|
@software{suchanek_kgmodule_utils,
|
|
818
875
|
author = {Suchanek, Eric G.},
|
|
819
876
|
title = {{kgmodule-utils}: Shared SDK for the KGModule Knowledge-Graph Ecosystem},
|
|
820
|
-
version = {0.
|
|
877
|
+
version = {0.29.0},
|
|
821
878
|
year = {2026},
|
|
822
879
|
publisher = {Flux-Frontiers},
|
|
823
880
|
url = {https://github.com/Flux-Frontiers/KG_utils},
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
|
|
2
2
|
[](https://www.python.org/)
|
|
3
3
|
[](https://www.elastic.co/licensing/elastic-license)
|
|
4
|
-
[](https://github.com/Flux-Frontiers/KG_utils/releases)
|
|
5
5
|
[](https://github.com/Flux-Frontiers/KG_utils/actions/workflows/ci.yml)
|
|
6
6
|
[](https://python-poetry.org/)
|
|
7
7
|
[](https://doi.org/10.5281/zenodo.21284866)
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
|
|
19
19
|
## Overview
|
|
20
20
|
|
|
21
|
-
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
|
|
21
|
+
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 vector indexing on sqlite-vec and a full build/query/pack pipeline — so domain authors implement only what is specific to their source domain.
|
|
22
22
|
|
|
23
23
|
Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/pycode_kg), [TypeScriptKG](https://github.com/Flux-Frontiers/tscode_kg), and [FTreeKG](https://github.com/Flux-Frontiers/ftree_kg) subclass `KGModule` from here and implement exactly three methods: `make_extractor()`, `kind()`, and `analyze()`. The rest — [DocKG](https://github.com/Flux-Frontiers/doc_kg), MemoryKG, MetaboKG, and others — keep their own pipelines and pull in the shared pieces they need: embedders, vector backends, snapshots, synthesis.
|
|
24
24
|
|
|
@@ -26,6 +26,13 @@ Fleet modules use it in two ways. [PyCodeKG](https://github.com/Flux-Frontiers/p
|
|
|
26
26
|
|
|
27
27
|
## Latest News
|
|
28
28
|
|
|
29
|
+
- **0.29.0 (2026-10-25)** -- New `kg_utils.mcp`: one MCP server base for every
|
|
30
|
+
KG module (`mcp` extra), with the fleet's canonical tools (`stats`, `query`,
|
|
31
|
+
`pack`, `get_node`, `neighbors`) and the standard `<tool> mcp` command; new
|
|
32
|
+
`kg_utils.stats`: one shape for a KG's statistics, which `KGModule.stats()`
|
|
33
|
+
now returns; `KGModule.neighbors()`. **Breaking:** LanceDB support is gone
|
|
34
|
+
(sqlite-vec is the only backend), and `KGModule.stats()` no longer returns
|
|
35
|
+
the flat `total_nodes` / `node_counts` keys (`flat_stats()` gives them back).
|
|
29
36
|
- **0.28.0 (2026-10-23)** -- New `kg_utils.devicepack`: the on-device
|
|
30
37
|
search-pack format the Knowledge Press apps read (passage pack, vector
|
|
31
38
|
sidecar, manifest, golden rankings), lifted out of gutenberg_kg's
|
|
@@ -174,7 +181,7 @@ storage (`specs`, `extractor`, `store`, `pipeline`), semantic indexing over
|
|
|
174
181
|
pluggable vector backends (`semantic`, `vector_backend`, `embed`, `embedder`),
|
|
175
182
|
document ingestion (`ingest`), a shared temporal contract for dated nodes
|
|
176
183
|
(`temporal`), on-device search packs for the Knowledge Press apps
|
|
177
|
-
(`devicepack`), temporal snapshots (`snapshots`), text + image
|
|
184
|
+
(`devicepack`), one MCP server base for every module (`mcp`), one shape for a KG's statistics (`stats`), temporal snapshots (`snapshots`), text + image
|
|
178
185
|
synthesis (`synthesis`), centrality analysis (`analysis`), and a visualization
|
|
179
186
|
stack that runs from interactive HTML (`viz`) through 3-D layouts and organic
|
|
180
187
|
trees grown as species (`viz3d`, `viz3d.species`) to Looking Glass light-field
|
|
@@ -209,15 +216,13 @@ extra dependency at all.
|
|
|
209
216
|
pip install 'kgmodule-utils[ingest]'
|
|
210
217
|
```
|
|
211
218
|
|
|
212
|
-
### With
|
|
219
|
+
### With the MCP server base
|
|
213
220
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
if you have a pre-existing, un-migrated LanceDB store on disk; migrate when you
|
|
217
|
-
can.
|
|
221
|
+
Serves any `KGModule` to an AI agent over MCP, with the fleet's canonical tools
|
|
222
|
+
and the standard `<tool> mcp` command (`kg_utils.mcp`).
|
|
218
223
|
|
|
219
224
|
```bash
|
|
220
|
-
pip install 'kgmodule-utils[
|
|
225
|
+
pip install 'kgmodule-utils[mcp]'
|
|
221
226
|
```
|
|
222
227
|
|
|
223
228
|
### With text + image synthesis (oMLX / Ollama / OpenAI / mflux-serve)
|
|
@@ -374,7 +379,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
374
379
|
|
|
375
380
|
| Class / function | Description |
|
|
376
381
|
|---|---|
|
|
377
|
-
| `SemanticIndex` | Vector index over
|
|
382
|
+
| `SemanticIndex` | Vector index over sqlite-vec (`VectorBackend` is the seam, `SqliteVecBackend` its one implementation): `build()`, `search()`, `close()` |
|
|
378
383
|
| `SentenceTransformerEmbedder` | Local embedding via sentence-transformers |
|
|
379
384
|
| `resolve_model_path()` | Resolve model name / alias to local cache path |
|
|
380
385
|
| `suppress_ingestion_logging()` | Silence verbose HF / tqdm output during ingestion |
|
|
@@ -383,7 +388,7 @@ delta = mgr.diff_snapshots(snaps[-1]["key"], snaps[0]["key"])
|
|
|
383
388
|
|
|
384
389
|
| Class | Description |
|
|
385
390
|
|---|---|
|
|
386
|
-
| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()` for free. `build_graph(wipe=True)` drops the vector index it invalidates; `drop_index()` does so on demand. `sync()` rewrites the graph and re-embeds only the nodes whose index text changed |
|
|
391
|
+
| `KGModule` | Concrete base — implement `make_extractor()`, `kind()`, `analyze()`; get `build()`, `query()`, `pack()`, `stats()`, `node()`, `neighbors()` for free. `build_graph(wipe=True)` drops the vector index it invalidates; `drop_index()` does so on demand. `sync()` rewrites the graph and re-embeds only the nodes whose index text changed |
|
|
387
392
|
|
|
388
393
|
### `kg_utils.snapshots`
|
|
389
394
|
|
|
@@ -545,6 +550,54 @@ server. Needs NumPy for vectors (`semantic` or `viz3d` extra).
|
|
|
545
550
|
| `read_vector_sidecar()` | Memory-map a sidecar; rejects a truncated or foreign file |
|
|
546
551
|
| `encode_vector()`, `rrf_fuse()`, `fts_phrase_expression()` | The pieces the search is built from |
|
|
547
552
|
|
|
553
|
+
### `kg_utils.mcp`
|
|
554
|
+
|
|
555
|
+
One MCP server base for every KG module (`mcp` extra). A module passes a
|
|
556
|
+
factory that opens its KG and adds its own domain tools; everything else is
|
|
557
|
+
shared. Plan of record: `kgrag_priv/docs/MCP_CENTRALIZATION_PLAN.md`.
|
|
558
|
+
|
|
559
|
+
| Class / function | Description |
|
|
560
|
+
|---|---|
|
|
561
|
+
| `make_server()` | Build a server for one KG with the canonical tools: `stats`, `query`, `pack`, `get_node`, `neighbors`. The KG opens per session and closes after; an unbuilt graph is refused, not served empty |
|
|
562
|
+
| `KGServer` | The `FastMCP` subclass it returns. Add domain tools with `@server.tool()`; replace a canonical tool with a richer version under the same name with `@server.canonical("query")`, refused at build time if it drops or retypes a canonical parameter; the instructions regenerate on every change |
|
|
563
|
+
| `kg_from()` | Inside a domain tool, the KG this session opened (declare `ctx: Context`) |
|
|
564
|
+
| `add_mcp_command()` | The standard `<tool> mcp [--repo] [--db] [--vectors] [--model] [--transport] [--host] [--port] [--manifest]`; relative `--db`/`--vectors` are taken from `--repo` |
|
|
565
|
+
| `manifest()`, `describe_tools()` | The tool list as JSON and as text, without opening the KG |
|
|
566
|
+
| `run()` | Serve over `stdio` (stdout reserved for the protocol, all other output sent to stderr) or `streamable-http`; `sse` is refused |
|
|
567
|
+
|
|
568
|
+
```python
|
|
569
|
+
from kg_utils.mcp import Context, add_mcp_command, kg_from, make_server
|
|
570
|
+
|
|
571
|
+
def build_server(repo, db, vectors, model):
|
|
572
|
+
kwargs = {"model": model} if model else {}
|
|
573
|
+
server = make_server(lambda: MyKG(repo, db, vectors, **kwargs), name="mykg", kind="my")
|
|
574
|
+
|
|
575
|
+
@server.tool()
|
|
576
|
+
def callers(node_id: str, ctx: Context) -> list[dict]:
|
|
577
|
+
"""Every node that calls this one."""
|
|
578
|
+
return kg_from(ctx).callers(node_id)
|
|
579
|
+
|
|
580
|
+
return server
|
|
581
|
+
|
|
582
|
+
add_mcp_command(cli, build_server)
|
|
583
|
+
```
|
|
584
|
+
|
|
585
|
+
### `kg_utils.stats`
|
|
586
|
+
|
|
587
|
+
The fleet's one shape for a KG's statistics. Every module's public `stats()`,
|
|
588
|
+
and so every server's canonical `stats` tool, returns `{"kind", "nodes":
|
|
589
|
+
{"total", "by_kind"}, "edges": {"total", "by_rel"}}` plus the module's own
|
|
590
|
+
measures as top-level extras. `KGModule.stats()` already does; a store's own
|
|
591
|
+
`stats()` keeps its flat `total_nodes` / `node_counts` keys, which snapshots
|
|
592
|
+
persist.
|
|
593
|
+
|
|
594
|
+
| Function | Description |
|
|
595
|
+
|---|---|
|
|
596
|
+
| `kg_stats()` | Build the shape from per-kind and per-relation counts; the totals are summed from them, so they cannot disagree |
|
|
597
|
+
| `stats_from_store()` | Reshape a store's flat `stats()`, keeping its other keys as extras |
|
|
598
|
+
| `flat_stats()` | The inverse: the flat keys, for a report or a snapshot |
|
|
599
|
+
| `stats_problems()` | Every way a dict departs from the shape; the `stats` tool reports them as a tool error |
|
|
600
|
+
|
|
548
601
|
### `kg_utils.analysis`
|
|
549
602
|
|
|
550
603
|
| Class / function | Description |
|
|
@@ -572,7 +625,7 @@ KG_utils/
|
|
|
572
625
|
│ ├── extractor.py # KGExtractor ABC
|
|
573
626
|
│ ├── store.py # GraphStore (SQLite)
|
|
574
627
|
│ ├── semantic.py # SemanticIndex, SentenceTransformerEmbedder, SeedHit
|
|
575
|
-
│ ├── vector_backend.py # VectorBackend protocol, SqliteVecBackend
|
|
628
|
+
│ ├── vector_backend.py # VectorBackend protocol, SqliteVecBackend
|
|
576
629
|
│ ├── pipeline.py # KGModule concrete base class
|
|
577
630
|
│ ├── module.py # Re-export shim
|
|
578
631
|
│ ├── embed.py # Embedder protocol, model registry
|
|
@@ -583,6 +636,10 @@ KG_utils/
|
|
|
583
636
|
│ │ ├── converters.py # Converter protocol, PassthroughConverter, AnydocConverter
|
|
584
637
|
│ │ ├── manifest.py # IngestRecord, IngestManifest, IngestStats — per-file provenance
|
|
585
638
|
│ │ └── pipeline.py # IngestPipeline: walk, convert, stage, dedup by content digest
|
|
639
|
+
│ ├── mcp/ # MCP server base for every KG module (mcp extra)
|
|
640
|
+
│ │ ├── __init__.py
|
|
641
|
+
│ │ ├── server.py # make_server, KGServer, canonical tools, manifest, run
|
|
642
|
+
│ │ └── cli.py # add_mcp_command: the standard `<tool> mcp`
|
|
586
643
|
│ ├── retrieval/ # Serialize + enrich KG hits (hit_to_dict, attach_content_by_sqlite)
|
|
587
644
|
│ │ ├── __init__.py
|
|
588
645
|
│ │ └── hits.py
|
|
@@ -707,16 +764,15 @@ git clone https://github.com/Flux-Frontiers/KG_utils.git
|
|
|
707
764
|
cd KG_utils
|
|
708
765
|
poetry env use python3.12
|
|
709
766
|
poetry install --with dev --extras "semantic" --extras "synthesis" --extras "viz" \
|
|
710
|
-
--extras "
|
|
767
|
+
--extras "viz3d-render" --extras "viz3d-qt" --extras "mcp"
|
|
711
768
|
```
|
|
712
769
|
|
|
713
770
|
**The extras are not optional for testing.** The core install is deliberately
|
|
714
771
|
zero-dependency (`dependencies = []`), so `poetry install --with dev` on its own
|
|
715
772
|
installs no runtime packages at all — pytest then aborts during *collection* on
|
|
716
773
|
missing `numpy` and `httpx` and runs nothing. The six extras above are what CI
|
|
717
|
-
installs
|
|
718
|
-
|
|
719
|
-
imports — and pre-commit runs ty, so install it locally.
|
|
774
|
+
installs, in both the test and the type-check job, and pre-commit runs ty, so
|
|
775
|
+
install them locally.
|
|
720
776
|
|
|
721
777
|
Run the fast test suite (no model downloads) — **750 passed, 1 skipped** (the
|
|
722
778
|
skip is a test that needs `doc_kg`, which the SDK cannot depend on):
|
|
@@ -754,7 +810,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
754
810
|
|
|
755
811
|
**APA**
|
|
756
812
|
|
|
757
|
-
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.
|
|
813
|
+
> Suchanek, E. G. (2026). *kgmodule-utils: Shared SDK for the KGModule Knowledge-Graph Ecosystem* (Version 0.29.0) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.21284866
|
|
758
814
|
|
|
759
815
|
**BibTeX**
|
|
760
816
|
|
|
@@ -762,7 +818,7 @@ If you use kgmodule-utils in research or a project, please cite it:
|
|
|
762
818
|
@software{suchanek_kgmodule_utils,
|
|
763
819
|
author = {Suchanek, Eric G.},
|
|
764
820
|
title = {{kgmodule-utils}: Shared SDK for the KGModule Knowledge-Graph Ecosystem},
|
|
765
|
-
version = {0.
|
|
821
|
+
version = {0.29.0},
|
|
766
822
|
year = {2026},
|
|
767
823
|
publisher = {Flux-Frontiers},
|
|
768
824
|
url = {https://github.com/Flux-Frontiers/KG_utils},
|
|
@@ -9,7 +9,7 @@ build-backend = "poetry.core.masonry.api"
|
|
|
9
9
|
|
|
10
10
|
[project]
|
|
11
11
|
name = "kgmodule-utils"
|
|
12
|
-
version = "0.
|
|
12
|
+
version = "0.29.0"
|
|
13
13
|
description = "Shared types, graph store, semantic index, and pipeline base for the KGModule SDK"
|
|
14
14
|
readme = "README.md"
|
|
15
15
|
license = "Elastic-2.0"
|
|
@@ -29,9 +29,8 @@ requires-python = ">=3.12,<3.14"
|
|
|
29
29
|
dependencies = []
|
|
30
30
|
|
|
31
31
|
[project.optional-dependencies]
|
|
32
|
-
# Embedding stack plus the
|
|
33
|
-
#
|
|
34
|
-
# it here was dead weight — see the `lancedb` extra for legacy stores.
|
|
32
|
+
# Embedding stack plus the vector store, sqlite-vec (the only backend since
|
|
33
|
+
# 0.29.0, when LanceDB support and the `lancedb` extra were removed).
|
|
35
34
|
semantic = [
|
|
36
35
|
"numpy>=1.24.0",
|
|
37
36
|
"rich>=13.0.0,<15.0.0",
|
|
@@ -71,15 +70,10 @@ viz3d-qt = [
|
|
|
71
70
|
"quiltwright>=0.16.0",
|
|
72
71
|
]
|
|
73
72
|
# Exact pin: pre-1.0, breaking minors possible. Prebuilt wheels everywhere;
|
|
74
|
-
# also bundled in `semantic
|
|
73
|
+
# also bundled in `semantic`, since it is the vector store.
|
|
75
74
|
sqlite-vec = [
|
|
76
75
|
"sqlite-vec==0.1.9",
|
|
77
76
|
]
|
|
78
|
-
# LanceDBBackend only, for reading/migrating a legacy un-migrated LanceDB
|
|
79
|
-
# store. Not part of `semantic`; opt in explicitly.
|
|
80
|
-
lancedb = [
|
|
81
|
-
"lancedb>=0.19.0",
|
|
82
|
-
]
|
|
83
77
|
# Document ingestion (kg_utils.ingest): pymupdf4llm converts PDF (the same
|
|
84
78
|
# call doc_kg makes, so both paths agree); anydoc converts Word, PowerPoint,
|
|
85
79
|
# Excel, OpenDocument, RTF, EPUB and CSV. Kept optional because .md/.txt/.rst
|
|
@@ -111,6 +105,21 @@ synthesis-mflux = [
|
|
|
111
105
|
"mflux>=0.9.0",
|
|
112
106
|
]
|
|
113
107
|
|
|
108
|
+
# MCP server base (kg_utils.mcp): serves any KGModule over MCP with the
|
|
109
|
+
# fleet's canonical tools (stats, query, pack, get_node, neighbors) and the
|
|
110
|
+
# standard `<tool> mcp` command. Capped below 2 with the rest of the fleet
|
|
111
|
+
# (kgrag_priv/docs/MCP_MIGRATION.md): mcp 2.0 renames FastMCP, and this
|
|
112
|
+
# module is the one place in the fleet that rename lands. click is declared
|
|
113
|
+
# rather than inherited, because add_mcp_command builds a click command.
|
|
114
|
+
# Floor measured 2026-10-25 by running tests/test_mcp_server.py against each
|
|
115
|
+
# release: 1.23.0 is the first whose FastMCP turns DNS-rebinding protection on
|
|
116
|
+
# by itself for a loopback host, which the streamable-http path relies on, and
|
|
117
|
+
# 1.21.0 and older no longer import against current pydantic.
|
|
118
|
+
mcp = [
|
|
119
|
+
"click>=8.1.0",
|
|
120
|
+
"mcp>=1.23.0,<2",
|
|
121
|
+
]
|
|
122
|
+
|
|
114
123
|
[project.urls]
|
|
115
124
|
Repository = "https://github.com/Flux-Frontiers/kg_utils"
|
|
116
125
|
|
|
@@ -30,6 +30,11 @@ Sub-packages / modules:
|
|
|
30
30
|
kg_utils.retrieval — Shared retrieval helpers: hit_to_dict, attach_content_by_sqlite.
|
|
31
31
|
kg_utils.analysis — ScoreSet, load_scores, available_metrics: persisted
|
|
32
32
|
centrality read back for ranking and visual encoding.
|
|
33
|
+
kg_utils.mcp — make_server, KGServer, add_mcp_command, kg_from, manifest:
|
|
34
|
+
one MCP server base for every KG module, with the
|
|
35
|
+
fleet's canonical tools (stats, query, pack, get_node,
|
|
36
|
+
neighbors) and the standard `<tool> mcp` command
|
|
37
|
+
(needs the 'mcp' extra).
|
|
33
38
|
kg_utils.viz — GraphTheme, TooltipSpec, build_graph_html, select_nodes:
|
|
34
39
|
shared interactive graph rendering (needs the 'viz' extra).
|
|
35
40
|
kg_utils.viz3d — Layout3D, LayoutNode, LayoutEdge, AlliumLayout, FunnelLayout:
|
|
@@ -53,11 +58,10 @@ Optional extras
|
|
|
53
58
|
The core install is stdlib-only; everything heavier is opt-in.
|
|
54
59
|
|
|
55
60
|
pip install 'kgmodule-utils[ingest]' # anydoc — document → Markdown
|
|
61
|
+
pip install 'kgmodule-utils[mcp]' # mcp + click — serve a KG over MCP
|
|
56
62
|
pip install 'kgmodule-utils[semantic]' # sentence-transformers + torch
|
|
57
63
|
# + sqlite-vec (the default backend)
|
|
58
64
|
pip install 'kgmodule-utils[sqlite-vec]' # sqlite-vec alone
|
|
59
|
-
pip install 'kgmodule-utils[lancedb]' # LanceDBBackend, for un-migrated
|
|
60
|
-
# legacy stores only
|
|
61
65
|
pip install 'kgmodule-utils[viz]' # pyvis — interactive graph HTML
|
|
62
66
|
pip install 'kgmodule-utils[viz3d]' # numpy — 3-D graph layout
|
|
63
67
|
pip install 'kgmodule-utils[viz3d-render]' # + pyvista — build the meshes,
|
|
@@ -68,4 +72,4 @@ The core install is stdlib-only; everything heavier is opt-in.
|
|
|
68
72
|
pip install 'kgmodule-utils[synthesis-mflux]' # + mflux (Apple Silicon local gen)
|
|
69
73
|
"""
|
|
70
74
|
|
|
71
|
-
__version__ = "0.
|
|
75
|
+
__version__ = "0.29.0"
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
"""kg_utils.mcp -- one MCP server base for every knowledge-graph module.
|
|
2
|
+
|
|
3
|
+
Needs the ``mcp`` extra: ``pip install 'kgmodule-utils[mcp]'``.
|
|
4
|
+
|
|
5
|
+
A module's whole server::
|
|
6
|
+
|
|
7
|
+
from kg_utils.mcp import Context, add_mcp_command, kg_from, make_server
|
|
8
|
+
|
|
9
|
+
def build_server(repo, db, vectors, model):
|
|
10
|
+
kwargs = {"model": model} if model else {}
|
|
11
|
+
server = make_server(
|
|
12
|
+
lambda: PyCodeKG(repo, db, vectors, **kwargs),
|
|
13
|
+
name="pycodekg",
|
|
14
|
+
kind="code",
|
|
15
|
+
version=__version__,
|
|
16
|
+
)
|
|
17
|
+
|
|
18
|
+
@server.tool()
|
|
19
|
+
def callers(node_id: str, ctx: Context) -> list[dict]:
|
|
20
|
+
\"\"\"Every node that calls this one.\"\"\"
|
|
21
|
+
return kg_from(ctx).callers(node_id)
|
|
22
|
+
|
|
23
|
+
@server.canonical("query") # same name, every canonical parameter kept
|
|
24
|
+
def query(q: str, ctx: Context, k: int = 8, hop: int = 1, max_nodes: int = 25,
|
|
25
|
+
rels: list[str] | None = None, min_score: float = 0.0,
|
|
26
|
+
rerank_mode: str = "hybrid") -> dict:
|
|
27
|
+
\"\"\"Hybrid search, ranked by blended semantic and lexical score.\"\"\"
|
|
28
|
+
...
|
|
29
|
+
|
|
30
|
+
return server
|
|
31
|
+
|
|
32
|
+
add_mcp_command(cli, build_server) # `pycodekg mcp --repo . [--manifest]`
|
|
33
|
+
|
|
34
|
+
The server answers the canonical tools -- ``stats``, ``query``, ``pack``,
|
|
35
|
+
``get_node``, ``neighbors`` -- under the same names on every fleet server, plus
|
|
36
|
+
whatever the module adds. See :mod:`kg_utils.mcp.server` for what belongs here
|
|
37
|
+
and what stays in the KG, and kgrag_priv/docs/MCP_CENTRALIZATION_PLAN.md for
|
|
38
|
+
the decision.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
from __future__ import annotations
|
|
42
|
+
|
|
43
|
+
from typing import TYPE_CHECKING, Any
|
|
44
|
+
|
|
45
|
+
from kg_utils.mcp._names import CANONICAL_TOOLS, TRANSPORTS
|
|
46
|
+
from kg_utils.mcp.cli import BuildServer, add_mcp_command
|
|
47
|
+
|
|
48
|
+
if TYPE_CHECKING:
|
|
49
|
+
from kg_utils.mcp.server import (
|
|
50
|
+
Context,
|
|
51
|
+
KGServer,
|
|
52
|
+
SearchableKG,
|
|
53
|
+
ServableKG,
|
|
54
|
+
describe_tools,
|
|
55
|
+
kg_from,
|
|
56
|
+
make_server,
|
|
57
|
+
manifest,
|
|
58
|
+
run,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
__all__ = [
|
|
62
|
+
"CANONICAL_TOOLS",
|
|
63
|
+
"TRANSPORTS",
|
|
64
|
+
"BuildServer",
|
|
65
|
+
"Context",
|
|
66
|
+
"KGServer",
|
|
67
|
+
"SearchableKG",
|
|
68
|
+
"ServableKG",
|
|
69
|
+
"add_mcp_command",
|
|
70
|
+
"describe_tools",
|
|
71
|
+
"kg_from",
|
|
72
|
+
"make_server",
|
|
73
|
+
"manifest",
|
|
74
|
+
"run",
|
|
75
|
+
]
|
|
76
|
+
|
|
77
|
+
#: Loaded from :mod:`kg_utils.mcp.server` on first use, so that importing this
|
|
78
|
+
#: package -- which a module's CLI does to register ``add_mcp_command`` -- does
|
|
79
|
+
#: not import ``mcp`` (about half a second) on every command.
|
|
80
|
+
_SERVER_NAMES = frozenset(
|
|
81
|
+
{
|
|
82
|
+
"Context",
|
|
83
|
+
"KGServer",
|
|
84
|
+
"SearchableKG",
|
|
85
|
+
"ServableKG",
|
|
86
|
+
"describe_tools",
|
|
87
|
+
"kg_from",
|
|
88
|
+
"make_server",
|
|
89
|
+
"manifest",
|
|
90
|
+
"run",
|
|
91
|
+
}
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def __getattr__(name: str) -> Any:
|
|
96
|
+
if name not in _SERVER_NAMES:
|
|
97
|
+
raise AttributeError(f"module 'kg_utils.mcp' has no attribute {name!r}")
|
|
98
|
+
try:
|
|
99
|
+
from kg_utils.mcp import server # noqa: PLC0415
|
|
100
|
+
except ImportError as exc: # pragma: no cover -- depends on install
|
|
101
|
+
raise ImportError(
|
|
102
|
+
"kg_utils.mcp needs the mcp extra: pip install 'kgmodule-utils[mcp]'"
|
|
103
|
+
) from exc
|
|
104
|
+
return getattr(server, name)
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""kg_utils/mcp/_names.py
|
|
2
|
+
|
|
3
|
+
The two constants a CLI needs before anything imports ``mcp``.
|
|
4
|
+
|
|
5
|
+
Kept apart from :mod:`kg_utils.mcp.server` so that registering the standard
|
|
6
|
+
``<tool> mcp`` command costs nothing: importing ``mcp`` takes about half a
|
|
7
|
+
second, and a module's whole CLI would otherwise pay it on every command, not
|
|
8
|
+
just on ``mcp``.
|
|
9
|
+
|
|
10
|
+
Author: Eric G. Suchanek, PhD
|
|
11
|
+
License: Elastic 2.0
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
__all__ = ["CANONICAL_TOOLS", "TRANSPORTS"]
|
|
17
|
+
|
|
18
|
+
#: The tools every fleet KG server answers, with the same names and meanings.
|
|
19
|
+
CANONICAL_TOOLS: tuple[str, ...] = ("stats", "query", "pack", "get_node", "neighbors")
|
|
20
|
+
|
|
21
|
+
#: Transports :func:`kg_utils.mcp.run` serves. HTTP+SSE is deprecated in the
|
|
22
|
+
#: 2026-07-28 MCP specification and is deliberately absent; streamable HTTP
|
|
23
|
+
#: replaces it.
|
|
24
|
+
TRANSPORTS: tuple[str, ...] = ("stdio", "streamable-http")
|