Add enums for encode objectives/metrics/segments

Introduce typed enums for encoding metadata and wire-safe coercion: EncodeObjective, EncodeMetric, EncodingSegmentKind, EncodingBoundType, and WorkloadSuitability. Update core and vector models to use these enums (with coercion helpers), change codec implementations and helper modules to use the enums instead of raw strings, and ensure segment_kind/guarantee fields serialize as enum values. Export the new symbols from package __init__ and update examples and tests to use the enums. Also bump package version to 0.2.0, adjust a few robustness issues (mlx import lint fix, pyproject cleanup), and harden tests (git executable check, exclude venv paths when scanning for bytecode).

Author: Engin Mahmut

README.md

@@ -98,13 +98,18 @@ Stable today:
 - `CompressionFootprint`
 - `CompressionGuarantee`
 - `ValidationEvidence`
+- `EncodingBoundType`
+- `WorkloadSuitability`
 - `VectorEncodeRequest`
 - `VectorEncodingSegment`
 - `VectorEncoding`
 - `VectorDecodeRequest`
 - `VectorDecodeResult`
 - `VectorCodec`
 - `PassthroughVectorCodec`
+- `EncodeObjective`
+- `EncodeMetric`
+- `EncodingSegmentKind`
 
 Available today, but intentionally outside the stable root surface:
 - `semafold.turboquant`
