neuralogic.core.builder package

Submodules

neuralogic.core.builder.builder module

class Builder(settings: SettingsProxy)[source]

Bases: object

Builder is responsible for grounding, neuralizing, and building models from models and sources.

build_model(parsed_model: Any, settings: SettingsProxy) → Any[source]

Builds a neural model from the parsed model.

Parameters:

  • parsed_model (Any) – The parsed model.

  • settings (SettingsProxy) – The settings proxy.

Returns:

The built neural model.

Return type:

Any

build_model_from_file(settings: SettingsProxy, filename: str) → Any[source]

Builds a model from a file.

Parameters:

  • settings (SettingsProxy) – The settings proxy.

  • filename (str) – The path to the model file.

Returns:

The built model.

Return type:

Any

static get_builders(settings: SettingsProxy) → Any[source]
ground_from_logic_samples(parsed_model: Any, logic_samples: list[Any], progress: bool) → Any[source]

Grounds the model from the provided logic samples.

Parameters:

  • parsed_model (Any) – The parsed model.

  • logic_samples (list[Any]) – The logic samples.

  • progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

ground_from_sources(parsed_model: Any, sources: Sources, progress: bool) → Any[source]

Grounds the model from the provided sources.

Parameters:

  • parsed_model (Any) – The parsed model.

  • sources (Sources) – The logic sources.

  • progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

neuralize(groundings, progress: bool, length: int | None) → list[NeuralSample][source]

Neuralizes the grounding samples.

Parameters:

  • groundings (Any) – The logic groundings to neuralize.

  • progress (bool) – Whether to show progress.

  • length (int, optional) – The total number of groundings. Default: None.

Returns:

The neuralized samples.

Return type:

list[NeuralSample]

stream_to_list(stream: Any) → list[source]

Converts a Java stream to a Python list.

Parameters:

stream (Any) – The Java stream to convert.

Returns:

The converted Python list.

Return type:

list

neuralogic.core.builder.components module

class Atom(atom: Any, substitutions: dict[str, Any])[source]

Bases: object

Represents an atom in the logic program, often corresponding to a node in the neural network.

property arity: int
node_type() → NeuronType[source]

Returns the type of the neuron.

Returns:

The type of the neuron.

Return type:

NeuronType

property predicate: str
substitutions
class Grounding(grounding: Any)[source]

Bases: object

Represents a grounded model, providing access to grounded atoms and facts.

property atoms: dict[str, dict[tuple[str, ...], Any]]
draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, settings: DrawingSettings | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the grounding.

Parameters:

  • filename (str, optional) – The filename to save the drawing to. Default: None.

  • show (bool) – Whether to show the drawing. Default: True.

  • img_type (str) – The image type. Default: β€œpng”.

  • value_detail (int) – The level of detail for values. Default: 0.

  • graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

  • settings (DrawingSettings, optional) – Styling settings. When provided, they control value detail and graph styling.

Returns:

The drawing data or image object.

Return type:

Any

get_atoms(literal: Any) → list[Atom][source]

Returns a list of grounded atoms matching the provided literal.

Parameters:

literal (Any) – The literal to match.

Returns:

The list of matching grounded atoms.

Return type:

list[Atom]

class NeuralSample(sample: Any)[source]

Bases: object

Represents a single training or testing sample, containing the query and its associated neural network (evidence).

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, settings: DrawingSettings | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the neural sample.

Parameters:

  • filename (str, optional) – The filename to save the drawing to. Default: None.

  • show (bool) – Whether to show the drawing. Default: True.

  • img_type (str) – The image type. Default: β€œpng”.

  • value_detail (int) – The level of detail for values. Default: 0.

  • graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

  • settings (DrawingSettings, optional) – Styling settings. When provided, they control value detail and graph styling.

Returns:

The drawing data or image object.

Return type:

Any

get_fact(fact: Any) → list[Neuron][source]

Returns the neuron corresponding to the provided fact.

