solverforge 0.3.0__tar.gz → 0.5.0__tar.gz

solverforge-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.14"
+  RUST_VERSION: "1.95.0"
+
+jobs:
+  ci-local:
+    name: local CI gate
+    runs-on: ${{ github.server_url == 'https://github.com' && 'ubuntu-latest' || 'rust' }}
+    steps:
+      - name: Checkout solverforge-py
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        shell: bash
+        run: |
+          curl --retry 5 --retry-all-errors --retry-delay 5 \
+            -LsSf https://astral.sh/uv/install.sh | sh
+          echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
+          "${HOME}/.local/bin/uv" python install "${PYTHON_VERSION}"
+          host_python="$("${HOME}/.local/bin/uv" python find "${PYTHON_VERSION}")"
+          host_python_dir="$(dirname "${host_python}")"
+          host_python_libdir="$("${host_python}" -c 'import sysconfig; print(sysconfig.get_config_var("LIBDIR") or "")')"
+          echo "${host_python_dir}" >> "${GITHUB_PATH}"
+          echo "HOST_PYTHON=${host_python}" >> "${GITHUB_ENV}"
+          echo "PYO3_PYTHON=${host_python}" >> "${GITHUB_ENV}"
+          echo "PYTHON_SYS_EXECUTABLE=${host_python}" >> "${GITHUB_ENV}"
+          echo "LIBRARY_PATH=${host_python_libdir}:${LIBRARY_PATH:-}" >> "${GITHUB_ENV}"
+          echo "LD_LIBRARY_PATH=${host_python_libdir}:${LD_LIBRARY_PATH:-}" >> "${GITHUB_ENV}"
+          "${host_python}" --version
+
+      - name: Set up Rust
+        shell: bash
+        run: |
+          curl --retry 5 --retry-all-errors --retry-delay 5 \
+            --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
+            | sh -s -- -y --profile minimal --default-toolchain "${RUST_VERSION}" \
+                --component rustfmt --component clippy
+          if [ -f "${HOME}/.cargo/env" ]; then
+            . "${HOME}/.cargo/env"
+            echo "${HOME}/.cargo/bin" >> "${GITHUB_PATH}"
+          else
+            . /usr/local/cargo/env
+            echo "/usr/local/cargo/bin" >> "${GITHUB_PATH}"
+          fi
+          rustc --version
+          cargo --version
+
+      - name: Validate SolverForge release base
+        run: make release-base-check
+
+      - name: Install Playwright system dependencies
+        if: ${{ runner.os == 'Linux' }}
+        run: make install-playwright-system-deps
+
+      - name: Run local CI
+        run: make ci-local
+
+      - name: Build and verify local distributions
+        run: make build-dist dist-check smoke-wheel

