@ltm-blueverse/alpha-semantic-hub 0.7.0 → 0.7.2
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.
- package/README.md +307 -1567
- package/explorer/src/App.tsx +83 -83
- package/explorer/src/index.css +3 -3
- package/explorer/src/ui/primitives.css +25 -25
- package/explorer/src/workspaces/DecisionWorkspace/DecisionWorkspace.tsx +7 -7
- package/explorer/src/workspaces/DiffMergeWorkspace/DiffMergeWorkspace.tsx +4 -4
- package/explorer/src/workspaces/EnrichWorkspace/EntityResolutionTab.tsx +24 -24
- package/explorer/src/workspaces/EnrichWorkspace/RegistryTab.tsx +22 -22
- package/explorer/src/workspaces/GraphWorkspace/GraphCanvas.tsx +1 -1
- package/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx +18 -18
- package/explorer/src/workspaces/GraphWorkspace/GraphLoadingOverlay.tsx +25 -25
- package/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx +28 -28
- package/explorer/src/workspaces/GraphWorkspace/MarkdownContentViewer.tsx +15 -15
- package/explorer/src/workspaces/GraphWorkspace/graphAnalytics.ts +1 -1
- package/explorer/src/workspaces/GraphWorkspace/graphConfig.ts +15 -15
- package/explorer/src/workspaces/GraphWorkspace/graphSceneLayers.ts +8 -8
- package/explorer/src/workspaces/GraphWorkspace/graphSceneState.ts +11 -11
- package/explorer/src/workspaces/GraphWorkspace/graphTheme.ts +66 -66
- package/explorer/src/workspaces/GraphWorkspace/plugins/explorationEffectsPlugin.tsx +17 -17
- package/explorer/src/workspaces/GraphWorkspace/plugins/explorationEffectsPluginPhaseC.tsx +22 -22
- package/explorer/src/workspaces/GraphWorkspace/plugins/legendPlugin.tsx +7 -7
- package/explorer/src/workspaces/GraphWorkspace/plugins/neighborhoodPanelPlugin.tsx +10 -10
- package/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx +9 -9
- package/explorer/src/workspaces/ImportExportWorkspace/ImportExportWorkspace.tsx +4 -4
- package/explorer/src/workspaces/LineageWorkspace/LineageDiagram.tsx +8 -8
- package/explorer/src/workspaces/ManageWorkspace/KGOverviewTab.tsx +5 -5
- package/explorer/src/workspaces/ManageWorkspace/OntologySummaryTab.tsx +19 -19
- package/explorer/src/workspaces/MemoryWorkspace.tsx +2 -2
- package/explorer/src/workspaces/OntologyWorkspace/AlignmentsTab.tsx +30 -30
- package/explorer/src/workspaces/OntologyWorkspace/HealthTab.tsx +26 -26
- package/explorer/src/workspaces/OntologyWorkspace/OntologyEditor.tsx +32 -32
- package/explorer/src/workspaces/OntologyWorkspace/OntologyLoader.tsx +22 -22
- package/explorer/src/workspaces/OntologyWorkspace/OntologyManager.tsx +40 -40
- package/explorer/src/workspaces/OntologyWorkspace/OntologySearch.tsx +22 -22
- package/explorer/src/workspaces/OntologyWorkspace/ProposalReview.tsx +31 -31
- package/explorer/src/workspaces/OntologyWorkspace/SKOSVocabularyManager.tsx +26 -26
- package/explorer/src/workspaces/OntologyWorkspace/ShaclStudio.tsx +21 -21
- package/explorer/src/workspaces/OntologyWorkspace/VersionsTab.tsx +38 -38
- package/explorer/src/workspaces/OntologyWorkspace/ontologyEditorModel.ts +3 -3
- package/explorer/src/workspaces/ReasoningWorkspace.tsx +4 -4
- package/explorer/src/workspaces/SparqlWorkspace/SparqlWorkspace.tsx +3 -3
- package/explorer/src/workspaces/VocabularyWorkspace/ConceptTree.tsx +3 -3
- package/explorer/src/workspaces/VocabularyWorkspace/ImportDropzone.tsx +4 -4
- package/explorer/src/workspaces/VocabularyWorkspace/PropertyPanel.tsx +8 -8
- package/explorer/src/workspaces/VocabularyWorkspace/Sidebar.tsx +4 -4
- package/explorer/src/workspaces/VocabularyWorkspace/VocabularyWorkspace.tsx +3 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,1674 +1,414 @@
|
|
|
1
|
-
<
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="logo/logo-512.png" alt="Alpha Semantic Hub" width="120" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
<
|
|
5
|
+
<h1 align="center">Alpha Semantic Hub</h1>
|
|
4
6
|
|
|
5
|
-
<
|
|
6
|
-
<
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
<p align="center">
|
|
8
|
+
<strong>Graph-Native Infrastructure for Context and Accountable AI Systems</strong><br/>
|
|
9
|
+
Context graphs · decision intelligence · full provenance tracking · explainable reasoning — every AI decision traceable, every output auditable.
|
|
10
|
+
</p>
|
|
9
11
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
#### *Developer-first, knowledge infrastructure for AI, alternative to expensive enterprise platforms.*
|
|
18
|
-
|
|
19
|
-
> Ingest your enterprise data, extract what matters, build a Context Graph and knowledge graph (KG), and run graph analytics and causal reasoning over all of it, with full decision provenance baked in. Explainable, traceable, and trustworthy by design.
|
|
20
|
-
|
|
21
|
-
**Context Management · Knowledge Modeling · Deterministic Reasoning · Ontology Management · Decision Intelligence · End-to-End Traceability**
|
|
22
|
-
|
|
23
|
-
**Open Source · Governed · Zero Vendor Lock-In**
|
|
24
|
-
|
|
25
|
-
**Polyglot Graph Storage · RDF & LPG Support · W3C Standards · Interoperable**
|
|
26
|
-
|
|
27
|
-
#### Built for High-Stakes, Regulated Domains
|
|
28
|
-
|
|
29
|
-
[](https://github.com/DeejayAI/alpha-semantic-hub) [](https://github.com/DeejayAI/alpha-semantic-hub/network/members) [](https://github.com/DeejayAI/alpha-semantic-hub/graphs/contributors) [](https://pypi.org/project/alphasemantichub/) [](https://pepy.tech/project/alphasemantichub) [](https://www.python.org/) [](https://opensource.org/licenses/MIT) [](https://github.com/DeejayAI/alpha-semantic-hub/actions) [](https://github.com/DeejayAI/alpha-semantic-hub/actions/workflows/install-matrix.yml) [](https://scorecard.dev/viewer/?uri=github.com/DeejayAI/alpha-semantic-hub) [](https://deepwiki.com/DeejayAI/alpha-semantic-hub)
|
|
30
|
-
|
|
31
|
-
[](https://alphahub.ltmb.io/)
|
|
32
|
-
[](https://docs.alphahub.ltmb.io/)
|
|
33
|
-
[](https://discord.gg/sV34vps5hH)
|
|
34
|
-
[](https://x.com/BuildAlpha Semantic Hub)
|
|
35
|
-
|
|
36
|
-
[](https://www.youtube.com/watch?v=QfnNZg4-dZA)
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
pip install alphasemantichub
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
</div>
|
|
44
|
-
|
|
45
|
-
[English](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=en) · [Deutsch](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=de) · [Français](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=fr) · [Español](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=es) · [Italiano](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=it) · [Português](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=pt) · [العربية](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=ar) · [اردو](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=ur) · [हिन्दी](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=hi) · [中文](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=zh) · [日本語](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=ja) · [한국어](https://readme-i18n.com/DeejayAI/alpha-semantic-hub?lang=ko)
|
|
12
|
+
<p align="center">
|
|
13
|
+
<a href="https://github.com/DeejayAI/alpha-semantic-hub/pkgs/npm"><img alt="npm" src="https://img.shields.io/badge/npm-%40ltm--blueverse-E11D2E?logo=npm&logoColor=white"></a>
|
|
14
|
+
<a href="https://github.com/DeejayAI/alpha-semantic-hub/releases"><img alt="GitHub release" src="https://img.shields.io/badge/python%20wheel-GitHub%20Releases-E11D2E?logo=github"></a>
|
|
15
|
+
<img alt="docker" src="https://img.shields.io/badge/docker-ltmbios%2Falpha--hub--studio-E11D2E?logo=docker&logoColor=white">
|
|
16
|
+
<img alt="license" src="https://img.shields.io/badge/license-MIT-E11D2E">
|
|
17
|
+
</p>
|
|
46
18
|
|
|
47
19
|
---
|
|
48
20
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
<a href="https://www.youtube.com/watch?v=QfnNZg4-dZA" target="_blank">
|
|
52
|
-
<img
|
|
53
|
-
src="docs/assets/img/alpha-hub-studio-demo.gif"
|
|
54
|
-
alt="Alpha Semantic Hub Knowledge Explorer: live graph, decisions, entity resolution, ontology hub"
|
|
55
|
-
width="900"
|
|
56
|
-
/>
|
|
57
|
-
</a>
|
|
21
|
+
> **Install guide:** see [INSTALL.md](INSTALL.md) for step-by-step install instructions for every platform.
|
|
58
22
|
|
|
59
|
-
|
|
23
|
+
Alpha Semantic Hub is a graph-native context platform rebuilt end-to-end under the
|
|
24
|
+
**LTM Blueverse** identity: red brand system, futuristic "Alpha" logo (a red **A**
|
|
25
|
+
inside a red circle), a redesigned futuristic Studio UI/UX, scoped npm packages,
|
|
26
|
+
harness integrations for every major AI coding agent, and a Docker Studio image.
|
|
60
27
|
|
|
61
|
-
|
|
28
|
+
## Packages
|
|
62
29
|
|
|
63
|
-
|
|
30
|
+
| Artifact | Where | Install |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Python distribution `alphasemantichub` | GitHub Releases (this repo) | `pip install <release wheel URL>` |
|
|
33
|
+
| npm metapackage (harness plugins + skills) | npm `@ltm-blueverse/alpha-semantic-hub` | `npm install @ltm-blueverse/alpha-semantic-hub` |
|
|
34
|
+
| Studio UI (prebuilt static assets) | npm `@ltm-blueverse/alpha-hub-studio` | `npm install @ltm-blueverse/alpha-hub-studio` |
|
|
35
|
+
| Docker Studio image | Docker Desktop / `ltmbios/alpha-hub-studio` | `docker pull ltmbios/alpha-hub-studio:latest` |
|
|
64
36
|
|
|
65
37
|
---
|
|
66
38
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
Alpha Semantic Hub is the semantic/context layer underneath your LLM, vector store, and agent framework: deterministic infrastructure (no LLM required for graph construction, reasoning, or provenance; where an LLM is used, it's optional and vendor-neutral, every major provider supported, OpenAI, Anthropic, Gemini, and more, via `alphasemantichub.llms`) that turns fragmented enterprise data into a structured, queryable Context Graph and knowledge graph that carries the business context, not just the data structure. Ontologies and controlled vocabularies (OWL, SHACL, SKOS) make what an entity *means* to your business, its definitions, relationships, and rules, as explicit as the data itself, not just its embedding.
|
|
70
|
-
|
|
71
|
-
Decision provenance and audit trails aren't the product. They fall out of that structure for free, and in domains a regulator can question, the same structure that makes your agent smarter also gives you a straight answer to "why."
|
|
39
|
+
## 1 · Install the Python package
|
|
72
40
|
|
|
73
|
-
|
|
74
|
-
|
|
41
|
+
The Python distribution (`alphasemantichub`; CLI: `alphasemantichub`,
|
|
42
|
+
`alphasemantichub-server`, `alphasemantichub-worker`, `alphasemantichub-explorer`,
|
|
43
|
+
`alphasemantichub-mcp`) is published on **GitHub Releases** (not PyPI).
|
|
75
44
|
|
|
76
|
-
**
|
|
77
|
-
|
|
78
|
-
- **AI/ML platform teams** shipping agents that make consequential decisions and need structured, queryable context, not just a vector index
|
|
79
|
-
- **Enterprise data teams on Databricks, Snowflake, or SAP** turning tables already in the lakehouse or warehouse into a governed, lineage-tracked knowledge graph, without exporting to a third-party SaaS
|
|
80
|
-
- **Compliance, risk, and audit teams** who need a straight answer to "why did the AI do that?" in a format a regulator accepts
|
|
81
|
-
- **Regulated enterprises** (finance, healthcare, legal, government, defense) that can't ship a black box or hand their data to someone else's SaaS to get one
|
|
82
|
-
- **Platform and infra engineers** who want the KG, reasoning, and provenance stack self-hosted and swappable, not locked to one vendor's backend
|
|
83
|
-
- **Data and knowledge engineers** building a KG from messy, multi-source data, where conflicting facts get flagged and duplicates get merged, not silently overwritten
|
|
84
|
-
|
|
85
|
-
**[Quick Start](#quick-start)** · **[Architecture](#architecture)** · **[What You Get](#what-alphasemantichub-gives-you)** · **[Why Alpha Semantic Hub](#why-alphasemantichub)** · **[Decision Intelligence](#decision-intelligence)** · **[Context Graphs](#context-graphs)** · **[Recipe: Audit Trail](#recipe-audit-trail-for-a-regulated-decision)** · **[Module Reference](#module-reference)** · **[Integrations](#integrations)** · **[CLI](#cli)** · **[Performance](#performance)** · **[Install](#installation)**
|
|
86
|
-
|
|
87
|
-
---
|
|
88
|
-
|
|
89
|
-
## What Alpha Semantic Hub Gives You
|
|
90
|
-
|
|
91
|
-
- **Context Graphs:** A structured, queryable graph of everything your agent knows, decides, and reasons about
|
|
92
|
-
- **Decision Intelligence:** Every decision is a first-class object: traceable, searchable by precedent, and causally linked
|
|
93
|
-
- **AI Governance & Ontology:** SHACL constraints, conflict detection, compliance rules, OWL generation, and SKOS vocabularies, all with a visual editor
|
|
94
|
-
- **Full Auditability:** W3C PROV-O provenance on every fact, exportable to JSON, CSV, or RDF
|
|
95
|
-
- **Deterministic Reasoning:** Forward chaining, Rete network, Datalog, and SPARQL, with fully explainable paths, not black boxes
|
|
96
|
-
- **Knowledge Pipeline:** Multi-source ingestion, entity-aware chunking, NER/relation/event extraction, and graph construction, with semantic dedup and provenance-preserving merges built in
|
|
97
|
-
- **Enterprise Data Platforms:** Native connectors for Databricks (Unity Catalog + Delta Lake), Snowflake, and SAP OData, so data already in your lakehouse or warehouse becomes graph nodes with provenance, no export/import hop
|
|
98
|
-
- **Graph Analytics:** Centrality, community detection, link prediction, and shortest-path queries over the graph you just built
|
|
99
|
-
- **Polyglot Graph Storage:** RDF (Oxigraph, Blazegraph, Jena, RDF4J) and Labeled Property Graphs (Neo4j, FalkorDB, AGE, Neptune), plus vector stores, all swappable without touching your code
|
|
100
|
-
- **Visualization:** Explore any graph, ontology, or timeline in an interactive browser workbench
|
|
101
|
-
- **Drop-in Integrations:** Agno, CrewAI, and LangChain support, a full MCP server, a CLI, a REST API, and plugins across major editors
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Why Alpha Semantic Hub
|
|
106
|
-
|
|
107
|
-
| | Vector DB + RAG | Plain LLM Memory | **Alpha Semantic Hub** |
|
|
108
|
-
| --- | --- | --- | --- |
|
|
109
|
-
| **Recall method** | Embedding similarity | Token window | Graph traversal + semantic search |
|
|
110
|
-
| **Decision history** | Not stored | Not stored | First-class queryable objects |
|
|
111
|
-
| **Provenance** | None | None | W3C PROV-O, source-linked |
|
|
112
|
-
| **Reasoning** | None | Black box | Forward chain, Rete, Datalog, SPARQL |
|
|
113
|
-
| **Conflict detection** | Silent overwrite | Silent overwrite | Detected, flagged, resolved |
|
|
114
|
-
| **Time travel** | No | No | Point-in-time graph snapshots |
|
|
115
|
-
| **Compliance export** | None | None | PROV-O, SHACL, OWL, RDF |
|
|
116
|
-
| **Policy enforcement** | None | None | Built-in rule engine + SHACL |
|
|
117
|
-
| **Entity resolution** | No | No | Blocking + semantic deduplication |
|
|
118
|
-
| **Multi-agent context** | Separate per agent | Separate per agent | Single shared intelligence layer |
|
|
119
|
-
|
|
120
|
-
Alpha Semantic Hub complements your existing stack rather than replacing it. Keep your LLM, vector store, and agent framework exactly as they are; Alpha Semantic Hub adds the decision records, causal reasoning, provenance, ontology governance, conflict detection, and audit trails on top. The reasoning engines, KG construction, and provenance layer are fully deterministic; no LLM is required to use them.
|
|
121
|
-
|
|
122
|
-
---
|
|
123
|
-
|
|
124
|
-
## Quick Start
|
|
45
|
+
**Python ≥ 3.10 required (3.10–3.13 supported).**
|
|
125
46
|
|
|
126
47
|
```bash
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
```python
|
|
131
|
-
from alphasemantichub.context import ContextGraph
|
|
132
|
-
|
|
133
|
-
graph = ContextGraph(advanced_analytics=True)
|
|
134
|
-
|
|
135
|
-
# Every agent decision becomes a queryable, auditable knowledge node
|
|
136
|
-
decision_id = graph.record_decision(
|
|
137
|
-
category="vendor_selection",
|
|
138
|
-
scenario="Choose cloud provider for HIPAA workload",
|
|
139
|
-
reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
|
|
140
|
-
outcome="selected_aws",
|
|
141
|
-
confidence=0.93,
|
|
142
|
-
)
|
|
143
|
-
|
|
144
|
-
# Ask "why did this happen?" and get a real, structured answer
|
|
145
|
-
chain = graph.trace_decision_chain(decision_id) # full causal ancestry
|
|
146
|
-
similar = graph.find_similar_decisions("cloud vendor", max_results=5) # precedents
|
|
147
|
-
impact = graph.analyze_decision_impact(decision_id) # downstream influence map
|
|
148
|
-
compliant = graph.check_decision_rules({"category": "vendor_selection"}) # policy gate
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
**Verify your install in 5 seconds:**
|
|
152
|
-
|
|
153
|
-
```bash
|
|
154
|
-
alphasemantichub doctor
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
**Running in a script or CI?** Progress bars are written only when stdout is an interactive terminal (or a Jupyter notebook), so piping and redirecting stay clean by default. Override with `ASHUB_DISABLE_PROGRESS=1` to silence progress everywhere, or `ASHUB_FORCE_PROGRESS=1` to keep it when stdout is redirected. `ASHUB_DISABLE_PROGRESS` takes precedence.
|
|
158
|
-
|
|
159
|
-
<div align="center">
|
|
160
|
-
|
|
161
|
-
If Alpha Semantic Hub solves a real problem for you, a star helps others find it.
|
|
162
|
-
|
|
163
|
-
**[⭐ Star on GitHub](https://github.com/DeejayAI/alpha-semantic-hub)** · **[Join Discord](https://discord.gg/sV34vps5hH)**
|
|
164
|
-
|
|
165
|
-
</div>
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## Architecture
|
|
170
|
-
|
|
171
|
-
Alpha Semantic Hub is a real end-to-end pipeline, not a single library with a marketing name. Every stage below is a shipping module, independently importable:
|
|
172
|
-
|
|
173
|
-
```
|
|
174
|
-
Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
|
|
175
|
-
→ Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
|
|
176
|
-
→ Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
- **Ingest:** files, web, databases, enterprise data platforms (Databricks, Snowflake, SAP), cloud (Google Drive, Elasticsearch), streams (Kafka, Kinesis), Git, email, MCP
|
|
180
|
-
- **Parse → Normalize → Split:** document parsing, text/entity/date normalization, GraphRAG-native entity-aware chunking
|
|
181
|
-
- **Extract → Conflict Detection → Deduplication:** NER, relations, events, triplets; conflicting facts flagged and resolved before they merge
|
|
182
|
-
- **Knowledge Graph:** `GraphBuilder` constructs the graph; bi-temporal facts and full graph analytics (centrality, communities, link prediction) run on top of it
|
|
183
|
-
- **Ontology · Reasoning · Provenance · Decisions:** the intelligence layer sitting on the KG, with SHACL/OWL governance, Rete/Datalog/SPARQL inference, W3C PROV-O lineage, and first-class decision records
|
|
184
|
-
- **Storage:** polyglot by design, with RDF triple stores (embedded Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J), Labeled Property Graphs (Neo4j, FalkorDB, Apache AGE, AWS Neptune), and vector stores, all swappable without touching your code
|
|
185
|
-
- **Outputs:** export (RDF, OWL, Parquet, Cypher, JSON-LD), interactive visualization, and access via REST API, MCP server, or CLI
|
|
186
|
-
|
|
187
|
-
**→ [Full Mermaid diagrams for the pipeline and the decision intelligence lifecycle](ARCHITECTURE.md)**
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## Decision Intelligence
|
|
192
|
-
|
|
193
|
-
Decision Intelligence turns every AI choice from an ephemeral inference into a permanent, auditable, queryable record. It answers *"what did your AI decide, why, and what happened next?"*: the question regulators and enterprise risk teams ask with increasing urgency.
|
|
194
|
-
|
|
195
|
-
In Alpha Semantic Hub, a decision is not a log line. It is a first-class graph node with a full lifecycle. In regulated domains, every AI decision must be traceable to a source and defensible to an auditor: `record_decision()` creates a permanent, structured record exportable as W3C PROV-O, the format most compliance frameworks accept for regulator submission.
|
|
196
|
-
|
|
197
|
-
```
|
|
198
|
-
record_decision() → stored as a graph node with full structured context
|
|
199
|
-
add_causal_relationship() → linked to upstream causes and downstream effects
|
|
200
|
-
find_similar_decisions() → semantic precedent search across all past decisions
|
|
201
|
-
trace_decision_chain() → full causal ancestry back to root causes
|
|
202
|
-
analyze_decision_impact() → downstream influence map - everything this decision affected
|
|
203
|
-
check_decision_rules() → policy compliance gate against configurable rule sets
|
|
204
|
-
export / audit trail → W3C PROV-O, CSV, or JSON for regulator submission
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
```python
|
|
208
|
-
from alphasemantichub.context import ContextGraph
|
|
209
|
-
|
|
210
|
-
graph = ContextGraph(advanced_analytics=True)
|
|
211
|
-
|
|
212
|
-
# Record decisions with full structured context
|
|
213
|
-
app_id = graph.record_decision(
|
|
214
|
-
category="credit_application",
|
|
215
|
-
scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
|
|
216
|
-
reasoning="Income meets threshold; employment stable; no adverse credit events",
|
|
217
|
-
outcome="proceed_to_underwriting",
|
|
218
|
-
confidence=0.88,
|
|
219
|
-
metadata={"applicant_id": "A-7291"},
|
|
220
|
-
)
|
|
221
|
-
uw_id = graph.record_decision(
|
|
222
|
-
category="loan_underwriting",
|
|
223
|
-
scenario="Underwriting review for A-7291",
|
|
224
|
-
reasoning="DTI within policy; clean 36-month credit history",
|
|
225
|
-
outcome="approved",
|
|
226
|
-
confidence=0.94,
|
|
227
|
-
)
|
|
228
|
-
rate_id = graph.record_decision(
|
|
229
|
-
category="interest_rate",
|
|
230
|
-
scenario="Rate assignment for approved loan A-7291",
|
|
231
|
-
outcome="rate_set_8.9pct",
|
|
232
|
-
reasoning="Prime + 2.4% based on risk tier B2",
|
|
233
|
-
confidence=0.99,
|
|
234
|
-
)
|
|
235
|
-
|
|
236
|
-
# Build the auditable causal chain - relationship_type must be one of
|
|
237
|
-
# CAUSED, INFLUENCED, or PRECEDENT_FOR
|
|
238
|
-
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")
|
|
239
|
-
graph.add_causal_relationship(uw_id, rate_id, relationship_type="INFLUENCED")
|
|
240
|
-
|
|
241
|
-
# Query the intelligence
|
|
242
|
-
chain = graph.trace_decision_chain(rate_id)
|
|
243
|
-
similar = graph.find_similar_decisions("personal loan approval, 31% DTI", max_results=5)
|
|
244
|
-
impact = graph.analyze_decision_impact(uw_id)
|
|
245
|
-
compliant = graph.check_decision_rules({"category": "loan_underwriting", "confidence": 0.94})
|
|
246
|
-
insights = graph.get_decision_insights()
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
---
|
|
250
|
-
|
|
251
|
-
## Context Graphs
|
|
252
|
-
|
|
253
|
-
A Context Graph is the structured memory layer that traditional RAG is missing. Instead of flat embeddings that answer *"what is similar?"*, a Context Graph answers *"what is connected, why, and how?"* Every entity, relationship, decision, and fact is a first-class node, queryable by graph traversal. Entities link to source documents, decisions link to evidence and consequences, facts carry full provenance, and conflicts are detected, not silently overwritten.
|
|
254
|
-
|
|
255
|
-
```python
|
|
256
|
-
from alphasemantichub.context import ContextGraph, AgentContext
|
|
257
|
-
from alphasemantichub.vector_store import VectorStore
|
|
258
|
-
|
|
259
|
-
graph = ContextGraph(advanced_analytics=True)
|
|
48
|
+
# latest release wheel
|
|
49
|
+
pip install https://github.com/DeejayAI/alpha-semantic-hub/releases/latest/download/alphasemantichub-0.7.1-py3-none-any.whl
|
|
260
50
|
|
|
261
|
-
#
|
|
262
|
-
|
|
263
|
-
graph.add_node("alice_chen", "Person", name="Alice Chen", role="CTO")
|
|
264
|
-
graph.add_node("contract_001", "Contract", value=2_400_000, currency="USD")
|
|
51
|
+
# or from a specific release tag
|
|
52
|
+
pip install https://github.com/DeejayAI/alpha-semantic-hub/releases/download/v0.7.1/alphasemantichub-0.7.1-py3-none-any.whl
|
|
265
53
|
|
|
266
|
-
#
|
|
267
|
-
|
|
268
|
-
graph.add_edge("acme_corp", "contract_001", edge_type="party_to", signed="2024-01-15")
|
|
269
|
-
|
|
270
|
-
# BFS traversal - hop through the graph from any node
|
|
271
|
-
neighbors = graph.get_neighbors("acme_corp", hops=2)
|
|
272
|
-
|
|
273
|
-
# Point-in-time snapshot - the graph as it existed on any past date
|
|
274
|
-
snapshot = graph.state_at("2024-01-01")
|
|
275
|
-
|
|
276
|
-
# AgentContext - high-level API for agent memory workflows
|
|
277
|
-
vs = VectorStore(backend="faiss")
|
|
278
|
-
ctx = AgentContext(vector_store=vs, knowledge_graph=graph)
|
|
279
|
-
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
|
|
280
|
-
retrieved = ctx.retrieve("who approved the Acme contract?")
|
|
54
|
+
# with optional extras
|
|
55
|
+
pip install "https://github.com/DeejayAI/alpha-semantic-hub/releases/latest/download/alphasemantichub-0.7.1-py3-none-any.whl[explorer]"
|
|
281
56
|
```
|
|
282
57
|
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
---
|
|
286
|
-
|
|
287
|
-
## Recipe: Audit Trail for a Regulated Decision
|
|
288
|
-
|
|
289
|
-
One pattern built on the same Context Graph: record a causally-linked decision chain, attach provenance to every entity, and export a regulator-ready audit trail.
|
|
290
|
-
|
|
291
|
-
```python
|
|
292
|
-
from alphasemantichub.context import ContextGraph
|
|
293
|
-
from alphasemantichub.provenance import ProvenanceManager
|
|
294
|
-
from alphasemantichub.export import RDFExporter
|
|
295
|
-
|
|
296
|
-
graph = ContextGraph(advanced_analytics=True)
|
|
297
|
-
prov = ProvenanceManager(storage_path="./audit.db")
|
|
298
|
-
|
|
299
|
-
# Record the decision chain
|
|
300
|
-
d1 = graph.record_decision(
|
|
301
|
-
category="drug_interaction_check", scenario="Patient P-4821: warfarin + amiodarone co-prescribed",
|
|
302
|
-
reasoning="Amiodarone potentiates warfarin's anticoagulant effect", outcome="flag_for_review", confidence=0.91,
|
|
303
|
-
)
|
|
304
|
-
d2 = graph.record_decision(
|
|
305
|
-
category="dosage_adjustment", scenario="INR monitoring plan for P-4821",
|
|
306
|
-
reasoning="Reduce warfarin dose per interaction severity; recheck INR in 5 days", outcome="dose_reduced_30pct", confidence=0.87,
|
|
307
|
-
)
|
|
308
|
-
# relationship_type must be one of CAUSED, INFLUENCED, or PRECEDENT_FOR
|
|
309
|
-
graph.add_causal_relationship(d1, d2, relationship_type="CAUSED")
|
|
310
|
-
|
|
311
|
-
# Track provenance for every entity
|
|
312
|
-
prov.track_entity("patient_P4821", source="ehr/medication_orders_2024.json",
|
|
313
|
-
metadata={"extractor": "NamedEntityRecognizer"})
|
|
314
|
-
|
|
315
|
-
# Export W3C PROV-O for regulator submission - to_kg_dict() is the official
|
|
316
|
-
# adapter that emits the {"entities": [...], "relationships": [...]} /
|
|
317
|
-
# source_id shape RDFExporter expects, so no manual field mapping is needed
|
|
318
|
-
kg = graph.to_kg_dict()
|
|
319
|
-
RDFExporter().export(kg, "audit_trail.ttl", format="turtle")
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
More recipes (GraphRAG pipelines, an AML rules engine, ontology-to-KG in one pass) are in **[More Recipes](#more-recipes)** below.
|
|
323
|
-
|
|
324
|
-
---
|
|
325
|
-
|
|
326
|
-
## Explore the Platform
|
|
327
|
-
|
|
328
|
-
Every module below is independently importable, with working code samples verified against the current source tree; use one or all of them.
|
|
329
|
-
|
|
330
|
-
| Module | What it does |
|
|
331
|
-
| --- | --- |
|
|
332
|
-
| [`alphasemantichub.ingest`](#alphasemantichubingest-multi-source-ingestion) | Files, web, databases, APIs, streams, email, Git, Parquet, Databricks, Snowflake, SAP, MCP |
|
|
333
|
-
| [`alphasemantichub.semantic_extract`](#alphasemantichubsemantic_extract-ner-relations-events-triplets) | NER, relation extraction, event detection, triplet generation |
|
|
334
|
-
| [`alphasemantichub.kg`](#alphasemantichubkg-knowledge-graph-construction--analysis) | Graph construction, centrality, communities, link prediction |
|
|
335
|
-
| [`alphasemantichub.reasoning`](#alphasemantichubreasoning-forward-chaining-rete-datalog-sparql) | Forward chaining, Rete, Datalog, SPARQL, fully explainable |
|
|
336
|
-
| [`alphasemantichub.vector_store`](#alphasemantichubvector_store-hybrid--filtered-semantic-search) | FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, hybrid search |
|
|
337
|
-
| [`alphasemantichub.split`](#alphasemantichubsplit-graphrag-native-document-chunking) | Entity-aware, relation-aware, ontology-aware chunking for GraphRAG |
|
|
338
|
-
| [`alphasemantichub.provenance`](#alphasemantichubprovenance-w3c-prov-o-lineage) | W3C PROV-O lineage on every fact |
|
|
339
|
-
| [`alphasemantichub.ontology`](#alphasemantichubontology-owl-generation-shacl-validation) | OWL generation, SHACL validation, SKOS vocabularies |
|
|
340
|
-
| [`alphasemantichub.conflicts`](#alphasemantichubconflicts-conflict-detection--resolution) | Detect and resolve conflicting facts across sources |
|
|
341
|
-
| [`alphasemantichub.deduplication`](#alphasemantichubdeduplication-entity-resolution-at-scale) | Entity resolution at scale |
|
|
342
|
-
| [`alphasemantichub.normalize`](#alphasemantichubnormalize-data-normalization--cleaning) | Text, entity, date, and number normalization; dataset cleaning |
|
|
343
|
-
| [`alphasemantichub.pipeline`](#alphasemantichubpipeline-pipeline-dsl) | Declarative, parallel pipeline DSL for ingest → extract → build → export |
|
|
344
|
-
| [`alphasemantichub.export`](#alphasemantichubexport-rdf-owl-parquet-cypher-json-ld) | RDF, OWL, Parquet, Cypher, JSON-LD |
|
|
345
|
-
| [`alphasemantichub.visualization`](#alphasemantichubvisualization-interactive-graph-workbench) | Force-directed graphs, ontology hierarchies, temporal dashboards |
|
|
346
|
-
| [Temporal Intelligence](#temporal-intelligence-bi-temporal-graphs--time-travel) | Bi-temporal facts, Allen interval algebra, time travel |
|
|
347
|
-
| [Multi-Agent (Agno)](#multi-agent-shared-context-with-agno) | One shared context graph across every agent on a team |
|
|
348
|
-
|
|
349
|
-
**↓ Expand [Module Reference](#module-reference) below** for every module's working example, or jump to [More Recipes](#more-recipes), the full [Integrations](#integrations) matrix, [MCP tool list](#mcp-server), and [REST endpoints](#rest-api).
|
|
350
|
-
|
|
351
|
-
---
|
|
352
|
-
|
|
353
|
-
## Module Reference
|
|
354
|
-
|
|
355
|
-
Expand any module below for its runnable example.
|
|
356
|
-
|
|
357
|
-
<details>
|
|
358
|
-
<summary><b><code>alphasemantichub.ingest</code></b>: Multi-Source Ingestion</summary>
|
|
359
|
-
<a id="alphasemantichubingest-multi-source-ingestion"></a>
|
|
360
|
-
|
|
361
|
-
Ingest from files, web, databases, APIs, streams, email, Git repos, Parquet, Databricks, Snowflake, SAP, or MCP servers, all through a unified interface.
|
|
362
|
-
|
|
363
|
-
```python
|
|
364
|
-
# WebIngestor needs the documents extra: pip install "alphasemantichub[documents]"
|
|
365
|
-
from alphasemantichub.ingest import FileIngestor, WebIngestor, ParquetIngestor, DBIngestor
|
|
366
|
-
|
|
367
|
-
# Ingest an entire directory of contracts (PDF, DOCX, HTML, TXT)
|
|
368
|
-
docs = FileIngestor().ingest_directory("./contracts/", recursive=True)
|
|
369
|
-
|
|
370
|
-
# Ingest live web content with robots.txt compliance
|
|
371
|
-
pages = WebIngestor().ingest_url("https://example.com/reports/annual-2024.html")
|
|
372
|
-
|
|
373
|
-
# Ingest structured data from Parquet with Snappy compression
|
|
374
|
-
records = ParquetIngestor().ingest("./data/transactions.parquet")
|
|
375
|
-
|
|
376
|
-
# Ingest from a SQL database - specify which tables to pull
|
|
377
|
-
rows = DBIngestor().ingest_database(
|
|
378
|
-
connection_string="postgresql://user:pass@localhost/mydb",
|
|
379
|
-
include_tables=["customer_events"],
|
|
380
|
-
max_rows_per_table=50_000,
|
|
381
|
-
)
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
```python
|
|
385
|
-
# Enterprise data platforms - pull tables straight out of your lakehouse
|
|
386
|
-
# or warehouse, with lineage, instead of exporting to CSV first
|
|
387
|
-
from alphasemantichub.ingest import DatabricksIngestor, SnowflakeIngestor
|
|
388
|
-
|
|
389
|
-
# pip install "alphasemantichub[db-databricks]"
|
|
390
|
-
databricks = DatabricksIngestor(
|
|
391
|
-
host="https://adb-xxx.azuredatabricks.net",
|
|
392
|
-
token="dapi-xxxxxxxx", # or client_id/client_secret for OAuth M2M
|
|
393
|
-
http_path="/sql/1.0/warehouses/xxxxxxxx",
|
|
394
|
-
catalog="main",
|
|
395
|
-
)
|
|
396
|
-
customers = databricks.ingest_table("customers", limit=10_000)
|
|
397
|
-
sales = databricks.ingest_query("SELECT * FROM sales WHERE region = 'EMEA'")
|
|
398
|
-
table_lineage = databricks.get_table_lineage("customers", catalog="main", schema="default") # Unity Catalog lineage
|
|
399
|
-
|
|
400
|
-
# pip install alphasemantichub[db-snowflake]
|
|
401
|
-
snowflake = SnowflakeIngestor(
|
|
402
|
-
account="myaccount",
|
|
403
|
-
user="myuser",
|
|
404
|
-
password="mypassword", # or private_key=... for key-pair; use authenticator="oauth", token=... for OAuth
|
|
405
|
-
warehouse="COMPUTE_WH",
|
|
406
|
-
database="MYDB",
|
|
407
|
-
)
|
|
408
|
-
orders = snowflake.ingest_table("ORDERS", limit=10_000)
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
> **Security Note:** Never hardcode credentials (`token`, `password`, `private_key`) in production code; pass them via environment variables (e.g., `DATABRICKS_TOKEN`, `SNOWFLAKE_PASSWORD`) or a secrets manager.
|
|
412
|
-
|
|
413
|
-
**Supported sources:** Local files (PDF, DOCX, PPTX, HTML, TXT, CSV, JSON, YAML, Excel, XML) · Web pages · RSS/Atom feeds · REST APIs · Databases (PostgreSQL, MySQL, SQLite, Oracle, SQL Server) · Parquet datasets · Databricks (Unity Catalog + Delta Lake) · Snowflake · SAP (OData v2/v4) · Git repositories · Email (IMAP/POP3) · Message streams (Kafka, RabbitMQ, Kinesis, Pulsar) · MCP resources · Apache Arrow/Feather/IPC (`ArrowIngestor`)
|
|
414
|
-
|
|
415
|
-
DuckDB, Elasticsearch, Google Drive, HuggingFace, MongoDB, and Pandas ingestion also ship (`DuckDBIngestor`, `ElasticIngestor`, `GDriveIngestor`, `HuggingFaceIngestor`, `MongoIngestor`, `PandasIngestor`) but aren't re-exported from the top-level `alphasemantichub.ingest` namespace yet — import them directly: `from alphasemantichub.ingest.duckdb_ingestor import DuckDBIngestor`.
|
|
416
|
-
|
|
417
|
-
</details>
|
|
418
|
-
|
|
419
|
-
<details>
|
|
420
|
-
<summary><b><code>alphasemantichub.semantic_extract</code></b>: NER, Relations, Events, Triplets</summary>
|
|
421
|
-
<a id="alphasemantichubsemantic_extract-ner-relations-events-triplets"></a>
|
|
422
|
-
|
|
423
|
-
Extract structured knowledge from raw text in one pass.
|
|
424
|
-
|
|
425
|
-
```python
|
|
426
|
-
from alphasemantichub.semantic_extract import (
|
|
427
|
-
NamedEntityRecognizer,
|
|
428
|
-
RelationExtractor,
|
|
429
|
-
EventDetector,
|
|
430
|
-
TripletExtractor,
|
|
431
|
-
)
|
|
432
|
-
|
|
433
|
-
text = """
|
|
434
|
-
Anthropic CEO Dario Amodei announced a $7.3B Series E funding round in partnership
|
|
435
|
-
with Google and Spark Capital, valuing the company at $61.5B as of Q4 2024.
|
|
436
|
-
"""
|
|
437
|
-
|
|
438
|
-
# Named entity recognition with confidence thresholding
|
|
439
|
-
ner = NamedEntityRecognizer(confidence_threshold=0.7)
|
|
440
|
-
entities = ner.extract_entities(text)
|
|
441
|
-
# → [Entity(name="Dario Amodei", type="PERSON"), Entity(name="Anthropic", type="ORG"),
|
|
442
|
-
# Entity(name="Google", type="ORG"), Entity(name="$7.3B", type="MONEY"), ...]
|
|
443
|
-
|
|
444
|
-
# Relationship extraction - bidirectional support
|
|
445
|
-
rel_extractor = RelationExtractor(confidence_threshold=0.6, bidirectional=True)
|
|
446
|
-
relations = rel_extractor.extract_relations(text, entities=entities)
|
|
447
|
-
# → [Relation(subject="Dario Amodei", predicate="ceo_of", object="Anthropic"),
|
|
448
|
-
# Relation(subject="Anthropic", predicate="raised", object="$7.3B Series E"), ...]
|
|
449
|
-
|
|
450
|
-
# Event detection with temporal processing
|
|
451
|
-
events = EventDetector(extract_participants=True, extract_time=True).detect_events(text)
|
|
452
|
-
# → [Event(type="FUNDING", participants=["Anthropic","Google","Spark Capital"],
|
|
453
|
-
# amount="$7.3B", date="Q4 2024")]
|
|
454
|
-
|
|
455
|
-
# RDF triplets with optional provenance metadata
|
|
456
|
-
triplets = TripletExtractor(include_temporal=True, include_provenance=True).extract_triplets(text)
|
|
457
|
-
# → [("Anthropic", "valuation", "$61.5B"), ("Dario Amodei", "is_ceo_of", "Anthropic"), ...]
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
Batch processing across many documents uses `ner.process_batch([...])`, not a per-call `extract_entities_batch` on the facade class.
|
|
461
|
-
|
|
462
|
-
</details>
|
|
463
|
-
|
|
464
|
-
<details>
|
|
465
|
-
<summary><b><code>alphasemantichub.kg</code></b>: Knowledge Graph Construction & Analysis</summary>
|
|
466
|
-
<a id="alphasemantichubkg-knowledge-graph-construction--analysis"></a>
|
|
467
|
-
|
|
468
|
-
Build a production knowledge graph from documents and run graph algorithms over it.
|
|
469
|
-
|
|
470
|
-
```python
|
|
471
|
-
from alphasemantichub.ingest import FileIngestor
|
|
472
|
-
from alphasemantichub.kg import (
|
|
473
|
-
GraphBuilder,
|
|
474
|
-
GraphAnalyzer,
|
|
475
|
-
CentralityCalculator,
|
|
476
|
-
CommunityDetector,
|
|
477
|
-
PathFinder,
|
|
478
|
-
LinkPredictor,
|
|
479
|
-
BiTemporalFact,
|
|
480
|
-
)
|
|
481
|
-
from datetime import datetime
|
|
482
|
-
|
|
483
|
-
# Build KG - merge duplicate entities, track temporal edges
|
|
484
|
-
sources = FileIngestor().ingest_directory("./contracts/", recursive=True)
|
|
485
|
-
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)
|
|
486
|
-
|
|
487
|
-
# Graph analytics
|
|
488
|
-
analyzer = GraphAnalyzer()
|
|
489
|
-
analysis = analyzer.analyze_graph(kg) # full graph metrics
|
|
490
|
-
|
|
491
|
-
centrality = CentralityCalculator()
|
|
492
|
-
degree = centrality.calculate_degree_centrality(kg) # most-connected entities
|
|
493
|
-
betweenness = centrality.calculate_betweenness_centrality(kg)
|
|
494
|
-
|
|
495
|
-
communities = CommunityDetector().detect_communities(kg, method="louvain") # natural clusters
|
|
496
|
-
path = PathFinder().find_shortest_path(kg, "alice_chen", "contract_001")
|
|
497
|
-
predictions = LinkPredictor().predict_links(kg, top_k=10) # relationship predictions
|
|
498
|
-
|
|
499
|
-
# Bi-temporal facts - track valid time vs. recorded time independently
|
|
500
|
-
fact = BiTemporalFact(
|
|
501
|
-
valid_from=datetime(2024, 3, 1),
|
|
502
|
-
valid_until=datetime(2025, 1, 1),
|
|
503
|
-
recorded_at=datetime(2024, 3, 5),
|
|
504
|
-
)
|
|
505
|
-
```
|
|
506
|
-
|
|
507
|
-
</details>
|
|
508
|
-
|
|
509
|
-
<details>
|
|
510
|
-
<summary><b><code>alphasemantichub.reasoning</code></b>: Forward Chaining, Rete, Datalog, SPARQL</summary>
|
|
511
|
-
<a id="alphasemantichubreasoning-forward-chaining-rete-datalog-sparql"></a>
|
|
512
|
-
|
|
513
|
-
Run explainable rule-based inference, not a black box.
|
|
514
|
-
|
|
515
|
-
```python
|
|
516
|
-
from alphasemantichub.reasoning import ReteEngine, Rule, Fact, RuleType
|
|
517
|
-
|
|
518
|
-
rete = ReteEngine()
|
|
519
|
-
rete.build_network([
|
|
520
|
-
Rule(
|
|
521
|
-
rule_id="aml_flag",
|
|
522
|
-
name="Flag high-risk transactions",
|
|
523
|
-
conditions=[
|
|
524
|
-
{"field": "amount", "operator": ">", "value": 10_000},
|
|
525
|
-
{"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
|
|
526
|
-
],
|
|
527
|
-
conclusion="flag_for_compliance_review",
|
|
528
|
-
rule_type=RuleType.IMPLICATION,
|
|
529
|
-
),
|
|
530
|
-
Rule(
|
|
531
|
-
rule_id="velocity_check",
|
|
532
|
-
name="Flag rapid sequential transfers",
|
|
533
|
-
conditions=[
|
|
534
|
-
{"field": "transfers_in_1h", "operator": ">", "value": 5},
|
|
535
|
-
{"field": "total_amount", "operator": ">", "value": 50_000},
|
|
536
|
-
],
|
|
537
|
-
conclusion="flag_velocity_breach",
|
|
538
|
-
rule_type=RuleType.IMPLICATION,
|
|
539
|
-
),
|
|
540
|
-
])
|
|
541
|
-
|
|
542
|
-
rete.add_fact(Fact("tx_001", "transaction", [{"amount": 15_000, "country": "IR"}]))
|
|
543
|
-
flagged = rete.match_patterns()
|
|
544
|
-
# → [{"rule": "aml_flag", "matched_facts": ["tx_001"], "conclusion": "flag_for_compliance_review"}]
|
|
545
|
-
```
|
|
546
|
-
|
|
547
|
-
> **Current limitation:** `ReteEngine`'s alpha-node condition matcher is intentionally simple in this release — validate `match_patterns()` output against your actual rule set before wiring it into a production compliance gate; more selective condition evaluation is on the roadmap.
|
|
548
|
-
|
|
549
|
-
```python
|
|
550
|
-
# Recursive Datalog - natural language for graph queries
|
|
551
|
-
from alphasemantichub.reasoning import DatalogReasoner
|
|
552
|
-
|
|
553
|
-
engine = DatalogReasoner()
|
|
554
|
-
engine.add_fact("parent(tom, bob)")
|
|
555
|
-
engine.add_fact("parent(bob, ann)")
|
|
556
|
-
engine.add_fact("parent(ann, pat)")
|
|
557
|
-
engine.add_rule("ancestor(X, Y) :- parent(X, Y).")
|
|
558
|
-
engine.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")
|
|
559
|
-
ancestors = engine.query("ancestor(tom, ?X)")
|
|
560
|
-
# → [{"X": "bob"}, {"X": "ann"}, {"X": "pat"}]
|
|
561
|
-
```
|
|
562
|
-
|
|
563
|
-
```python
|
|
564
|
-
# Explainable reasoning - trace the path, not just the answer
|
|
565
|
-
from alphasemantichub.reasoning import ExplanationGenerator, Reasoner
|
|
566
|
-
|
|
567
|
-
reasoner = Reasoner()
|
|
568
|
-
reasoner.add_fact("parent(tom, bob)")
|
|
569
|
-
reasoner.add_rule("ancestor(X, Y) :- parent(X, Y)")
|
|
570
|
-
result = reasoner.forward_chain()
|
|
571
|
-
|
|
572
|
-
explainer = ExplanationGenerator()
|
|
573
|
-
explanation = explainer.generate_explanation(result)
|
|
574
|
-
# → Explanation(conclusion="...", steps=[ReasoningStep(...)], justification=Justification(...))
|
|
575
|
-
```
|
|
576
|
-
|
|
577
|
-
</details>
|
|
578
|
-
|
|
579
|
-
<details>
|
|
580
|
-
<summary><b><code>alphasemantichub.vector_store</code></b>: Hybrid & Filtered Semantic Search</summary>
|
|
581
|
-
<a id="alphasemantichubvector_store-hybrid--filtered-semantic-search"></a>
|
|
582
|
-
|
|
583
|
-
Drop-in vector store with multiple backends, hybrid search, and decision-aware retrieval.
|
|
584
|
-
|
|
585
|
-
```python
|
|
586
|
-
from alphasemantichub.vector_store import VectorStore, HybridSearch
|
|
587
|
-
|
|
588
|
-
# In-memory backend shown here: HybridSearch and explain_decision() work out of the box.
|
|
589
|
-
# Swap backend="qdrant" / "weaviate" / "milvus" / "pinecone" / "pgvector" / "faiss" once you
|
|
590
|
-
# scale past a single process — search() and store_decision() work identically on all of them.
|
|
591
|
-
vs = VectorStore(backend="inmemory", dimension=1536)
|
|
592
|
-
|
|
593
|
-
# Store a decision with scenario description and outcome
|
|
594
|
-
vs.store_decision(
|
|
595
|
-
scenario="Personal loan A-7291, $85k income, 31% DTI, 3yr employment",
|
|
596
|
-
outcome="approved",
|
|
597
|
-
confidence=0.94,
|
|
598
|
-
category="loan_underwriting",
|
|
599
|
-
)
|
|
600
|
-
|
|
601
|
-
# Semantic similarity search
|
|
602
|
-
results = vs.search(
|
|
603
|
-
query="personal loan approval with low DTI",
|
|
604
|
-
limit=10,
|
|
605
|
-
)
|
|
606
|
-
|
|
607
|
-
# Hybrid search - dense + sparse retrieval in one pass with RRF fusion
|
|
608
|
-
hs = HybridSearch(vector_store=vs)
|
|
609
|
-
hits = hs.search("high-risk transactions 2024")
|
|
610
|
-
|
|
611
|
-
# Explain why a decision was retrieved
|
|
612
|
-
explanation = vs.explain_decision(results[0]["id"])
|
|
613
|
-
```
|
|
614
|
-
|
|
615
|
-
**Backends:** `faiss` · `qdrant` · `weaviate` · `milvus` · `pinecone` · `pgvector` · `sqlite` · `inmemory`
|
|
616
|
-
|
|
617
|
-
</details>
|
|
618
|
-
|
|
619
|
-
<details>
|
|
620
|
-
<summary><b><code>alphasemantichub.split</code></b>: GraphRAG-Native Document Chunking</summary>
|
|
621
|
-
<a id="alphasemantichubsplit-graphrag-native-document-chunking"></a>
|
|
622
|
-
|
|
623
|
-
KG-aware splitting that preserves entity boundaries, relation triplets, and ontology concepts, essential for GraphRAG pipelines.
|
|
624
|
-
|
|
625
|
-
```python
|
|
626
|
-
from alphasemantichub.split import TextSplitter, EntityAwareChunker, RelationAwareChunker
|
|
58
|
+
Verify:
|
|
627
59
|
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
# Standard recursive chunking
|
|
631
|
-
chunks = TextSplitter(method="recursive", chunk_size=1000, chunk_overlap=200).split(text)
|
|
632
|
-
|
|
633
|
-
# Entity-aware chunking - never splits a named entity across chunks (GraphRAG)
|
|
634
|
-
chunks = TextSplitter(method="entity_aware", ner_method="llm", chunk_size=1000).split(text)
|
|
635
|
-
|
|
636
|
-
# Relation-aware chunking - preserves (subject, predicate, object) triplets intact
|
|
637
|
-
chunks = RelationAwareChunker(chunk_size=1000, preserve_triplets=True).chunk(text)
|
|
638
|
-
|
|
639
|
-
# Graph-based chunking - uses centrality to find natural community boundaries
|
|
640
|
-
chunks = TextSplitter(method="graph_based", chunk_size=1000).split(text)
|
|
641
|
-
|
|
642
|
-
# Hierarchical chunking - multi-level (section → paragraph → sentence)
|
|
643
|
-
chunks = TextSplitter(method="hierarchical", levels=["section", "paragraph"]).split(text)
|
|
644
|
-
```
|
|
645
|
-
|
|
646
|
-
**Supported methods:** `recursive` · `token` · `sentence` · `paragraph` · `semantic_transformer` · `entity_aware` · `relation_aware` · `graph_based` · `ontology_aware` · `hierarchical` · `community_detection` · `centrality_based` · `llm`
|
|
647
|
-
|
|
648
|
-
</details>
|
|
649
|
-
|
|
650
|
-
<details>
|
|
651
|
-
<summary><b><code>alphasemantichub.provenance</code></b>: W3C PROV-O Lineage</summary>
|
|
652
|
-
<a id="alphasemantichubprovenance-w3c-prov-o-lineage"></a>
|
|
653
|
-
|
|
654
|
-
Every fact is linked to its source. No black boxes, no mystery outputs.
|
|
655
|
-
|
|
656
|
-
```python
|
|
657
|
-
from alphasemantichub.provenance import ProvenanceManager
|
|
658
|
-
|
|
659
|
-
prov = ProvenanceManager(storage_path="./provenance.db")
|
|
660
|
-
|
|
661
|
-
# Track where every entity came from
|
|
662
|
-
prov.track_entity(
|
|
663
|
-
entity_id="acme_corp",
|
|
664
|
-
source="contracts/acme_master_agreement_2024.pdf",
|
|
665
|
-
metadata={"page": 1, "confidence": 0.97, "extractor": "NamedEntityRecognizer"},
|
|
666
|
-
)
|
|
667
|
-
|
|
668
|
-
# Track a relationship's provenance - entity linkage travels in metadata
|
|
669
|
-
prov.track_relationship(
|
|
670
|
-
relationship_id="alice_works_for_acme",
|
|
671
|
-
source="hr_records/employees_q1_2024.csv",
|
|
672
|
-
metadata={"source_entity_id": "alice_chen", "target_entity_id": "acme_corp"},
|
|
673
|
-
)
|
|
674
|
-
|
|
675
|
-
# Answer "where did this come from?"
|
|
676
|
-
lineage = prov.get_lineage("acme_corp")
|
|
677
|
-
trail = prov.trace_lineage("alice_chen") # full ancestor chain
|
|
678
|
-
entry = prov.get_provenance("acme_corp")
|
|
679
|
-
```
|
|
680
|
-
|
|
681
|
-
</details>
|
|
682
|
-
|
|
683
|
-
<details>
|
|
684
|
-
<summary><b><code>alphasemantichub.ontology</code></b>: OWL Generation, SHACL Validation</summary>
|
|
685
|
-
<a id="alphasemantichubontology-owl-generation-shacl-validation"></a>
|
|
686
|
-
|
|
687
|
-
Generate ontologies from data, validate shapes, and manage your vocabulary.
|
|
688
|
-
|
|
689
|
-
```python
|
|
690
|
-
from alphasemantichub.ontology import OntologyGenerator, OntologyValidator
|
|
691
|
-
|
|
692
|
-
data = {
|
|
693
|
-
"entities": [
|
|
694
|
-
{"id": "acme_corp", "type": "Organization", "industry": "SaaS", "founded": 2012},
|
|
695
|
-
{"id": "alice_chen", "type": "Person", "role": "CTO", "since": 2019},
|
|
696
|
-
],
|
|
697
|
-
"relationships": [
|
|
698
|
-
{"source": "alice_chen", "target": "acme_corp", "type": "works_for"},
|
|
699
|
-
],
|
|
700
|
-
}
|
|
701
|
-
|
|
702
|
-
gen = OntologyGenerator(base_uri="https://alphahub.ltmb.io/ontology/")
|
|
703
|
-
ontology = gen.generate_ontology(data)
|
|
704
|
-
classes = gen.infer_classes(data)
|
|
705
|
-
props = gen.infer_properties(data, classes)
|
|
706
|
-
optimized = gen.optimize_ontology(ontology)
|
|
707
|
-
|
|
708
|
-
# Validate against SHACL shapes
|
|
709
|
-
validator = OntologyValidator()
|
|
710
|
-
report = validator.validate(ontology)
|
|
711
|
-
# → ValidationResult(valid=True, consistent=True, satisfiable=True, errors=[], warnings=[])
|
|
712
|
-
```
|
|
713
|
-
|
|
714
|
-
</details>
|
|
715
|
-
|
|
716
|
-
<details>
|
|
717
|
-
<summary><b><code>alphasemantichub.conflicts</code></b>: Conflict Detection & Resolution</summary>
|
|
718
|
-
<a id="alphasemantichubconflicts-conflict-detection--resolution"></a>
|
|
719
|
-
|
|
720
|
-
Detect and resolve conflicting facts from multiple sources before they corrupt your knowledge base.
|
|
721
|
-
|
|
722
|
-
```python
|
|
723
|
-
from alphasemantichub.conflicts import ConflictDetector, ConflictResolver, SourceTracker
|
|
724
|
-
|
|
725
|
-
entities_from_source_a = [
|
|
726
|
-
{"id": "alice_chen", "role": "CTO", "salary": 250_000, "start_date": "2019-03-01"},
|
|
727
|
-
]
|
|
728
|
-
entities_from_source_b = [
|
|
729
|
-
{"id": "alice_chen", "role": "VP Eng", "salary": 275_000, "start_date": "2019-03-01"},
|
|
730
|
-
]
|
|
731
|
-
|
|
732
|
-
# Detect all conflict types: value, type, relationship, temporal, logical
|
|
733
|
-
detector = ConflictDetector()
|
|
734
|
-
conflicts = detector.detect_conflicts(entities_from_source_a + entities_from_source_b)
|
|
735
|
-
# → [Conflict(entity="alice_chen", field="role", values=["CTO","VP Eng"], severity="HIGH"),
|
|
736
|
-
# Conflict(entity="alice_chen", field="salary", values=[250000,275000], severity="MEDIUM")]
|
|
737
|
-
|
|
738
|
-
# Resolve using multiple strategies
|
|
739
|
-
resolver = ConflictResolver()
|
|
740
|
-
resolved = resolver.resolve_conflicts(conflicts, strategy="credibility_weighted") # weighted by source trust
|
|
741
|
-
resolved = resolver.resolve_conflicts(conflicts, strategy="most_recent") # prefer most recent
|
|
742
|
-
resolved = resolver.resolve_conflicts(conflicts, strategy="voting") # majority wins
|
|
743
|
-
|
|
744
|
-
# Track source credibility over time
|
|
745
|
-
tracker = SourceTracker()
|
|
746
|
-
tracker.register_source("source_a", source_type="document", credibility_score=0.85)
|
|
747
|
-
tracker.register_source("source_b", source_type="document", credibility_score=0.72)
|
|
748
|
-
```
|
|
749
|
-
|
|
750
|
-
</details>
|
|
751
|
-
|
|
752
|
-
<details>
|
|
753
|
-
<summary><b><code>alphasemantichub.deduplication</code></b>: Entity Resolution at Scale</summary>
|
|
754
|
-
<a id="alphasemantichubdeduplication-entity-resolution-at-scale"></a>
|
|
755
|
-
|
|
756
|
-
Block, cluster, and merge duplicates with semantic similarity.
|
|
757
|
-
|
|
758
|
-
```python
|
|
759
|
-
from alphasemantichub.deduplication import DuplicateDetector, EntityMerger
|
|
760
|
-
|
|
761
|
-
entities = [
|
|
762
|
-
{"id": "e1", "name": "Acme Corporation", "domain": "acme.com"},
|
|
763
|
-
{"id": "e2", "name": "Acme Corp.", "domain": "acme.com"},
|
|
764
|
-
{"id": "e3", "name": "ACME Corp", "domain": "acme.co"},
|
|
765
|
-
{"id": "e4", "name": "Globex Industries", "domain": "globex.com"},
|
|
766
|
-
]
|
|
767
|
-
|
|
768
|
-
detector = DuplicateDetector(similarity_threshold=0.75, use_clustering=True)
|
|
769
|
-
candidates = detector.detect_duplicates(entities)
|
|
770
|
-
groups = detector.detect_duplicate_groups(entities)
|
|
771
|
-
# → DuplicateGroup(entities=["e1","e2","e3"], confidence=0.91, strategy="semantic+blocking")
|
|
772
|
-
|
|
773
|
-
merger = EntityMerger(preserve_provenance=True)
|
|
774
|
-
ops = merger.merge_duplicates(entities, strategy="keep_most_complete")
|
|
775
|
-
history = merger.get_merge_history()
|
|
776
|
-
```
|
|
777
|
-
|
|
778
|
-
</details>
|
|
779
|
-
|
|
780
|
-
<details>
|
|
781
|
-
<summary><b><code>alphasemantichub.normalize</code></b>: Data Normalization & Cleaning</summary>
|
|
782
|
-
<a id="alphasemantichubnormalize-data-normalization--cleaning"></a>
|
|
783
|
-
|
|
784
|
-
Standardize text, entities, dates, numbers, and encodings before building your knowledge graph.
|
|
785
|
-
|
|
786
|
-
```python
|
|
787
|
-
from alphasemantichub.normalize import (
|
|
788
|
-
TextNormalizer,
|
|
789
|
-
EntityNormalizer,
|
|
790
|
-
DateNormalizer,
|
|
791
|
-
NumberNormalizer,
|
|
792
|
-
DataCleaner,
|
|
793
|
-
)
|
|
794
|
-
|
|
795
|
-
# Unicode, whitespace, casing, HTML tags, smart quotes
|
|
796
|
-
text = TextNormalizer().normalize(" Acme Corp.'s Q4 report... ")
|
|
797
|
-
# → "Acme Corp.'s Q4 report..."
|
|
798
|
-
|
|
799
|
-
# Alias resolution + entity disambiguation with confidence scores
|
|
800
|
-
canonical = EntityNormalizer().normalize_entity("ACME Corp.")
|
|
801
|
-
# → NormalizedEntity(canonical="Acme Corporation", type="Organization", confidence=0.91)
|
|
802
|
-
|
|
803
|
-
# Natural language date parsing with timezone conversion
|
|
804
|
-
dt = DateNormalizer().normalize_date("3 weeks ago")
|
|
805
|
-
# → datetime(2026, 7, 1, tzinfo=UTC)
|
|
806
|
-
|
|
807
|
-
# Numbers with currency symbols and magnitude suffixes
|
|
808
|
-
price = NumberNormalizer().normalize_number("$1.25M")
|
|
809
|
-
# → 1250000.0
|
|
810
|
-
|
|
811
|
-
# Deduplicate, validate, and impute missing values across a dataset
|
|
812
|
-
clean = DataCleaner().clean_data(records, remove_duplicates=True, handle_missing=True)
|
|
813
|
-
```
|
|
814
|
-
|
|
815
|
-
</details>
|
|
816
|
-
|
|
817
|
-
<details>
|
|
818
|
-
<summary><b><code>alphasemantichub.pipeline</code></b>: Pipeline DSL</summary>
|
|
819
|
-
<a id="alphasemantichubpipeline-pipeline-dsl"></a>
|
|
820
|
-
|
|
821
|
-
Compose ingestion, extraction, and graph-building into a declarative, parallel pipeline.
|
|
822
|
-
|
|
823
|
-
```python
|
|
824
|
-
from alphasemantichub.pipeline import PipelineBuilder, ExecutionEngine
|
|
825
|
-
|
|
826
|
-
builder = PipelineBuilder()
|
|
827
|
-
|
|
828
|
-
# add_step() returns the created PipelineStep, not the builder, so these don't chain
|
|
829
|
-
builder.add_step("ingest", step_type="ingest", source="./contracts/", recursive=True)
|
|
830
|
-
builder.add_step("extract", step_type="ner_extract")
|
|
831
|
-
builder.add_step("relations", step_type="relation_extract")
|
|
832
|
-
builder.add_step("build_kg", step_type="kg_build", merge_entities=True)
|
|
833
|
-
builder.add_step("deduplicate", step_type="deduplicate", threshold=0.75)
|
|
834
|
-
builder.add_step("export", step_type="export", format="turtle", output="kg.ttl")
|
|
835
|
-
|
|
836
|
-
# connect_steps() and set_parallelism() return the builder, so these do chain
|
|
837
|
-
pipeline = (
|
|
838
|
-
builder
|
|
839
|
-
.connect_steps("ingest", "extract")
|
|
840
|
-
.connect_steps("extract", "relations")
|
|
841
|
-
.connect_steps("relations", "build_kg")
|
|
842
|
-
.connect_steps("build_kg", "deduplicate")
|
|
843
|
-
.connect_steps("deduplicate", "export")
|
|
844
|
-
.set_parallelism(4)
|
|
845
|
-
.build(name="contracts_pipeline")
|
|
846
|
-
)
|
|
847
|
-
|
|
848
|
-
engine = ExecutionEngine()
|
|
849
|
-
result = engine.execute_pipeline(pipeline)
|
|
850
|
-
status = engine.get_pipeline_status(pipeline.name)
|
|
851
|
-
progress = engine.get_progress(pipeline.name)
|
|
852
|
-
```
|
|
853
|
-
|
|
854
|
-
</details>
|
|
855
|
-
|
|
856
|
-
<details>
|
|
857
|
-
<summary><b>Temporal Intelligence</b>: Bi-Temporal Graphs & Time Travel</summary>
|
|
858
|
-
<a id="temporal-intelligence-bi-temporal-graphs--time-travel"></a>
|
|
859
|
-
|
|
860
|
-
Track when facts were true *in the world* vs. when they were *recorded*, and query either axis.
|
|
861
|
-
|
|
862
|
-
```python
|
|
863
|
-
from alphasemantichub.context import ContextGraph
|
|
864
|
-
from alphasemantichub.kg import (
|
|
865
|
-
BiTemporalFact,
|
|
866
|
-
TemporalGraphQuery,
|
|
867
|
-
TemporalNormalizer,
|
|
868
|
-
)
|
|
869
|
-
from datetime import datetime
|
|
870
|
-
|
|
871
|
-
graph = ContextGraph(advanced_analytics=True)
|
|
872
|
-
graph.add_node("alice_chen", "Person", role="VP Engineering")
|
|
873
|
-
graph.add_node("acme_corp", "Organization", valuation=1_200_000_000)
|
|
874
|
-
|
|
875
|
-
# A temporally-bounded edge - valid_from/valid_until define when it held true
|
|
876
|
-
graph.add_edge(
|
|
877
|
-
"alice_chen", "acme_corp", edge_type="works_for",
|
|
878
|
-
valid_from="2024-03-01T00:00:00", valid_until="2025-01-01T00:00:00",
|
|
879
|
-
)
|
|
880
|
-
|
|
881
|
-
# Point-in-time snapshots - replay history without reprocessing
|
|
882
|
-
snapshot_2023 = graph.state_at("2023-06-01")
|
|
883
|
-
snapshot_2024 = graph.state_at("2024-01-01")
|
|
884
|
-
|
|
885
|
-
# Bi-temporal facts - valid_time is when true in the world;
|
|
886
|
-
# recorded_at is when you learned about it
|
|
887
|
-
fact = BiTemporalFact(
|
|
888
|
-
valid_from=datetime(2024, 3, 1),
|
|
889
|
-
valid_until=datetime(2025, 1, 1),
|
|
890
|
-
recorded_at=datetime(2024, 3, 5),
|
|
891
|
-
)
|
|
892
|
-
|
|
893
|
-
# Query facts valid within a time window - to_kg_dict() is the official
|
|
894
|
-
# adapter that emits {"entities", "relationships"} with source_id/target_id
|
|
895
|
-
# keys, the shape query_time_range() expects (no manual mapping required)
|
|
896
|
-
kg = graph.to_kg_dict()
|
|
897
|
-
|
|
898
|
-
tq = TemporalGraphQuery()
|
|
899
|
-
facts_in_window = tq.query_time_range(
|
|
900
|
-
kg, query="valid_facts", start_time="2024-01-01", end_time="2024-12-31"
|
|
901
|
-
)
|
|
902
|
-
|
|
903
|
-
# Normalize natural language temporal expressions - returns a (start, end) range
|
|
904
|
-
norm = TemporalNormalizer()
|
|
905
|
-
start, end = norm.normalize("last quarter")
|
|
906
|
-
```
|
|
907
|
-
|
|
908
|
-
</details>
|
|
909
|
-
|
|
910
|
-
<details>
|
|
911
|
-
<summary><b><code>alphasemantichub.export</code></b>: RDF, OWL, Parquet, Cypher, JSON-LD</summary>
|
|
912
|
-
<a id="alphasemantichubexport-rdf-owl-parquet-cypher-json-ld"></a>
|
|
913
|
-
|
|
914
|
-
Export to any format required by regulators, graph databases, or downstream systems.
|
|
915
|
-
|
|
916
|
-
```python
|
|
917
|
-
from alphasemantichub.export import (
|
|
918
|
-
RDFExporter,
|
|
919
|
-
JSONExporter,
|
|
920
|
-
ParquetExporter,
|
|
921
|
-
LPGExporter,
|
|
922
|
-
ReportGenerator,
|
|
923
|
-
)
|
|
924
|
-
|
|
925
|
-
kg = {"entities": [...], "relationships": [...]}
|
|
926
|
-
|
|
927
|
-
rdf = RDFExporter()
|
|
928
|
-
turtle_str = rdf.export_to_rdf(kg, format="turtle") # returns string
|
|
929
|
-
jsonld_str = rdf.export_to_rdf(kg, format="json-ld")
|
|
930
|
-
|
|
931
|
-
rdf.export(kg, "kg_audit.ttl", format="turtle")
|
|
932
|
-
rdf.export(kg, "kg_audit.jsonld", format="json-ld")
|
|
933
|
-
rdf.export(kg, "kg_audit.nt", format="ntriples")
|
|
934
|
-
|
|
935
|
-
# Columnar analytics - Snappy-compressed Parquet (writes kg_snapshot_entities.parquet
|
|
936
|
-
# and kg_snapshot_relationships.parquet)
|
|
937
|
-
ParquetExporter(compression="snappy").export_knowledge_graph(kg, "kg_snapshot")
|
|
938
|
-
|
|
939
|
-
# JSON knowledge graph
|
|
940
|
-
JSONExporter().export_knowledge_graph(kg, "kg.json")
|
|
941
|
-
|
|
942
|
-
# Neo4j / Memgraph Cypher statements for graph database import
|
|
943
|
-
LPGExporter().export(kg, "kg_import.cypher")
|
|
944
|
-
|
|
945
|
-
# Human-readable HTML report
|
|
946
|
-
ReportGenerator().generate_report(
|
|
947
|
-
{"title": "KG Audit Report", "summary": "Weekly ingestion summary", "metrics": {"entities": len(kg["entities"])}},
|
|
948
|
-
file_path="audit_report.html",
|
|
949
|
-
format="html",
|
|
950
|
-
)
|
|
60
|
+
```bash
|
|
61
|
+
alphasemantichub --version
|
|
951
62
|
```
|
|
952
63
|
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
<details>
|
|
956
|
-
<summary><b><code>alphasemantichub.visualization</code></b>: Interactive Graph Workbench</summary>
|
|
957
|
-
<a id="alphasemantichubvisualization-interactive-graph-workbench"></a>
|
|
958
|
-
|
|
959
|
-
Render force-directed graphs, community maps, ontology hierarchies, and temporal dashboards.
|
|
64
|
+
### Optional extras
|
|
960
65
|
|
|
961
|
-
```
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
kg = {"entities": [...], "relationships": [...]}
|
|
971
|
-
|
|
972
|
-
# Interactive force-directed graph (opens in browser)
|
|
973
|
-
viz = KGVisualizer(layout="force", color_scheme="default")
|
|
974
|
-
viz.visualize_network(kg, output="interactive", file_path="kg.html")
|
|
975
|
-
viz.visualize_communities(kg, communities, output="interactive")
|
|
976
|
-
viz.visualize_centrality(kg, centrality, centrality_type="degree")
|
|
977
|
-
viz.visualize_entity_types(kg, output="html", file_path="entity_types.html")
|
|
978
|
-
|
|
979
|
-
# Ontology class hierarchy
|
|
980
|
-
OntologyVisualizer().visualize_hierarchy(ontology, output="interactive")
|
|
981
|
-
|
|
982
|
-
# 2D embedding projection (UMAP / t-SNE / PCA)
|
|
983
|
-
EmbeddingVisualizer().visualize_2d_projection(
|
|
984
|
-
embeddings=np.array([...]),
|
|
985
|
-
labels=["entity_a", "entity_b"],
|
|
986
|
-
method="umap",
|
|
987
|
-
)
|
|
988
|
-
|
|
989
|
-
# Timeline scrubber - watch the graph evolve
|
|
990
|
-
TemporalVisualizer().visualize_timeline(kg, output="interactive")
|
|
66
|
+
```bash
|
|
67
|
+
pip install "alphasemantichub[explorer]" # Studio backend (FastAPI)
|
|
68
|
+
pip install "alphasemantichub[shacl]" # SHACL validation
|
|
69
|
+
pip install "alphasemantichub[parse-docling]" # advanced document parsing
|
|
70
|
+
pip install "alphasemantichub[llm-openai]" # OpenAI LLM provider
|
|
71
|
+
pip install "alphasemantichub[llm-anthropic]" # Anthropic LLM provider
|
|
72
|
+
pip install "alphasemantichub[llm-gemini]" # Google Gemini provider
|
|
73
|
+
pip install "alphasemantichub[all]" # everything
|
|
991
74
|
```
|
|
992
75
|
|
|
993
|
-
|
|
76
|
+
## 2 · Install the npm packages
|
|
994
77
|
|
|
995
|
-
|
|
996
|
-
<summary><b>Multi-Agent Shared Context with Agno</b></summary>
|
|
997
|
-
<a id="multi-agent-shared-context-with-agno"></a>
|
|
78
|
+
Published on npmjs.com under the **`@ltm-blueverse`** scope (user **LTM-ALpha**).
|
|
998
79
|
|
|
999
|
-
|
|
80
|
+
```bash
|
|
81
|
+
# metapackage: harness plugins, skills, agents, hooks
|
|
82
|
+
npm install @ltm-blueverse/alpha-semantic-hub
|
|
1000
83
|
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
from agno.agent import Agent
|
|
1004
|
-
from agno.team import Team
|
|
1005
|
-
from agno.models.anthropic import Claude
|
|
1006
|
-
from alphasemantichub.context import ContextGraph
|
|
1007
|
-
from alphasemantichub.vector_store import VectorStore
|
|
1008
|
-
from integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit
|
|
1009
|
-
|
|
1010
|
-
shared = AgnoSharedContext(
|
|
1011
|
-
vector_store=VectorStore(backend="faiss"),
|
|
1012
|
-
knowledge_graph=ContextGraph(advanced_analytics=True),
|
|
1013
|
-
decision_tracking=True,
|
|
1014
|
-
)
|
|
1015
|
-
|
|
1016
|
-
researcher = Agent(
|
|
1017
|
-
name="Researcher",
|
|
1018
|
-
model=Claude(id="claude-sonnet-4-5"),
|
|
1019
|
-
memory=shared.bind_agent("researcher"),
|
|
1020
|
-
tools=[AgnoKGToolkit(context=shared)],
|
|
1021
|
-
)
|
|
1022
|
-
analyst = Agent(
|
|
1023
|
-
name="Analyst",
|
|
1024
|
-
model=Claude(id="claude-sonnet-4-5"),
|
|
1025
|
-
memory=shared.bind_agent("analyst"),
|
|
1026
|
-
tools=[AgnoDecisionKit(context=shared)],
|
|
1027
|
-
)
|
|
1028
|
-
|
|
1029
|
-
team = Team(agents=[researcher, analyst], mode="coordinate")
|
|
1030
|
-
# Researcher's findings are instantly available to the Analyst - no copy, no sync
|
|
84
|
+
# studio UI as prebuilt static assets (no toolchain needed)
|
|
85
|
+
npm install @ltm-blueverse/alpha-hub-studio
|
|
1031
86
|
```
|
|
1032
87
|
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
</details>
|
|
1036
|
-
|
|
1037
|
-
---
|
|
1038
|
-
|
|
1039
|
-
## More Recipes
|
|
1040
|
-
|
|
1041
|
-
The audit-trail recipe is [above](#recipe-audit-trail-for-a-regulated-decision). Here are three more common patterns.
|
|
1042
|
-
|
|
1043
|
-
<details>
|
|
1044
|
-
<summary><b>End-to-End GraphRAG Pipeline</b></summary>
|
|
1045
|
-
|
|
1046
|
-
```python
|
|
1047
|
-
from alphasemantichub.ingest import FileIngestor
|
|
1048
|
-
from alphasemantichub.split import TextSplitter
|
|
1049
|
-
from alphasemantichub.semantic_extract import NamedEntityRecognizer, RelationExtractor
|
|
1050
|
-
from alphasemantichub.kg import GraphBuilder
|
|
1051
|
-
from alphasemantichub.vector_store import VectorStore, HybridSearch
|
|
1052
|
-
from alphasemantichub.context import AgentContext
|
|
1053
|
-
|
|
1054
|
-
# 1. Ingest
|
|
1055
|
-
docs = FileIngestor().ingest_directory("./docs/", recursive=True)
|
|
1056
|
-
|
|
1057
|
-
# 2. Entity-aware chunking - never splits an entity across a chunk boundary
|
|
1058
|
-
splitter = TextSplitter(method="entity_aware", chunk_size=1000)
|
|
1059
|
-
chunks = [splitter.split(doc.text) for doc in docs]
|
|
1060
|
-
|
|
1061
|
-
# 3. Extract entities and relations
|
|
1062
|
-
ner = NamedEntityRecognizer(confidence_threshold=0.7)
|
|
1063
|
-
rel_ext = RelationExtractor(confidence_threshold=0.6)
|
|
1064
|
-
entities = [ner.extract_entities(chunk.text) for chunk_group in chunks for chunk in chunk_group]
|
|
1065
|
-
|
|
1066
|
-
# 4. Build KG
|
|
1067
|
-
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(docs)
|
|
1068
|
-
|
|
1069
|
-
# 5. Hybrid retrieval
|
|
1070
|
-
vs = VectorStore(backend="inmemory")
|
|
1071
|
-
ctx = AgentContext(vector_store=vs, knowledge_graph=kg)
|
|
1072
|
-
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="c1")
|
|
1073
|
-
|
|
1074
|
-
results = HybridSearch(vector_store=vs).search("who approved the renewal?")
|
|
1075
|
-
```
|
|
88
|
+
## 3 · Run the Studio with Docker (Docker Desktop)
|
|
1076
89
|
|
|
1077
|
-
|
|
90
|
+
The Studio UI + API ships as a Docker image built for Docker Desktop on macOS.
|
|
1078
91
|
|
|
1079
|
-
|
|
1080
|
-
|
|
92
|
+
```bash
|
|
93
|
+
docker pull ltmbios/alpha-hub-studio:latest
|
|
1081
94
|
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
rete = ReteEngine()
|
|
1086
|
-
rete.build_network([
|
|
1087
|
-
Rule(
|
|
1088
|
-
rule_id="sanctions_check",
|
|
1089
|
-
name="Flag sanctioned-country transactions",
|
|
1090
|
-
conditions=[
|
|
1091
|
-
{"field": "amount", "operator": ">", "value": 10_000},
|
|
1092
|
-
{"field": "country", "operator": "in", "value": ["IR", "KP", "SY", "CU"]},
|
|
1093
|
-
],
|
|
1094
|
-
conclusion="flag_for_compliance_review",
|
|
1095
|
-
rule_type=RuleType.IMPLICATION,
|
|
1096
|
-
),
|
|
1097
|
-
])
|
|
1098
|
-
|
|
1099
|
-
# Run the rule across a batch of incoming transactions, not just one
|
|
1100
|
-
for tx in [
|
|
1101
|
-
Fact("tx_101", "transaction", [{"amount": 25_000, "country": "IR"}]),
|
|
1102
|
-
Fact("tx_102", "transaction", [{"amount": 4_500, "country": "DE"}]),
|
|
1103
|
-
Fact("tx_103", "transaction", [{"amount": 60_000, "country": "KP"}]),
|
|
1104
|
-
]:
|
|
1105
|
-
rete.add_fact(tx)
|
|
1106
|
-
|
|
1107
|
-
flagged = rete.match_patterns()
|
|
95
|
+
# or with the bundled FalkorDB graph database:
|
|
96
|
+
docker compose up -d
|
|
1108
97
|
```
|
|
1109
98
|
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
</details>
|
|
99
|
+
`docker-compose.yml` starts:
|
|
1113
100
|
|
|
1114
|
-
|
|
1115
|
-
|
|
101
|
+
- `alpha-hub-studio` — Studio UI + API on **http://localhost:8000**
|
|
102
|
+
- `falkordb` — graph database on port 6379
|
|
1116
103
|
|
|
1117
|
-
|
|
1118
|
-
from alphasemantichub.ingest import FileIngestor
|
|
1119
|
-
from alphasemantichub.semantic_extract import NamedEntityRecognizer, RelationExtractor
|
|
1120
|
-
from alphasemantichub.kg import GraphBuilder
|
|
1121
|
-
from alphasemantichub.ontology import OntologyGenerator, OntologyValidator
|
|
1122
|
-
from alphasemantichub.export import RDFExporter
|
|
1123
|
-
|
|
1124
|
-
sources = FileIngestor().ingest_directory("./contracts/")
|
|
1125
|
-
ner = NamedEntityRecognizer(confidence_threshold=0.7)
|
|
1126
|
-
entities = ner.process_batch([s["text"] for s in sources])
|
|
1127
|
-
|
|
1128
|
-
kg = GraphBuilder(merge_entities=True).build(sources)
|
|
1129
|
-
gen = OntologyGenerator(base_uri="https://myco.dev/ontology/")
|
|
1130
|
-
ont = gen.generate_ontology({"entities": entities[0], "relationships": []})
|
|
1131
|
-
|
|
1132
|
-
report = OntologyValidator().validate(ont)
|
|
1133
|
-
if report.valid:
|
|
1134
|
-
RDFExporter().export({"entities": entities[0]}, "ontology.ttl", format="turtle")
|
|
1135
|
-
```
|
|
104
|
+
Environment variables (all prefixed `ASHUB_`):
|
|
1136
105
|
|
|
1137
|
-
|
|
106
|
+
| Variable | Purpose |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `ASHUB_API_KEY` | API key for protected Studio routes (generate: `openssl rand -hex 32`) |
|
|
109
|
+
| `ASHUB_ALLOW_ANONYMOUS` | `true` bypasses the API key (local-only setups) |
|
|
110
|
+
| `ASHUB_KG_PATH` | Knowledge-graph storage path |
|
|
111
|
+
| `ASHUB_LOG_LEVEL` | Logging verbosity |
|
|
112
|
+
| `ASHUB_CORS_ORIGINS` | Allowed CORS origins |
|
|
1138
113
|
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
## Features at a Glance
|
|
1142
|
-
|
|
1143
|
-
| Capability | Highlights |
|
|
1144
|
-
| --- | --- |
|
|
1145
|
-
| **Context Graphs** | Queryable graph of entities, decisions, relationships; causal links; cross-graph navigation |
|
|
1146
|
-
| **Decision Intelligence** | `record_decision` · `trace_decision_chain` · `find_similar_decisions` · `analyze_decision_impact` · `check_decision_rules` |
|
|
1147
|
-
| **Temporal Intelligence** | Point-in-time snapshots · Allen interval algebra (13 relations) · `TemporalNormalizer` · bi-temporal provenance |
|
|
1148
|
-
| **Distance Intelligence** | N×N semantic distance matrices · ego-mode visualization · distance bands · embedding cache |
|
|
1149
|
-
| **Semantic Extraction** | NER · relation extraction · event detection · triplet generation · coreference |
|
|
1150
|
-
| **Reasoning Engines** | Forward chaining · Rete · deductive · abductive · SPARQL · Datalog with explainable output |
|
|
1151
|
-
| **GraphRAG Chunking** | Entity-aware · relation-aware · graph-based · ontology-aware · community-detection chunking |
|
|
1152
|
-
| **Conflict Detection** | Value / type / relationship / temporal / logical conflicts · multiple resolution strategies |
|
|
1153
|
-
| **Provenance** | W3C PROV-O · every fact traced to source · audit log export JSON/CSV/RDF |
|
|
1154
|
-
| **Ontology Hub** | SHACL Studio · visual editor · cross-ontology alignments · health dashboard |
|
|
1155
|
-
| **Vector Store** | FAISS · Pinecone · Weaviate · Qdrant · Milvus · PgVector · hybrid + filtered search |
|
|
1156
|
-
| **Graph Databases (LPG)** | Neo4j · FalkorDB · Apache AGE · AWS Neptune |
|
|
1157
|
-
| **Triple Stores (RDF)** | Oxigraph (embedded) · Blazegraph · Apache Jena · Eclipse RDF4J · unified `TripletStore` interface · SPARQL query & bulk load |
|
|
1158
|
-
| **Enterprise Data Platforms** | Databricks (`DatabricksIngestor`: Unity Catalog + Delta Lake, PAT/OAuth M2M, table/query ingestion, catalog/schema/table/lineage introspection) · Snowflake (`SnowflakeIngestor`: warehouse/database/schema, password/key-pair/OAuth auth) · SAP (`SAPIngestor`: OData v2/v4, OAuth2/Basic auth, Business Partners/Sales Orders) |
|
|
1159
|
-
| **LLM Providers** | **All already supported today:** OpenAI (GPT-4o, o1, o3) · Anthropic (Claude) · Google Gemini · Mistral · Meta Llama · Groq · Cohere · Azure OpenAI · AWS Bedrock · Ollama · DeepSeek · Perplexity · Together AI · Fireworks AI · Replicate · HuggingFace · via `alphasemantichub.llms` and LiteLLM |
|
|
1160
|
-
|
|
1161
|
-
---
|
|
114
|
+
Then open **http://localhost:8000** — the red-themed futuristic Studio.
|
|
1162
115
|
|
|
1163
|
-
##
|
|
116
|
+
## 4 · Harness integrations (AI coding agents)
|
|
1164
117
|
|
|
1165
|
-
|
|
118
|
+
The repo ships ready-to-install plugins under `plugins/`. Install the npm metapackage
|
|
119
|
+
(`npm install @ltm-blueverse/alpha-semantic-hub`) or point your tool at the checked-out
|
|
120
|
+
`plugins/` directory.
|
|
1166
121
|
|
|
1167
|
-
|
|
1168
|
-
| --- | --- | --- | --- |
|
|
1169
|
-
| Node search (118k nodes) | 24 ms | 0.004 ms | **6,000×** faster |
|
|
1170
|
-
| Embedding cache hit | cold load | revision-based cache | **10×** throughput |
|
|
1171
|
-
| Semantic deduplication | baseline | optimized candidate gen | **6.98×** faster |
|
|
1172
|
-
| Candidate generation | baseline | blocking strategy | **63.6%** faster |
|
|
122
|
+
### How the harness integration works
|
|
1173
123
|
|
|
1174
|
-
|
|
124
|
+
Every integration follows the same shape:
|
|
1175
125
|
|
|
1176
|
-
|
|
126
|
+
1. The harness (Claude Code, Copilot, Codex, …) launches the **MCP server as a
|
|
127
|
+
child process** (`python -m alphasemantichub.mcp_server`, stdio transport)
|
|
128
|
+
2. The plugin manifest tells the harness which **skills** (markdown playbooks in
|
|
129
|
+
`plugins/skills/`) and **agents** (persona definitions in `plugins/agents/`)
|
|
130
|
+
to load alongside its native tools
|
|
131
|
+
3. The agent can then call knowledge-graph tools (`extract_entities`,
|
|
132
|
+
`record_decision`, `find_precedents`, `query_graph`, …) directly from its
|
|
133
|
+
chat/tool loop — reading from and writing to the same graph the Studio shows
|
|
134
|
+
4. Optional **hooks** (`plugins/hooks/hooks.json`) run small guards on
|
|
135
|
+
Write/Edit/Bash events (e.g. Python syntax checks on graph files)
|
|
1177
136
|
|
|
1178
|
-
|
|
137
|
+
Because the transport is stdio JSON-RPC, there is no server to manage: install
|
|
138
|
+
the Python package in the interpreter the harness uses, register the command,
|
|
139
|
+
and the tools appear.
|
|
1179
140
|
|
|
1180
|
-
|
|
141
|
+
### Claude (Claude Code / Claude Desktop)
|
|
1181
142
|
|
|
1182
143
|
```bash
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
144
|
+
# from a checkout of this repo
|
|
145
|
+
claude plugin add ./plugins/.claude-plugin
|
|
146
|
+
# or from the npm package
|
|
147
|
+
claude plugin add "$(npm root -g)/@ltm-blueverse/alpha-semantic-hub/plugins/.claude-plugin"
|
|
1187
148
|
```
|
|
1188
149
|
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
**Command groups:** `ingest` · `parse` · `extract` · `kg` · `reason` · `decision` · `temporal` · `provenance` · `ontology` · `embed` · `deduplicate` · `validate` · `export` · `visualize` · `pipeline` · `server` · `explorer` · `mcp` · `doctor` · `shell` · `init` · `watch`
|
|
150
|
+
Includes skills (`plugins/skills/`), agents (KG assistant, decision advisor,
|
|
151
|
+
explainability), and hooks.
|
|
1192
152
|
|
|
1193
|
-
|
|
153
|
+
### VS Code / GitHub Copilot
|
|
1194
154
|
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
## Integrations
|
|
1198
|
-
|
|
1199
|
-
Native plugin bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, OpenClaw, and pi; a full-featured MCP server for any MCP-compatible client; a comprehensive REST API; and first-class Agno, CrewAI, and LangChain support for agentic frameworks. Every major LLM provider is already supported via `alphasemantichub.llms` and LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.
|
|
1200
|
-
|
|
1201
|
-
MCP setup takes 30 seconds — see [MCP Server](#mcp-server) below.
|
|
1202
|
-
|
|
1203
|
-
<details>
|
|
1204
|
-
<summary><b>Full integrations matrix</b> (editors, MCP clients, REST clients, agentic frameworks)</summary>
|
|
1205
|
-
|
|
1206
|
-
<table>
|
|
1207
|
-
<tr>
|
|
1208
|
-
<th colspan="4" align="left">Native Plugin Bundle</th>
|
|
1209
|
-
<th colspan="5" align="left">MCP Server + Plugin</th>
|
|
1210
|
-
</tr>
|
|
1211
|
-
<tr>
|
|
1212
|
-
<td align="center" width="11.1%">
|
|
1213
|
-
<a href="https://claude.com/product/claude-code"><img src="https://github.com/anthropics.png?size=120" alt="Claude Code" width="48" height="48" /></a><br/>
|
|
1214
|
-
<strong>Claude Code</strong><br/>
|
|
1215
|
-
<sub>Skills · agents · hooks</sub>
|
|
1216
|
-
</td>
|
|
1217
|
-
<td align="center" width="11.1%">
|
|
1218
|
-
<a href="https://cursor.com"><img src="https://www.freelogovectors.net/wp-content/uploads/2025/06/cursor-logo-freelogovectors.net_.png" alt="Cursor" width="48" height="48" /></a><br/>
|
|
1219
|
-
<strong>Cursor</strong><br/>
|
|
1220
|
-
<sub>Skills · agents</sub>
|
|
1221
|
-
</td>
|
|
1222
|
-
<td align="center" width="11.1%">
|
|
1223
|
-
<a href="https://github.com/openai/codex"><img src="https://github.com/openai.png?size=120" alt="Codex CLI" width="48" height="48" /></a><br/>
|
|
1224
|
-
<strong>Codex CLI</strong><br/>
|
|
1225
|
-
<sub>Skills · agents</sub>
|
|
1226
|
-
</td>
|
|
1227
|
-
<td align="center" width="11.1%">
|
|
1228
|
-
<a href="https://pi.dev"><img src="https://github.com/earendil-works.png?size=120" alt="pi" width="48" height="48" /></a><br/>
|
|
1229
|
-
<strong>pi</strong><br/>
|
|
1230
|
-
<sub>Skills · <a href="plugins/.pi-plugin/">plugin</a></sub>
|
|
1231
|
-
</td>
|
|
1232
|
-
<td align="center" width="11.1%">
|
|
1233
|
-
<a href="https://windsurf.com"><img src="https://exafunction.github.io/public/brand/windsurf-black-symbol.svg" alt="Windsurf" width="48" height="48" /></a><br/>
|
|
1234
|
-
<strong>Windsurf</strong><br/>
|
|
1235
|
-
<sub><a href="plugins/.windsurf-plugin/">plugin</a></sub>
|
|
1236
|
-
</td>
|
|
1237
|
-
<td align="center" width="11.1%">
|
|
1238
|
-
<a href="https://github.com/cline/cline"><img src="https://github.com/cline.png?size=120" alt="Cline" width="48" height="48" /></a><br/>
|
|
1239
|
-
<strong>Cline</strong><br/>
|
|
1240
|
-
<sub><a href="plugins/.cline-plugin/">plugin</a></sub>
|
|
1241
|
-
</td>
|
|
1242
|
-
<td align="center" width="11.1%">
|
|
1243
|
-
<a href="https://github.com/continuedev/continue"><img src="https://github.com/continuedev.png?size=120" alt="Continue" width="48" height="48" /></a><br/>
|
|
1244
|
-
<strong>Continue</strong><br/>
|
|
1245
|
-
<sub><a href="plugins/.continue-plugin/">plugin</a></sub>
|
|
1246
|
-
</td>
|
|
1247
|
-
<td align="center" width="11.1%">
|
|
1248
|
-
<a href="https://github.com/microsoft/vscode"><img src="https://github.com/microsoft.png?size=120" alt="VS Code" width="48" height="48" /></a><br/>
|
|
1249
|
-
<strong>VS Code</strong><br/>
|
|
1250
|
-
<sub><a href="plugins/.vscode-plugin/">plugin</a></sub>
|
|
1251
|
-
</td>
|
|
1252
|
-
<td align="center" width="11.1%">
|
|
1253
|
-
<a href="integrations/openclaw/"><img src="https://github.com/openclaw.png?size=120" alt="OpenClaw" width="48" height="48" /></a><br/>
|
|
1254
|
-
<strong>OpenClaw</strong><br/>
|
|
1255
|
-
<sub>MCP + <a href="integrations/openclaw/">plugin</a></sub>
|
|
1256
|
-
</td>
|
|
1257
|
-
</tr>
|
|
1258
|
-
<tr>
|
|
1259
|
-
<th colspan="1" align="left">MCP Server</th>
|
|
1260
|
-
<th colspan="7" align="left">REST API</th>
|
|
1261
|
-
</tr>
|
|
1262
|
-
<tr>
|
|
1263
|
-
<td align="center" width="12.5%">
|
|
1264
|
-
<a href="https://claude.ai/download"><img src="https://github.com/anthropics.png?size=120" alt="Claude Desktop" width="48" height="48" /></a><br/>
|
|
1265
|
-
<strong>Claude Desktop</strong><br/>
|
|
1266
|
-
<sub>MCP server</sub>
|
|
1267
|
-
</td>
|
|
1268
|
-
<td align="center" width="12.5%">
|
|
1269
|
-
<a href="https://github.com/features/copilot"><img src="https://github.com/github.png?size=120" alt="GitHub Copilot" width="48" height="48" /></a><br/>
|
|
1270
|
-
<strong>GitHub Copilot</strong><br/>
|
|
1271
|
-
<sub>REST API</sub>
|
|
1272
|
-
</td>
|
|
1273
|
-
<td align="center" width="12.5%">
|
|
1274
|
-
<a href="https://github.com/RooCodeInc/Roo-Code"><img src="https://github.com/RooCodeInc.png?size=120" alt="Roo Code" width="48" height="48" /></a><br/>
|
|
1275
|
-
<strong>Roo Code</strong><br/>
|
|
1276
|
-
<sub>REST API</sub>
|
|
1277
|
-
</td>
|
|
1278
|
-
<td align="center" width="12.5%">
|
|
1279
|
-
<a href="https://github.com/block/goose"><img src="https://github.com/block.png?size=120" alt="Goose" width="48" height="48" /></a><br/>
|
|
1280
|
-
<strong>Goose</strong><br/>
|
|
1281
|
-
<sub>REST API</sub>
|
|
1282
|
-
</td>
|
|
1283
|
-
<td align="center" width="12.5%">
|
|
1284
|
-
<a href="https://github.com/Kilo-Org/kilocode"><img src="https://github.com/Kilo-Org.png?size=120" alt="Kilo Code" width="48" height="48" /></a><br/>
|
|
1285
|
-
<strong>Kilo Code</strong><br/>
|
|
1286
|
-
<sub>REST API</sub>
|
|
1287
|
-
</td>
|
|
1288
|
-
<td align="center" width="12.5%">
|
|
1289
|
-
<a href="https://github.com/Aider-AI/aider"><img src="https://github.com/Aider-AI.png?size=120" alt="Aider" width="48" height="48" /></a><br/>
|
|
1290
|
-
<strong>Aider</strong><br/>
|
|
1291
|
-
<sub>REST API</sub>
|
|
1292
|
-
</td>
|
|
1293
|
-
<td align="center" width="12.5%">
|
|
1294
|
-
<a href="https://github.com/aws/amazon-q-developer-cli"><img src="https://github.com/aws.png?size=120" alt="Amazon Q" width="48" height="48" /></a><br/>
|
|
1295
|
-
<strong>Amazon Q</strong><br/>
|
|
1296
|
-
<sub>REST API</sub>
|
|
1297
|
-
</td>
|
|
1298
|
-
<td align="center" width="12.5%">
|
|
1299
|
-
<a href="https://zed.dev"><img src="https://github.com/zed-industries.png?size=120" alt="Zed" width="48" height="48" /></a><br/>
|
|
1300
|
-
<strong>Zed</strong><br/>
|
|
1301
|
-
<sub>REST API</sub>
|
|
1302
|
-
</td>
|
|
1303
|
-
</tr>
|
|
1304
|
-
</table>
|
|
1305
|
-
|
|
1306
|
-
### Agentic Frameworks
|
|
1307
|
-
|
|
1308
|
-
<table>
|
|
1309
|
-
<tr>
|
|
1310
|
-
<th colspan="8" align="left">Native Integration</th>
|
|
1311
|
-
</tr>
|
|
1312
|
-
<tr>
|
|
1313
|
-
<td align="center" width="12.5%">
|
|
1314
|
-
<a href="https://github.com/agno-agi/agno"><img src="https://github.com/agno-agi.png?size=120" alt="Agno" width="48" height="48" /></a><br/>
|
|
1315
|
-
<strong>Agno</strong><br/>
|
|
1316
|
-
<sub>First-class · <code>pip install alphasemantichub[agno]</code></sub>
|
|
1317
|
-
</td>
|
|
1318
|
-
<td align="center" width="12.5%">
|
|
1319
|
-
<a href="https://github.com/crewAIInc/crewAI"><img src="https://github.com/crewAIInc.png?size=120" alt="CrewAI" width="48" height="48" /></a><br/>
|
|
1320
|
-
<strong>CrewAI</strong><br/>
|
|
1321
|
-
<sub>First-class · <code>pip install "crewai>=0.80.0"</code> alongside alphasemantichub</sub>
|
|
1322
|
-
</td>
|
|
1323
|
-
<td align="center" width="12.5%">
|
|
1324
|
-
<a href="https://github.com/langchain-ai/langchain"><img src="https://github.com/langchain-ai.png?size=120" alt="LangChain" width="48" height="48" /></a><br/>
|
|
1325
|
-
<strong>LangChain</strong><br/>
|
|
1326
|
-
<sub>First-class · <code>pip install alphasemantichub[langchain]</code></sub>
|
|
1327
|
-
</td>
|
|
1328
|
-
</tr>
|
|
1329
|
-
<tr>
|
|
1330
|
-
<th colspan="8" align="left">Already Supported via REST API & MCP</th>
|
|
1331
|
-
</tr>
|
|
1332
|
-
<tr>
|
|
1333
|
-
<td align="center" width="12.5%">
|
|
1334
|
-
<a href="https://github.com/langchain-ai/langgraph"><img src="https://github.com/langchain-ai.png?size=120" alt="LangGraph" width="48" height="48" /></a><br/>
|
|
1335
|
-
<strong>LangGraph</strong><br/>
|
|
1336
|
-
<sub>REST API · MCP</sub>
|
|
1337
|
-
</td>
|
|
1338
|
-
<td align="center" width="12.5%">
|
|
1339
|
-
<a href="https://github.com/run-llama/llama_index"><img src="https://github.com/run-llama.png?size=120" alt="LlamaIndex" width="48" height="48" /></a><br/>
|
|
1340
|
-
<strong>LlamaIndex</strong><br/>
|
|
1341
|
-
<sub>REST API · MCP</sub>
|
|
1342
|
-
</td>
|
|
1343
|
-
<td align="center" width="12.5%">
|
|
1344
|
-
<a href="https://github.com/microsoft/autogen"><img src="https://github.com/microsoft.png?size=120" alt="AutoGen" width="48" height="48" /></a><br/>
|
|
1345
|
-
<strong>AutoGen</strong><br/>
|
|
1346
|
-
<sub>REST API · MCP</sub>
|
|
1347
|
-
</td>
|
|
1348
|
-
<td align="center" width="12.5%">
|
|
1349
|
-
<a href="https://github.com/openai/openai-agents-python"><img src="https://github.com/openai.png?size=120" alt="OpenAI Agents SDK" width="48" height="48" /></a><br/>
|
|
1350
|
-
<strong>OpenAI Agents</strong><br/>
|
|
1351
|
-
<sub>REST API · MCP</sub>
|
|
1352
|
-
</td>
|
|
1353
|
-
<td align="center" width="12.5%">
|
|
1354
|
-
<a href="https://github.com/google/adk-python"><img src="https://github.com/google.png?size=120" alt="Google ADK" width="48" height="48" /></a><br/>
|
|
1355
|
-
<strong>Google ADK</strong><br/>
|
|
1356
|
-
<sub>REST API · MCP</sub>
|
|
1357
|
-
</td>
|
|
1358
|
-
</tr>
|
|
1359
|
-
<tr>
|
|
1360
|
-
<th colspan="8" align="left">Native SDK Integration (Coming Soon)</th>
|
|
1361
|
-
</tr>
|
|
1362
|
-
<tr>
|
|
1363
|
-
<td align="center" width="12.5%">
|
|
1364
|
-
<a href="https://github.com/run-llama/llama_index"><img src="https://github.com/run-llama.png?size=120" alt="LlamaIndex" width="48" height="48" /></a><br/>
|
|
1365
|
-
<strong>LlamaIndex</strong><br/>
|
|
1366
|
-
<sub>Dedicated toolkit</sub>
|
|
1367
|
-
</td>
|
|
1368
|
-
<td align="center" width="12.5%">
|
|
1369
|
-
<a href="https://github.com/microsoft/autogen"><img src="https://github.com/microsoft.png?size=120" alt="AutoGen" width="48" height="48" /></a><br/>
|
|
1370
|
-
<strong>AutoGen</strong><br/>
|
|
1371
|
-
<sub>Dedicated toolkit</sub>
|
|
1372
|
-
</td>
|
|
1373
|
-
<td align="center" width="12.5%">
|
|
1374
|
-
<a href="https://github.com/openai/openai-agents-python"><img src="https://github.com/openai.png?size=120" alt="OpenAI Agents SDK" width="48" height="48" /></a><br/>
|
|
1375
|
-
<strong>OpenAI Agents</strong><br/>
|
|
1376
|
-
<sub>Dedicated toolkit</sub>
|
|
1377
|
-
</td>
|
|
1378
|
-
<td align="center" width="12.5%">
|
|
1379
|
-
<a href="https://github.com/google/adk-python"><img src="https://github.com/google.png?size=120" alt="Google ADK" width="48" height="48" /></a><br/>
|
|
1380
|
-
<strong>Google ADK</strong><br/>
|
|
1381
|
-
<sub>Dedicated toolkit</sub>
|
|
1382
|
-
</td>
|
|
1383
|
-
</tr>
|
|
1384
|
-
</table>
|
|
1385
|
-
|
|
1386
|
-
</details>
|
|
1387
|
-
|
|
1388
|
-
### MCP Server
|
|
1389
|
-
|
|
1390
|
-
Connect any MCP-compatible client (Claude Desktop, Windsurf, Cline, VS Code) in 30 seconds:
|
|
1391
|
-
|
|
1392
|
-
```bash
|
|
1393
|
-
python -m alphasemantichub.mcp_server
|
|
1394
|
-
# or via the installed entry point
|
|
1395
|
-
alphasemantichub-mcp
|
|
1396
|
-
```
|
|
155
|
+
Install the `.vscode-plugin` manifest, or configure the MCP server in VS Code
|
|
156
|
+
`settings.json`:
|
|
1397
157
|
|
|
1398
158
|
```json
|
|
1399
159
|
{
|
|
1400
|
-
"
|
|
1401
|
-
"
|
|
160
|
+
"mcp": {
|
|
161
|
+
"servers": {
|
|
162
|
+
"alpha-semantic-hub": {
|
|
163
|
+
"command": "python",
|
|
164
|
+
"args": ["-m", "alphasemantichub.mcp_server"],
|
|
165
|
+
"transport": "stdio"
|
|
166
|
+
}
|
|
167
|
+
}
|
|
1402
168
|
}
|
|
1403
169
|
}
|
|
1404
170
|
```
|
|
1405
171
|
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
| Tool | What it does |
|
|
1409
|
-
| --- | --- |
|
|
1410
|
-
| `extract_entities` | NER on any text |
|
|
1411
|
-
| `extract_relations` | Relation extraction |
|
|
1412
|
-
| `record_decision` | Persist a decision node |
|
|
1413
|
-
| `query_decisions` | Search decision history |
|
|
1414
|
-
| `find_precedents` | Semantic precedent lookup |
|
|
1415
|
-
| `get_causal_chain` | Full causal ancestry |
|
|
1416
|
-
| `add_entity` | Add a KG node |
|
|
1417
|
-
| `add_relationship` | Add a KG edge |
|
|
1418
|
-
| `run_reasoning` | Execute rule set |
|
|
1419
|
-
| `get_graph_analytics` | Centrality, communities |
|
|
1420
|
-
| `export_graph` | Export to RDF/JSON/Parquet |
|
|
1421
|
-
| `get_graph_summary` | Graph statistics |
|
|
1422
|
-
| `query_graph` | Fetch a node, walk neighbours, keyword search |
|
|
1423
|
-
| `update_node` | Merge properties onto a node |
|
|
1424
|
-
| `delete_node` | Archive (soft-delete) a node |
|
|
1425
|
-
|
|
1426
|
-
### REST API
|
|
172
|
+
### Codex (OpenAI)
|
|
1427
173
|
|
|
1428
174
|
```bash
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
# Extract entities & relations via REST
|
|
1433
|
-
curl -X POST http://localhost:8000/api/enrich/extract \
|
|
1434
|
-
-H "Content-Type: application/json" \
|
|
1435
|
-
-d '{"text": "Apple CEO Tim Cook announced record earnings."}'
|
|
175
|
+
codex plugin add ./plugins/.codex-plugin
|
|
176
|
+
```
|
|
1436
177
|
|
|
1437
|
-
|
|
1438
|
-
curl "http://localhost:8000/api/decisions?category=vendor_selection"
|
|
178
|
+
### Cursor
|
|
1439
179
|
|
|
1440
|
-
|
|
1441
|
-
|
|
180
|
+
```bash
|
|
181
|
+
# add the plugin directory in Cursor settings → MCP, or:
|
|
182
|
+
cursor install ./plugins/.cursor-plugin
|
|
1442
183
|
```
|
|
1443
184
|
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
### Plugin Bundles
|
|
185
|
+
### Continue.dev
|
|
1447
186
|
|
|
1448
|
-
|
|
187
|
+
Copy `plugins/.continue-plugin` into your Continue config and register the MCP
|
|
188
|
+
server command above.
|
|
1449
189
|
|
|
1450
|
-
|
|
190
|
+
### Windsurf / Cline / OpenClaw
|
|
1451
191
|
|
|
1452
|
-
|
|
192
|
+
Each has a ready manifest: `plugins/.windsurf-plugin`, `plugins/.cline-plugin`,
|
|
193
|
+
`plugins/.openclaw-plugin` — all pointing at the same MCP server.
|
|
1453
194
|
|
|
1454
195
|
---
|
|
1455
196
|
|
|
1456
|
-
##
|
|
1457
|
-
|
|
1458
|
-
|
|
1459
|
-
|
|
1460
|
-
|
|
1461
|
-
|
|
1462
|
-
|
|
1463
|
-
|
|
1464
|
-
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
197
|
+
## 5 · The Studio UI
|
|
198
|
+
|
|
199
|
+
The bundled Knowledge Explorer ships in the Alpha red brand system with a light,
|
|
200
|
+
readable theme:
|
|
201
|
+
|
|
202
|
+
- **White background with near-black text** and light red highlights/captions
|
|
203
|
+
- **Alpha red** accent system (`#E11D2E` → `#FF4B55` gradients), sharp futuristic geometry
|
|
204
|
+
- Red **A-in-circle** brand mark in the navigation rail, favicon and app icons
|
|
205
|
+
- All workspaces (Graph, Analyze, Decisions, Enrich, Manage, Ontology Hub) restyled
|
|
206
|
+
|
|
207
|
+
Serve it three ways:
|
|
208
|
+
|
|
209
|
+
1. **Python (recommended):** `pip install "alphasemantichub[explorer]"` then `alphasemantichub-explorer` → http://localhost:8000
|
|
210
|
+
2. **Docker:** `docker compose up -d` → http://localhost:8000
|
|
211
|
+
3. **Static:** grab `@ltm-blueverse/alpha-hub-studio` from npm and serve `static/`
|
|
212
|
+
|
|
213
|
+
## 6 · How the MCP server works
|
|
214
|
+
|
|
215
|
+
Alpha Semantic Hub exposes its knowledge graph to AI agents over the
|
|
216
|
+
**Model Context Protocol (MCP)**. The server speaks JSON-RPC 2.0 over **stdio** —
|
|
217
|
+
an agent harness launches it as a child process and exchanges newline-delimited
|
|
218
|
+
JSON-RPC messages (`initialize`, `tools/list`, `tools/call`, `resources/list`,
|
|
219
|
+
`resources/read`). No network port is opened, so it works identically in Claude
|
|
220
|
+
Code, VS Code, Codex, Cursor, or any MCP-capable client.
|
|
221
|
+
|
|
222
|
+
Two builds are included:
|
|
223
|
+
|
|
224
|
+
| Server | Launch | Tools |
|
|
225
|
+
|---|---|---|
|
|
226
|
+
| **Installed server** (`alphasemantichub.mcp_server`) | `alphasemantichub-mcp` or `python -m alphasemantichub.mcp_server` | 16 tools |
|
|
227
|
+
| **Extended in-repo server** (`alphasemantichub_mcp.mcp`) | `python -m alphasemantichub_mcp.mcp` | 22 tools (adds retrieval, provenance, impact analysis) |
|
|
228
|
+
|
|
229
|
+
What the tools cover:
|
|
230
|
+
|
|
231
|
+
- **Extraction** — `extract_entities` (NER over text), `extract_relations`
|
|
232
|
+
(relations + subject-predicate-object triplets)
|
|
233
|
+
- **Decision intelligence** — `record_decision`, `query_decisions`,
|
|
234
|
+
`find_precedents` (similarity search over past decisions), `get_causal_chain`
|
|
235
|
+
(trace what a decision influenced, upstream or downstream), `link_decisions`
|
|
236
|
+
(typed causal edges: CAUSED / INFLUENCED / PRECEDENT_FOR), `analyze_decision_impact`
|
|
237
|
+
- **Graph** — `add_entity`, `add_relationship`, `query_graph` (node lookup,
|
|
238
|
+
1–5-hop neighborhoods, keyword search), `get_graph_analytics` (PageRank,
|
|
239
|
+
community detection), `get_graph_summary`
|
|
240
|
+
- **Reasoning** — `run_reasoning` (forward-chaining IF/THEN rules over facts),
|
|
241
|
+
`abductive_reasoning` (hypotheses that explain observed facts)
|
|
242
|
+
- **Persistence & I/O** — `export_graph` (Turtle, JSON-LD, RDF/XML, GraphML,
|
|
243
|
+
CSV, Parquet, N-Triples), `update_node`, `delete_node` (soft archive)
|
|
244
|
+
- **Retrieval (extended server)** — `store_document` (chunk + embed),
|
|
245
|
+
`retrieve_context` (semantic search + related graph relationships)
|
|
246
|
+
|
|
247
|
+
State: point `ASHUB_KG_PATH` at a graph file and every mutation (decisions,
|
|
248
|
+
entities, relationships) is persisted and reloaded across sessions — the graph
|
|
249
|
+
your agent edits is the graph the Studio renders.
|
|
250
|
+
|
|
251
|
+
## 7 · How the ontology is built
|
|
252
|
+
|
|
253
|
+
Ontologies are produced by `OntologyEngine`, which composes a six-stage
|
|
254
|
+
generator pipeline:
|
|
255
|
+
|
|
256
|
+
1. **Parse** — normalize `{"entities": [...], "relationships": [...]}` produced
|
|
257
|
+
by the semantic-extraction pipeline (`NERExtractor`, `RelationExtractor`,
|
|
258
|
+
`TripletExtractor`)
|
|
259
|
+
2. **Define** — map concepts to candidate class definitions
|
|
260
|
+
3. **Type & property inference** — `PropertyGenerator.infer_properties` stamps
|
|
261
|
+
classes/properties with URIs from `NamespaceManager`
|
|
262
|
+
(base namespace `https://alphahub.ltmb.io/ontology/`)
|
|
263
|
+
4. **Hierarchy** — `ClassInferrer.build_class_hierarchy` assembles the class
|
|
264
|
+
tree (frequency-gated: concepts need `min_occurrences=2` to survive)
|
|
265
|
+
5. **Serialize** — `OWLGenerator` emits Turtle / RDF-XML / JSON-LD / N3
|
|
266
|
+
6. **Validate** — `OntologyValidator` checks consistency and satisfiability;
|
|
267
|
+
results land in `ontology["validation"]`
|
|
268
|
+
|
|
269
|
+
Then:
|
|
270
|
+
|
|
271
|
+
- **SHACL shapes** are derived with `OntologyEngine.to_shacl(...)` (quality
|
|
272
|
+
tiers basic/standard/strict) and enforced at runtime with
|
|
273
|
+
`validate_graph(...)` (pyshacl) — reports come back as plain-English
|
|
274
|
+
violations
|
|
275
|
+
- **Quality gate** — `quality_check(...)` returns a graded report of issues
|
|
276
|
+
- **Versioning** — `VersionManager.create_version` gives each ontology a
|
|
277
|
+
versioned IRI, and `compare_versions` / `diff_ontologies` produce change
|
|
278
|
+
reports between versions
|
|
279
|
+
- **LLM-assisted drafting** — `OntologyEngine.from_text(...)` drafts an ontology
|
|
280
|
+
from unstructured text; the result goes through the same validation and
|
|
281
|
+
versioning
|
|
282
|
+
|
|
283
|
+
Resulting dict shape:
|
|
1482
284
|
|
|
1483
285
|
```python
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
286
|
+
{
|
|
287
|
+
"uri": "https://alphahub.ltmb.io/ontology/v1.0/",
|
|
288
|
+
"name": "...", "version": "1.0",
|
|
289
|
+
"classes": [{"name", "uri", "label", "comment", "properties", "entity_count"}],
|
|
290
|
+
"properties": [...],
|
|
291
|
+
"validation": {"valid": true, "consistent": true, "satisfiable": true, ...}
|
|
292
|
+
}
|
|
1491
293
|
```
|
|
1492
294
|
|
|
1493
|
-
|
|
1494
|
-
updates the supplied runtime object; it does not add disk persistence.
|
|
295
|
+
## 8 · Connecting source systems
|
|
1495
296
|
|
|
1496
|
-
|
|
297
|
+
The `ingest` layer feeds the ontology and knowledge graph from external systems.
|
|
298
|
+
Every connector is lazy-loaded and degrades to a helpful install hint when its
|
|
299
|
+
SDK is missing. Two patterns:
|
|
1497
300
|
|
|
1498
|
-
|
|
301
|
+
- a **Connector** (auth + transport) paired with an **Ingestor** (extraction +
|
|
302
|
+
`export_as_documents`)
|
|
303
|
+
- a unified dispatcher: `ingest(sources, source_type="db", method=...)`
|
|
1499
304
|
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
305
|
+
| Source system | Ingestor | Connection | Primary call |
|
|
306
|
+
|---|---|---|---|
|
|
307
|
+
| **Databricks** | `DatabricksIngestor` | `host`, `token`, `http_path`, `catalog`, `schema` (env: `DATABRICKS_HOST`, `DATABRICKS_TOKEN`, `DATABRICKS_HTTP_PATH`) | `ingest_table("silver_customers")`, `ingest_query("SELECT ...")` |
|
|
308
|
+
| **SAP** (OData) | `SAPIngestor` | `base_url`, `auth="oauth2"|"basic"`, `token_url`, `client_id`, `client_secret` | `discover_service()`, `ingest_entity_set(service, entity_set, top=1000)` |
|
|
309
|
+
| **Snowflake** | `SnowflakeIngestor` | `account`, `user`, `password`/`private_key`, `warehouse`, `database`, `schema`, `role` | `ingest_table(...)`, `ingest_query(...)` |
|
|
310
|
+
| **Salesforce** | `SalesforceIngestor` | `username`, `password`, `security_token` (env: `SALESFORCE_USERNAME`, …) | `ingest_sobject("Account", fields=[...])`, `ingest_query(soql)` |
|
|
311
|
+
| **ServiceNow** | `ServiceNowIngestor` | `instance_url`, `auth`, `username`/`client_id` + secret | `ingest_table(table="incident", query=..., limit=...)` |
|
|
312
|
+
| **Power BI** | `PowerBIIngestor` | `tenant_id`, `client_id`, `client_secret`, `workspace_id` | `ingest_workspace_metadata()` |
|
|
313
|
+
| **Tableau** | `TableauIngestor` | `server_url`, `site_name`, `token_name`, `token_value` | `ingest_workbooks()`, `ingest_datasources()` |
|
|
314
|
+
| **Looker** | `LookerIngestor` | `base_url`, `client_id`, `client_secret` (or `looker.ini`) | `ingest_looks()`, `ingest_dashboards()`, `ingest_lookml_models()` |
|
|
315
|
+
| **BigQuery** | `BigQueryIngestor` | `project`, `dataset`, `credentials_file` | `ingest_table(...)`, `ingest_query(...)` |
|
|
316
|
+
| **Web / intranet** | `WebIngestor` | `user_agent`, `respect_robots=True` | `ingest_url(url)`, `crawl_sitemap(...)`, `crawl_domain(...)` |
|
|
317
|
+
| **Files & cloud storage** | `FileIngestor`, `CloudStorageIngestor` | provider config for S3 / GCS / Azure Blob | `ingest_file`, `ingest_directory`, `ingest_cloud` |
|
|
318
|
+
| **Git repositories** | `RepoIngestor` | repo URL | `ingest_repository(url)` + commit/code analysis |
|
|
319
|
+
| **REST APIs** | `RESTIngestor` | `config={"headers": {...}}` | `ingest_endpoint(...)`, `paginated_fetch(...)` |
|
|
320
|
+
| **Other MCP servers** | `MCPIngestor` | `connect(server_name, url=...)` | `ingest_resources(...)`, `ingest_tool_output(...)` |
|
|
1508
321
|
|
|
1509
|
-
|
|
322
|
+
Also available: Redshift, Cassandra, MongoDB, DuckDB, Elasticsearch, Kafka-style
|
|
323
|
+
streams, email, RSS/Atom feeds, Airflow, Parquet/Arrow.
|
|
1510
324
|
|
|
1511
|
-
|
|
325
|
+
### Running ingestion (Python workflow)
|
|
1512
326
|
|
|
1513
|
-
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
## Installation
|
|
327
|
+
Source ingestion is a **Python-library workflow** — the Studio UI imports graph
|
|
328
|
+
files (JSON/CSV), it does not call source systems directly. The bridge is
|
|
329
|
+
`examples/ingest_to_studio.py`:
|
|
1518
330
|
|
|
1519
331
|
```bash
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
```
|
|
1523
|
-
|
|
1524
|
-
> **Note:** Heavy machine learning, NLP, visualization, and document dependencies live in optional extras to keep core installation lightweight and fast. If you want the previous bundled installation, install with `pip install "alphasemantichub[all]"`.
|
|
332
|
+
# any text/document file — no credentials needed:
|
|
333
|
+
uv run python examples/ingest_to_studio.py ./doc.txt --kind file --import
|
|
1525
334
|
|
|
1526
|
-
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
pip install "alphasemantichub[nlp-langdetect]" # Language detection for LanguageDetector (langdetect)
|
|
1533
|
-
pip install "alphasemantichub[viz]" # Visualization (matplotlib, seaborn, plotly, pyvis, graphviz)
|
|
1534
|
-
pip install "alphasemantichub[media]" # Audio & computer vision (librosa, opencv-python)
|
|
1535
|
-
pip install "alphasemantichub[graph-embeddings]" # Knowledge graph embeddings (gensim / Node2Vec)
|
|
1536
|
-
pip install "alphasemantichub[ingest-git]" # Git repository ingestor (GitPython)
|
|
1537
|
-
pip install "alphasemantichub[vectorstore-faiss]" # FAISS vector store
|
|
1538
|
-
pip install "alphasemantichub[vectorstore-all]" # All vector stores (Qdrant, Pinecone, Weaviate, FAISS, PgVector, SQLite)
|
|
1539
|
-
pip install "alphasemantichub[agno]" # Agno multi-agent integration
|
|
1540
|
-
pip install "crewai>=0.80.0" # CrewAI integration (no alphasemantichub extra — see integrations/crewai/README.md)
|
|
1541
|
-
pip install "alphasemantichub[langchain]" # LangChain / LangGraph integration
|
|
1542
|
-
pip install "alphasemantichub[llm-all]" # All LLM provider clients
|
|
1543
|
-
pip install "alphasemantichub[graph-neo4j]" # Neo4j graph store (LPG)
|
|
1544
|
-
pip install "alphasemantichub[graph-falkordb]" # FalkorDB graph store (LPG)
|
|
1545
|
-
pip install "alphasemantichub[graph-apache-age]" # Apache AGE graph store (LPG)
|
|
1546
|
-
pip install "alphasemantichub[graph-amazon-neptune]" # AWS Neptune graph store (LPG)
|
|
1547
|
-
pip install "alphasemantichub[tripletstore-oxigraph]" # Embedded in-memory/on-disk RDF store
|
|
1548
|
-
# RDF triple stores (Blazegraph, Apache Jena, Eclipse RDF4J) need no extra:
|
|
1549
|
-
# alphasemantichub.triplet_store talks SPARQL over HTTP using the core `requests` dependency
|
|
1550
|
-
pip install "alphasemantichub[db-snowflake]" # Snowflake
|
|
1551
|
-
pip install "alphasemantichub[db-databricks]" # Databricks (SDK + SQL connector)
|
|
1552
|
-
pip install "alphasemantichub[ingest-sap]" # SAP OData
|
|
1553
|
-
pip install "alphasemantichub[ingest-servicenow]" # ServiceNow Table API
|
|
1554
|
-
pip install "alphasemantichub[ingest-parquet]" # Parquet / PyArrow
|
|
1555
|
-
pip install "alphasemantichub[ingest-arrow]" # Apache Arrow, Feather, IPC
|
|
1556
|
-
pip install "alphasemantichub[watch]" # Directory file watcher
|
|
1557
|
-
pip install "alphasemantichub[explorer]" # Knowledge Explorer dashboard
|
|
335
|
+
# source systems (credentials via env vars, e.g. DATABRICKS_HOST/TOKEN/HTTP_PATH):
|
|
336
|
+
uv run python examples/ingest_to_studio.py silver_customers --kind databricks --import
|
|
337
|
+
uv run python examples/ingest_to_studio.py SalesOrder --kind sap --import
|
|
338
|
+
uv run python examples/ingest_to_studio.py CUSTOMERS --kind snowflake --import
|
|
339
|
+
uv run python examples/ingest_to_studio.py Account --kind salesforce --import
|
|
340
|
+
uv run python examples/ingest_to_studio.py https://api.example.com/items --kind rest --import
|
|
1558
341
|
```
|
|
1559
342
|
|
|
1560
|
-
|
|
343
|
+
What it does: ingest → `export_as_documents` → extract entities + triplets
|
|
344
|
+
(NER/pattern) → build a `ContextGraph` → save JSON → `--import` POSTs it to the
|
|
345
|
+
running Studio (multipart `/api/import`), where it appears in the Graph view.
|
|
1561
346
|
|
|
1562
|
-
|
|
1563
|
-
# From source
|
|
1564
|
-
git clone https://github.com/DeejayAI/alpha-semantic-hub.git
|
|
1565
|
-
cd alphasemantichub && pip install -e . --group dev && pytest tests/
|
|
1566
|
-
```
|
|
347
|
+
### A note on SharePoint
|
|
1567
348
|
|
|
1568
|
-
|
|
349
|
+
There is no dedicated SharePoint connector in this repository. The recommended
|
|
350
|
+
path today is **Microsoft Graph via `RESTIngestor`**:
|
|
1569
351
|
|
|
1570
|
-
|
|
352
|
+
```python
|
|
353
|
+
from alphasemantichub.ingest import RESTIngestor
|
|
1571
354
|
|
|
1572
|
-
|
|
1573
|
-
|
|
1574
|
-
|
|
1575
|
-
python-version: '3.11'
|
|
355
|
+
ing = RESTIngestor(config={"headers": {"Authorization": f"Bearer {token}"}})
|
|
356
|
+
for page in ing.paginated_fetch("https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root/children"):
|
|
357
|
+
...
|
|
1576
358
|
```
|
|
1577
359
|
|
|
1578
|
-
|
|
1579
|
-
|
|
1580
|
-
|
|
1581
|
-
|
|
1582
|
-
---
|
|
1583
|
-
|
|
1584
|
-
## Enterprise
|
|
1585
|
-
|
|
1586
|
-
On-premises deployment · Private cloud · Custom domain implementations · SLA-backed support · Professional services for regulated industries (finance, healthcare, legal, government).
|
|
1587
|
-
|
|
1588
|
-
**[alphahub.ltmb.io](https://alphahub.ltmb.io/)** for enterprise solutions and pricing.
|
|
1589
|
-
|
|
1590
|
-
---
|
|
1591
|
-
|
|
1592
|
-
## Community & Support
|
|
1593
|
-
|
|
1594
|
-
| | |
|
|
1595
|
-
| --- | --- |
|
|
1596
|
-
| **Discord** | [discord.gg/sV34vps5hH](https://discord.gg/sV34vps5hH): real-time help, showcases, and announcements |
|
|
1597
|
-
| **GitHub Discussions** | [Q&A and feature requests](https://github.com/DeejayAI/alpha-semantic-hub/discussions) |
|
|
1598
|
-
| **GitHub Issues** | [Bug reports](https://github.com/DeejayAI/alpha-semantic-hub/issues) |
|
|
1599
|
-
| **Documentation** | [docs.alphahub.ltmb.io](https://docs.alphahub.ltmb.io/) |
|
|
1600
|
-
| **Cookbook** | [Runnable Jupyter notebooks](https://github.com/DeejayAI/alpha-semantic-hub/tree/main/cookbook) |
|
|
1601
|
-
| **Changelog** | [CHANGELOG.md](CHANGELOG.md) · [Release Notes](RELEASE_NOTES.md) |
|
|
1602
|
-
|
|
1603
|
-
---
|
|
1604
|
-
|
|
1605
|
-
## Star History
|
|
360
|
+
…or `WebIngestor.ingest_url(...)` for pages, or `CloudStorageIngestor` /
|
|
361
|
+
`FileIngestor` for documents synced out of SharePoint document libraries. A
|
|
362
|
+
dedicated connector can be added by registering a new method in
|
|
363
|
+
`ingest/methods.py`.
|
|
1606
364
|
|
|
1607
|
-
|
|
1608
|
-
<picture>
|
|
1609
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=DeejayAI/alpha-semantic-hub&type=date&theme=dark&legend=top-left" />
|
|
1610
|
-
<source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=DeejayAI/alpha-semantic-hub&type=date&legend=top-left" />
|
|
1611
|
-
<img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=DeejayAI/alpha-semantic-hub&type=date&legend=top-left" />
|
|
1612
|
-
</picture>
|
|
1613
|
-
</a>
|
|
365
|
+
## 9 · Development
|
|
1614
366
|
|
|
1615
|
-
|
|
1616
|
-
|
|
1617
|
-
|
|
1618
|
-
|
|
1619
|
-
<div align="center">
|
|
1620
|
-
|
|
1621
|
-
[](https://github.com/DeejayAI/alpha-semantic-hub/graphs/contributors)
|
|
1622
|
-
|
|
1623
|
-
</div>
|
|
1624
|
-
|
|
1625
|
-
---
|
|
1626
|
-
|
|
1627
|
-
## Contributing
|
|
1628
|
-
|
|
1629
|
-
All contributions are welcome: bug fixes, features, tests, and documentation.
|
|
1630
|
-
|
|
1631
|
-
1. Fork the repo and create a branch
|
|
1632
|
-
2. `pip install -e . --group dev` (pip 25.1+) or `uv sync`
|
|
1633
|
-
3. Write tests alongside your changes (`pytest tests/`)
|
|
1634
|
-
4. Open a PR and tag `@KaifAhmad1` for review
|
|
1635
|
-
|
|
1636
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
|
|
1637
|
-
|
|
1638
|
-
---
|
|
367
|
+
```bash
|
|
368
|
+
git clone https://github.com/DeejayAI/alpha-semantic-hub.git
|
|
369
|
+
cd alpha-semantic-hub
|
|
1639
370
|
|
|
1640
|
-
|
|
371
|
+
# Python
|
|
372
|
+
uv sync --extra explorer
|
|
373
|
+
uv run alphasemantichub --version
|
|
374
|
+
uv build # → dist/
|
|
1641
375
|
|
|
1642
|
-
|
|
376
|
+
# Studio UI (Node 22+)
|
|
377
|
+
cd explorer && npm install && npm run build # outputs to alphasemantichub/static/
|
|
1643
378
|
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
|
-
title = {Alpha Semantic Hub: Graph-Native Infrastructure for Context and Accountable AI Systems},
|
|
1647
|
-
author = {Mohammad Kaif},
|
|
1648
|
-
year = {2026},
|
|
1649
|
-
url = {https://github.com/DeejayAI/alpha-semantic-hub}
|
|
1650
|
-
}
|
|
379
|
+
# Docker image
|
|
380
|
+
docker build -t ltmbios/alpha-hub-studio:0.7.0 .
|
|
1651
381
|
```
|
|
1652
382
|
|
|
1653
|
-
|
|
1654
|
-
|
|
1655
|
-
---
|
|
383
|
+
### Release automation
|
|
1656
384
|
|
|
1657
|
-
|
|
385
|
+
`.github/workflows/release.yml` builds the wheel/sdist and attaches them to a
|
|
386
|
+
GitHub Release (this is how the Python distribution is published — GitHub-hosted,
|
|
387
|
+
not PyPI). npm packages are published manually by the release manager under
|
|
388
|
+
`@ltm-blueverse`.
|
|
1658
389
|
|
|
1659
|
-
|
|
390
|
+
### Configuration reference
|
|
1660
391
|
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
[Docs](https://docs.alphahub.ltmb.io/) ·
|
|
1666
|
-
[PyPI](https://pypi.org/project/alphasemantichub/)
|
|
392
|
+
All environment variables use the **`ASHUB_`** prefix:
|
|
393
|
+
`ASHUB_KG_PATH`, `ASHUB_API_KEY`, `ASHUB_NS`, `ASHUB_VECTOR_PATH`,
|
|
394
|
+
`ASHUB_DISABLE_PROGRESS`, `ASHUB_LOG_LEVEL`, and more — grep the source for
|
|
395
|
+
`ASHUB_` to see the full list.
|
|
1667
396
|
|
|
1668
|
-
|
|
397
|
+
## 10 · Identity summary
|
|
1669
398
|
|
|
1670
|
-
|
|
399
|
+
| Token | Value |
|
|
400
|
+
|---|---|
|
|
401
|
+
| Product | **Alpha Semantic Hub** |
|
|
402
|
+
| Python package | `alphasemantichub` |
|
|
403
|
+
| npm scope / user | `@ltm-blueverse` / **LTM-ALpha** |
|
|
404
|
+
| Org | **ltm-blueverse** (LTM Blueverse) |
|
|
405
|
+
| GitHub | [DeejayAI/alpha-semantic-hub](https://github.com/DeejayAI/alpha-semantic-hub) |
|
|
406
|
+
| Docker image | `ltmbios/alpha-hub-studio` |
|
|
407
|
+
| Brand color | Alpha red `#E11D2E` |
|
|
408
|
+
| Logo | Red **A** inside a red circle (`logo/`) |
|
|
409
|
+
| Env prefix | `ASHUB_` |
|
|
410
|
+
| Namespace | `https://alphahub.ltmb.io/ns#` |
|
|
1671
411
|
|
|
1672
|
-
|
|
412
|
+
## License
|
|
1673
413
|
|
|
1674
|
-
|
|
414
|
+
MIT — © 2026 LTM Blueverse. See [LICENSE](LICENSE).
|