商业产业 Hacker News AI 2026-08-19T22:28 正文 ok 8185 words

Semantica：面向 AI Agent 的开源 Palantir

英文标题：🔶 Semantica, the Open Source Palantir for AI Agents

Semantica 将自身定位为位于 LLM、向量数据库和 Agent 框架之下的确定性基础设施层，用于构建可查询的上下文图谱、决策记录、因果关系和数据溯源。其核心主张是提供系统级可解释性：不试图揭示 LLM 内部推理，而是追踪输入上下文、输出决策、相关证据、适用策略及完整执行轨迹。该项目面向金融、医疗、法律和政府等受监管行业，支持 W3C PROV-O、SHACL、OWL、Rete、Datalog、SPARQL，以及 Databricks、Snowflake、Neo4j 等平台与存储后端。对开发者而言，Semantica 可在不替换既有 LLM、向量库和 Agent 框架的前提下，补充可审计决策、冲突检测、知识图谱治理和合规导出能力。

打开原文相关 5 · 机会 3

769.8 KB

5.1 KB

4.2 KB

1.9 KB

1.7 KB

3.2 KB

1.2 KB

2.6 KB

553 B

547 B

1.8 KB

1.4 KB

2.9 KB

2.5 KB

1.1 KB

1.3 KB

4.0 KB

8.1 MB

2.6 KB

中文

大多数 AI Agent 的行为没有留下可追溯路径。它们存储的是嵌入，而非语义：上下文无法解释，决策无法审计。在信贷领域，这种缺口并非只是使用不便，而是合规风险：承保 Agent 的审批决定，必须能够在数月后经受监管机构对“为什么”的追问。

Semantica 位于你的 LLM、向量数据库和 Agent 框架之下，作为一个确定性的基础设施层：图谱构建、推理或溯源均不需要 LLM。

⚠️ 这是系统级可解释性，而非基础模型可解释性。 Semantica 不会暴露或重构 LLM _内部_发生的过程——其内部推理或思维链与任何外部系统一样，仍然是不透明的。Semantica 解释的是模型_外部_的内容：输入的上下文和数据、产生的决策、决策溯源、相关关系、所应用的策略，以及完整的执行轨迹。

适用对象：

AI/ML 平台团队：正在交付会做出重要决策的 Agent，需要从碎片化原始数据构建结构化、可查询的上下文，而不仅仅是一个向量索引
使用 Databricks 或 Snowflake 的数据平台团队：需要将已存放在 Unity Catalog 或 Snowflake 数据仓库中的表转化为受治理、可追踪数据血缘的知识图谱，而无需先将数据导出至第三方 SaaS
合规、风险与审计团队：需要以监管机构真正会接受的格式，直接回答“AI 为什么这么做？”
受监管企业（金融、医疗、法律、政府、国防）：既不能交付黑盒系统，也无法为了得到一个系统而把数据发送给其他公司的 SaaS
平台和基础设施工程师：希望知识图谱、推理和溯源技术栈能够自托管且可替换，而不是被锁定在某一家供应商的后端中
数据和知识工程师：从混乱的多源数据中构建知识图谱；系统会提取实体和关系，标记相互冲突或矛盾的事实而不是静默覆盖，并在重复内容演变为噪声前进行合并

快速开始 · 架构 · 你将获得什么 · 为什么选择 Semantica · 决策智能 · 上下文图谱 · 实践方案：审计轨迹 · 模块参考 · 集成 · CLI · 性能 · 安装

**上下文图谱：**以结构化、可查询的图谱形式，呈现 Agent 所知、所决定和所推理的一切内容
**决策智能：**每项决策都是一等对象：可追踪、可按先例检索，并具有因果关联
**AI 治理与本体：**提供 SHACL 约束、冲突检测、合规规则、OWL 生成以及带可视化编辑器的 SKOS 词汇表管理
**完整可审计性：**每项事实都具备 W3C PROV-O 溯源信息，审计轨迹可导出为 JSON、CSV 或 RDF
**确定性推理：**支持前向链推理、Rete 网络、Datalog 和 SPARQL，并提供完全可解释的推理路径，而非黑盒
**知识管道：**支持多源摄取、面向实体的分块、NER/关系/事件提取和知识图谱构建，并在全流程中实现语义去重与保留溯源的合并
**企业数据平台：**原生连接 Databricks（Unity Catalog + Delta Lake、PAT/OAuth M2M 身份验证、catalog/schema/table/lineage 检视）和 Snowflake（warehouse/database/schema、密钥对和 OAuth 身份验证），让已存在于数据湖仓或数据仓库中的表成为带溯源的图谱节点，而非又一次导出/导入流程
**图谱分析：**可对刚刚构建的图谱执行中心性分析、社区发现、链路预测和最短路径查询
**多语言图谱存储：**原生支持 RDF（通过 SPARQL 接入嵌入式 Oxigraph、Blazegraph、Apache Jena、Eclipse RDF4J）和带标签属性图（通过 Cypher 接入 Neo4j、FalkorDB、Apache AGE、AWS Neptune），同时支持向量数据库；无需改动代码即可替换后端
**可视化：**可在交互式浏览器工作台中探索任意图谱、本体或时间线
**即插即用集成：**原生支持 Agno 和 CrewAI，提供功能完整的 MCP 服务器、全面的 CLI、REST API，以及覆盖主流编辑器的插件

| 向量数据库 + RAG | 普通 LLM 记忆 | Semantica
---|---|---|---
召回方法 | 嵌入相似度 | Token 窗口 | 图谱遍历 + 语义搜索
决策历史 | 不存储 | 不存储 | 可查询的一等对象
溯源 | 无 | 无 | W3C PROV-O，与来源关联
推理 | 无 | 黑盒 | 前向链、Rete、Datalog、SPARQL
冲突检测 | 静默覆盖 | 静默覆盖 | 检测、标记、解决
时间回溯 | 否 | 否 | 时间点图谱快照
合规导出 | 无 | 无 | PROV-O、SHACL、OWL、RDF
策略执行 | 无 | 无 | 内置规则引擎 + SHACL
实体消歧 | 否 | 否 | Blocking + 语义去重
多 Agent 上下文 | 每个 Agent 独立 | 每个 Agent 独立 | 单一共享智能层

Semantica 对现有技术栈起补充作用，而非替代作用。你可以完全保留原有的 LLM、向量数据库和 Agent 框架；Semantica 会在其上增加决策记录、因果推理、溯源、本体治理、冲突检测和审计轨迹。推理引擎、知识图谱构建和溯源层均为完全确定性的实现；使用这些能力不需要 LLM。

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Every agent decision becomes a queryable, auditable knowledge node
decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

# Ask "why did this happen?" and get a real, structured answer
chain     = graph.trace_decision_chain(decision_id)       # full causal ancestry
similar   = graph.find_similar_decisions("cloud vendor", max_results=5)  # precedents
impact    = graph.analyze_decision_impact(decision_id)    # downstream influence map
compliant = graph.check_decision_rules({"category": "vendor_selection"})  # policy gate

在 5 秒内验证安装：

semantica doctor
# Python 3.11.9         pass
# semantica 0.6.6       pass
# faiss vector store    pass
# Config file           pass    ~/.semantica/config.yaml

Semantica 是一条真正的端到端管道，而不是一个挂着营销名称的单一库。下面每个阶段都是已交付模块，均可独立导入：

Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
   → Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
   → Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI

