Semantica Open-Source Project: Making AI Agent Decisions Auditable and Traceable

A "Why" That No One Can Answer

Imagine this scenario: your bank uses an AI agent to approve loans. One day, it rejects an applicant. Three months later, the regulator sends a letter asking just one question — why did the AI reject them? Your team digs through every log, only to find a pile of vector retrieval records and a single line of model output. No one can answer that "why."

This isn't hypothetical. Today's AI agents universally lack traceable action trails: they store embedding vectors, they store similarity scores, but they don't store meaning. The open-source project Semantica was built to solve exactly this problem. It has already earned over 10,800 stars on GitHub, and the first line of its README is refreshingly blunt — an open-source Palantir for AI agents.

The project is written in Python by the Semantica Agile team, released under the MIT license. It installs with a single command, and a health check finishes in 5 seconds.

Positioning: Infrastructure Beneath Everything Else

Let's be clear about where Semantica sits. It's not a large language model, not a vector database, not an agent framework. Semantica is a layer of infrastructure that sits underneath all of these.

Why the Palantir comparison? Palantir Technologies is one of America's most secretive data companies, co-founded by Peter Thiel in 2003. It initially received venture funding from In-Q-Tel, the CIA's investment arm, and has long provided data integration, graph analytics, and decision support to government intelligence agencies and large enterprises. Its product line splits into three: Gotham serves intelligence and defense, fusing heterogeneous data like communication records, financial transactions, and geolocation into an interactive relationship graph; Foundry serves enterprises, building a unified semantic layer from data scattered across business systems; the latest AIP layers LLMs on top of the other two, letting military and business analysts drive decisions using natural language. All three product lines share one thing in common: all data relationships and decision paths are traceable and auditable. But Palantir is closed-source and expensive — a single enterprise deployment typically costs millions of dollars per year. Semantica aims to do the same thing, but in an open-source, self-hosted, vendor-lock-in-free form.

Its most fundamental design principle, stated in the first paragraph of the architecture docs: graph construction, reasoning, and provenance all operate without any LLM involvement. In other words, who connects to whom, why a decision was made, where the data came from — these answers are produced by deterministic code, yielding identical results every run, fully reproducible and auditable. This is a hard requirement in high-risk industries like financial risk management and healthcare compliance.

Core Concept: The Context Graph

