flopscope 0.2.0__tar.gz → 0.3.0__tar.gz

{flopscope-0.2.0 → flopscope-0.3.0}/.github/workflows/ci.yml

@@ -137,6 +137,9 @@ jobs:
       - name: Check generated files are in sync
         run: uv run python scripts/sync_client.py --check
 
+      - name: Check package versions are in lockstep
+        run: uv run python scripts/check_version_sync.py
+
       - name: Run parity tests
         run: uv run pytest tests/test_client_server_parity.py tests/test_serialization_parity.py -v
 

{flopscope-0.2.0 → flopscope-0.3.0}/.github/workflows/pypi-publish.yml

@@ -1,8 +1,9 @@
 name: PyPI publish
 
 # Triggered when a `v*` tag is pushed (typically via `cz bump` followed by
-# `git push --follow-tags`). See AGENTS.md → "Release process" for the
-# end-to-end flow and the one-time PyPI Trusted Publisher setup.
+# `git push --follow-tags`). Publishes all published packages at the tagged
+# version under a single environment approval. See the Release docs at
+# website/content/docs/development/release.mdx.
 
 on:
   push:
@@ -13,17 +14,32 @@ on:
 permissions: {}
 
 # Never run two publish jobs for the same tag in parallel. Don't cancel an
-# in-flight publish if another tag arrives — let it finish atomically.
+# in-flight publish if another tag arrives -- let it finish atomically.
 concurrency:
   group: pypi-publish-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
+  # NOTE: flopscope-client is intentionally absent from both matrices in this
+  # release. A PyPI bug currently blocks creating a Trusted Publisher for the
+  # `flopscope-client` project (server-side 500 on the publisher-create form,
+  # despite the identical request succeeding for `flopscope-server`). The
+  # package's version is bumped + handshake code is present, so the next
+  # release that includes it just needs to add the entries back in both
+  # matrices. Track the unblock in the PyPI bug filed for this issue.
   build:
