synth-ai 0.2.9.dev7__py3-none-any.whl → 0.2.10__py3-none-any.whl

synth_ai/task/json.py

@@ -1,9 +1,9 @@
-from __future__ import annotations
-
 """Shared JSON sanitisation helpers for Task Apps."""
 
+from __future__ import annotations
+
 from collections.abc import Mapping, Sequence
-from dataclasses import is_dataclass, asdict
+from dataclasses import asdict, is_dataclass
 from enum import Enum
 from typing import Any
 
@@ -13,13 +13,19 @@ except Exception:  # pragma: no cover - handled at runtime
     _np = None  # type: ignore
 
 
-def _mask_numpy_array(arr: "_np.ndarray") -> str:
+def _mask_numpy_array(arr: Any) -> str:
     shape = getattr(arr, "shape", None)
     dtype = getattr(arr, "dtype", None)
     return f"<ndarray shape={shape} dtype={dtype}>"
 
 
-def to_jsonable(value: Any) -> Any:
+def to_jsonable(
+    value: Any,
+    *,
+    _visited: set[int] | None = None,
+    _depth: int = 0,
+    _max_depth: int = 32,
+) -> Any:
     """Convert `value` into structures compatible with JSON serialisation.
 
     - numpy scalars are converted to their Python counterparts
@@ -29,25 +35,33 @@ def to_jsonable(value: Any) -> Any:
     - non-serialisable objects fall back to `repr`
     """
 
-    if value is None or isinstance(value, (str, bool, int, float)):
+    if _visited is None:
+        _visited = set()
+
+    if _depth > _max_depth:
+        return f"<max_depth type={type(value).__name__}>"
+
+    if value is None or isinstance(value, str | bool | int | float):
         return value
 
     # numpy scalars / arrays
     if _np is not None:
-        if isinstance(value, (_np.integer,)):
+        if isinstance(value, _np.integer):
             return int(value)
-        if isinstance(value, (_np.floating,)):
+        if isinstance(value, _np.floating):
             return float(value)
-        if isinstance(value, (_np.bool_,)):
+        if isinstance(value, _np.bool_):
             return bool(value)
-        if isinstance(value, (_np.ndarray,)):
+        if isinstance(value, _np.ndarray):
             return _mask_numpy_array(value)
 
     if isinstance(value, Enum):
-        return to_jsonable(value.value)
+        return to_jsonable(value.value, _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth)
 
     if is_dataclass(value):
-        return to_jsonable(asdict(value))
+        return to_jsonable(
+            asdict(value), _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth
+        )
 
     # pydantic BaseModel / attrs objects
     for attr in ("model_dump", "dict", "to_dict", "to_json"):
@@ -56,21 +70,42 @@ def to_jsonable(value: Any) -> Any:
                 dumped = getattr(value, attr)()  # type: ignore[misc]
             except TypeError:
                 dumped = getattr(value, attr)(exclude_none=False)  # pragma: no cover
-            return to_jsonable(dumped)
-
-    if isinstance(value, Mapping):
-        return {str(k): to_jsonable(v) for k, v in value.items()}
+            return to_jsonable(
+                dumped, _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth
+            )
 
-    if isinstance(value, (set, tuple)):
-        return [to_jsonable(v) for v in value]
+    obj_id = id(value)
+    if obj_id in _visited:
+        return f"<circular type={type(value).__name__}>"
 
-    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
-        return [to_jsonable(v) for v in value]
-
-    if isinstance(value, (bytes, bytearray)):
+    if isinstance(value, Mapping):
+        _visited.add(obj_id)
+        return {
+            str(k): to_jsonable(v, _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth)
+            for k, v in value.items()
+        }
+
+    if isinstance(value, set | tuple):
+        _visited.add(obj_id)
+        return [
+            to_jsonable(v, _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth)
+            for v in value
+        ]
+
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+        _visited.add(obj_id)
+        return [
+            to_jsonable(v, _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth)
+            for v in value
+        ]
+
+    if isinstance(value, bytes | bytearray):
         return f"<bytes len={len(value)}>"
 
     if hasattr(value, "__dict__"):
