evolve-sdk 0.0.52.dev744__tar.gz → 0.0.52.dev756__tar.gz

{evolve_sdk-0.0.52.dev744 → evolve_sdk-0.0.52.dev756}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evolve-sdk
-Version: 0.0.52.dev744
+Version: 0.0.52.dev756
 Summary: Pythonic SDK for multi-agent orchestration in E2B sandboxes
 Author-email: "Swarmlink, Inc." <brandomagnani@evolvingmachines.ai>
 License: Apache-2.0

{evolve_sdk-0.0.52.dev744 → evolve_sdk-0.0.52.dev756}/evolve/__init__.py

@@ -38,6 +38,7 @@ from .hosted import (
     Agent,
     AgentArm,
     AgentCapability,
+    AgentDatasetStats,
     AgentInfo,
     AgentPage,
     AgentResult,
@@ -80,6 +81,9 @@ from .hosted import (
     JobEvent,
     JobFailure,
     JobPage,
+    JobRetryConfig,
+    JobRetryConfigInput,
+    JobStats,
     JobStatus,
     JobTaskRollup,
     JobTaskRollupPage,
@@ -385,7 +389,7 @@ async def list_checkpoints(
         await store.close()
 
 
-__version__ = '0.0.52.dev744'
+__version__ = '0.0.52.dev756'
 
 __all__ = [
     # Main classes
@@ -480,9 +484,13 @@ __all__ = [
     'Task',
     'TaskProviderVerdict',
     'AgentArm',
+    'AgentDatasetStats',
     'Job',
     'JobCounts',
     'JobFailure',
+    'JobRetryConfig',
+    'JobRetryConfigInput',
+    'JobStats',
     'JobStatus',
     'TrialStatus',
     'EvalSandboxProvider',
@@ -601,7 +609,10 @@ __all__ = [
     'JudgeCompleteEvent',
     'EmitOption',
 
-    # Retry
+    # Retry — the SWARM client-side retry helper. The hosted job auto-retry
+    # policy is a different shape with its own names: JobRetryConfig /
+    # JobRetryConfigInput above (the spec calls that pair RetryConfig /
+    # RetryConfigInput; the Python export is prefixed so the two never shadow).
     'RetryConfig',
     'OnItemRetryCallback',
     'execute_with_retry',

{evolve_sdk-0.0.52.dev744 → evolve_sdk-0.0.52.dev756}/evolve/hosted.py

@@ -46,6 +46,7 @@ from typing import (
     Literal,
     NoReturn,
     Optional,
+    TypedDict,
     Union,
     get_args,
 )
@@ -161,6 +162,7 @@ HostedErrorCode = Literal[
     'import_not_found',
     'import_too_large',
     'invalid_archive',
+    'unpinned_git_ref',
     'package_not_retained',
     'package_corrupt',
     'package_missing',
@@ -437,15 +439,22 @@ class TaskPage:
 
 @dataclass
 class UpstreamStatus:
-    """Where a dataset's git source points now, versus what its active version
-    was built from — the data behind a "new version available" badge.
+    """The active version's git provenance, plus the watch on a ref that can
+    move.
+
+    The provenance half — ``git_url`` + the requested ``ref`` + the resolved
+    commit (``current_commit``) + the repository subfolder (``path``) — says
+    what the active version was built from. The watch half (``latest_commit``,
+    ``moved``, ``checked_at``, …) is the data behind a "new version available"
+    badge; on a version pinned to a commit sha it stays at rest (None / False),
+    because a pin cannot move and nothing checks one.
 
     Nothing here imports anything by itself — a new version is always a row you
     create, or ``auto_import`` creates.
     """
-    #: The ref the active version was imported from.
+    #: The ref the active version was imported from, exactly as requested.
     ref: str
-    #: The commit the active version was built from.
+    #: The commit the active version was built from (the resolved sha).
     current_commit: str
     #: Where the ref points upstream now; None when the last check failed.
     latest_commit: Optional[str]
@@ -459,6 +468,16 @@ class UpstreamStatus:
     error: Optional[str]
     #: Whether a moved upstream automatically imports a new version.
     auto_import: bool = False
+    #: The repository the active version was imported from, userinfo (an
+    #: embedded token) stripped. None on an older server or an unparseable url.
+    git_url: Optional[str] = None
+    #: The repository subfolder the corpus was read from; None = the
+    #: repository root (or an older server).
+    path: Optional[str] = None
+    #: The newest commit a local version already exists for, whether or not it
+    #: is the active one; None before any import recorded one (or an older
+    #: server).
+    acked_commit: Optional[str] = None
 
 
 @dataclass
@@ -781,6 +800,149 @@ class JobFailure:
     message: str
 
 
+class AgentDatasetStats(TypedDict, total=False):
+    """Per-(agent, model, dataset) statistics — one ``stats['evals']`` group.
+
+    The evals key format is ``{agent}__{model}__{dataset}`` — the dataset ref
+    is always the LAST ``__`` segment, which is where Harbor-compatible
+    readers recover it — with the platform extension of an ``__{effort}``
+    segment inserted BEFORE the dataset when a declared reasoning effort is
+    part of the arm identity: ``{agent}__{model}__{effort}__{dataset}``.
+
+    A ``TypedDict``: at runtime this IS the plain wire dict, read by key like
+    always — the class only teaches type checkers the keys. Every key is
+    optional, like the TypeScript interface's ``?`` fields.
+    """
+    #: Trials that produced a rewards map — rewarded, not merely settled.
+    n_trials: int
+    #: Trials carrying ``exception_info`` — indeterminate and cancelled included.
+    n_errors: int
+    #: Metric results (a mean entry per arm today: the primary reward averaged
+    #: over EVERY trial of the group, unrewarded trials counting 0); open objects.
+    metrics: List[Dict[str, Any]]
+    #: pass@k for this group, k (as a string — JSON object keys always are) to
+    #: a value in [0, 1]; ``{}`` when the group cannot answer. Read it with
+    #: :func:`pass_at_k`, which returns sorted numeric points.
+    pass_at_k: Dict[str, float]
+    #: reward key -> reward value -> trial identifiers.
+    reward_stats: Dict[str, Dict[str, List[str]]]
+    #: exception type -> trial identifiers.
+    exception_stats: Dict[str, List[str]]
+
+
+class JobStats(TypedDict, total=False):
+    """Aggregate statistics of a job. Progress counters, token totals, and
+    measured cost. The ``n_*`` counters are CUMULATIVE, Harbor-style: errored
+    trials are a subset of completed, cancelled a subset of errored — a
+    cancelled trial counts in all three. The disjoint per-status breakdown
+    rides ``Job.trials.by_status``. ``cost_usd`` is what the trials actually
+    spent so far — reporting, never a gate (enforcement is the per-trial cap).
+
+    A ``TypedDict``: at runtime this IS the plain wire dict, read by key like
+    always (``stats.get('cost_usd')``, ``stats['evals']``) — the class only
+    teaches type checkers the keys. Every key is optional, like the
+    TypeScript interface's ``?`` fields.
+    """
+    #: Cumulative: every trial that produced a result — errored and cancelled included.
+    n_completed_trials: int
+    #: Cumulative: every completed trial carrying ``exception_info``, cancelled included.
+    n_errored_trials: int
+    n_running_trials: int
+    n_pending_trials: int
+    #: A subset of ``n_errored_trials``.
+    n_cancelled_trials: int
+    n_retries: int
+    #: Keyed ``{agent}__{model}__{dataset}`` — dataset ref last, optional
+    #: effort segment before it.
+    evals: Dict[str, AgentDatasetStats]
+    #: Total input tokens (cache included); None until recorded.
+    n_input_tokens: Optional[int]
+    n_cache_tokens: Optional[int]
+    n_output_tokens: Optional[int]
+    #: Measured spend across settled trials — the WHOLE model bill, agent and
+    #: judge together; None before any settled.
+    cost_usd: Optional[float]
+    #: Sum of the job's per-trial GPU compute ESTIMATES (each trial's
+    #: ``gpu_cost['estimate_usd']``) — a SEPARATE labeled figure, never merged
+    #: into ``cost_usd`` (metered model spend). None when no trial of the job
+    #: carries an estimate; a real $0 (a GPU trial that provably never booted
+    #: a sandbox) keeps the sum non-None.
+    gpu_cost_usd: Optional[float]
+    #: The judge share of ``cost_usd``, itemized: what the trials'
+    #: verifier-phase judge keys spent. 0 for a job with no judge-enabled
+    #: tasks; None before anything settled, like ``cost_usd``.
+    judge_cost_usd: Optional[float]
+
+
+class JobRetryConfigInput(TypedDict, total=False):
+    """Auto-retry policy INPUT — ``jobs().start(retry=...)``, the spec's
+    ``RetryConfigInput`` schema, Harbor's RetryConfig vocabulary verbatim.
+
+    ONE NAMING NOTE: Harbor, the spec, and the TypeScript SDK call this pair
+    ``RetryConfig`` / ``RetryConfigInput``. The Python SDK exports them as
+    ``JobRetryConfig`` / ``JobRetryConfigInput`` because ``evolve.RetryConfig``
+    already names the Swarm client-side retry helper (``max_attempts``,
+    ``backoff_ms``, ...) — two unrelated shapes never share one exported name.
+
+    A ``TypedDict``: pass the plain dict you always passed — the class only
+    teaches type checkers the keys. Every key is optional, and an omitted key
+    takes Harbor's own default with ONE named deviation: ``max_retries``
+    omitted takes the PLATFORM fleet default (published as
+    ``limits['job']['default_max_retries']`` on ``meta()``; 2 unless the
+    operator tuned it) rather than Harbor's 0 — infrastructure errors on a
+    hosted fleet retry automatically. Send ``{'max_retries': 0}`` to turn
+    retries off.
+
+    Inside the policy, an EXPLICIT ``'exclude_exceptions': None`` is not the
+    same as leaving the key out: None turns exclusions off entirely (Harbor's
+    own None semantics), while an omitted key keeps Harbor's default
+    non-retryable set. ``include_exceptions`` has no such split: None, an
+    omitted key, and ``[]`` all mean no filter.
+    """
+    #: Maximum automatic retries per trial (0-10). Omitted = fleet default; 0 = off.
+    max_retries: int
+    #: Exception types to retry on. None, omitted, or ``[]`` = no filter.
+    include_exceptions: Optional[List[str]]
+    #: Exception types to NOT retry on; wins over ``include_exceptions``.
+    #: Omitted = Harbor's default non-retryable set; an EXPLICIT None turns
+    #: exclusions off entirely.
+    exclude_exceptions: Optional[List[str]]
+    #: Multiplier for exponential backoff wait time (default 1.0).
+    wait_multiplier: float
+    #: Minimum wait in seconds between retries (default 1.0).
+    min_wait_sec: float
+    #: Maximum wait in seconds between retries (default 60.0; platform cap 3600).
+    max_wait_sec: float
+
+
+class JobRetryConfig(TypedDict):
+    """The RESOLVED auto-retry policy a job runs under — the spec's
+    ``RetryConfig`` schema, echoed on every job body as ``Job.retry``: the
+    caller's values or the defaults of the day, resolved at create and
+    stored, so the row always states the policy it executes. Backoff between
+    attempts is Harbor's formula:
+    min(min_wait_sec x wait_multiplier^attempt, max_wait_sec).
+
+    A ``TypedDict``: at runtime this IS the plain wire dict, read by key like
+    always (``job.retry['max_retries']``) — the class only teaches type
+    checkers the keys. Every key is REQUIRED, like the spec's own required
+    list: the mapper reads an older server that sends no policy as the
+    retries-off policy with Harbor's defaults — exactly how such a server
+    behaves — so every field is always present.
+
+    Named ``JobRetryConfig`` rather than the spec's ``RetryConfig`` because
+    ``evolve.RetryConfig`` is the (unrelated) Swarm retry helper — see
+    :class:`JobRetryConfigInput` for the input half and the naming note.
+    """
+    max_retries: int
+    #: None = no include filter (everything the exclude set admits).
+    include_exceptions: Optional[List[str]]
+    exclude_exceptions: List[str]
+    wait_multiplier: float
+    min_wait_sec: float
+    max_wait_sec: float
+
+
 @dataclass
 class Job:
     """THE job body — the same shape from start, get, list rows, cancel,
@@ -807,8 +969,21 @@ class Job:
     #: The RESOLVED auto-retry policy this job runs under — Harbor's
     #: RetryConfig field names (``max_retries``, ``include_exceptions``,
     #: ``exclude_exceptions``, ``wait_multiplier``, ``min_wait_sec``,
-    #: ``max_wait_sec``). A plain dict with the wire's own keys, read by key.
-    retry: Dict[str, Any]
+    #: ``max_wait_sec``). Still the plain wire dict at runtime, read by key —
+    #: :class:`JobRetryConfig` types the keys, and every field is ALWAYS
+    #: present: an older server that sends no policy reads as the retries-off
+    #: policy with Harbor's defaults, exactly how such a server behaves.
+    retry: JobRetryConfig
+    #: The RESOLVED timeout multipliers this job's phases arm under —
+    #: Harbor's five flat JobConfig fields, echoed on every job body. The
+    #: global one is always a number (1.0 when the create request named
+    #: none); each phase field below is None when not overridden, meaning the
+    #: global one applies to that phase.
+    timeout_multiplier: float
+    agent_timeout_multiplier: Optional[float]
+    verifier_timeout_multiplier: Optional[float]
+    agent_setup_timeout_multiplier: Optional[float]
+    environment_build_timeout_multiplier: Optional[float]
     sandbox_provider: EvalSandboxProvider
     counts: JobCounts
     n_total_trials: int
@@ -820,8 +995,10 @@ class Job:
     #: GPU compute estimate, never merged into ``cost_usd``; ``evals`` keyed
     #: ``agent__model__dataset``, each group carrying its mean and its
     #: ``pass_at_k`` — read the latter with :func:`pass_at_k`).
-    #: A plain dict with the wire's own keys, read by key, never constructed.
-    stats: Dict[str, Any]
+    #: Still the plain wire dict at runtime, read by key, never constructed —
+    #: :class:`JobStats` types the keys so ``stats['evals']`` and friends
+    #: check instead of being ``Any``.
+    stats: JobStats
     #: Why the job FAILED, or None.
     failure: Optional[JobFailure]
     #: Provenance of a derived job; empty for an original one.
@@ -1477,6 +1654,9 @@ def _map_upstream(data: Any) -> Optional[UpstreamStatus]:
         checked_at=data.get('checked_at'),
         error=data.get('error'),
         auto_import=data.get('auto_import') is True,
+        git_url=data.get('git_url'),
+        path=data.get('path'),
+        acked_commit=data.get('acked_commit'),
     )
 
 
@@ -1734,6 +1914,34 @@ def _map_source_job(data: Dict[str, Any]) -> SourceJob:
     )
 
 
+def _optional_float(value: Any) -> Optional[float]:
+    """A wire number or None — anything else (an older server, garbage) is None."""
+    return float(value) if isinstance(value, (int, float)) else None
+
+
+def _map_retry_config(data: Any) -> JobRetryConfig:
+    """The resolved retry policy off a job body. Tolerant of an OLDER server
+    that does not send one yet: the absent-field reading is the retries-off
+    policy with Harbor's defaults — exactly how such a server behaves.
+    """
+    raw = data if isinstance(data, dict) else {}
+
+    def _number(value: Any, default: float) -> float:
+        # bool is an int in Python; a boolean here is malformed, not a number.
+        return value if isinstance(value, (int, float)) and not isinstance(value, bool) else default
+
+    include = raw.get('include_exceptions')
+    exclude = raw.get('exclude_exceptions')
+    return {
+        'max_retries': int(_number(raw.get('max_retries'), 0)),
+        'include_exceptions': include if isinstance(include, list) else None,
+        'exclude_exceptions': exclude if isinstance(exclude, list) else [],
+        'wait_multiplier': _number(raw.get('wait_multiplier'), 1.0),
+        'min_wait_sec': _number(raw.get('min_wait_sec'), 1.0),
+        'max_wait_sec': _number(raw.get('max_wait_sec'), 60.0),
+    }
+
+
 def _map_job(data: Dict[str, Any]) -> Job:
     """The ONE job mapper — nothing conditional, because nothing is optional."""
     agents = data.get('agents')
@@ -1753,9 +1961,23 @@ def _map_job(data: Dict[str, Any]) -> Job:
         n_concurrent_trials=int(data.get('n_concurrent_trials', 0)),
         max_trial_spend_usd=float(data.get('max_trial_spend_usd', 0)),
         worst_case_spend_usd=float(data.get('worst_case_spend_usd', 0)),
-        # An older server sends no policy; {} reads as "no auto-retry", which
-        # is exactly how such a server behaves.
-        retry=data.get('retry') if isinstance(data.get('retry'), dict) else {},
+        # Resolved with Harbor's defaults for anything absent — an older
+        # server that sends no policy reads as the retries-off policy, which
+        # is exactly how such a server behaves; every field always present.
+        retry=_map_retry_config(data.get('retry')),
+        # Timeout multipliers: an older server sends none — 1.0 / None reads
+        # as "every phase at 1.0", exactly how such a server behaves.
+        timeout_multiplier=(
+            float(data['timeout_multiplier'])
+            if isinstance(data.get('timeout_multiplier'), (int, float))
+            else 1.0
+        ),
+        agent_timeout_multiplier=_optional_float(data.get('agent_timeout_multiplier')),
+        verifier_timeout_multiplier=_optional_float(data.get('verifier_timeout_multiplier')),
+        agent_setup_timeout_multiplier=_optional_float(data.get('agent_setup_timeout_multiplier')),
+        environment_build_timeout_multiplier=_optional_float(
+            data.get('environment_build_timeout_multiplier')
+        ),
         sandbox_provider=data.get('sandbox_provider', ''),
         counts=_map_counts(data.get('counts')),
         n_total_trials=int(data.get('n_total_trials', 0)),
@@ -1907,6 +2129,23 @@ def _map_trial_retry(data: Dict[str, Any]) -> TrialRetry:
     )
 
 
+def _map_provider_degrade(data: Any) -> Optional[Dict[str, str]]:
+    """The wire degrade object, defensively: anything malformed answers None,
+    never a crash and never a partial row; extra keys never ride through."""
+    if not isinstance(data, dict):
+        return None
+    from_provider = data.get('from')
+    to_provider = data.get('to')
+    reason = data.get('reason')
+    if not (
+        isinstance(from_provider, str)
+        and isinstance(to_provider, str)
+        and isinstance(reason, str)
+    ):
+        return None
+    return {'from': from_provider, 'to': to_provider, 'reason': reason}
+
+
 def _map_trial(data: Dict[str, Any]) -> Trial:
     retries = data.get('retries')
     return Trial(
@@ -1938,11 +2177,7 @@ def _map_trial(data: Dict[str, Any]) -> Trial:
         max_trial_spend_usd=data.get('max_trial_spend_usd'),
         sandbox_provider=data.get('sandbox_provider'),
         # Defensive: a malformed degrade object reads as None, never a crash.
-        sandbox_provider_degrade=(
-            data['sandbox_provider_degrade']
-            if isinstance(data.get('sandbox_provider_degrade'), dict)
-            else None
-        ),
+        sandbox_provider_degrade=_map_provider_degrade(data.get('sandbox_provider_degrade')),
         # Same defensive rule; absent (an older server) reads as None too.
         gpu_cost=(
             data['gpu_cost'] if isinstance(data.get('gpu_cost'), dict) else None
@@ -3387,7 +3622,12 @@ class JobsClient:
         n_concurrent_trials: Optional[int] = None,
         max_trial_spend_usd: Optional[float] = None,
         sandbox_provider: Optional[str] = None,
-        retry: Optional[Dict[str, Any]] = None,
+        retry: Optional[JobRetryConfigInput] = None,
+        timeout_multiplier: Optional[float] = None,
+        agent_timeout_multiplier: Optional[float] = None,
+        verifier_timeout_multiplier: Optional[float] = None,
+        agent_setup_timeout_multiplier: Optional[float] = None,
+        environment_build_timeout_multiplier: Optional[float] = None,
         agent_env: Optional[Dict[str, str]] = None,
         verifier_env: Optional[Dict[str, str]] = None,
         idempotency_key: Optional[str] = None,
@@ -3408,10 +3648,12 @@ class JobsClient:
         case for the whole job. ``retry`` is the auto-retry policy in
         Harbor's RetryConfig vocabulary (``max_retries``,
         ``include_exceptions``, ``exclude_exceptions``, ``wait_multiplier``,
-        ``min_wait_sec``, ``max_wait_sec``); omitted, the server applies its
+        ``min_wait_sec``, ``max_wait_sec``) — a plain dict, typed
+        :class:`JobRetryConfigInput`; omitted, the server applies its
         fleet defaults (infrastructure errors retry automatically — send
         ``{'max_retries': 0}`` to turn retries off), and the response echoes
-        the RESOLVED policy either way. Inside the policy, an EXPLICIT
+        the RESOLVED policy either way as ``Job.retry``
+        (:class:`JobRetryConfig`, every field present). Inside the policy, an EXPLICIT
         ``'exclude_exceptions': None`` is not the same as leaving the key
         out: None turns exclusions off entirely (everything the include set
         admits is retried — Harbor's own None semantics), while an omitted
@@ -3419,7 +3661,19 @@ class JobsClient:
         ``'include_exceptions'`` has no such split: None, an omitted key,
         and the empty list ``[]`` all mean no filter — Harbor's include
         check treats the empty set exactly like None, so ``[]`` never means
-        "retry nothing". ``agent_env`` / ``verifier_env`` are
+        "retry nothing". The five ``*timeout_multiplier`` arguments are
+        Harbor's timeout knobs verbatim: ``timeout_multiplier`` multiplies
+        every TASK-DECLARED timeout for this job's runs (default 1.0;
+        values below 1 shrink), and each phase-specific one —
+        ``agent_timeout_multiplier``, ``verifier_timeout_multiplier``,
+        ``agent_setup_timeout_multiplier``,
+        ``environment_build_timeout_multiplier`` — overrides it for that
+        phase. The task itself is never rewritten. Every multiplier must be
+        greater than 0 and at most the published ceiling
+        (``limits['job']['max_timeout_multiplier']`` on the capability
+        document; 10 unless the fleet changes it) — an absurd value is
+        refused at create with a typed message naming the bound.
+        ``agent_env`` / ``verifier_env`` are
         pass-through slots injected into every agent / verifier run — sent
         verbatim; the server owns acceptance (refused where unsupported,
         never silently dropped). The hosted platform honors exactly two
@@ -3452,6 +3706,16 @@ class JobsClient:
             body['sandbox_provider'] = sandbox_provider
         if retry is not None:
             body['retry'] = retry
+        if timeout_multiplier is not None:
+            body['timeout_multiplier'] = timeout_multiplier
+        if agent_timeout_multiplier is not None:
+            body['agent_timeout_multiplier'] = agent_timeout_multiplier
+        if verifier_timeout_multiplier is not None:
+            body['verifier_timeout_multiplier'] = verifier_timeout_multiplier
+        if agent_setup_timeout_multiplier is not None:
+            body['agent_setup_timeout_multiplier'] = agent_setup_timeout_multiplier
+        if environment_build_timeout_multiplier is not None:
+            body['environment_build_timeout_multiplier'] = environment_build_timeout_multiplier
         if agent_env is not None:
             body['agent_env'] = agent_env
         if verifier_env is not None:

{evolve_sdk-0.0.52.dev744 → evolve_sdk-0.0.52.dev756}/evolve_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evolve-sdk
-Version: 0.0.52.dev744
+Version: 0.0.52.dev756
 Summary: Pythonic SDK for multi-agent orchestration in E2B sandboxes
 Author-email: "Swarmlink, Inc." <brandomagnani@evolvingmachines.ai>
 License: Apache-2.0

{evolve_sdk-0.0.52.dev744 → evolve_sdk-0.0.52.dev756}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "evolve-sdk"
-version = "0.0.52.dev744"
+version = "0.0.52.dev756"
 description = "Pythonic SDK for multi-agent orchestration in E2B sandboxes"
 readme = "README.md"
 requires-python = ">=3.10"