synth-ai 0.2.13.dev1__py3-none-any.whl → 0.2.14__py3-none-any.whl

examples/{warming_up_to_rl → task_apps/crafter}/task_app/synth_envs_hosted/envs/crafter/react_agent.py

@@ -85,8 +85,17 @@ class CrafterReActAgent:
         history: list[dict[str, Any]] | None = None,
         turn: int | None = None,
         image_parts: list[dict[str, Any]] | None = None,
+        image_only_mode: bool = False,
     ) -> list[dict[str, Any]]:
-        """Construct OpenAI-style messages list for vLLM generation."""
+        """Construct OpenAI-style messages list for vLLM generation.
+        
+        Args:
+            observation: Text observation to include
+            history: Previous conversation history
+            turn: Current turn number
+            image_parts: Image content parts in OpenAI format
+            image_only_mode: If True, only include images without text observation
+        """
         msgs: list[dict[str, Any]] = [
             {"role": "system", "content": CrafterReActAgent.get_system_prompt()}
         ]
@@ -94,8 +103,14 @@ class CrafterReActAgent:
             msgs.extend(history)
         user_content: Any
         if image_parts:
-            user_content = [{"type": "text", "text": observation}] + list(image_parts)
+            # Image-only mode: send only images without text observation
+            if image_only_mode:
+                user_content = list(image_parts)
+            else:
+                # Normal vision mode: send both text and images
+                user_content = [{"type": "text", "text": observation}] + list(image_parts)
         else:
+            # Text-only mode (default): no images
             user_content = observation
         msgs.append({"role": "user", "content": user_content})
         return msgs

examples/{warming_up_to_rl → task_apps/crafter}/task_app/synth_envs_hosted/inference/openai_client.py