**摄取：**文件、Web、数据库、企业数据平台（Databricks、Snowflake）、云服务（Google Drive、Elasticsearch）、流（Kafka、Kinesis）、Git、电子邮件、MCP
**解析 → 规范化 → 分块：**文档解析、文本/实体/日期规范化、原生面向 GraphRAG 的实体感知分块
**提取 → 冲突检测 → 去重：**NER、关系、事件、三元组；在冲突事实合并之前对其进行标记和解决
知识图谱：GraphBuilder 负责构建图谱；其上可运行双时间事实和完整图谱分析能力（中心性、社区、链路预测）
**本体 · 推理 · 溯源 · 决策：**位于知识图谱之上的智能层，提供 SHACL/OWL 治理、Rete/Datalog/SPARQL 推理、W3C PROV-O 血缘和一等决策记录
**存储：**设计上采用多语言存储，支持 RDF 三元组存储（嵌入式 Oxigraph、Blazegraph、Apache Jena、Eclipse RDF4J）、带标签属性图（Neo4j、FalkorDB、Apache AGE、AWS Neptune）以及向量数据库，均可在不改动代码的情况下替换
**输出：**支持导出（RDF、OWL、Parquet、Cypher、JSON-LD）、交互式可视化，并可通过 REST API、MCP 服务器或 CLI 访问

→管道和决策智能生命周期的完整 Mermaid 图

决策智能将每一次 AI 选择从短暂的推理结果转化为永久、可审计、可查询的记录。它回答的是：“你的 AI 做了什么决定、为什么做出这个决定，以及之后发生了什么？”——这是监管机构和企业风险团队日益迫切提出的问题。

在 Semantica 中，决策不是一条日志，而是拥有完整生命周期的一等图谱节点。在受监管领域，每个 AI 决策都必须可追溯到来源，并能够向审计人员进行辩护：record_decision() 会创建永久的结构化记录，并可导出为 W3C PROV-O——这是大多数合规框架接受并用于提交监管机构的格式。

record_decision()             → stored as a graph node with full structured context
add_causal_relationship()     → linked to upstream causes and downstream effects
find_similar_decisions()      → semantic precedent search across all past decisions
trace_decision_chain()        → full causal ancestry back to root causes
analyze_decision_impact()     → downstream influence map - everything this decision affected
check_decision_rules()        → policy compliance gate against configurable rule sets
export / audit trail          → W3C PROV-O, CSV, or JSON for regulator submission



from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Record decisions with full structured context
app_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"},
)
uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Underwriting review for A-7291",
    reasoning="DTI within policy; clean 36-month credit history",
    outcome="approved",
    confidence=0.94,
)
rate_id = graph.record_decision(
    category="interest_rate",
    scenario="Rate assignment for approved loan A-7291",
    outcome="rate_set_8.9pct",
    reasoning="Prime + 2.4% based on risk tier B2",
    confidence=0.99,
)

# Build the auditable causal chain - relationship_type must be one of
# CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(app_id, uw_id,   relationship_type="CAUSED")
graph.add_causal_relationship(uw_id,  rate_id, relationship_type="INFLUENCED")

# Query the intelligence
chain     = graph.trace_decision_chain(rate_id)
similar   = graph.find_similar_decisions("personal loan approval, 31% DTI", max_results=5)
impact    = graph.analyze_decision_impact(uw_id)
compliant = graph.check_decision_rules({"category": "loan_underwriting", "confidence": 0.94})
insights  = graph.get_decision_insights()

上下文图谱是传统 RAG 所缺少的结构化记忆层。与只能回答_“什么内容相似？”的扁平嵌入不同，上下文图谱能够回答“什么内容彼此关联、为什么关联、以及如何关联？”_。每个实体、关系、决策和事实都是一等节点，可通过图谱遍历进行查询。实体可关联来源文档，决策可关联证据和后果，事实携带完整溯源信息，冲突会被检测而非静默覆盖。

from semantica.context import ContextGraph, AgentContext
from semantica.vector_store import VectorStore

graph = ContextGraph(advanced_analytics=True)

# Add nodes with typed properties
graph.add_node("acme_corp",    "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen",   "Person",       name="Alice Chen", role="CTO")
graph.add_node("contract_001", "Contract",     value=2_400_000, currency="USD")

# Add typed, weighted edges (extra kwargs become edge metadata)
graph.add_edge("alice_chen", "acme_corp",    edge_type="works_for",  since="2019-03-01")
graph.add_edge("acme_corp",  "contract_001", edge_type="party_to",   signed="2024-01-15")

# BFS traversal - hop through the graph from any node
neighbors = graph.get_neighbors("acme_corp", hops=2)

# Point-in-time snapshot - the graph as it existed on any past date
snapshot  = graph.state_at("2024-01-01")

# AgentContext - high-level API for agent memory workflows
vs  = VectorStore(backend="faiss")
ctx = AgentContext(vector_store=vs, knowledge_graph=graph)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
retrieved = ctx.retrieve("who approved the Acme contract?")

**为什么选择图谱而不是嵌入：**图谱遍历能够发现嵌入遗漏的连接（例如与合同相隔 3 跳的某个人）；每个节点都携带溯源信息，因此你始终可以追问_“这来自哪里？”_；冲突会在污染知识库之前被标记；时间点快照让你无需重新处理数据即可回放历史。

实践方案：受监管决策的审计轨迹

这一核心模式包括：记录具有因果关联的决策链、为每个实体附加溯源信息，并导出可直接提交监管机构的审计轨迹。

from semantica.context import ContextGraph
from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

graph = ContextGraph(advanced_analytics=True)
prov  = ProvenanceManager(storage_path="./audit.db")