Parameters:

fact (Any) – The fact to look for.

Returns:

The matching fact neuron(s).

Return type:

list[Neuron]

get_neurons(literal: Any, neuron_type: NeuronType | None = NeuronType.Atom) → list[Neuron][source]

Returns a list of neurons matching the provided literal and neuron type.

Parameters:

  • literal (Any) – The literal to match.

  • neuron_type (NeuronType, optional) – The type of neurons to search for. Default: NeuronType.Atom.

Returns:

The list of matching neurons.

Return type:

list[Neuron]

property neurons: dict[str, dict[str, dict[tuple[str, ...], Any]]]
set_fact_value(fact: Any, value: float) → int[source]

Sets the value of a specific fact in the sample.

Parameters:

  • fact (Any) – The fact to set the value for.

  • value (float) – The value to set.

Returns:

The index of the fact neuron, or -1 if not found.

Return type:

int

property target: float | list | ndarray
class Neuron(neuron: Any, substitutions: dict[str, Any])[source]

Bases: Atom

Represents a neuron in the neural network, extending the Atom class with value and gradient properties.

property gradient: float | list | ndarray
substitutions
property value: float | list | ndarray
class NeuronType(value)[source]

Bases: str, Enum

Enum representing different types of neurons in the neural network.

Aggregation = 'AggregationNeuron'
Atom = 'AtomNeuron'
Fact = 'FactNeuron'
Negation = 'NegationNeuron'
Rule = 'RuleNeuron'
SplittableAggregation = 'SplittableAggregationNeuron'
WeightedAtom = 'WeightedAtomNeuron'
WeightedRule = 'WeightedRuleNeuron'

neuralogic.core.builder.dataset module

class BuiltDataset(samples: list[NeuralSample], batch_size: int)[source]

Bases: object

BuiltDataset represents an already built dataset - that is, a dataset that has been grounded and neuralized.

load_state_dict(state_dict: dict, strict: bool = True) → IncompatibleKeys[source]

Sets this dataset’s example-fact parameters from a state_dict() shaped dictionary.

With strict=False this is also how a parameter reaches a dataset it was not trained on - the embeddings learned for the training set, carried onto the test set for the constants the two share:

test_data.load_state_dict(train_data.state_dict(), strict=False)

A constant the training set never saw keeps whatever its example wrote, untrained, and comes back in missing_keys; a trained parameter with no fact to attach to here comes back in unexpected_keys. Both are ordinary in that use and neither is in the round trip of one dataset, which is why strict defaults to refusing them.

Parameters:

  • state_dict (dict) – {"weights": {literal: value}}.

  • strict (bool) – Whether the literals must match this dataset’s exactly, as in torch. Default: True.

Returns:

missing_keys - this dataset’s learnable facts the dictionary said nothing about - and unexpected_keys - literals in the dictionary this dataset has no learnable fact for.

Return type:

IncompatibleKeys

Raises:

ValueError – Under strict, if either list is non-empty: the saved parameters and the data have drifted apart, and carrying on would leave a model half restored. Always, if two literals that share one weight are given different values - facts share a weight when the example named it, and then only one of the two values could survive, which one being an accident of iteration order.

state_dict() → dict[source]

The learnable values this dataset’s own example facts carry, keyed by ground literal.

A value written on an example fact and made learnable with learnable_facts=True is a real parameter - it trains - but it belongs to the data, not to the template, so it is not in the model’s state_dict() and saving the model does not save it. This is where it is.

The key is the ground literal (emb(a)) because nothing else survives a rebuild: the weight’s index continues a counter that keeps running, so building the same dataset twice on one model gives the parameters indices 1, 2 and then 5, 6, and the generated weight name is w plus that index.

Returns:

{"weights": {literal: value}}, empty when the dataset was not built with learnable_facts=True.

Return type:

dict

class GroundedDataset(groundings, builder: Builder)[source]

Bases: object

GroundedDataset represents grounded examples that are not neuralized yet.

