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

[eduardstan]

What Changed

• Bumped nesyarena from 0.1.0.dev0 to 0.1.0 in both pyproject.toml and src/nesyarena/__init__.py, and added PyPI release metadata: trove classifiers (Python 3.10–3.12, Science/Research, AI) and [project.urls] (Homepage, Repository, Issues).
• Extended the CI test job to a 3.10 / 3.11 / 3.12 matrix with fail-fast: false; 3.12 keeps the pinned requirements.txt install, while 3.10/3.11 install via extras (.[dev,oracles,reporting,learning] plus LTNtorch).
• Added docs/PUBLISHING.md (build, twine check, TestPyPI/PyPI upload, clean-venv verification), linked it from the README companion-docs line, deduplicated the README docs/ inventory entry, and ignored dist//build/.

Pipeline notes: build and publish path was verified — python -m build plus twine check passed for both sdist and wheel, and a clean-venv install from each imported nesyarena at 0.1.0 with the test subset passing (43 passed, 6 skipped) on 3.10, 3.11 and 3.12. Review flagged follow-ups left out of this change: the generated out/ artifacts still stamp 0.1.0.dev0, the README has no pip install nesyarena line yet, and benchmarks/instances_v1.json is not shipped as package data so load_instances() needs a repo checkout.

Risk Assessment

⚠️ Medium: Release-metadata and CI-matrix change is well-bounded and safe to merge, but publishing 0.1.0 exposes a packaging gap (frozen benchmark JSON not shipped, so load_instances() fails for PyPI users) plus CI-cost and coverage-asymmetry issues worth addressing before or shortly after the upload.

Testing

Exercised the release-prep intent the way a publisher and a downstream user would: built the sdist and wheel, ran twine check (both PASSED), inspected the wheel metadata to confirm version 0.1.0, MIT license expression, project URLs and the 3.10–3.12 classifiers, then installed both artifacts into fresh virtualenvs and ran the PUBLISHING.md verification import, which printed 0.1.0. To back the extended CI matrix, the core numpy-only test files were run against the installed wheel under Python 3.10, 3.11 and 3.12 (43 passed, 6 skipped on each), the workflow matrix was cross-checked against the packaging metadata and extras names, and the new 3.10/3.11 install line was resolved with a dry run to prove it is satisfiable. The TestPyPI and PyPI upload steps were deliberately not executed since they publish outward and need credentials; everything up to the upload is verified. Build leftovers (egg-info, temp venvs) were removed and the worktree is clean. One informational note: the sdist ships test files without conftest/fixtures.

Evidence: Full release verification transcript (build, twine check, metadata, clean-venv installs, 3.10/3.11/3.12 test runs, CI cross-check)

=== build ===
-rw-rw-r-- 1 eduard eduard 33700 Jul 31 02:15 nesyarena-0.1.0-py3-none-any.whl
-rw-rw-r-- 1 eduard eduard 41201 Jul 31 02:15 nesyarena-0.1.0.tar.gz

=== twine check ===
Checking 
/tmp/no-mistakes-evidence/01KYTR6FHJSXXDMSXEWWYQXBZY/dist/nesyarena-0.1.0-py3-no
ne-any.whl: PASSED
Checking 
/tmp/no-mistakes-evidence/01KYTR6FHJSXXDMSXEWWYQXBZY/dist/nesyarena-0.1.0.tar.gz
: PASSED

=== wheel metadata (head) ===
Metadata-Version: 2.4
Name: nesyarena
Version: 0.1.0
Summary: NeSyArena: measuring semantic fidelity of neuro-symbolic reasoning systems against their claimed semantics
Author: Ionel Eduard Stan
License-Expression: MIT
Project-URL: Homepage, https://github.com/eduardstan/nesyarena
Project-URL: Repository, https://github.com/eduardstan/nesyarena
Project-URL: Issues, https://github.com/eduardstan/nesyarena/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: oracles

=== clean-venv install + import (PUBLISHING.md verification command) ===
$ pip install nesyarena-0.1.0-py3-none-any.whl
Name: nesyarena
Version: 0.1.0
Summary: NeSyArena: measuring semantic fidelity of neuro-symbolic reasoning systems against their claimed semantics
Home-page: https://github.com/eduardstan/nesyarena
Author: Ionel Eduard Stan
Author-email: 
License: 
Location: /tmp/nsa_wheel_venv/lib/python3.12/site-packages

$ python -c 'import nesyarena, nesyarena.generators, nesyarena.suts; ...'
Wheel install verified. Version: 0.1.0

=== sdist clean-venv install ===
Sdist install verified. Version: 0.1.0

=== core tests against installed wheel, 3.10/3.11/3.12 ===
### Python 3.10: Python 3.10.20
nesyarena 0.1.0 from /tmp/nsa_py3.10/lib/python3.10/site-packages/nesyarena/__init__.py
...........................................ssssss                        [100%]
43 passed, 6 skipped in 4.11s

