synth-ai 0.2.4.dev7__py3-none-any.whl → 0.2.4.dev8__py3-none-any.whl

synth_ai/scripts/verify_rewards.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Verify reward persistence in a traces database.
+
+Usage:
+  uv run python -m synth_ai.scripts.verify_rewards --db /path/to/db.sqlite --min-reward 1
+"""
+
+import argparse
+import asyncio
+import os
+from typing import Dict
+
+from sqlalchemy import text
+
+from synth_ai.tracing_v3.turso.manager import AsyncSQLTraceManager
+
+
+async def verify(db_path: str, min_reward: int) -> int:
+    db_url = db_path
+    if not db_url.startswith("sqlite+aiosqlite:///"):
+        db_url = f"sqlite+aiosqlite:///{os.path.abspath(db_path)}"
+
+    mgr = AsyncSQLTraceManager(db_url=db_url)
+    await mgr.initialize()
+
+    try:
+        async with mgr.session() as session:
+            # Sessions with outcome_rewards
+            q_good = text(
+                """
+                SELECT session_id, MAX(total_reward) as total_reward
+                FROM outcome_rewards
+                GROUP BY session_id
+                """
+            )
+            res = await session.execute(q_good)
+            outcomes = {row[0]: int(row[1]) for row in res.fetchall()}
+
+            # Sessions without outcome_rewards
+            q_missing = text(
+                """
+                SELECT s.session_id
+                FROM session_traces s
+                LEFT JOIN outcome_rewards o ON s.session_id = o.session_id
+                WHERE o.session_id IS NULL
+                """
+            )
+            res2 = await session.execute(q_missing)
+            missing = [row[0] for row in res2.fetchall()]
+
+            # Aggregate event_rewards per session (informational)
+            q_event = text(
+                """
+                SELECT session_id, COALESCE(SUM(reward_value), 0.0) as sum_rewards
+                FROM event_rewards
+                GROUP BY session_id
+                """
+            )
+            res3 = await session.execute(q_event)
+            event_sums: Dict[str, float] = {row[0]: float(row[1]) for row in res3.fetchall()}
+
+        print(f"Sessions with outcome_rewards: {len(outcomes)}")
+        print(f"Sessions missing outcome_rewards: {len(missing)}")
+        if missing:
+            print("Missing session_ids:", ", ".join(missing[:10]) + (" ..." if len(missing) > 10 else ""))
+
+        # Threshold check
+        qualifying = {sid: r for sid, r in outcomes.items() if r >= min_reward}
+        print(f"Sessions with total_reward >= {min_reward}: {len(qualifying)}")
+
+        # Show a small comparison snapshot
+        sample = list(qualifying.items())[:5]
+        for sid, tot in sample:
+            er = event_sums.get(sid, 0.0)
+            print(f"  {sid}: outcome={tot}, sum(event_rewards)={er:.2f}")
+
+        # Exit non-zero if any sessions are missing outcome rewards
+        if missing:
+            return 2
+        if min_reward > 0 and not qualifying:
+            return 3
+        return 0
+    finally:
+        await mgr.close()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Verify reward persistence in traces DB")
+    ap.add_argument("--db", required=True, help="Path to traces SQLite DB (aiosqlite)")
+    ap.add_argument("--min-reward", type=int, default=0, help="Minimum total_reward to consider qualifying")
+    args = ap.parse_args()
+
+    return asyncio.run(verify(args.db, args.min_reward))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+

synth_ai/task/__init__.py

@@ -0,0 +1,10 @@
+from .validators import validate_task_app_url
+from .health import task_app_health
+from .contracts import TaskAppContract, TaskAppEndpoints
+
+__all__ = [
+    "validate_task_app_url",
+    "task_app_health",
+    "TaskAppContract",
+    "TaskAppEndpoints",
+]

synth_ai/task/contracts.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Any, Dict, List
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class TaskAppEndpoints:
+    """Canonical Task App endpoint shapes used by RL trainers.
+
+    The Task App is an HTTP service (often deployed on Modal) that exposes:
+    - Health: GET /health
+      • Requires header X-API-Key (when ENVIRONMENT_API_KEY is configured)
+      • Returns { healthy: true }
+    - Environment lifecycle:
+      • POST /env/{env_name}/initialize → { env_id, observation }
+      • POST /env/{env_name}/step      → { observation, reward, done, info }
+      • POST /env/{env_name}/terminate → { ok: true }
+    - Rollout (optional, unified schema):
+      • POST /rollout → { run_id, trajectories[], metrics, ... }
+    - Proxy (optional):
+      • POST /proxy/v1/chat/completions (for direct OpenAI calls from Task App)
+    """
+
+    health: str = "/health"
+    rollout: str = "/rollout"
+    proxy_chat_completions: str = "/proxy/v1/chat/completions"
+    env_initialize: str = "/env/{env_name}/initialize"
+    env_step: str = "/env/{env_name}/step"
+    env_terminate: str = "/env/{env_name}/terminate"
+
+
+@dataclass(frozen=True)
+class TaskAppContract:
+    """Requirements and expectations for a Task App used by RL trainers.
+
+    - Auth: ENVIRONMENT_API_KEY must be set in the Task App environment; requests include X-API-Key.
+    - Health: /health returns 200 and JSON; may verify X-API-Key header.
+    - Env API: initialize/step/terminate are present for the target env (e.g., CrafterClassic).
+    - Rollout API: optional; provides a single-call rollout for convenience/testing.
+    - Inference routing: policy config passes an inference_url (Synth backend or OpenAI proxy).
+    - URL: base must be reachable via HTTPS and should be under .modal.run in production.
+    """
+
+    base_url: str
+    env_name: Optional[str] = None
+    requires_api_key_header: bool = True
+
+
+# --- Unified rollout schema used by Task App services and SDK utilities ---
+
+class RolloutEnvSpec(BaseModel):
+    env_id: Optional[str] = None
+    env_name: Optional[str] = None
+    config: Dict[str, Any] = {}
+    seed: Optional[int] = None
+
+
+class RolloutPolicySpec(BaseModel):
+    policy_id: Optional[str] = None
+    policy_name: Optional[str] = None
+    config: Dict[str, Any] = {}
+
+
+class RolloutRecordConfig(BaseModel):
+    trajectories: bool = True
+    logprobs: bool = False
+    value: bool = False
+
+
+class RolloutSafetyConfig(BaseModel):
+    max_ops: int = 100000
+    max_time_s: float = 3600.0
+
+
+class RolloutRequest(BaseModel):
+    run_id: str
+    env: RolloutEnvSpec
+    policy: RolloutPolicySpec
+    ops: List[Dict[str, Any]] | List[str]
+    record: RolloutRecordConfig = RolloutRecordConfig()
+    on_done: str = "reset"
+    safety: RolloutSafetyConfig = RolloutSafetyConfig()
+    training_session_id: Optional[str] = None
+    synth_base_url: Optional[str] = None
+
+
+class RolloutStep(BaseModel):
+    obs: Dict[str, Any]
+    tool_calls: List[Dict[str, Any]]
+    reward: Optional[float] = None
+    done: bool = False
+    truncated: Optional[bool] = None
+    info: Optional[Dict[str, Any]] = None
+
+
+class RolloutTrajectory(BaseModel):
+    env_id: str
+    policy_id: str
+    steps: List[RolloutStep]
+    final: Optional[Dict[str, Any]] = None
+    length: int
+
+
+class RolloutMetrics(BaseModel):
+    episode_returns: List[float]
+    mean_return: float
+    num_steps: int
+    num_episodes: int = 0
+
+
+class RolloutResponse(BaseModel):
+    run_id: str
+    trajectories: List[RolloutTrajectory]
+    branches: Dict[str, List[str]] = {}
+    metrics: RolloutMetrics
+    aborted: bool = False
+    ops_executed: int = 0
+

synth_ai/task/health.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+import aiohttp
+
+
+async def task_app_health(task_app_url: str) -> Dict[str, Any]:
+    """Probe a Task App base URL for basic reachability.
+
+    Behavior:
+    - Try HEAD first (follows redirects)
+    - Fallback to GET if HEAD is unsupported
+    - Returns {ok: bool, status?: int, error?: str}
+    """
+    try:
+        async with aiohttp.ClientSession() as session:
+            async with session.head(task_app_url, allow_redirects=True) as r:
+                if 200 <= r.status < 400:
+                    return {"ok": True, "status": r.status}
+        async with aiohttp.ClientSession() as session:
+            async with session.get(task_app_url, allow_redirects=True) as r2:
+                if 200 <= r2.status < 400:
+                    return {"ok": True, "status": r2.status}
+        return {"ok": False, "status": None}
+    except Exception as e:
+        return {"ok": False, "error": f"{type(e).__name__}: {e}"}
+
+

synth_ai/task/validators.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+
+def validate_task_app_url(url: str, *, name: str = "TASK_APP_BASE_URL") -> None:
+    """Validate a Task App base URL (scheme + host present)."""
+
+    p = urlparse(url)
+    if p.scheme not in ("http", "https") or not p.netloc:
+        raise ValueError(f"Invalid {name}: malformed: {url}")
+

synth_ai/tracing_v3/hooks.py

@@ -200,7 +200,9 @@ def create_default_hooks() -> HookManager:
 
     # Example: Log session starts - useful for debugging and monitoring
     async def log_session_start(session_id: str, metadata: dict[str, Any]):
-        print(f"Session started: {session_id}")
+        import os
+        if os.getenv("SYNTH_TRACE_VERBOSE", "0") in ("1", "true", "True"):
+            print(f"Session started: {session_id}")
 
     # Example: Validate events before recording - ensures data quality
     def validate_event(event_obj: BaseEvent) -> bool:

synth_ai/tracing_v3/session_tracer.py

@@ -107,6 +107,10 @@ class SessionTracer:
             if self.auto_save and self.db is None:
                 await self.initialize()
 
+            # Ensure session row exists for incremental writes
+            if self.db:
+                await self.db.ensure_session(session_id, created_at=self._current_trace.created_at, metadata=metadata or {})
+
             # Trigger hooks
             await self.hooks.trigger(
                 "session_start", session_id=session_id, metadata=metadata or {}
@@ -152,6 +156,17 @@ class SessionTracer:
             "timestep_start", step=step, session_id=self._current_trace.session_id
         )
 
+        # Ensure timestep row exists in DB for incremental linkage
+        if self.db:
+            await self.db.ensure_timestep(
+                self._current_trace.session_id,
+                step_id=step.step_id,
+                step_index=step.step_index,
+                turn_number=turn_number,
+                started_at=step.timestamp,
+                metadata=metadata or {},
+            )
+
         return step
 
     async def end_timestep(self, step_id: str | None = None):
@@ -180,7 +195,7 @@ class SessionTracer:
         if step == self._current_step:
             self._current_step = None
 
-    async def record_event(self, event: BaseEvent):
+    async def record_event(self, event: BaseEvent) -> int | None:
         """Record an event.
 
         Args:
@@ -201,6 +216,46 @@ class SessionTracer:
         if self._current_step:
             self._current_step.events.append(event)
 
+        # Persist incrementally if DB is available; return DB event id
+        if self.db:
+            timestep_db_id = None
+            if self._current_step:
+                # ensure timestep exists and get id
+                timestep_db_id = await self.db.ensure_timestep(
+                    self._current_trace.session_id,
+                    step_id=self._current_step.step_id,
+                    step_index=self._current_step.step_index,
+                    turn_number=self._current_step.turn_number,
+                    started_at=self._current_step.timestamp,
+                    completed_at=self._current_step.completed_at,
+                    metadata=self._current_step.step_metadata,
+                )
+            event_id = await self.db.insert_event_row(
+                self._current_trace.session_id,
+                timestep_db_id=timestep_db_id,
+                event=event,
+            )
+            # Auto-insert an event reward if EnvironmentEvent carries reward
+            try:
+                from .abstractions import EnvironmentEvent  # local import to avoid cycles
+
+                if isinstance(event, EnvironmentEvent) and event.reward is not None:
+                    await self.record_event_reward(
+                        event_id=event_id,
+                        message_id=None,
+                        turn_number=self._current_step.turn_number if self._current_step else None,
+                        reward_value=float(event.reward),
+                        reward_type="sparse",
+                        key=None,
+                        annotation=getattr(event, "event_metadata", None),
+                        source="environment",
+                    )
+            except Exception:
+                # Do not fail tracing if reward recording fails
+                pass
+            return event_id
+        return None
+
     async def record_message(
         self,
         content: str,
@@ -208,7 +263,7 @@ class SessionTracer:
         event_time: float | None = None,
         message_time: int | None = None,
         metadata: dict[str, Any] | None = None,
-    ):
+    ) -> int | None:
         """Record a message.
 
         Args:
@@ -242,6 +297,31 @@ class SessionTracer:
         if self._current_step:
             self._current_step.markov_blanket_messages.append(msg)
 
+        # Persist incrementally and return DB message id
+        if self.db:
+            timestep_db_id = None
+            if self._current_step:
+                timestep_db_id = await self.db.ensure_timestep(
+                    self._current_trace.session_id,
+                    step_id=self._current_step.step_id,
+                    step_index=self._current_step.step_index,
+                    turn_number=self._current_step.turn_number,
+                    started_at=self._current_step.timestamp,
+                    completed_at=self._current_step.completed_at,
+                    metadata=self._current_step.step_metadata,
+                )
+            message_id = await self.db.insert_message_row(
+                self._current_trace.session_id,
+                timestep_db_id=timestep_db_id,
+                message_type=message_type,
+                content=content,
+                event_time=msg.time_record.event_time,
+                message_time=msg.time_record.message_time,
+                metadata=msg.metadata,
+            )
+            return message_id
+        return None
+
     async def end_session(self, save: bool = None) -> SessionTrace:
         """End the current session.
 
