Semantica’s reasoning layer encodes domain logic as rules and applies it to your knowledge graph to derive conclusions that no single document states explicitly. Eight complementary reasoning modes — from symbol-rule forward chaining to recursive Datalog and LLM-backed freeform queries — let you choose the right tool for each inference problem without switching frameworks.

​
What Is Reasoning?

Reasoning derives implicit knowledge from explicit facts using logical rules. Unlike retrieval, search, or graph traversal, reasoning generates new conclusions that weren’t directly stated in your original data. Reasoning vs. Retrieval: Retrieval finds existing information that matches your query. Reasoning applies logical rules to derive new facts that weren’t explicitly stored. Reasoning vs. Search: Search matches keywords or semantic similarity. Reasoning uses logical inference to conclude facts like “if A implies B, and A is true, then B must be true.” Reasoning vs. Graph Traversal: Traversal follows existing edges between nodes. Reasoning can infer new relationships based on rules — for example, concluding that two entities are related even if no direct edge exists.

​
Why Use Reasoning?

Deriving implicit knowledge. Documents might state “APT29 uses SUNBURST” and “SUNBURST exploits CVE-2020-10148” separately, but reasoning concludes “APT29 exploits CVE-2020-10148” automatically. Identifying patterns. Rules can detect complex patterns across your knowledge graph — threat actors that share TTPs, suppliers in transitive relationships, or compliance violations that emerge from combinations of conditions. Supporting investigations. Reasoning helps analysts by highlighting non-obvious connections, flagging entities that meet risk criteria, and explaining why conclusions were reached. Decision support. Encode policies, regulations, or business rules as logical statements. Reasoning engines evaluate them consistently and provide audit trails for decisions.

​
When To Use / When Not To Use

Use reasoning for:
  • Complex domains with well-defined logical relationships
  • Policy enforcement and compliance checking
  • Multi-step inference where conclusions depend on chains of facts
  • Situations requiring explainable decisions with audit trails
  • Identifying implicit relationships that aren’t explicitly stated
Retrieval may be sufficient for:
  • Finding documents or information that directly answers your question
  • Exploratory research where you don’t know what patterns to look for
  • Simple keyword or semantic searches
Graph traversal may be sufficient for:
  • Following explicit relationships between entities
  • Neighborhood analysis around known starting points
  • Path-finding between entities with direct connections
Reasoning provides additional value when:
  • Your domain has logical rules that can infer new facts
  • You need to detect patterns that require multiple conditions
  • Decisions must be explainable and auditable
  • Implicit relationships are as important as explicit ones

​
Key Reasoning Concepts

Datalog is a logic programming language based on rules and facts. Facts are simple statements like “parent(tom, bob)”. Rules derive new facts: “grandparent(X, Z) :- parent(X, Y), parent(Y, Z)”. Datalog excels at recursive queries and transitive relationships. SPARQL is a query language for RDF data that can incorporate inference rules. It uses triple patterns to match graph data and can be extended with reasoning to derive implicit triples before querying. RETE is an algorithm for efficiently evaluating many rules against a working memory of facts. It builds a network that avoids re-evaluating unchanged conditions, making it suitable for systems with hundreds of rules or streaming data. Rule-based inference applies “if-then” rules to derive new conclusions. Forward chaining applies all applicable rules to derive everything possible. Backward chaining works backwards from a goal to find the minimal proof.

​
How Graph Data Becomes Reasoning Facts

When using DatalogReasoner.load_from_graph(), your knowledge graph’s nodes and edges are converted into Datalog facts. All predicates and arguments are lowercased:
  • A node with type “ThreatActor” and id “APT29” becomes threatactor(apt29)
  • An edge from APT29 to SUNBURST with type “uses” becomes uses(apt29, sunburst)
The reasoning engine treats these facts as the starting point for inference, applying rules to derive new conclusions that get added to working memory.
The reasoning module operates over facts you supply directly or load from a ContextGraph. Derived facts are added to working memory and are immediately available for further inference in the same session. To persist derived facts back into the graph, pass them to AgentContext.store().

​
Choosing a reasoning mode

​
Step 1 — Ground facts and working memory

The Reasoner class maintains a set of ground facts and a list of rules. Facts can be added as predicate strings or loaded from a ContextGraph. Start with the explicit knowledge your extraction pipeline produced:
These ground facts represent what documents explicitly stated. The rules you add next tell the system what those facts imply.

​
Step 2 — Forward chaining: materialising derived facts

Forward chaining starts from ground facts and applies every matching rule until no new conclusions can be drawn — reaching fixpoint:
DELTA-3 is flagged even though no document described it that way — the system traced: DELTA-3 supplied GAMMA-7, and GAMMA-7 exploits critical CVEs. For rules that need priority ordering or graded confidence, use the Rule dataclass:

​
Step 3 — Backward chaining: proving a specific goal