### Python 3.11: Python 3.11.15
nesyarena 0.1.0 from /tmp/nsa_py3.11/lib/python3.11/site-packages/nesyarena/__init__.py
...........................................ssssss                        [100%]
43 passed, 6 skipped in 4.11s

### Python 3.12: Python 3.12.9
nesyarena 0.1.0 from /tmp/nsa_wheel_venv/lib/python3.12/site-packages/nesyarena/__init__.py
...........................................ssssss                        [100%]
43 passed, 6 skipped in 4.18s

=== CI matrix vs package metadata ===
CI matrix python-version: ['3.10', '3.11', '3.12']
pyproject requires-python: >=3.10
pyproject version classifiers: ['3.10', '3.11', '3.12']
matrix == classifiers: True
extras used by CI (3.10/3.11 branch): ['dev', 'learning', 'oracles', 'reporting']
extras declared in pyproject: ['backends', 'dev', 'learning', 'oracles', 'reporting']
all CI extras declared: True
version pyproject: 0.1.0

src/nesyarena/__init__.py: __version__ = "0.1.0"

- Evidence: Built distribution artifacts (local file: /tmp/no-mistakes-evidence/01KYTR6FHJSXXDMSXEWWYQXBZY/dist)

Evidence: twine check + clean-venv install verification

Checking dist/nesyarena-0.1.0-py3-none-any.whl: PASSED
Checking dist/nesyarena-0.1.0.tar.gz: PASSED

$ pip install nesyarena-0.1.0-py3-none-any.whl
Name: nesyarena
Version: 0.1.0
Home-page: https://github.com/eduardstan/nesyarena

$ python -c 'import nesyarena, nesyarena.generators, nesyarena.suts; ...'
Wheel install verified. Version: 0.1.0
Sdist install verified. Version: 0.1.0

Evidence: CI matrix rows exercised locally against the installed wheel

### Python 3.10: Python 3.10.20
nesyarena 0.1.0 from /tmp/nsa_py3.10/lib/python3.10/site-packages/nesyarena/__init__.py
43 passed, 6 skipped in 4.11s

### Python 3.11: Python 3.11.15
nesyarena 0.1.0 from /tmp/nsa_py3.11/lib/python3.11/site-packages/nesyarena/__init__.py
43 passed, 6 skipped in 4.11s

### Python 3.12: Python 3.12.9
nesyarena 0.1.0 from /tmp/nsa_wheel_venv/lib/python3.12/site-packages/nesyarena/__init__.py
43 passed, 6 skipped in 4.18s

Evidence: Wheel METADATA (PyPI-facing project page fields)

Metadata-Version: 2.4
Name: nesyarena
Version: 0.1.0
Summary: NeSyArena: measuring semantic fidelity of neuro-symbolic reasoning systems against their claimed semantics
Author: Ionel Eduard Stan
License-Expression: MIT
Project-URL: Homepage, https://github.com/eduardstan/nesyarena
Project-URL: Repository, https://github.com/eduardstan/nesyarena
Project-URL: Issues, https://github.com/eduardstan/nesyarena/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Provides-Extra: oracles
Requires-Dist: problog>=2.2; extra == "oracles"
Requires-Dist: pysdd>=1.0; extra == "oracles"
Provides-Extra: reporting
Requires-Dist: matplotlib>=3.8; extra == "reporting"
Requires-Dist: pyyaml>=6.0; extra == "reporting"
Provides-Extra: learning
Requires-Dist: torch>=2.4; extra == "learning"
Requires-Dist: torchvision>=0.20; extra == "learning"
Provides-Extra: backends
Requires-Dist: pydeeplog>=3.0; extra == "backends"
Requires-Dist: deepproblog>=2.0; extra == "backends"
Requires-Dist: LTNtorch>=1.0; extra == "backends"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

- Outcome: ⚠️ 1 info across 1 run (4m11s)

Pipeline

Updates from git push no-mistakes

⏭️ **intent** - skipped

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 6 issues (2 warnings, 4 infos)