neuralize(*, batch_size: int = 1, progress: bool = False) → BuiltDataset[source]
class IncompatibleKeys(missing_keys: list[str], unexpected_keys: list[str])[source]

Bases: NamedTuple

What BuiltDataset.load_state_dict() could not match up, in torch’s shape.

missing_keys: list[str]

Alias for field number 0

unexpected_keys: list[str]

Alias for field number 1

neuralogic.core.builder.dataset_builder module

class DatasetBuilder(parsed_model: Any, java_factory: JavaFactory)[source]

Bases: object

DatasetBuilder is responsible for grounding and neuralizing datasets.

build_dataset(dataset: BaseDataset | GroundedDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False) → BuiltDataset[source]

Builds the dataset (does grounding and neuralization).

Parameters:

  • dataset (datasets.BaseDataset | GroundedDataset) – The dataset to build.

  • settings (SettingsProxy) – The settings proxy.

  • batch_size (int) – The batch size. Default: 1.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

  • progress (bool) – Whether to show progress. Default: False.

Returns:

The built dataset.

Return type:

BuiltDataset

build_examples(examples: Iterable[Any], examples_builder: Any, learnable_facts: bool = False) → tuple[list[Any], bool][source]

Builds examples from the provided examples and examples builder.

Parameters:

  • examples (Iterable) – The examples to build.

  • examples_builder (Any) – The examples builder.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there are examples with queries.

Return type:

tuple[list[Any], bool]

build_queries(queries: Iterable[Any], query_builder: Any) → tuple[list[Any], bool][source]

Builds queries from the provided queries and query builder.

Parameters:

  • queries (Iterable) – The queries to build.

  • query_builder (Any) – The query builder.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there is one query per example.

Return type:

tuple[list[Any], bool]

ground_dataset(dataset: BaseDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False, raw_groundings: bool = False) → GroundedDataset | Any[source]

Grounds the dataset.

Parameters:

  • dataset (datasets.BaseDataset) – The dataset to ground.

  • settings (SettingsProxy) – The settings proxy.

  • batch_size (int) – The batch size. Default: 1.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

  • progress (bool) – Whether to show progress. Default: False.

  • raw_groundings (bool) – Whether to return raw groundings. Default: False.

Returns:

The grounded dataset or raw groundings.

Return type:

GroundedDataset | Any

static merge_queries_with_examples(queries: list[Any], examples: list[Any], one_query_per_example: bool, example_queries: bool = True) → list[Any][source]

Merges queries with their corresponding examples.

Parameters:

  • queries (list[Any]) – The list of queries.

  • examples (list[Any]) – The list of examples.

  • one_query_per_example (bool) – Whether there is one query per example.

  • example_queries (bool) – Whether examples contain queries. Default: True.

Returns:

The list of merged logic samples.

Return type:

list[Any]

samples_to_examples_and_queries(samples: list[Any]) → tuple[Iterable[Any], Iterable[Any]][source]

Converts a list of samples to two lists: examples and queries.

Parameters:

samples (list[Any]) – The list of samples.

Returns:

A tuple containing the iterable of examples and the iterable of queries.

Return type:

tuple[Iterable[Any], Iterable[Any]]

Module contents

class Atom(atom: Any, substitutions: dict[str, Any])[source]

Bases: object

Represents an atom in the logic program, often corresponding to a node in the neural network.

property arity: int
node_type() → NeuronType[source]

Returns the type of the neuron.

Returns:

The type of the neuron.

Return type:

NeuronType

property predicate: str
substitutions
class Builder(settings: SettingsProxy)[source]

Bases: object

Builder is responsible for grounding, neuralizing, and building models from models and sources.

build_model(parsed_model: Any, settings: SettingsProxy) → Any[source]

Builds a neural model from the parsed model.

Parameters:

  • parsed_model (Any) – The parsed model.

  • settings (SettingsProxy) – The settings proxy.

Returns:

