PyReason: Graph-Based Temporal Logic for Explainable AI

Hook

Most AI systems can't explain why they reached a conclusion. PyReason tracks every logical step through time, making it the rare reasoning engine that shows its work—critical when lives or regulations are on the line.

Context

Modern machine learning excels at pattern recognition but struggles with explainability and logical reasoning. A neural network might flag a transaction as fraudulent with 87% confidence, but it can't tell you which relationships and temporal sequences led to that conclusion. Conversely, traditional logic programming systems like Prolog handle deductive reasoning well but struggle with uncertainty, temporal dynamics, and the graph-structured data that dominates real-world applications.

PyReason emerged from this gap in the neurosymbolic AI landscape. Researchers needed a system that could reason over evolving graph structures—social networks, supply chains, cybersecurity logs—while handling incomplete information and tracking inference provenance. The tool combines temporal logic (reasoning about how facts change over time), annotated logic with real-valued bounds (representing uncertainty as intervals), and graph-based knowledge representation. This trifecta enables applications where you need both the pattern-matching power of modern AI and the explainability of symbolic systems: medical diagnosis support, fraud detection, scientific hypothesis generation, and compliance verification.

Technical Insight

PyReason's architecture centers on a forward-chaining inference engine that propagates logical conclusions through a graph over discrete time steps. Unlike classical logic systems that operate on a closed-world assumption (what isn't known is false), PyReason embraces open-world reasoning where absence of evidence isn't evidence of absence. This is implemented through annotated logic with lower and upper bounds—a fact can be [0.6, 0.8] true, representing uncertainty ranges rather than binary truth values.

The system uses a three-layer architecture: a graph representation layer (built on NetworkX-style structures), a rule engine layer that processes temporal logic rules, and a Numba-optimized computation layer for performance. Here's a practical example of defining rules for a social network scenario:

import pyreason as pr

# Initialize PyReason with a graph
pr.reset()
pr.load_graph('social_network.graphml')

# Define initial facts with uncertainty bounds
pr.add_fact(pr.Fact('person_1', 'suspicious', [0.7, 0.9], 0, 0))

# Create a temporal rule: if person A is suspicious at time t
# and A communicates with B, then B becomes suspicious at t+1
rule = pr.Rule(
    'suspicious_contact',
    [
        pr.Clause('person', 'suspicious', [l, u]),
        pr.Clause('person', 'communicates_with', 'person2')
    ],
    pr.Clause('person2', 'suspicious', [l*0.8, u*0.8]),
    temporal_offset=1
)
pr.add_rule(rule)

# Run inference for 10 time steps
interpretation = pr.reason(timesteps=10)

# Extract results and provenance
suspicious_people = interpretation.get_facts('suspicious', timestep=5)
for person, bounds in suspicious_people:
    provenance = interpretation.get_provenance(person, 'suspicious', 5)
    print(f"{person}: {bounds} (derived from: {provenance})")

This code demonstrates PyReason's temporal reasoning capabilities. The rule doesn't just propagate suspicion instantaneously—it models how information spreads through social networks over time. The bounds [l0.8, u0.8] represent decay in certainty as information propagates (suspicion of a contact is slightly less certain than suspicion of the original person).

The temporal_offset parameter is crucial: it means the conclusion appears one time step after the premises are satisfied. You can chain multiple rules with different temporal offsets to model complex dynamic systems. For instance, in cybersecurity, you might model: initial network scan → reconnaissance (t+1) → exploitation attempt (t+2) → data exfiltration (t+3).

PyReason's rule syntax supports several operators for working with annotated bounds. You can use l and u variables in the conclusion to reference lower and upper bounds from premises, apply arithmetic operations, and even compare bounds across multiple premises. The system automatically handles bound propagation using interval arithmetic, ensuring logical consistency throughout the inference process.

Performance optimization comes from Numba's JIT compilation. The core inference loop—checking which rules fire, updating graph attributes, propagating bounds—is compiled to machine code. For Python 3.9+, PyReason supports multi-core parallelism, distributing rule evaluation across CPU cores. This is particularly valuable when you have hundreds of rules and thousands of nodes:

# Enable parallel execution (Python 3.9+ only)
interpretation = pr.reason(
    timesteps=20,
    parallel=True,
    num_cores=8
)

The provenance tracking is where PyReason truly shines for explainable AI applications. Every derived fact maintains a complete lineage: which rules fired, which premises were satisfied, and the specific graph elements involved. This creates an audit trail from initial facts to final conclusions. In regulated industries—healthcare, finance, defense—this explainability isn't a nice-to-have; it's mandatory.

One architectural choice worth noting: PyReason separates the graph structure from the attributes being reasoned about. You can load a fixed graph topology and reason about changing attributes over time, or you can modify the graph structure itself between time steps. This flexibility supports scenarios from static knowledge graphs with evolving properties to fully dynamic networks where both nodes/edges and their attributes change.

Gotcha

PyReason's Python version constraints bite harder than you'd expect. The Numba dependency locks you into Python 3.7-3.10, and parallel execution only works on 3.9-3.10. If your organization has standardized on Python 3.11+ (released in 2022), you're stuck waiting for Numba compatibility updates or running PyReason in an isolated older environment. This versioning constraint ripples through your entire dependency stack—you can't use newer libraries that require Python 3.11+ in the same project.

The forward-chaining approach has computational implications that aren't obvious at first. Each time step evaluates every rule against every matching subgraph pattern. On a graph with 10,000 nodes and 50 rules, even with Numba optimization, you're looking at significant computation per time step. The complexity scales with the number of rules, graph size, and rule complexity (how many clauses each rule has). For real-time applications requiring sub-second response times on large graphs, PyReason might not cut it. The explainability comes at a performance cost compared to approximate methods or neural approaches.

The learning curve is steep if you're not already familiar with temporal logic and annotated logic frameworks. The documentation provides examples, but understanding how to structure rules for your specific domain, how bound propagation works, and how to tune the system for performance requires investment. Expect a few weeks of experimentation before you're productive. Additionally, the annotated logic with bounds is less intuitive than probabilistic logic programming—you're not working with probabilities but with lower and upper bounds that represent epistemic uncertainty. This requires a different mental model and careful rule design to ensure bounds propagate meaningfully.

Verdict

Use PyReason if you're building neurosymbolic AI systems where explainability is non-negotiable—cybersecurity threat analysis, medical decision support, regulatory compliance checking, or scientific hypothesis generation. It's ideal when you have graph-structured data that evolves over time and you need to maintain complete provenance of inferences. The uncertainty handling through annotated bounds works well for domains with incomplete information where you need to reason defensively (open-world assumption). If you're integrating symbolic reasoning with ML pipelines and need the symbolic component to show its work, PyReason delivers. Skip it if you need bleeding-edge Python versions, require real-time inference on massive graphs (millions of nodes), or are solving problems that don't genuinely need temporal logic and explainability. For pure graph analytics, use NetworkX or Neo4j. For probabilistic reasoning without temporal aspects, ProbLog or Stan are more mature. For classical logic programming, stick with Prolog. PyReason occupies a specific niche—graph-based temporal reasoning with uncertainty and explainability—and excels there, but it's overkill for simpler use cases.