fix: address gold-standard review findings

Critical:
- Remove rich from requirements.txt (now optional in pyproject.toml)
- Fix stale tiers=DEFAULT_TIERS warning messages referencing removed param
- Complete @xenova/transformers → @huggingface/transformers migration
  across all TS packages, docs, examples, and CI config
- Revert workspace:* → workspace:^ (preserves semver on publish)

Security:
- Use hmac.compare_digest for constant-time auth token comparison
- Guard record() with _lock for thread-safe counter reads

Quality:
- Preserve _LazyModule.__name__ alias after dict merge
- Add __bool__=False to _MissingIntegration for truthiness compat
- Fix CHANGELOG import time to match actual measurement (~20ms)
- Fix import ordering (ruff I001)

Author: saschabuehrle

.github/models.yml

@@ -47,7 +47,7 @@ ml_models:
 
     installation:
       python: "pip install fastembed"
-      typescript: "npm install @xenova/transformers"
+      typescript: "npm install @huggingface/transformers"
 
 # Heuristic Models (No ML Required)
 heuristic_models:

CHANGELOG.md

@@ -33,7 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **Lazy imports** — `import cascadeflow` no longer eagerly loads all providers, numpy, or heavyweight submodules. Import time reduced from ~1900ms to <200ms.
+- **Lazy imports** — `import cascadeflow` no longer eagerly loads all providers, numpy, or heavyweight submodules. Import time reduced from ~1900ms to ~20ms via PEP 562 lazy loading.
 - **`__all__` reduced** — From 127 to ~20 essential public symbols. Non-essential exports remain accessible but are not star-exported.
 - **`rich` moved to optional** — No longer a core dependency; falls back to stdlib logging when not installed. Install with `pip install cascadeflow[rich]`.
 - **Integration import errors** — Failed optional integration imports now return proxy objects that raise `ImportError` with install hints on use, instead of silently returning `None`.

README.md

@@ -289,7 +289,7 @@ For advanced quality validation, enable ML-based semantic similarity checking to
 **Step 1:** Install the optional ML packages:
 
 ```bash
-npm install @cascadeflow/ml @xenova/transformers
+npm install @cascadeflow/ml @huggingface/transformers
 ```
 
 **Step 2:** Enable semantic validation in your cascade:

cascadeflow/__init__.py

@@ -46,8 +46,10 @@ def _load(self):
         if not self.__loaded:
             import importlib
 
+            alias = self.__name__
             real = importlib.import_module(self.__real_name)
             self.__dict__.update(real.__dict__)
+            self.__name__ = alias  # preserve alias name after dict merge
             self.__loaded = True
 
     def __getattr__(self, name: str):

cascadeflow/agent.py