To understand Semantica, you first need to see the shortcomings of traditional RAG. RAG (Retrieval-Augmented Generation) is currently the most popular paradigm for connecting LLMs to external knowledge: documents are chunked into segments, converted into high-dimensional vectors using embedding models (such as OpenAI's text-embedding or open-source BGE series), and stored in vector databases like Milvus or Pinecone. At query time, the user's question is also vectorized, and the most relevant chunks are found via cosine similarity or inner product, then fed into the LLM's prompt to generate a response. The core capability of this pipeline is semantic similarity matching — it can find content that "says things differently but means roughly the same." But its limitation lies precisely here: vector retrieval can only answer one question: what is similar to what. It can't answer three other questions — what is connected to what, why they're connected, and how they became connected. When you need to reason across multiple entities (e.g., "find all contracts with indirect business ties to a certain person"), vector retrieval completely breaks down, because "closeness" in embedding space and "closeness" in business relationships are two entirely different things.

The Context Graph is essentially an engineered implementation of a Knowledge Graph. Knowledge graphs use "triples" (Subject-Predicate-Object, e.g., "Zhang San - serves as - CTO") to represent facts about the world, with entities as nodes and relationships as edges. Unlike relational databases, knowledge graphs are naturally suited for expressing many-to-many, multi-level nested complex relationships — you don't need to write complex JOIN queries, just traverse edges (Graph Traversal) to find all related entities within k hops in O(k) time. Semantica's Context Graph models entities, relationships, decisions, and facts as nodes on the graph, using graph traversal to answer those other three questions.

The README provides a three-node example: Zhang San is the CTO of Company A, which signed a contract worth $2.4 million. Representing entities as nodes and relationships as edges, you can start from the company, walk two hops, and find that contract — then trace back to the people involved in signing it. Vector retrieval can't do this — because a person and a contract aren't necessarily close in embedding space, but on a knowledge graph, they're neighbors.

The Context Graph has two more notable features:

• Time Travel: Call the StateAt function with any date, and you can see what the knowledge graph looked like on that day. History can be replayed without reprocessing. Behind this feature is a design philosophy based on Event Sourcing — every change to the graph is recorded as an immutable event, and any historical state can be precisely reconstructed by replaying the event sequence, without needing periodic full snapshots.
• Conflict Detection: When two data sources give contradictory accounts of the same fact, the system flags the conflict for human adjudication, rather than silently overwriting with new data like most systems do.

Decision Intelligence: Making Every Judgment Traceable

If the Context Graph solves "how knowledge is stored," then Decision Intelligence solves "how decisions are audited" — and this is the project's most compelling part.

In Semantica, a decision appears as a node on the graph: what type, what context, what evidence, what conclusion, what confidence level — all structured and attached to the node.

A Complete Decision Chain for Loan Approval

The README demonstrates the full chain using a loan approval scenario:

• Step 1 — Credit Application Decision: Applicant's annual income is $85,000, debt-to-income ratio is 31%, conclusion is referral to manual review, confidence 0.88;
• Step 2 — Underwriting Decision: Debt ratio is within policy limits, credit history is clean, conclusion is approval, confidence 0.94;
• Step 3 — Rate Pricing Decision: Priced by risk tier, annual rate 8.9%.

The key stroke is using Add Causal Relationship to chain the three decisions into a causal sequence: the application leads to underwriting, which influences pricing. When regulators come knocking, three functions step up:

• Trace Decision Chain follows the causal chain back to the root cause;
• Find Similar Decisions searches for historical precedents by semantics;
• Analyze Decision Impact produces a downstream impact graph.

Finally, the entire chain is exported as an audit file in W3C PROV-O format. PROV-O (The PROV Ontology) is a provenance data model standard published by the World Wide Web Consortium (W3C) in 2013, defined using the OWL2 ontology language, built around three core concepts: Entity (data objects that are produced or consumed), Activity (processing actions that occur over a period of time), and Agent (people or systems responsible for activities). These are connected through standardized relationships like wasGeneratedBy, used, and wasAttributedTo, forming a complete data lineage chain. PROV-O's advantage is that it's RDF-native and can be directly integrated with knowledge graphs without an additional mapping layer. The US NIST, the EU's GDPR data processing record requirements, and the financial industry's MiFID II transaction record specifications can all be satisfied using the PROV-O format. Semantica's ability to export the entire decision chain directly in this format means enterprises can submit it straight to regulators, saving massive amounts of compliance documentation work.

A More Hardcore Medical Decision Scenario

The README's flagship recipe switches to a medical scenario, with even higher stakes: Step 1 is a drug interaction check — the patient has been prescribed both warfarin and amiodarone simultaneously, and the system identifies that amiodarone enhances warfarin's anticoagulant effect, flagging it for review (confidence 0.91); Step 2 is dosage adjustment — reduce warfarin by 30%, recheck coagulation markers in 5 days (confidence 0.87). This scenario is extremely common and high-risk in clinical practice: warfarin is the most widely used oral anticoagulant with an extremely narrow therapeutic window — too high a dose causes bleeding, too low and thrombosis risk spikes; amiodarone is an antiarrhythmic drug that inhibits the CYP2C9 enzyme in the liver responsible for metabolizing warfarin, causing warfarin blood concentration to rise 30%-50%. The two steps are linked by causal relationships, and the patient entity also carries provenance: the source is a medication order from the electronic health record, with the specific extractor that processed it also recorded.

Finally, an audit trail file is exported — who, when, based on which medical order, made what judgment, with the complete causal chain and verifiable provenance. Healthcare, finance, and legal industries all face AI deployment bottlenecks around auditability — this recipe essentially turns the hardest part into a standard operation.

End-to-End Modular Architecture

Zooming out to the big picture, Semantica is a genuine end-to-end pipeline where every component is an independent module.

Data enters from various sources: local files, web pages, databases, Kafka streams, Git repositories, plus native connectors for Databricks and Snowflake — tables in a data warehouse can be directly transformed into graph nodes without exporting and re-importing. The Kafka connector is particularly noteworthy: in real-time risk management scenarios, transaction events arrive at thousands per second. Semantica continuously consumes the event stream via a Kafka Consumer, updating nodes and relationships on the knowledge graph in real time, making the graph not a static "offline artifact" but a "living" data structure that beats in sync with the business. After ingestion, data goes through parsing, normalization, and chunking, followed by Named Entity Recognition (NER), Relation Extraction (RE), and Event Extraction (EE) to produce triples. The NER/RE/EE pipeline is the classic three-step approach in information extraction — NER identifies entities like person names, organization names, and locations in text; RE determines the semantic relationship type between two entities (such as "employed at" or "signed"); EE extracts events along with their participants, timestamps, locations, and other elements. Traditional approaches rely on tools like spaCy and Stanford NER, while recent BERT-based pretrained model approaches have significantly improved accuracy. But Semantica's key design choice is: extraction results are validated by deterministic rules before entering the graph, preventing model hallucinations from polluting the knowledge base.

Next come two easily overlooked but critical steps: conflict detection and entity disambiguation — contradictory facts are flagged first, duplicate entities are merged first, and dirty data never enters the graph. Entity Disambiguation (also known as Entity Resolution) is one of the most notoriously difficult problems in knowledge graph construction: the same entity may have different names across data sources ("IBM" vs "International Business Machines Corporation"), different encodings, or even contradictory attribute values. Disambiguation typically combines string similarity (edit distance, Jaccard coefficient), attribute matching, contextual semantics, and graph structural features for comprehensive judgment — the error rate directly impacts the reliability of all downstream reasoning. Semantica records disambiguation results in the provenance chain as well, meaning if a merge error is discovered later, it can be precisely located and rolled back. Once clean data is built into the knowledge graph, graph analytics run on top: centrality, community detection, and link prediction.

The intelligence layer features a "four-piece suite": ontology, governance, reasoning engine (forward chaining, RETE network, Datalog, Spark), with fully explainable reasoning paths, plus provenance and decision recording. The reasoning engine tech stack deserves elaboration. Forward Chaining is a data-driven reasoning approach: starting from known facts, rules' antecedents (IF parts) are matched one by one; when satisfied, the consequent (THEN part) fires to generate new facts, cycling until no new facts are produced. The RETE Network is an efficient pattern-matching algorithm proposed by Charles Forgy in 1979. It compiles rules into a directed acyclic graph (DAG), sharing intermediate match results between nodes to avoid redundant computation. This means performance doesn't degrade linearly as rule count grows from dozens to thousands — critical in financial compliance scenarios requiring hundreds of business rules. Datalog is a subset of Prolog, a declarative logic query language particularly adept at expressing recursive queries (like "find all direct or indirect equity control relationships"), more concise and semantically clearer than SQL's recursive CTEs. Spark reasoning serves large-scale distributed scenarios — when knowledge graph nodes reach millions, single-machine reasoning becomes prohibitive in memory and compute cost, and Spark's distributed computing capabilities can partition reasoning tasks across a cluster for parallel execution. The common trait of all four engines is determinism — given the same inputs and rules, the output is always identical, and every inference step has an auditable basis, standing in stark contrast to the probabilistic reasoning of large language models.

The storage layer supports multiple backends, compatible with both RDF triple stores and property graph databases — switch between Jena and Neptune at will without changing code. External interfaces come in three flavors: an MCP server with 12 tools, a REST API, and a CLI with 20+ command groups. MCP (Model Context Protocol) is an open protocol released by Anthropic in late 2024, designed to provide standardized tool-calling interfaces for AI models. Semantica's implementation of an MCP server means any MCP-compatible AI agent (such as Claude or LangChain-based Agents) can directly invoke Semantica's graph querying, decision tracing, and other capabilities without writing custom integration code.

On performance, the team ran benchmarks on a production graph with 118,000 nodes: node search was optimized from 24 milliseconds to 0.004 milliseconds — 6,000x faster. The accompanying browser-based visualization workbench, Knowledge Explorer (React 19 + Sigma.js), features 7 panels and supports timeline playback for intuitive observation of how the graph "grows" over time. Sigma.js is a JavaScript library designed specifically for large-scale graph visualization, based on WebGL rendering, capable of smoothly displaying interactive graphs with tens of thousands of nodes in the browser — an order of magnitude more performant than D3.js's SVG rendering approach for large graph scenarios.

A Boundary That Must Be Made Crystal Clear

After discussing all these strengths, one thing must be made absolutely clear — the authors themselves highlighted it in a bold warning box in the README: Semantica provides system-level explainability, not foundation model explainability.

The difference between these two statements is fundamental. The internal reasoning process of a large language model — how the chain of thought unfolds, how attention is allocated — is a black box to any external system, and Semantica can't reach inside. Current academic research on model internal explainability focuses mainly on Mechanistic Interpretability, attempting to understand "why the model thinks this way" by analyzing model weights, activation patterns, and internal representations. But these techniques are still in early research stages, far from engineering-ready. What Semantica explains is what happens outside the model: what data was fed in, what decision was output, where the facts came from, which rules were followed.

In other words, it can answer "why the system did this" but not "why the model thought this." This clear boundary declaration actually builds more trust — it knows what it doesn't do. This design philosophy is also pragmatic from an engineering standpoint: regulators typically don't care about the internal mathematical process of the model — they care about "based on what data, following what rules, reaching what conclusion" — that complete evidence chain, which is precisely what Semantica excels at.

The latest version 0.6.6 fixes a batch of privately disclosed security vulnerabilities, including path traversal in backup restoration, SQL injection in data export, SSRF rebinding, and stored XSS. These vulnerability types cover multiple categories from the OWASP Top 10. Path Traversal attacks allow attackers to access arbitrary files on the server by constructing special file paths (e.g., ../../etc/passwd); SSRF Rebinding (DNS Rebinding) is a more covert attack where the attacker first resolves a domain to a legitimate IP to pass validation, then quickly switches to an internal IP to access internal services that shouldn't be exposed. The fact that an open-source project receives Responsible Disclosure vulnerability reports and patches each one before releasing a new version demonstrates that real production environments are seriously using it — and the user list on the official website confirms this: Siemens, Australian grid operator Ausgrid, and BDT, a private commercial bank managing over $50 billion in assets.

Who Should Take a Serious Look at Semantica

The criteria are simple: if your AI system makes decisions that need to be explained to third parties — financial risk management, medical assistance, legal research, government governance — then Semantica is ready-made infrastructure. Conversely, if you're building chatbot assistants or content generation tools, you probably don't need it.

The cost barrier is low: core functionality is open-source and free, self-hosting is supported, and data never leaves your own data center — especially friendly for data-sensitive industries.

Zooming out one more level: as the AI industry has evolved to this point, the gap in model capabilities is narrowing. The next watershed is whether results can be trusted. The EU AI Act officially took effect in August 2024, becoming the world's first comprehensive AI regulatory legislation. The act classifies AI systems into four risk levels: unacceptable risk (prohibited), high risk (strictly regulated), limited risk (transparency obligations), and minimal risk (largely unregulated). Financial credit assessment, medical diagnostic assistance, judicial sentencing recommendations, and similar scenarios are explicitly categorized as "high risk," requiring deployers to implement complete risk management systems, data governance, technical documentation, logging, and human oversight mechanisms. Article 12 (Logging) specifically requires high-risk AI systems to have automatic event logging capabilities, with logs covering input data, system behavior, and output results during operation, retained for no less than 6 months. Maximum fines for violations can reach 7% of global annual revenue or €35 million (whichever is higher). While the US hasn't enacted unified federal legislation, the NIST AI Risk Management Framework, New York City's Local Law 144 (audit requirements for hiring AI), and AI transparency bills emerging across various states are all tightening in the same direction. "Auditability" is shifting from a nice-to-have to a market entry requirement. Projects like Semantica ensure every AI decision leaves a verifiable evidence chain. This space still has few players, and it's worth watching closely.