API Reference¶

Module-Level Functions¶

set_logging_level(level)¶

Set the logging level for the library.

Parameters:: level (int) – Logging level from 0 (TRACE) to 5 (FATAL)

Logging levels:

0 - TRACE: Most verbose
1 - DEBUG: Debug information
2 - INFO: Informational messages
3 - WARNING: Warning messages (default)
4 - ERROR: Error messages
5 - FATAL: Fatal errors only

Example:

import triggergraphs as tg
tg.set_logging_level(2)  # Set to INFO level

EDBLayer¶

class EDBLayer(confPath='')¶

The Extensional Database Layer manages base facts.

Parameters:: confPath (str) – Path to configuration file (optional)

add_csv_source(predname, rows)¶

Add an in-memory CSV source for a predicate.

Parameters:

predname (str) – Name of the predicate
rows (list[list[str]]) – List of fact tuples, where each tuple is a list of strings

Example:

edb.add_csv_source("person", [["alice"], ["bob"]])
edb.add_csv_source("edge", [["a", "b"], ["b", "c"]])

replace_facts_csv_source(predname, rows)¶

Replace all facts for an existing CSV source.

Parameters:

predname (str) – Name of the predicate
rows (list[list[str]]) – New list of fact tuples

add_source(predname, obj)¶

Add a custom Python object as a data source.

Parameters:

predname (str) – Name of the predicate
obj (object) – Python object implementing the table interface

get_term_id(term)¶

Get the numerical ID for a term string.

Parameters:: term (str) – The term string
Returns:: The term ID, or None if not found
Return type:: int or None

get_n_terms()¶

Get the total number of unique terms in the database.

Returns:: Number of terms
Return type:: int

get_n_predicates()¶

Get the number of predicates in the EDB.

Returns:: Number of predicates
Return type:: int

get_predicates()¶

Get a list of all EDB predicate names.

Returns:: List of predicate names
Return type:: list[str]

get_facts(predicate_name)¶

Get all facts for a given predicate as term IDs.

Parameters:: predicate_name (str) – Name of the predicate
Returns:: List of fact tuples (as term IDs)
Return type:: list[list[int]]

Example:

facts = edb.get_facts("person")
# Returns: [[123], [456]] where 123 and 456 are term IDs

Program¶

class Program(edb)¶

A Datalog program containing rules.

Parameters:: edb (EDBLayer) – The EDB layer to use

add_rule(rule)¶

Add a Datalog rule to the program.

Parameters:: rule (str) – The rule in Datalog syntax
Returns:: The rule ID
Return type:: int
Raises:: RuntimeError – If the rule syntax is invalid

Example:

program.add_rule("ancestor(X,Y) :- parent(X,Y)")

load_from_file(path)¶

Load rules from a file.

Parameters:: path (str) – Path to the rules file
Raises:: RuntimeError – If file does not exist

get_n_rules()¶

Get the number of rules in the program.

Returns:: Number of rules
Return type:: int

get_rule(ruleIdx)¶

Get a rule as a string.

Parameters:: ruleIdx (int) – Index of the rule
Returns:: The rule string
Return type:: str

get_predicate_name(predId)¶

Get the name of a predicate by its ID.

Parameters:: predId (int) – Predicate ID
Returns:: Predicate name
Return type:: str

apply_magic_transform(query)¶

Apply magic set transformation for a query.

Parameters:: query (str) – Query literal in Datalog syntax
Returns:: Tuple of (transformed_program, input_pred_id, output_pred_id)
Return type:: tuple

Example:

new_prog, in_id, out_id = program.apply_magic_transform("ancestor(alice,X)")

Reasoner¶

class Reasoner(typeChase, edb, program, queryCont=True, edbCheck=True, rewriteCliques=True, tgpath='', typeProv='NOPROV', delProofs=True)¶

The reasoning engine that executes Datalog rules.

Parameters:

typeChase (str) – Type of chase algorithm (“tgchase”, “tgchase_static”, or “probtgchase”)
edb (EDBLayer) – The EDB layer
program (Program) – The program to execute
queryCont (bool) – Enable query containment optimization
edbCheck (bool) – Check EDB during reasoning
rewriteCliques (bool) – Enable clique rewriting
tgpath (str) – Path to save trigger graph (empty for in-memory)
typeProv (str) – Provenance type (“NOPROV”, “NODEPROV”, or “FULLPROV”)
delProofs (bool) – Delete proofs (for probabilistic chase)

