English · Deutsch · Français · Español · Italiano · Português · العربية · اردو · हिन्दी · 中文 · 日本語 · 한국어

---

---

Most AI agents run on embeddings, not meaning: similarity scores with no structure, no relationships, and no way to explain why a result came back.

Semantica 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 semantica.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.

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."

[!NOTE]

System-level explainability, not foundation-model explainability. Semantica doesn't expose or reconstruct what happens inside the LLM: its internal reasoning stays opaque, like it does for any external system. Semantica explains what's outside the model: the context 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, not just a vector index
• 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
• Compliance, risk, and audit teams who need a straight answer to "why did the AI do that?" in a format a regulator accepts
• 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
• 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, where conflicting facts get flagged and duplicates get merged, not silently overwritten

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

---

What Semantica Gives You

• 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 vocabularies, all with a visual editor
• Full Auditability: W3C PROV-O provenance on every fact, 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 graph construction, with semantic dedup and provenance-preserving merges built in
• 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
• Graph Analytics: Centrality, community detection, link prediction, and shortest-path queries over the graph you just built
• 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
• Visualization: Explore any graph, ontology, or timeline in an interactive browser workbench
• Drop-in Integrations: Agno, CrewAI, and LangChain support, a full MCP server, a CLI, a REST API, and plugins across major editors

---

Why Semantica

| | 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.

---

Quick Start

pip install semantica

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

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 SEMANTICA_DISABLE_PROGRESS=1 to silence progress everywhere, or SEMANTICA_FORCE_PROGRESS=1 to keep it when stdout is redirected. SEMANTICA_DISABLE_PROGRESS takes precedence.

---

Architecture

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, SAP), 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

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()

---

Context Graphs

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

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.

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.

---

Explore the Platform

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, SAP, 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 |

↓ Expand Module Reference below for eve