# Record the decision chain
d1 = graph.record_decision(
    category="drug_interaction_check", scenario="Patient P-4821: warfarin

English / 原文

Most AI agents act without a trail. They store embeddings, not meaning: context that can't be explained, decisions that can't be audited. In lending, that gap is a compliance exposure, not an inconvenience: an underwriting agent's approval has to survive a regulator's "why" months later.

Semantica sits underneath your LLM, vector store, and agent framework as a deterministic infrastructure layer: no LLM required for graph construction, reasoning, or provenance.

⚠️ System-level explainability, not foundation-model explainability. Semantica does not expose or reconstruct what happens inside the LLM — its internal reasoning or chain-of-thought stays opaque, as it does for any external system. Semantica explains what's outside the model: the context and data fed in, the decision produced, its provenance, relevant relationships, applied policies, and the full execution trail.

Who it's for:

AI/ML platform teams shipping agents that make consequential decisions and need structured, queryable context built from fragmented raw data, not just a vector index
Data platform teams on Databricks or Snowflake who need to turn tables already sitting in Unity Catalog or a Snowflake warehouse into a governed, lineage-tracked knowledge graph, without exporting that data to a third-party SaaS first
Compliance, risk, and audit teams who need a straight answer to "why did the AI do that?" in a format a regulator will actually accept
Regulated enterprises (finance, healthcare, legal, government, defense) that can't ship a black box, and can't send their data to someone else's SaaS to get one
Platform and infra engineers who want the KG, reasoning, and provenance stack self-hosted and swappable, not locked to one vendor's backend
Data and knowledge engineers building a KG from messy, multi-source data: entities and relationships get extracted, conflicting or contradictory facts are flagged instead of silently overwritten, and duplicates are merged before they turn into noise

Quick Start · Architecture · What You Get · Why Semantica · Decision Intelligence · Context Graphs · Recipe: Audit Trail · Module Reference · Integrations · CLI · Performance · Install

Context Graphs: A structured, queryable graph of everything your agent knows, decides, and reasons about
Decision Intelligence: Every decision is a first-class object: traceable, searchable by precedent, and causally linked
AI Governance & Ontology: SHACL constraints, conflict detection, compliance rules, OWL generation, and SKOS vocabulary management with a visual editor
Full Auditability: W3C PROV-O provenance on every fact, with audit trails exportable to JSON, CSV, or RDF
Deterministic Reasoning: Forward chaining, Rete network, Datalog, and SPARQL with fully explainable paths, not black boxes
Knowledge Pipeline: Multi-source ingestion, entity-aware chunking, NER/relation/event extraction, and knowledge graph construction, with semantic deduplication and provenance-preserving merges throughout
Enterprise Data Platforms: Native connectors for Databricks (Unity Catalog + Delta Lake, PAT/OAuth M2M auth, catalog/schema/table/lineage introspection) and Snowflake (warehouse/database/schema, key-pair and OAuth auth), so tables already living in your lakehouse or warehouse become graph nodes with provenance, not another export/import hop
Graph Analytics: Centrality, community detection, link prediction, and shortest-path queries over the graph you just built
Polyglot Graph Storage: Native RDF (embedded Oxigraph, Blazegraph, Apache Jena, Eclipse RDF4J via SPARQL) and Labeled Property Graphs (Neo4j, FalkorDB, Apache AGE, AWS Neptune via Cypher), plus vector stores, all swappable without touching your code
Visualization: Explore any graph, ontology, or timeline in an interactive browser workbench
Drop-in Integrations: Native Agno and CrewAI support, a full-featured MCP server, a comprehensive CLI, a REST API, and plugins across major editors

| Vector DB + RAG | Plain LLM Memory | Semantica
---|---|---|---
Recall method | Embedding similarity | Token window | Graph traversal + semantic search
Decision history | Not stored | Not stored | First-class queryable objects
Provenance | None | None | W3C PROV-O, source-linked
Reasoning | None | Black box | Forward chain, Rete, Datalog, SPARQL
Conflict detection | Silent overwrite | Silent overwrite | Detected, flagged, resolved
Time travel | No | No | Point-in-time graph snapshots
Compliance export | None | None | PROV-O, SHACL, OWL, RDF
Policy enforcement | None | None | Built-in rule engine + SHACL
Entity resolution | No | No | Blocking + semantic deduplication
Multi-agent context | Separate per agent | Separate per agent | Single shared intelligence layer

Semantica complements your existing stack rather than replacing it. Keep your LLM, vector store, and agent framework exactly as they are; Semantica 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.

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Every agent decision becomes a queryable, auditable knowledge node
decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

# Ask "why did this happen?" and get a real, structured answer
chain     = graph.trace_decision_chain(decision_id)       # full causal ancestry
similar   = graph.find_similar_decisions("cloud vendor", max_results=5)  # precedents
impact    = graph.analyze_decision_impact(decision_id)    # downstream influence map
compliant = graph.check_decision_rules({"category": "vendor_selection"})  # policy gate

Verify your install in 5 seconds:

semantica doctor
# Python 3.11.9         pass
# semantica 0.6.6       pass
# faiss vector store    pass
# Config file           pass    ~/.semantica/config.yaml

Semantica is a real end-to-end pipeline, not a single library with a marketing name. Every stage below is a shipping module, independently importable:

Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
   → Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
   → Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI

Ingest: files, web, databases, enterprise data platforms (Databricks, Snowflake), cloud (Google Drive, Elasticsearch), streams (Kafka, Kinesis), Git, email, MCP
Parse → Normalize → Split: document parsing, text/entity/date normalization, GraphRAG-native entity-aware chunking
Extract → Conflict Detection → Deduplication: NER, relations, events, triplets; conflicting facts flagged and resolved before they merge
Knowledge Graph: GraphBuilder constructs the graph; bi-temporal facts and full graph analytics (centrality, communities, link prediction) run on top of it
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
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
Outputs: export (RDF, OWL, Parquet, Cypher, JSON-LD), interactive visualization, and access via REST API, MCP server, or CLI

→Full Mermaid diagrams for the pipeline and the decision intelligence lifecycle

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.

In Semantica, 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.

record_decision()             → stored as a graph node with full structured context
add_causal_relationship()     → linked to upstream causes and downstream effects
find_similar_decisions()      → semantic precedent search across all past decisions
trace_decision_chain()        → full causal ancestry back to root causes
analyze_decision_impact()     → downstream influence map - everything this decision affected
check_decision_rules()        → policy compliance gate against configurable rule sets
export / audit trail          → W3C PROV-O, CSV, or JSON for regulator submission



from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

# Record decisions with full structured context
app_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"},
)
uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Underwriting review for A-7291",
    reasoning="DTI within policy; clean 36-month credit history",
    outcome="approved",
    confidence=0.94,
)
rate_id = graph.record_decision(
    category="interest_rate",
    scenario="Rate assignment for approved loan A-7291",
    outcome="rate_set_8.9pct",
    reasoning="Prime + 2.4% based on risk tier B2",
    confidence=0.99,
)

# Build the auditable causal chain - relationship_type must be one of
# CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(app_id, uw_id,   relationship_type="CAUSED")
graph.add_causal_relationship(uw_id,  rate_id, relationship_type="INFLUENCED")

# Query the intelligence
chain     = graph.trace_decision_chain(rate_id)
similar   = graph.find_similar_decisions("personal loan approval, 31% DTI", max_results=5)
impact    = graph.analyze_decision_impact(uw_id)
compliant = graph.check_decision_rules({"category": "loan_underwriting", "confidence": 0.94})
insights  = graph.get_decision_insights()

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.

from semantica.context import ContextGraph, AgentContext
from semantica.vector_store import VectorStore

graph = ContextGraph(advanced_analytics=True)

# Add nodes with typed properties
graph.add_node("acme_corp",    "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen",   "Person",       name="Alice Chen", role="CTO")
graph.add_node("contract_001", "Contract",     value=2_400_000, currency="USD")

# Add typed, weighted edges (extra kwargs become edge metadata)
graph.add_edge("alice_chen", "acme_corp",    edge_type="works_for",  since="2019-03-01")
graph.add_edge("acme_corp",  "contract_001", edge_type="party_to",   signed="2024-01-15")

# BFS traversal - hop through the graph from any node
neighbors = graph.get_neighbors("acme_corp", hops=2)

# Point-in-time snapshot - the graph as it existed on any past date
snapshot  = graph.state_at("2024-01-01")

# AgentContext - high-level API for agent memory workflows
vs  = VectorStore(backend="faiss")
ctx = AgentContext(vector_store=vs, knowledge_graph=graph)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
retrieved = ctx.retrieve("who approved the Acme contract?")

Why graph over embeddings: traversal finds connections embeddings miss (a person 3 hops from a contract); every node carries provenance so you can always ask "where did this come from?" ; conflicts are flagged before they corrupt your knowledge base; point-in-time snapshots let you replay history without reprocessing.

Recipe: Audit Trail for a Regulated Decision

The flagship pattern: record a causally-linked decision chain, attach provenance to every entity, and export a regulator-ready audit trail.

from semantica.context import ContextGraph
from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

graph = ContextGraph(advanced_analytics=True)
prov  = ProvenanceManager(storage_path="./audit.db")

# Record the decision chain
d1 = graph.record_decision(
    category="drug_interaction_check", scenario="Patient P-4821: warfarin + amiodarone co-prescribed",
    reasoning="Amiodarone potentiates warfarin's anticoagulant effect", outcome="flag_for_review", confidence=0.91,
)
d2 = graph.record_decision(
    category="dosage_adjustment", scenario="INR monitoring plan for P-4821",
    reasoning="Reduce warfarin dose per interaction severity; recheck INR in 5 days", outcome="dose_reduced_30pct", confidence=0.87,
)
# relationship_type must be one of CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(d1, d2, relationship_type="CAUSED")

# Track provenance for every entity
prov.track_entity("patient_P4821", source="ehr/medication_orders_2024.json",
                  metadata={"extractor": "NamedEntityRecognizer"})

# Export W3C PROV-O for regulator submission - to_kg_dict() is the official
# adapter that emits the {"entities": [...], "relationships": [...]} /
# source_id shape RDFExporter expects, so no manual field mapping is needed
kg = graph.to_kg_dict()
RDFExporter().export(kg, "audit_trail.ttl", format="turtle")

More recipes (GraphRAG pipelines, an AML rules engine, ontology-to-KG in one pass) are in More Recipes below.

Every module below is independently importable, with working code samples verified against the current source tree; use one or all of them.

