fluence-hpc 0.0.0__tar.gz

fluence_hpc-0.0.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: fluence-hpc
+Version: 0.0.0
+Summary: Fluence quantum-classical scheduling coordination library (sidecar + interceptor + providers)
+Author: Fluence / converged-computing
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: braket
+Requires-Dist: amazon-braket-sdk; extra == "braket"
+Requires-Dist: boto3; extra == "braket"
+Provides-Extra: all
+Requires-Dist: amazon-braket-sdk; extra == "all"
+Requires-Dist: boto3; extra == "all"
+
+# fluence (Python)
+
+Quantum-classical scheduling coordination library for the Fluence Kubernetes
+scheduler. Import name `fluence`; distributed on PyPI as `fluence-hpc`.
+
+This package is **built into the Fluence sidecar image** and **staged into user
+application containers at admission time** — users never install it.
+
+## What it does
+
+A hybrid quantum-classical workflow submits work to two queues: the Kubernetes
+scheduler (classical) and a QPU vendor API (quantum). Classical worker pods would
+idle while the QPU queue drains. Fluence gates the workers until the quantum task
+is about to run, then releases them. This library is the runtime half:
+
+- **interceptor** (`fluence.interceptor`) — runs inside the user container,
+  monkey-patches the vendor SDK submit call to tag each task with the pod UID.
+- **sidecar** (`fluence.sidecar`) — runs in a sidecar container, discovers the
+  tagged task, polls queue position, and ungates the classical workers when the
+  task is ready (or, in observe-only mode, just records the queue position).
+- **providers** (`fluence.providers`) — per-vendor plug-ins implementing both
+  halves. Providers self-register on import.
+
+## Delivery (Model C)
+
+The interceptor must run in the user's container, which does **not** have this
+package installed. Rather than require a user install or concatenate a text
+snippet, the Fluence webhook:
+
+1. injects an **init container** (the sidecar image) running
+   `python -m fluence.stage <dir>`, which copies the pure-Python `fluence`
+   package plus a `sitecustomize.py` into a shared `emptyDir`;
+2. mounts that volume into the user container and prepends `<dir>` to
+   `PYTHONPATH`.
+
+Python imports `sitecustomize` automatically on every interpreter start
+(`python app.py` included — unlike `PYTHONSTARTUP`, which only fires for
+interactive sessions), so `import fluence.interceptor` runs before user code.
+The interceptor patches whichever vendor SDK is present and fail-soft skips the
+rest. No user code changes, no vendor SDKs added to the user image.
+
+## Adding a provider
+
+Add one module under `fluence/providers/` that subclasses `Provider`, implements
+`install_interceptor` (tag hook), `matches`, `find_my_task`, `is_ready_to_ungate`,
+`queue_position` (optional), and `job_id`, and calls `register(PROVIDER)`. Import
+it from `fluence/providers/__init__.py`. Nothing else changes.
+
+## Tests
+
+    python3 python/tests/test_fluence.py
+
+## Building and releasing
+
+The package is distributed on PyPI as `fluence-hpc` (the import name `fluence` is
+already taken on PyPI). It is also baked into the sidecar image, so a release
+moves the package version and the image tag together.
+
+### Build the distributions
+
+From `python/`:
+
+    pip install --upgrade build twine
+    python -m build
+
+This produces `dist/fluence_hpc-<version>-py3-none-any.whl` and
+`dist/fluence_hpc-<version>.tar.gz`. Upload both.
+
+### Test on TestPyPI first
+
+    twine upload --repository testpypi dist/*
+    pip install --index-url https://test.pypi.org/simple/ fluence-hpc
+    python -c "import fluence; print(fluence.__version__)"
+
+### Release to PyPI
+
+    twine upload dist/*
+
+After this, `pip install fluence-hpc` works anywhere and imports as `fluence`.
+
+### Versioning
+
+Bump `version` in `pyproject.toml` and `__version__` in `fluence/__init__.py`
+together (PyPI refuses to overwrite an existing version). Because the package is
+version-locked into the sidecar image, tag the release so the image and the
+package share a version — e.g. a `v0.1.1` git tag triggers both the
+`sidecar-build-deploy` workflow (image) and a PyPI publish.
+
+### Automated release (recommended)
+
+Prefer GitHub Actions with PyPI Trusted Publishing (OIDC) over manual token
+uploads: register the repo + workflow once on PyPI, then a release workflow
+triggered by a version tag builds with `python -m build` and uploads with
+`pypa/gh-action-pypi-publish` — no stored secret. The Docker image is built by
+`.github/workflows/sidecar-build-deploy.yaml` on the same tag, keeping the
+package version and image tag in lockstep.

fluence_hpc-0.0.0/README.md

@@ -0,0 +1,96 @@
+# fluence (Python)
+
+Quantum-classical scheduling coordination library for the Fluence Kubernetes
+scheduler. Import name `fluence`; distributed on PyPI as `fluence-hpc`.
+
+This package is **built into the Fluence sidecar image** and **staged into user
+application containers at admission time** — users never install it.
+
+## What it does
+
+A hybrid quantum-classical workflow submits work to two queues: the Kubernetes
+scheduler (classical) and a QPU vendor API (quantum). Classical worker pods would
+idle while the QPU queue drains. Fluence gates the workers until the quantum task
+is about to run, then releases them. This library is the runtime half:
+
+- **interceptor** (`fluence.interceptor`) — runs inside the user container,
+  monkey-patches the vendor SDK submit call to tag each task with the pod UID.
+- **sidecar** (`fluence.sidecar`) — runs in a sidecar container, discovers the
+  tagged task, polls queue position, and ungates the classical workers when the
+  task is ready (or, in observe-only mode, just records the queue position).
+- **providers** (`fluence.providers`) — per-vendor plug-ins implementing both
+  halves. Providers self-register on import.
+
+## Delivery (Model C)
+
+The interceptor must run in the user's container, which does **not** have this
+package installed. Rather than require a user install or concatenate a text
+snippet, the Fluence webhook:
+
+1. injects an **init container** (the sidecar image) running
+   `python -m fluence.stage <dir>`, which copies the pure-Python `fluence`
+   package plus a `sitecustomize.py` into a shared `emptyDir`;
+2. mounts that volume into the user container and prepends `<dir>` to
+   `PYTHONPATH`.
+
+Python imports `sitecustomize` automatically on every interpreter start
+(`python app.py` included — unlike `PYTHONSTARTUP`, which only fires for
+interactive sessions), so `import fluence.interceptor` runs before user code.
+The interceptor patches whichever vendor SDK is present and fail-soft skips the
+rest. No user code changes, no vendor SDKs added to the user image.
+
+## Adding a provider
+
+Add one module under `fluence/providers/` that subclasses `Provider`, implements
+`install_interceptor` (tag hook), `matches`, `find_my_task`, `is_ready_to_ungate`,
+`queue_position` (optional), and `job_id`, and calls `register(PROVIDER)`. Import
+it from `fluence/providers/__init__.py`. Nothing else changes.
+
+## Tests
+
+    python3 python/tests/test_fluence.py
+
+## Building and releasing
+
+The package is distributed on PyPI as `fluence-hpc` (the import name `fluence` is
+already taken on PyPI). It is also baked into the sidecar image, so a release
+moves the package version and the image tag together.
+
+### Build the distributions
+
+From `python/`:
+
+    pip install --upgrade build twine
+    python -m build
+
+This produces `dist/fluence_hpc-<version>-py3-none-any.whl` and
+`dist/fluence_hpc-<version>.tar.gz`. Upload both.
+
+### Test on TestPyPI first
+
+    twine upload --repository testpypi dist/*
+    pip install --index-url https://test.pypi.org/simple/ fluence-hpc
+    python -c "import fluence; print(fluence.__version__)"
+
+### Release to PyPI
+
+    twine upload dist/*
+
+After this, `pip install fluence-hpc` works anywhere and imports as `fluence`.
+
+### Versioning
+
+Bump `version` in `pyproject.toml` and `__version__` in `fluence/__init__.py`
+together (PyPI refuses to overwrite an existing version). Because the package is
+version-locked into the sidecar image, tag the release so the image and the
+package share a version — e.g. a `v0.1.1` git tag triggers both the
+`sidecar-build-deploy` workflow (image) and a PyPI publish.
+
+### Automated release (recommended)
+
+Prefer GitHub Actions with PyPI Trusted Publishing (OIDC) over manual token
+uploads: register the repo + workflow once on PyPI, then a release workflow
+triggered by a version tag builds with `python -m build` and uploads with
+`pypa/gh-action-pypi-publish` — no stored secret. The Docker image is built by
+`.github/workflows/sidecar-build-deploy.yaml` on the same tag, keeping the
+package version and image tag in lockstep.

fluence_hpc-0.0.0/fluence/__init__.py

@@ -0,0 +1,16 @@
+"""
+fluence — quantum-classical scheduling coordination for the Fluence Kubernetes
+scheduler.
+
+This package is built into the Fluence sidecar image and staged into user
+application containers at admission time (via an init container + shared volume
+on PYTHONPATH), so the interceptor runs with zero user code changes.
+
+Submodules:
+  fluence.providers   provider interface + registry (per-vendor plug-ins)
+  fluence.interceptor  runs every registered provider's submit-time tag hook
+  fluence.sidecar      the sidecar coordination main loop
+  fluence.ungate       generic worker ungating (Kubernetes patch logic)
+"""
+
+__version__ = "0.1.0"

fluence_hpc-0.0.0/fluence/interceptor.py

@@ -0,0 +1,38 @@
+"""
+fluence.interceptor — installs every registered provider's submit-time tag hook.
+
+Runs inside the user's application container, triggered automatically by a
+sitecustomize.py on PYTHONPATH (staged there by the Fluence init container). On
+import it asks every registered provider to install its interceptor; each
+provider fail-soft skips if its vendor SDK is not present in this container.
+
+This module's import must never raise — sitecustomize guards it, but we also
+guard here so a single provider bug cannot affect the user application.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def install() -> None:
+    pod_uid = os.environ.get("FLUENCE_POD_UID", "")
+    try:
+        from fluence.providers import all_providers
+    except Exception as e:  # pragma: no cover - defensive
+        print(f"[fluence] interceptor: providers unavailable: {e}", flush=True)
+        return
+
+    for provider in all_providers():
+        try:
+            if provider.install_interceptor(pod_uid):
+                print(f"[fluence] interceptor installed for provider "
+                      f"{provider.name!r} (pod_uid={pod_uid})", flush=True)
+        except Exception as e:
+            # A provider's hook must never break the user app.
+            print(f"[fluence] interceptor for {provider.name!r} skipped: {e}",
+                  flush=True)
+
+
+# Install on import.
+install()

fluence_hpc-0.0.0/fluence/providers/__init__.py

@@ -0,0 +1,27 @@
+"""
+fluence.providers — provider registry.
+
+Importing this package imports every provider submodule, each of which calls
+fluence.providers.base.register() at import time. This is the single extension
+point: to add a vendor, drop a new module here that defines a Provider subclass
+and calls register() — nothing else in the codebase needs to change.
+
+Provider discovery is by explicit submodule import below (simple and debuggable).
+Importing a provider module never fails on a missing vendor SDK: the SDK is only
+imported lazily inside the methods that need it.
+"""
+
+from fluence.providers.base import (  # noqa: F401
+    Provider,
+    Task,
+    TAG_KEY,
+    log,
+    register,
+    all_providers,
+    resolve,
+    resolve_from_env,
+)
+
+# Import provider modules so they self-register. Add new providers here.
+from fluence.providers import braket  # noqa: F401,E402
+# from fluence.providers import ibm   # noqa: F401  (when implemented)

fluence_hpc-0.0.0/fluence/providers/base.py

@@ -0,0 +1,117 @@
+"""
+fluence.providers.base — the provider interface and registration machinery.
+
+A provider is a per-vendor plug-in (AWS Braket, IBM Qiskit Runtime, ...) that
+implements two halves of the quantum-coordination mechanism:
+
+  - INTERCEPTOR hook (`install_interceptor`): runs inside the user's application
+    container; monkey-patches the vendor SDK's submit call to stamp the shared
+    `fluence-pod-uid` tag on every task. Must fail-soft if the vendor SDK is not
+    importable in that container.
+
+  - SIDECAR methods (`matches`, `find_my_task`, `is_ready_to_ungate`,
+    `queue_position`, `job_id`): run inside the Fluence sidecar container; find
+    the tagged task, poll readiness, and yield a vendor-neutral job id.
+
+Providers self-register by calling `register()` at import time. The package
+imports every provider submodule (see fluence.providers.__init__) so importing
+the package registers them all. Registration is the single extension point:
+adding a vendor is one new module that calls register().
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timezone
+
+
+# Shared convention between every interceptor hook and every find_my_task.
+# The interceptor stamps this tag key with the pod UID; the sidecar searches
+# for it. Changing it is a coordinated change across all providers.
+TAG_KEY = "fluence-pod-uid"
+
+
+def log(msg: str) -> None:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    print(f"[fluence] {ts} {msg}", flush=True)
+
+
+class Task:
+    """
+    Opaque handle to a vendor quantum task. A provider returns its own subclass
+    from find_my_task; the framework treats it opaquely and only passes it back
+    to that provider. Vendor identifiers (ARN, job id) live inside.
+    """
+
+
+class Provider:
+    """Interface every quantum vendor implements. See module docstring."""
+
+    #: short stable name, e.g. "braket", "ibm"
+    name: str = "base"
+
+    # ── interceptor half (runs in the user container) ──────────────────────────
+
+    def install_interceptor(self, pod_uid: str) -> bool:
+        """
+        Monkey-patch this vendor's SDK submit call to stamp TAG_KEY=<pod_uid>.
+        Return True if the patch was installed, False if the SDK is absent
+        (fail-soft). Must never raise.
+        """
+        raise NotImplementedError
+
+    # ── sidecar half (runs in the sidecar container) ───────────────────────────
+
+    def matches(self, vendor: str, backend: str) -> bool:
+        """True if this provider handles the given vendor/backend (resolved at
+        runtime from the pod's backend annotation)."""
+        raise NotImplementedError
+
+    def find_my_task(self, pod_uid: str, backend: str, timeout: int) -> "Task | None":
+        """Search the vendor for the task tagged TAG_KEY=<pod_uid>, polling until
+        found or timeout. Returns an opaque Task or None."""
+        raise NotImplementedError
+
+    def is_ready_to_ungate(self, task: "Task") -> bool:
+        """True when workers should be ungated — queue position == 1 or the task
+        is already RUNNING/terminal. Always implementable."""
+        raise NotImplementedError
+
+    def queue_position(self, task: "Task") -> "int | None":
+        """Optional richer telemetry: integer queue position (1 == next), or None
+        if the vendor does not expose one. Not required for the ungate decision."""
+        return None
+
+    def job_id(self, task: "Task") -> str:
+        """Stable, vendor-neutral identifier handed to workers at ungate time."""
+        raise NotImplementedError
+
+
+# ── registry ────────────────────────────────────────────────────────────────────
+
+_REGISTRY: "list[Provider]" = []
+
+
+def register(provider: Provider) -> None:
+    """Register a provider. Called by each provider module at import time."""
+    _REGISTRY.append(provider)
+
+
+def all_providers() -> "list[Provider]":
+    return list(_REGISTRY)
+
+
+def resolve(vendor: str = "", backend: str = "") -> "Provider | None":
+    """Return the registered provider matching vendor/backend, or None."""
+    for p in _REGISTRY:
+        try:
+            if p.matches(vendor, backend):
+                return p
+        except Exception as e:  # a provider's matches() must never break resolution
+            log(f"provider {p.name!r} matches() error: {e}")
+    return None
+
+
+def resolve_from_env() -> "Provider | None":
+    return resolve(os.environ.get("FLUXION_VENDOR", ""),
+                   os.environ.get("FLUXION_BACKEND", ""))

fluence_hpc-0.0.0/fluence/providers/braket.py

@@ -0,0 +1,122 @@
+"""
+fluence.providers.braket — AWS Braket provider.
+
+Holds both halves of the Braket coordination mechanism:
+  - install_interceptor: patches AwsDevice.run() to stamp the pod-uid tag
+    (runs in the user container; fail-soft if amazon-braket-sdk is absent).
+  - sidecar methods: discover the tagged task, poll queue position, yield the
+    task ARN as the (vendor-neutral-typed) job id.
+
+Self-registers via register(PROVIDER) at import. Importing this module never
+requires the braket SDK; SDK imports are lazy, inside the methods.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+from fluence.providers.base import Provider, Task, TAG_KEY, log, register
+
+
+class BraketTask(Task):
+    def __init__(self, arn: str):
+        self.arn = arn
+
+
+def _region_from_arn(arn: str) -> str:
+    parts = arn.split(":")
+    region = parts[3] if len(parts) > 3 and parts[3] else ""
+    return region or os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+
+
+class BraketProvider(Provider):
+    name = "braket"
+
+    # ── interceptor half ───────────────────────────────────────────────────────
+
+    def install_interceptor(self, pod_uid: str) -> bool:
+        try:
+            from braket.aws import AwsDevice
+        except ImportError:
+            return False  # braket SDK not in this container — fail-soft
+
+        original_run = AwsDevice.run
+
+        def patched_run(self, task_specification, *args, **kwargs):
+            if pod_uid:
+                tags = kwargs.get("tags", {})
+                tags[TAG_KEY] = pod_uid
+                kwargs["tags"] = tags
+            return original_run(self, task_specification, *args, **kwargs)
+
+        AwsDevice.run = patched_run
+        return True
+
+    # ── sidecar half ───────────────────────────────────────────────────────────
+
+    def matches(self, vendor: str, backend: str) -> bool:
+        v, b = (vendor or "").lower(), (backend or "").lower()
+        if v == "braket":
+            return True
+        return "braket" in b or b.startswith("arn:aws:braket")
+
+    def _client(self, backend: str):
+        import boto3
+        region = (_region_from_arn(backend) if backend.startswith("arn:")
+                  else os.environ.get("AWS_DEFAULT_REGION", "us-east-1"))
+        return boto3.client("braket", region_name=region)
+
+    def find_my_task(self, pod_uid, backend, timeout):
+        client = self._client(backend)
+        log(f"[braket] searching for task tagged {TAG_KEY}={pod_uid}")
+        deadline = time.time() + timeout
+        device_arn = backend if backend.startswith("arn:aws:braket") else None
+        while time.time() < deadline:
+            try:
+                filters = [{"name": f"tags:{TAG_KEY}", "operator": "EQUAL",
+                            "values": [pod_uid]}]
+                if device_arn:
+                    filters.append({"name": "deviceArn", "operator": "EQUAL",
+                                    "values": [device_arn]})
+                resp = client.search_quantum_tasks(filters=filters, maxResults=10)
+                tasks = resp.get("quantumTasks", [])
+                if tasks:
+                    tasks.sort(key=lambda t: t.get("createdAt", ""), reverse=True)
+                    arn = tasks[0]["quantumTaskArn"]
+                    log(f"[braket] found task by tag: {arn}")
+                    return BraketTask(arn)
+            except Exception as e:
+                log(f"[braket] search error (will retry): {e}")
+            time.sleep(10)
+        log("[braket] task discovery timed out")
+        return None
+
+    def _aws_task(self, task: BraketTask):
+        import asyncio
+        asyncio.set_event_loop(asyncio.new_event_loop())
+        from braket.aws import AwsQuantumTask
+        return AwsQuantumTask(arn=task.arn)
+
+    def is_ready_to_ungate(self, task: BraketTask) -> bool:
+        t = self._aws_task(task)
+        if t.state() in ("RUNNING", "COMPLETED", "FAILED", "CANCELLED"):
+            return True
+        try:
+            return str(t.queue_position().queue_position) == "1"
+        except Exception:
+            return False
+
+    def queue_position(self, task: BraketTask):
+        try:
+            pos = self._aws_task(task).queue_position().queue_position
+            return int(pos) if pos is not None and str(pos).isdigit() else None
+        except Exception:
+            return None
+
+    def job_id(self, task: BraketTask) -> str:
+        return task.arn
+
+
+PROVIDER = BraketProvider()
+register(PROVIDER)

fluence_hpc-0.0.0/fluence/sidecar.py

@@ -0,0 +1,99 @@
+"""
+fluence.sidecar — provider-agnostic quantum coordination sidecar main loop.
+
+Injected by the Fluence webhook into the quantum-submitting pod. Resolves its
+vendor at runtime from the backend annotation, discovers the task the user
+application submitted (tagged by the interceptor), polls readiness, and either
+ungates gated workers (gang mode) or just logs the queue-position series
+(observe-only mode).
+
+Entry point: `fluence-sidecar` console script (see pyproject.toml) -> main().
+
+Environment (injected by the Fluence webhook):
+  FLUENCE_POD_UID                 UID of this pod (matches interceptor tag)
+  FLUENCE_NAMESPACE               Kubernetes namespace
+  FLUENCE_GATED_PODS              comma-separated gated worker names
+  FLUENCE_OBSERVE                 "true" for observe-only telemetry mode
+  FLUXION_BACKEND / FLUXION_VENDOR  scheduler-chosen backend / vendor
+  FLUENCE_TASK_DISCOVERY_TIMEOUT  seconds to wait for discovery (default 300)
+  FLUENCE_POLL_INTERVAL           seconds between polls (default 30)
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from fluence.providers import resolve_from_env
+from fluence.providers.base import log
+from fluence.ungate import ungate_pods, gated_pods_from_env, namespace_from_env
+
+
+def _poll(provider, task, poll_interval, ungate):
+    mode = "gang" if ungate else "observe-only"
+    log(f"{mode} mode: polling queue position")
+    last = object()
+    while True:
+        try:
+            if provider.is_ready_to_ungate(task):
+                log(f"task ready (position={provider.queue_position(task)})")
+                return
+            pos = provider.queue_position(task)
+            if pos != last:
+                log(f"queue position: {pos}")
+                last = pos
+        except Exception as e:
+            log(f"poll error (will retry): {e}")
+        time.sleep(poll_interval)
+
+
+def main():
+    pod_uid = os.environ.get("FLUENCE_POD_UID", "")
+    backend = os.environ.get("FLUXION_BACKEND", "")
+    observe = os.environ.get("FLUENCE_OBSERVE", "").lower() == "true"
+    discovery_timeout = int(os.environ.get("FLUENCE_TASK_DISCOVERY_TIMEOUT", 300))
+    poll_interval = int(os.environ.get("FLUENCE_POLL_INTERVAL", 30))
+
+    namespace = namespace_from_env()
+    gated_pods = gated_pods_from_env()
+
+    log("starting fluence quantum sidecar")
+    log(f"  pod_uid={pod_uid} namespace={namespace} backend={backend} "
+        f"observe={observe} gated_pods={gated_pods}")
+
+    provider = resolve_from_env()
+    if provider is None:
+        log("ERROR: could not resolve a quantum provider from the backend")
+        if gated_pods and not observe:
+            ungate_pods(gated_pods, "", namespace)
+        sys.exit(1)
+    log(f"resolved provider: {provider.name}")
+
+    if not observe and not gated_pods:
+        log("no gated workers and not observe mode — nothing to do")
+        return
+
+    task = provider.find_my_task(pod_uid, backend, discovery_timeout)
+    if task is None:
+        log("ERROR: could not discover quantum task")
+        if gated_pods and not observe:
+            log("ungating workers anyway to avoid deadlock")
+            ungate_pods(gated_pods, "", namespace)
+        sys.exit(1)
+
+    job_id = provider.job_id(task)
+    log(f"discovered task, job_id={job_id}")
+
+    _poll(provider, task, poll_interval, ungate=not observe)
+
+    if observe:
+        log("observe-only run complete")
+        return
+
+    ungate_pods(gated_pods, job_id, namespace)
+    log("done — workers ungated")
+
+
+if __name__ == "__main__":
+    main()

fluence_hpc-0.0.0/fluence/sitecustomize.py

@@ -0,0 +1,12 @@
+# fluence sitecustomize — staged onto the user container's PYTHONPATH by the
+# Fluence init container. Python imports `sitecustomize` automatically on every
+# interpreter start (interactive OR script), so this runs the interceptor with
+# zero user code changes and without relying on PYTHONSTARTUP (which only fires
+# for interactive sessions).
+#
+# Guarded so a fluence-side error can never break the user's application.
+try:
+    import fluence.interceptor  # noqa: F401  (import side-effect installs hooks)
+except Exception as _e:  # pragma: no cover
+    import sys
+    print(f"[fluence] interceptor skipped: {_e}", file=sys.stderr, flush=True)

fluence_hpc-0.0.0/fluence/stage.py

@@ -0,0 +1,59 @@
+"""
+fluence.stage — init-container entrypoint for Model C delivery.
+
+The Fluence webhook injects an init container (the sidecar image, which has
+`fluence` installed) that runs `python -m fluence.stage <dest>`. This copies the
+installed `fluence` package plus a `sitecustomize.py` into <dest>, a shared
+emptyDir volume. The webhook mounts that volume into the user's application
+container and prepends <dest> to PYTHONPATH. Python then auto-imports
+sitecustomize on startup, which imports fluence.interceptor — tagging the user's
+quantum tasks with zero user code changes and no vendor SDK requirement on our
+side (the interceptor patches whatever SDK the user already has).
+
+Replaces the old build-interceptor.sh: assembly is real package staging, not
+text concatenation.
+
+Usage:
+  python -m fluence.stage /opt/fluence-staged
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+
+import fluence
+
+
+def stage(dest: str) -> None:
+    os.makedirs(dest, exist_ok=True)
+
+    # Copy the installed `fluence` package into <dest>/fluence so it is importable
+    # when <dest> is on PYTHONPATH. We copy only the pure-Python package — no
+    # vendor SDKs — so we never perturb the user container's own dependencies.
+    pkg_src = os.path.dirname(os.path.abspath(fluence.__file__))
+    pkg_dst = os.path.join(dest, "fluence")
+    if os.path.exists(pkg_dst):
+        shutil.rmtree(pkg_dst)
+    shutil.copytree(
+        pkg_src, pkg_dst,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "tests"),
+    )
+
+    # Place sitecustomize.py at the TOP of <dest> (not inside the package) so
+    # Python's site machinery imports it automatically on interpreter startup.
+    src_sitecustomize = os.path.join(pkg_src, "sitecustomize.py")
+    shutil.copyfile(src_sitecustomize, os.path.join(dest, "sitecustomize.py"))
+
+    print(f"[fluence] staged package + sitecustomize into {dest}", flush=True)
+
+
+def main(argv=None):
+    argv = argv if argv is not None else sys.argv[1:]
+    dest = argv[0] if argv else os.environ.get("FLUENCE_STAGE_DIR", "/opt/fluence-staged")
+    stage(dest)
+
+
+if __name__ == "__main__":
+    main()

fluence_hpc-0.0.0/fluence/ungate.py

@@ -0,0 +1,73 @@
+"""
+fluence.ungate — generic worker ungating (Kubernetes side).
+
+Once the sidecar determines the quantum task is ready, it ungates the gated
+classical worker pods: stamp the vendor-neutral job-id annotation, set the
+high-priority class, and remove the scheduling gate atomically. This is pure
+Kubernetes plumbing — no vendor specifics.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+
+from fluence.providers.base import log
+
+JOB_ID_ANNOTATION = "fluence.flux-framework.org/quantum-job-id"
+QUANTUM_GATE_NAME = "quantum.braket/ready"
+PRIORITY_CLASS = "fluence-quantum-classical"
+
+
+def kubectl(args):
+    result = subprocess.run(["kubectl"] + args, capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RuntimeError(f"kubectl {' '.join(args)} failed: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def ungate_pods(gated_pods, job_id, namespace):
+    """
+    For each gated worker pod:
+      1. Stamp the vendor-neutral job-id annotation so the worker can locate
+         the quantum result.
+      2. Set the high-priority class and remove the scheduling gate atomically
+         (priority is set here, not in the webhook, to avoid the admission
+         controller conflict where priority:0 is already defaulted).
+    """
+    for pod_name in gated_pods:
+        pod_name = pod_name.strip()
+        if not pod_name:
+            continue
+        log(f"ungating pod: {pod_name}")
+
+        if job_id:
+            try:
+                kubectl(["annotate", "pod", pod_name, "-n", namespace,
+                         f"{JOB_ID_ANNOTATION}={job_id}", "--overwrite"])
+                log(f"  patched job id onto {pod_name}: {job_id}")
+            except RuntimeError as e:
+                log(f"  WARNING: could not annotate {pod_name}: {e}")
+        else:
+            log(f"  WARNING: no job id to patch onto {pod_name}")
+
+        patch = json.dumps([
+            {"op": "add", "path": "/spec/priorityClassName", "value": PRIORITY_CLASS},
+            {"op": "remove", "path": "/spec/schedulingGates/0"},
+        ])
+        try:
+            kubectl(["patch", "pod", pod_name, "-n", namespace,
+                     "--type=json", f"-p={patch}"])
+            log(f"  set priority and removed gate from {pod_name}")
+        except RuntimeError as e:
+            log(f"  WARNING: could not patch {pod_name}: {e}")
+
+
+def gated_pods_from_env():
+    return [p.strip() for p in os.environ.get("FLUENCE_GATED_PODS", "").split(",")
+            if p.strip()]
+
+
+def namespace_from_env():
+    return os.environ.get("FLUENCE_NAMESPACE", "default")

fluence_hpc-0.0.0/fluence_hpc.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: fluence-hpc
+Version: 0.0.0
+Summary: Fluence quantum-classical scheduling coordination library (sidecar + interceptor + providers)
+Author: Fluence / converged-computing
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: braket
+Requires-Dist: amazon-braket-sdk; extra == "braket"
+Requires-Dist: boto3; extra == "braket"
+Provides-Extra: all
+Requires-Dist: amazon-braket-sdk; extra == "all"
+Requires-Dist: boto3; extra == "all"
+
+# fluence (Python)
+
+Quantum-classical scheduling coordination library for the Fluence Kubernetes
+scheduler. Import name `fluence`; distributed on PyPI as `fluence-hpc`.
+
+This package is **built into the Fluence sidecar image** and **staged into user
+application containers at admission time** — users never install it.
+
+## What it does
+
+A hybrid quantum-classical workflow submits work to two queues: the Kubernetes
+scheduler (classical) and a QPU vendor API (quantum). Classical worker pods would
+idle while the QPU queue drains. Fluence gates the workers until the quantum task
+is about to run, then releases them. This library is the runtime half:
+
+- **interceptor** (`fluence.interceptor`) — runs inside the user container,
+  monkey-patches the vendor SDK submit call to tag each task with the pod UID.
+- **sidecar** (`fluence.sidecar`) — runs in a sidecar container, discovers the
+  tagged task, polls queue position, and ungates the classical workers when the
+  task is ready (or, in observe-only mode, just records the queue position).
+- **providers** (`fluence.providers`) — per-vendor plug-ins implementing both
+  halves. Providers self-register on import.
+
+## Delivery (Model C)
+
+The interceptor must run in the user's container, which does **not** have this
+package installed. Rather than require a user install or concatenate a text
+snippet, the Fluence webhook:
+
+1. injects an **init container** (the sidecar image) running
+   `python -m fluence.stage <dir>`, which copies the pure-Python `fluence`
+   package plus a `sitecustomize.py` into a shared `emptyDir`;
+2. mounts that volume into the user container and prepends `<dir>` to
+   `PYTHONPATH`.
+
+Python imports `sitecustomize` automatically on every interpreter start
+(`python app.py` included — unlike `PYTHONSTARTUP`, which only fires for
+interactive sessions), so `import fluence.interceptor` runs before user code.
+The interceptor patches whichever vendor SDK is present and fail-soft skips the
+rest. No user code changes, no vendor SDKs added to the user image.
+
+## Adding a provider
+
+Add one module under `fluence/providers/` that subclasses `Provider`, implements
+`install_interceptor` (tag hook), `matches`, `find_my_task`, `is_ready_to_ungate`,
+`queue_position` (optional), and `job_id`, and calls `register(PROVIDER)`. Import
+it from `fluence/providers/__init__.py`. Nothing else changes.
+
+## Tests
+
+    python3 python/tests/test_fluence.py
+
+## Building and releasing
+
+The package is distributed on PyPI as `fluence-hpc` (the import name `fluence` is
+already taken on PyPI). It is also baked into the sidecar image, so a release
+moves the package version and the image tag together.
+
+### Build the distributions
+
+From `python/`:
+
+    pip install --upgrade build twine
+    python -m build
+
+This produces `dist/fluence_hpc-<version>-py3-none-any.whl` and
+`dist/fluence_hpc-<version>.tar.gz`. Upload both.
+
+### Test on TestPyPI first
+
+    twine upload --repository testpypi dist/*
+    pip install --index-url https://test.pypi.org/simple/ fluence-hpc
+    python -c "import fluence; print(fluence.__version__)"
+
+### Release to PyPI
+
+    twine upload dist/*
+
+After this, `pip install fluence-hpc` works anywhere and imports as `fluence`.
+
+### Versioning
+
+Bump `version` in `pyproject.toml` and `__version__` in `fluence/__init__.py`
+together (PyPI refuses to overwrite an existing version). Because the package is
+version-locked into the sidecar image, tag the release so the image and the
+package share a version — e.g. a `v0.1.1` git tag triggers both the
+`sidecar-build-deploy` workflow (image) and a PyPI publish.
+
+### Automated release (recommended)
+
+Prefer GitHub Actions with PyPI Trusted Publishing (OIDC) over manual token
+uploads: register the repo + workflow once on PyPI, then a release workflow
+triggered by a version tag builds with `python -m build` and uploads with
+`pypa/gh-action-pypi-publish` — no stored secret. The Docker image is built by
+`.github/workflows/sidecar-build-deploy.yaml` on the same tag, keeping the
+package version and image tag in lockstep.

fluence_hpc-0.0.0/fluence_hpc.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+fluence/__init__.py
+fluence/interceptor.py
+fluence/sidecar.py
+fluence/sitecustomize.py
+fluence/stage.py
+fluence/ungate.py
+fluence/providers/__init__.py
+fluence/providers/base.py
+fluence/providers/braket.py
+fluence_hpc.egg-info/PKG-INFO
+fluence_hpc.egg-info/SOURCES.txt
+fluence_hpc.egg-info/dependency_links.txt
+fluence_hpc.egg-info/entry_points.txt
+fluence_hpc.egg-info/requires.txt
+fluence_hpc.egg-info/top_level.txt
+tests/test_fluence.py

fluence_hpc-0.0.0/fluence_hpc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fluence_hpc-0.0.0/fluence_hpc.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fluence-sidecar = fluence.sidecar:main

fluence_hpc-0.0.0/fluence_hpc.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[all]
+amazon-braket-sdk
+boto3
+
+[braket]
+amazon-braket-sdk
+boto3

fluence_hpc-0.0.0/fluence_hpc.egg-info/top_level.txt

@@ -0,0 +1 @@
+fluence

fluence_hpc-0.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI distribution name (the import name `fluence` is taken on PyPI, so we
+# distribute under a scoped name but import as `fluence`).
+name = "fluence-hpc"
+version = "0.0.0"
+description = "Fluence quantum-classical scheduling coordination library (sidecar + interceptor + providers)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Fluence / converged-computing" }]
+
+# No hard runtime dependencies. Vendor SDKs (amazon-braket-sdk, qiskit-ibm-
+# runtime, ...) are optional extras installed in the SIDECAR image only. The
+# interceptor never imports an SDK it isn't already running alongside.
+dependencies = []
+
+[project.optional-dependencies]
+braket = ["amazon-braket-sdk", "boto3"]
+# ibm = ["qiskit-ibm-runtime"]
+all = ["amazon-braket-sdk", "boto3"]
+
+[project.scripts]
+fluence-sidecar = "fluence.sidecar:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["fluence*"]

fluence_hpc-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fluence_hpc-0.0.0/tests/test_fluence.py

@@ -0,0 +1,108 @@
+"""
+Tests for the fluence package. Run: python3 -m pytest python/tests/
+None of these require a vendor SDK — they exercise registration, resolution,
+fail-soft interceptor behavior, and the staging mechanism.
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+
+
+def test_braket_registered():
+    from fluence.providers import all_providers
+    assert "braket" in [p.name for p in all_providers()]
+
+
+def test_resolve_braket_by_vendor():
+    from fluence.providers import resolve
+    assert resolve("braket", "").name == "braket"
+
+
+def test_resolve_braket_by_arn_backend():
+    from fluence.providers import resolve
+    p = resolve("", "arn:aws:braket:us-east-1::device/quantum-simulator/amazon/sv1")
+    assert p is not None and p.name == "braket"
+
+
+def test_resolve_unknown_returns_none():
+    from fluence.providers import resolve
+    assert resolve("nope", "nope") is None
+
+
+def test_interceptor_failsoft_without_sdk():
+    # Importing the interceptor must not raise even though braket is absent.
+    import importlib
+    import fluence.interceptor
+    importlib.reload(fluence.interceptor)  # re-run install(); must not raise
+
+
+def test_braket_install_interceptor_failsoft():
+    from fluence.providers.braket import PROVIDER
+    # No braket SDK installed -> returns False, never raises.
+    assert PROVIDER.install_interceptor("uid") is False
+
+
+def test_job_id_is_arn():
+    from fluence.providers.braket import PROVIDER, BraketTask
+    arn = "arn:aws:braket:us-east-1::quantum-task/abc-123"
+    assert PROVIDER.job_id(BraketTask(arn)) == arn
+
+
+def test_stage_produces_importable_package():
+    # python -m fluence.stage <dest> must create an importable fluence + a
+    # top-level sitecustomize.py.
+    with tempfile.TemporaryDirectory() as d:
+        subprocess.run([sys.executable, "-m", "fluence.stage", d], check=True)
+        assert os.path.isfile(os.path.join(d, "sitecustomize.py"))
+        assert os.path.isfile(os.path.join(d, "fluence", "__init__.py"))
+        assert os.path.isdir(os.path.join(d, "fluence", "providers"))
+        # __pycache__ and tests must be excluded from the staged copy.
+        assert not os.path.exists(os.path.join(d, "fluence", "tests"))
+
+
+def test_staged_sitecustomize_runs_interceptor():
+    # Stage, then run a subprocess with ONLY the staged dir on PYTHONPATH and a
+    # fake braket SDK; the interceptor must patch AwsDevice.run to inject the tag.
+    with tempfile.TemporaryDirectory() as d:
+        staged = os.path.join(d, "staged")
+        subprocess.run([sys.executable, "-m", "fluence.stage", staged], check=True)
+
+        fakesdk = os.path.join(d, "fakesdk")
+        os.makedirs(os.path.join(fakesdk, "braket", "aws"))
+        open(os.path.join(fakesdk, "braket", "__init__.py"), "w").close()
+        with open(os.path.join(fakesdk, "braket", "aws", "__init__.py"), "w") as f:
+            f.write(
+                "class AwsDevice:\n"
+                "    def run(self, spec, *a, **k):\n"
+                "        print('TAGS', k.get('tags'))\n"
+            )
+        app = os.path.join(d, "app.py")
+        with open(app, "w") as f:
+            f.write("from braket.aws import AwsDevice\nAwsDevice().run('c')\n")
+
+        env = {
+            "PATH": os.environ.get("PATH", ""),
+            "HOME": d,
+            "FLUENCE_POD_UID": "pod-xyz",
+            "PYTHONPATH": staged + os.pathsep + fakesdk,
+        }
+        out = subprocess.run([sys.executable, app], env=env,
+                             capture_output=True, text=True)
+        assert "fluence-pod-uid" in out.stdout, out.stdout + out.stderr
+        assert "pod-xyz" in out.stdout, out.stdout + out.stderr
+
+
+if __name__ == "__main__":
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = 0
+    for fn in fns:
+        try:
+            fn()
+            print(f"PASS {fn.__name__}")
+        except Exception as e:
+            failed += 1
+            print(f"FAIL {fn.__name__}: {e}")
+    print(f"\n{len(fns) - failed}/{len(fns)} passed")
+    sys.exit(1 if failed else 0)