-    name: Build sdist + wheel
+    name: Build ${{ matrix.package.name }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: flopscope
+            path: .
+          - name: flopscope-server
+            path: flopscope-server
     steps:
       - uses: actions/checkout@v4
 
@@ -31,24 +47,32 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Build distributions
+        working-directory: ${{ matrix.package.path }}
         run: uv build
 
       - name: Upload dist artifact
         uses: actions/upload-artifact@v4
         with:
-          name: dist
-          path: dist/
+          name: dist-${{ matrix.package.name }}
+          path: ${{ matrix.package.path }}/dist/
           if-no-files-found: error
 
   publish-pypi:
-    name: Publish to PyPI
+    name: Publish ${{ matrix.package.name }} to PyPI
     needs: build
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: flopscope
+          - name: flopscope-server
     # The `pypi` environment in repo settings has Required Reviewers
-    # configured, so this job pauses for a human approval before running.
+    # configured. A single approval click in this environment covers both
+    # matrix entries that share it.
     environment:
       name: pypi
-      url: https://pypi.org/project/flopscope/
+      url: https://pypi.org/project/${{ matrix.package.name }}/
     permissions:
       # Required for Trusted Publishing (OIDC). No long-lived token stored.
       id-token: write
@@ -56,7 +80,7 @@ jobs:
       - name: Download dist artifact
         uses: actions/download-artifact@v4
         with:
-          name: dist
+          name: dist-${{ matrix.package.name }}
           path: dist/
 
       - name: Publish to PyPI
@@ -82,7 +106,7 @@ jobs:
             capture { print }
           ' CHANGELOG.md > release-notes.md
 
-          # Fallback if no matching section (defensive — shouldn't happen if cz bump was used).
+          # Fallback if no matching section (defensive -- shouldn't happen if cz bump was used).
           if [ ! -s release-notes.md ]; then
             printf 'Release %s\n\nSee CHANGELOG.md for details.\n' "${GITHUB_REF_NAME}" > release-notes.md
           fi

flopscope-0.3.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+## v0.3.0 (2026-05-26)
+
+Synchronized multi-package release. The `flopscope-server` package is
+published to PyPI for the first time, versioned in lockstep with
+`flopscope`. The `flopscope-client` package is built and tested in this
+release but its PyPI publish is deferred to a follow-up release pending
+resolution of a PyPI Trusted Publisher bug (the publisher-create form
+returns 500 for the `flopscope-client` project name despite the
+identical request succeeding for `flopscope-server`).
+
+### Added
+
+- `flopscope[server]` extra: `pip install "flopscope[server]"` installs
+  both flopscope and flopscope-server, exact-pinned to the same version.
+- `flopscope-server` first PyPI release. Server-side runtime for the
+  client/server architecture; pulls in flopscope as a dependency.
+- Runtime version handshake between client and server: the first
+  request from a flopscope-client to a flopscope-server compares
+  versions and raises `ConnectionError` with both versions on mismatch.
+  Code lives in both packages so the contract is in place for the
+  follow-up flopscope-client PyPI release.
+
+### Changed
+
+- `flopscope.__version__` now reflects the synchronized release line
+  (still suffixed `+np<numpy_version>`).
+- `flopscope-server`'s `flopscope` dependency is now an exact pin
+  (`flopscope==0.3.0`) so server and library always travel together.
+
+### Tooling
+
+- Commitizen `version_files` is configured to update all version
+  strings across the three packages in one `cz bump` invocation,
+  including the cross-package pin.
+- New `scripts/check_version_sync.py` and `make check-sync-versions`
+  catch drift in CI before merge.
+- `.github/workflows/pypi-publish.yml` is now a matrix workflow:
+  one `v*` tag triggers three parallel builds, three parallel
+  publishes (gated by a single `pypi` environment approval), and one
+  GitHub Release.
+
+## v0.2.0 (2026-05-26)
+
+First PyPI release.
+
+Flopscope is a NumPy-compatible math library that counts every FLOP
+analytically, so compute budgets stop being guesswork.
+
+### What's included
+
+- 508 NumPy-compatible operations with analytical FLOP cost formulas
+- Symmetry-aware einsum cost model (direct-event α/M)
+- Orbit-mapping cost model for reductions (`sum`, `mean`, `median`, …)
+- Configurable FMA cost convention (1 op vs 2 op)
+- Budget tracking via `flopscope.BudgetContext` with namespaces and
+  per-operation breakdowns
+- Symmetric tensor support via `flopscope.as_symmetric`
+- Bilinear-wrapper symmetry propagation (`matmul`, `dot`, `outer`,
+  `inner`, `vdot`, `tensordot`)
+- Public inspection helpers: `einsum_accumulation_cost`,
+  `reduction_accumulation_cost`, `tier2_reduction_cost`
+
+### Release tooling
+
+- Commitizen for version bumps + CHANGELOG management
+- Conventional-commits enforcement via a `gitlint` `commit-msg` hook
+- PyPI publishing via Trusted Publishing (OIDC, no API tokens stored)
+- Auto-created GitHub Release on every tag push
+
+See the [README](README.md) for the API overview and the
+[docs site](https://aicrowd.github.io/flopscope/) for guides and the
+full API reference.
+
+## Unreleased

{flopscope-0.2.0 → flopscope-0.3.0}/Makefile

@@ -16,7 +16,7 @@ UV    := uv run
 # Composite targets
 # ---------------------------------------------------------------------------
 .PHONY: ci
-ci: lint lint-commits typecheck test test-numpy-compat check-sync docs-build  ## Run the full CI pipeline locally
+ci: lint lint-commits typecheck test test-numpy-compat check-sync check-sync-versions docs-build  ## Run the full CI pipeline locally
 
 # ---------------------------------------------------------------------------
 # Lint  (mirrors: CI → lint job)
@@ -87,6 +87,10 @@ check-sync:  ## Verify client is in sync with core library
 	$(UV) python scripts/sync_client.py --check
 	$(UV) pytest tests/test_client_server_parity.py tests/test_serialization_parity.py -v
 
+.PHONY: check-sync-versions
+check-sync-versions:  ## Verify all package versions are in lockstep
+	$(UV) python scripts/check_version_sync.py
+
 .PHONY: sync-client
 sync-client:  ## Regenerate client files from core library
 	$(UV) python scripts/sync_client.py

{flopscope-0.2.0 → flopscope-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flopscope
-Version: 0.2.0
+Version: 0.3.0
 Summary: NumPy-compatible math primitives with FLOP counting for the Mechanistic Estimation Challenge
 License-Expression: MIT
 Requires-Python: >=3.10
@@ -19,5 +19,7 @@ Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: scipy>=1.10; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: numpydoc>=1.10; extra == 'docs'
+Provides-Extra: server
+Requires-Dist: flopscope-server==0.3.0; extra == 'server'
 Provides-Extra: sympy
 Requires-Dist: sympy>=1.11; extra == 'sympy'

{flopscope-0.2.0 → flopscope-0.3.0}/README.md

@@ -117,6 +117,28 @@ uv add flopscope
 pip install flopscope
 ```
 
+For the server-side toolkit (heavy install plus the flopscope-server
+process for remote-execution architectures):
+
+```bash
+pip install "flopscope[server]"
+# equivalently:
+pip install flopscope-server
+```
+
+For the lightweight client (proxies all calls to a remote
+flopscope-server over ZMQ; no numpy dependency), build from the
+`flopscope-client/` subdirectory:
+
+```bash
+pip install "flopscope-client @ git+https://github.com/AIcrowd/flopscope.git#subdirectory=flopscope-client"
+```
+
+The client occupies the same `import flopscope` namespace as the main
+package — install it *instead of* `flopscope`, not alongside. A PyPI
+release of flopscope-client is pending; see
+[CHANGELOG.md](CHANGELOG.md) for status.
+
 Latest development version from git:
 
 ```bash

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flopscope-client"
-version = "0.1.0"
+version = "0.3.0"
 description = "Lightweight flopscope client — drop-in replacement with no numpy dependency"
 requires-python = ">=3.10"
 dependencies = [
@@ -18,11 +18,6 @@ packages = ["src/flopscope"]
 [tool.hatch.build.targets.wheel.force-include]
 "src/flopscope/data/default_weights.json" = "flopscope/data/default_weights.json"
 
-[tool.hatch.build.targets.sdist]
-include = [
-    "src/flopscope/data/default_weights.json",
-]
-
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/src/flopscope/__init__.py

@@ -18,7 +18,7 @@ import builtins
 import struct
 from typing import Any
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 # ---------------------------------------------------------------------------
 # Errors

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/src/flopscope/_connection.py

@@ -33,6 +33,7 @@ class Connection:
         self.timeout_ms: int = timeout_ms
         self._context: zmq.Context | None = None
         self._socket: zmq.Socket | None = None
+        self._handshake_done: bool = False
 
     # ------------------------------------------------------------------
     # Internal helpers
@@ -54,9 +55,61 @@ class Connection:
     # Public API
     # ------------------------------------------------------------------
 
+    def _ensure_handshaked(self) -> None:
+        """Send a `hello` once; raise ConnectionError on version mismatch.
+
+        Compares the client's leading X.Y.Z (`flopscope.__version__` minus
+        any `+np<numpy>` suffix) against the server. On success, sets
+        ``self._handshake_done = True``. Idempotent: subsequent calls
+        return immediately without sending again.
+
+        Raised exceptions
+        -----------------
+        ConnectionError
+            If the server reports VersionMismatch, returns a malformed
+            response, or fails to respond.
+        """
+        if self._handshake_done:
+            return
+
+        from flopscope import __version__ as _flopscope_version
+        from flopscope._protocol import encode_hello
+
+        client_xyz = _flopscope_version.split("+", 1)[0]
+        sock = self._ensure_connected()
+
+        try:
+            sock.send(encode_hello(client_xyz))
+            raw = sock.recv()
+        except zmq.Again as err:
+            self._reset_socket()
+            raise ConnectionError(
+                f"flopscope-client {client_xyz} handshake timeout: "
+                "server did not respond"
+            ) from err
+
+        response = decode_response(raw)
+        if (
+            response.get("status") == "error"
+            and response.get("error_type") == "VersionMismatch"
+        ):
+            raise ConnectionError(
+                f"flopscope-client {client_xyz} cannot talk to this server: "
+                f"{response.get('message', 'version mismatch')}"
+            )
+        if response.get("status") != "ok":
+            raise ConnectionError(
+                f"unexpected handshake response from server: {response!r}"
+            )
+        self._handshake_done = True
+
     def send_recv(self, raw_request: bytes) -> dict:
         """Send *raw_request* and return the decoded response dict.
 
+        On the first call against a fresh Connection, performs a lazy
+        version handshake with the server (a `hello` op carrying the
+        client's leading X.Y.Z) before forwarding the real request.
+
         Augments the response with timing/size metadata:
 
         * ``_round_trip_ns`` – round-trip time in nanoseconds
@@ -69,6 +122,7 @@ class Connection:
         from flopscope.errors import FlopscopeServerError
 
         sock = self._ensure_connected()
+        self._ensure_handshaked()
 
         t0 = time.monotonic_ns()
         try:
@@ -100,12 +154,14 @@ class Connection:
         if self._socket is not None:
             self._socket.close(linger=0)
             self._socket = None
+        self._handshake_done = False
 
     def close(self) -> None:
         """Close the ZMQ socket, if open."""
         if self._socket is not None:
             self._socket.close(linger=0)
             self._socket = None
+        self._handshake_done = False
 
 
 # ---------------------------------------------------------------------------

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/src/flopscope/_protocol.py

@@ -41,6 +41,11 @@ def encode_request(op: str, args=None, kwargs=None) -> bytes:
     )
 
 
+def encode_hello(client_version: str) -> bytes:
+    """Encode a `hello` op carrying the client's leading X.Y.Z version."""
+    return encode_request("hello", kwargs={"client_version": client_version})
+
+
 def encode_create_from_data(data: bytes, shape: list, dtype: str) -> bytes:
     """Encode a create_from_data request."""
     return encode_request("create_from_data", args=[data, shape, dtype])

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/tests/test_connection.py

@@ -318,6 +318,7 @@ class TestSendRecv:
             {"status": "ok", "result": 99}
         )
         conn._socket = mock_socket
+        conn._handshake_done = True  # bypass the lazy version handshake
 
         raw = encode_request("test_op")
         result = conn.send_recv(raw)
@@ -333,6 +334,7 @@ class TestSendRecv:
         mock_socket = MagicMock()
         mock_socket.recv.return_value = self._make_response({"status": "ok"})
         conn._socket = mock_socket
+        conn._handshake_done = True  # bypass the lazy version handshake
 
         raw = encode_request("test_op")
         result = conn.send_recv(raw)
@@ -353,6 +355,7 @@ class TestSendRecv:
             {"status": "error", "error_type": "FlopscopeServerError", "message": "boom"}
         )
         conn._socket = mock_socket
+        conn._handshake_done = True  # bypass the lazy version handshake
 
         raw = encode_request("op")
         with pytest.raises(FlopscopeServerError, match="boom"):
@@ -374,6 +377,7 @@ class TestSendRecv:
             }
         )
         conn._socket = mock_socket