The built neural model.

Return type:

Any

build_model_from_file(settings: SettingsProxy, filename: str) → Any[source]

Builds a model from a file.

Parameters:

  • settings (SettingsProxy) – The settings proxy.

  • filename (str) – The path to the model file.

Returns:

The built model.

Return type:

Any

static get_builders(settings: SettingsProxy) → Any[source]
ground_from_logic_samples(parsed_model: Any, logic_samples: list[Any], progress: bool) → Any[source]

Grounds the model from the provided logic samples.

Parameters:

  • parsed_model (Any) – The parsed model.

  • logic_samples (list[Any]) – The logic samples.

  • progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

ground_from_sources(parsed_model: Any, sources: Sources, progress: bool) → Any[source]

Grounds the model from the provided sources.

Parameters:

  • parsed_model (Any) – The parsed model.

  • sources (Sources) – The logic sources.

  • progress (bool) – Whether to show progress.

Returns:

The grounded logic samples.

Return type:

Any

neuralize(groundings, progress: bool, length: int | None) → list[NeuralSample][source]

Neuralizes the grounding samples.

Parameters:

  • groundings (Any) – The logic groundings to neuralize.

  • progress (bool) – Whether to show progress.

  • length (int, optional) – The total number of groundings. Default: None.

Returns:

The neuralized samples.

Return type:

list[NeuralSample]

class BuiltDataset(samples: list[NeuralSample], batch_size: int)[source]

Bases: object

BuiltDataset represents an already built dataset - that is, a dataset that has been grounded and neuralized.

load_state_dict(state_dict: dict, strict: bool = True) → IncompatibleKeys[source]

Sets this dataset’s example-fact parameters from a state_dict() shaped dictionary.

With strict=False this is also how a parameter reaches a dataset it was not trained on - the embeddings learned for the training set, carried onto the test set for the constants the two share:

test_data.load_state_dict(train_data.state_dict(), strict=False)

A constant the training set never saw keeps whatever its example wrote, untrained, and comes back in missing_keys; a trained parameter with no fact to attach to here comes back in unexpected_keys. Both are ordinary in that use and neither is in the round trip of one dataset, which is why strict defaults to refusing them.

Parameters:

  • state_dict (dict) – {"weights": {literal: value}}.

  • strict (bool) – Whether the literals must match this dataset’s exactly, as in torch. Default: True.

Returns:

missing_keys - this dataset’s learnable facts the dictionary said nothing about - and unexpected_keys - literals in the dictionary this dataset has no learnable fact for.

Return type:

IncompatibleKeys

Raises:

ValueError – Under strict, if either list is non-empty: the saved parameters and the data have drifted apart, and carrying on would leave a model half restored. Always, if two literals that share one weight are given different values - facts share a weight when the example named it, and then only one of the two values could survive, which one being an accident of iteration order.

state_dict() → dict[source]

The learnable values this dataset’s own example facts carry, keyed by ground literal.

A value written on an example fact and made learnable with learnable_facts=True is a real parameter - it trains - but it belongs to the data, not to the template, so it is not in the model’s state_dict() and saving the model does not save it. This is where it is.

The key is the ground literal (emb(a)) because nothing else survives a rebuild: the weight’s index continues a counter that keeps running, so building the same dataset twice on one model gives the parameters indices 1, 2 and then 5, 6, and the generated weight name is w plus that index.

Returns:

{"weights": {literal: value}}, empty when the dataset was not built with learnable_facts=True.

Return type:

dict

class DatasetBuilder(parsed_model: Any, java_factory: JavaFactory)[source]

Bases: object

DatasetBuilder is responsible for grounding and neuralizing datasets.

build_dataset(dataset: BaseDataset | GroundedDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False) → BuiltDataset[source]

Builds the dataset (does grounding and neuralization).

Parameters:

  • dataset (datasets.BaseDataset | GroundedDataset) – The dataset to build.

  • settings (SettingsProxy) – The settings proxy.

  • batch_size (int) – The batch size. Default: 1.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

  • progress (bool) – Whether to show progress. Default: False.