Module	What it does
`semantica.ingest`	Files, web, databases, APIs, streams, email, Git, Parquet, Databricks, Snowflake, MCP
`semantica.semantic_extract`	NER, relation extraction, event detection, triplet generation
`semantica.kg`	Graph construction, centrality, communities, link prediction
`semantica.reasoning`	Forward chaining, Rete, Datalog, SPARQL, fully explainable
`semantica.vector_store`	FAISS, Qdrant, Weaviate, Milvus, Pinecone, PgVector, hybrid search
`semantica.split`	Entity-aware, relation-aware, ontology-aware chunking for GraphRAG
`semantica.provenance`	W3C PROV-O lineage on every fact
`semantica.ontology`	OWL generation, SHACL validation, SKOS vocabularies
`semantica.conflicts`	Detect and resolve conflicting facts across sources
`semantica.deduplication`	Entity resolution at scale
`semantica.normalize`	Text, entity, date, and number normalization; dataset cleaning
`semantica.pipeline`	Declarative, parallel pipeline DSL for ingest → extract → build → export
`semantica.export`	RDF, OWL, Parquet, Cypher, JSON-LD
`semantica.visualization`	Force-directed graphs, ontology hierarchies, temporal dashboards
Temporal Intelligence	Bi-temporal facts, Allen interval algebra, time travel
Multi-Agent (Agno)	One shared context graph across every agent on a team

↓ ExpandModule Reference below for every module's working example, or jump to More Recipes, the full Integrations matrix, MCP tool list, and REST endpoints.

Expand any module below for its runnable example.

semantica.ingest : Multi-Source Ingestion

Ingest from files, web, databases, APIs, streams, email, Git repos, Parquet, Databricks, Snowflake, or MCP servers, all through a unified interface.

from semantica.ingest import FileIngestor, WebIngestor, ParquetIngestor, DBIngestor

# Ingest an entire directory of contracts (PDF, DOCX, HTML, TXT)
docs = FileIngestor().ingest_directory("./contracts/", recursive=True)

# Ingest live web content with robots.txt compliance
pages = WebIngestor().ingest_url("https://example.com/reports/annual-2024.html")

# Ingest structured data from Parquet with Snappy compression
records = ParquetIngestor().ingest("./data/transactions.parquet")

# Ingest from a SQL database - specify which tables to pull
rows = DBIngestor().ingest_database(
    connection_string="postgresql://user:pass@localhost/mydb",
    include_tables=["customer_events"],
    max_rows_per_table=50_000,
)


# Enterprise data platforms - pull tables straight out of your lakehouse
# or warehouse, with lineage, instead of exporting to CSV first
from semantica.ingest import DatabricksIngestor, SnowflakeIngestor

# pip install "semantica[db-databricks]"
databricks = DatabricksIngestor(
    host="https://adb-xxx.azuredatabricks.net",
    token="dapi-xxxxxxxx",              # or client_id/client_secret for OAuth M2M
    http_path="/sql/1.0/warehouses/xxxxxxxx",
    catalog="main",
)
customers    = databricks.ingest_table("customers", limit=10_000)
sales        = databricks.ingest_query("SELECT * FROM sales WHERE region = 'EMEA'")
table_lineage = databricks.get_table_lineage("customers", catalog="main", schema="default")  # Unity Catalog lineage

# pip install semantica[db-snowflake]
snowflake = SnowflakeIngestor(
    account="myaccount",
    user="myuser",
    password="mypassword",              # or private_key=... for key-pair; use authenticator="oauth", token=... for OAuth
    warehouse="COMPUTE_WH",
    database="MYDB",
)
orders = snowflake.ingest_table("ORDERS", limit=10_000)

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.

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 · Git repositories · Email (IMAP/POP3) · Message streams (Kafka, RabbitMQ, Kinesis, Pulsar) · MCP resources · Apache Arrow/Feather/IPC (ArrowIngestor)

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 semantica.ingest namespace yet — import them directly: from semantica.ingest.duckdb_ingestor import DuckDBIngestor.

semantica.semantic_extract : NER, Relations, Events, Triplets

Extract structured knowledge from raw text in one pass.

from semantica.semantic_extract import (
    NamedEntityRecognizer,
    RelationExtractor,
    EventDetector,
    TripletExtractor,
)

text = """
Anthropic CEO Dario Amodei announced a $7.3B Series E funding round in partnership
with Google and Spark Capital, valuing the company at $61.5B as of Q4 2024.
"""

# Named entity recognition with confidence thresholding
ner = NamedEntityRecognizer(confidence_threshold=0.7)
entities = ner.extract_entities(text)
# → [Entity(name="Dario Amodei", type="PERSON"), Entity(name="Anthropic", type="ORG"),
#    Entity(name="Google", type="ORG"), Entity(name="$7.3B", type="MONEY"), ...]

# Relationship extraction - bidirectional support
rel_extractor = RelationExtractor(confidence_threshold=0.6, bidirectional=True)
relations = rel_extractor.extract_relations(text, entities=entities)
# → [Relation(subject="Dario Amodei", predicate="ceo_of", object="Anthropic"),
#    Relation(subject="Anthropic", predicate="raised", object="$7.3B Series E"), ...]

# Event detection with temporal processing
events = EventDetector(extract_participants=True, extract_time=True).detect_events(text)
# → [Event(type="FUNDING", participants=["Anthropic","Google","Spark Capital"],
#          amount="$7.3B", date="Q4 2024")]

# RDF triplets with optional provenance metadata
triplets = TripletExtractor(include_temporal=True, include_provenance=True).extract_triplets(text)
# → [("Anthropic", "valuation", "$61.5B"), ("Dario Amodei", "is_ceo_of", "Anthropic"), ...]

Batch processing across many documents uses ner.process_batch([...]), not a per-call extract_entities_batch on the facade class.

semantica.kg : Knowledge Graph Construction & Analysis

Build a production knowledge graph from documents and run graph algorithms over it.

from semantica.ingest import FileIngestor
from semantica.kg import (
    GraphBuilder,
    GraphAnalyzer,
    CentralityCalculator,
    CommunityDetector,
    PathFinder,
    LinkPredictor,
    BiTemporalFact,
)
from datetime import datetime

# Build KG - merge duplicate entities, track temporal edges
sources = FileIngestor().ingest_directory("./contracts/", recursive=True)
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)

# Graph analytics
analyzer    = GraphAnalyzer()
analysis    = analyzer.analyze_graph(kg)             # full graph metrics

centrality  = CentralityCalculator()
degree      = centrality.calculate_degree_centrality(kg)    # most-connected entities
betweenness = centrality.calculate_betweenness_centrality(kg)

communities = CommunityDetector().detect_communities(kg, method="louvain")  # natural clusters
path        = PathFinder().find_shortest_path(kg, "alice_chen", "contract_001")
predictions = LinkPredictor().predict_links(kg, top_k=10)   # relationship predictions

# Bi-temporal facts - track valid time vs. recorded time independently
fact = BiTemporalFact(
    valid_from=datetime(2024, 3, 1),
    valid_until=datetime(2025, 1, 1),
    recorded_at=datetime(2024, 3, 5),
)

semantica.reasoning : Forward Chaining, Rete, Datalog, SPARQL

Run explainable rule-based inference, not a black box.

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType

rete = ReteEngine()
rete.build_network([
    Rule(
        rule_id="aml_flag",
        name="Flag high-risk transactions",
        conditions=[
            {"field": "amount",  "operator": ">",  "value": 10_000},
            {"field": "country", "operator": "in", "value": ["IR", "KP", "SY"]},
        ],
        conclusion="flag_for_compliance_review",
        rule_type=RuleType.IMPLICATION,
    ),
    Rule(
        rule_id="velocity_check",
        name="Flag rapid sequential transfers",
        conditions=[
            {"field": "transfers_in_1h", "operator": ">", "value": 5},
            {"field": "total_amount",    "operator": ">", "value": 50_000},
        ],
        conclusion="flag_velocity_breach",
        rule_type=RuleType.IMPLICATION,
    ),
])