Backward chaining tests a single hypothesis by working backward through rules — the right tool when you need a yes/no answer and the minimal evidence chain without deriving every other possible fact first:
The premises list is the explanation chain — each item is a fact that was necessary to reach the conclusion. Show this to analysts when they ask “why is DELTA-3 classified as high-risk?”

​
Step 4 — Recursive inference with Datalog

DatalogReasoner handles questions requiring arbitrary-depth traversal — “which actors can transitively reach critical infrastructure?” — using recursive Horn clause rules with semi-naive bottom-up fixpoint evaluation:
DELTA-3 appears even though no document connects it directly to critical infrastructure. Datalog traced the full chain: delta3 → gamma7 → apt29_affiliate → apt29 → nato_logistics → critical_infrastructure. Bind variables to ask directed questions:
Skip manual add_fact() calls by loading a ContextGraph directly:

​
Step 5 — SPARQL queries over enriched working memory

After forward chaining has derived new facts, SPARQLReasoner lets you query the enriched working memory using SPARQL triple-pattern matching with optional inference expansion:
Inspect the expanded query before running it:

​
Step 6 — RETE engine for large rule sets

ReteEngine implements the RETE algorithm — a network of alpha nodes (single-condition matching) and beta nodes (join operations) that avoids re-evaluating unchanged conditions on every new fact. Use it when you have 100+ rules or need incremental fact propagation in a streaming or event-driven setting:
The rule network is compiled once by build_network(). Each subsequent add_fact() call propagates incrementally through only the nodes whose conditions it satisfies — not the full rule set — which keeps evaluation cost proportional to the number of new activations rather than the total rule count.

​
Step 7 — Temporal interval reasoning

TemporalReasoningEngine computes Allen interval relations between time windows, letting you identify whether two events overlap, one contains the other, they meet at a boundary, and so on across your graph:
The 13 Allen relations cover every possible temporal relationship: An OVERLAPS or EQUALS result between two campaigns attributed to different actors is a signal worth flagging for analyst review — a temporal coincidence is a hypothesis, not a conclusion.

​
Step 8 — LLM-based graph reasoning

GraphReasoner routes freeform natural language queries through an LLM provider, using the graph as grounded context. Use it for exploratory questions that do not map cleanly to a predefined rule set:
GraphReasoner is well suited for early-stage investigation — when the question is exploratory and you have not yet formalised inference rules. For reproducible, auditable decisions, use Reasoner or DatalogReasoner instead.

​
Step 9 — Explaining inferences in natural language

ExplanationGenerator translates any InferenceResult (from forward or backward chaining) into a human-readable explanation, a step-by-step ReasoningPath, and a Justification with supporting evidence:
Three detail levels control explanation verbosity: "simple" gives a one-line summary, "detailed" lists premises and the rule name, and "verbose" produces a full confidence-annotated narrative.

​
Putting it together: a complete reasoning pipeline

A pipeline combining forward chaining, Datalog reachability, and natural language explanations for a threat intelligence graph:

​
Domain examples

Attribution chains in threat intelligence require multi-hop confidence propagation: a TTP match raises the probability of actor attribution, corroborating ASN geolocation raises it further, and a known targeting pattern for the attributed sector raises it to actionable confidence. Each hop is a separate rule with its own confidence weight, and InferenceResult carries the propagated value through the chain.

​
Common Pitfalls

Overusing reasoning. Not every query needs inference. If you can answer your question with simple retrieval or graph traversal, reasoning adds unnecessary complexity. Use reasoning when you need to derive facts that aren’t explicitly stated. Poor graph quality. Reasoning amplifies data quality issues. If your graph has inconsistent entity names, missing relationships, or incorrect facts, reasoning will propagate these errors. Clean your graph data before applying inference rules. Treating inferred facts as verified facts. Reasoning conclusions are only as reliable as the rules and facts they’re based on. An inferred fact like “HighRiskActor(APT29)” reflects your rule logic, not ground truth. Always distinguish between observed facts and inferred conclusions. Excessive rule complexity. Complex rules with many conditions are hard to debug and maintain. Start with simple rules and add complexity gradually. A rule with 10 conditions probably should be broken into smaller, more focused rules. Recursive reasoning on large datasets. Recursive Datalog rules can generate exponential numbers of derived facts on large graphs. Monitor working memory size and add depth limits or termination conditions to prevent runaway inference.
  • Semantic Extraction — extract the entities and relationships that populate the graph facts you reason over
  • GraphRAG — retrieve graph-grounded context for LLM responses
  • Ontology Management — generate OWL ontologies to give your rules formal semantics
  • Decision Intelligence — record and trace inferred decisions through the full causal chain
  • Context Graphs — the knowledge graph that reasoning operates over
  • MCP Server — expose run_reasoning as a tool for Claude and other agents