Returns:

The built dataset.

Return type:

BuiltDataset

build_examples(examples: Iterable[Any], examples_builder: Any, learnable_facts: bool = False) → tuple[list[Any], bool][source]

Builds examples from the provided examples and examples builder.

Parameters:

  • examples (Iterable) – The examples to build.

  • examples_builder (Any) – The examples builder.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there are examples with queries.

Return type:

tuple[list[Any], bool]

build_queries(queries: Iterable[Any], query_builder: Any) → tuple[list[Any], bool][source]

Builds queries from the provided queries and query builder.

Parameters:

  • queries (Iterable) – The queries to build.

  • query_builder (Any) – The query builder.

Returns:

A tuple containing the list of built logic samples and a boolean indicating if there is one query per example.

Return type:

tuple[list[Any], bool]

ground_dataset(dataset: BaseDataset, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False, raw_groundings: bool = False) → GroundedDataset | Any[source]

Grounds the dataset.

Parameters:

  • dataset (datasets.BaseDataset) – The dataset to ground.

  • settings (SettingsProxy) – The settings proxy.

  • batch_size (int) – The batch size. Default: 1.

  • learnable_facts (bool) – Whether facts are learnable. Default: False.

  • progress (bool) – Whether to show progress. Default: False.

  • raw_groundings (bool) – Whether to return raw groundings. Default: False.

Returns:

The grounded dataset or raw groundings.

Return type:

GroundedDataset | Any

static merge_queries_with_examples(queries: list[Any], examples: list[Any], one_query_per_example: bool, example_queries: bool = True) → list[Any][source]

Merges queries with their corresponding examples.

Parameters:

  • queries (list[Any]) – The list of queries.

  • examples (list[Any]) – The list of examples.

  • one_query_per_example (bool) – Whether there is one query per example.

  • example_queries (bool) – Whether examples contain queries. Default: True.

Returns:

The list of merged logic samples.

Return type:

list[Any]

class GroundedDataset(groundings, builder: Builder)[source]

Bases: object

GroundedDataset represents grounded examples that are not neuralized yet.

neuralize(*, batch_size: int = 1, progress: bool = False) → BuiltDataset[source]
class Grounding(grounding: Any)[source]

Bases: object

Represents a grounded model, providing access to grounded atoms and facts.

property atoms: dict[str, dict[tuple[str, ...], Any]]
draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, settings: DrawingSettings | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the grounding.

Parameters:

  • filename (str, optional) – The filename to save the drawing to. Default: None.

  • show (bool) – Whether to show the drawing. Default: True.

  • img_type (str) – The image type. Default: β€œpng”.

  • value_detail (int) – The level of detail for values. Default: 0.

  • graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

  • settings (DrawingSettings, optional) – Styling settings. When provided, they control value detail and graph styling.

Returns:

The drawing data or image object.

Return type:

Any

get_atoms(literal: Any) → list[Atom][source]

Returns a list of grounded atoms matching the provided literal.

Parameters:

literal (Any) – The literal to match.

Returns:

The list of matching grounded atoms.

Return type:

list[Atom]

class NeuralSample(sample: Any)[source]

Bases: object

Represents a single training or testing sample, containing the query and its associated neural network (evidence).

draw(filename: str | None = None, show: bool = True, img_type: str = 'png', value_detail: int = 0, graphviz_path: str | None = None, settings: DrawingSettings | None = None, *args: Any, **kwargs: Any) → Any[source]

Draws the neural sample.

Parameters:

  • filename (str, optional) – The filename to save the drawing to. Default: None.

  • show (bool) – Whether to show the drawing. Default: True.

  • img_type (str) – The image type. Default: β€œpng”.

  • value_detail (int) – The level of detail for values. Default: 0.

  • graphviz_path (str, optional) – The path to the Graphviz executable. Default: None.

  • settings (DrawingSettings, optional) – Styling settings. When provided, they control value detail and graph styling.

