Alpha Semantic Hub

Graph-Native Infrastructure for Context and Accountable AI Systems
Context graphs · decision intelligence · full provenance tracking · explainable reasoning — every AI decision traceable, every output auditable.

---

Install guide: see INSTALL.md for step-by-step install instructions for every platform.

Alpha Semantic Hub is a graph-native context platform rebuilt end-to-end under the LTM Blueverse identity: red brand system, futuristic "Alpha" logo (a red A inside a red circle), a redesigned futuristic Studio UI/UX, scoped npm packages, harness integrations for every major AI coding agent, and a Docker Studio image.

Packages

Artifact	Where	Install
Python distribution alphasemantichub	GitHub Releases (this repo)	pip install <release wheel URL>
npm metapackage (harness plugins + skills)	npm @ltm-blueverse/alpha-semantic-hub	npm install @ltm-blueverse/alpha-semantic-hub
Studio UI (prebuilt static assets)	npm @ltm-blueverse/alpha-hub-studio	npm install @ltm-blueverse/alpha-hub-studio
Docker Studio image	Docker Desktop / ltmbios/alpha-hub-studio	docker pull ltmbios/alpha-hub-studio:latest

---

1 · Install the Python package

The Python distribution (alphasemantichub; CLI: alphasemantichub, alphasemantichub-server, alphasemantichub-worker, alphasemantichub-explorer, alphasemantichub-mcp) is published on GitHub Releases (not PyPI).

Python ≥ 3.10 required (3.10–3.13 supported).

# latest release wheel
pip install https://github.com/DeejayAI/alpha-semantic-hub/releases/latest/download/alphasemantichub-0.7.1-py3-none-any.whl

# or from a specific release tag
pip install https://github.com/DeejayAI/alpha-semantic-hub/releases/download/v0.7.1/alphasemantichub-0.7.1-py3-none-any.whl

# with optional extras
pip install "https://github.com/DeejayAI/alpha-semantic-hub/releases/latest/download/alphasemantichub-0.7.1-py3-none-any.whl[explorer]"

Verify:

alphasemantichub --version

Optional extras

pip install "alphasemantichub[explorer]"      # Studio backend (FastAPI)
pip install "alphasemantichub[shacl]"         # SHACL validation
pip install "alphasemantichub[parse-docling]" # advanced document parsing
pip install "alphasemantichub[llm-openai]"    # OpenAI LLM provider
pip install "alphasemantichub[llm-anthropic]" # Anthropic LLM provider
pip install "alphasemantichub[llm-gemini]"    # Google Gemini provider
pip install "alphasemantichub[all]"           # everything

2 · Install the npm packages

Published on npmjs.com under the @ltm-blueverse scope (user LTM-ALpha).

# metapackage: harness plugins, skills, agents, hooks
npm install @ltm-blueverse/alpha-semantic-hub

# studio UI as prebuilt static assets (no toolchain needed)
npm install @ltm-blueverse/alpha-hub-studio

3 · Run the Studio with Docker (Docker Desktop)

The Studio UI + API ships as a Docker image built for Docker Desktop on macOS.

docker pull ltmbios/alpha-hub-studio:latest

# or with the bundled FalkorDB graph database:
docker compose up -d

docker-compose.yml starts:

• alpha-hub-studio — Studio UI + API on http://localhost:8000
• falkordb — graph database on port 6379

Environment variables (all prefixed ASHUB_):

Variable	Purpose
ASHUB_API_KEY	API key for protected Studio routes (generate: openssl rand -hex 32)
ASHUB_ALLOW_ANONYMOUS	true bypasses the API key (local-only setups)
ASHUB_KG_PATH	Graph persistence file — auto-loaded at startup, auto-saved on every import (set to /data/graph.json in the compose stack)
ASHUB_LOG_LEVEL	Logging verbosity
ASHUB_CORS_ORIGINS	Allowed CORS origins