@@ -139,14 +144,15 @@ Run the exact file here: [examples/wire_roundtrip.py](examples/wire_roundtrip.py
 ```python
 import numpy as np
 
+from semafold import EncodeObjective
 from semafold import PassthroughVectorCodec
 from semafold import VectorDecodeRequest
 from semafold import VectorEncodeRequest
 
 codec = PassthroughVectorCodec()
 request = VectorEncodeRequest(
     data=np.linspace(-1.0, 1.0, 1024, dtype=np.float32),
-    objective="reconstruction",
+    objective=EncodeObjective.RECONSTRUCTION,
 )
 
 encoding = codec.encode(request)
@@ -162,6 +168,8 @@ Run the exact file here: [examples/turboquant_embedding.py](examples/turboquant_
 ```python
 import numpy as np
 
+from semafold import EncodeMetric
+from semafold import EncodeObjective
 from semafold import VectorDecodeRequest
 from semafold import VectorEncodeRequest
 from semafold.turboquant import TurboQuantMSEConfig
@@ -175,8 +183,8 @@ codec = TurboQuantMSEVectorCodec(
 encoding = codec.encode(
     VectorEncodeRequest(
         data=rows,
-        objective="reconstruction",
-        metric="mse",
+        objective=EncodeObjective.RECONSTRUCTION,
+        metric=EncodeMetric.MSE,
         role="embedding",
         seed=11,
     )

STABILITY.md

@@ -12,13 +12,18 @@ Stable surface:
 - `CompressionFootprint`
 - `CompressionGuarantee`
 - `ValidationEvidence`
+- `EncodingBoundType`
+- `WorkloadSuitability`
 - `VectorEncodeRequest`
 - `VectorEncodingSegment`
 - `VectorEncoding`
 - `VectorDecodeRequest`
 - `VectorDecodeResult`
 - `VectorCodec`
 - `PassthroughVectorCodec`
+- `EncodeObjective`
+- `EncodeMetric`
+- `EncodingSegmentKind`
 
 ## Intentionally Not Stable
 

benchmarks/turboquant_paper_validation.py

@@ -10,6 +10,7 @@
 
 from semafold import __version__
 from semafold import VectorDecodeRequest, VectorEncodeRequest
+from semafold.vector.models import EncodeObjective, EncodeMetric
 from semafold.turboquant import (
     TurboQuantMSEConfig,
     TurboQuantMSEVectorCodec,
@@ -44,7 +45,7 @@ def _mse_record(*, rows: np.ndarray, bits_per_scalar: int, rotation_seed: int) -
             default_rotation_seed=rotation_seed,
         )
     )
-    request = VectorEncodeRequest(data=rows, objective="reconstruction", metric="mse")
+    request = VectorEncodeRequest(data=rows, objective=EncodeObjective.RECONSTRUCTION, metric=EncodeMetric.MSE)
 
     encode_start = time.perf_counter()
     encoding = codec.encode(request)
@@ -87,8 +88,8 @@ def _prod_record(
     )
     request = VectorEncodeRequest(
         data=rows,
-        objective="inner_product_estimation",
-        metric="dot_product_error",
+        objective=EncodeObjective.INNER_PRODUCT_ESTIMATION,
+        metric=EncodeMetric.DOT_PRODUCT_ERROR,
     )
 
     encode_start = time.perf_counter()

benchmarks/turboquant_synthetic_kv_benchmark.py

@@ -10,6 +10,7 @@
 
 from semafold import __version__
 from semafold import VectorDecodeRequest, VectorEncodeRequest
+from semafold.vector.models import EncodeObjective, EncodeMetric
 from semafold.turboquant import (
     TurboQuantMSEConfig,
     TurboQuantMSEVectorCodec,
@@ -101,8 +102,8 @@ def run_synthetic_kv_benchmark(
     )
     key_request = VectorEncodeRequest(
         data=key_rows,
-        objective="inner_product_estimation",
-        metric="dot_product_error",
+        objective=EncodeObjective.INNER_PRODUCT_ESTIMATION,
+        metric=EncodeMetric.DOT_PRODUCT_ERROR,
         role="key_cache",
     )
     key_encode_start = time.perf_counter()
@@ -124,8 +125,8 @@ def run_synthetic_kv_benchmark(
     )
     value_request = VectorEncodeRequest(
         data=value_rows,
-        objective="reconstruction",
-        metric="mse",
+        objective=EncodeObjective.RECONSTRUCTION,
+        metric=EncodeMetric.MSE,
         role="value_cache",
     )
     value_encode_start = time.perf_counter()

examples/turboquant_embedding.py

@@ -9,6 +9,7 @@
 from semafold.turboquant import TurboQuantMSEConfig
 from semafold.turboquant import TurboQuantMSEVectorCodec
 from semafold.turboquant.backends import get_backend
+from semafold.vector.models import EncodeObjective, EncodeMetric
 
 
 def _row_cosine_similarity(lhs: np.ndarray, rhs: np.ndarray) -> float:
@@ -54,8 +55,8 @@ def main() -> None:
     encoding = codec.encode(
         VectorEncodeRequest(
             data=rows,
-            objective="reconstruction",
-            metric="mse",
+            objective=EncodeObjective.RECONSTRUCTION,
+            metric=EncodeMetric.MSE,
             role="embedding",
             seed=11,
         )

examples/wire_roundtrip.py

@@ -8,6 +8,7 @@
 from semafold import VectorDecodeRequest
 from semafold import VectorEncodeRequest
 from semafold import VectorEncoding
+from semafold.vector.models import EncodeObjective
 
 
 def _format_bytes(value: int) -> str:
@@ -33,7 +34,7 @@ def main() -> None:
     codec = PassthroughVectorCodec()
     request = VectorEncodeRequest(
         data=np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], dtype=np.float32),
-        objective="reconstruction",
+        objective=EncodeObjective.RECONSTRUCTION,
         role="embedding",
         profile_id="examples.wire_roundtrip",
     )

pyproject.toml

@@ -42,7 +42,4 @@ include = ["src", "tests", "examples", "benchmarks"]
 typeCheckingMode = "basic"
 venvPath = "."
 venv = ".venv"
-# Optional backends (torch, mlx) are not installed in the base dev environment.
-# reportMissingImports is silenced so pyright does not error on those packages;
-# structural type errors in those files are still caught.
-reportMissingImports = "none"
+

src/semafold/__init__.py

@@ -8,6 +8,7 @@
     CompressionGuarantee,
     ValidationEvidence,
 )
+from semafold.core.models import EncodingBoundType, WorkloadSuitability
 from semafold.vector import (
     PassthroughVectorCodec,
     VectorCodec,
@@ -17,13 +18,18 @@
     VectorEncoding,
     VectorEncodingSegment,
 )
+from semafold.vector.models import EncodeMetric, EncodeObjective, EncodingSegmentKind
 
 __all__ = [
     "__version__",
     "CompressionBudget",
     "CompressionEstimate",
     "CompressionFootprint",
     "CompressionGuarantee",
+    "EncodeMetric",
+    "EncodeObjective",
+    "EncodingBoundType",
+    "EncodingSegmentKind",
     "PassthroughVectorCodec",
     "ValidationEvidence",
     "VectorCodec",
@@ -32,4 +38,5 @@
     "VectorEncodeRequest",
     "VectorEncoding",
     "VectorEncodingSegment",
+    "WorkloadSuitability",
 ]

src/semafold/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/semafold/core/__init__.py

@@ -4,12 +4,14 @@
 
 from .accounting import CompressionEstimate, CompressionFootprint
 from .evidence import ValidationEvidence
-from .models import CompressionBudget, CompressionGuarantee
+from .models import CompressionBudget, CompressionGuarantee, EncodingBoundType, WorkloadSuitability
 
 __all__ = [
     "CompressionBudget",
     "CompressionEstimate",
     "CompressionFootprint",
     "CompressionGuarantee",
+    "EncodingBoundType",
     "ValidationEvidence",
+    "WorkloadSuitability",
 ]