Returns:

The drawing data or image object.

Return type:

Any

get_fact(fact: Any) → list[Neuron][source]

Returns the neuron corresponding to the provided fact.

Parameters:

fact (Any) – The fact to look for.

Returns:

The matching fact neuron(s).

Return type:

list[Neuron]

get_neurons(literal: Any, neuron_type: NeuronType | None = NeuronType.Atom) → list[Neuron][source]

Returns a list of neurons matching the provided literal and neuron type.

Parameters:

  • literal (Any) – The literal to match.

  • neuron_type (NeuronType, optional) – The type of neurons to search for. Default: NeuronType.Atom.

Returns:

The list of matching neurons.

Return type:

list[Neuron]

property neurons: dict[str, dict[str, dict[tuple[str, ...], Any]]]
set_fact_value(fact: Any, value: float) → int[source]

Sets the value of a specific fact in the sample.

Parameters:

  • fact (Any) – The fact to set the value for.

  • value (float) – The value to set.

Returns:

The index of the fact neuron, or -1 if not found.

Return type:

int

property target: float | list | ndarray
class Neuron(neuron: Any, substitutions: dict[str, Any])[source]

Bases: Atom

Represents a neuron in the neural network, extending the Atom class with value and gradient properties.

property gradient: float | list | ndarray
substitutions
property value: float | list | ndarray
class NeuronType(value)[source]

Bases: str, Enum

Enum representing different types of neurons in the neural network.

Aggregation = 'AggregationNeuron'
Atom = 'AtomNeuron'
Fact = 'FactNeuron'
Negation = 'NegationNeuron'
Rule = 'RuleNeuron'
SplittableAggregation = 'SplittableAggregationNeuron'
WeightedAtom = 'WeightedAtomNeuron'
WeightedRule = 'WeightedRuleNeuron'
class StaticGraphDataset(static_sample: NeuralSample, fact_mappings: list[list[tuple[BaseRelation, Any]]], batch_size: int = 1, targets: list[Any] | None = None)[source]

Bases: object

A dataset that grounds and neuralizes only the first sample, then reuses the same neural graph for all subsequent samples by updating fact values via NeuralSample.set_fact_value.

This is useful when all samples share identical structure (same predicates, same term groundings) and differ only in fact values.

Parameters:

  • static_sample (NeuralSample) – The single neuralized sample built from the first example.

  • fact_mappings (list[list[tuple[BaseRelation, float]]]) – For each original sample, a list of (fact, value) pairs to set before evaluating that sample.

  • batch_size (int) – The batch size.

apply_mapping(index: int) → int[source]

Apply the fact values for the sample at the given index.

Parameters:

index (int) – The sample index.

Returns:

Number of facts updated.

Return type:

int

property fact_mappings: list[list[tuple[BaseRelation, Any]]]

Return the per-sample fact→value mappings.

static_sample
property targets: list[Any]

Each sample’s own target, in the same order as fact_mappings.

The static sample carries the first sample’s target, so without these every sample would be fitted to that one label.

build_static_graph_dataset(dataset_builder: DatasetBuilder, dataset: Any, settings: SettingsProxy, *, batch_size: int = 1, learnable_facts: bool = False, progress: bool = False) → StaticGraphDataset[source]

Build a StaticGraphDataset from a logic Dataset.

Only the first sample is grounded and neuralized. For every sample (including the first), a fact→value mapping is stored so that the caller can update the static sample before each learning/evaluation step.

Parameters:

  • dataset_builder (DatasetBuilder)

  • dataset (Dataset) – The dataset with one or more samples.

  • settings (SettingsProxy)

  • batch_size (int) – Batch size (default 1).

  • learnable_facts (bool) – Whether facts are learnable (default False).

  • progress (bool) – Whether to show a progress bar (default False).

Return type:

StaticGraphDataset