rete.add_fact(Fact("tx_001", "transaction", [{"amount": 15_000, "country": "IR"}]))
flagged = rete.match_patterns()
# → [{"rule": "aml_flag", "matched_facts": ["tx_001"], "conclusion": "flag_for_compliance_review"}]

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.

# Recursive Datalog - natural language for graph queries
from semantica.reasoning import DatalogReasoner

engine = DatalogReasoner()
engine.add_fact("parent(tom, bob)")
engine.add_fact("parent(bob, ann)")
engine.add_fact("parent(ann, pat)")
engine.add_rule("ancestor(X, Y) :- parent(X, Y).")
engine.add_rule("ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).")
ancestors = engine.query("ancestor(tom, ?X)")
# → [{"X": "bob"}, {"X": "ann"}, {"X": "pat"}]


# Explainable reasoning - trace the path, not just the answer
from semantica.reasoning import ExplanationGenerator, Reasoner

reasoner = Reasoner()
reasoner.add_fact("parent(tom, bob)")
reasoner.add_rule("ancestor(X, Y) :- parent(X, Y)")
result = reasoner.forward_chain()

explainer = ExplanationGenerator()
explanation = explainer.generate_explanation(result)
# → Explanation(conclusion="...", steps=[ReasoningStep(...)], justification=Justification(...))

semantica.vector_store : Hybrid & Filtered Semantic Search

Drop-in vector store with multiple backends, hybrid search, and decision-aware retrieval.

from semantica.vector_store import VectorStore, HybridSearch

# In-memory backend shown here: HybridSearch and explain_decision() work out of the box.
# Swap backend="qdrant" / "weaviate" / "milvus" / "pinecone" / "pgvector" / "faiss" once you
# scale past a single process — search() and store_decision() work identically on all of them.
vs = VectorStore(backend="inmemory", dimension=1536)

# Store a decision with scenario description and outcome
vs.store_decision(
    scenario="Personal loan A-7291, $85k income, 31% DTI, 3yr employment",
    outcome="approved",
    confidence=0.94,
    category="loan_underwriting",
)

# Semantic similarity search
results = vs.search(
    query="personal loan approval with low DTI",
    limit=10,
)

# Hybrid search - dense + sparse retrieval in one pass with RRF fusion
hs   = HybridSearch(vector_store=vs)
hits = hs.search("high-risk transactions 2024")

# Explain why a decision was retrieved
explanation = vs.explain_decision(results[0]["id"])

Backends: faiss · qdrant · weaviate · milvus · pinecone · pgvector · sqlite · inmemory

semantica.split : GraphRAG-Native Document Chunking

KG-aware splitting that preserves entity boundaries, relation triplets, and ontology concepts, essential for GraphRAG pipelines.

from semantica.split import TextSplitter, EntityAwareChunker, RelationAwareChunker

text = open("contracts/master_agreement.txt").read()

# Standard recursive chunking
chunks = TextSplitter(method="recursive", chunk_size=1000, chunk_overlap=200).split(text)

# Entity-aware chunking - never splits a named entity across chunks (GraphRAG)
chunks = TextSplitter(method="entity_aware", ner_method="llm", chunk_size=1000).split(text)

# Relation-aware chunking - preserves (subject, predicate, object) triplets intact
chunks = RelationAwareChunker(chunk_size=1000, preserve_triplets=True).chunk(text)

# Graph-based chunking - uses centrality to find natural community boundaries
chunks = TextSplitter(method="graph_based", chunk_size=1000).split(text)

# Hierarchical chunking - multi-level (section → paragraph → sentence)
chunks = TextSplitter(method="hierarchical", levels=["section", "paragraph"]).split(text)

Supported methods: recursive · token · sentence · paragraph · semantic_transformer · entity_aware · relation_aware · graph_based · ontology_aware · hierarchical · community_detection · centrality_based · llm

semantica.provenance : W3C PROV-O Lineage

Every fact is linked to its source. No black boxes, no mystery outputs.

from semantica.provenance import ProvenanceManager

prov = ProvenanceManager(storage_path="./provenance.db")

# Track where every entity came from
prov.track_entity(
    entity_id="acme_corp",
    source="contracts/acme_master_agreement_2024.pdf",
    metadata={"page": 1, "confidence": 0.97, "extractor": "NamedEntityRecognizer"},
)

# Track a relationship's provenance - entity linkage travels in metadata
prov.track_relationship(
    relationship_id="alice_works_for_acme",
    source="hr_records/employees_q1_2024.csv",
    metadata={"source_entity_id": "alice_chen", "target_entity_id": "acme_corp"},
)

# Answer "where did this come from?"
lineage = prov.get_lineage("acme_corp")
trail   = prov.trace_lineage("alice_chen")   # full ancestor chain
entry   = prov.get_provenance("acme_corp")

semantica.ontology : OWL Generation, SHACL Validation

Generate ontologies from data, validate shapes, and manage your vocabulary.

from semantica.ontology import OntologyGenerator, OntologyValidator

data = {
    "entities": [
        {"id": "acme_corp",  "type": "Organization", "industry": "SaaS", "founded": 2012},
        {"id": "alice_chen", "type": "Person",        "role": "CTO",     "since": 2019},
    ],
    "relationships": [
        {"source": "alice_chen", "target": "acme_corp", "type": "works_for"},
    ],
}

gen       = OntologyGenerator(base_uri="https://semantica.dev/ontology/")
ontology  = gen.generate_ontology(data)
classes   = gen.infer_classes(data)
props     = gen.infer_properties(data, classes)
optimized = gen.optimize_ontology(ontology)

# Validate against SHACL shapes
validator = OntologyValidator()
report    = validator.validate(ontology)
# → ValidationResult(valid=True, consistent=True, satisfiable=True, errors=[], warnings=[])

semantica.conflicts : Conflict Detection & Resolution

Detect and resolve conflicting facts from multiple sources before they corrupt your knowledge base.

from semantica.conflicts import ConflictDetector, ConflictResolver, SourceTracker

entities_from_source_a = [
    {"id": "alice_chen", "role": "CTO",   "salary": 250_000, "start_date": "2019-03-01"},
]
entities_from_source_b = [
    {"id": "alice_chen", "role": "VP Eng", "salary": 275_000, "start_date": "2019-03-01"},
]

# Detect all conflict types: value, type, relationship, temporal, logical
detector   = ConflictDetector()
conflicts  = detector.detect_conflicts(entities_from_source_a + entities_from_source_b)
# → [Conflict(entity="alice_chen", field="role",   values=["CTO","VP Eng"], severity="HIGH"),
#    Conflict(entity="alice_chen", field="salary",  values=[250000,275000],   severity="MEDIUM")]

# Resolve using multiple strategies
resolver = ConflictResolver()
resolved = resolver.resolve_conflicts(conflicts, strategy="credibility_weighted")  # weighted by source trust
resolved = resolver.resolve_conflicts(conflicts, strategy="most_recent")          # prefer most recent
resolved = resolver.resolve_conflicts(conflicts, strategy="voting")               # majority wins

# Track source credibility over time
tracker = SourceTracker()
tracker.register_source("source_a", source_type="document", credibility_score=0.85)
tracker.register_source("source_b", source_type="document", credibility_score=0.72)

semantica.deduplication : Entity Resolution at Scale

Block, cluster, and merge duplicates with semantic similarity.

from semantica.deduplication import DuplicateDetector, EntityMerger

entities = [
    {"id": "e1", "name": "Acme Corporation",  "domain": "acme.com"},
    {"id": "e2", "name": "Acme Corp.",         "domain": "acme.com"},
    {"id": "e3", "name": "ACME Corp",          "domain": "acme.co"},
    {"id": "e4", "name": "Globex Industries",  "domain": "globex.com"},
]

detector   = DuplicateDetector(similarity_threshold=0.75, use_clustering=True)
candidates = detector.detect_duplicates(entities)
groups     = detector.detect_duplicate_groups(entities)
# → DuplicateGroup(entities=["e1","e2","e3"], confidence=0.91, strategy="semantic+blocking")