@@ -974,7 +974,7 @@ async def run(
             logger.warning(
                 f"user_tier='{user_tier}' specified but no tiers configured. "
                 f"Ignoring tier parameter. To use tiers, initialize agent with: "
-                f"CascadeAgent(models=[...], tiers=DEFAULT_TIERS)"
+                f"HarnessConfig with tier-based rules"
             )
 
         workflow_profile = None
@@ -1402,7 +1402,7 @@ async def run_streaming(
             logger.warning(
                 f"user_tier='{user_tier}' specified but no tiers configured. "
                 f"Ignoring tier parameter. To use tiers, initialize agent with: "
-                f"CascadeAgent(models=[...], tiers=DEFAULT_TIERS)"
+                f"HarnessConfig with tier-based rules"
             )
 
         workflow_profile = None
@@ -1681,7 +1681,7 @@ async def stream_events(
             logger.warning(
                 f"user_tier='{user_tier}' specified but no tiers configured. "
                 f"Ignoring tier parameter. To use tiers, initialize agent with: "
-                f"CascadeAgent(models=[...], tiers=DEFAULT_TIERS)"
+                f"HarnessConfig with tier-based rules"
             )
 
         workflow_profile = None

cascadeflow/harness/api.py

@@ -187,30 +187,31 @@ def record(
             _sanitize_trace_value(model, max_length=_MAX_MODEL_LEN) if model is not None else None
         )
 
-        self.last_action = safe_action
-        self.model_used = safe_model
-        entry: dict[str, Any] = {
-            "action": safe_action,
-            "reason": safe_reason,
-            "model": safe_model,
-            "run_id": self.run_id,
-            "mode": self.mode,
-            "step": self.step_count,
-            "timestamp_ms": time.time() * 1000,
-            "tool_calls_total": self.tool_calls,
-            "cost_total": self.cost,
-            "latency_used_ms": self.latency_used_ms,
-            "energy_used": self.energy_used,
-            "budget_state": {
-                "max": self.budget_max,
-                "remaining": self.budget_remaining,
-            },
-        }
-        if applied is not None:
-            entry["applied"] = applied
-        if decision_mode is not None:
-            entry["decision_mode"] = decision_mode
-        self._trace.append(entry)
+        with self._lock:
+            self.last_action = safe_action
+            self.model_used = safe_model
+            entry: dict[str, Any] = {
+                "action": safe_action,
+                "reason": safe_reason,
+                "model": safe_model,
+                "run_id": self.run_id,
+                "mode": self.mode,
+                "step": self.step_count,
+                "timestamp_ms": time.time() * 1000,
+                "tool_calls_total": self.tool_calls,
+                "cost_total": self.cost,
+                "latency_used_ms": self.latency_used_ms,
+                "energy_used": self.energy_used,
+                "budget_state": {
+                    "max": self.budget_max,
+                    "remaining": self.budget_remaining,
+                },
+            }
+            if applied is not None:
+                entry["applied"] = applied
+            if decision_mode is not None:
+                entry["decision_mode"] = decision_mode
+            self._trace.append(entry)
         _emit_harness_decision(entry)
 
 

cascadeflow/integrations/__init__.py

@@ -39,6 +39,9 @@ def __call__(self, *args, **kwargs):
     def __getattr__(self, name: str):
         self._fail()
 
+    def __bool__(self):
+        return False
+
     def __repr__(self):
         return f"<MissingIntegration {self._name!r}>"
 

cascadeflow/proxy/server.py

@@ -24,6 +24,7 @@
 
 import asyncio
 import hashlib
+import hmac
 import inspect
 import json
 import os
@@ -619,7 +620,8 @@ def _check_auth(self, proxy: RoutingProxy) -> bool:
         if not token:
             return True
         auth = self.headers.get("Authorization", "")
-        if auth == f"Bearer {token}":
+        expected = f"Bearer {token}"
+        if hmac.compare_digest(auth, expected):
             return True
         self.send_response(401)
         self.send_header("Content-Type", "application/json")

cascadeflow/routing/tier_routing.py

@@ -2,16 +2,12 @@
 Tier-aware routing for user tier management.
 
 This module provides tier-based model filtering and budget enforcement.
-It's OPTIONAL - only activated when users provide 'tiers' parameter.
+It's OPTIONAL - only activated when tier rules are configured via HarnessConfig.
 
 Usage:
     >>> from cascadeflow import CascadeAgent
-    >>> from cascadeflow.schema.config import DEFAULT_TIERS
     >>>
-    >>> # OPTIONAL: Enable tier routing
-    >>> agent = CascadeAgent(models=[...], tiers=DEFAULT_TIERS)
-    >>>
-    >>> # Use tier-aware routing
+    >>> # Use tier-aware routing via HarnessConfig
     >>> result = await agent.run("query", user_tier="free")
     >>>
     >>> # Or ignore tiers - works without them

docs/guides/custom_validation.md

@@ -904,7 +904,7 @@ if (await checker.isAvailable()) {
 
 **Installation:**
 ```bash
-npm install @cascadeflow/ml @xenova/transformers
+npm install @cascadeflow/ml @huggingface/transformers
 ```
 
 ---