solverforge-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,200 @@
+name: Release
+
+on:
+  workflow_dispatch: {}
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  PYTHON_VERSION: "3.14"
+  RUST_VERSION: "1.95.0"
+
+jobs:
+  sdist:
+    name: source distribution
+    if: github.server_url == 'https://github.com'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout solverforge-py
+        uses: actions/checkout@v6
+        with:
+          path: solverforge-py
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: ${{ env.RUST_VERSION }}
+          components: rustfmt, clippy
+
+      - name: Build sdist
+        working-directory: solverforge-py
+        run: make build-sdist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: solverforge-py/dist/*.tar.gz
+
+  wheels:
+    name: wheel ${{ matrix.os }} ${{ matrix.target }}
+    if: github.server_url == 'https://github.com'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: x86_64
+            manylinux: "2014"
+            interpreter: python3.14
+          - os: macos-14
+            target: aarch64
+            manylinux: ""
+            interpreter: python3.14
+          - os: windows-latest
+            target: x64
+            manylinux: ""
+            interpreter: python
+    steps:
+      - name: Checkout solverforge-py
+        uses: actions/checkout@v6
+        with:
+          path: solverforge-py
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --locked --strip --compatibility pypi -i ${{ matrix.interpreter }} --out dist
+          manylinux: ${{ matrix.manylinux }}
+          target: ${{ matrix.target }}
+          rust-toolchain: ${{ env.RUST_VERSION }}
+          working-directory: solverforge-py
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: solverforge-py/dist/*.whl
+
+  verify:
+    name: verify artifacts
+    if: github.server_url == 'https://github.com'
+    runs-on: ubuntu-latest
+    needs: [sdist, wheels]
+    steps:
+      - name: Checkout solverforge-py
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: artifact-download
+
+      - name: Collect distributions
+        run: |
+          mkdir dist
+          find artifact-download -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp '{}' dist/ \;
+
+      - name: Install release tools
+        run: python -m pip install --disable-pip-version-check twine
+
+      - name: Check metadata
+        run: |
+          python -m twine check dist/*
+          python scripts/verify_release_artifacts.py --dist dist
+
+      - name: Upload verified distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-dist
+          path: dist/*
+
+  publish-testpypi:
+    name: publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: verify
+    if: >-
+      github.server_url == 'https://github.com' &&
+      github.event_name == 'workflow_dispatch'
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dist
+          path: dist
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: publish to PyPI
+    runs-on: ubuntu-latest
+    needs: verify
+    if: >-
+      github.server_url == 'https://github.com' &&
+      github.event_name == 'push' &&
+      startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout solverforge-py
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Validate tag version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+
+          with open("pyproject.toml", "rb") as handle:
+              version = tomllib.load(handle)["project"]["version"]
+
+          expected = f"v{version}"
+          actual = os.environ["GITHUB_REF_NAME"]
+          if actual != expected:
+              raise SystemExit(f"tag {actual} does not match package version {expected}")
+          PY
+
+      - name: Download verified distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

solverforge-0.5.0/.gitignore

@@ -0,0 +1,11 @@
+/target/
+/.venv/
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+/dist/
+/wheelhouse/
+*.egg-info/
+__pycache__/
+*.py[cod]
+python/solverforge/_native*.so

solverforge-0.5.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+    -   id: check-merge-conflict
+    -   id: check-added-large-files
+
+-   repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.0
+    hooks:
+    -   id: gitleaks
+-   repo: https://github.com/psf/black
+    rev: 26.5.1
+    hooks:
+    -   id: black
+
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+    -   id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+-   repo: https://github.com/doublify/pre-commit-rust
+    rev: v1.0
+    hooks:
+    -   id: fmt
+        args: ["--", "--check"]
+    -   id: clippy
+        args: ["--", "-D", "warnings"]

solverforge-0.5.0/.python-version

@@ -0,0 +1 @@
+3.14t

solverforge-0.5.0/AGENTS.md

@@ -0,0 +1,121 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`solverforge-py` is a mixed Python/Rust binding package built with PyO3 and
+maturin. Python package code lives under `python/solverforge/`; the native
+extension, dynamic runtime bridge, callbacks, manager, and schema code live under
+`src/`. Python tests are in `tests/python/`, Rust tests are in `tests/rust/`, and
+examples are in `examples/`. The hospital and deliveries demos own their
+FastAPI apps, app-specific static UI, generated UI models, and seed data under
+`examples/solverforge_hospital/` and `examples/solverforge_deliveries/`;
+shared `/sf/*` assets are served from the pinned `solverforge-ui` crate through
+the native binding.
+`WIREFRAME.md` is the as-built API/UI map; `README.md` carries installation,
+callback/threading, boundary, and release contracts. There is no separate
+`docs/` directory.
+
+## Build, Test, and Development Commands
+
+- `make develop`: create `.venv`, install tools, and install the release native extension.
+- `make install-playwright-system-deps`: install Chromium plus Linux shared
+  libraries required by Playwright browser tests in lean CI images.
+- `make test`: run Rust tests with the local Python link setup, then pytest.
+- `make test-quick`: run fast Python regressions without the example app tests.
+- `make test-hospital`: run the hospital model, FastAPI/frontend lifecycle, and
+  hospital Playwright browser test.
+- `make test-deliveries`: run the deliveries model, FastAPI/frontend lifecycle,
+  and deliveries Playwright browser test.
+- `make test-examples-browser`: run the Playwright browser tests for both example apps.
+- `make lint`: run rustfmt check, ruff, strict mypy, and clippy with warnings denied.
+- `make docs-check`: verify the tracked README, AGENTS, WIREFRAME, and example
+  README surface exists and avoids known stale claims.
+- `make release-base-check`: verify the exact crates.io SolverForge dependency
+  base in `Cargo.toml` and `Cargo.lock`.
+- `make ci-local` or `make audit`: run the local CI simulation.
+- `make pre-release`: run `release-base-check`, `ci-local`, release
+  distribution build/checks, and clean-wheel smoke test.
+- `make hospital-run`: serve the hospital app on `APP_HOST=127.0.0.1 PORT=7860`.
+- `make deliveries-run`: serve the deliveries app on `APP_HOST=127.0.0.1 PORT=7860`
+  unless `PORT` is overridden.
+
+Use Rust `1.95.0` from `rust-toolchain.toml`. Python code targets Python `3.14`.
+
+## Coding Style & Naming Conventions
+
+Python uses Ruff linting, strict mypy, and the 100-character line limit from
+`pyproject.toml`; `make py-format` is available for an intentional Black pass.
+Prefer typed public APIs and keep exports in `python/solverforge/__init__.py`
+intentional. Use snake_case for Python modules, functions, and variables; use
+PascalCase for classes. Rust follows rustfmt and clippy with `-D warnings`; keep
+module names snake_case and public types descriptive.
+
+## Testing Guidelines
+
+Add Python regression tests as `tests/python/test_*.py`. Add Rust integration or
+unit coverage under `tests/rust/` or the relevant `src/` module. For binding
+changes, prefer tests that prove Python behavior through the public `solverforge`
+API, then add Rust tests only where native runtime behavior is directly changed.
+Run the narrow suite first, then `make ci-local` for cross-language or
+integration changes. Use `make test-hospital` or `make test-deliveries` when
+touching either example app. Binding changes should normally prove behavior
+through the public Python API and add Rust coverage only when native runtime
+behavior changes directly.
+
+## Runtime & Callback Contracts
+
+Python owns model authoring: classes, decorators, functions, lambdas, and
+callbacks. `solverforge-py` owns the Python API, PyO3 binding code, Rust-owned
+dynamic model state, callback invocation, marshaling, packaging, and example
+apps. Upstream SolverForge owns the solver engine, phases, selectors, move
+machinery, termination, telemetry, retained lifecycle, descriptors, and public
+bridge seams. This checkout consumes public upstream crates through exact
+registry pins in `Cargo.toml` and `Cargo.lock`; do not add private upstream
+module dependencies or local path overrides for release work.
+
+Python callbacks are the only constraint authoring surface. Callback exceptions
+must preserve actionable Python tracebacks. Callback solution views must expose
+ordinary solution-level lookup context while projecting entity/fact collections
+from Rust-owned state. Callback code may be called many times and from multiple
+worker threads on CPython 3.14 free-threaded, so treat solution-level lookup
+context as immutable during a solve.
+
+Do not fake unsupported behavior. Top-level `ConstraintFactory.join`,
+`group_by`, `if_exists`, `if_not_exists`, and `flattened` remain explicit
+unsupported methods until public bridge support exists for those top-level
+semantics. Rust-only custom search and partitioner registration cannot be
+claimed as Python-bindable without a public upstream seam.
+
+## Release Responsibilities
+
+`pyproject.toml` owns PyPI metadata, version, Python requirement, optional
+example dependencies, project URLs, classifiers, and maturin module settings.
+`Cargo.toml` owns native crate metadata and the SolverForge Rust dependency
+base; the package version must match `pyproject.toml`. `Cargo.lock` locks
+reproducible Rust builds. The `Makefile` owns local release targets,
+dependency-base checks, distribution builds, artifact validation, browser system
+dependency setup, and `pre-release`. `.github/workflows/ci.yml` validates source
+checkouts on GitHub and Forgejo, installs Playwright system dependencies on
+Linux, and retries network toolchain bootstraps for transient runner DNS misses.
+`.github/workflows/release.yml` builds sdists/wheels, verifies release
+artifacts, publishes to TestPyPI only from manual workflow dispatch, and
+publishes to PyPI only from a matching `v*.*.*` tag after the reviewed `pypi`
+environment approves the job. `scripts/verify_release_artifacts.py` checks
+deterministic artifact metadata/content, and
+`tests/python/test_release_metadata.py` guards release metadata drift.
+
+## Commit & Pull Request Guidelines
+
+The history uses concise Conventional Commit-style subjects such as
+`fix(runtime): preserve scalar snapshots` or `test(manager): cover retained jobs`.
+Pull requests should include the motivation, user-visible behavior, tests run,
+and any linked issue. Include screenshots or short recordings for changes under
+`examples/solverforge_hospital/static/` or
+`examples/solverforge_deliveries/static/`.
+
+## Agent-Specific Instructions
+
+Keep changes scoped to the requested surface. Do not rewrite runtime, callback,
+manager, or API payload paths for a simple documentation, UI, naming, or wiring
+task unless live evidence proves that path is the failing layer. Verify assumptions
+from the repo before changing critical integration code.

solverforge-0.5.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
+
+## [0.5.0](https://github.com/SolverForge/solverforge-py/compare/v0.4.1...v0.5.0) (2026-07-03)
+
+
+### Features
+
+* **examples:** add deliveries Python app 0179084
+* **model:** carry dynamic route and shadow hooks 83a8d41
+* **runtime:** bind Python list route hooks fd51788
+* **runtime:** broaden dynamic Python planning surface f04eefa
+* **ui:** embed shared frontend assets ab30697
+
+
+### Bug Fixes
+
+* **ci:** bootstrap Forgejo toolchains in workflow 8e5f791
+* **ci:** install Playwright system dependencies b249fd1
+* **ci:** retry toolchain bootstrap downloads cd60f76
+* **ci:** run workflow from checkout root 8733fc3
+* **ci:** select Forgejo runner labels 56ff4fc
+* **deliveries:** recommend assigned-route insertions d59daea
+* **examples:** report snapshot score in payloads 0bfcaa0
+* **examples:** report solution scores in events bdcddd8
+* **model:** validate scalar group names cfa2070
+* **runtime:** align dynamic construction with core semantics 7cacda0
+* **runtime:** cap first-fit required construction candidates 3666c20
+* **runtime:** resolve dynamic slots against descriptors a2544be
+* **runtime:** reuse required assignment construction streams 0caf06d
+* **runtime:** use direct cursor for first-fit assignments 769a081
+* **scoring:** return true shadow update deltas 88dc500
+* **state:** preserve callback root fields 0aacef5
+
+
+### Tests
+
+* **examples:** stabilize hospital browser smoke f11efd6
+* **examples:** stub map tiles in browser smoke d69ca3e
+
+
+### Documentation and release
+
+* **docs:** remove standalone docs surface b1c6e1f
+* **release:** cut 0.5.0 metadata 4728014
+
+## [0.4.1](https://github.com/SolverForge/solverforge-py/compare/v0.4.0...v0.4.1) (2026-06-02)
+
+
+### Bug Fixes
+
+* **deps:** resolve SolverForge crates from crates.io 73bfe4a