@@ -149,7 +149,11 @@ class OpenAIClient:
             OpenAI-compatible chat completion response
         """
         base = (base_url or self.base_url).rstrip("/")
-        url = base + "/v1/chat/completions"
+        # Don't append /v1/chat/completions if the URL already contains it
+        if "/v1/chat/completions" in base:
+            url = base
+        else:
+            url = base + "/v1/chat/completions"
         timeout = timeout_s or self.timeout_s
 
         # Merge headers
@@ -164,10 +168,28 @@ class OpenAIClient:
         except Exception:
             pass
 
-        # If target is our in-app Groq proxy, force Authorization to use GROQ_API_KEY
+        # Set Authorization header based on the target URL
         try:
             low_url = (url or "").lower()
-            if "/proxy/groq" in low_url or "groq" in low_url:
+            
+            # If calling OpenAI directly (api.openai.com)
+            if "api.openai.com" in low_url:
+                openai_key = os.getenv("OPENAI_API_KEY")
+                if openai_key and isinstance(openai_key, str):
+                    headers["Authorization"] = f"Bearer {openai_key}"
+            
+            # If target is Synth backend (any deployment), use SYNTH_API_KEY
+            # Matches: synth-backend-*, agent-learning*, localhost:8000, 127.0.0.1:8000
+            elif any(pattern in low_url for pattern in [
+                "synth-backend", "synth.run", "agent-learning",
+                "localhost:8000", "127.0.0.1:8000"
+            ]):
+                synth_key = os.getenv("SYNTH_API_KEY")
+                if synth_key and isinstance(synth_key, str):
+                    headers["Authorization"] = f"Bearer {synth_key}"
+            
+            # If target is Groq, use GROQ_API_KEY
+            elif "/proxy/groq" in low_url or "api.groq.com" in low_url:
                 gk = os.getenv("GROQ_API_KEY")
                 if gk and isinstance(gk, str):
                     headers["Authorization"] = f"Bearer {gk}"

examples/{warming_up_to_rl → task_apps/crafter}/task_app/synth_envs_hosted/policy_routes.py

@@ -10,11 +10,13 @@ from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
 from synth_ai.task.auth import allowed_environment_api_keys, normalize_environment_api_key
+from synth_ai.task.contracts import RolloutMode
 
 from .envs.crafter.policy import CrafterPolicy
 from .inference.openai_client import create_inference_client
 from .registry import registry
 from .storage.volume import storage
+from .utils import ensure_chat_completions_url
 
 # Token budgeting (shared logic with inference server)
 try:
@@ -40,6 +42,7 @@ class PolicyCreateRequest(BaseModel):
     parent_policy_id: str | None = None
     rl_run_id: str
     bound_env_id: str | None = None
+    mode: RolloutMode
 
 
 class PolicyCreateResponse(BaseModel):
@@ -97,10 +100,40 @@ async def create_policy(
 
         # Set defaults from TaskApp / environment if not provided
         config = dict(request.config or {})
+        provider_raw = config.get("provider") or config.get("vendor")
+        provider = str(provider_raw).strip().lower() if provider_raw else None
+
+        # Resolve base URL for proxy endpoints (strip trailing slash)
+        base_url = str(req.base_url).rstrip("/")
+
+        if provider == "groq":
+            # Route through in-app Groq proxy by default
+            config.setdefault("inference_url", f"{base_url}/proxy/groq")
+            # Default to a recent Groq-hosted Qwen unless caller overrides
+            preferred_model = "qwen/qwen3-32b"
+            config.setdefault("model", preferred_model)
+            # Groq Qwen defaults tuned for deterministic tool use
+            config.setdefault("temperature", 0.0)
+            config.setdefault("top_p", 0.95)
+            config.setdefault("max_tokens", 256)
+            # Avoid leaking provider in downstream policy if unset
+            config["provider"] = "groq"
+        elif provider == "openai":
+            config.setdefault("inference_url", f"{base_url}/proxy")
+            config["provider"] = "openai"
+
+        received_url = config.get("inference_url")
+        logger.info(
+            "POLICY_CREATE: policy=%s provider=%s raw_inference_url=%s",
+            request.policy_name,
+            provider,
+            received_url,
+        )
+
         if "inference_url" not in config and task_app is not None:
-            base_url = getattr(task_app, "vllm_base_url", None)
-            if base_url:
-                config["inference_url"] = base_url
+            task_base_url = getattr(task_app, "vllm_base_url", None)
+            if task_base_url:
+                config["inference_url"] = task_base_url
         if "model" not in config and task_app is not None:
             default_model = getattr(task_app, "default_model", None)
             if default_model:
@@ -111,6 +144,31 @@ async def create_policy(
                 detail="Policy configuration must include 'inference_url' and 'model'.",
             )
 
+        # Get mode from PolicyCreateRequest (defaults to "rl" for backward compatibility)
+        mode = request.mode
+        logger.info("POLICY_CREATE: Using mode=%s for URL processing", mode)
+        
+        sanitized_url = ensure_chat_completions_url(config.get("inference_url"), mode=mode)
+        if isinstance(sanitized_url, str) and sanitized_url:
+            if sanitized_url != config.get("inference_url"):
+                logger.warning(
+                    "POLICY_CREATE: normalized inference_url for policy=%s provider=%s mode=%s from %s to %s",
+                    request.policy_name,
+                    provider,
+                    mode,
+                    config.get("inference_url"),
+                    sanitized_url,
+                )
+            config["inference_url"] = sanitized_url
+        else:
+            logger.warning(
+                "POLICY_CREATE: unable to normalize inference_url for policy=%s provider=%s mode=%s raw=%s",
+                request.policy_name,
+                mode,
+                provider,
+                config.get("inference_url"),
+            )
+
         # Create policy instance based on name
         pname = request.policy_name.lower()
         if pname in ["crafter-react", "crafter"]:
@@ -485,7 +543,22 @@ async def step_policy(
 
             # Ensure meta carries the final target URL for downstream logging/clients
             with contextlib.suppress(Exception):
-                meta["inference_url"] = target_url
+                sanitized_target = ensure_chat_completions_url(target_url)
+                if sanitized_target and sanitized_target != target_url:
+                    logger.warning(
+                        "POLICY_STEP: normalized inference_url mid-flight policy=%s from %s to %s",
+                        policy_name,
+                        target_url,
+                        sanitized_target,
+                    )
+                elif not sanitized_target:
+                    logger.info(
+                        "POLICY_STEP: inference_url unchanged policy=%s target=%s",
+                        policy_name,
+                        target_url,
+                    )
+                meta["inference_url"] = sanitized_target if sanitized_target else target_url
+                target_url = sanitized_target or target_url
 
             # Select API key based on resolved target URL
             api_key_override = None

examples/{warming_up_to_rl → task_apps/crafter}/task_app/synth_envs_hosted/rollout.py

@@ -13,6 +13,7 @@ from pydantic import BaseModel, Field
 from synth_ai.lm.vendors.base import BaseLMResponse
 from synth_ai.task.tracing_utils import unique_sft_path
 from synth_ai.tracing_v3.abstractions import EnvironmentEvent, LMCAISEvent, TimeRecord
+from synth_ai.task.contracts import RolloutMode
 from synth_ai.tracing_v3.llm_call_record_helpers import create_llm_call_record_from_response
 from synth_ai.tracing_v3.session_tracer import SessionTracer
 
@@ -120,6 +121,8 @@ class RolloutRequest(BaseModel):
     # Optional run/session context
     training_session_id: str | None = None
     synth_base_url: str | None = None
+    # Mode controls URL transformation: REQUIRED to make intent explicit
+    mode: RolloutMode
 
 
 class RolloutStep(BaseModel):
@@ -140,6 +143,7 @@ class RolloutTrajectory(BaseModel):
     final: dict[str, Any] | None = None
     length: int
     decision_samples: list[dict[str, Any]] | None = None
+    inference_url: str | None = None
 
 
 def _normalize_step_strategy(raw_strategy: Any) -> str:
@@ -452,11 +456,12 @@ class RolloutMetrics(BaseModel):
 class RolloutResponse(BaseModel):
     run_id: str
     trajectories: list[RolloutTrajectory]
-    branches: dict[str, list[str]] = {}
+    branches: dict[str, list[str]] = Field(default_factory=dict)
     metrics: RolloutMetrics
     aborted: bool = False
     ops_executed: int = 0
     trace: dict[str, Any] | None = None
+    pipeline_metadata: dict[str, Any] = Field(default_factory=dict)
 
 
 class RolloutTracingContext:
@@ -567,7 +572,7 @@ class RolloutTracingContext:
             try:
                 await self.tracer.record_message(
                     content=self._prompt_payload(entry, role="system"),
-                    message_type="policy_system_prompt",
+                    message_type="system",  # Use standard message type
                     metadata=self._message_metadata(),
                 )
             except Exception as exc:
@@ -576,11 +581,16 @@ class RolloutTracingContext:
             try:
                 await self.tracer.record_message(
                     content=self._prompt_payload(entry, role="user"),
-                    message_type="policy_user_prompt",
+                    message_type="user",  # Use standard message type
                     metadata=self._message_metadata(),
                 )
             except Exception as exc:
                 logger.debug("TRACING_USER_MSG_FAIL: %s", exc)
+        
+        # Debug: Check message count
+        if self.tracer and self.tracer._current_trace:
+            msg_count = len(self.tracer._current_trace.markov_blanket_message_history)
+            logger.info(f"[TRACE_DEBUG] After record_policy_prompts: {msg_count} messages in trace")
 
     def _content_to_text(self, content: Any) -> str:
         if isinstance(content, str):
@@ -656,8 +666,8 @@ class RolloutTracingContext:
             try:
                 await self.tracer.record_message(
                     content=self._safe_json(tool_calls),
-                    message_type="policy_tool_call",
-                    metadata=self._message_metadata(),
+                    message_type="assistant",  # Map to standard assistant message type
+                    metadata={**self._message_metadata(), "is_tool_call": True},
                 )
             except Exception as exc:
                 logger.debug("TRACING_TOOL_MSG_FAIL: %s", exc)
@@ -928,11 +938,22 @@ class RolloutTracingContext:
             except Exception as exc:
                 logger.debug("TRACING_OUTCOME_FAIL: %s", exc)
             try:
+                # Debug: Check message count before end_session
+                if self.tracer._current_trace:
+                    msg_count = len(self.tracer._current_trace.markov_blanket_message_history)
+                    logger.info(f"[TRACE_DEBUG] Before end_session: {msg_count} messages in trace")
+                
                 self.session_trace = await self.tracer.end_session()
-                if self.session_trace is not None:
+                
+                # Debug: Check if session was saved
+                if self.session_trace:
+                    logger.info(f"[TRACE_DEBUG] Session ended successfully, session_id={self.session_trace.session_id}")
                     self.session_trace.metadata.update(self.metadata_updates)
+                    logger.info(f"[TRACE_DEBUG] session_trace.metadata keys: {list(self.session_trace.metadata.keys())}")
+                else:
+                    logger.warning("[TRACE_DEBUG] end_session returned None!")
             except Exception as exc:
-                logger.debug("TRACING_END_SESSION_FAIL: %s", exc)
+                logger.warning(f"TRACING_END_SESSION_FAIL: {exc}", exc_info=True)
                 self.session_trace = None
             with contextlib.suppress(Exception):
                 await self.tracer.close()
@@ -1056,12 +1077,14 @@ async def execute_rollout(
     req: Request,
 ) -> RolloutResponse:
     """Execute a rollout with coordinated environment and policy steps."""
+    logger.info("ROLLOUT: mode = %s", request.mode)
+    
     # Emit rollout identifier early for correlation
     with contextlib.suppress(Exception):
         _rid = getattr(request, "run_id", None)
         _pol = getattr(request.policy, "policy_name", None) or getattr(request.policy, "policy_id", None)
         _env = getattr(request.env, "env_name", None) or getattr(request.env, "env_id", None)
-        logger.info("ROLLOUT_BEGIN: run_id=%s policy=%s env=%s", _rid, _pol, _env)
+        logger.info("ROLLOUT_BEGIN: run_id=%s policy=%s env=%s mode=%s", _rid, _pol, _env, request.mode)
         print(f"[rollout] begin run_id={_rid} policy={_pol} env={_env}", flush=True)
     # Enforce per-episode step cap via env-specific parameters; default to 20 if omitted
     try:
@@ -1271,6 +1294,7 @@ async def execute_rollout(
                     config=_policy_config,
                     rl_run_id=request.run_id,
                     bound_env_id=env_id,
+                    mode=request.mode,  # Pass through mode for URL transformation control
                 ),
                 req,
             )
@@ -1843,12 +1867,81 @@ async def execute_rollout(
                     timing_final.setdefault("overhead_ms", 0.0)
 
         # Build trajectory
+        # Extract inference_url from policy config (REQUIRED for trace correlation)
+        # The trainer sets this in policy config with ?cid=... parameter
+        inference_url = None
+        
+        # Try policy config from request first (most reliable source)
+        try:
+            policy_config_snapshot = (
+                request.policy.config if isinstance(request.policy.config, dict) else {}
+            )
+            inference_url = policy_config_snapshot.get("inference_url")
+            if inference_url:
+                logger.info(
+                    "ROLLOUT_TRAJECTORY: extracted inference_url from request.policy.config run_id=%s url=%s",
+                    request.run_id,
+                    inference_url,
+                )
+        except Exception as exc:
+            logger.warning(
+                "ROLLOUT_TRAJECTORY: failed to get inference_url from request.policy.config run_id=%s: %s",
+                request.run_id,
+                exc,
+            )
+        
+        # Fallback: Try policy handle snapshot (if request.policy.config failed)
+        if not inference_url and policy_handle is not None:
+            try:
+                policy_snapshot = policy_handle.snapshot()
+                inference_url = policy_snapshot.get("config", {}).get("inference_url")
+                if inference_url:
+                    logger.info(
+                        "ROLLOUT_TRAJECTORY: extracted inference_url from policy_handle.snapshot run_id=%s url=%s",
+                        request.run_id,
+                        inference_url,
+                    )
+            except Exception as exc:
+                logger.warning(
+                    "ROLLOUT_TRAJECTORY: failed to snapshot policy for run_id=%s policy_id=%s: %s",
+                    request.run_id,
+                    policy_id,
+                    exc,
+                )
+        
+        # ASSERTION: inference_url MUST be present (required by RolloutTrajectory schema)
+        if not inference_url:
+            raise ValueError(
+                f"FATAL: inference_url is required but not found!\n"
+                f"\n"
+                f"run_id: {request.run_id}\n"
+                f"policy_id: {policy_id}\n"
+                f"policy_config_keys: {list(policy_config_snapshot.keys()) if 'policy_config_snapshot' in locals() else 'N/A'}\n"
+                f"\n"
+                f"The trainer MUST set inference_url in policy config with ?cid=... parameter.\n"
+                f"This is required for trace correlation and hydration.\n"
+            )
+        
+        # policy_config_snapshot already set above in try block (line 1876-1878)
+        # Ensure it exists for logging below
+        if 'policy_config_snapshot' not in locals():
+            policy_config_snapshot = {}
+        
+        logger.info(
+            "ROLLOUT_TRAJECTORY: run_id=%s policy_id=%s inference_url=%s trace_id=%s",
+            request.run_id,
+            policy_id,
+            inference_url,
+            policy_config_snapshot.get("trace_correlation_id"),
+        )
+        
         trajectory = RolloutTrajectory(
             env_id=env_id,
             policy_id=policy_id,
             steps=trajectory_steps,
             final={"observation": _summarize_observation_for_storage(env_handle, current_obs)},
             length=len(trajectory_steps),
+            inference_url=inference_url,  # NEW: Required for trace correlation
             decision_samples=decision_samples if step_rewards_active else None,
         )
 
@@ -1938,12 +2031,17 @@ async def execute_rollout(
             )
             finalized = True
         trace_payload = tracing_context.build_trace_payload(session_trace)
+        
+        # Debug: Check trace payload
+        logger.info(f"[TRACE_DEBUG] trace_payload is None: {trace_payload is None}, return_trace={tracing_context.return_trace}")
+        if trace_payload:
+            logger.info(f"[TRACE_DEBUG] trace_payload keys: {list(trace_payload.keys())}")
 
         # Hard-fail if no steps executed (avg_turns == 0 scenario)
         if metrics.num_steps <= 0:
             raise HTTPException(status_code=500, detail="no_steps_executed: avg_turns == 0")
 
-        return RolloutResponse(
+        response = RolloutResponse(
             run_id=request.run_id,
             trajectories=[trajectory],
             branches={},
@@ -1952,6 +2050,16 @@ async def execute_rollout(
             ops_executed=ops_executed,
             trace=trace_payload,
         )
+        logger.info(
+            "ROLLOUT_RESPONSE: run_id=%s aborted=%s ops_executed=%s metrics_steps=%s trace_present=%s pipeline_metadata=%s",
+            request.run_id,
+            aborted,
+            ops_executed,
+            metrics.num_steps,
+            bool(trace_payload),
+            response.pipeline_metadata,
+        )
+        return response
 
     except Exception as e:
         logger.error(f"Rollout failed for run {request.run_id}: {e}")

examples/{warming_up_to_rl → task_apps/crafter}/task_app/synth_envs_hosted/test_service.py

@@ -1,15 +1,14 @@
 #!/usr/bin/env python3
-"""
-Simple test script for the GRPO Synth Envs Hosted Service.
-
-Run this after starting the service with:
-    python main.py
-"""
+"""Manual smoke script for the GRPO Synth Envs Hosted Service."""
 
 import asyncio
 import json
 
 import httpx
+import pytest
+
+
+pytestmark = pytest.mark.skip(reason="Requires running hosted service on localhost:8000")
 
 
 async def test_service():

examples/task_apps/crafter/task_app/synth_envs_hosted/utils.py

@@ -0,0 +1,218 @@
+"""Utility functions for the task service."""
+
+import logging
+from typing import Any
+from urllib.parse import parse_qs, urlparse, urlunparse
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+_CHAT_COMPLETIONS_SUFFIX = "/v1/chat/completions"
+
+
+def ensure_chat_completions_url(raw_url: Any, mode: str | None = None) -> Any:
+    """
+    Ensure inference URLs point at the chat completions endpoint.
+    
+    Args:
+        raw_url: The inference URL to process
+        mode: "rl" applies URL transformations, "eval" uses URLs as-is (deprecated - use RolloutMode enum)
+        
+    Returns:
+        Processed URL (transformed in RL mode, unchanged in EVAL mode)
+    """
+    # In EVAL mode, use URLs exactly as provided - no transformations
+    # Accept both string "eval" (legacy) and RolloutMode.EVAL
+    from synth_ai.task.contracts import RolloutMode
+    is_eval_mode = (mode == "eval" or mode == RolloutMode.EVAL or 
+                    (hasattr(mode, 'value') and mode.value == "eval"))
+    
+    if is_eval_mode:
+        logger.info("ensure_chat_completions_url: EVAL mode - using URL as-is: %s", raw_url)
+        return raw_url
+        
+    # RL mode: apply transformations for compatibility
+    if not isinstance(raw_url, str):
+        logger.debug("ensure_chat_completions_url: non-string input %r (type=%s)", raw_url, type(raw_url))
+        return raw_url
+    url = raw_url.strip()
+    if not url:
+        logger.debug("ensure_chat_completions_url: blank/whitespace URL input")
+        return raw_url
+
+    parsed = urlparse(url)
+    path = (parsed.path or "").rstrip("/")
+    if path.endswith("/v1/chat/completions"):
+        logger.debug("ensure_chat_completions_url: URL already normalized %s", url)
+        # Already targeting the desired endpoint; keep original to preserve trailing slash.
+        return url
+
+    if not path:
+        new_path = _CHAT_COMPLETIONS_SUFFIX
+    else:
+        new_path = f"{path}{_CHAT_COMPLETIONS_SUFFIX}"
+
+    rebuilt = parsed._replace(path=new_path)
+    normalized = urlunparse(rebuilt)
+    logger.info(
+        "ensure_chat_completions_url: RL mode - normalized inference URL from %s to %s",
+        url,
+        normalized,
+    )
+    return normalized
+
+
+def inference_url_to_trace_correlation_id(raw_url: Any, *, required: bool = False, mode: Any = None) -> str | None:
+    """
+    Extract trace_correlation_id from inference URL query params.
+    
+    The inference URL should contain ?cid=trace_xxxxx parameter.
+    This is THE canonical source for trace_correlation_id - it's what the
+    inference server uses to tag traces, so we extract it here.
+    
+    Args:
+        raw_url: Inference URL (should contain ?cid=... query param)
+        required: If True, raises AssertionError if trace_correlation_id not found
+        mode: RolloutMode or string ("rl" or "eval"). Controls warning behavior - 
+              warnings only logged for RL mode, not EVAL mode.
+    
+    Returns:
+        trace_correlation_id if found in URL, None otherwise
+        
+    Raises:
+        AssertionError: If required=True and trace_correlation_id not found
+    """
+    if not isinstance(raw_url, str):
+        logger.debug(
+            "inference_url_to_trace_correlation_id: non-string input %r (type=%s)",
+            raw_url,
+            type(raw_url)
+        )
+        if required:
+            raise AssertionError(
+                f"FATAL: inference_url_to_trace_correlation_id requires string URL, got {type(raw_url)}: {raw_url!r}"
+            )
+        return None
+    
+    parsed = urlparse(raw_url)
+    query_params = parse_qs(parsed.query or "")
+    
+    # Check all possible parameter names (cid is primary)
+    candidates = (
+        query_params.get("cid") or 
+        query_params.get("trace") or 
+        query_params.get("trace_correlation_id") or 
+        []
+    )
+    
+    for value in candidates:
+        if isinstance(value, str) and value.strip():
+            correlation_id = value.strip()
+            logger.info(
+                "inference_url_to_trace_correlation_id: ✅ extracted id=%s from url=%s",
+                correlation_id,
+                raw_url,
+            )
+            # ASSERTION: Correlation ID should look like trace_xxxxx
+            assert correlation_id.startswith("trace_"), (
+                f"FATAL: trace_correlation_id has unexpected format: {correlation_id!r}. "
+                f"Expected to start with 'trace_'"
+            )
+            return correlation_id
+    
+    # Not found - check if we're in EVAL mode (trace_correlation_id not required for eval)
+    from synth_ai.task.contracts import RolloutMode
+    is_eval_mode = (mode == "eval" or mode == RolloutMode.EVAL or 
+                    (hasattr(mode, 'value') and mode.value == "eval"))
+    
+    if is_eval_mode:
+        # For EVAL mode, missing trace_correlation_id is expected - log as debug, not warning
+        logger.debug(
+            "inference_url_to_trace_correlation_id: No trace_correlation_id in EVAL mode (expected) url=%s query_params=%s",
+            raw_url,
+            list(query_params.keys())
+        )
+    else:
+        # For RL mode, missing trace_correlation_id is concerning
+        logger.warning(
+            "inference_url_to_trace_correlation_id: ❌ NO trace_correlation_id found in url=%s query_params=%s",
+            raw_url,
+            list(query_params.keys())
+        )
+    
+    if required:
+        raise AssertionError(
+            f"FATAL: trace_correlation_id REQUIRED but not found in inference_url!\n"
+            f"\n"
+            f"URL: {raw_url}\n"
+            f"Query params found: {list(query_params.keys())}\n"
+            f"\n"
+            f"The inference_url MUST contain ?cid=trace_xxxxx parameter.\n"
+            f"This is set by the trainer when generating rollout requests.\n"
+        )
+    
+    return None
+
+
+# Legacy alias for backward compatibility
+def extract_trace_correlation_id(raw_url: Any, mode: Any = None) -> str | None:
+    """DEPRECATED: Use inference_url_to_trace_correlation_id instead."""
+    return inference_url_to_trace_correlation_id(raw_url, required=False, mode=mode)
+
+
+def convert_numpy_to_python(obj: Any) -> Any:
+    """
+    Recursively convert numpy types to Python native types for JSON serialization.
+
+    Args:
+        obj: Object that may contain numpy types
+
+    Returns:
+        Object with numpy types converted to Python native types
+    """
+    if isinstance(obj, np.integer):
+        return int(obj)
+    elif isinstance(obj, np.floating):
+        return float(obj)
+    elif isinstance(obj, np.ndarray):
+        return obj.tolist()
+    elif isinstance(obj, dict):
+        return {key: convert_numpy_to_python(value) for key, value in obj.items()}
+    elif isinstance(obj, list | tuple):
+        return [convert_numpy_to_python(item) for item in obj]
+    else:
+        return obj
+
+
+def sanitize_observation(observation: dict[str, Any]) -> dict[str, Any]:
+    """
+    Sanitize observation data for JSON serialization.
+
+    Converts numpy types and removes non-serializable objects.
+
+    Args:
+        observation: Raw observation from environment
+
+    Returns:
+        Sanitized observation safe for JSON serialization
+    """
+    if not isinstance(observation, dict):
+        return observation
+
+    sanitized = {}
+    for key, value in observation.items():
+        # Skip non-serializable keys or convert them
+        if key in ["semantic_map", "world_material_map", "observation_image"]:
+            # These are likely numpy arrays - convert to lists or skip
+            if isinstance(value, np.ndarray):
+                # For large arrays, we might want to skip or compress
+                # For now, skip them as they're likely debug info
+                continue
+        elif key == "player_position" and isinstance(value, tuple):
+            # Convert tuple with potential numpy types
+            sanitized[key] = [convert_numpy_to_python(v) for v in value]
+        else:
+            sanitized[key] = convert_numpy_to_python(value)
+
+    return sanitized

examples/task_apps/dev/pokemon_emerald/__init__.py

@@ -0,0 +1,2 @@
+"""Pokémon Emerald speedrun task app examples."""
+