merger  = EntityMerger(preserve_provenance=True)
ops     = merger.merge_duplicates(entities, strategy="keep_most_complete")
history = merger.get_merge_history()

semantica.normalize : Data Normalization & Cleaning

Standardize text, entities, dates, numbers, and encodings before building your knowledge graph.

from semantica.normalize import (
    TextNormalizer,
    EntityNormalizer,
    DateNormalizer,
    NumberNormalizer,
    DataCleaner,
)

# Unicode, whitespace, casing, HTML tags, smart quotes
text  = TextNormalizer().normalize("  Acme Corp.'s Q4 report...  ")
# → "Acme Corp.'s Q4 report..."

# Alias resolution + entity disambiguation with confidence scores
canonical = EntityNormalizer().normalize_entity("ACME Corp.")
# → NormalizedEntity(canonical="Acme Corporation", type="Organization", confidence=0.91)

# Natural language date parsing with timezone conversion
dt    = DateNormalizer().normalize_date("3 weeks ago")
# → datetime(2026, 7, 1, tzinfo=UTC)

# Unit conversion and currency normalization
price = NumberNormalizer().normalize_number("$1.25M USD")
# → NormalizedNumber(value=1_250_000, currency="USD")

# Deduplicate, validate, and impute missing values across a dataset
clean = DataCleaner().clean_data(records, remove_duplicates=True, handle_missing=True)

semantica.pipeline : Pipeline DSL

Compose ingestion, extraction, and graph-building into a declarative, parallel pipeline.

from semantica.pipeline import PipelineBuilder, ExecutionEngine

builder = PipelineBuilder()

# add_step() returns the created PipelineStep, not the builder, so these don't chain
builder.add_step("ingest",      step_type="ingest",           source="./contracts/", recursive=True)
builder.add_step("extract",     step_type="ner_extract")
builder.add_step("relations",   step_type="relation_extract")
builder.add_step("build_kg",    step_type="kg_build",         merge_entities=True)
builder.add_step("deduplicate", step_type="deduplicate",      threshold=0.75)
builder.add_step("export",      step_type="export",           format="turtle", output="kg.ttl")

# connect_steps() and set_parallelism() return the builder, so these do chain
pipeline = (
    builder
    .connect_steps("ingest",      "extract")
    .connect_steps("extract",     "relations")
    .connect_steps("relations",   "build_kg")
    .connect_steps("build_kg",    "deduplicate")
    .connect_steps("deduplicate", "export")
    .set_parallelism(4)
    .build(name="contracts_pipeline")
)

engine   = ExecutionEngine()
result   = engine.execute_pipeline(pipeline)
status   = engine.get_pipeline_status(pipeline.name)
progress = engine.get_progress(pipeline.name)

Temporal Intelligence : Bi-Temporal Graphs & Time Travel

Track when facts were true in the world vs. when they were recorded , and query either axis.

from semantica.context import ContextGraph
from semantica.kg import (
    BiTemporalFact,
    TemporalGraphQuery,
    TemporalNormalizer,
)
from datetime import datetime

graph = ContextGraph(advanced_analytics=True)
graph.add_node("alice_chen", "Person",       role="VP Engineering")
graph.add_node("acme_corp",  "Organization", valuation=1_200_000_000)

# A temporally-bounded edge - valid_from/valid_until define when it held true
graph.add_edge(
    "alice_chen", "acme_corp", edge_type="works_for",
    valid_from="2024-03-01T00:00:00", valid_until="2025-01-01T00:00:00",
)

# Point-in-time snapshots - replay history without reprocessing
snapshot_2023 = graph.state_at("2023-06-01")
snapshot_2024 = graph.state_at("2024-01-01")

# Bi-temporal facts - valid_time is when true in the world;
# recorded_at is when you learned about it
fact = BiTemporalFact(
    valid_from=datetime(2024, 3, 1),
    valid_until=datetime(2025, 1, 1),
    recorded_at=datetime(2024, 3, 5),
)

# Query facts valid within a time window - to_kg_dict() is the official
# adapter that emits {"entities", "relationships"} with source_id/target_id
# keys, the shape query_time_range() expects (no manual mapping required)
kg = graph.to_kg_dict()

tq = TemporalGraphQuery()
facts_in_window = tq.query_time_range(
    kg, query="valid_facts", start_time="2024-01-01", end_time="2024-12-31"
)

# Normalize natural language temporal expressions - returns a (start, end) range
norm = TemporalNormalizer()
start, end = norm.normalize("last quarter")

semantica.export : RDF, OWL, Parquet, Cypher, JSON-LD

Export to any format required by regulators, graph databases, or downstream systems.

from semantica.export import (
    RDFExporter,
    JSONExporter,
    ParquetExporter,
    LPGExporter,
    ReportGenerator,
)

kg = {"entities": [...], "relationships": [...]}

rdf = RDFExporter()
turtle_str = rdf.export_to_rdf(kg, format="turtle")     # returns string
jsonld_str = rdf.export_to_rdf(kg, format="json-ld")

rdf.export(kg, "kg_audit.ttl",    format="turtle")
rdf.export(kg, "kg_audit.jsonld", format="json-ld")
rdf.export(kg, "kg_audit.nt",     format="n-triples")

# Columnar analytics - Snappy-compressed Parquet (writes kg_snapshot_entities.parquet
# and kg_snapshot_relationships.parquet)
ParquetExporter(compression="snappy").export_knowledge_graph(kg, "kg_snapshot")

# JSON knowledge graph
JSONExporter().export_knowledge_graph(kg, "kg.json")

# Neo4j / Memgraph Cypher statements for graph database import
LPGExporter().export(kg, "kg_import.cypher")

# Human-readable HTML report
ReportGenerator().generate_report(
    {"title": "KG Audit Report", "summary": "Weekly ingestion summary", "metrics": {"entities": len(kg["entities"])}},
    file_path="audit_report.html",
    format="html",
)

semantica.visualization : Interactive Graph Workbench

Render force-directed graphs, community maps, ontology hierarchies, and temporal dashboards.

from semantica.visualization import (
    KGVisualizer,
    OntologyVisualizer,
    EmbeddingVisualizer,
    TemporalVisualizer,
)
import numpy as np

kg = {"entities": [...], "relationships": [...]}

# Interactive force-directed graph (opens in browser)
viz = KGVisualizer(layout="force", color_scheme="default")
viz.visualize_network(kg, output="interactive", file_path="kg.html")
viz.visualize_communities(kg, communities, output="interactive")
viz.visualize_centrality(kg, centrality, centrality_type="degree")
viz.visualize_entity_types(kg, output="html", file_path="entity_types.html")

# Ontology class hierarchy
OntologyVisualizer().visualize_hierarchy(ontology, output="interactive")

# 2D embedding projection (UMAP / t-SNE / PCA)
EmbeddingVisualizer().visualize_2d_projection(
    embeddings=np.array([...]),
    labels=["entity_a", "entity_b"],
    method="umap",
)

# Timeline scrubber - watch the graph evolve
TemporalVisualizer().visualize_timeline(kg, output="interactive")

Multi-Agent Shared Context with Agno

One shared intelligence layer. All agents read and write to the same context graph.

# pip install semantica[agno]
from agno.agent import Agent
from agno.team import Team
from agno.models.anthropic import Claude
from semantica.context import ContextGraph
from semantica.vector_store import VectorStore
from integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit

