synth-ai 0.2.14__py3-none-any.whl → 0.2.16__py3-none-any.whl

examples/rl/task_app/math_task_app.py

@@ -0,0 +1,111 @@
+"""Legacy entrypoint for the math single-step task app."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.requests import Request
+from synth_ai.task.auth import is_api_key_header_authorized, normalize_environment_api_key
+from synth_ai.task.server import create_task_app, run_task_app
+
+from .math_single_step import build_config
+
+
+def fastapi_app():
+    """Return a FastAPI application for hosting the math task app."""
+
+    app = create_task_app(build_config())
+
+    # Replace default health endpoints with auth-tolerant handlers.
+    filtered_routes = []
+    for route in app.router.routes:
+        path = getattr(route, "path", None)
+        methods = getattr(route, "methods", set()) or set()
+        if path in {"/health", "/health/rollout"} and "GET" in methods:
+            continue
+        filtered_routes.append(route)
+    app.router.routes = filtered_routes
+
+    def _log_env_key_prefix(source: str, env_key: str | None) -> str | None:
+        if not env_key:
+            return None
+        prefix = env_key[: max(1, len(env_key) // 2)]
+        print(f"[{source}] expected ENVIRONMENT_API_KEY prefix: {prefix}")
+        return prefix
+
+    @app.get("/health")
+    async def health(request: Request):
+        env_key = normalize_environment_api_key()
+        if not env_key:
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "detail": "Missing ENVIRONMENT_API_KEY"},
+            )
+        if not is_api_key_header_authorized(request):
+            prefix = _log_env_key_prefix("health", env_key)
+            content = {"status": "healthy", "authorized": False}
+            if prefix:
+                content["expected_api_key_prefix"] = prefix
+            return JSONResponse(status_code=200, content=content)
+        return {"status": "healthy", "authorized": True}
+
+    @app.get("/health/rollout")
+    async def health_rollout(request: Request):
+        env_key = normalize_environment_api_key()
+        if not env_key:
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "detail": "Missing ENVIRONMENT_API_KEY"},
+            )
+        if not is_api_key_header_authorized(request):
+            prefix = _log_env_key_prefix("health/rollout", env_key)
+            content = {"status": "healthy", "authorized": False}
+            if prefix:
+                content["expected_api_key_prefix"] = prefix
+            return JSONResponse(status_code=200, content=content)
+        return {"ok": True, "authorized": True}
+
+    @app.exception_handler(RequestValidationError)
+    async def _on_validation_error(request: Request, exc: RequestValidationError):
+        try:
+            hdr = request.headers
+            snapshot = {
+                "path": str(request.url.path),
+                "have_x_api_key": bool(hdr.get("x-api-key")),
+                "have_x_api_keys": bool(hdr.get("x-api-keys")),
+                "have_authorization": bool(hdr.get("authorization")),
+                "errors": exc.errors()[:5],
+            }
+            print("[422] validation", snapshot, flush=True)
+        except Exception:
+            pass
+        return JSONResponse(
+            status_code=422, content={"status": "invalid", "detail": exc.errors()[:5]}
+        )
+
+    return app
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run the math single-step task app locally")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8101)
+    parser.add_argument("--reload", action="store_true", help="Enable uvicorn autoreload")
+    parser.add_argument(
+        "--env-file",
+        action="append",
+        default=[],
+        help="Path to .env file to load (can be specified multiple times)",
+    )
+    args = parser.parse_args()
+
+    run_task_app(
+        build_config,
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        env_files=args.env_file or [],
+    )

examples/sft/README.md

@@ -27,7 +27,7 @@ You can generate traces with the Crafter task app and then export them to SFT JS
 # Serve the task app locally with tracing enabled (example)
 uvx synth-ai serve grpo-crafter \
   --trace traces/v3 \
-  --trace-db traces/v3/synth_ai.db \
+  --trace-db traces/v3/task_app_traces_<timestamp>.db \
   --port 8001
 
 # Or run traced local rollouts to accumulate data
@@ -36,9 +36,9 @@ uv run python examples/warming_up_to_rl/run_local_rollout_traced.py \
 
 # Export SFT dataset from the trace DB
 uv run python examples/warming_up_to_rl/export_trace_sft.py \
-  --db traces/v3/synth_ai.db \
+  --db traces/v3/task_app_traces_<timestamp>.db \
   --min-unique 0 \
-  --output examples/sft/ft_data/crafter_traces.jsonl
+  --output examples/sft/ft_data/crafter_sft.jsonl
 ```
 
 Notes:
@@ -56,7 +56,7 @@ Use the standard CLI. Do not use a custom Python finetuning script. Point the CL
 uvx synth-ai train \
   --type sft \
   --config examples/sft/configs/crafter_lora_qwen0p6b.toml \
-  --dataset examples/sft/ft_data/crafter_traces.jsonl \
+  --dataset examples/sft/ft_data/crafter_sft.jsonl \
   --env-file /Users/joshpurtell/Documents/GitHub/monorepo/backend/.env.dev
 ```
 
@@ -76,7 +76,7 @@ Full finetuning updates all weights and uses a near-identical CLI flow with the
 uvx synth-ai train \
   --type sft \
   --config examples/sft/configs/crafter_fft_qwen0p6b.toml \
-  --dataset examples/sft/ft_data/crafter_traces.jsonl \
+  --dataset examples/sft/ft_data/crafter_sft.jsonl \
   --env-file /Users/joshpurtell/Documents/GitHub/monorepo/backend/.env.dev
 ```
 

examples/sft/configs/crafter_fft_qwen0p6b.toml

@@ -1,7 +1,9 @@
+type = "sft"
+
 [job]
 model = "Qwen/Qwen3-0.6B"
 # Prefer passing --dataset at runtime for repeatability
-# data = "examples/sft/ft_data/crafter_traces.jsonl"
+# data = "examples/sft/ft_data/crafter_sft.jsonl"
 
 [compute]
 gpu_type = "H100"
@@ -11,7 +13,7 @@ nodes = 1
 [data]
 topology = {}
 # Optional validation set if you have one locally
-# validation_path = "examples/sft/ft_data/crafter_traces.val.jsonl"
+# validation_path = "examples/sft/ft_data/crafter_sft.val.jsonl"
 
 [training]
 mode = "sft_offline"

examples/sft/configs/crafter_lora_qwen0p6b.toml

@@ -1,7 +1,9 @@
+type = "sft"
+
 [job]
 model = "Qwen/Qwen3-0.6B"
 # Optionally set here, but prefer passing --dataset at runtime
-# data = "examples/sft/ft_data/crafter_traces.jsonl"
+# data = "examples/sft/ft_data/crafter_sft.jsonl"
 
 [compute]
 gpu_type = "H100"
@@ -12,7 +14,7 @@ nodes = 1
 # Forwarded into metadata.effective_config
 topology = {}
 # Optional validation set if you have one locally
-# validation_path = "examples/sft/ft_data/crafter_traces.val.jsonl"
+# validation_path = "examples/sft/ft_data/crafter_sft.val.jsonl"
 
 [training]
 mode = "lora"
@@ -42,4 +44,3 @@ fsdp = false
 bf16 = true
 fp16 = false
 activation_checkpointing = true
-

examples/sft/evaluate.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import argparse
 import asyncio
 import os
+from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any
 
@@ -104,10 +105,8 @@ async def main() -> None:
     for r in results:
         ers = r.get("episode_returns") or []
         if isinstance(ers, list) and ers:
-            try:
+            with suppress(Exception):
                 flat_returns.append(float(ers[0]))
-            except Exception:
-                pass
     if flat_returns:
         mean_ret = sum(flat_returns) / len(flat_returns)
         print(f"mean_return={mean_ret:.3f} over {len(flat_returns)} episodes")
@@ -116,4 +115,3 @@ async def main() -> None:
 if __name__ == "__main__":
     asyncio.run(main())
 
-

examples/sft/export_dataset.py

@@ -20,12 +20,17 @@ from examples.warming_up_to_rl.export_trace_sft import (
     parse_event_filters,
     write_jsonl,
 )
+from synth_ai.tracing_v3.constants import TRACE_DB_DIR, canonical_trace_db_name
 
 
 def main() -> None:
     p = argparse.ArgumentParser(description=__doc__)
-    p.add_argument("--db", type=Path, default=Path("traces/v3/synth_ai.db"))
-    p.add_argument("--output", type=Path, default=Path("examples/sft/ft_data/crafter_traces.jsonl"))
+    p.add_argument(
+        "--db",
+        type=Path,
+        default=TRACE_DB_DIR / canonical_trace_db_name(),
+    )
+    p.add_argument("--output", type=Path, default=Path("examples/sft/ft_data/crafter_sft.jsonl"))
     p.add_argument("--model", action="append", dest="models")
     p.add_argument("--provider", action="append", dest="providers")
     p.add_argument("--min-unique", type=int, default=0)
@@ -113,5 +118,3 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
-
-

examples/swe/task_app/README.md

@@ -38,7 +38,7 @@ uvx synth-ai serve swe-mini \
   --port 8020 \
   --env-file .env \
   --trace traces/v3 \
-  --trace-db traces/v3/synth_ai.db
+  --trace-db traces/v3/task_app_traces_<timestamp>.db
 ```
 
 This avoids interactive prompts (useful for CI) and loads `ENVIRONMENT_API_KEY`, `OPENAI_API_KEY`, etc. from `.env`.

examples/swe/task_app/grpo_swe_mini.py

@@ -556,7 +556,6 @@ register_task_app(
         description="mini-swe-agent task app with rollout + proxy endpoints",
         config_factory=build_config,
         aliases=("mini-swe", "swe-mini-task"),
-        env_files=(str(REPO_ROOT / "backend" / ".env.dev"),),
         modal=ModalDeploymentConfig(
             app_name="swe-mini-task-app",
             python_version="3.11",

examples/swe/task_app/grpo_swe_mini_task_app.py

@@ -114,23 +114,11 @@ if __name__ == "__main__":
     parser.add_argument("--host", default="0.0.0.0")
     parser.add_argument("--port", type=int, default=8020)
     parser.add_argument("--reload", action="store_true", help="Enable uvicorn autoreload")
-    parser.add_argument(
-        "--env-file",
-        action="append",
-        default=[],
-        help="Additional .env files to load before startup",
-    )
     args = parser.parse_args()
 
-    default_env = Path(__file__).resolve().parents[4] / "backend" / ".env.dev"
-    env_files = [str(default_env)] if default_env.exists() else []
-    env_files.extend(args.env_file or [])
-
     run_task_app(
         build_task_app_config,
         host=args.host,
         port=args.port,
         reload=args.reload,
-        env_files=env_files,
     )
-

examples/swe/task_app/hosted/envs/mini_swe/environment.py

@@ -776,7 +776,7 @@ class MiniSweEnvironmentWrapper:
             or os.getenv("SWE_REX_MODAL_SANDBOX_KWARGS")
         )
         modal_kwargs: dict[str, Any] = {}
-        if isinstance(modal_kwargs_raw, (dict, list)):
+        if isinstance(modal_kwargs_raw, dict | list):
             modal_kwargs = dict(modal_kwargs_raw or {})
         elif isinstance(modal_kwargs_raw, str) and modal_kwargs_raw.strip():
             try:
@@ -841,9 +841,9 @@ class MiniSweEnvironmentWrapper:
             instance_image_tag=instance_image_tag,
             env_image_tag=env_image_tag,
             model_name=model_name,
-            Command=Command,
-            WriteFileRequest=WriteFileRequest,
-            ReadFileRequest=ReadFileRequest,
+            command_cls=Command,
+            write_file_request_cls=WriteFileRequest,
+            read_file_request_cls=ReadFileRequest,
         )
         try:
             return self._run_coroutine_blocking(coro)
@@ -867,9 +867,9 @@ class MiniSweEnvironmentWrapper:
         instance_image_tag: str,
         env_image_tag: str,
         model_name: str,
-        Command,
-        WriteFileRequest,
-        ReadFileRequest,
+        command_cls,
+        write_file_request_cls,
+        read_file_request_cls,
     ) -> dict[str, Any]:
         deployment = deployment_config.get_deployment()
         await deployment.start()
@@ -880,7 +880,7 @@ class MiniSweEnvironmentWrapper:
 
             # Ensure working directory exists.
             mkdir_resp = await runtime.execute(
-                Command(command=["mkdir", "-p", remote_root], timeout=60, shell=False)
+                command_cls(command=["mkdir", "-p", remote_root], timeout=60, shell=False)
             )
             if mkdir_resp.exit_code not in (0, None):
                 logger.warning("Failed to ensure remote directory %s (exit=%s)", remote_root, mkdir_resp.exit_code)
@@ -888,8 +888,8 @@ class MiniSweEnvironmentWrapper:
             # Upload dataset & predictions.
             dataset_blob = json.dumps([instance], ensure_ascii=False)
             predictions_blob = json.dumps({instance_id: prediction}, ensure_ascii=False)
-            await runtime.write_file(WriteFileRequest(path=dataset_remote_path, content=dataset_blob))
-            await runtime.write_file(WriteFileRequest(path=predictions_remote_path, content=predictions_blob))
+            await runtime.write_file(write_file_request_cls(path=dataset_remote_path, content=dataset_blob))
+            await runtime.write_file(write_file_request_cls(path=predictions_remote_path, content=predictions_blob))
 
             eval_cmd = [
                 "python",
@@ -921,7 +921,7 @@ class MiniSweEnvironmentWrapper:
 
             command_timeout = max(eval_timeout + 900, 1200)
             response = await runtime.execute(
-                Command(
+                command_cls(
                     command=eval_cmd,
                     timeout=command_timeout,
                     cwd=remote_root,
@@ -945,7 +945,7 @@ class MiniSweEnvironmentWrapper:
                 for filename in ("report.json", "test_output.txt", "run_instance.log", "patch.diff"):
                     remote_path = f"{remote_log_dir}/{filename}"
                     try:
-                        content = await runtime.read_file(ReadFileRequest(path=remote_path))
+                        content = await runtime.read_file(read_file_request_cls(path=remote_path))
                     except Exception:
                         continue
                     if getattr(content, "content", None):
@@ -1073,7 +1073,7 @@ class MiniSweEnvironmentWrapper:
             return value
         if isinstance(value, str):
             return value.strip().lower() in {"1", "true", "yes", "on"}
-        if isinstance(value, (int, float)):
+        if isinstance(value, int | float):
             return bool(value)
         return False  # pragma: no cover - defensive default
 

examples/swe/task_app/hosted/policy_routes.py

@@ -343,8 +343,6 @@ async def step_policy(
             inf_req = meta["inference_request"]
             msgs = inf_req["messages"]
             model_name = inf_req.get("model") or getattr(policy, "model", None) or ""
-            system_messages: list[str] = []
-            user_messages: list[str] = []
             if msgs and len(msgs) > 0 and msgs[0]["role"] == "system":
                 sys_text = msgs[0]["content"]
                 policy_name = getattr(policy, "name", "") or type(policy).__name__.lower()

examples/swe/task_app/hosted/rollout.py

@@ -888,14 +888,6 @@ async def execute_rollout(
             logger.debug(f"TRACER_FACTORY_FAIL: {exc}")
     tracing_context = RolloutTracingContext(tracer_instance, request, req)
     await tracing_context.start_session()
-    # Print whether tracing is active for this rollout
-    try:
-        print(
-            f"[rollout] tracing enabled={bool(tracing_context.enabled)} run_id={request.run_id}",
-            flush=True,
-        )
-    except Exception:
-        pass
 
     # Register run
     registry.register_run(request.run_id)

examples/task_apps/crafter/task_app/grpo_crafter.py

@@ -7,6 +7,7 @@ import logging
 import os
 import sys
 from collections.abc import Iterable, Sequence
+from contextlib import suppress
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -614,16 +615,14 @@ def _coerce_math_to_crafter(request: RolloutRequest) -> RolloutRequest:
 
     coerced = request.model_copy(update={"env": updated_env, "policy": updated_policy, "ops": ops_override})
 
-    try:
+    with suppress(Exception):
         print(
             "[rollout] remapped math request -> crafter "
             f"(env={request.env.env_name!r}→{coerced.env.env_name!r}, "
             f"policy={request.policy.policy_name!r}→{coerced.policy.policy_name!r})",
             flush=True,
         )
-    except Exception:
-        pass
-    try:
+    with suppress(Exception):
         logger.info(
             "ROLLOUT_ALIAS: remapped math env/policy to crafter (env=%s→%s, policy=%s→%s)",
             request.env.env_name,
@@ -631,8 +630,6 @@ def _coerce_math_to_crafter(request: RolloutRequest) -> RolloutRequest:
             request.policy.policy_name,
             coerced.policy.policy_name,
         )
-    except Exception:
-        pass
 
     return coerced
 
@@ -654,7 +651,7 @@ def _resolve_trace_correlation_id(policy_cfg: dict[str, Any], mode: Any = None)
             if stripped:
                 return stripped
 
-    return extract_trace_correlation_id(policy_cfg.get("inference_url"), mode=mode)
+    return extract_trace_correlation_id(policy_cfg.get("inference_url"))
 
 
 async def rollout_executor(request: RolloutRequest, fastapi_request) -> RolloutResponse:

examples/task_apps/crafter/task_app/synth_envs_hosted/envs/crafter/policy.py

@@ -59,6 +59,13 @@ class CrafterPolicy(Policy):
         self.trajectory_history: list[dict[str, Any]] = []  # env/policy step records
 
     async def initialize(self, config: dict[str, Any]) -> None:
+        # DEBUG: Log the incoming config
+        import logging
+        _logger = logging.getLogger(__name__)
+        _logger.debug(f"🔊 [POLICY_INIT] Received config keys: {list(config.keys())}")
+        _logger.debug(f"🔊 [POLICY_INIT] use_vision in config: {'use_vision' in config}, value: {config.get('use_vision')}")
+        _logger.debug(f"🔊 [POLICY_INIT] image_only_mode in config: {'image_only_mode' in config}, value: {config.get('image_only_mode')}")
+        
         if "inference_url" in config:
             self.inference_url = config["inference_url"]
         if "model" in config:
@@ -67,6 +74,7 @@ class CrafterPolicy(Policy):
             self.use_tools = bool(config["use_tools"])
         if "use_vision" in config:
             self.use_vision = bool(config["use_vision"])
+            _logger.debug(f"🔊 [POLICY_INIT] Set use_vision={self.use_vision} from config")
         if "image_only_mode" in config:
             self.image_only_mode = bool(config["image_only_mode"])
             # If image_only_mode is enabled, automatically enable vision
@@ -97,6 +105,9 @@ class CrafterPolicy(Policy):
         self.history_messages = []
         self.turn_index = 0
         self.trajectory_history = []
+        
+        # DEBUG: Log final state
+        _logger.debug(f"🔊 [POLICY_INIT] FINAL STATE: use_vision={self.use_vision}, image_only_mode={self.image_only_mode}, model={self.model}")
 
     def _append_user_observation(self, observation_text: str) -> None:
         self.history_messages.append({"role": "user", "content": observation_text})
@@ -131,10 +142,36 @@ class CrafterPolicy(Policy):
             history=history,
             turn=turn,
             image_parts=image_parts,
+            image_only_mode=self.image_only_mode,
         )
+        
+        # DEBUG: Log message structure
+        import logging
+        _logger = logging.getLogger(__name__)
+        _logger.debug(f"🔊 [BUILD_REQUEST] Built {len(messages)} messages")
+        for idx, msg in enumerate(messages):
+            role = msg.get("role")
+            content = msg.get("content")
+            if isinstance(content, list):
+                _logger.debug(f"🔊 [BUILD_REQUEST] Message[{idx}] role={role}, content=list[{len(content)}]")
+                for part_idx, part in enumerate(content):
+                    if isinstance(part, dict):
+                        part_type = part.get("type")
+                        _logger.debug(f"🔊 [BUILD_REQUEST]   Part[{part_idx}]: type={part_type}")
+            else:
+                content_len = len(str(content)) if content else 0
+                _logger.debug(f"🔊 [BUILD_REQUEST] Message[{idx}] role={role}, content_len={content_len}")
+        
         payload: dict[str, Any] = {
             "messages": messages,
         }
+        
+        # DEBUG: Verify messages are in payload correctly
+        _logger.debug(f"🔊 [BUILD_REQUEST_PAYLOAD] Created payload with {len(payload['messages'])} messages")
+        for idx, msg in enumerate(payload["messages"]):
+            content = msg.get("content")
+            _logger.debug(f"🔊 [BUILD_REQUEST_PAYLOAD] Payload message[{idx}]: type={type(content).__name__}, is_list={isinstance(content, list)}, len={len(content) if isinstance(content, list) else len(str(content)) if content else 0}")
+        
         if self.model is not None:
             payload["model"] = self.model
         # Thinking controls
@@ -360,7 +397,18 @@ class CrafterPolicy(Policy):
             raw_candidate = metadata.get("raw_observation")
             if isinstance(raw_candidate, dict):
                 raw_observation = raw_candidate
+        
+        # DEBUG: Log image extraction
+        import logging
+        _logger = logging.getLogger(__name__)
+        _logger.debug(f"🔊 [POLICY] use_vision={self.use_vision}, has_raw_obs={raw_observation is not None}")
+        if raw_observation:
+            obs = raw_observation.get("observation", raw_observation)
+            data_url = obs.get("observation_image_data_url") if isinstance(obs, dict) else None
+            _logger.debug(f"🔊 [POLICY] has_data_url={data_url is not None}, url_preview={data_url[:50] if data_url else 'NONE'}...")
+        
         image_parts = self._extract_image_parts(raw_observation)
+        _logger.debug(f"🔊 [POLICY] Extracted {len(image_parts)} image parts")
 
         payload = self.build_inference_request(
             combined_text,
@@ -368,7 +416,17 @@ class CrafterPolicy(Policy):
             turn=self.turn_index,
             image_parts=image_parts,
         )
-        # print("Debugging only:; ", payload)
+        
+        # DEBUG: Verify payload before returning
+        _logger.debug(f"🔊 [POLICY_STEP_RETURN] About to return payload with {len(payload.get('messages', []))} messages")
+        for idx, msg in enumerate(payload.get("messages", [])):
+            content = msg.get("content")
+            _logger.debug(f"🔊 [POLICY_STEP_RETURN] Return message[{idx}]: type={type(content).__name__}, is_list={isinstance(content, list)}")
+            if isinstance(content, list):
+                _logger.debug(f"🔊 [POLICY_STEP_RETURN]   Content list has {len(content)} items")
+                # Add assertion to catch corruption early
+                assert len(content) > 0, f"Message content list is empty! This should contain images."
+        
         meta_out = {
             "inference_url": self.inference_url,
             "inference_request": payload,

examples/task_apps/crafter/task_app/synth_envs_hosted/inference/openai_client.py

@@ -218,8 +218,20 @@ class OpenAIClient:
             # Do NOT fall back silently; surface the error so callers fail fast
             raise
 
+        # DEBUG: Log request BEFORE _fix_model_parameters
+        logger.debug(f"🔊 [OPENAI_CLIENT_PRE_FIX] Request message[1] content type: {type(request.get('messages', [])[1].get('content') if len(request.get('messages', [])) > 1 else None)}")
+        if len(request.get("messages", [])) > 1:
+            msg1_content = request["messages"][1].get("content")
+            logger.debug(f"🔊 [OPENAI_CLIENT_PRE_FIX] Message[1] content value: {msg1_content if not isinstance(msg1_content, list) else f'list[{len(msg1_content)}]'}")
+        
         # Fix parameter compatibility for newer models
         processed_request = self._fix_model_parameters(request, target_url=url)
+        
+        # DEBUG: Log request AFTER _fix_model_parameters
+        logger.debug(f"🔊 [OPENAI_CLIENT_POST_FIX] Processed message[1] content type: {type(processed_request.get('messages', [])[1].get('content') if len(processed_request.get('messages', [])) > 1 else None)}")
+        if len(processed_request.get("messages", [])) > 1:
+            msg1_content_post = processed_request["messages"][1].get("content")
+            logger.debug(f"🔊 [OPENAI_CLIENT_POST_FIX] Message[1] content value: {msg1_content_post if not isinstance(msg1_content_post, list) else f'list[{len(msg1_content_post)}]'}")
 
         # Log request (redact messages in production)
         logger.info(f"Inference POST target: {url}")
@@ -228,6 +240,24 @@ class OpenAIClient:
         with contextlib.suppress(Exception):
             keys_preview = sorted(processed_request.keys())
             logger.info(f"Request keys: {keys_preview}")
+            # DEBUG: Log message structure for vision debugging
+            if "messages" in processed_request:
+                msgs = processed_request["messages"]
+                if isinstance(msgs, list):
+                    logger.debug(f"🔊 [OPENAI_CLIENT] Request has {len(msgs)} messages")
+                    for idx, msg in enumerate(msgs):
+                        if isinstance(msg, dict):
+                            role = msg.get("role")
+                            content = msg.get("content")
+                            if isinstance(content, list):
+                                logger.debug(f"🔊 [OPENAI_CLIENT] Message[{idx}] role={role}, content=list[{len(content)}]")
+                                for part_idx, part in enumerate(content):
+                                    if isinstance(part, dict):
+                                        part_type = part.get("type")
+                                        logger.debug(f"🔊 [OPENAI_CLIENT]   Part[{part_idx}]: type={part_type}")
+                            else:
+                                content_len = len(str(content)) if content else 0
+                                logger.debug(f"🔊 [OPENAI_CLIENT] Message[{idx}] role={role}, content_type={type(content).__name__}, len={content_len}")
 
         # Final hard-guard for OpenAI: ensure unsupported field is not present
         try: