benchcraft-core 0.1.0__py3-none-any.whl

benchcraft_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: benchcraft-core
+Version: 0.1.0
+Summary: Benchcraft Core: the thin, shared substrate used by all Benchcraft modules (data-tier conventions, OTel GenAI telemetry helpers, license-isolation policy).
+Author: Benchcraft
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pandas>=2.0; extra == 'dev'
+Requires-Dist: polars>=0.20; extra == 'dev'
+Requires-Dist: pyarrow>=14.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lazycore
+
+The thin, shared substrate underneath every Benchcraft module (AutoML,
+LazyClean, LazyForecast, LazyGraph, LazyVision, LazyTune, LazyRed,
+LazyAgent). It exists so that modules working on largely the same
+underlying data, telemetry, and licensing concerns don't each invent their
+own conventions -- without forcing premature unification of things that
+genuinely differ per module.
+
+## This package is intentionally thin. Here's why.
+
+Benchcraft's packaging model (architecture doc §2.7) is Hugging Face-style:
+independently-versioned, separate packages per module, sharing one thin
+`lazycore` package for common schemas/interfaces with near-zero
+dependencies -- explicitly **not** one monorepo with pip extras. The reason
+is concrete, not aesthetic: PyTorch-heavy modules (LazyTune, LazyVision,
+LazyGraph), the deliberately PyTorch-free LazyClean (which stays under a
+100MB footprint by using ONNX Runtime instead of PyTorch), and the
+Node-adjacent tooling implied by LazyRed's Promptfoo integration have
+genuinely conflicting dependency universes that pip's extras resolver
+cannot cleanly reconcile. If `lazycore` pulled in pandas, polars, or torch
+as hard dependencies, every module -- including the ones explicitly
+designed to avoid those dependencies -- would be forced to install them
+just to get `import lazycore` to work. That defeats the entire point of
+per-module packaging.
+
+The architecture doc is equally explicit that formal, typed interface
+contracts between modules (in the style of MLflow's model "flavors") are
+**deferred** until at least two real modules actually need to exchange
+data (§2.9) -- so `lazycore` does not attempt to be a data-contract system.
+What it provides instead are lightweight, checked-in *conventions*:
+type-hint-only interfaces, small helper functions, policy tables encoded as
+data. Nothing here assumes what shape a future formal contract should take.
+
+Concretely, `lazycore`'s runtime dependency footprint is exactly one
+non-stdlib package: `opentelemetry-api` (never the SDK). It does not depend
+on pandas, polars, torch, or any ML framework -- where those are referenced
+for type hints, the imports are guarded behind `typing.TYPE_CHECKING` or
+done lazily inside a function body, so importing `lazycore` never forces
+any of them to be installed.
+
+## What's in here
+
+Everything in this package maps directly to a locked decision in Part 2 of
+`Benchcraft_Unified_Architecture.md`. Nothing module-specific belongs here
+(see the repo's `CLAUDE.md`, "lazycore stays thin").
+
+### `lazycore.data` -- three-tier data/tensor conventions (§2.1)
+
+- **Tier 1 (dense tabular/text/time-series):** small conversion/validation
+  helpers over Arrow-backed pandas 2.x (`ArrowDtype`) and Polars, since both
+  are confirmed near-zero-cost, interchangeable front-ends over the same
+  Arrow buffers. `is_arrow_backed_pandas`, `pandas_arrow_dtypes`,
+  `to_polars_zero_copy`, `from_polars_zero_copy`.
+- **Tier 2 (sparse graph tensors):** `SparseGraphTensorAdapter`, an abstract
+  base class describing the COO/CSR-CSC conversion boundary DLPack cannot
+  represent. No graph-library dependency; LazyGraph provides concrete PyG-
+  and DGL-facing implementations.
+- **Tier 3 (dense image/audio):** `DenseMediaPipeline`, an abstract base
+  class describing an FFCV-style decode → augment → DLPack-handoff
+  pipeline shape (decode/augment are compute-bound, not copy-bound, so
+  DLPack only applies at the final dense-tensor stage). LazyVision provides
+  concrete implementations.
+
+### `lazycore.telemetry` -- OpenTelemetry GenAI semantic conventions (§2.6)
+
+Shared attribute-name constants (`security.severity`, `owasp.mapping`,
+`ml.metric.*`) and a thin wrapper (`genai_span`, `set_security_finding`,
+`set_ml_metric`, `add_transcript_event`) over `opentelemetry-api` so
+LazyRed's security-audit reports, LazyAgent's execution trajectories, and
+the ML leaderboards from AutoML/LazyForecast/LazyGraph/LazyVision all
+report through the same schema. Depends only on `opentelemetry-api`; if the
+calling application hasn't configured an SDK TracerProvider, spans are
+OTel's documented no-ops -- safe to call, nothing exported until a real
+exporter is wired up by whichever module needs one.
+
+### `lazycore.licensing` -- license-isolation and model-allowlist policy (§2.2, §2.10)
+
+- `RiskType` / `Mitigation` / `RISK_MITIGATIONS`: the §2.2 License Isolation
+  Policy decision table, encoded as data rather than prose, so module
+  owners can look up the exact required mitigation for a given dependency
+  risk (GPL-at-build-time, restrictive optional build dep,
+  AGPL/GPL-at-runtime-internal, AGPL/GPL-network-facing,
+  source-available-non-compete, non-commercial weights).
+- `ModelTier` / `ModelLicenseEntry` / `Allowlist`: the §2.10 mechanism every
+  module uses to register and check model checkpoints against Tier 1
+  (permissive, auto-usable) or Tier 2 (restricted, opt-in-gated) --
+  including the runtime guard that raises `RestrictedLicenseNotAcceptedError`
+  for a Tier 2 checkpoint unless the caller explicitly passes
+  `accept_restricted_licenses=True`.
+
+This is a **policy and mechanism**, not a populated list. Every `Allowlist`
+starts empty; populating and maintaining the actual per-module allowlists
+(which specific model checkpoints go in Tier 1 vs Tier 2) is called out in
+the architecture doc (Part 6) as an ongoing, per-module maintenance task,
+not something `lazycore` does on a module's behalf.
+
+### `lazycore.sandbox` -- shared sandbox executor + adapter base class (§2.3, §2.3.1)
+
+LazyRed and LazyAgent contain the same kernel-level threat class --
+arbitrary code execution by a red-team target or a benchmarked agent -- so
+per §2.3, LazyCore provides **one** shared sandbox executor and **one**
+generic policy dataclass, with mode-specific policy *values* layered on
+top by each module when it's built (LazyRed's "red-team target sandbox",
+LazyAgent's "benchmark task sandbox"). Nothing module-specific (e.g. an
+OWASP mapping, a benchmark-task allowlist) lives in this package -- only
+the generic shape both modes share.
+
+- `SandboxPolicy` -- generic, frozen dataclass config: `allow_network`,
+  `allowed_read_paths`, `allowed_write_paths`, `allowed_executables`,
+  plus env/timeout/cwd knobs. The exact same dataclass is meant to be
+  instantiated with different values for LazyRed vs. LazyAgent.
+- `BaseSandboxExecutor` -- the shared ABC (`is_available`, `run_command`,
+  `run_callable`, returning a structured `SandboxResult`).
+- `SeatbeltSandboxExecutor` -- the real, tested macOS backend. Generates an
+  SBPL (Sandbox Profile Language) profile from a `SandboxPolicy` and runs
+  the target command under `/usr/bin/sandbox-exec -f <profile> -- ...`.
+- `LinuxNamespaceSandboxExecutor` -- a **documented stub**, not a real
+  implementation. It satisfies the same ABC and reports availability via
+  `shutil.which("bwrap"/"unshare")`, but every actual run method raises
+  `SandboxBackendUnavailableError`. This repository's reference/dev
+  environment is macOS, so a real gVisor/Firecracker/namespace-based
+  backend (the intended Linux implementation per §2.3, since Linux has no
+  VM-boundary GPU problem to design around) cannot be meaningfully built or
+  verified here. Do not treat this stub as production-ready.
+- `get_default_executor()` -- returns `SeatbeltSandboxExecutor` on macOS
+  (when `/usr/bin/sandbox-exec` exists) or `LinuxNamespaceSandboxExecutor`
+  on Linux; raises `SandboxBackendUnavailableError` on anything else.
+
+**Why GPU/Metal/MPS access is never sandboxed here, on either platform**
+(§2.3.1): 2026 research confirmed no Mac container/VM runtime (Docker
+Desktop, Podman+libkrun, Apple's `container`/Containerization framework)
+exposes Metal/MPS passthrough into an isolation boundary, and -- more
+fundamentally -- Seatbelt itself **cannot** gate GPU/Metal/Cocoa access
+even in principle, because those are system-level services outside SBPL's
+reach. The locked v1 design is a **split-trust architecture**: GPU-bound
+model inference always runs unsandboxed (there's no adversarial surface in
+local weights/forward-pass compute), and only the CPU-bound tool-calling/
+code-execution layer -- shell commands, file I/O, network egress, the
+actual adversarial surface in both LazyRed's and LazyAgent's threat models
+-- is what this package ever constrains. `SeatbeltSandboxExecutor` does not
+implement, and will never implement, any GPU-blocking rule; see its module
+docstring for the exact technical reasoning.
+
+Runtime dependencies added by this subpackage: **none** -- it uses only
+`subprocess`, `shutil`, `tempfile`, `pickle`, `platform`, `dataclasses`,
+and `abc` from the standard library.
+
+## What's deliberately NOT in here
+
+- A *real* Linux sandbox backend -- `LinuxNamespaceSandboxExecutor` is a
+  documented stub only; see `lazycore.sandbox` above.
+- Any LLM router or `BaseTarget`/multi-provider abstraction (§2.8) --
+  explicitly and permanently excluded platform-wide.
+- Formal inter-module data contracts / MLflow "flavors"-style manifests
+  (§2.9) -- deferred until two real modules need to exchange data.
+- pandas, polars, torch, or any ML framework as a hard dependency.
+
+## Installation
+
+```bash
+cd packages/lazycore
+pip install -e .          # runtime only
+pip install -e ".[dev]"   # + pytest for running the test suite
+```
+
+## Running tests
+
+```bash
+pytest packages/lazycore/tests
+```
+
+The Tier 1 data-helper tests additionally require `pandas` and `polars` to
+be installed in the test environment (they are not runtime dependencies of
+`lazycore` itself, so those tests are skipped via `pytest.importorskip` if
+unavailable).
+
+`tests/sandbox/test_seatbelt.py` actually invokes `/usr/bin/sandbox-exec`
+against real temp directories to demonstrate enforcement (an allowed write
+succeeds, a write outside the policy is denied, network egress is denied
+by default) -- it is skipped entirely on non-macOS hosts via
+`pytest.mark.skipif`, rather than mocked. `tests/sandbox/test_linux_stub.py`
+only verifies the documented-stub behavior of `LinuxNamespaceSandboxExecutor`
+on this non-Linux machine (it raises `SandboxBackendUnavailableError`); it
+cannot and does not validate real Linux namespace isolation.

benchcraft_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+lazycore/__init__.py,sha256=VbVQ5MhyG4Cq7uHFM4AArUlSSIvi4GkPvEQj6FO8_bI,2475
+lazycore/data.py,sha256=6HqEV_ekFK4awAeEw5kF-OOt2Mph0vVRK2tP0vgO_8A,11544
+lazycore/licensing.py,sha256=pNbpEQzUhIoFog3qexKd8a3DlQov9g2kKQVQ2KlFWpY,11804
+lazycore/telemetry.py,sha256=FpM50x6gFXU7UZ4QJg3_B9H8N7MI3-D0vp2GZCdCjlA,13669
+lazycore/sandbox/__init__.py,sha256=9ICIpsVD37Gk3RW9CYGpY7qiIzJVYgVCMh_Cfst42cs,3794
+lazycore/sandbox/base.py,sha256=hKVv347wBrDnP04XDfrF5pF9Vf_wziwDHn2VEgG593w,17948
+lazycore/sandbox/linux_stub.py,sha256=MisAM7U9OHnhsmpvdfZeriKx3_bEtyzzm9xgwsvsAc0,6735
+lazycore/sandbox/seatbelt.py,sha256=-a51U72lUgHGlhLdvHGzWgsH7qVBXKp0n2JzsO7J9yc,66482
+benchcraft_core-0.1.0.dist-info/METADATA,sha256=fv5mK8e-kWEEMLZdMWplQlQ1f3jaBUUFDyOV0tFgZKo,10923
+benchcraft_core-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+benchcraft_core-0.1.0.dist-info/RECORD,,

benchcraft_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lazycore/__init__.py

@@ -0,0 +1,100 @@
+"""lazycore: the thin, shared substrate underneath every Benchcraft module.
+
+See the package README for scope and the "why thin" rationale. This module
+re-exports the small public surface of ``lazycore.data``,
+``lazycore.telemetry``, ``lazycore.licensing``, and ``lazycore.sandbox`` so
+most consumers only need ``import lazycore``.
+"""
+
+from lazycore.data import (
+    ArrowBackedFrame,
+    DenseMediaPipeline,
+    SparseFormat,
+    SparseGraphTensorAdapter,
+    from_polars_zero_copy,
+    is_arrow_backed_pandas,
+    pandas_arrow_dtypes,
+    to_polars_zero_copy,
+)
+from lazycore.licensing import (
+    Allowlist,
+    Mitigation,
+    ModelLicenseEntry,
+    ModelTier,
+    RestrictedLicenseNotAcceptedError,
+    RISK_MITIGATIONS,
+    RiskType,
+)
+from lazycore.sandbox import (
+    BaseSandboxExecutor,
+    LinuxNamespaceSandboxExecutor,
+    SandboxBackendUnavailableError,
+    SandboxError,
+    SandboxPolicy,
+    SandboxPolicyViolationError,
+    SandboxResult,
+    SeatbeltSandboxExecutor,
+    get_default_executor,
+)
+from lazycore.telemetry import (
+    ATTR_GENAI_EVENT_CONTENT,
+    ATTR_GENAI_EVENT_ROLE,
+    ATTR_ML_METRIC_ACCURACY,
+    ATTR_ML_METRIC_PREFIX,
+    ATTR_OWASP_MAPPING,
+    ATTR_SECURITY_SEVERITY,
+    SecuritySeverity,
+    add_transcript_event,
+    genai_span,
+    get_tracer,
+    ml_metric_attribute,
+    set_ml_metric,
+    set_security_finding,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # data.py
+    "ArrowBackedFrame",
+    "DenseMediaPipeline",
+    "SparseFormat",
+    "SparseGraphTensorAdapter",
+    "from_polars_zero_copy",
+    "is_arrow_backed_pandas",
+    "pandas_arrow_dtypes",
+    "to_polars_zero_copy",
+    # licensing.py
+    "Allowlist",
+    "Mitigation",
+    "ModelLicenseEntry",
+    "ModelTier",
+    "RestrictedLicenseNotAcceptedError",
+    "RISK_MITIGATIONS",
+    "RiskType",
+    # sandbox/__init__.py
+    "BaseSandboxExecutor",
+    "LinuxNamespaceSandboxExecutor",
+    "SandboxBackendUnavailableError",
+    "SandboxError",
+    "SandboxPolicy",
+    "SandboxPolicyViolationError",
+    "SandboxResult",
+    "SeatbeltSandboxExecutor",
+    "get_default_executor",
+    # telemetry.py
+    "ATTR_GENAI_EVENT_CONTENT",
+    "ATTR_GENAI_EVENT_ROLE",
+    "ATTR_ML_METRIC_ACCURACY",
+    "ATTR_ML_METRIC_PREFIX",
+    "ATTR_OWASP_MAPPING",
+    "ATTR_SECURITY_SEVERITY",
+    "SecuritySeverity",
+    "add_transcript_event",
+    "genai_span",
+    "get_tracer",
+    "ml_metric_attribute",
+    "set_ml_metric",
+    "set_security_finding",
+]

lazycore/data.py

@@ -0,0 +1,285 @@
+"""Shared three-tier data/tensor conventions (architecture doc §2.1).
+
+LazyCore does not ship a data-processing library. It documents and lightly
+implements the three-tier convention that every Benchcraft module agrees to
+follow so that modules sharing "the same underlying data" don't each invent
+their own representation:
+
+Tier 1 - Dense tabular / text / time-series
+    Canonical format: Apache Arrow, fronted by pandas 2.x ``ArrowDtype``
+    columns and/or Polars DataFrames. pandas 2.x and Polars are both
+    zero-copy front-ends over the same Arrow buffers, so this tier is a set
+    of small conversion/validation helpers, not a wrapping library. Neither
+    pandas nor polars is a hard dependency of ``lazycore`` -- consumers
+    import them themselves, and these helpers import them lazily so that a
+    PyTorch-free or otherwise minimal module never pays for that import
+    unless it actually calls into this tier.
+
+Tier 2 - Sparse graph tensors
+    DLPack's spec is explicitly limited to dense/strided arrays and cannot
+    represent sparsity, so there is no zero-copy shortcut here -- a real
+    adapter is required. LazyCore only defines the *shape* of that adapter
+    (an abstract interface for COO / CSR-CSC exchange) via
+    :class:`SparseGraphTensorAdapter`. Concrete implementations bridging
+    PyTorch Geometric's native COO and DGL's native CSR/CSC formats belong
+    in LazyGraph, not here -- lazycore never depends on torch, PyG, or DGL.
+
+Tier 3 - Dense image / audio
+    FFCV-style workloads are bottlenecked by decode+augmentation *compute*,
+    not by data-copy/serialization overhead, so the shared convention is a
+    pipeline shape (decode -> augment -> DLPack handoff only at the final
+    dense-tensor stage), defined here as :class:`DenseMediaPipeline`.
+    Concrete decode/augment implementations belong in LazyVision.
+
+Nothing in this module imports pandas, polars, torch, or any other heavy
+runtime dependency at module import time. Where such libraries are needed
+for type-checking only, imports are guarded behind ``TYPE_CHECKING``.
+"""
+
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING, Any, Iterable, Protocol, runtime_checkable
+
+if TYPE_CHECKING:  # pragma: no cover - type-checking-only imports
+    import pandas as pd
+    import polars as pl
+
+__all__ = [
+    "ArrowBackedFrame",
+    "is_arrow_backed_pandas",
+    "pandas_arrow_dtypes",
+    "to_polars_zero_copy",
+    "from_polars_zero_copy",
+    "SparseGraphTensorAdapter",
+    "SparseFormat",
+    "DenseMediaPipeline",
+]
+
+
+# ---------------------------------------------------------------------------
+# Tier 1: Arrow-backed dense tabular / text / time-series helpers
+# ---------------------------------------------------------------------------
+
+#: Duck-typed alias for "something Arrow-shaped": a pandas DataFrame backed
+#: by ArrowDtype columns, or a Polars DataFrame. Not a runtime-enforced type
+#: (that would require importing pandas/polars eagerly); it exists purely
+#: for readability in module type hints via ``TYPE_CHECKING``.
+if TYPE_CHECKING:  # pragma: no cover
+    ArrowBackedFrame = "pd.DataFrame | pl.DataFrame"
+else:
+    ArrowBackedFrame = Any
+
+
+def _require_pandas() -> "pd":  # pragma: no cover - trivial import guard
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "This lazycore.data helper requires pandas to be installed in "
+            "the calling module's environment. lazycore itself does not "
+            "depend on pandas."
+        ) from exc
+    return pd
+
+
+def _require_polars() -> "pl":  # pragma: no cover - trivial import guard
+    try:
+        import polars as pl
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "This lazycore.data helper requires polars to be installed in "
+            "the calling module's environment. lazycore itself does not "
+            "depend on polars."
+        ) from exc
+    return pl
+
+
+def pandas_arrow_dtypes(frame: "pd.DataFrame") -> dict[str, str]:
+    """Return the subset of ``frame``'s columns backed by ``ArrowDtype``.
+
+    Maps column name -> the string form of its pyarrow type. Useful for a
+    module to quickly check which columns are already on the Tier-1
+    zero-copy path versus which are still plain numpy-backed pandas columns
+    that would force a conversion.
+    """
+    pd = _require_pandas()
+    result: dict[str, str] = {}
+    for name, dtype in frame.dtypes.items():
+        if isinstance(dtype, pd.ArrowDtype):
+            result[str(name)] = str(dtype.pyarrow_dtype)
+    return result
+
+
+def is_arrow_backed_pandas(frame: "pd.DataFrame") -> bool:
+    """True if every column in ``frame`` uses a pandas 2.x ``ArrowDtype``.
+
+    An empty DataFrame (no columns) is considered trivially Arrow-backed.
+    """
+    pd = _require_pandas()
+    dtypes = list(frame.dtypes)
+    if not dtypes:
+        return True
+    return all(isinstance(dtype, pd.ArrowDtype) for dtype in dtypes)
+
+
+def to_polars_zero_copy(frame: "pd.DataFrame") -> "pl.DataFrame":
+    """Convert an Arrow-backed pandas DataFrame to Polars.
+
+    Per §2.1, pandas 2.x (``ArrowDtype``) and Polars are interchangeable
+    front-ends over the same Arrow buffers, so this conversion is
+    near-zero-cost when ``frame`` is already Arrow-backed. If it is not,
+    this still works correctly but pandas/polars will do the necessary
+    materialization themselves -- this helper does not silently hide that
+    cost, it just delegates to ``pl.from_pandas`` either way.
+    """
+    pl = _require_polars()
+    return pl.from_pandas(frame)
+
+
+def from_polars_zero_copy(frame: "pl.DataFrame") -> "pd.DataFrame":
+    """Convert a Polars DataFrame to an Arrow-backed pandas DataFrame.
+
+    Uses pandas 2.x's ``dtype_backend="pyarrow"`` so the resulting frame
+    stays on the Tier-1 Arrow representation rather than falling back to
+    numpy-backed columns.
+    """
+    _require_pandas()  # ensure a clear error if pandas is missing at all
+    return frame.to_pandas(use_pyarrow_extension_array=True)
+
+
+# ---------------------------------------------------------------------------
+# Tier 2: Sparse graph tensor adapter (interface only)
+# ---------------------------------------------------------------------------
+
+
+class SparseFormat:
+    """Sparse tensor storage format names used across the Tier-2 adapter.
+
+    These correspond to the "COO / CSR-CSC / SciPy sparse bridge" family
+    named in §2.1 (modeled on NVIDIA's "Universal Sparse Tensor" concept).
+    """
+
+    COO = "coo"
+    CSR = "csr"
+    CSC = "csc"
+
+
+class SparseGraphTensorAdapter(abc.ABC):
+    """Abstract interface for a Tier-2 sparse graph tensor adapter.
+
+    DLPack cannot represent sparsity, so there is no zero-copy shortcut for
+    graph tensors -- a real conversion step between sparse formats (COO,
+    CSR/CSC) is unavoidable. LazyCore defines only the *shape* of that
+    conversion boundary here; it does not implement it and does not depend
+    on any graph library (PyTorch Geometric, DGL, SciPy, etc.). LazyGraph
+    is expected to provide concrete subclasses that actually bridge PyG's
+    native COO representation and DGL's native CSR/CSC representation.
+
+    Implementations should treat every method below as doing real work
+    (not just re-labelling metadata) since a genuine conversion step is
+    happening.
+    """
+
+    @property
+    @abc.abstractmethod
+    def native_format(self) -> str:
+        """The sparse format (one of :class:`SparseFormat`) this adapter
+        instance currently holds its data in."""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def shape(self) -> tuple[int, int]:
+        """The dense (rows, cols) shape represented by this sparse tensor."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def to_coo(self) -> "SparseGraphTensorAdapter":
+        """Return an adapter view/copy in COO format (PyG-native)."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def to_csr(self) -> "SparseGraphTensorAdapter":
+        """Return an adapter view/copy in CSR format (DGL-native for many
+        aggregation ops)."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def to_csc(self) -> "SparseGraphTensorAdapter":
+        """Return an adapter view/copy in CSC format."""
+        raise NotImplementedError
+
+
+# ---------------------------------------------------------------------------
+# Tier 3: Dense image / audio pipeline (interface only)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class _SupportsDLPack(Protocol):
+    """Structural type for "something that can hand off via DLPack" --
+    i.e. exposes ``__dlpack__``/``__dlpack_device__`` per the DLPack
+    protocol, without lazycore needing to depend on torch/numpy to say so.
+    """
+
+    def __dlpack__(self, stream: Any | None = ...) -> Any:
+        """Export this tensor via the DLPack protocol for zero-copy handoff."""
+        ...  # pragma: no cover
+
+    def __dlpack_device__(self) -> tuple[int, int]:
+        """Return the ``(device_type, device_id)`` pair per the DLPack spec."""
+        ...  # pragma: no cover
+
+
+class DenseMediaPipeline(abc.ABC):
+    """Abstract interface for a Tier-3 FFCV-style decode+augment pipeline.
+
+    Image/audio workloads are bottlenecked by decode+augmentation
+    *compute*, not by data-copy/serialization overhead (this is why FFCV
+    outperforms both the PyTorch DataLoader and NVIDIA DALI). The shared
+    convention is therefore about pipeline *shape*, not about a shared
+    zero-copy buffer: decode and augment happen natively (however the
+    concrete implementation wants), and only the final, already-dense
+    tensor is handed off via DLPack.
+
+    LazyCore does not implement decode/augment logic and does not depend on
+    any image/audio/tensor library. LazyVision is expected to provide
+    concrete subclasses.
+    """
+
+    @abc.abstractmethod
+    def decode(self, raw: bytes) -> Any:
+        """Decode a raw media payload (e.g. JPEG/PNG/WAV bytes) into an
+        intermediate in-memory representation. Not required to be a dense
+        tensor yet -- this stage is decode-compute-bound, and
+        implementations are free to use whatever intermediate
+        representation is fastest for their decoder."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def augment(self, decoded: Any) -> Any:
+        """Apply augmentation to a decoded sample. Still not required to be
+        a DLPack-compatible dense tensor -- augmentation is also
+        compute-bound, not copy-bound."""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def to_dense_tensor(self, augmented: Any) -> _SupportsDLPack:
+        """Produce the final dense tensor for this sample. The return value
+        must support the DLPack protocol (``__dlpack__`` /
+        ``__dlpack_device__``) -- this is the one and only point in the
+        Tier-3 pipeline where a zero-copy handoff (e.g. to PyTorch) is
+        expected to occur."""
+        raise NotImplementedError
+
+    def run(self, raw: bytes) -> _SupportsDLPack:
+        """Convenience driver: decode -> augment -> to_dense_tensor.
+
+        Concrete pipelines may override this if they need to fuse stages
+        for performance, but the default composition documents the
+        expected shape of the pipeline.
+        """
+        decoded = self.decode(raw)
+        augmented = self.augment(decoded)
+        return self.to_dense_tensor(augmented)