Then open http://localhost:8000 — the red-themed futuristic Studio.

4 · Harness integrations (AI coding agents)

The repo ships ready-to-install plugins under plugins/. Install the npm metapackage (npm install @ltm-blueverse/alpha-semantic-hub) or point your tool at the checked-out plugins/ directory.

How the harness integration works

Every integration follows the same shape:

1. The harness (Claude Code, Copilot, Codex, …) launches the MCP server as a child process (python -m alphasemantichub.mcp_server, stdio transport)
2. The plugin manifest tells the harness which skills (markdown playbooks in plugins/skills/) and agents (persona definitions in plugins/agents/) to load alongside its native tools
3. The agent can then call knowledge-graph tools (extract_entities, record_decision, find_precedents, query_graph, …) directly from its chat/tool loop — reading from and writing to the same graph the Studio shows
4. Optional hooks (plugins/hooks/hooks.json) run small guards on Write/Edit/Bash events (e.g. Python syntax checks on graph files)

Because the transport is stdio JSON-RPC, there is no server to manage: install the Python package in the interpreter the harness uses, register the command, and the tools appear.

Claude (Claude Code / Claude Desktop)

# from a checkout of this repo
claude plugin add ./plugins/.claude-plugin
# or from the npm package
claude plugin add "$(npm root -g)/@ltm-blueverse/alpha-semantic-hub/plugins/.claude-plugin"

Includes skills (plugins/skills/), agents (KG assistant, decision advisor, explainability), and hooks.

VS Code / GitHub Copilot

Install the .vscode-plugin manifest, or configure the MCP server in VS Code settings.json:

{
  "mcp": {
    "servers": {
      "alpha-semantic-hub": {
        "command": "python",
        "args": ["-m", "alphasemantichub.mcp_server"],
        "transport": "stdio"
      }
    }
  }
}

Codex (OpenAI)

codex plugin add ./plugins/.codex-plugin

Cursor

# add the plugin directory in Cursor settings → MCP, or:
cursor install ./plugins/.cursor-plugin

Continue.dev

Copy plugins/.continue-plugin into your Continue config and register the MCP server command above.

Windsurf / Cline / OpenClaw

Each has a ready manifest: plugins/.windsurf-plugin, plugins/.cline-plugin, plugins/.openclaw-plugin — all pointing at the same MCP server.

---

5 · The Studio UI

The bundled Knowledge Explorer ships in the Alpha red brand system with a light, readable theme:

