Metadata-Version: 2.4
Name: pydeeplog
Version: 4.0.3
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: 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: nbmake; 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: nbconvert; 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: nbstripout; 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: nbmake; 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[tests]` | Adds pytest, coverage and supporting utilities for contributors. |
| `pydeeplog[site]` | Installs the documentation/notebook toolchain (Sphinx, PyData theme, myst-nb, nbconvert, 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** – Reproduces the semantic loss workflow, DeepLog module deep dives, MNIST addition with DeepProbLog, and more. Launch them from the `examples/` directory after installing `deeplog[examples]`.
- **API reference** – Generated automatically via `sphinx-autoapi`, covering symbols, shapes, modules, and engine utilities.

## 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.