shared = AgnoSharedContext(
    vector_store=VectorStore(backend="faiss"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
)

researcher = Agent(
    name="Researcher",
    model=Claude(id="claude-sonnet-4-5"),
    memory=shared.bind_agent("researcher"),
    tools=[AgnoKGToolkit(context=shared)],
)
analyst = Agent(
    name="Analyst",
    model=Claude(id="claude-sonnet-4-5"),
    memory=shared.bind_agent("analyst"),
    tools=[AgnoDecisionKit(context=shared)],
)

team = Team(agents=[researcher, analyst], mode="coordinate")
# Researcher's findings are instantly available to the Analyst - no copy, no sync

→ runnable notebooks in the cookbook, each self-contained and runnable in under 5 minutes

The flagship audit-trail recipe is above. Here are three more common patterns.

End-to-End GraphRAG Pipeline

from semantica.ingest import FileIngestor
from semantica.split import TextSplitter
from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor
from semantica.kg import GraphBuilder
from semantica.vector_store import VectorStore, HybridSearch
from semantica.context import AgentContext

# 1. Ingest
docs = FileIngestor().ingest_directory("./docs/", recursive=True)

# 2. Entity-aware chunking - never splits an entity across a chunk boundary
splitter = TextSplitter(method="entity_aware", chunk_size=1000)
chunks   = [splitter.split(doc["text"]) for doc in docs]

# 3. Extract entities and relations
ner      = NamedEntityRecognizer(confidence_threshold=0.7)
rel_ext  = RelationExtractor(confidence_threshold=0.6)
entities = [ner.extract_entities(chunk) for chunk_group in chunks for chunk in chunk_group]

# 4. Build KG
kg = GraphBuilder(merge_entities=True, enable_temporal=True).build(docs)

# 5. Hybrid retrieval
vs  = VectorStore(backend="inmemory")
ctx = AgentContext(vector_store=vs, knowledge_graph=kg)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="c1")

results = HybridSearch(vector_store=vs).search("who approved the renewal?")

AML Rules Engine

from semantica.reasoning import ReteEngine, Rule, Fact, RuleType

rete = ReteEngine()
rete.build_network([
    Rule(
        rule_id="sanctions_check",
        name="Flag sanctioned-country transactions",
        conditions=[
            {"field": "amount",  "operator": ">",  "value": 10_000},
            {"field": "country", "operator": "in", "value": ["IR", "KP", "SY", "CU"]},
        ],
        conclusion="flag_for_compliance_review",
        rule_type=RuleType.IMPLICATION,
    ),
])

# Run the rule across a batch of incoming transactions, not just one
for tx in [
    Fact("tx_101", "transaction", [{"amount": 25_000, "country": "IR"}]),
    Fact("tx_102", "transaction", [{"amount": 4_500,  "country": "DE"}]),
    Fact("tx_103", "transaction", [{"amount": 60_000, "country": "KP"}]),
]:
    rete.add_fact(tx)

flagged = rete.match_patterns()

Same condition-matcher caveat as above applies — validate against your rule set before production use.

Ontology-to-Knowledge-Graph in One Pass

from semantica.ingest import FileIngestor
from semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor
from semantica.kg import GraphBuilder
from semantica.ontology import OntologyGenerator, OntologyValidator
from semantica.export import RDFExporter

sources   = FileIngestor().ingest_directory("./contracts/")
ner       = NamedEntityRecognizer(confidence_threshold=0.7)
entities  = ner.process_batch([s["text"] for s in sources])

kg  = GraphBuilder(merge_entities=True).build(sources)
gen = OntologyGenerator(base_uri="https://myco.dev/ontology/")
ont = gen.generate_ontology({"entities": entities[0], "relationships": []})

report = OntologyValidator().validate(ont)
if report.valid:
    RDFExporter().export({"entities": entities[0]}, "ontology.ttl", format="turtle")

Capability	Highlights
Context Graphs	Queryable graph of entities, decisions, relationships; causal links; cross-graph navigation
Decision Intelligence	`record_decision` · `trace_decision_chain` · `find_similar_decisions` · `analyze_decision_impact` · `check_decision_rules`
Temporal Intelligence	Point-in-time snapshots · Allen interval algebra (13 relations) · `TemporalNormalizer` · bi-temporal provenance
Distance Intelligence	N×N semantic distance matrices · ego-mode visualization · distance bands · embedding cache
Semantic Extraction	NER · relation extraction · event detection · triplet generation · coreference
Reasoning Engines	Forward chaining · Rete · deductive · abductive · SPARQL · Datalog with explainable output
GraphRAG Chunking	Entity-aware · relation-aware · graph-based · ontology-aware · community-detection chunking
Conflict Detection	Value / type / relationship / temporal / logical conflicts · multiple resolution strategies
Provenance	W3C PROV-O · every fact traced to source · audit log export JSON/CSV/RDF
Ontology Hub	SHACL Studio · visual editor · cross-ontology alignments · health dashboard
Vector Store	FAISS · Pinecone · Weaviate · Qdrant · Milvus · PgVector · hybrid + filtered search
Graph Databases (LPG)	Neo4j · FalkorDB · Apache AGE · AWS Neptune
Triple Stores (RDF)	Oxigraph (embedded) · Blazegraph · Apache Jena · Eclipse RDF4J · unified `TripletStore` interface · SPARQL query & bulk load
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)
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 `semantica.llms` and LiteLLM

Benchmarks from v0.5.0 on a 118,000-node production graph:

Operation	Before	After	Improvement
Node search (118k nodes)	24 ms	0.004 ms	6,000× faster
Embedding cache hit	cold load	revision-based cache	10× throughput
Semantic deduplication	baseline	optimized candidate gen	6.98× faster
Candidate generation	baseline	blocking strategy	63.6% faster

Measured on a 118,000-node production graph (AMD EPYC, 64 GB RAM); the deduplication/candidate-generation figures are historical measurements recorded inCHANGELOG.md rather than an automated tests/ assertion. Results vary by hardware, dataset topology, and backend selection — run pytest tests/vector_store/test_performance_benchmarks.py -s to measure your own data.

Every capability is available from the terminal. The CLI ships with the package, no separate install required.

pip install semantica
semantica        # startup dashboard
semantica doctor # health check
semantica --help # full grouped command reference

Start with semantica, verify with doctor, build a graph, and explore the command groups from one terminal.

Command groups: ingest · parse · extract · kg · reason · decision · temporal · provenance · ontology · embed · deduplicate · validate · export · visualize · pipeline · server · explorer · mcp · doctor · shell · init · watch

→ Full CLI reference

Native plugin bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw; a full-featured MCP server for any MCP-compatible client; a comprehensive REST API; and first-class Agno and CrewAI support for agentic frameworks. Every major LLM provider is already supported via semantica.llms and LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.

MCP setup takes 30 seconds — see MCP Server below.

Full integrations matrix (editors, MCP clients, REST clients, agentic frameworks) Native Plugin Bundle	MCP Server + Plugin

Claude Code
Skills · agents · hooks
Cursor
Skills · agents
Codex CLI
Skills · agents
Windsurf
plugin
Cline
plugin
Continue
plugin
VS Code
plugin
OpenClaw
MCP + plugin
MCP Server	REST API

Claude Desktop
MCP server
GitHub Copilot
REST API
Roo Code
REST API
Goose
REST API
Kilo Code
REST API
Aider
REST API
Amazon Q
REST API
Zed
REST API
Native Integration

Agno
First-class · pip install semantica[agno] |
CrewAI
First-class · pip install semantica[crewai]
Already Supported via REST API & MCP

LangChain
REST API · MCP |
LangGraph
REST API · MCP |
LlamaIndex
REST API · MCP |
AutoGen
REST API · MCP |
OpenAI Agents
REST API · MCP |
Google ADK
REST API · MCP
Native SDK Integration (Coming Soon)

LangChain
Dedicated toolkit |
LlamaIndex
Dedicated toolkit |
AutoGen
Dedicated toolkit |
OpenAI Agents
Dedicated toolkit |
Google ADK
Dedicated toolkit

Connect any MCP-compatible client (Claude Desktop, Windsurf, Cline, VS Code) in 30 seconds:

python -m semantica.mcp_server
# or via the installed entry point
semantica-mcp