+        conn._handshake_done = True  # bypass the lazy version handshake
 
         raw = encode_request("dot")
         with pytest.raises(BudgetExhaustedError):

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/tests/test_full_integration.py

@@ -431,3 +431,47 @@ class TestErrorPropagation:
             b = we.array([4.0, 5.0, 6.0])
             result = we.add(a, b)
             assert result.tolist() == [5.0, 7.0, 9.0]
+
+
+# ===========================================================================
+# Category 8: Version handshake (added in v0.3.0)
+# ===========================================================================
+
+
+class TestVersionHandshake:
+    def test_handshake_completes_transparently_on_first_op(self):
+        """A fresh Connection performs the version handshake on first send_recv."""
+        from flopscope._connection import get_connection
+
+        import flopscope as we
+
+        conn = get_connection()
+        assert conn._handshake_done is False
+
+        with we.BudgetContext(flop_budget=1_000):
+            a = we.array([1.0, 2.0, 3.0])
+            b = we.array([4.0, 5.0, 6.0])
+            we.add(a, b)
+
+        assert conn._handshake_done is True
+
+    def test_handshake_rejects_version_mismatch(self):
+        """A client whose __version__ doesn't match the server fails fast."""
+        from flopscope._connection import reset_connection
+
+        import flopscope
+        import flopscope as we
+
+        reset_connection()
+        original = flopscope.__version__
+        flopscope.__version__ = "9.99.99"
+        try:
+            with pytest.raises(ConnectionError) as excinfo:
+                with we.BudgetContext(flop_budget=1_000):
+                    we.array([1.0, 2.0, 3.0])
+            msg = str(excinfo.value)
+            assert "9.99.99" in msg
+            assert original.split("+", 1)[0] in msg
+        finally:
+            flopscope.__version__ = original
+            reset_connection()