-        return to_jsonable(vars(value))
+        _visited.add(obj_id)
+        return to_jsonable(
+            vars(value), _visited=_visited, _depth=_depth + 1, _max_depth=_max_depth
+        )
 
     return repr(value)

synth_ai/task/proxy.py

@@ -1,14 +1,14 @@
-from __future__ import annotations
-
 """Shared helpers for Task App proxy endpoints (OpenAI, Groq, etc.)."""
 
+from __future__ import annotations
+
 import copy
 import json
 import re
-from typing import Any, Iterable, List, Tuple
-
+from collections.abc import Iterable
+from typing import Any
 
-INTERACT_TOOL_SCHEMA: List[dict[str, Any]] = [
+INTERACT_TOOL_SCHEMA: list[dict[str, Any]] = [
     {
         "type": "function",
         "function": {
@@ -80,9 +80,13 @@ def prepare_for_groq(model: str | None, payload: dict[str, Any]) -> dict[str, An
 
     sanitized = prepare_for_openai(model, payload)
     # Groq supports `max_tokens`; prefer their native parameter when present
-    if model and "gpt-5" not in (model or ""):
-        if "max_completion_tokens" in sanitized and "max_tokens" not in payload:
-            sanitized["max_tokens"] = sanitized.pop("max_completion_tokens")
+    if (
+        model
+        and "gpt-5" not in model
+        and "max_completion_tokens" in sanitized
+        and "max_tokens" not in payload
+    ):
+        sanitized["max_tokens"] = sanitized.pop("max_completion_tokens")
     return sanitized
 
 
@@ -146,7 +150,7 @@ def _parse_actions_from_json_candidate(candidate: Any) -> tuple[list[str], str]:
     return actions, reasoning
 
 
-def parse_tool_call_from_text(text: str) -> Tuple[list[str], str]:
+def parse_tool_call_from_text(text: str) -> tuple[list[str], str]:
     """Derive tool-call actions and reasoning from assistant text."""
 
     text = (text or "").strip()

synth_ai/task/rubrics.py

@@ -1,10 +1,11 @@
-from __future__ import annotations
-
 """Rubric schema, loading, and scoring helpers for Task Apps."""
 
+from __future__ import annotations
+
 import json
+from collections.abc import Iterable
 from pathlib import Path
-from typing import Any, Dict, Iterable, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field, field_validator
 
@@ -48,14 +49,14 @@ class Rubric(BaseModel):
         return criteria
 
 
-def _load_text(source: str) -> tuple[str, Optional[str]]:
+def _load_text(source: str) -> tuple[str, str | None]:
     path = Path(source)
     if path.exists():
         return path.read_text(encoding="utf-8"), path.suffix.lower()
     return source, None
 
 
-def _parse_structured(text: str, suffix: Optional[str]) -> Dict[str, Any]:
+def _parse_structured(text: str, suffix: str | None) -> dict[str, Any]:
     text = text.strip()
     if not text:
         raise ValueError("Rubric source is empty")
@@ -66,7 +67,7 @@ def _parse_structured(text: str, suffix: Optional[str]) -> Dict[str, Any]:
             raise RuntimeError("PyYAML is required to load YAML rubrics") from exc
         data = yaml.safe_load(text)
         if not isinstance(data, dict):
-            raise ValueError("Rubric YAML must produce a mapping")
+            raise ValueError("Rubric YAML must produce a mapping") from None
         return data
     if text.startswith("{"):
         return json.loads(text)
@@ -85,7 +86,7 @@ def _parse_structured(text: str, suffix: Optional[str]) -> Dict[str, Any]:
             raise RuntimeError("PyYAML is required to load rubric text") from exc
         data = yaml.safe_load(text)
         if not isinstance(data, dict):
-            raise ValueError("Rubric text must decode to a mapping")
+            raise ValueError("Rubric text must decode to a mapping") from None
         return data
 
 
@@ -148,7 +149,7 @@ def blend_rubrics(base: Rubric | None, override: Rubric | None) -> Rubric | None
     )
 
 
-def _as_float(value: Any) -> Optional[float]:
+def _as_float(value: Any) -> float | None:
     try:
         return float(value)
     except Exception:
@@ -156,11 +157,11 @@ def _as_float(value: Any) -> Optional[float]:
 
 
 def _score(
-    criteria: Iterable[Criterion], values: Dict[str, float], aggregation: str
-) -> Dict[str, Any]:
+    criteria: Iterable[Criterion], values: dict[str, float], aggregation: str
+) -> dict[str, Any]:
     if aggregation == "inherit":
         aggregation = "weighted_sum"
-    per_criterion: Dict[str, Dict[str, Any]] = {}
+    per_criterion: dict[str, dict[str, Any]] = {}
     total = 0.0
     total_weight = 0.0
     for criterion in criteria:
@@ -188,10 +189,10 @@ def _score(
 
 def score_events_against_rubric(
     events: list[dict[str, Any]], rubric: Rubric | None
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     if rubric is None:
         return {"aggregation": "none", "score": None, "per_criterion": {}}
-    values: Dict[str, float] = {}
+    values: dict[str, float] = {}
     for event in events or []:
         if not isinstance(event, dict):
             continue
@@ -202,10 +203,10 @@ def score_events_against_rubric(
     return _score(rubric.criteria, values, rubric.aggregation)
 
 
-def score_outcome_against_rubric(outcome: dict[str, Any], rubric: Rubric | None) -> Dict[str, Any]:
+def score_outcome_against_rubric(outcome: dict[str, Any], rubric: Rubric | None) -> dict[str, Any]:
     if rubric is None:
         return {"aggregation": "none", "score": None, "per_criterion": {}}
-    values: Dict[str, float] = {}
+    values: dict[str, float] = {}
     if isinstance(outcome, dict):
         candidates = (
             outcome.get("criteria") if isinstance(outcome.get("criteria"), dict) else outcome

synth_ai/task/server.py

@@ -1,39 +1,34 @@
-from __future__ import annotations
-
 """FastAPI scaffolding for Task Apps (local dev + deployment)."""
 
+from __future__ import annotations
+
 import asyncio
 import inspect
 import os
+from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Awaitable, Callable, Iterable, Mapping, MutableMapping, Sequence
+from typing import Any
 
 import httpx
 from fastapi import APIRouter, Depends, FastAPI, Query, Request
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
 from starlette.middleware import Middleware
 
-from .auth import (
-    is_api_key_header_authorized,
-    normalize_environment_api_key,
-    require_api_key_dependency,
-)
+from .auth import normalize_environment_api_key, require_api_key_dependency
 from .contracts import RolloutRequest, RolloutResponse, TaskInfo
 from .datasets import TaskDatasetRegistry
 from .errors import http_exception
 from .json import to_jsonable
 from .proxy import (
+    inject_system_hint,
     prepare_for_groq,
     prepare_for_openai,
-    inject_system_hint,
     synthesize_tool_call_if_missing,
 )
 from .rubrics import Rubric
 from .vendors import get_groq_key_or_503, get_openai_key_or_503, normalize_vendor_keys
 
-
 TasksetDescriptor = Callable[[], Mapping[str, Any] | Awaitable[Mapping[str, Any]]]
 InstanceProvider = Callable[[Sequence[int]], Iterable[TaskInfo] | Awaitable[Iterable[TaskInfo]]]
 RolloutExecutor = Callable[[RolloutRequest, Request], Any | Awaitable[Any]]
@@ -81,7 +76,7 @@ class TaskAppConfig:
     startup_hooks: Sequence[Callable[[], None | Awaitable[None]]] = field(default_factory=tuple)
     shutdown_hooks: Sequence[Callable[[], None | Awaitable[None]]] = field(default_factory=tuple)
 
-    def clone(self) -> "TaskAppConfig":
+    def clone(self) -> TaskAppConfig:
         """Return a shallow copy safe to mutate when wiring the app."""
 
         return TaskAppConfig(
@@ -299,6 +294,11 @@ def create_task_app(config: TaskAppConfig) -> FastAPI:
             }
         )
 
+    @app.post("/done", dependencies=[Depends(auth_dependency)])
+    async def done() -> Mapping[str, Any]:
+        # Coordination endpoint for tests and automation; indicates app is reachable
+        return to_jsonable({"ok": True, "service": cfg.app_id})
+
     @app.get("/info", dependencies=[Depends(auth_dependency)])
     async def info() -> Mapping[str, Any]:
         dataset_meta = cfg.base_task_info.dataset

synth_ai/task/tracing_utils.py

@@ -1,11 +1,11 @@
-from __future__ import annotations
-
 """Utilities for wiring tracing_v3 into task apps."""
 
+from __future__ import annotations
+
 import os
-import time
+from collections.abc import Callable
 from pathlib import Path
-from typing import Any, Callable
+from typing import Any
 
 
 def tracing_env_enabled(default: bool = False) -> bool:

synth_ai/task/vendors.py

@@ -1,9 +1,8 @@
-from __future__ import annotations
-
 """Vendor API key helpers shared by Task Apps."""
 
+from __future__ import annotations
+
 import os
-from typing import Optional
 
 from .errors import http_exception
 
@@ -20,7 +19,7 @@ def _mask(value: str, *, prefix: int = 4) -> str:
     return f"{visible}{'…' if len(value) > prefix else ''}"
 
 
-def _normalize_single(key: str) -> Optional[str]:
+def _normalize_single(key: str) -> str | None:
     direct = os.getenv(key)
     if direct:
         return direct
@@ -37,10 +36,10 @@ def _normalize_single(key: str) -> Optional[str]:
     return None
 
 
-def normalize_vendor_keys() -> dict[str, Optional[str]]:
+def normalize_vendor_keys() -> dict[str, str | None]:
     """Normalise known vendor keys from dev fallbacks and return the mapping."""
 
-    resolved: dict[str, Optional[str]] = {}
+    resolved: dict[str, str | None] = {}
     for key in _VENDOR_KEYS:
         resolved[key] = _normalize_single(key)
     return resolved

synth_ai/tracing_v3/__init__.py

@@ -75,6 +75,7 @@ from .abstractions import (
     EnvironmentEvent,
     RuntimeEvent,
     SessionEventMarkovBlanketMessage,
+    SessionMessageContent,
     SessionTimeStep,
     SessionTrace,
     TimeRecord,
@@ -90,6 +91,7 @@ __all__ = [
     "RuntimeEvent",
     "EnvironmentEvent",
     "SessionEventMarkovBlanketMessage",
+    "SessionMessageContent",
     "TimeRecord",
     "TursoConfig",
 ]

synth_ai/tracing_v3/abstractions.py

@@ -37,7 +37,7 @@ Concepts:
 from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import Any
 
 from .lm_call_record_abstractions import LLMCallRecord
@@ -61,6 +61,23 @@ class TimeRecord:
     message_time: int | None = None
 
 
+@dataclass(frozen=True)
+class SessionMessageContent:
+    """Normalized payload stored alongside session messages."""
+
+    text: str | None = None
+    json_payload: str | None = None
+
+    def as_text(self) -> str:
+        return self.text or (self.json_payload or "")
+
+    def has_json(self) -> bool:
+        return self.json_payload is not None
+
+    def __str__(self) -> str:  # pragma: no cover - convenience for logging
+        return self.as_text()
+
+
 @dataclass
 class SessionEventMarkovBlanketMessage:
     """Message crossing Markov blanket boundaries between systems in a session.
@@ -97,7 +114,7 @@ class SessionEventMarkovBlanketMessage:
                   - 'causal_influence': Direction of causal flow
     """
 
-    content: str
+    content: SessionMessageContent
     message_type: str
     time_record: TimeRecord
     metadata: dict[str, Any] = field(default_factory=dict)
@@ -232,7 +249,7 @@ class SessionTimeStep:
 
     step_id: str = ""
     step_index: int = 0
-    timestamp: datetime = field(default_factory=datetime.utcnow)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
     turn_number: int | None = None
     events: list[BaseEvent] = field(default_factory=list)
     markov_blanket_messages: list[SessionEventMarkovBlanketMessage] = field(default_factory=list)
@@ -266,7 +283,7 @@ class SessionTrace:
     """
 
     session_id: str = ""
-    created_at: datetime = field(default_factory=datetime.utcnow)
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
     session_time_steps: list[SessionTimeStep] = field(default_factory=list)
     event_history: list[BaseEvent] = field(default_factory=list)
     markov_blanket_message_history: list[SessionEventMarkovBlanketMessage] = field(

synth_ai/tracing_v3/decorators.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """Async-aware decorators for tracing v3.
 
 This module provides decorators and context management utilities for the tracing
@@ -24,6 +22,8 @@ The decorators support both sync and async functions where appropriate,
 though async is preferred for consistency with the rest of the system.
 """
 
+from __future__ import annotations
+
 import asyncio
 import contextvars
 import functools
@@ -37,12 +37,8 @@ from .utils import calculate_cost, detect_provider
 # Context variables for session and turn tracking
 # These variables automatically propagate across async call boundaries,
 # allowing deeply nested code to access tracing context without explicit passing
-_session_id_ctx: contextvars.ContextVar[str | None] = contextvars.ContextVar(
-    "session_id", default=None
-)
-_turn_number_ctx: contextvars.ContextVar[int | None] = contextvars.ContextVar(
-    "turn_number", default=None
-)
+_session_id_ctx: contextvars.ContextVar[str | None] = contextvars.ContextVar("session_id")
+_turn_number_ctx: contextvars.ContextVar[int | None] = contextvars.ContextVar("turn_number")
 _session_tracer_ctx: contextvars.ContextVar[Any | None] = contextvars.ContextVar(
     "session_tracer", default=None
 )
@@ -120,7 +116,9 @@ def with_session(require: bool = True):
             async def async_wrapper(*args, **kwargs):
                 session_id = get_session_id()
                 if require and session_id is None:
-                    raise RuntimeError(f"No active session for {fn.__name__}")
+                    raise RuntimeError(
+                        f"No active session for {getattr(fn, '__name__', 'unknown')}"
+                    )
                 return await fn(*args, **kwargs)
 
             return async_wrapper
@@ -130,7 +128,9 @@ def with_session(require: bool = True):
             def sync_wrapper(*args, **kwargs):
                 session_id = get_session_id()
                 if require and session_id is None:
-                    raise RuntimeError(f"No active session for {fn.__name__}")
+                    raise RuntimeError(
+                        f"No active session for {getattr(fn, '__name__', 'unknown')}"
+                    )
                 return fn(*args, **kwargs)
 
             return sync_wrapper
@@ -139,7 +139,7 @@ def with_session(require: bool = True):
 
 
 def trace_llm_call(
-    model_name: str = None,
+    model_name: str | None = None,
     system_id: str = "llm",
     extract_tokens: bool = True,
     extract_cost: bool = True,
@@ -209,14 +209,16 @@ def trace_llm_call(
                         input_tokens=input_tokens,
                         output_tokens=output_tokens,
                         total_tokens=total_tokens,
-                        cost_usd=calculate_cost(actual_model, input_tokens or 0, output_tokens or 0)
+                        cost_usd=calculate_cost(
+                            actual_model or "unknown", input_tokens or 0, output_tokens or 0
+                        )
                         if extract_cost
                         else None,
                         latency_ms=latency_ms,
                         system_state_before=system_state_before,
                         system_state_after=kwargs.get("state_after", {}),
                         metadata={
-                            "function": fn.__name__,
+                            "function": getattr(fn, "__name__", "unknown"),
                             "step_id": kwargs.get("step_id"),
                         },
                     )
@@ -235,7 +237,7 @@ def trace_llm_call(
                             provider=detect_provider(model_name),
                             latency_ms=int((time.time() - start_time) * 1000),
                             metadata={
-                                "function": fn.__name__,
+                                "function": getattr(fn, "__name__", "unknown"),
                                 "error": str(e),
                                 "error_type": type(e).__name__,
                             },
@@ -250,7 +252,7 @@ def trace_llm_call(
     return decorator
 
 
-def trace_method(event_type: str = "runtime", system_id: str = None):
+def trace_method(event_type: str = "runtime", system_id: str | None = None):
     """Generic method tracing decorator.
 
     Traces any method call by recording it as a RuntimeEvent. Supports both
@@ -289,7 +291,7 @@ def trace_method(event_type: str = "runtime", system_id: str = None):
                     time_record=TimeRecord(event_time=time.time()),
                     actions=[],  # Can be overridden in metadata
                     metadata={
-                        "method": fn.__name__,
+                        "method": getattr(fn, "__name__", "unknown"),
                         "args": str(args)[:100],  # Truncate for safety
                         "step_id": kwargs.get("step_id"),
                     },

synth_ai/tracing_v3/hooks.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """Hook system for extending tracing functionality.
 
 The hook system provides a flexible way to extend the tracing system without
@@ -34,6 +32,8 @@ Common Use Cases:
 - Custom filtering and sampling
 """
 
+from __future__ import annotations
+
 import asyncio
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -89,9 +89,9 @@ class HookManager:
         self,
         event: str,
         callback: Callable,
-        name: str = None,
+        name: str | None = None,
         priority: int = 0,
-        event_types: list[str] = None,
+        event_types: list[str] | None = None,
     ) -> Hook:
         """Register a new hook.
 
@@ -115,7 +115,7 @@ class HookManager:
             raise ValueError(f"Unknown hook event: {event}")
 
         hook = Hook(
-            name=name or callback.__name__,
+            name=name or getattr(callback, "__name__", "unknown"),
             callback=callback,
             event_types=event_types,
             priority=priority,

synth_ai/tracing_v3/llm_call_record_helpers.py

@@ -5,10 +5,9 @@ format and compute aggregates from call records.
 """
 
 import uuid
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import Any
 
-from synth_ai.lm.vendors.base import BaseLMResponse
 from synth_ai.tracing_v3.lm_call_record_abstractions import (
     LLMCallRecord,
     LLMChunk,
@@ -18,6 +17,7 @@ from synth_ai.tracing_v3.lm_call_record_abstractions import (
     LLMUsage,
     ToolCallSpec,
 )
+from synth_ai.v0.lm.vendors.base import BaseLMResponse
 
 
 def create_llm_call_record_from_response(
@@ -161,8 +161,8 @@ def create_llm_call_record_from_response(
         api_type=api_type,
         provider=provider,
         model_name=model_name,
-        started_at=started_at or datetime.utcnow(),
-        completed_at=completed_at or datetime.utcnow(),
+        started_at=started_at or datetime.now(UTC),
+        completed_at=completed_at or datetime.now(UTC),
         latency_ms=latency_ms,
         request_params=params,
         input_messages=input_messages,
@@ -322,8 +322,8 @@ def create_llm_call_record_from_streaming(
         api_type="responses",  # Streaming typically from Responses API
         provider=provider,
         model_name=model_name,
-        started_at=started_at or datetime.utcnow(),
-        completed_at=completed_at or datetime.utcnow(),
+        started_at=started_at or datetime.now(UTC),
+        completed_at=completed_at or datetime.now(UTC),
         latency_ms=latency_ms,
         request_params=params,
         input_messages=input_messages,