{
  "mcpServers": {
    "semantica": { "command": "python", "args": ["-m", "semantica.mcp_server"] }
  }
}

Tools exposed over MCP:

Tool	What it does
`extract_entities`	NER on any text
`extract_relations`	Relation extraction
`record_decision`	Persist a decision node
`query_decisions`	Search decision history
`find_precedents`	Semantic precedent lookup
`get_causal_chain`	Full causal ancestry
`add_entity`	Add a KG node
`add_relationship`	Add a KG edge
`run_reasoning`	Execute rule set
`get_graph_analytics`	Centrality, communities
`export_graph`	Export to RDF/JSON/Parquet
`get_graph_summary`	Graph statistics

# Start the backend
python -m semantica.server   # port 8000

# Extract entities & relations via REST
curl -X POST http://localhost:8000/api/enrich/extract \
  -H "Content-Type: application/json" \
  -d '{"text": "Apple CEO Tim Cook announced record earnings."}'

# List recorded decisions
curl "http://localhost:8000/api/decisions?category=vendor_selection"

# Query the knowledge graph
curl "http://localhost:8000/api/graph/node/acme_corp/neighbors?depth=2"

REST endpoints span: enrich (extract) · graph · decisions · reasoning · provenance · ontology · embeddings · search · export · pipeline · temporal · deduplication

Domain skills: extract · ingest · query · ontology · validate · deduplicate · embed · reason · decision · causal · temporal · provenance · policy · explain · export · change · visualize

Specialized agents: kg-assistant · decision-advisor · explainability

Bundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw in plugins/.

A browser-based graph workbench. Pan and zoom live graphs, scrub the timeline, review every decision's causal chain, resolve duplicates, and author your ontology visually. Built on React 19 + Sigma.js.

Workspace	What you can do
Knowledge Graph	Live Sigma.js canvas with ForceAtlas2 layout, Ego Mode, semantic distance heatmap
Timeline	Scrub through temporal events and watch the graph evolve
Decisions	Browse the causal chain behind every recorded decision
Registry	Live audit log of every graph mutation
Entity Resolution	Review and merge duplicates
Ontology Hub	SHACL Studio, visual editor, cross-ontology alignments, SKOS browser
Lineage	W3C PROV-O provenance visualization for any entity

Quickest way to start (no Node.js required):

pip install "semantica[explorer]"
semantica-explorer --graph my_graph.json
# Dashboard opens at http://127.0.0.1:8000

For contributor / dev-server setup: explorer/README.md: Local Setup Guide

Security release — upgrading is strongly recommended. Fixes for a privately disclosed batch of vulnerabilities spanning backup/restore, database export, outbound requests, and triplet-store backends, plus SSRF hardening across ingestion:

Tarball restore path traversal : semantica backup restore now validates every archive member for path containment and rejects symlink/hardlink escapes before extraction
Latent SQL injection inDataExporter.export_table_data(): table/schema names are now identifier-allowlisted and where/order_by fragments are blocklist-checked
DNS-rebinding TOCTOU in the shared SSRF guard : the resolved IP that passes validation is now the one the connection is pinned to, closing the check-then-use race (also closes the 100.64.0.0/10 CGNAT gap)
Stored XSS in HTML report generation and unvalidated SPARQL object IRIs in AnzoStore (SPARQL injection): both now escape/validate before interpolation
Authorization/Proxy-Authorization credential leakage across redirects, plus SSRF gaps inFeedIngestor/FeedMonitor, RepoIngestor, and the MCP/public-API ingest paths: all now route through the shared, redirect-safe SSRF guard
HTTP response header injection and an unbounded-memory DoS in the Explorer API, and a fastapi/python-multipart ReDoS (PYSEC-2024-38): floors raised, inputs sanitized, candidate pools capped

Also ships: first-class CrewAI integration (semantica[crewai], extraction/decision tools + a knowledge source), ContextGraph retraction and purge (GDPR-style erasure without a full clear()), a declared Semantica RDF vocabulary with deterministic entity/relationship IRIs (stable, diffable exports), and timezone-aware timestamps across export/ and provenance/.

→ Full release notes · Changelog

Built for High-Stakes Domains

Semantica is designed for environments where AI outputs must be explainable, auditable, and defensible, and where the data itself can't leave your infrastructure. Self-hostable with zero vendor lock-in, it's built as much for organizations handling confidential or classified data as for regulated industries chasing an audit trail:

Finance: Loan underwriting audit trails, fraud detection, AML compliance, regulatory risk knowledge graphs
Healthcare: Clinical decision support, drug interaction graphs, and patient safety audit trails
Legal: Evidence-backed research, contract analysis, case law reasoning, and privilege tracking
Government & Defense: Policy decision records, classified information governance, and regulatory reporting, fully self-hosted with no data leaving your perimeter
Law Enforcement: Case linkage, evidence provenance chains, and investigative knowledge graphs that hold up under legal scrutiny
Cybersecurity: Threat attribution, incident response timelines, and IOC provenance tracking
Autonomous Systems: Decision logs, safety validation, and explainable AI for certification

⚠️ This is system-level explainability, not foundation-model explainability. Semantica does not expose, reconstruct, or explain what happens inside the LLM/foundation model — its internal reasoning or chain-of-thought stays opaque, as it does for any external system. What Semantica explains is outside the model: the context and data fed in, the decision produced, its provenance, the relevant relationships, the policies applied, and the full execution trail. In short, Semantica explains and audits what the AI system did, not the LLM's private internal reasoning.

pip install semantica           # core
pip install semantica[all]      # everything


pip install semantica[agno]                 # Agno multi-agent integration
pip install semantica[crewai]               # CrewAI integration
pip install semantica[llm-litellm]          # OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Bedrock, Ollama, DeepSeek, and more
pip install semantica[graph-neo4j]          # Neo4j graph store (LPG)
pip install semantica[graph-falkordb]       # FalkorDB graph store (LPG)
pip install semantica[graph-apache-age]     # Apache AGE graph store (LPG)
pip install semantica[graph-amazon-neptune] # AWS Neptune graph store (LPG)
pip install semantica[tripletstore-oxigraph] # Embedded in-memory/on-disk RDF store
# RDF triple stores (Blazegraph, Apache Jena, Eclipse RDF4J) need no extra:
# semantica.triplet_store talks SPARQL over HTTP using the core `requests` dependency
pip install semantica[vectorstore-qdrant]   # Qdrant vector store
pip install semantica[vectorstore-pinecone] # Pinecone vector store
pip install semantica[db-snowflake]         # Snowflake
pip install semantica[db-databricks]        # Databricks (SDK + SQL connector)
pip install semantica[ingest-parquet]       # Parquet / PyArrow
pip install semantica[ingest-arrow]        # Apache Arrow, Feather, IPC
pip install semantica[viz]                  # HTML interactive visualization
pip install semantica[watch]                # Directory file watcher
pip install semantica[explorer]             # Knowledge Explorer dashboard

For production deployments, use Docker or Kubernetes rather than a local pip install. Set SEMANTICA_SECRET_KEY, configure a persistent LPG graph store (Neo4j / FalkorDB / Apache AGE / AWS Neptune) and/or RDF triple store (Blazegraph / Apache Jena / Eclipse RDF4J), and point the vector store at a hosted backend (Qdrant / Pinecone). See ARCHITECTURE.md for the full deployment topology.

# From source
git clone https://github.com/semantica-agi/semantica.git
cd semantica && pip install -e ".[dev]" && pytest tests/

On-premises deployment · Private cloud · Custom domain implementations · SLA-backed support · Professional services for regulated industries (finance, healthcare, legal, government).

getsemantica.ai for enterprise solutions and pricing.

Community & Support

All contributions are welcome: bug fixes, features, tests, and documentation.

Fork the repo and create a branch
pip install -e ".[dev]"
Write tests alongside your changes (pytest tests/)
Open a PR and tag @KaifAhmad1 for review

See CONTRIBUTING.md for full guidelines.