evolvingmachines-evolve 0.0.55.dev1355__py3-none-any.whl

evolve/results.py

@@ -0,0 +1,315 @@
+"""Result types for Evolve SDK."""
+
+from dataclasses import dataclass, field
+import math
+from typing import Any, Dict, List, Literal, Optional, Union
+
+
+@dataclass
+class CheckpointInfo:
+    """Checkpoint metadata.
+
+    Matches TypeScript SDK's CheckpointInfo for exact parity.
+    Evidence: sdk-ts/src/types.ts lines 613-634
+
+    Attributes:
+        id: Checkpoint ID — pass as `from_checkpoint` to restore
+        hash: SHA-256 of tar.gz — integrity verification
+        tag: Session tag at checkpoint time — lineage tracking
+        timestamp: ISO 8601 timestamp
+        size_bytes: Archive size in bytes
+        agent_type: Agent type that produced this checkpoint
+        model: Model that produced this checkpoint
+        workspace_mode: Workspace mode used when checkpoint was created
+        parent_id: Parent checkpoint ID — lineage tracking
+        comment: User-provided label for this checkpoint
+    """
+    id: str
+    hash: str
+    tag: str
+    timestamp: str
+    size_bytes: Optional[int] = None
+    agent_type: Optional[str] = None
+    model: Optional[str] = None
+    workspace_mode: Optional[str] = None
+    parent_id: Optional[str] = None
+    comment: Optional[str] = None
+
+
+@dataclass
+class AgentResponse:
+    """Response from agent execution.
+
+    Matches TypeScript SDK's AgentResponse for exact parity.
+
+    Attributes:
+        sandbox_id: Sandbox ID
+        session_id: Dashboard session ID for trace/replay APIs, when known
+        browser: Managed browser runtime info, when a remote browser is configured
+        run_id: Run ID for spend/cost attribution (present for run(), None for execute_command())
+        exit_code: Command exit code
+        stdout: Standard output
+        stderr: Standard error
+        checkpoint: Checkpoint info if storage configured and run succeeded
+    """
+    sandbox_id: str
+    exit_code: int
+    stdout: str
+    stderr: str
+    session_id: Optional[str] = None
+    browser: Optional[Dict[str, str]] = None
+    run_id: Optional[str] = None
+    checkpoint: Optional[CheckpointInfo] = None
+
+
+# Backward compatibility alias
+ExecuteResult = AgentResponse
+
+
+@dataclass
+class SessionStatus:
+    """Runtime status snapshot for sandbox and agent."""
+    sandbox_id: Optional[str]
+    sandbox: str
+    agent: str
+    active_process_id: Optional[str]
+    has_run: bool
+    timestamp: str
+    browser: Optional[Dict[str, str]] = None
+
+
+@dataclass
+class OutputResult:
+    """Result from get_output_files() with optional schema validation.
+
+    Matches TypeScript SDK's OutputResult<T> for exact parity.
+    Evidence: sdk-ts/src/types.ts lines 258-268
+
+    Attributes:
+        files: Output files from output/ folder
+        data: Parsed and validated result.json data (None if no schema or validation failed)
+        error: Validation or parse error message, if any
+        raw_data: Raw result.json string when parse or validation failed (for debugging)
+    """
+    files: Dict[str, Union[str, bytes]] = field(default_factory=dict)
+    data: Optional[Any] = None
+    error: Optional[str] = None
+    raw_data: Optional[str] = None
+
+
+@dataclass
+class RunCost:
+    """Cost breakdown for a single run() invocation.
+
+    Matches TypeScript SDK's RunCost for exact parity.
+
+    Attributes:
+        run_id: Run ID matching AgentResponse.run_id
+        index: 1-based chronological position in session
+        cost: Total cost in USD as billed to your Evolve account
+        tokens: Token counts {'prompt': N, 'completion': N, 'cached': N}.
+            ``prompt`` INCLUDES the cached share; ``cached`` is that share,
+            absent on servers predating the field (never 0-by-default).
+        model: Model used (e.g., 'claude-opus-4-8')
+        requests: Number of LLM API requests in this run
+        as_of: ISO timestamp when this data was fetched
+        is_complete: False if recent LLM calls may still be batching (~60s delay)
+        truncated: True if spend log pagination was capped
+    """
+    run_id: str
+    index: int
+    cost: float
+    tokens: Dict[str, int]
+    model: str
+    requests: int
+    as_of: str
+    is_complete: bool
+    truncated: bool
+
+
+@dataclass
+class SessionCost:
+    """Cost breakdown for an entire agent session (all runs).
+
+    Matches TypeScript SDK's SessionCost for exact parity.
+
+    Attributes:
+        session_tag: Session tag matching get_session_tag()
+        total_cost: Total cost across all runs in USD
+        total_tokens: Aggregate token counts
+            {'prompt': N, 'completion': N, 'cached': N}. ``prompt`` INCLUDES
+            the cached share; ``cached`` is absent on servers predating it.
+        runs: Per-run breakdown, chronological order
+        as_of: ISO timestamp when this data was fetched
+        is_complete: False if session is still active or recently ended
+        truncated: True if spend log pagination was capped
+    """
+    session_tag: str
+    total_cost: float
+    total_tokens: Dict[str, int]
+    runs: List[RunCost]
+    as_of: str
+    is_complete: bool
+    truncated: bool
+
+
+@dataclass
+class UsageReading:
+    """THE ONE-HOME USAGE READING — "what has this run's meter said so far".
+
+    Money and tokens come from the SAME gateway spend-log records, so the two
+    can never describe different sets of requests. Served under the one key
+    ``usage``, with these exact keys, by the trial surfaces and the
+    managed-agents session surfaces alike — a renderer that reads one reads
+    the other unchanged. While the run is alive the platform's own poll
+    raises the numbers, so a polling reader sees them tick; once settled, the
+    settled figures replace the live ones under the same keys. The whole
+    object is None when the meter has never answered — never a fabricated
+    zero.
+
+    Attributes:
+        provisional: True while every number is a LOWER BOUND that can still
+            grow — the run is alive, or its settled lane is not yet
+            confirmed. False = settled; the reading will not move again.
+        spent_usd: Metered model spend so far, USD. None = the money was
+            never measured (a trial's ``spend_source`` lane ``assumed_cap``;
+            the token fields beside it may still carry real readings).
+        input_tokens: Prompt tokens so far, INCLUDING the cached share and
+            the cache-write share.
+        cached_input_tokens: The cached share of ``input_tokens`` (read from
+            the provider's prompt cache).
+        cache_write_tokens: The share of ``input_tokens`` WRITTEN to the
+            provider's prompt cache. Anthropic bills it at a premium above the
+            plain input price, so it is the fourth count ``spent_usd`` needs
+            to be reproducible from the tokens; providers without a
+            cache-write price report 0. None when the meter never answered —
+            and on a run settled before the platform recorded this share (an
+            older server omits the key), where the three counts beside it stay
+            real: None is never a fabricated 0.
+        output_tokens: Completion tokens so far.
+        as_of: When this reading was taken — show its age, never the figure
+            alone.
+    """
+    provisional: bool
+    spent_usd: Optional[float]
+    input_tokens: Optional[int]
+    cached_input_tokens: Optional[int]
+    cache_write_tokens: Optional[int]
+    output_tokens: Optional[int]
+    as_of: Optional[str]
+
+
+def _usage_reading_from_data(data: Any) -> Optional[UsageReading]:
+    """The wire's usage reading, defensively — the same one rule as the
+    TypeScript SDK's ``mapUsageReading``: anything malformed answers None
+    (which already means "the meter never answered"), each numeric field is
+    taken only as a real number, and ``provisional`` must be a real bool —
+    without it the reading has no statement to make."""
+    if not isinstance(data, dict):
+        return None
+    provisional = data.get('provisional')
+    if not isinstance(provisional, bool):
+        return None
+
+    def _num(value: Any) -> Optional[float]:
+        # bool is an int subclass; a stray True must never become money. And a
+        # non-finite float (json.loads admits NaN/Infinity) is not a reading —
+        # refuse it like the TS side's Number.isFinite does.
+        if not isinstance(value, (int, float)) or isinstance(value, bool):
+            return None
+        return value if math.isfinite(value) else None
+
+    as_of = data.get('as_of')
+    return UsageReading(
+        provisional=provisional,
+        spent_usd=_num(data.get('spent_usd')),
+        input_tokens=_num(data.get('input_tokens')),
+        cached_input_tokens=_num(data.get('cached_input_tokens')),
+        cache_write_tokens=_num(data.get('cache_write_tokens')),
+        output_tokens=_num(data.get('output_tokens')),
+        as_of=as_of if isinstance(as_of, str) else None,
+    )
+
+
+SessionEvent = Dict[str, Any]
+
+
+@dataclass
+class SessionInfo:
+    """Historical session metadata from the standalone sessions() client.
+
+    Matches the TypeScript sessions() surface, with snake_case field names for
+    Python transport ergonomics.
+    """
+    id: str
+    tag: str
+    agent: str
+    model: Optional[str]
+    provider: str
+    sandbox_id: Optional[str]
+    state: Literal['live', 'ended']
+    runtime_status: Literal['alive', 'dead', 'unknown']
+    cost: Optional[float]
+    created_at: str
+    ended_at: Optional[str]
+    step_count: int
+    tool_stats: Optional[Dict[str, int]]
+    #: The one-home usage reading — the SAME object, same keys, a trial
+    #: serves (see :class:`UsageReading`). None = the meter never answered
+    #: (and on servers predating the field).
+    usage: Optional[UsageReading] = None
+
+
+@dataclass
+class SessionPage:
+    """Paginated session list response from the standalone sessions() client."""
+    items: List[SessionInfo]
+    next_cursor: Optional[str]
+    has_more: bool
+
+
+@dataclass
+class SessionTranscript:
+    """One read of a session's transcript feed — the TypeScript SDK's
+    ``SessionTranscript``: the parsed events after ``since`` plus the facts
+    the feed serves around them. There is no server-side paging: one read
+    answers everything after ``since``, and ``total`` counts ALL stored
+    events, so the next delta read passes ``since=total``.
+    """
+    #: The session as the feed served it — the same shape ``get()`` returns,
+    #: so ``usage`` / ``cost`` is the run's total.
+    session: SessionInfo
+    #: The events after ``since``: what ``events()`` returns alone.
+    events: List[SessionEvent]
+    #: ALL stored events, independent of ``since``.
+    total: int
+    #: THE GATEWAY METER's per-call lines for this session (the spec's
+    #: GatewayUsageEvent, its own camelCase keys — ``call['update']['usage']``
+    #: carries ``promptTokens``, ``completionTokens``, ``cachedTokens`` and
+    #: ``costUsd``), in time order: one model call as the LiteLLM gateway
+    #: priced it, the same line a trial's trace carries in its gateway band.
+    #: Served whole on every read and beside ``events``, never inside them: a
+    #: session's ``since`` is an event COUNT, so a call line in the list would
+    #: corrupt every delta poller's cursor. The ONLY per-call tokens and money
+    #: a client may show (a harness's own ``usage`` line stays a raw record).
+    gateway_calls: List[Dict[str, Any]]
+    #: The server's write instant of each event's row, one per entry of
+    #: ``events``, index-aligned (the contract's ``SessionTranscript.storedAt``):
+    #: present on every row-served page (an empty page carries an empty list),
+    #: ``None`` when the transcript was served from its file, where no write
+    #: instant exists. It places the gateway meter's calls under the harness's
+    #: steps for harnesses whose lines carry no clock of their own (codex,
+    #: kimi, qwen); a reader that does not place calls needs nothing from it.
+    stored_at: Optional[List[str]] = None
+
+
+@dataclass
+class BrowserReplay:
+    """Browser replay metadata and Dashboard-owned access URLs."""
+    session_id: str
+    status: Literal['ready']
+    replay_url: str
+    download_url: str
+    suggested_start_seconds: Optional[float] = None
+    size_bytes: Optional[int] = None
+    ready_at: Optional[str] = None

