Metadata-Version: 2.4
Name: pydeeplog
Version: 4.1.0
Summary: An operational framework for building neurosymbolic (NeSy) systems on top of PyTorch.
Author: KU Leuven
License: LGPL-2.1-only
Project-URL: Homepage, https://github.com/ML-KULeuven/deeplog
Project-URL: Documentation, https://ml-kuleuven.github.io/deeplog/
Project-URL: Repository, https://github.com/ML-KULeuven/deeplog
Project-URL: Source, https://github.com/ML-KULeuven/deeplog
Project-URL: Issues, https://github.com/ML-KULeuven/deeplog/issues
Project-URL: Changelog, https://github.com/ML-KULeuven/deeplog/blob/main/CHANGELOG.md
Keywords: neurosymbolic,nesy,deep learning,logic,probabilistic logic,knowledge compilation,differentiable reasoning,pytorch,deepproblog,semantic loss
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 (LGPLv2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<3,>=2.4
Requires-Dist: pysdd<2,>=1.0
Requires-Dist: numpy<3,>=2.0.2
Requires-Dist: klaycircuits<0.1,>=0.0.3
Requires-Dist: lark<2,>=1.0
Provides-Extra: examples
Requires-Dist: pytorch-lightning; extra == "examples"
Requires-Dist: torchvision; extra == "examples"
Requires-Dist: torchmetrics; extra == "examples"
Requires-Dist: mv-sdd; extra == "examples"
Requires-Dist: matplotlib; extra == "examples"
Requires-Dist: notebook; extra == "examples"
Requires-Dist: graphviz; extra == "examples"
Provides-Extra: janus-engine
Requires-Dist: janus_swi; extra == "janus-engine"
Provides-Extra: mvsdd
Requires-Dist: mv-sdd; extra == "mvsdd"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-xdist; extra == "tests"
Requires-Dist: coverage; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: jupytext; extra == "tests"
Requires-Dist: nbclient; extra == "tests"
Requires-Dist: ipykernel; extra == "tests"
Requires-Dist: pytorch-lightning; extra == "tests"
Requires-Dist: torchvision; extra == "tests"
Requires-Dist: torchmetrics; extra == "tests"
Requires-Dist: mv-sdd; extra == "tests"
Requires-Dist: matplotlib; extra == "tests"
Requires-Dist: graphviz; extra == "tests"
Provides-Extra: site
Requires-Dist: sphinx; extra == "site"
Requires-Dist: sphinx-autoapi; extra == "site"
Requires-Dist: pydata-sphinx-theme==0.16.1; extra == "site"
Requires-Dist: myst-nb; extra == "site"
Requires-Dist: sphinx-design==0.6.1; extra == "site"
Requires-Dist: sphinx-copybutton; extra == "site"
Requires-Dist: sphinx-multiversion; extra == "site"
Requires-Dist: jupyter-sphinx; extra == "site"
Requires-Dist: nbformat; extra == "site"
Requires-Dist: jupytext; extra == "site"
Requires-Dist: ipykernel; extra == "site"
Requires-Dist: pytorch-lightning; extra == "site"
Requires-Dist: torchvision; extra == "site"
Requires-Dist: torchmetrics; extra == "site"
Requires-Dist: mv-sdd; extra == "site"
Requires-Dist: matplotlib; extra == "site"
Requires-Dist: graphviz; extra == "site"
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: jupytext; extra == "dev"
Requires-Dist: nbclient; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# DeepLog
[![GitHub Release](https://img.shields.io/github/v/release/ML-KULeuven/deeplog?display_name=tag)](https://github.com/ML-KULeuven/deeplog/releases)
[![PyPI version](https://img.shields.io/pypi/v/pydeeplog)](https://pypi.org/project/pydeeplog/)
[![License](https://img.shields.io/github/license/ML-KULeuven/deeplog)](LICENSE)
[![DOI](https://zenodo.org/badge/901879738.svg)](https://doi.org/10.5281/zenodo.20408413)

DeepLog is an operational framework for building neurosymbolic (NeSy) systems. Instead of presenting a monolithic stack, DeepLog provides high-performance building blocks that plug directly into PyTorch-first workflows so you can compose differentiable learning and symbolic reasoning with predictable interfaces.

## Why DeepLog?

- **Symbol-first modeling** – declare symbolic tensors and shapes, then let DeepLog check interfaces between modules before you wire them into larger systems.
- **Logic-aware modules** – compile formulas into differentiable modules, wrap existing PyTorch components, and connect them to multiple reasoning backends.
- **Backend flexibility** – start with the pure Python engine or enable the Janus/SWI-Prolog backend for lower latency inference without changing your training code.
- **Batteries included** – tutorial notebooks, example projects (semantic loss, MNIST addition, …), and a Sphinx site walk you from “hello world” to custom NeSy stacks.
- **Research to production** – typing, validation, and extensive tests keep advanced reasoning pipelines trustworthy when you move from prototypes to production workloads.

## Installation


DeepLog publishes optional extras so you can extend the base install as needed:

| Extra | Description |
| ----- | ----------- |
| `pydeeplog[examples]` | Adds interactive notebook tooling (Jupyter) plus Lightning/torchvision/torchmetrics for tutorials. |
| `pydeeplog[janus_engine]` | Installs the Janus SWI-Prolog bridge for the highest performance Prolog backend. |
| `pydeeplog[mvsdd]` | Installs MV-SDD, the knowledge compiler for a formula that reaches two values of one variable, such as the branches of an annotated disjunction. |
| `pydeeplog[tests]` | Adds pytest, coverage and supporting utilities for contributors. |
| `pydeeplog[site]` | Installs the documentation/notebook toolchain (Sphinx, PyData theme, myst-nb, Jupytext, ipykernel, Lightning/torchvision/torchmetrics, …). |

Combine extras as needed, for example `pip install ".[examples,tests]"`.

### Optional: Janus/SWI-Prolog backend

The Janus backend depends on a local SWI-Prolog installation. On Ubuntu you can install it with:

```bash
sudo apt-get install software-properties-common
sudo apt-add-repository ppa:swi-prolog/stable && sudo apt-get update
sudo apt-get install swi-prolog
```

Once SWI-Prolog is available, install the Python bindings via `pip install "pydeeplog[janus_engine]"`.

### Install from source

```bash
git clone https://github.com/ML-KULeuven/deeplog.git
cd deeplog
pip install -e ".[examples,tests]"
```

Editable installs refresh automatically when you change the source tree, which is handy when contributing.

## Quick start

```python
import torch
from deeplog import SymTensor, WrappedModule, parse_symbol

# Wrap a plain PyTorch head with symbolic input/output shapes so DeepLog can
# validate every tensor that flows through it.
digits = SymTensor([parse_symbol("digit_a"), parse_symbol("digit_b")])
sigmoid_head = WrappedModule(torch.nn.Sigmoid(), digits, digits, name="sigmoid_head")

print(sigmoid_head(torch.tensor([[1.0, -2.0]])))
# tensor([[0.7311, 0.1192]])
```

`WrappedModule` validates tensor shapes against the symbolic specification, so interface mismatches surface as Python errors instead of silent shape bugs when you wire modules into larger reasoning pipelines.

For a taste of the symbolic side, compile a logical formula straight into a differentiable module:

```python
from deeplog import parse_formula_to_module

# Count satisfying assignments of A ∨ B over booleans (= 3: TT, TF, FT).
module = parse_formula_to_module(
    "sum(A): sum(B): =(A,true)_boolean or =(B,true)_boolean"
)
print(int(module()))  # 3
```

See `examples/` for end-to-end notebooks (MNIST addition, semantic loss, LTN, …) and the full API reference on the docs site.

## Documentation & tutorials

- **Landing page & docs** – All documentation lives under [`site/`](site/). Build it locally with the steps in [Building the documentation site](#building-the-documentation-site).
- **Notebooks** – The notebooks in [`examples/`](examples/) teach DeepLog concept by concept; they are listed [below](#notebooks). The docs site sequences a selection of them into two reading paths, one for ML practitioners and one for neurosymbolic developers, and each notebook's page there has an **Open in Colab** badge.
- **API reference** – Generated automatically via `sphinx-autoapi`, covering symbols, shapes, modules, and engine utilities.

### Notebooks

#### Foundations

| Notebook | What it teaches |
|---|---|
| [`symbol`](examples/symbol.md) | The `Symbol` type: DeepLog's lightweight tagged-tuple representation of anything symbolic. |
| [`shape`](examples/shape.md) | `SymTensor` and how symbolic shapes let DeepLog validate module composition. |
| [`deeplogmodule`](examples/deeplogmodule.md) | `DeepLogModule` — the shape-aware `torch.nn.Module` subclass everything downstream builds on. |
| [`composition`](examples/composition.md) | Combining modules using `Sequential` and `ModuleCircuit`, and handling automatic shape transformations. |

#### Core concepts

| Notebook | What it teaches                                                                                     |
|---|-----------------------------------------------------------------------------------------------------|
| [`formula_to_module`](examples/formula_to_module.md) | Compiling a logical formula straight into a runnable `DeepLogModule` via `parse_formula_to_module`. |
| [`ast_and_rewrites`](examples/ast_and_rewrites.md) | The materialized formula AST, `fold`/`map_children`, and the `recognize_expectation`/`recognize_posterior` rewrite passes. |
| [`predicates`](examples/predicates.md) | Predicate modules: how symbolic atoms become executable tensor operations.                          |
| [`01_aggregation_basics`](examples/01_aggregation_basics.md) | Aggregation syntax, finite domains, and how DeepLog builds aggregation modules.                     |
| [`03_free_variables_and_batching`](examples/03_free_variables_and_batching.md) | Free variables are module inputs.                                                                   |
| [`circuits`](examples/circuits.md) | The `Circuit` DAG and `to_module()`.                                                                |
| [`circuit_transformation`](examples/circuit_transformation.md) | Transforming circuits between algebraic structures (boolean → probability, etc.).                   |
| [`language`](examples/language.md) | Tour of the textual DeepLog formula language and its parser.                                        |

#### Applications

| Notebook | What it teaches |
|---|---|
| [`problog`](examples/problog.md) | Running ProbLog programs: probabilistic facts, rules, queries, and conditioning on evidence with `:- ` integrity constraints (`P(q \| e)`). |
| [`deepproblog`](examples/deepproblog.md) | Neural predicates: a fact's probability comes from a network instead of a constant (an annotated disjunction compiled via the MV-SDD backend), building up to the classic MNIST-addition experiment. **Slow.** |
| [`semantic_loss`](examples/semantic_loss.md) | A full ML training pipeline that uses a DeepLog formula as a differentiable loss term (semantic loss). **Slow.** |
| [`ltn`](examples/ltn.md) | Reproducing a subset of the Logic Tensor Networks tutorial on top of DeepLog. |

## Development workflow

See [CONTRIBUTING.md](CONTRIBUTING.md) for code quality and testing guidelines.

Public bug reports, questions, and feature requests live on GitHub. Development and code review happen privately, and tagged releases (`v*`) are mirrored to the public GitHub repository after release.

## Building the documentation site

The landing page and docs live under `site/` (Sphinx + PyData theme). To preview them locally:

1. Install the site tooling (from the repo root):

   ```bash
   pip install -r site/requirements.txt
   ```

2. Build the static HTML:

   ```bash
   (cd site && make html)
   ```

3. Serve the generated pages from `site/build/html`. Any static file server works, e.g.:

   ```bash
   python -m http.server --directory site/build/html 8000
   ```

Visit `http://localhost:8000` to browse the site. Tools like `sphinx-autobuild` can provide live reloads, but the above workflow is the canonical build pipeline.

## Support & community

- **Bugs & questions** – Open an issue on [GitHub](https://github.com/ML-KULeuven/deeplog/issues) and include reproduction steps plus relevant version information.
- **Security reports** – Please do **not** file public issues for security vulnerabilities; instead reach the maintainers privately (see `CONTRIBUTING.md` for details).
- **Roadmap discussions** – Feature proposals, architectural questions, and broader discussions are welcome via issues.

## Contributing

We welcome contributions of all kinds—bug reports, docs, examples, and new modules. Review the [contributing guide](CONTRIBUTING.md) for coding standards, triage practices, and tips for a smooth review cycle. If you are looking for a first issue, check the tracker for `good first issue` and `help wanted` labels.

## License

DeepLog is released under the [LGPL-2.1 license](LICENSE) © DTAI Research Group, KU Leuven.