• ⚠️ src/nesyarena/benchmarks.py:30 - Releasing 0.1.0 to PyPI makes load_instances() unusable for installed users: DEFAULT_PATH is os.path.dirname(benchmarks.py)/../../benchmarks/instances_v1.json, which from site-packages resolves outside the installed package, and the wheel ships no data file ([tool.setuptools.packages.find] where=["src"] only, no package-data, no MANIFEST.in, no non-.py file under src/). pip install nesyarena then from nesyarena.benchmarks import load_instances; load_instances() raises FileNotFoundError, while the module docstring documents that loop as the conformance entry point. Fix at the package boundary: move instances_v1.json under src/nesyarena/data/, add it as package data, and resolve via importlib.resources — or state in README/PUBLISHING.md that the frozen benchmark set requires a repo checkout.
• ⚠️ .github/workflows/ci.yml:40 - 3.10/3.11 legs install the learning extra (torch>=2.4, torchvision) from default PyPI, which on Linux pulls the CUDA build plus nvidia-* wheels (~2.5 GB per leg); the 3.12 leg avoids this because requirements.txt carries --extra-index-url https://download.pytorch.org/whl/cpu and +cpu pins. Two extra GB-scale downloads per CI run, with runner disk pressure. Install CPU torch first in the else branch (e.g. pip install --index-url https://download.pytorch.org/whl/cpu torch torchvision before the extras install).
• ℹ️ .github/workflows/ci.yml:42 - pip install -e . --no-deps runs unconditionally, but the else branch already did pip install -e ".[...]". Only the requirements.txt branch needs it; move it inside the if to drop a redundant reinstall step.
• ℹ️ .github/workflows/ci.yml:40 - The non-3.12 legs omit the backends extra (pydeeplog, deepproblog) and add only LTNtorch, so tests/test_deeplog_adapter.py and tests/test_deepproblog_standalone.py pytest.importorskip out on 3.10/3.11. The wider matrix therefore does not extend adapter-conformance coverage to those versions — green 3.10/3.11 legs are a narrower claim than the 3.12 leg. Likely deliberate (those backends are version-fragile); noting so the coverage difference is not read as full parity.
• ℹ️ README.md:24 - Quickstart (and docs/OVERVIEW.md:257) still document only the source install (pip install -r requirements.txt + pip install -e .), with no pip install nesyarena path, even though this change publishes the package. Users arriving from PyPI get no supported install line.
• ℹ️ out/RESULTS.md:1 - The committed auto-generated results header still reads package 0.1.0.dev0 after the bump to 0.1.0, so the published artifact's provenance line disagrees with the released version. Regenerate via make report before tagging.

⚠️ **Test** - 1 info

• ℹ️ pyproject.toml:37 - The built sdist ships tests/test_.py but not tests/conftest.py or tests/fixtures/toy_golden.json, so the test directory inside nesyarena-0.1.0.tar.gz cannot actually run (setuptools' legacy auto-include picks up test.py only). Harmless for pip install nesyarena, but a downstream consumer building from the sdist gets a broken test tree. Fix if wanted: a MANIFEST.in, or prune tests from the sdist entirely.
• python -m build --outdir <evidence>/dist . — built nesyarena-0.1.0.tar.gz and nesyarena-0.1.0-py3-none-any.whl
• twine check dist/* — PASSED for both wheel and sdist (README renders, metadata valid)
• Inspected wheel METADATA: Version 0.1.0, License-Expression MIT, Homepage/Repository/Issues URLs, 3.10/3.11/3.12 classifiers, Requires-Python >=3.10
• Clean venv install from wheel + python -c "import nesyarena, nesyarena.generators, nesyarena.suts; print(nesyarena.__version__)" (the exact verification command from docs/PUBLISHING.md) → 0.1.0
• Clean venv install from the sdist tarball + same import check → 0.1.0
• python -m pytest tests/test_ir.py tests/test_generators.py tests/test_engine.py tests/test_suts.py tests/test_witness_metrics.py tests/test_benchmarks.py run against the installed wheel under Python 3.10.20, 3.11.15 and 3.12.9 → 43 passed, 6 skipped on each
• Cross-checked .github/workflows/ci.yml matrix (3.10/3.11/3.12) against pyproject classifiers, requires-python, and extras names used by the new non-3.12 install branch (dev,oracles,reporting,learning all declared)
• uv pip install --dry-run --python 3.10 ".[dev,oracles,reporting,learning]" LTNtorch — the new CI 3.10/3.11 install line resolves (torch 2.13.0, problog 2.2.10, pysdd 1.0.6, ruff, pytest, …)
• Confirmed src/nesyarena/__init__.py __version__ matches pyproject version (0.1.0)

⚠️ **Document** - 2 issues (1 warning, 1 info)

• ⚠️ out/RESULTS.md:1 - Generated artifacts in out/ still stamp the old package version: out/RESULTS.md header reads "auto-generated, package 0.1.0.dev0" and 15 out/*.json payloads carry package_version "0.1.0.dev0". These are generated from nesyarena.version by experiments/report.py and each experiment runner, so hand-editing would falsify provenance; refreshing them requires rerunning make all, which is behavioral validation outside this pass. Decide whether to regenerate before tagging 0.1.0 or accept that committed results record the version they were measured under.
• ℹ️ README.md:20 - README Quickstart still documents only the editable dev install; it has no pip install nesyarena path even though this change prepares a 0.1.0 PyPI release (version bump, classifiers, project URLs, docs/PUBLISHING.md). Left unchanged because the package does not appear to be published yet and documenting an unavailable install would be wrong. Add the PyPI install line to README once the upload in docs/PUBLISHING.md §3 succeeds.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.