flopscope-0.3.0/flopscope-client/tests/test_version_handshake.py

@@ -0,0 +1,106 @@
+"""Tests for the client-side lazy version handshake."""
+
+from __future__ import annotations
+
+import msgpack
+import pytest
+
+from flopscope import _connection, _protocol
+
+
+def test_encode_hello_serializes_client_version():
+    """encode_hello produces a hello op with a client_version kwarg."""
+    raw = _protocol.encode_hello("0.3.0")
+    decoded = msgpack.unpackb(raw, raw=False)
+    assert decoded["op"] == "hello"
+    assert decoded["kwargs"]["client_version"] == "0.3.0"
+
+
+class _FakeSocket:
+    """Stand-in for a zmq REQ socket: records sends, replays scripted recvs."""
+
+    def __init__(self, recv_payloads: list[bytes]) -> None:
+        self.sent: list[bytes] = []
+        self._recv_payloads = list(recv_payloads)
+
+    def send(self, payload: bytes) -> None:
+        self.sent.append(payload)
+
+    def recv(self) -> bytes:
+        return self._recv_payloads.pop(0)
+
+
+def _make_connection(socket: _FakeSocket) -> _connection.Connection:
+    conn = _connection.Connection()
+    conn._socket = socket
+    return conn
+
+
+def test_ensure_handshaked_happy_path_sets_flag_and_sends_hello():
+    server_ok = msgpack.packb(
+        {"status": "ok", "server_version": "0.3.0"}, use_bin_type=True
+    )
+    sock = _FakeSocket([server_ok])
+    conn = _make_connection(sock)
+
+    assert conn._handshake_done is False
+    conn._ensure_handshaked()
+    assert conn._handshake_done is True
+
+    first = msgpack.unpackb(sock.sent[0], raw=False)
+    assert first["op"] == "hello"
+    assert "client_version" in first["kwargs"]
+
+
+def test_ensure_handshaked_mismatch_raises_connection_error():
+    err = msgpack.packb(
+        {
+            "status": "error",
+            "error_type": "VersionMismatch",
+            "message": ("flopscope-client 0.3.0 cannot talk to flopscope-server 0.4.0"),
+        },
+        use_bin_type=True,
+    )
+    sock = _FakeSocket([err])
+    conn = _make_connection(sock)
+
+    with pytest.raises(ConnectionError) as excinfo:
+        conn._ensure_handshaked()
+    msg = str(excinfo.value)
+    assert "0.3.0" in msg
+    assert "0.4.0" in msg
+
+
+def test_ensure_handshaked_is_idempotent():
+    """Calling _ensure_handshaked twice only sends one hello."""
+    server_ok = msgpack.packb(
+        {"status": "ok", "server_version": "0.3.0"}, use_bin_type=True
+    )
+    sock = _FakeSocket([server_ok])
+    conn = _make_connection(sock)
+
+    conn._ensure_handshaked()
+    conn._ensure_handshaked()  # second call must not send again
+    assert len(sock.sent) == 1
+
+
+def test_send_recv_triggers_handshake_first():
+    """The first send_recv on a fresh Connection performs the handshake."""
+    server_ok_hello = msgpack.packb(
+        {"status": "ok", "server_version": "0.3.0"}, use_bin_type=True
+    )
+    server_ok_op = msgpack.packb(
+        {"status": "ok", "result": 42, "budget": 0, "comms_overhead_ns": 0},
+        use_bin_type=True,
+    )
+    sock = _FakeSocket([server_ok_hello, server_ok_op])
+    conn = _make_connection(sock)
+
+    # An arbitrary "op" request — not a hello — should still get handshaked first.
+    op_request = msgpack.packb({"op": "budget_status"}, use_bin_type=True)
+    response = conn.send_recv(op_request)
+    assert response["status"] == "ok"
+    assert conn._handshake_done is True
+    # Order matters: hello first, then the real op.
+    assert msgpack.unpackb(sock.sent[0], raw=False)["op"] == "hello"
+    assert msgpack.unpackb(sock.sent[1], raw=False)["op"] == "budget_status"

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-client/uv.lock

@@ -107,7 +107,7 @@ wheels = [
 
 [[package]]
 name = "flopscope-client"
-version = "0.1.0"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "msgpack" },

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-server/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flopscope-server"
-version = "0.1.0"
+version = "0.3.0"
 description = "Backend server for flopscope client-server architecture"
 requires-python = ">=3.10"
 dependencies = [
-    "flopscope>=0.2.0",
+    "flopscope==0.3.0",
     "numpy>=2.0.0,<2.5.0",
     "pyzmq>=26.0.0",
     "msgpack>=1.0.0",

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-server/src/flopscope_server/__init__.py

@@ -1,3 +1,3 @@
 """Flopscope backend server — executes numpy operations on behalf of remote clients."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"

{flopscope-0.2.0 → flopscope-0.3.0}/flopscope-server/src/flopscope_server/_protocol.py

@@ -23,6 +23,7 @@ from flopscope._registry import REGISTRY
 #: Protocol-level ops not in the numpy REGISTRY.
 _PROTOCOL_OPS: frozenset[str] = frozenset(
     {
+        "hello",
         "budget_open",
         "budget_close",
         "budget_status",