create_model(startStep=0, maxStep=2 ^ 64 - 1)¶

Execute reasoning and materialize facts.

Parameters:

startStep (int) – Starting step number
maxStep (int) – Maximum step number

Returns:

Dictionary of statistics

Return type:

dict

Returns a dictionary with keys:

n_nodes: Number of nodes in the trigger graph
n_edges: Number of edges in the trigger graph
n_triggers: Number of trigger firings
n_derivations: Number of derived facts
steps: Number of reasoning steps executed
max_mem_mb: Maximum memory used (MB)
runtime_ms: Runtime in milliseconds

get_TG()¶

Get the trigger graph after reasoning.

Returns:: The trigger graph
Return type:: TG

TG (Trigger Graph)¶

class TG(reasoner)¶

Represents the trigger graph structure.

Parameters:: reasoner (Reasoner) – The reasoner that created this TG

get_n_nodes()¶

Get the number of nodes in the trigger graph.

Returns:: Number of nodes
Return type:: int

get_n_edges()¶

Get the number of edges in the trigger graph.

Returns:: Number of edges
Return type:: int

get_n_facts()¶

Get the total number of facts in the trigger graph.

Returns:: Number of facts
Return type:: int

get_node_size(nodeId)¶

Get the number of facts in a specific node.

Parameters:: nodeId (int) – ID of the node
Returns:: Number of facts in the node
Return type:: int

add_node(predid, step, facts)¶

Add a node to the trigger graph with facts.

Parameters:

predid (int) – Predicate ID
step (int) – Reasoning step
facts (list[list[str]]) – List of fact tuples

dump_files(path='')¶

Export the trigger graph to files.

Parameters:: path (str) – Directory path for output files

Querier¶

class Querier(tg)¶

Query interface for extracting facts and provenance from a trigger graph.

Parameters:: tg (TG) – The trigger graph to query

get_all_facts()¶

Get all derived facts organized by predicate.

Returns:: Dictionary mapping predicate names to lists of fact tuples
Return type:: dict[str, list[list[str]]]

Example:

facts = querier.get_all_facts()
# Returns: {"ancestor": [["alice", "bob"], ["bob", "charlie"]], ...}

get_list_predicates()¶

Get a list of all predicates in the trigger graph.

Returns:: List of predicate names
Return type:: list[str]

get_facts_coordinates_with_predicate(predName)¶

Get facts and their coordinates (node ID and offset) for a predicate.

Parameters:: predName (str) – Predicate name
Returns:: List of tuples: (fact_tuple, (node_id, offset))
Return type:: list

get_node_details_predicate(predName)¶

Get detailed node information for a predicate as JSON.

Parameters:: predName (str) – Predicate name
Returns:: JSON string with node details
Return type:: str

get_facts_in_TG_node(nodeId)¶

Get all facts in a specific trigger graph node as JSON.

Parameters:: nodeId (int) – Node ID
Returns:: JSON string with facts
Return type:: str

get_derivation_tree(nodeId, factId)¶

Get the derivation tree for a fact as JSON.

Parameters:

nodeId (int) – Node ID
factId (int) – Fact ID within the node

Returns:

JSON string representing the derivation tree

Return type:

str

get_derivation_tree_in_TupleSet(tupleSet, factId)¶

Get derivation tree for a fact in a TupleSet.

Parameters:

tupleSet (TupleSet) – The tuple set
factId (int) – Fact ID

Returns:

JSON string representing the derivation tree

Return type:

str

get_leaves(nodeId, factId)¶

Get the base facts (leaves) used in a derivation.

Parameters:

nodeId (int) – Node ID
factId (int) – Fact ID

Returns:

List of leaf literal sets

Return type:

list

get_fact_in_TupleSet(tupleSet, factId)¶

Get a specific fact from a TupleSet.

Parameters:

tupleSet (TupleSet) – The tuple set
factId (int) – Fact ID

Returns:

Fact as a list of terms

Return type:

list[str]

get_predicate_name(predicateId)¶

Get predicate name from its ID.

Parameters:: predicateId (int) – Predicate ID
Returns:: Predicate name
Return type:: str

get_term_name(termId)¶

Get term string from its ID.

Parameters:: termId (int) – Term ID
Returns:: Term string
Return type:: str

TupleSet¶

class TupleSet¶

Represents a set of tuples (facts).

get_n_facts()¶

Get the number of facts in this tuple set.

Returns:: Number of facts
Return type:: int