{"slug": "an-open-source-knowledge-graph-for-traceable-ai-decisions", "title": "An open-source knowledge graph for traceable AI decisions", "summary": "Semantica, an open-source knowledge graph platform, provides deterministic reasoning, context graphs, and W3C PROV-O provenance to make AI decisions auditable and explainable, targeting regulated enterprises in finance, healthcare, and government. The platform, installable via pip, integrates with Databricks and Snowflake and requires no LLM for graph construction or reasoning.", "body_md": "Ingest your enterprise data, extract what matters, build a Context Graph and knowledge graph (KG), and run graph analytics and causal reasoning over all of it, with full decision provenance baked in. Explainable, traceable, and trustworthy by design.\n\n**Decision Intelligence · Context Management · Deterministic Reasoning · Ontology Management · Knowledge Modeling · End-to-End Traceability**\n\n**Open Source · Self-Hostable · Auditable · Governed · Zero Vendor Lock-In**\n\n**Polyglot Graph Storage · RDF & LPG Support · W3C Standards · Interoperable**\n\n```\npip install semantica\n```\n\nMost 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.\n\nSemantica sits underneath your LLM, vector store, and agent framework as a deterministic infrastructure layer: no LLM required for graph construction, reasoning, or provenance.\n\n**Who it's for:**\n\n**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\n\n** Quick Start** ·\n\n**·**\n\n[Architecture](#architecture)**·**\n\n[What You Get](#what-semantica-gives-you)**·**\n\n[Why Semantica](#why-semantica)**·**\n\n[Decision Intelligence](#decision-intelligence)**·**\n\n[Context Graphs](#context-graphs)**·**\n\n[Recipe: Audit Trail](#recipe-audit-trail-for-a-regulated-decision)**·**\n\n[Module Reference](#module-reference)**·**\n\n[Integrations](#integrations)**·**\n\n[CLI](#cli)**·**\n\n[Performance](#performance)\n\n[Install](#installation)**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 support, a full-featured MCP server, a comprehensive CLI, a REST API, and plugins across major editors\n\n| Vector DB + RAG | Plain LLM Memory | Semantica |\n|\n|---|---|---|---|\nRecall method |\nEmbedding similarity | Token window | Graph traversal + semantic search |\nDecision history |\nNot stored | Not stored | First-class queryable objects |\nProvenance |\nNone | None | W3C PROV-O, source-linked |\nReasoning |\nNone | Black box | Forward chain, Rete, Datalog, SPARQL |\nConflict detection |\nSilent overwrite | Silent overwrite | Detected, flagged, resolved |\nTime travel |\nNo | No | Point-in-time graph snapshots |\nCompliance export |\nNone | None | PROV-O, SHACL, OWL, RDF |\nPolicy enforcement |\nNone | None | Built-in rule engine + SHACL |\nEntity resolution |\nNo | No | Blocking + semantic deduplication |\nMulti-agent context |\nSeparate per agent | Separate per agent | Single shared intelligence layer |\n\nSemantica 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.\n\n```\npip install semantica\npython\nfrom semantica.context import ContextGraph\n\ngraph = ContextGraph(advanced_analytics=True)\n\n# Every agent decision becomes a queryable, auditable knowledge node\ndecision_id = graph.record_decision(\n    category=\"vendor_selection\",\n    scenario=\"Choose cloud provider for HIPAA workload\",\n    reasoning=\"AWS offers BAA, mature HIPAA tooling, and existing team expertise\",\n    outcome=\"selected_aws\",\n    confidence=0.93,\n)\n\n# Ask \"why did this happen?\" and get a real, structured answer\nchain     = graph.trace_decision_chain(decision_id)       # full causal ancestry\nsimilar   = graph.find_similar_decisions(\"cloud vendor\", max_results=5)  # precedents\nimpact    = graph.analyze_decision_impact(decision_id)    # downstream influence map\ncompliant = graph.check_decision_rules({\"category\": \"vendor_selection\"})  # policy gate\n```\n\n**Verify your install in 5 seconds:**\n\n```\nsemantica doctor\n# Python 3.11.9         pass\n# semantica 0.6.5       pass\n# faiss vector store    pass\n# Config file           pass    ~/.semantica/config.yaml\n```\n\nIf Semantica solves a real problem for you, a star helps others find it.\n\nSemantica is a real end-to-end pipeline, not a single library with a marketing name. Every stage below is a shipping module, independently importable:\n\n```\nSources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication\n   → Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG\n   → Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI\n```\n\n**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`\n\nconstructs 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\n\n**→ Full Mermaid diagrams for the pipeline and the decision intelligence lifecycle**\n\nDecision 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.\n\nIn 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()`\n\ncreates a permanent, structured record exportable as W3C PROV-O, the format most compliance frameworks accept for regulator submission.\n\n```\nrecord_decision()             → stored as a graph node with full structured context\nadd_causal_relationship()     → linked to upstream causes and downstream effects\nfind_similar_decisions()      → semantic precedent search across all past decisions\ntrace_decision_chain()        → full causal ancestry back to root causes\nanalyze_decision_impact()     → downstream influence map - everything this decision affected\ncheck_decision_rules()        → policy compliance gate against configurable rule sets\nexport / audit trail          → W3C PROV-O, CSV, or JSON for regulator submission\npython\nfrom semantica.context import ContextGraph\n\ngraph = ContextGraph(advanced_analytics=True)\n\n# Record decisions with full structured context\napp_id = graph.record_decision(\n    category=\"credit_application\",\n    scenario=\"Personal loan, $85k income, 31% DTI, 3yr employment\",\n    reasoning=\"Income meets threshold; employment stable; no adverse credit events\",\n    outcome=\"proceed_to_underwriting\",\n    confidence=0.88,\n    metadata={\"applicant_id\": \"A-7291\"},\n)\nuw_id = graph.record_decision(\n    category=\"loan_underwriting\",\n    scenario=\"Underwriting review for A-7291\",\n    reasoning=\"DTI within policy; clean 36-month credit history\",\n    outcome=\"approved\",\n    confidence=0.94,\n)\nrate_id = graph.record_decision(\n    category=\"interest_rate\",\n    scenario=\"Rate assignment for approved loan A-7291\",\n    outcome=\"rate_set_8.9pct\",\n    reasoning=\"Prime + 2.4% based on risk tier B2\",\n    confidence=0.99,\n)\n\n# Build the auditable causal chain - relationship_type must be one of\n# CAUSED, INFLUENCED, or PRECEDENT_FOR\ngraph.add_causal_relationship(app_id, uw_id,   relationship_type=\"CAUSED\")\ngraph.add_causal_relationship(uw_id,  rate_id, relationship_type=\"INFLUENCED\")\n\n# Query the intelligence\nchain     = graph.trace_decision_chain(rate_id)\nsimilar   = graph.find_similar_decisions(\"personal loan approval, 31% DTI\", max_results=5)\nimpact    = graph.analyze_decision_impact(uw_id)\ncompliant = graph.check_decision_rules({\"category\": \"loan_underwriting\", \"confidence\": 0.94})\ninsights  = graph.get_decision_insights()\n```\n\nA 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.\n\n``` python\nfrom semantica.context import ContextGraph, AgentContext\nfrom semantica.vector_store import VectorStore\n\ngraph = ContextGraph(advanced_analytics=True)\n\n# Add nodes with typed properties\ngraph.add_node(\"acme_corp\",    \"Organization\", name=\"Acme Corp\", industry=\"SaaS\")\ngraph.add_node(\"alice_chen\",   \"Person\",       name=\"Alice Chen\", role=\"CTO\")\ngraph.add_node(\"contract_001\", \"Contract\",     value=2_400_000, currency=\"USD\")\n\n# Add typed, weighted edges (extra kwargs become edge metadata)\ngraph.add_edge(\"alice_chen\", \"acme_corp\",    edge_type=\"works_for\",  since=\"2019-03-01\")\ngraph.add_edge(\"acme_corp\",  \"contract_001\", edge_type=\"party_to\",   signed=\"2024-01-15\")\n\n# BFS traversal - hop through the graph from any node\nneighbors = graph.get_neighbors(\"acme_corp\", hops=2)\n\n# Point-in-time snapshot - the graph as it existed on any past date\nsnapshot  = graph.state_at(\"2024-01-01\")\n\n# AgentContext - high-level API for agent memory workflows\nvs  = VectorStore(backend=\"faiss\")\nctx = AgentContext(vector_store=vs, knowledge_graph=graph)\nctx.store(\"Alice approved the Acme renewal in Q1 2024\", conversation_id=\"conv_001\")\nretrieved = ctx.retrieve(\"who approved the Acme contract?\")\n```\n\n**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.\n\nThe flagship pattern: record a causally-linked decision chain, attach provenance to every entity, and export a regulator-ready audit trail.\n\n``` python\nfrom semantica.context import ContextGraph\nfrom semantica.provenance import ProvenanceManager\nfrom semantica.export import RDFExporter\n\ngraph = ContextGraph(advanced_analytics=True)\nprov  = ProvenanceManager(storage_path=\"./audit.db\")\n\n# Record the decision chain\nd1 = graph.record_decision(\n    category=\"drug_interaction_check\", scenario=\"Patient P-4821: warfarin + amiodarone co-prescribed\",\n    reasoning=\"Amiodarone potentiates warfarin's anticoagulant effect\", outcome=\"flag_for_review\", confidence=0.91,\n)\nd2 = graph.record_decision(\n    category=\"dosage_adjustment\", scenario=\"INR monitoring plan for P-4821\",\n    reasoning=\"Reduce warfarin dose per interaction severity; recheck INR in 5 days\", outcome=\"dose_reduced_30pct\", confidence=0.87,\n)\n# relationship_type must be one of CAUSED, INFLUENCED, or PRECEDENT_FOR\ngraph.add_causal_relationship(d1, d2, relationship_type=\"CAUSED\")\n\n# Track provenance for every entity\nprov.track_entity(\"patient_P4821\", source=\"ehr/medication_orders_2024.json\",\n                  metadata={\"extractor\": \"NamedEntityRecognizer\"})\n\n# Export W3C PROV-O for regulator submission - RDFExporter expects\n# {\"entities\": [...], \"relationships\": [...]}, so map ContextGraph.to_dict()'s\n# {\"nodes\": [...], \"edges\": [...]} shape onto it first\ngraph_dict = graph.to_dict()\nkg = {\n    \"entities\": [{\"id\": n[\"id\"], \"type\": n[\"type\"], \"text\": n[\"content\"]} for n in graph_dict[\"nodes\"]],\n    \"relationships\": [\n        {\"source_id\": e[\"source\"], \"target_id\": e[\"target\"], \"type\": e[\"type\"]}\n        for e in graph_dict[\"edges\"]\n    ],\n}\nRDFExporter().export(kg, \"audit_trail.ttl\", format=\"turtle\")\n```\n\nMore recipes (GraphRAG pipelines, an AML rules engine, ontology-to-KG in one pass) are in ** More Recipes** below.\n\nEvery module below is independently importable, with working code samples verified against the current source tree; use one or all of them.\n\n| Module | What it does |\n|---|---|\n`semantica.ingest` |\n\n`semantica.semantic_extract`\n\n`semantica.kg`\n\n`semantica.reasoning`\n\n`semantica.vector_store`\n\n`semantica.split`\n\n`semantica.provenance`\n\n`semantica.ontology`\n\n`semantica.conflicts`\n\n`semantica.deduplication`\n\n`semantica.normalize`\n\n`semantica.pipeline`\n\n`semantica.export`\n\n`semantica.visualization`\n\n[Temporal Intelligence](#temporal-intelligence-bi-temporal-graphs--time-travel)[Multi-Agent (Agno)](#multi-agent-shared-context-with-agno)**↓ Expand Module Reference below** for every module's working example, or jump to\n\n[More Recipes](#more-recipes), the full\n\n[Integrations](#integrations)matrix,\n\n[MCP tool list](#mcp-server), and\n\n[REST endpoints](#rest-api).\n\nExpand any module below for its runnable example.\n\n`semantica.ingest`\n\n: Multi-Source Ingestion\n\n`semantica.ingest`\n\nIngest from files, web, databases, APIs, streams, email, Git repos, Parquet, Databricks, Snowflake, or MCP servers, all through a unified interface.\n\n``` python\nfrom semantica.ingest import FileIngestor, WebIngestor, ParquetIngestor, DBIngestor\n\n# Ingest an entire directory of contracts (PDF, DOCX, HTML, TXT)\ndocs = FileIngestor().ingest_directory(\"./contracts/\", recursive=True)\n\n# Ingest live web content with robots.txt compliance\npages = WebIngestor().ingest_url(\"https://example.com/reports/annual-2024.html\")\n\n# Ingest structured data from Parquet with Snappy compression\nrecords = ParquetIngestor().ingest(\"./data/transactions.parquet\")\n\n# Ingest from a SQL database - specify which tables to pull\nrows = DBIngestor().ingest_database(\n    connection_string=\"postgresql://user:pass@localhost/mydb\",\n    include_tables=[\"customer_events\"],\n    max_rows_per_table=50_000,\n)\n# Enterprise data platforms - pull tables straight out of your lakehouse\n# or warehouse, with lineage, instead of exporting to CSV first\nfrom semantica.ingest import DatabricksIngestor, SnowflakeIngestor\n\n# pip install \"semantica[db-databricks]\"\ndatabricks = DatabricksIngestor(\n    host=\"https://adb-xxx.azuredatabricks.net\",\n    token=\"dapi-xxxxxxxx\",              # or client_id/client_secret for OAuth M2M\n    http_path=\"/sql/1.0/warehouses/xxxxxxxx\",\n    catalog=\"main\",\n)\ncustomers    = databricks.ingest_table(\"customers\", limit=10_000)\nsales        = databricks.ingest_query(\"SELECT * FROM sales WHERE region = 'EMEA'\")\ntable_lineage = databricks.get_table_lineage(\"customers\", catalog=\"main\", schema=\"default\")  # Unity Catalog lineage\n\n# pip install semantica[db-snowflake]\nsnowflake = SnowflakeIngestor(\n    account=\"myaccount\",\n    user=\"myuser\",\n    password=\"mypassword\",              # or private_key=... for key-pair; use authenticator=\"oauth\", token=... for OAuth\n    warehouse=\"COMPUTE_WH\",\n    database=\"MYDB\",\n)\norders = snowflake.ingest_table(\"ORDERS\", limit=10_000)\n```\n\nSecurity Note:Never hardcode credentials (`token`\n\n,`password`\n\n,`private_key`\n\n) in production code; pass them via environment variables (e.g.,`DATABRICKS_TOKEN`\n\n,`SNOWFLAKE_PASSWORD`\n\n) or a secrets manager.\n\n**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`\n\n)\n\nDuckDB, Elasticsearch, Google Drive, HuggingFace, MongoDB, and Pandas ingestion also ship (`DuckDBIngestor`\n\n, `ElasticIngestor`\n\n, `GDriveIngestor`\n\n, `HuggingFaceIngestor`\n\n, `MongoIngestor`\n\n, `PandasIngestor`\n\n) but aren't re-exported from the top-level `semantica.ingest`\n\nnamespace yet — import them directly: `from semantica.ingest.duckdb_ingestor import DuckDBIngestor`\n\n.\n\n`semantica.semantic_extract`\n\n: NER, Relations, Events, Triplets\n\n`semantica.semantic_extract`\n\nExtract structured knowledge from raw text in one pass.\n\n```\nfrom semantica.semantic_extract import (\n    NamedEntityRecognizer,\n    RelationExtractor,\n    EventDetector,\n    TripletExtractor,\n)\n\ntext = \"\"\"\nAnthropic CEO Dario Amodei announced a $7.3B Series E funding round in partnership\nwith Google and Spark Capital, valuing the company at $61.5B as of Q4 2024.\n\"\"\"\n\n# Named entity recognition with confidence thresholding\nner = NamedEntityRecognizer(confidence_threshold=0.7)\nentities = ner.extract_entities(text)\n# → [Entity(name=\"Dario Amodei\", type=\"PERSON\"), Entity(name=\"Anthropic\", type=\"ORG\"),\n#    Entity(name=\"Google\", type=\"ORG\"), Entity(name=\"$7.3B\", type=\"MONEY\"), ...]\n\n# Relationship extraction - bidirectional support\nrel_extractor = RelationExtractor(confidence_threshold=0.6, bidirectional=True)\nrelations = rel_extractor.extract_relations(text, entities=entities)\n# → [Relation(subject=\"Dario Amodei\", predicate=\"ceo_of\", object=\"Anthropic\"),\n#    Relation(subject=\"Anthropic\", predicate=\"raised\", object=\"$7.3B Series E\"), ...]\n\n# Event detection with temporal processing\nevents = EventDetector(extract_participants=True, extract_time=True).detect_events(text)\n# → [Event(type=\"FUNDING\", participants=[\"Anthropic\",\"Google\",\"Spark Capital\"],\n#          amount=\"$7.3B\", date=\"Q4 2024\")]\n\n# RDF triplets with optional provenance metadata\ntriplets = TripletExtractor(include_temporal=True, include_provenance=True).extract_triplets(text)\n# → [(\"Anthropic\", \"valuation\", \"$61.5B\"), (\"Dario Amodei\", \"is_ceo_of\", \"Anthropic\"), ...]\n```\n\nBatch processing across many documents uses `ner.process_batch([...])`\n\n, not a per-call `extract_entities_batch`\n\non the facade class.\n\n`semantica.kg`\n\n: Knowledge Graph Construction & Analysis\n\n`semantica.kg`\n\nBuild a production knowledge graph from documents and run graph algorithms over it.\n\n``` python\nfrom semantica.ingest import FileIngestor\nfrom semantica.kg import (\n    GraphBuilder,\n    GraphAnalyzer,\n    CentralityCalculator,\n    CommunityDetector,\n    PathFinder,\n    LinkPredictor,\n    BiTemporalFact,\n)\nfrom datetime import datetime\n\n# Build KG - merge duplicate entities, track temporal edges\nsources = FileIngestor().ingest_directory(\"./contracts/\", recursive=True)\nkg = GraphBuilder(merge_entities=True, enable_temporal=True).build(sources)\n\n# Graph analytics\nanalyzer    = GraphAnalyzer()\nanalysis    = analyzer.analyze_graph(kg)             # full graph metrics\n\ncentrality  = CentralityCalculator()\ndegree      = centrality.calculate_degree_centrality(kg)    # most-connected entities\nbetweenness = centrality.calculate_betweenness_centrality(kg)\n\ncommunities = CommunityDetector().detect_communities(kg, method=\"louvain\")  # natural clusters\npath        = PathFinder().find_shortest_path(kg, \"alice_chen\", \"contract_001\")\npredictions = LinkPredictor().predict_links(kg, top_k=10)   # relationship predictions\n\n# Bi-temporal facts - track valid time vs. recorded time independently\nfact = BiTemporalFact(\n    valid_from=datetime(2024, 3, 1),\n    valid_until=datetime(2025, 1, 1),\n    recorded_at=datetime(2024, 3, 5),\n)\n```\n\n`semantica.reasoning`\n\n: Forward Chaining, Rete, Datalog, SPARQL\n\n`semantica.reasoning`\n\nRun explainable rule-based inference, not a black box.\n\n``` python\nfrom semantica.reasoning import ReteEngine, Rule, Fact, RuleType\n\nrete = ReteEngine()\nrete.build_network([\n    Rule(\n        rule_id=\"aml_flag\",\n        name=\"Flag high-risk transactions\",\n        conditions=[\n            {\"field\": \"amount\",  \"operator\": \">\",  \"value\": 10_000},\n            {\"field\": \"country\", \"operator\": \"in\", \"value\": [\"IR\", \"KP\", \"SY\"]},\n        ],\n        conclusion=\"flag_for_compliance_review\",\n        rule_type=RuleType.IMPLICATION,\n    ),\n    Rule(\n        rule_id=\"velocity_check\",\n        name=\"Flag rapid sequential transfers\",\n        conditions=[\n            {\"field\": \"transfers_in_1h\", \"operator\": \">\", \"value\": 5},\n            {\"field\": \"total_amount\",    \"operator\": \">\", \"value\": 50_000},\n        ],\n        conclusion=\"flag_velocity_breach\",\n        rule_type=RuleType.IMPLICATION,\n    ),\n])\n\nrete.add_fact(Fact(\"tx_001\", \"transaction\", [{\"amount\": 15_000, \"country\": \"IR\"}]))\nflagged = rete.match_patterns()\n# → [{\"rule\": \"aml_flag\", \"matched_facts\": [\"tx_001\"], \"conclusion\": \"flag_for_compliance_review\"}]\n```\n\nCurrent limitation:`ReteEngine`\n\n's alpha-node condition matcher is intentionally simple in this release — validate`match_patterns()`\n\noutput against your actual rule set before wiring it into a production compliance gate; more selective condition evaluation is on the roadmap.\n\n```\n# Recursive Datalog - natural language for graph queries\nfrom semantica.reasoning import DatalogReasoner\n\nengine = DatalogReasoner()\nengine.add_fact(\"parent(tom, bob)\")\nengine.add_fact(\"parent(bob, ann)\")\nengine.add_fact(\"parent(ann, pat)\")\nengine.add_rule(\"ancestor(X, Y) :- parent(X, Y).\")\nengine.add_rule(\"ancestor(X, Z) :- parent(X, Y), ancestor(Y, Z).\")\nancestors = engine.query(\"ancestor(tom, ?X)\")\n# → [{\"X\": \"bob\"}, {\"X\": \"ann\"}, {\"X\": \"pat\"}]\n# Explainable reasoning - trace the path, not just the answer\nfrom semantica.reasoning import ExplanationGenerator, Reasoner\n\nreasoner = Reasoner()\nreasoner.add_fact(\"parent(tom, bob)\")\nreasoner.add_rule(\"ancestor(X, Y) :- parent(X, Y)\")\nresult = reasoner.forward_chain()\n\nexplainer = ExplanationGenerator()\nexplanation = explainer.generate_explanation(result)\n# → Explanation(conclusion=\"...\", steps=[ReasoningStep(...)], justification=Justification(...))\n```\n\n`semantica.vector_store`\n\n: Hybrid & Filtered Semantic Search\n\n`semantica.vector_store`\n\nDrop-in vector store with multiple backends, hybrid search, and decision-aware retrieval.\n\n``` python\nfrom semantica.vector_store import VectorStore, HybridSearch\n\n# In-memory backend shown here: HybridSearch and explain_decision() work out of the box.\n# Swap backend=\"qdrant\" / \"weaviate\" / \"milvus\" / \"pinecone\" / \"pgvector\" / \"faiss\" once you\n# scale past a single process — search() and store_decision() work identically on all of them.\nvs = VectorStore(backend=\"inmemory\", dimension=1536)\n\n# Store a decision with scenario description and outcome\nvs.store_decision(\n    scenario=\"Personal loan A-7291, $85k income, 31% DTI, 3yr employment\",\n    outcome=\"approved\",\n    confidence=0.94,\n    category=\"loan_underwriting\",\n)\n\n# Semantic similarity search\nresults = vs.search(\n    query=\"personal loan approval with low DTI\",\n    limit=10,\n)\n\n# Hybrid search - dense + sparse retrieval in one pass with RRF fusion\nhs   = HybridSearch(vector_store=vs)\nhits = hs.search(\"high-risk transactions 2024\")\n\n# Explain why a decision was retrieved\nexplanation = vs.explain_decision(results[0][\"id\"])\n```\n\n**Backends:** `faiss`\n\n· `qdrant`\n\n· `weaviate`\n\n· `milvus`\n\n· `pinecone`\n\n· `pgvector`\n\n· `sqlite`\n\n· `inmemory`\n\n`semantica.split`\n\n: GraphRAG-Native Document Chunking\n\n`semantica.split`\n\nKG-aware splitting that preserves entity boundaries, relation triplets, and ontology concepts, essential for GraphRAG pipelines.\n\n``` python\nfrom semantica.split import TextSplitter, EntityAwareChunker, RelationAwareChunker\n\ntext = open(\"contracts/master_agreement.txt\").read()\n\n# Standard recursive chunking\nchunks = TextSplitter(method=\"recursive\", chunk_size=1000, chunk_overlap=200).split(text)\n\n# Entity-aware chunking - never splits a named entity across chunks (GraphRAG)\nchunks = TextSplitter(method=\"entity_aware\", ner_method=\"llm\", chunk_size=1000).split(text)\n\n# Relation-aware chunking - preserves (subject, predicate, object) triplets intact\nchunks = RelationAwareChunker(chunk_size=1000, preserve_triplets=True).chunk(text)\n\n# Graph-based chunking - uses centrality to find natural community boundaries\nchunks = TextSplitter(method=\"graph_based\", chunk_size=1000).split(text)\n\n# Hierarchical chunking - multi-level (section → paragraph → sentence)\nchunks = TextSplitter(method=\"hierarchical\", levels=[\"section\", \"paragraph\"]).split(text)\n```\n\n**Supported methods:** `recursive`\n\n· `token`\n\n· `sentence`\n\n· `paragraph`\n\n· `semantic_transformer`\n\n· `entity_aware`\n\n· `relation_aware`\n\n· `graph_based`\n\n· `ontology_aware`\n\n· `hierarchical`\n\n· `community_detection`\n\n· `centrality_based`\n\n· `llm`\n\n`semantica.provenance`\n\n: W3C PROV-O Lineage\n\n`semantica.provenance`\n\nEvery fact is linked to its source. No black boxes, no mystery outputs.\n\n``` python\nfrom semantica.provenance import ProvenanceManager\n\nprov = ProvenanceManager(storage_path=\"./provenance.db\")\n\n# Track where every entity came from\nprov.track_entity(\n    entity_id=\"acme_corp\",\n    source=\"contracts/acme_master_agreement_2024.pdf\",\n    metadata={\"page\": 1, \"confidence\": 0.97, \"extractor\": \"NamedEntityRecognizer\"},\n)\n\n# Track a relationship's provenance - entity linkage travels in metadata\nprov.track_relationship(\n    relationship_id=\"alice_works_for_acme\",\n    source=\"hr_records/employees_q1_2024.csv\",\n    metadata={\"source_entity_id\": \"alice_chen\", \"target_entity_id\": \"acme_corp\"},\n)\n\n# Answer \"where did this come from?\"\nlineage = prov.get_lineage(\"acme_corp\")\ntrail   = prov.trace_lineage(\"alice_chen\")   # full ancestor chain\nentry   = prov.get_provenance(\"acme_corp\")\n```\n\n`semantica.ontology`\n\n: OWL Generation, SHACL Validation\n\n`semantica.ontology`\n\nGenerate ontologies from data, validate shapes, and manage your vocabulary.\n\n``` python\nfrom semantica.ontology import OntologyGenerator, OntologyValidator\n\ndata = {\n    \"entities\": [\n        {\"id\": \"acme_corp\",  \"type\": \"Organization\", \"industry\": \"SaaS\", \"founded\": 2012},\n        {\"id\": \"alice_chen\", \"type\": \"Person\",        \"role\": \"CTO\",     \"since\": 2019},\n    ],\n    \"relationships\": [\n        {\"source\": \"alice_chen\", \"target\": \"acme_corp\", \"type\": \"works_for\"},\n    ],\n}\n\ngen       = OntologyGenerator(base_uri=\"https://semantica.dev/ontology/\")\nontology  = gen.generate_ontology(data)\nclasses   = gen.infer_classes(data)\nprops     = gen.infer_properties(data, classes)\noptimized = gen.optimize_ontology(ontology)\n\n# Validate against SHACL shapes\nvalidator = OntologyValidator()\nreport    = validator.validate(ontology)\n# → ValidationResult(valid=True, consistent=True, satisfiable=True, errors=[], warnings=[])\n```\n\n`semantica.conflicts`\n\n: Conflict Detection & Resolution\n\n`semantica.conflicts`\n\nDetect and resolve conflicting facts from multiple sources before they corrupt your knowledge base.\n\n``` python\nfrom semantica.conflicts import ConflictDetector, ConflictResolver, SourceTracker\n\nentities_from_source_a = [\n    {\"id\": \"alice_chen\", \"role\": \"CTO\",   \"salary\": 250_000, \"start_date\": \"2019-03-01\"},\n]\nentities_from_source_b = [\n    {\"id\": \"alice_chen\", \"role\": \"VP Eng\", \"salary\": 275_000, \"start_date\": \"2019-03-01\"},\n]\n\n# Detect all conflict types: value, type, relationship, temporal, logical\ndetector   = ConflictDetector()\nconflicts  = detector.detect_conflicts(entities_from_source_a + entities_from_source_b)\n# → [Conflict(entity=\"alice_chen\", field=\"role\",   values=[\"CTO\",\"VP Eng\"], severity=\"HIGH\"),\n#    Conflict(entity=\"alice_chen\", field=\"salary\",  values=[250000,275000],   severity=\"MEDIUM\")]\n\n# Resolve using multiple strategies\nresolver = ConflictResolver()\nresolved = resolver.resolve_conflicts(conflicts, strategy=\"credibility_weighted\")  # weighted by source trust\nresolved = resolver.resolve_conflicts(conflicts, strategy=\"most_recent\")          # prefer most recent\nresolved = resolver.resolve_conflicts(conflicts, strategy=\"voting\")               # majority wins\n\n# Track source credibility over time\ntracker = SourceTracker()\ntracker.register_source(\"source_a\", source_type=\"document\", credibility_score=0.85)\ntracker.register_source(\"source_b\", source_type=\"document\", credibility_score=0.72)\n```\n\n`semantica.deduplication`\n\n: Entity Resolution at Scale\n\n`semantica.deduplication`\n\nBlock, cluster, and merge duplicates with semantic similarity.\n\n``` python\nfrom semantica.deduplication import DuplicateDetector, EntityMerger\n\nentities = [\n    {\"id\": \"e1\", \"name\": \"Acme Corporation\",  \"domain\": \"acme.com\"},\n    {\"id\": \"e2\", \"name\": \"Acme Corp.\",         \"domain\": \"acme.com\"},\n    {\"id\": \"e3\", \"name\": \"ACME Corp\",          \"domain\": \"acme.co\"},\n    {\"id\": \"e4\", \"name\": \"Globex Industries\",  \"domain\": \"globex.com\"},\n]\n\ndetector   = DuplicateDetector(similarity_threshold=0.75, use_clustering=True)\ncandidates = detector.detect_duplicates(entities)\ngroups     = detector.detect_duplicate_groups(entities)\n# → DuplicateGroup(entities=[\"e1\",\"e2\",\"e3\"], confidence=0.91, strategy=\"semantic+blocking\")\n\nmerger  = EntityMerger(preserve_provenance=True)\nops     = merger.merge_duplicates(entities, strategy=\"keep_most_complete\")\nhistory = merger.get_merge_history()\n```\n\n`semantica.normalize`\n\n: Data Normalization & Cleaning\n\n`semantica.normalize`\n\nStandardize text, entities, dates, numbers, and encodings before building your knowledge graph.\n\n```\nfrom semantica.normalize import (\n    TextNormalizer,\n    EntityNormalizer,\n    DateNormalizer,\n    NumberNormalizer,\n    DataCleaner,\n)\n\n# Unicode, whitespace, casing, HTML tags, smart quotes\ntext  = TextNormalizer().normalize(\"  Acme Corp.'s Q4 report...  \")\n# → \"Acme Corp.'s Q4 report...\"\n\n# Alias resolution + entity disambiguation with confidence scores\ncanonical = EntityNormalizer().normalize_entity(\"ACME Corp.\")\n# → NormalizedEntity(canonical=\"Acme Corporation\", type=\"Organization\", confidence=0.91)\n\n# Natural language date parsing with timezone conversion\ndt    = DateNormalizer().normalize_date(\"3 weeks ago\")\n# → datetime(2026, 7, 1, tzinfo=UTC)\n\n# Unit conversion and currency normalization\nprice = NumberNormalizer().normalize_number(\"$1.25M USD\")\n# → NormalizedNumber(value=1_250_000, currency=\"USD\")\n\n# Deduplicate, validate, and impute missing values across a dataset\nclean = DataCleaner().clean_data(records, remove_duplicates=True, handle_missing=True)\n```\n\n`semantica.pipeline`\n\n: Pipeline DSL\n\n`semantica.pipeline`\n\nCompose ingestion, extraction, and graph-building into a declarative, parallel pipeline.\n\n``` python\nfrom semantica.pipeline import PipelineBuilder, ExecutionEngine\n\nbuilder = PipelineBuilder()\n\n# add_step() returns the created PipelineStep, not the builder, so these don't chain\nbuilder.add_step(\"ingest\",      step_type=\"ingest\",           source=\"./contracts/\", recursive=True)\nbuilder.add_step(\"extract\",     step_type=\"ner_extract\")\nbuilder.add_step(\"relations\",   step_type=\"relation_extract\")\nbuilder.add_step(\"build_kg\",    step_type=\"kg_build\",         merge_entities=True)\nbuilder.add_step(\"deduplicate\", step_type=\"deduplicate\",      threshold=0.75)\nbuilder.add_step(\"export\",      step_type=\"export\",           format=\"turtle\", output=\"kg.ttl\")\n\n# connect_steps() and set_parallelism() return the builder, so these do chain\npipeline = (\n    builder\n    .connect_steps(\"ingest\",      \"extract\")\n    .connect_steps(\"extract\",     \"relations\")\n    .connect_steps(\"relations\",   \"build_kg\")\n    .connect_steps(\"build_kg\",    \"deduplicate\")\n    .connect_steps(\"deduplicate\", \"export\")\n    .set_parallelism(4)\n    .build(name=\"contracts_pipeline\")\n)\n\nengine   = ExecutionEngine()\nresult   = engine.execute_pipeline(pipeline)\nstatus   = engine.get_pipeline_status(pipeline.name)\nprogress = engine.get_progress(pipeline.name)\n```\n\n**Temporal Intelligence**: Bi-Temporal Graphs & Time Travel\n\nTrack when facts were true *in the world* vs. when they were *recorded*, and query either axis.\n\n``` python\nfrom semantica.context import ContextGraph\nfrom semantica.kg import (\n    BiTemporalFact,\n    TemporalGraphQuery,\n    TemporalNormalizer,\n)\nfrom datetime import datetime\n\ngraph = ContextGraph(advanced_analytics=True)\ngraph.add_node(\"alice_chen\", \"Person\",       role=\"VP Engineering\")\ngraph.add_node(\"acme_corp\",  \"Organization\", valuation=1_200_000_000)\n\n# A temporally-bounded edge - valid_from/valid_until define when it held true\ngraph.add_edge(\n    \"alice_chen\", \"acme_corp\", edge_type=\"works_for\",\n    valid_from=\"2024-03-01T00:00:00\", valid_until=\"2025-01-01T00:00:00\",\n)\n\n# Point-in-time snapshots - replay history without reprocessing\nsnapshot_2023 = graph.state_at(\"2023-06-01\")\nsnapshot_2024 = graph.state_at(\"2024-01-01\")\n\n# Bi-temporal facts - valid_time is when true in the world;\n# recorded_at is when you learned about it\nfact = BiTemporalFact(\n    valid_from=datetime(2024, 3, 1),\n    valid_until=datetime(2025, 1, 1),\n    recorded_at=datetime(2024, 3, 5),\n)\n\n# Query facts valid within a time window - query_time_range() expects\n# {\"relationships\": [...]} with source_id/target_id keys, which differs from\n# ContextGraph.to_dict()'s {\"nodes\", \"edges\"} shape, so map it first\ngraph_dict = graph.to_dict()\nkg_relationships = {\n    \"relationships\": [\n        {**e, \"source_id\": e[\"source\"], \"target_id\": e[\"target\"]}\n        for e in graph_dict[\"edges\"]\n    ]\n}\n\ntq = TemporalGraphQuery()\nfacts_in_window = tq.query_time_range(\n    kg_relationships, query=\"valid_facts\", start_time=\"2024-01-01\", end_time=\"2024-12-31\"\n)\n\n# Normalize natural language temporal expressions - returns a (start, end) range\nnorm = TemporalNormalizer()\nstart, end = norm.normalize(\"last quarter\")\n```\n\n`semantica.export`\n\n: RDF, OWL, Parquet, Cypher, JSON-LD\n\n`semantica.export`\n\nExport to any format required by regulators, graph databases, or downstream systems.\n\n```\nfrom semantica.export import (\n    RDFExporter,\n    JSONExporter,\n    ParquetExporter,\n    LPGExporter,\n    ReportGenerator,\n)\n\nkg = {\"entities\": [...], \"relationships\": [...]}\n\nrdf = RDFExporter()\nturtle_str = rdf.export_to_rdf(kg, format=\"turtle\")     # returns string\njsonld_str = rdf.export_to_rdf(kg, format=\"json-ld\")\n\nrdf.export(kg, \"kg_audit.ttl\",    format=\"turtle\")\nrdf.export(kg, \"kg_audit.jsonld\", format=\"json-ld\")\nrdf.export(kg, \"kg_audit.nt\",     format=\"n-triples\")\n\n# Columnar analytics - Snappy-compressed Parquet (writes kg_snapshot_entities.parquet\n# and kg_snapshot_relationships.parquet)\nParquetExporter(compression=\"snappy\").export_knowledge_graph(kg, \"kg_snapshot\")\n\n# JSON knowledge graph\nJSONExporter().export_knowledge_graph(kg, \"kg.json\")\n\n# Neo4j / Memgraph Cypher statements for graph database import\nLPGExporter().export(kg, \"kg_import.cypher\")\n\n# Human-readable HTML report\nReportGenerator().generate_report(\n    {\"title\": \"KG Audit Report\", \"summary\": \"Weekly ingestion summary\", \"metrics\": {\"entities\": len(kg[\"entities\"])}},\n    file_path=\"audit_report.html\",\n    format=\"html\",\n)\n```\n\n`semantica.visualization`\n\n: Interactive Graph Workbench\n\n`semantica.visualization`\n\nRender force-directed graphs, community maps, ontology hierarchies, and temporal dashboards.\n\n```\nfrom semantica.visualization import (\n    KGVisualizer,\n    OntologyVisualizer,\n    EmbeddingVisualizer,\n    TemporalVisualizer,\n)\nimport numpy as np\n\nkg = {\"entities\": [...], \"relationships\": [...]}\n\n# Interactive force-directed graph (opens in browser)\nviz = KGVisualizer(layout=\"force\", color_scheme=\"default\")\nviz.visualize_network(kg, output=\"interactive\", file_path=\"kg.html\")\nviz.visualize_communities(kg, communities, output=\"interactive\")\nviz.visualize_centrality(kg, centrality, centrality_type=\"degree\")\nviz.visualize_entity_types(kg, output=\"html\", file_path=\"entity_types.html\")\n\n# Ontology class hierarchy\nOntologyVisualizer().visualize_hierarchy(ontology, output=\"interactive\")\n\n# 2D embedding projection (UMAP / t-SNE / PCA)\nEmbeddingVisualizer().visualize_2d_projection(\n    embeddings=np.array([...]),\n    labels=[\"entity_a\", \"entity_b\"],\n    method=\"umap\",\n)\n\n# Timeline scrubber - watch the graph evolve\nTemporalVisualizer().visualize_timeline(kg, output=\"interactive\")\n```\n\n**Multi-Agent Shared Context with Agno**\n\nOne shared intelligence layer. All agents read and write to the same context graph.\n\n``` python\n# pip install semantica[agno]\nfrom agno.agent import Agent\nfrom agno.team import Team\nfrom agno.models.anthropic import Claude\nfrom semantica.context import ContextGraph\nfrom semantica.vector_store import VectorStore\nfrom integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit\n\nshared = AgnoSharedContext(\n    vector_store=VectorStore(backend=\"faiss\"),\n    knowledge_graph=ContextGraph(advanced_analytics=True),\n    decision_tracking=True,\n)\n\nresearcher = Agent(\n    name=\"Researcher\",\n    model=Claude(id=\"claude-sonnet-4-5\"),\n    memory=shared.bind_agent(\"researcher\"),\n    tools=[AgnoKGToolkit(context=shared)],\n)\nanalyst = Agent(\n    name=\"Analyst\",\n    model=Claude(id=\"claude-sonnet-4-5\"),\n    memory=shared.bind_agent(\"analyst\"),\n    tools=[AgnoDecisionKit(context=shared)],\n)\n\nteam = Team(agents=[researcher, analyst], mode=\"coordinate\")\n# Researcher's findings are instantly available to the Analyst - no copy, no sync\n```\n\n→ [runnable notebooks in the cookbook](https://github.com/semantica-agi/semantica/tree/main/cookbook), each self-contained and runnable in under 5 minutes\n\nThe flagship audit-trail recipe is [above](#recipe-audit-trail-for-a-regulated-decision). Here are three more common patterns.\n\n**End-to-End GraphRAG Pipeline**\n\n``` python\nfrom semantica.ingest import FileIngestor\nfrom semantica.split import TextSplitter\nfrom semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor\nfrom semantica.kg import GraphBuilder\nfrom semantica.vector_store import VectorStore, HybridSearch\nfrom semantica.context import AgentContext\n\n# 1. Ingest\ndocs = FileIngestor().ingest_directory(\"./docs/\", recursive=True)\n\n# 2. Entity-aware chunking - never splits an entity across a chunk boundary\nsplitter = TextSplitter(method=\"entity_aware\", chunk_size=1000)\nchunks   = [splitter.split(doc[\"text\"]) for doc in docs]\n\n# 3. Extract entities and relations\nner      = NamedEntityRecognizer(confidence_threshold=0.7)\nrel_ext  = RelationExtractor(confidence_threshold=0.6)\nentities = [ner.extract_entities(chunk) for chunk_group in chunks for chunk in chunk_group]\n\n# 4. Build KG\nkg = GraphBuilder(merge_entities=True, enable_temporal=True).build(docs)\n\n# 5. Hybrid retrieval\nvs  = VectorStore(backend=\"inmemory\")\nctx = AgentContext(vector_store=vs, knowledge_graph=kg)\nctx.store(\"Alice approved the Acme renewal in Q1 2024\", conversation_id=\"c1\")\n\nresults = HybridSearch(vector_store=vs).search(\"who approved the renewal?\")\n```\n\n**AML Rules Engine**\n\n``` python\nfrom semantica.reasoning import ReteEngine, Rule, Fact, RuleType\n\nrete = ReteEngine()\nrete.build_network([\n    Rule(\n        rule_id=\"sanctions_check\",\n        name=\"Flag sanctioned-country transactions\",\n        conditions=[\n            {\"field\": \"amount\",  \"operator\": \">\",  \"value\": 10_000},\n            {\"field\": \"country\", \"operator\": \"in\", \"value\": [\"IR\", \"KP\", \"SY\", \"CU\"]},\n        ],\n        conclusion=\"flag_for_compliance_review\",\n        rule_type=RuleType.IMPLICATION,\n    ),\n])\n\n# Run the rule across a batch of incoming transactions, not just one\nfor tx in [\n    Fact(\"tx_101\", \"transaction\", [{\"amount\": 25_000, \"country\": \"IR\"}]),\n    Fact(\"tx_102\", \"transaction\", [{\"amount\": 4_500,  \"country\": \"DE\"}]),\n    Fact(\"tx_103\", \"transaction\", [{\"amount\": 60_000, \"country\": \"KP\"}]),\n]:\n    rete.add_fact(tx)\n\nflagged = rete.match_patterns()\n```\n\nSame condition-matcher caveat as [above](#semanticareasoning-forward-chaining-rete-datalog-sparql) applies — validate against your rule set before production use.\n\n**Ontology-to-Knowledge-Graph in One Pass**\n\n``` python\nfrom semantica.ingest import FileIngestor\nfrom semantica.semantic_extract import NamedEntityRecognizer, RelationExtractor\nfrom semantica.kg import GraphBuilder\nfrom semantica.ontology import OntologyGenerator, OntologyValidator\nfrom semantica.export import RDFExporter\n\nsources   = FileIngestor().ingest_directory(\"./contracts/\")\nner       = NamedEntityRecognizer(confidence_threshold=0.7)\nentities  = ner.process_batch([s[\"text\"] for s in sources])\n\nkg  = GraphBuilder(merge_entities=True).build(sources)\ngen = OntologyGenerator(base_uri=\"https://myco.dev/ontology/\")\nont = gen.generate_ontology({\"entities\": entities[0], \"relationships\": []})\n\nreport = OntologyValidator().validate(ont)\nif report.valid:\n    RDFExporter().export({\"entities\": entities[0]}, \"ontology.ttl\", format=\"turtle\")\n```\n\n| Capability | Highlights |\n|---|---|\nContext Graphs |\nQueryable graph of entities, decisions, relationships; causal links; cross-graph navigation |\nDecision Intelligence |\n`record_decision` · `trace_decision_chain` · `find_similar_decisions` · `analyze_decision_impact` · `check_decision_rules` |\nTemporal Intelligence |\nPoint-in-time snapshots · Allen interval algebra (13 relations) · `TemporalNormalizer` · bi-temporal provenance |\nDistance Intelligence |\nN×N semantic distance matrices · ego-mode visualization · distance bands · embedding cache |\nSemantic Extraction |\nNER · relation extraction · event detection · triplet generation · coreference |\nReasoning Engines |\nForward chaining · Rete · deductive · abductive · SPARQL · Datalog with explainable output |\nGraphRAG Chunking |\nEntity-aware · relation-aware · graph-based · ontology-aware · community-detection chunking |\nConflict Detection |\nValue / type / relationship / temporal / logical conflicts · multiple resolution strategies |\nProvenance |\nW3C PROV-O · every fact traced to source · audit log export JSON/CSV/RDF |\nOntology Hub |\nSHACL Studio · visual editor · cross-ontology alignments · health dashboard |\nVector Store |\nFAISS · Pinecone · Weaviate · Qdrant · Milvus · PgVector · hybrid + filtered search |\nGraph Databases (LPG) |\nNeo4j · FalkorDB · Apache AGE · AWS Neptune |\nTriple Stores (RDF) |\nOxigraph (embedded) · Blazegraph · Apache Jena · Eclipse RDF4J · unified `TripletStore` interface · SPARQL query & bulk load |\nEnterprise Data Platforms |\nDatabricks (`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) |\nLLM Providers |\nAll 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 |\n\nBenchmarks from v0.5.0 on a 118,000-node production graph:\n\n| Operation | Before | After | Improvement |\n|---|---|---|---|\n| Node search (118k nodes) | 24 ms | 0.004 ms | 6,000× faster |\n| Embedding cache hit | cold load | revision-based cache | 10× throughput |\n| Semantic deduplication | baseline | optimized candidate gen | 6.98× faster |\n| Candidate generation | baseline | blocking strategy | 63.6% faster |\n\n*Measured on a 118,000-node production graph (AMD EPYC, 64 GB RAM); the deduplication/candidate-generation figures are historical measurements recorded in CHANGELOG.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.*\n\nEvery capability is available from the terminal. The CLI ships with the package, no separate install required.\n\n```\npip install semantica\nsemantica        # startup dashboard\nsemantica doctor # health check\nsemantica --help # full grouped command reference\n```\n\nStart with `semantica`\n\n, verify with `doctor`\n\n, build a graph, and explore the command groups from one terminal.\n\n**Command groups:** `ingest`\n\n· `parse`\n\n· `extract`\n\n· `kg`\n\n· `reason`\n\n· `decision`\n\n· `temporal`\n\n· `provenance`\n\n· `ontology`\n\n· `embed`\n\n· `deduplicate`\n\n· `validate`\n\n· `export`\n\n· `visualize`\n\n· `pipeline`\n\n· `server`\n\n· `explorer`\n\n· `mcp`\n\n· `doctor`\n\n· `shell`\n\n· `init`\n\n· `watch`\n\nNative 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 support for multi-agent shared context. Every major LLM provider is already supported via `semantica.llms`\n\nand LiteLLM: OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Azure, Bedrock, Ollama, DeepSeek, HuggingFace, and more.\n\nMCP setup takes 30 seconds — see [MCP Server](#mcp-server) below.\n\n**Full integrations matrix** (editors, MCP clients, REST clients, agentic frameworks)\n\n| Native Plugin Bundle | MCP Server + Plugin | ||||||\n|---|---|---|---|---|---|---|---|\nClaude CodeSkills · agents · hooks\n|\nCursorSkills · agents\n|\nCodex CLISkills · agents\n|\nWindsurf\n|\nCline\n|\nContinue\n|\nVS Code\n|\nOpenClawMCP +\n|\n| MCP Server | REST API | ||||||\nClaude DesktopMCP server\n|\nGitHub CopilotREST API\n|\nRoo CodeREST API\n|\nGooseREST API\n|\nKilo CodeREST API\n|\nAiderREST API\n|\nAmazon QREST API\n|\nZedREST API\n|\n\nConnect any MCP-compatible client (Claude Desktop, Windsurf, Cline, VS Code) in 30 seconds:\n\n```\npython -m semantica.mcp_server\n# or via the installed entry point\nsemantica-mcp\n{\n  \"mcpServers\": {\n    \"semantica\": { \"command\": \"python\", \"args\": [\"-m\", \"semantica.mcp_server\"] }\n  }\n}\n```\n\n**Tools exposed over MCP:**\n\n| Tool | What it does |\n|---|---|\n`extract_entities` |\nNER on any text |\n`extract_relations` |\nRelation extraction |\n`record_decision` |\nPersist a decision node |\n`query_decisions` |\nSearch decision history |\n`find_precedents` |\nSemantic precedent lookup |\n`get_causal_chain` |\nFull causal ancestry |\n`add_entity` |\nAdd a KG node |\n`add_relationship` |\nAdd a KG edge |\n`run_reasoning` |\nExecute rule set |\n`get_graph_analytics` |\nCentrality, communities |\n`export_graph` |\nExport to RDF/JSON/Parquet |\n`get_graph_summary` |\nGraph statistics |\n\n```\n# Start the backend\npython -m semantica.server   # port 8000\n\n# Extract entities & relations via REST\ncurl -X POST http://localhost:8000/api/enrich/extract \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\": \"Apple CEO Tim Cook announced record earnings.\"}'\n\n# List recorded decisions\ncurl \"http://localhost:8000/api/decisions?category=vendor_selection\"\n\n# Query the knowledge graph\ncurl \"http://localhost:8000/api/graph/node/acme_corp/neighbors?depth=2\"\n```\n\n**REST endpoints span:** `enrich`\n\n(extract) · `graph`\n\n· `decisions`\n\n· `reasoning`\n\n· `provenance`\n\n· `ontology`\n\n· `embeddings`\n\n· `search`\n\n· `export`\n\n· `pipeline`\n\n· `temporal`\n\n· `deduplication`\n\n**Domain skills:** `extract`\n\n· `ingest`\n\n· `query`\n\n· `ontology`\n\n· `validate`\n\n· `deduplicate`\n\n· `embed`\n\n· `reason`\n\n· `decision`\n\n· `causal`\n\n· `temporal`\n\n· `provenance`\n\n· `policy`\n\n· `explain`\n\n· `export`\n\n· `change`\n\n· `visualize`\n\n**Specialized agents:** `kg-assistant`\n\n· `decision-advisor`\n\n· `explainability`\n\nBundles for Claude Code, Cursor, Codex, Windsurf, Cline, Continue, VS Code, and OpenClaw in [ plugins/](/semantica-agi/semantica/blob/main/plugins).\n\nA 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.\n\n| Workspace | What you can do |\n|---|---|\nKnowledge Graph |\nLive Sigma.js canvas with ForceAtlas2 layout, Ego Mode, semantic distance heatmap |\nTimeline |\nScrub through temporal events and watch the graph evolve |\nDecisions |\nBrowse the causal chain behind every recorded decision |\nRegistry |\nLive audit log of every graph mutation |\nEntity Resolution |\nReview and merge duplicates |\nOntology Hub |\nSHACL Studio, visual editor, cross-ontology alignments, SKOS browser |\nLineage |\nW3C PROV-O provenance visualization for any entity |\n\nQuickest way to start (no Node.js required):\n\n```\npip install \"semantica[explorer]\"\nsemantica-explorer --graph my_graph.json\n# Dashboard opens at http://127.0.0.1:8000\n```\n\nFor contributor / dev-server setup: [explorer/README.md: Local Setup Guide](/semantica-agi/semantica/blob/main/explorer/README.md)\n\n**Security release — upgrading is strongly recommended.** Fixes for 5 externally-reported vulnerabilities in the Explorer API and graph/triplet store backends, plus a CodeQL-flagged ReDoS:\n\n**Missing authentication on all Explorer API routes**(GHSA-j4mq-hprp-987v, Critical): every route now requires`SEMANTICA_API_KEY`\n\n, fails closed (503) rather than open when unconfigured**SSRF via redirect bypass in ontology URL fetching**(GHSA-8c7v-62gr-hj6g, High): redirect targets are now re-validated at every hop and the connection is pinned to the validated address, closing a DNS check-then-use race**Cypher injection via unvalidated node labels and property keys**(GHSA-482h-hw99-h62p, Critical): Neptune, Neo4j, and FalkorDB now sanitize every label/relationship-type/property-key interpolation site**SPARQL injection via unvalidated triplet IRIs**(GHSA-8vgg-8mr4-r236, Critical): Blazegraph, RDF4J, and Jena now validate subject/predicate/object IRIs before interpolation**Missing Origin validation on the WebSocket handshake**(GHSA-4643-wpgq-w329, Moderate, anonymous-mode only):`/ws/graph-updates`\n\nnow checks`Origin`\n\nagainst the same allowlist`CORSMiddleware`\n\nenforces for HTTP**Polynomial ReDoS in SPARQL query validation**(CodeQL`py/polynomial-redos`\n\n): fixed a backtracking regex in the Explorer's SPARQL route\n\nAlso includes: embedded Oxigraph backend for `TripletStore`\n\n, PROV-O trust/spec completeness for `ProvenanceManager`\n\n, and the Altair Anzo triplet store backend.\n\n→ [Full release notes](/semantica-agi/semantica/blob/main/RELEASE_NOTES.md) · [Changelog](/semantica-agi/semantica/blob/main/CHANGELOG.md)\n\nSemantica 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:\n\n**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\n\n```\npip install semantica           # core\npip install semantica[all]      # everything\npip install semantica[agno]                 # Agno multi-agent integration\npip install semantica[llm-litellm]          # OpenAI, Anthropic, Gemini, Mistral, Llama, Groq, Cohere, Bedrock, Ollama, DeepSeek, and more\npip install semantica[graph-neo4j]          # Neo4j graph store (LPG)\npip install semantica[graph-falkordb]       # FalkorDB graph store (LPG)\npip install semantica[graph-apache-age]     # Apache AGE graph store (LPG)\npip install semantica[graph-amazon-neptune] # AWS Neptune graph store (LPG)\npip install semantica[tripletstore-oxigraph] # Embedded in-memory/on-disk RDF store\n# RDF triple stores (Blazegraph, Apache Jena, Eclipse RDF4J) need no extra:\n# semantica.triplet_store talks SPARQL over HTTP using the core `requests` dependency\npip install semantica[vectorstore-qdrant]   # Qdrant vector store\npip install semantica[vectorstore-pinecone] # Pinecone vector store\npip install semantica[db-snowflake]         # Snowflake\npip install semantica[db-databricks]        # Databricks (SDK + SQL connector)\npip install semantica[ingest-parquet]       # Parquet / PyArrow\npip install semantica[ingest-arrow]        # Apache Arrow, Feather, IPC\npip install semantica[viz]                  # HTML interactive visualization\npip install semantica[watch]                # Directory file watcher\npip install semantica[explorer]             # Knowledge Explorer dashboard\n```\n\nFor production deployments, use Docker or Kubernetes rather than a local `pip install`\n\n. Set `SEMANTICA_SECRET_KEY`\n\n, 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](/semantica-agi/semantica/blob/main/ARCHITECTURE.md) for the full deployment topology.\n\n```\n# From source\ngit clone https://github.com/semantica-agi/semantica.git\ncd semantica && pip install -e \".[dev]\" && pytest tests/\n```\n\nOn-premises deployment · Private cloud · Custom domain implementations · SLA-backed support · Professional services for regulated industries (finance, healthcare, legal, government).\n\n** getsemantica.ai** for enterprise solutions and pricing.\n\nDiscord |\n|\n\n**GitHub Discussions**[Q&A and feature requests](https://github.com/semantica-agi/semantica/discussions)** GitHub Issues**[Bug reports](https://github.com/semantica-agi/semantica/issues)** Documentation**[docs.getsemantica.ai](https://docs.getsemantica.ai/)** Cookbook**[Runnable Jupyter notebooks](https://github.com/semantica-agi/semantica/tree/main/cookbook)** Changelog**[CHANGELOG.md](/semantica-agi/semantica/blob/main/CHANGELOG.md)·[Release Notes](/semantica-agi/semantica/blob/main/RELEASE_NOTES.md)\n\nAll contributions are welcome: bug fixes, features, tests, and documentation.\n\n- Fork the repo and create a branch\n`pip install -e \".[dev]\"`\n\n- Write tests alongside your changes (\n`pytest tests/`\n\n) - Open a PR and tag\n`@KaifAhmad1`\n\nfor review\n\nSee [CONTRIBUTING.md](/semantica-agi/semantica/blob/main/CONTRIBUTING.md) for full guidelines.", "url": "https://wpnews.pro/news/an-open-source-knowledge-graph-for-traceable-ai-decisions", "canonical_source": "https://github.com/semantica-agi/semantica", "published_at": "2026-08-14 03:31:14+00:00", "updated_at": "2026-08-14 03:40:42.859185+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-infrastructure"], "entities": ["Semantica", "Databricks", "Snowflake", "W3C"], "alternates": {"html": "https://wpnews.pro/news/an-open-source-knowledge-graph-for-traceable-ai-decisions", "markdown": "https://wpnews.pro/news/an-open-source-knowledge-graph-for-traceable-ai-decisions.md", "text": "https://wpnews.pro/news/an-open-source-knowledge-graph-for-traceable-ai-decisions.txt", "jsonld": "https://wpnews.pro/news/an-open-source-knowledge-graph-for-traceable-ai-decisions.jsonld"}}