feat: fix 4 broken doc samples, add middleware param, CallbackObservability, custom policy example

Code fixes (verified by audit):
- Add `middleware` parameter to `create()` in Python and TypeScript
- Create `CallbackObservability` CDK class (was referenced in FAQ but missing)
- Add `router` getter on TS ModelMesh, `setMiddleware()` on TS Router

Doc fixes:
- FAQ Q8: Fix `explain()` call (add required `model` arg, fix snake_case key)
- FAQ Q10: Add custom rotation policy example with `select()` override
- FAQ Q10: Add YAML registration pattern for custom policies

All 1,879 tests pass (1,166 Python + 713 TypeScript).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: apartsin

docs/guides/FAQ.md

@@ -310,9 +310,9 @@ expect(client.calls.length).toBe(1);
 Debug routing decisions without making API calls:
 
 ```python
-explanation = client.explain()
-print(explanation["selectedModel"])   # Which model would be selected
-print(explanation["reason"])          # Why
+explanation = client.explain(model="chat-completion")
+print(explanation["selected_model"])   # Which model would be selected
+print(explanation["reason"])           # Why
 ```
 
 See the [Mock Client and Testing](Testing.md) guide.
@@ -459,6 +459,49 @@ provider = CorpLLMProvider(BaseProviderConfig(
 
 Override only what differs: `_get_completion_endpoint()` for the URL path, `_build_headers()` for authentication, `_build_request_payload()` to translate the request format, and `_parse_response()` to translate the response back. For streaming, also override `_parse_sse_chunk()`.
 
+**Custom rotation policy:**
+
+Inherit from `BaseRotationPolicy` and override `select()` to control how models are chosen, `should_deactivate()` to control when a model is taken offline, or `should_recover()` to control when it comes back.
+
+```python
+from modelmesh.cdk import BaseRotationPolicy, BaseRotationConfig
+from modelmesh.interfaces.rotation import ModelState
+from modelmesh.interfaces.provider import CompletionRequest
+from typing import Optional
+
+class CostAwarePolicy(BaseRotationPolicy):
+    """Pick the cheapest model that hasn't exceeded its error threshold."""
+
+    def select(
+        self,
+        candidates: list[ModelState],
+        request: CompletionRequest,
+    ) -> Optional[ModelState]:
+        if not candidates:
+            return None
+        # Sort by cost (lowest first), break ties by error rate
+        return min(candidates, key=lambda c: (c.total_cost, c.error_rate))
+```
+
+Register the policy in YAML by pointing `strategy` at your custom class, or pass it programmatically:
+
+```yaml
+pools:
+  chat:
+    capability: generation.text-generation.chat-completion
+    strategy: my_app.policies.CostAwarePolicy
+```
+
+```python
+# Or register programmatically
+from modelmesh.cdk import ThresholdRotationPolicy, ThresholdRotationConfig
+
+policy = CostAwarePolicy(BaseRotationConfig(
+    failure_threshold=5,
+    cooldown_seconds=120,
+))
+```
+
 Six connector types are extensible this way: providers, rotation policies, secret stores, storage backends, observability sinks, and discovery connectors.
 
 See the [CDK](../ConnectorCatalogue.md) reference and [CDK Developer Guide](../cdk/DeveloperGuide.md).

src/python/modelmesh/__init__.py

@@ -78,6 +78,7 @@ def create(
     strategy: str = "stick-until-failure",
     api_keys: dict[str, str] | None = None,
     config: str | dict | MeshConfig | None = None,
+    middleware: list[Middleware] | None = None,
 ) -> MeshClient:
     """Create an OpenAI SDK-compatible client with ModelMesh routing.
 
@@ -109,6 +110,8 @@ def create(
         config: Full configuration -- YAML file path, dict, or
             ``MeshConfig`` object. When provided, auto-detection is
             skipped.
+        middleware: List of :class:`Middleware` instances to attach to the
+            router. Middleware runs before and after each provider call.
 
     Returns:
         ``MeshClient``: OpenAI SDK-compatible client with ModelMesh
@@ -158,7 +161,10 @@ def create(
                 f"{type(config).__name__}"
             )
         mesh.initialize(mesh_config)
-        return mesh.get_client()
+        client = mesh.get_client()
+        if middleware:
+            mesh._router._middleware = MiddlewareStack(middleware)
+        return client
 
     if not capabilities and pool is None:
         raise ValueError(
@@ -183,7 +189,10 @@ def create(
         strategy=strategy,
     )
     mesh.initialize(MeshConfig(raw=raw_config))
-    return mesh.get_client()
+    client = mesh.get_client()
+    if middleware:
+        mesh._router._middleware = MiddlewareStack(middleware)
+    return client
 
 
 # Well-known short names mapped to full capability tree paths.

src/python/modelmesh/cdk/__init__.py

@@ -60,6 +60,8 @@
 # -- Specialized classes -----------------------------------------------------
 
 from modelmesh.cdk.specialized import (
+    CallbackObservability,
+    CallbackObservabilityConfig,
     ConsoleObservability,
     ConsoleObservabilityConfig,
     FileObservability,
@@ -132,6 +134,8 @@
     "FileSecretStore",
     "KeyValueStorageConfig",
     "KeyValueStorage",
+    "CallbackObservabilityConfig",
+    "CallbackObservability",
     "ConsoleObservabilityConfig",
     "ConsoleObservability",
     "FileObservabilityConfig",

src/python/modelmesh/cdk/specialized/__init__.py

@@ -17,6 +17,10 @@
 """
 from __future__ import annotations
 
+from modelmesh.cdk.specialized.callback_observability import (
+    CallbackObservability,
+    CallbackObservabilityConfig,
+)
 from modelmesh.cdk.specialized.console_observability import (
     ConsoleObservability,
     ConsoleObservabilityConfig,
@@ -74,6 +78,8 @@
     "KeyValueStorageConfig",
     "KeyValueStorage",
     # Observability
+    "CallbackObservabilityConfig",
+    "CallbackObservability",
     "ConsoleObservabilityConfig",
     "ConsoleObservability",
     "FileObservabilityConfig",

src/python/modelmesh/cdk/specialized/callback_observability.py

@@ -0,0 +1,97 @@
+"""Callback-based observability sink.
+
+Routes events, logs, and traces to a user-supplied callback function,
+enabling integration with custom dashboards, message queues, or alerting
+systems without subclassing.
+
+Usage::
+
+    from modelmesh.cdk import CallbackObservability, CallbackObservabilityConfig
+
+    def on_event(event):
+        my_dashboard.send(event.event_type, event.model_id, event.timestamp)
+
+    obs = CallbackObservability(CallbackObservabilityConfig(
+        callback=on_event,
+    ))
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from modelmesh.cdk.base_observability import (
+    BaseObservability,
+    BaseObservabilityConfig,
+)
+from modelmesh.interfaces.observability import (
+    RequestLogEntry,
+    RoutingEvent,
+    Severity,
+    TraceEntry,
+)
+
+__all__ = [
+    "CallbackObservabilityConfig",
+    "CallbackObservability",
+]
+
+
+@dataclass
+class CallbackObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for CallbackObservability.
+
+    Attributes:
+        callback: Function called with each event, log entry, or trace.
+            Receives the original object (RoutingEvent, RequestLogEntry,
+            or TraceEntry), not a formatted string.
+    """
+
+    callback: Optional[Callable[[Any], None]] = None
+
+
+class CallbackObservability(BaseObservability):
+    """Observability sink that routes events to a user-supplied callback.
+
+    The callback receives the original event/log/trace object (not a
+    formatted string), enabling integration with custom dashboards,
+    message queues, or alerting systems.
+
+    Respects all BaseObservability filters (event_filter, min_severity,
+    redact_secrets) before invoking the callback.
+    """
+
+    def __init__(self, config: CallbackObservabilityConfig) -> None:
+        super().__init__(config)
+        self._callback_fn = config.callback
+
+    def emit(self, event: RoutingEvent) -> None:
+        """Emit a routing event to the callback.
+
+        Applies event_filter from config before invoking.
+        """
+        if self._config.event_filter:
+            if event.event_type.value not in self._config.event_filter:
+                return
+        if self._callback_fn:
+            self._callback_fn(event)
+
+    def log(self, entry: RequestLogEntry) -> None:
+        """Route a request/response log entry to the callback."""
+        if self._callback_fn:
+            self._callback_fn(entry)
+
+    def trace(self, entry: TraceEntry) -> None:
+        """Route a trace entry to the callback, filtering by min_severity."""
+        min_level = self._SEVERITY_ORDER.get(
+            Severity(self._config.min_severity), 1
+        )
+        entry_level = self._SEVERITY_ORDER.get(entry.severity, 0)
+        if entry_level < min_level:
+            return
+        if self._callback_fn:
+            self._callback_fn(entry)
+
+    def _write(self, line: str) -> None:
+        """No-op: output goes through callback, not formatted _write."""
+        pass

src/typescript/src/core/mesh.ts

@@ -51,6 +51,14 @@ export class ModelMesh {
   private _observability: ObservabilityConnector | null = null;
   private _initialized = false;
 
+  /** Access the underlying Router instance. */
+  get router(): Router {
+    if (!this._router) {
+      throw new Error('ModelMesh not initialized. Call initialize() first.');
+    }
+    return this._router;
+  }
+
   // -- Lifecycle -----------------------------------------------------------
 
   /**

src/typescript/src/core/router.ts

@@ -51,7 +51,7 @@ export class Router {
   private readonly _emitter: EventEmitter;
   private readonly _observability: ObservabilityConnector | null;
   private readonly _maxRetries: number;
-  private readonly _middleware: MiddlewareStack | null;
+  private _middleware: MiddlewareStack | null;
 
   constructor(
     pools: Record<string, CapabilityPool>,
@@ -71,6 +71,11 @@ export class Router {
     this._middleware = middleware ?? null;
   }
 
+  /** Replace the middleware stack. Called by create() when middleware is provided. */
+  setMiddleware(stack: MiddlewareStack): void {
+    this._middleware = stack;
+  }
+
   private _trace(
     severity: Severity | string,
     component: string,

src/typescript/src/index.ts

@@ -199,6 +199,8 @@ export interface CreateOptions {
   strategy?: string;
   apiKeys?: Record<string, string>;
   config?: string | Record<string, unknown> | MeshConfig;
+  /** Middleware instances to attach to the router. */
+  middleware?: Middleware[];
 }
 
 /**
@@ -247,6 +249,7 @@ export function create(...args: unknown[]): MeshClient {
     strategy = 'stick-until-failure',
     apiKeys,
     config,
+    middleware: middlewareList,
   } = options;
 
   const mesh = new ModelMesh();
@@ -262,7 +265,11 @@ export function create(...args: unknown[]): MeshClient {
       meshConfig = MeshConfig.fromDict(config);
     }
     mesh.initialize(meshConfig);
-    return mesh.getClient();
+    const client = mesh.getClient();
+    if (middlewareList && middlewareList.length > 0) {
+      mesh.router.setMiddleware(new MiddlewareStack(middlewareList));
+    }
+    return client;
   }
 
   if (capabilities.length === 0 && pool === undefined) {
@@ -325,5 +332,9 @@ export function create(...args: unknown[]): MeshClient {
     pools: poolsSection,
     observability: { connector: 'modelmesh.null.v1' },
   }));
-  return mesh.getClient();
+  const client = mesh.getClient();
+  if (middlewareList && middlewareList.length > 0) {
+    mesh.router.setMiddleware(new MiddlewareStack(middlewareList));
+  }
+  return client;
 }