@@ -341,3 +421,44 @@ class SessionTracer:
         if self.db:
             await self.db.close()
             self.db = None
+
+    # -------------------------------
+    # Reward recording helpers
+    # -------------------------------
+
+    async def record_outcome_reward(self, *, total_reward: int, achievements_count: int, total_steps: int) -> int | None:
+        """Record an episode-level outcome reward for the current session."""
+        if self._current_trace is None:
+            raise RuntimeError("No active session")
+        if self.db is None:
+            await self.initialize()
+        if self.db:
+            return await self.db.insert_outcome_reward(
+                self._current_trace.session_id,
+                total_reward=total_reward,
+                achievements_count=achievements_count,
+                total_steps=total_steps,
+            )
+        return None
+
+    # StepMetrics removed in favor of event_rewards; use record_event_reward for per-turn shaped values
+
+    async def record_event_reward(self, *, event_id: int, message_id: int | None = None, turn_number: int | None = None, reward_value: float = 0.0, reward_type: str | None = None, key: str | None = None, annotation: dict[str, Any] | None = None, source: str | None = None) -> int | None:
+        """Record a first-class event-level reward with optional annotations."""
+        if self._current_trace is None:
+            raise RuntimeError("No active session")
+        if self.db is None:
+            await self.initialize()
+        if self.db:
+            return await self.db.insert_event_reward(
+                self._current_trace.session_id,
+                event_id=event_id,
+                message_id=message_id,
+                turn_number=turn_number,
+                reward_value=reward_value,
+                reward_type=reward_type,
+                key=key,
+                annotation=annotation,
+                source=source,
+            )
+        return None