• White background with near-black text and light red highlights/captions
• Alpha red accent system (#E11D2E → #FF4B55 gradients), sharp futuristic geometry
• Red A-in-circle brand mark in the navigation rail, favicon and app icons
• All workspaces (Graph, Analyze, Decisions, Enrich, Manage, Ontology Hub) restyled

Serve it three ways:

1. Python (recommended): pip install "alphasemantichub[explorer]" then alphasemantichub-explorer → http://localhost:8000
2. Docker: docker compose up -d → http://localhost:8000
3. Static: grab @ltm-blueverse/alpha-hub-studio from npm and serve static/

6 · How the MCP server works

Alpha Semantic Hub exposes its knowledge graph to AI agents over the Model Context Protocol (MCP). The server speaks JSON-RPC 2.0 over stdio — an agent harness launches it as a child process and exchanges newline-delimited JSON-RPC messages (initialize, tools/list, tools/call, resources/list, resources/read). No network port is opened, so it works identically in Claude Code, VS Code, Codex, Cursor, or any MCP-capable client.

Two builds are included:

Server	Launch	Tools
Installed server (alphasemantichub.mcp_server)	alphasemantichub-mcp or python -m alphasemantichub.mcp_server	16 tools
Extended in-repo server (alphasemantichub_mcp.mcp)	python -m alphasemantichub_mcp.mcp	22 tools (adds retrieval, provenance, impact analysis)

What the tools cover:

• Extraction — extract_entities (NER over text), extract_relations (relations + subject-predicate-object triplets)
• Decision intelligence — record_decision, query_decisions, find_precedents (similarity search over past decisions), get_causal_chain (trace what a decision influenced, upstream or downstream), link_decisions (typed causal edges: CAUSED / INFLUENCED / PRECEDENT_FOR), analyze_decision_impact
• Graph — add_entity, add_relationship, query_graph (node lookup, 1–5-hop neighborhoods, keyword search), get_graph_analytics (PageRank, community detection), get_graph_summary
• Reasoning — run_reasoning (forward-chaining IF/THEN rules over facts), abductive_reasoning (hypotheses that explain observed facts)
• Persistence & I/O — export_graph (Turtle, JSON-LD, RDF/XML, GraphML, CSV, Parquet, N-Triples), update_node, delete_node (soft archive)
• Retrieval (extended server) — store_document (chunk + embed), retrieve_context (semantic search + related graph relationships)

State: point ASHUB_KG_PATH at a graph file and every mutation (decisions, entities, relationships) is persisted and reloaded across sessions — the graph your agent edits is the graph the Studio renders.

7 · How the ontology is built

Ontologies are produced by OntologyEngine, which composes a six-stage generator pipeline:

1. Parse — normalize {"entities": [...], "relationships": [...]} produced by the semantic-extraction pipeline (NERExtractor, RelationExtractor, TripletExtractor)
2. Define — map concepts to candidate class definitions
3. Type & property inference — PropertyGenerator.infer_properties stamps classes/properties with URIs from NamespaceManager (base namespace https://alphahub.ltmb.io/ontology/)
4. Hierarchy — ClassInferrer.build_class_hierarchy assembles the class tree (frequency-gated: concepts need min_occurrences=2 to survive)
5. Serialize — OWLGenerator emits Turtle / RDF-XML / JSON-LD / N3
6. Validate — OntologyValidator checks consistency and satisfiability; results land in ontology["validation"]

Then:

• SHACL shapes are derived with OntologyEngine.to_shacl(...) (quality tiers basic/standard/strict) and enforced at runtime with validate_graph(...) (pyshacl) — reports come back as plain-English violations
• Quality gate — quality_check(...) returns a graded report of issues
• Versioning — VersionManager.create_version gives each ontology a versioned IRI, and compare_versions / diff_ontologies produce change reports between versions
• LLM-assisted drafting — OntologyEngine.from_text(...) drafts an ontology from unstructured text; the result goes through the same validation and versioning

Resulting dict shape:

{
  "uri": "https://alphahub.ltmb.io/ontology/v1.0/",
  "name": "...", "version": "1.0",
  "classes": [{"name", "uri", "label", "comment", "properties", "entity_count"}],
  "properties": [...],
  "validation": {"valid": true, "consistent": true, "satisfiable": true, ...}
}

8 · Connecting source systems

The ingest layer feeds the ontology and knowledge graph from external systems. Every connector is lazy-loaded and degrades to a helpful install hint when its SDK is missing. Two patterns:

• a Connector (auth + transport) paired with an Ingestor (extraction + export_as_documents)
• a unified dispatcher: ingest(sources, source_type="db", method=...)

Source system	Ingestor	Connection	Primary call
Databricks	DatabricksIngestor	host, token, http_path, catalog, schema (env: DATABRICKS_HOST, DATABRICKS_TOKEN, DATABRICKS_HTTP_PATH)	ingest_table("silver_customers"), ingest_query("SELECT ...")
SAP (OData)	SAPIngestor	base_url, `auth="oauth2"	"basic", token_url, client_id, client_secret`
Snowflake	SnowflakeIngestor	account, user, password/private_key, warehouse, database, schema, role	ingest_table(...), ingest_query(...)
Salesforce	SalesforceIngestor	username, password, security_token (env: SALESFORCE_USERNAME, …)	ingest_sobject("Account", fields=[...]), ingest_query(soql)
ServiceNow	ServiceNowIngestor	instance_url, auth, username/client_id + secret	ingest_table(table="incident", query=..., limit=...)
Power BI	PowerBIIngestor	tenant_id, client_id, client_secret, workspace_id	ingest_workspace_metadata()
Tableau	TableauIngestor	server_url, site_name, token_name, token_value	ingest_workbooks(), ingest_datasources()
Looker	LookerIngestor	base_url, client_id, client_secret (or looker.ini)	ingest_looks(), ingest_dashboards(), ingest_lookml_models()
BigQuery	BigQueryIngestor	project, dataset, credentials_file	ingest_table(...), ingest_query(...)
Web / intranet	WebIngestor	user_agent, respect_robots=True	ingest_url(url), crawl_sitemap(...), crawl_domain(...)
Files & cloud storage	FileIngestor, CloudStorageIngestor	provider config for S3 / GCS / Azure Blob	ingest_file, ingest_directory, ingest_cloud
Git repositories	RepoIngestor	repo URL	ingest_repository(url) + commit/code analysis
REST APIs	RESTIngestor	config={"headers": {...}}	ingest_endpoint(...), paginated_fetch(...)
Other MCP servers	MCPIngestor	connect(server_name, url=...)	ingest_resources(...), ingest_tool_output(...)

Also available: Redshift, Cassandra, MongoDB, DuckDB, Elasticsearch, Kafka-style streams, email, RSS/Atom feeds, Airflow, Parquet/Arrow.

Connector catalog and the credential vault

26 connectors in 5 categories, all selectable from the Studio's Source Ingestion tab:

Category	Connectors
Warehouses & Lakehouses	Databricks, Snowflake, BigQuery, Redshift
Databases	SQL (Postgres/MySQL/SQLite), DuckDB, MongoDB, Cassandra, Elasticsearch
Business SaaS	Salesforce, SAP (OData), ServiceNow, Power BI, SharePoint/OneDrive (Graph API)
Files & Storage	File, Parquet, XML, Cloud Storage (S3/GCS/Azure), Google Drive
Web & APIs	REST, Web page, RSS/Atom, Git repo, Email (IMAP/POP3), HuggingFace, MCP server

Connectors marked dep need an optional dependency (e.g. lxml, boto3, pymongo, gitpython, duckdb, google-cloud-bigquery); the Studio shows this before you run.

Credentials vault. Secrets entered in the UI are encrypted and stored under ASHUB_VAULT_DIR (default /data/vault, mounted from ./data). Saved credentials are reusable across ingestion runs and LLM calls.

• ASHUB_VAULT_KEY — optional 32-byte master key (base64/hex). When unset, a key file is generated at <vault_dir>/vault.key with 0600 permissions.
• Records are encrypted with encrypt-then-MAC (HMAC-SHA256, HKDF-derived keys) using only the standard library — no new dependencies in the hash-pinned image. Tampered records fail closed rather than decrypting.
• Secrets are never returned by the list API and are scrubbed from job/error messages.

OpenAI-compatible LLM endpoints. Besides the 8 built-in providers, the LLM Endpoints tab can add any /v1-style endpoint (vLLM, Ollama's OpenAI layer, OpenRouter, LiteLLM proxies, Azure gateways): enter a base URL + optional API key, fetch the model list from the endpoint, pick a model, save it to the vault, and set it as the platform default.

Ingestion, MCP tools and LLM endpoints in the Studio

The Enrich workspace has three tabs for this:

• Source Ingestion — all 26 connectors across 5 categories (warehouses, databases, business SaaS, files & storage, web & APIs — including Git repositories, SharePoint/OneDrive via Graph, Google Drive, MongoDB, Elasticsearch, DuckDB, HuggingFace datasets). Pick a category in the sidebar, search to filter, save credentials in the encrypted vault, test the connection, run ingestion with live progress, and extraction loads the entities/relations straight into the graph on screen. Private Git repos: save an authenticated clone URL (https://x-access-token:TOKEN@github.com/org/repo.git) as the repo_url credential field and put the plain URL in the source box.
• MCP Tools — browse and invoke all 16 tools that Claude Code / Codex / Copilot get over MCP. Calls run against the same live graph the Studio shows.
• LLM Endpoints — shows where the platform uses language models, which providers are configured (OpenAI, Anthropic, Gemini, Groq, DeepSeek, Novita, Ollama, HuggingFace) and fires a real test prompt per provider.

npm-packages/ staging, data/ volumes and container-local paths (/data/…) apply as per the compose file.

Running ingestion (Python workflow)

Source ingestion is a Python-library workflow — the Studio UI imports graph files (JSON/CSV), it does not call source systems directly. The bridge is examples/ingest_to_studio.py:

# any text/document file — no credentials needed:
uv run python examples/ingest_to_studio.py ./doc.txt --kind file --import

# source systems (credentials via env vars, e.g. DATABRICKS_HOST/TOKEN/HTTP_PATH):
uv run python examples/ingest_to_studio.py silver_customers --kind databricks --import
uv run python examples/ingest_to_studio.py SalesOrder --kind sap --import
uv run python examples/ingest_to_studio.py CUSTOMERS --kind snowflake --import
uv run python examples/ingest_to_studio.py Account --kind salesforce --import
uv run python examples/ingest_to_studio.py https://api.example.com/items --kind rest --import

What it does: ingest → export_as_documents → extract entities + triplets (NER/pattern) → build a ContextGraph → save JSON → --import POSTs it to the running Studio (multipart /api/import), where it appears in the Graph view.

A note on SharePoint

There is no dedicated SharePoint connector in this repository. The recommended path today is Microsoft Graph via RESTIngestor:

from alphasemantichub.ingest import RESTIngestor

ing = RESTIngestor(config={"headers": {"Authorization": f"Bearer {token}"}})
for page in ing.paginated_fetch("https://graph.microsoft.com/v1.0/sites/{site-id}/drive/root/children"):
    ...

…or WebIngestor.ingest_url(...) for pages, or CloudStorageIngestor / FileIngestor for documents synced out of SharePoint document libraries. A dedicated connector can be added by registering a new method in ingest/methods.py.

9 · Development

git clone https://github.com/DeejayAI/alpha-semantic-hub.git
cd alpha-semantic-hub

# Python
uv sync --extra explorer
uv run alphasemantichub --version
uv build                      # → dist/

# Studio UI (Node 22+)
cd explorer && npm install && npm run build   # outputs to alphasemantichub/static/

# Docker image
docker build -t ltmbios/alpha-hub-studio:0.7.0 .

Release automation

.github/workflows/release.yml builds the wheel/sdist and attaches them to a GitHub Release (this is how the Python distribution is published — GitHub-hosted, not PyPI). npm packages are published manually by the release manager under @ltm-blueverse.

Configuration reference

All environment variables use the ASHUB_ prefix: ASHUB_KG_PATH, ASHUB_API_KEY, ASHUB_NS, ASHUB_VECTOR_PATH, ASHUB_DISABLE_PROGRESS, ASHUB_LOG_LEVEL, and more — grep the source for ASHUB_ to see the full list.

10 · Identity summary

Token	Value
Product	Alpha Semantic Hub
Python package	alphasemantichub
npm scope / user	@ltm-blueverse / LTM-ALpha
Org	ltm-blueverse (LTM Blueverse)
GitHub	DeejayAI/alpha-semantic-hub
Docker image	ltmbios/alpha-hub-studio
Brand color	Alpha red #E11D2E
Logo	Red A inside a red circle (logo/)
Env prefix	ASHUB_
Namespace	https://alphahub.ltmb.io/ns#

License

MIT — © 2026 LTM Blueverse. See LICENSE.