build(nesyarena): prepare 0.1.0 PyPI release and widen CI matrix

.github/workflows/ci.yml

@@ -13,24 +13,32 @@ concurrency:
 
 jobs:
   test:
-    name: Run tests
+    name: Run tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          if [ "${{ matrix.python-version }}" = "3.12" ]; then
+            pip install -r requirements.txt
+          else
+            pip install -e ".[dev,oracles,reporting,learning]" LTNtorch
+          fi
           pip install -e . --no-deps
 
       - name: Run test suite

.gitignore

@@ -4,6 +4,8 @@ __pycache__/
 *.egg-info/
 .venv/
 venv/
+dist/
+build/
 .pytest_cache/
 .ruff_cache/
 

README.md

@@ -13,8 +13,9 @@ as a function of program structure, plus what that error does to learning.
 > component, how external systems (Scallop, DeepLog) plug in, and what is and
 > isn't done yet. This README is the quick reference.
 
-Companion docs: [`docs/OVERVIEW.md`](docs/OVERVIEW.md) (plain-language guide)
-and [`docs/ADAPTERS.md`](docs/ADAPTERS.md) (how to plug in a system).
+Companion docs: [`docs/OVERVIEW.md`](docs/OVERVIEW.md) (plain-language guide),
+[`docs/ADAPTERS.md`](docs/ADAPTERS.md) (how to plug in a system), and
+[`docs/PUBLISHING.md`](docs/PUBLISHING.md) (release guide).
 
 ## Quickstart
 
@@ -88,7 +89,8 @@ experiments/     one runner per experiment (E1–E8 + scorecard); `make all` run
 tests/           the correctness contract: oracle ≡ ProbLog, gradients, error laws,
                  and parity against the frozen golden fixtures (tests/fixtures/)
 out/             measured results from the experiment runs (RESULTS.md, JSON, figures)
-docs/            OVERVIEW.md (start here) and ADAPTERS.md (plug in a system)
+docs/            project documentation (start with OVERVIEW.md; see the
+                 companion-docs links above)
 ```
 
 Correctness is gated by parity: `tests/fixtures/toy_golden.json` pins the

docs/PUBLISHING.md

@@ -0,0 +1,65 @@
+# Publishing NeSyArena to PyPI
+
+This guide outlines the exact commands to build, check, rehearse on TestPyPI, and publish `nesyarena` to PyPI.
+
+> **Note:** Do not add `build` or `twine` to project dependencies. Install them in a temporary virtual environment for packaging.
+
+---
+
+## 1. Build and Validate Artifacts
+
+First, install the packaging tools in an isolated virtual environment and build the source distribution (`.tar.gz`) and wheel (`.whl`):
+
+```bash
+python3 -m venv /tmp/build_venv
+/tmp/build_venv/bin/pip install build twine
+
+# Clean any existing build artifacts
+rm -rf dist build src/nesyarena.egg-info
+
+# Build source distribution and wheel
+/tmp/build_venv/bin/python -m build
+
+# Validate README rendering and metadata
+/tmp/build_venv/bin/twine check dist/*
+```
+
+---
+
+## 2. TestPyPI Rehearsal
+
+Upload the built artifacts to TestPyPI and verify installation from a clean virtual environment:
+
+### Upload to TestPyPI
+```bash
+/tmp/build_venv/bin/twine upload --repository testpypi dist/*
+```
+
+### Verification from TestPyPI
+Create a clean virtual environment and install `nesyarena` from TestPyPI (using PyPI as fallback for dependencies like `numpy`):
+
+```bash
+python3 -m venv /tmp/testpypi_verify_venv
+/tmp/testpypi_verify_venv/bin/pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple nesyarena
+/tmp/testpypi_verify_venv/bin/python -c "import nesyarena, nesyarena.generators, nesyarena.suts; print('TestPyPI install verified. Version:', nesyarena.__version__)"
+```
+
+---
+
+## 3. Production PyPI Release
+
+Once TestPyPI rehearsal succeeds, publish the release to PyPI:
+
+### Upload to PyPI
+```bash
+/tmp/build_venv/bin/twine upload dist/*
+```
+
+### Production Verification
+Verify the public PyPI release in a fresh virtual environment:
+
+```bash
+python3 -m venv /tmp/pypi_verify_venv
+/tmp/pypi_verify_venv/bin/pip install nesyarena
+/tmp/pypi_verify_venv/bin/python -c "import nesyarena, nesyarena.generators, nesyarena.suts; print('PyPI release verified. Version:', nesyarena.__version__)"
+```

pyproject.toml

@@ -4,17 +4,30 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nesyarena"
-version = "0.1.0.dev0"
+version = "0.1.0"
 description = "NeSyArena: measuring semantic fidelity of neuro-symbolic reasoning systems against their claimed semantics"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Ionel Eduard Stan" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
 dependencies = [
     "numpy>=1.26",
 ]
 
+[project.urls]
+Homepage = "https://github.com/eduardstan/nesyarena"
+Repository = "https://github.com/eduardstan/nesyarena"
+Issues = "https://github.com/eduardstan/nesyarena/issues"
+
 [project.optional-dependencies]
 oracles = ["problog>=2.2", "pysdd>=1.0"]   # exact PLP oracle beyond the brute-force fact limit
 reporting = ["matplotlib>=3.8", "pyyaml>=6.0"]

src/nesyarena/__init__.py

@@ -5,4 +5,4 @@
 of program structure — plus the learning consequences.
 """
 
-__version__ = "0.1.0.dev0"
+__version__ = "0.1.0"