evolve/retry.py

@@ -0,0 +1,133 @@
+"""Retry Utility for Swarm operations.
+
+Generic retry with exponential backoff.
+Works with any result type that has a status field.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Optional, TypeVar
+
+# =============================================================================
+# CONSTANTS
+# =============================================================================
+
+DEFAULT_MAX_ATTEMPTS = 3
+DEFAULT_BACKOFF_MS = 1000
+DEFAULT_BACKOFF_MULTIPLIER = 2.0
+
+# =============================================================================
+# TYPES
+# =============================================================================
+
+# TypeVar for result types (SwarmResult, ReduceResult, etc.)
+# Results must have a `status` field for default retry behavior.
+TResult = TypeVar('TResult')
+
+# Callback type for item retry events (must be defined before RetryConfig)
+OnItemRetryCallback = Callable[[int, int, str], None]  # (item_index, attempt, error)
+
+
+def _get_field(obj: Any, field: str, default: Any = None) -> Any:
+    """Get field from dict or object (duck typing helper)."""
+    if isinstance(obj, dict):
+        return obj.get(field, default)
+    return getattr(obj, field, default)
+
+
+@dataclass
+class RetryConfig:
+    """Per-item retry configuration.
+
+    Example:
+        # Basic retry on error
+        RetryConfig(max_attempts=3)
+
+        # With exponential backoff
+        RetryConfig(max_attempts=3, backoff_ms=1000, backoff_multiplier=2)
+
+        # Custom retry condition
+        RetryConfig(max_attempts=3, retry_on=lambda r: r.status == "error" or "timeout" in (r.error or ""))
+
+        # With callback
+        RetryConfig(max_attempts=3, on_item_retry=lambda i, a, e: print(f"Item {i} retry {a}: {e}"))
+
+    Args:
+        max_attempts: Maximum retry attempts (default: 3)
+        backoff_ms: Initial backoff in ms (default: 1000)
+        backoff_multiplier: Exponential backoff multiplier (default: 2)
+        retry_on: Custom retry condition (default: status == "error")
+        on_item_retry: Callback when retry occurs (item_index, attempt, error)
+    """
+    max_attempts: int = DEFAULT_MAX_ATTEMPTS
+    backoff_ms: int = DEFAULT_BACKOFF_MS
+    backoff_multiplier: float = DEFAULT_BACKOFF_MULTIPLIER
+    retry_on: Optional[Callable[[Any], bool]] = None
+    on_item_retry: Optional[OnItemRetryCallback] = None
+
+    def should_retry(self, result: Any) -> bool:
+        """Check if result should be retried."""
+        if self.retry_on is not None:
+            return self.retry_on(result)
+        # Default: retry on error status
+        return _get_field(result, 'status') == "error"
+
+
+# =============================================================================
+# RETRY LOGIC
+# =============================================================================
+
+async def execute_with_retry(
+    fn: Callable[[int], Awaitable[TResult]],
+    config: Optional[RetryConfig] = None,
+    item_index: int = 0,
+) -> TResult:
+    """Execute a function with retry and exponential backoff.
+
+    Works with any result type that has a `status` field (SwarmResult, ReduceResult, etc.).
+
+    Args:
+        fn: Async function that receives attempt number (1-based) and returns a result
+        config: Retry configuration (optional, uses defaults if not provided)
+        item_index: Item index for callback (default: 0)
+
+    Returns:
+        Result from the function
+
+    Example:
+        result = await execute_with_retry(
+            lambda attempt: self._execute_map_item(item, prompt, index, operation_id, params, timeout, attempt),
+            RetryConfig(max_attempts=3, backoff_ms=1000),
+            item_index=index,
+        )
+    """
+    resolved = config or RetryConfig()
+
+    last_result: Optional[TResult] = None
+    attempts = 0
+    backoff = resolved.backoff_ms
+
+    while attempts < resolved.max_attempts:
+        attempts += 1
+        last_result = await fn(attempts)
+
+        # Check if we should retry
+        if not resolved.should_retry(last_result):
+            return last_result
+
+        # Don't retry if we've exhausted attempts
+        if attempts >= resolved.max_attempts:
+            break
+
+        # Notify of retry via callback in config
+        if resolved.on_item_retry is not None:
+            error = _get_field(last_result, 'error') or "Unknown error"
+            resolved.on_item_retry(item_index, attempts, error)
+
+        # Wait before retrying (convert ms to seconds)
+        await asyncio.sleep(backoff / 1000)
+        backoff = backoff * resolved.backoff_multiplier
+
+    # Return last result
+    assert last_result is not None
+    return last_result

evolve/schema.py

@@ -0,0 +1,107 @@
+"""Schema utilities for Pydantic models, dataclasses, and JSON Schema.
+
+Provides unified detection, conversion, and validation for schema types.
+Uses Pydantic's TypeAdapter for dataclass support.
+"""
+
+import dataclasses
+from typing import Any, Dict, Optional
+
+
+# =============================================================================
+# DETECTION
+# =============================================================================
+
+
+def is_pydantic_model(obj: Any) -> bool:
+    """Check if object is a Pydantic model class."""
+    try:
+        from pydantic import BaseModel
+        return isinstance(obj, type) and issubclass(obj, BaseModel)
+    except ImportError:
+        return False
+
+
+def is_dataclass(obj: Any) -> bool:
+    """Check if object is a dataclass."""
+    return dataclasses.is_dataclass(obj) and isinstance(obj, type)
+
+
+def is_json_schema(obj: Any) -> bool:
+    """Check if object is a JSON Schema dict."""
+    return isinstance(obj, dict)
+
+
+# =============================================================================
+# CONVERSION
+# =============================================================================
+
+
+def to_json_schema(schema: Any) -> Optional[Dict[str, Any]]:
+    """Convert a schema to JSON Schema format.
+
+    Supports:
+    - Dict (JSON Schema) - passed through
+    - Pydantic models - uses model_json_schema()
+    - Dataclasses - uses Pydantic TypeAdapter
+
+    Args:
+        schema: Pydantic model, dataclass, or JSON Schema dict
+
+    Returns:
+        JSON Schema dict, or None if schema is None
+    """
+    if schema is None:
+        return None
+
+    if is_json_schema(schema):
+        return schema
+
+    if is_pydantic_model(schema):
+        return schema.model_json_schema()
+
+    if is_dataclass(schema):
+        from pydantic import TypeAdapter
+        return TypeAdapter(schema).json_schema()
+
+    raise TypeError(
+        f"Schema must be a Pydantic model, dataclass, or dict. "
+        f"Got {type(schema).__name__}"
+    )
+
+
+# =============================================================================
+# VALIDATION
+# =============================================================================
+
+
+def validate_and_parse(
+    raw_json: str,
+    schema: Any,
+    strict: bool = False,
+) -> Any:
+    """Validate JSON string and parse into schema type.
+
+    Args:
+        raw_json: Raw JSON string to validate
+        schema: Pydantic model or dataclass (returns instance)
+        strict: Use strict validation mode
+
+    Returns:
+        Model/dataclass instance, or None for dict schemas
+
+    Raises:
+        ValidationError: If validation fails
+    """
+    if schema is None or is_json_schema(schema):
+        # JSON Schema validation is handled by TS SDK
+        return None
+
+    if is_pydantic_model(schema):
+        return schema.model_validate_json(raw_json, strict=strict)
+
+    if is_dataclass(schema):
+        from pydantic import TypeAdapter
+        return TypeAdapter(schema).validate_json(raw_json, strict=strict)
+
+    return None