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

evolve/sessions_client.py

@@ -0,0 +1,167 @@
+"""Standalone sessions() client for historical traces and past sessions."""
+
+import asyncio
+from typing import Any, Dict, List, Literal, Optional
+
+from .results import BrowserReplay, SessionEvent, SessionInfo, SessionPage, SessionTranscript
+from .utils import (
+    _filter_none,
+    _require_browser_replay,
+    _require_session_info,
+    _require_session_transcript,
+)
+
+
+class SessionsClient:
+    """Client for listing historical sessions and downloading traces.
+
+    Created via the standalone ``sessions()`` factory only.
+    Wraps bridge JSON-RPC calls to the TypeScript SDK's sessions() client.
+
+    Gateway-only: requires ``EVOLVE_API_KEY`` unless ``SessionsConfig(api_key=...)``
+    is provided.
+
+    Example::
+
+        from evolve import sessions
+
+        async with sessions() as client:
+            page = await client.list(limit=20, state='ended')
+            events = await client.events(page.items[0].id)
+            path = await client.download(page.items[0].id, to='./traces')
+    """
+
+    def __init__(
+        self,
+        bridge: Any,
+        sessions_config: Any = None,
+        *,
+        _owns_bridge: bool = False,
+    ):
+        self._bridge = bridge
+        self._config = sessions_config
+        self._owns_bridge = _owns_bridge
+        self._started = False
+        self._init_lock = asyncio.Lock()
+
+    async def _ensure_ready(self) -> None:
+        """Ensure the bridge is started and ready to handle RPC calls."""
+        async with self._init_lock:
+            if self._started:
+                return
+            await self._bridge.start()
+            self._started = True
+
+    def _build_params(self, **kwargs: Any) -> Dict[str, Any]:
+        """Build RPC params, including standalone sessions config."""
+        params: Dict[str, Any] = {}
+        if self._config is not None:
+            params['sessions'] = self._config.to_dict()
+        params.update(_filter_none(kwargs))
+        return params
+
+    async def list(
+        self,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+        state: Optional[Literal['live', 'ended', 'all']] = None,
+        agent: Optional[str] = None,
+        tag_prefix: Optional[str] = None,
+        sort: Optional[Literal['newest', 'oldest', 'cost']] = None,
+    ) -> SessionPage:
+        """List historical sessions with optional filtering and pagination."""
+        await self._ensure_ready()
+        params = self._build_params(
+            limit=limit,
+            cursor=cursor,
+            state=state,
+            agent=agent,
+            tag_prefix=tag_prefix,
+            sort=sort,
+        )
+        response = await self._bridge.call('sessions_list', params)
+        return SessionPage(
+            items=[_require_session_info(item) for item in response.get('items', [])],
+            next_cursor=response.get('next_cursor'),
+            has_more=bool(response.get('has_more', False)),
+        )
+
+    async def get(self, id: str) -> SessionInfo:
+        """Get a single session's metadata by ID."""
+        await self._ensure_ready()
+        response = await self._bridge.call('sessions_get', self._build_params(id=id))
+        return _require_session_info(response)
+
+    async def events(
+        self,
+        id: str,
+        *,
+        since: Optional[int] = None,
+    ) -> List[SessionEvent]:
+        """Fetch parsed JSONL events for a historical session."""
+        await self._ensure_ready()
+        response = await self._bridge.call('sessions_events', self._build_params(id=id, since=since))
+        return list(response.get('events', []))
+
+    async def transcript(
+        self,
+        id: str,
+        *,
+        since: Optional[int] = None,
+    ) -> SessionTranscript:
+        """The transcript feed in one read: the ``session``, its ``events``
+        after ``since``, the ``total`` stored, and the gateway meter's per-call
+        ``gateway_calls`` (see :class:`SessionTranscript`)."""
+        await self._ensure_ready()
+        response = await self._bridge.call('sessions_transcript', self._build_params(id=id, since=since))
+        return _require_session_transcript(response)
+
+    async def download(
+        self,
+        id: str,
+        *,
+        to: Optional[str] = None,
+    ) -> str:
+        """Download a session's raw JSONL trace file. Returns the local path."""
+        await self._ensure_ready()
+        response = await self._bridge.call('sessions_download', self._build_params(id=id, to=to))
+        return response['path']
+
+    async def browser_replay(
+        self,
+        id: str,
+        *,
+        timeout_ms: Optional[int] = None,
+        interval_ms: Optional[int] = None,
+    ) -> BrowserReplay:
+        """Wait for browser replay readiness and return replay/download URLs."""
+        await self._ensure_ready()
+        effective_timeout_ms = timeout_ms if timeout_ms is not None else 600_000
+        effective_interval_ms = interval_ms if interval_ms is not None else 5_000
+        if effective_timeout_ms <= 0:
+            raise ValueError('timeout_ms must be positive')
+        if effective_interval_ms <= 0:
+            raise ValueError('interval_ms must be positive')
+        rpc_timeout_s = max(1.0, (effective_timeout_ms / 1000) + 30)
+        response = await self._bridge.call(
+            'sessions_browser_replay',
+            self._build_params(id=id, timeout_ms=timeout_ms, interval_ms=interval_ms),
+            timeout_s=rpc_timeout_s,
+        )
+        return _require_browser_replay(response)
+
+    async def close(self) -> None:
+        """Close the sessions client and release resources."""
+        if self._owns_bridge:
+            await self._bridge.stop()
+
+    async def __aenter__(self) -> 'SessionsClient':
+        try:
+            await self._ensure_ready()
+            return self
+        except Exception:
+            await self.close()
+            raise
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

evolve/storage_client.py

@@ -0,0 +1,178 @@
+"""StorageClient for browsing and downloading checkpoints."""
+
+import asyncio
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union
+
+from .results import CheckpointInfo
+from .utils import _decode_files_from_transport, _filter_none, _parse_checkpoint, _require_checkpoint
+
+
+class StorageClient:
+    """Client for browsing and downloading checkpoints.
+
+    Created via the standalone ``storage()`` factory or ``Evolve.storage()`` accessor.
+    Wraps bridge JSON-RPC calls to the TypeScript SDK's StorageClient.
+
+    Two creation modes:
+
+    - **Standalone** (``storage(config)``): Owns its own bridge subprocess.
+      Use as an async context manager to ensure cleanup.
+    - **Bound** (``evolve.storage()``): Reuses the Evolve instance's bridge.
+      No cleanup needed — the Evolve instance manages the bridge.
+
+    Example (standalone)::
+
+        from evolve import storage, StorageConfig
+
+        async with storage(StorageConfig(url='s3://my-bucket/')) as store:
+            checkpoints = await store.list_checkpoints(limit=5)
+            files = await store.download_files(checkpoints[0].id)
+
+    Example (bound)::
+
+        async with Evolve(storage=StorageConfig(url='s3://bucket/')) as evolve:
+            store = evolve.storage()
+            info = await store.get_checkpoint('ckpt_abc123')
+    """
+
+    def __init__(
+        self,
+        bridge: Any,
+        storage_config: Any = None,
+        *,
+        _owns_bridge: bool = False,
+        _init_fn: Optional[Callable[[], Awaitable[None]]] = None,
+    ):
+        self._bridge = bridge
+        self._config = storage_config  # None = use Evolve's initialized config
+        self._owns_bridge = _owns_bridge
+        # Readiness callback — in bound mode this triggers Evolve._ensure_initialized
+        # so the bridge adapter has a live Evolve instance to delegate to.
+        self._init_fn = _init_fn
+        self._started = False
+        self._init_lock = asyncio.Lock()
+
+    async def _ensure_ready(self) -> None:
+        """Ensure the bridge is started and ready to handle RPC calls."""
+        async with self._init_lock:
+            if self._started:
+                return
+            if self._init_fn is not None:
+                await self._init_fn()
+            else:
+                await self._bridge.start()
+            self._started = True
+
+    def _build_params(self, **kwargs: Any) -> Dict[str, Any]:
+        """Build RPC params, including storage config if in standalone mode."""
+        params: Dict[str, Any] = {}
+        if self._config is not None:
+            params['storage'] = self._config.to_dict()
+        params.update(_filter_none(kwargs))
+        return params
+
+    async def list_checkpoints(
+        self,
+        limit: Optional[int] = None,
+        tag: Optional[str] = None,
+    ) -> List[CheckpointInfo]:
+        """List checkpoints sorted by newest first.
+
+        Args:
+            limit: Maximum number of checkpoints to return (default: 100, max: 500)
+            tag: Filter by session tag
+
+        Returns:
+            List of CheckpointInfo sorted by newest first
+        """
+        await self._ensure_ready()
+        params = self._build_params(limit=limit, tag=tag)
+        response = await self._bridge.call('storage_list_checkpoints', params)
+        return [_require_checkpoint(cp) for cp in response]
+
+    async def get_checkpoint(self, id: str) -> CheckpointInfo:
+        """Get checkpoint metadata by ID.
+
+        Args:
+            id: Checkpoint ID
+
+        Returns:
+            CheckpointInfo with full metadata
+
+        Raises:
+            Exception: If checkpoint not found
+        """
+        await self._ensure_ready()
+        params = self._build_params(id=id)
+        response = await self._bridge.call('storage_get_checkpoint', params)
+        return _require_checkpoint(response)
+
+    async def download_checkpoint(
+        self,
+        id: str,
+        *,
+        to: Optional[str] = None,
+        extract: bool = True,
+    ) -> str:
+        """Download a checkpoint archive.
+
+        Args:
+            id: Checkpoint ID or ``"latest"``
+            to: Target directory (default: current working directory)
+            extract: Extract the tar.gz archive (default: True).
+                     If False, saves the raw .tar.gz file.
+
+        Returns:
+            Path to the extracted directory or saved archive file
+        """
+        await self._ensure_ready()
+        params = self._build_params(id=id, to=to, extract=extract if not extract else None)
+        response = await self._bridge.call('storage_download_checkpoint', params)
+        return response['path']
+
+    async def download_files(
+        self,
+        id: str,
+        *,
+        files: Optional[List[str]] = None,
+        glob: Optional[List[str]] = None,
+        to: Optional[str] = None,
+    ) -> Dict[str, Union[str, bytes]]:
+        """Download specific files from a checkpoint.
+
+        For large checkpoints, prefer :meth:`download_checkpoint` which streams
+        the archive to disk instead of loading all files into memory.
+
+        Args:
+            id: Checkpoint ID or ``"latest"``
+            files: Exact file paths to extract (e.g., ``["workspace/data.txt"]``)
+            glob: Glob patterns to match (e.g., ``["workspace/*.txt"]``)
+            to: Write files to this directory instead of returning in-memory
+
+        Returns:
+            Dict mapping file path to content (str for text, bytes for binary)
+        """
+        await self._ensure_ready()
+        params = self._build_params(id=id, files=files, glob=glob, to=to)
+        response = await self._bridge.call('storage_download_files', params)
+        return _decode_files_from_transport(response.get('files', {}))
+
+    async def close(self) -> None:
+        """Close the storage client and release resources.
+
+        Only needed for standalone clients (created via ``storage()``).
+        Bound clients (from ``Evolve.storage()``) are managed by the Evolve instance.
+        """
+        if self._owns_bridge:
+            await self._bridge.stop()
+
+    async def __aenter__(self) -> 'StorageClient':
+        try:
+            await self._ensure_ready()
+            return self
+        except Exception:
+            await self.close()
+            raise
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

evolve/swarm/__init__.py

@@ -0,0 +1,75 @@
+"""Swarm abstractions for parallel AI agent execution."""
+
+from .swarm import Swarm
+from .types import (
+    FileMap,
+    SwarmConfig,
+    BestOfConfig,
+    VerifyConfig,
+    IndexedMeta,
+    ReduceMeta,
+    JudgeMeta,
+    VerifyMeta,
+    BaseMeta,
+    OperationType,
+    Prompt,
+    PromptFn,
+    ItemInput,
+    SchemaType,
+    JudgeDecision,
+    VerifyDecision,
+    # Callback types
+    OnCandidateCompleteCallback,
+    OnJudgeCompleteCallback,
+    OnWorkerCompleteCallback,
+    OnVerifierCompleteCallback,
+)
+from .results import (
+    SwarmResult,
+    SwarmResultList,
+    ReduceResult,
+    BestOfResult,
+    BestOfInfo,
+    VerifyInfo,
+    is_swarm_result,
+    SWARM_RESULT_BRAND,
+)
+
+__all__ = [
+    # Main class
+    'Swarm',
+    # Config types
+    'SwarmConfig',
+    'BestOfConfig',
+    'VerifyConfig',
+    # Result types
+    'SwarmResult',
+    'SwarmResultList',
+    'ReduceResult',
+    'BestOfResult',
+    'BestOfInfo',
+    'VerifyInfo',
+    # Meta types
+    'IndexedMeta',
+    'ReduceMeta',
+    'JudgeMeta',
+    'VerifyMeta',
+    'BaseMeta',
+    'OperationType',
+    # Other types
+    'FileMap',
+    'Prompt',
+    'PromptFn',
+    'ItemInput',
+    'SchemaType',
+    'JudgeDecision',
+    'VerifyDecision',
+    # Callback types
+    'OnCandidateCompleteCallback',
+    'OnJudgeCompleteCallback',
+    'OnWorkerCompleteCallback',
+    'OnVerifierCompleteCallback',
+    # Helpers
+    'is_swarm_result',
+    'SWARM_RESULT_BRAND',
+]

evolve/swarm/results.py

@@ -0,0 +1,140 @@
+"""Result types for Swarm abstractions."""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Generic, List, Literal, Optional, TypeVar, Union
+
+from .types import FileMap, IndexedMeta, ReduceMeta, JudgeMeta, VerifyMeta
+
+
+T = TypeVar('T')
+
+# Brand for runtime detection of SwarmResult (for chaining)
+SWARM_RESULT_BRAND = "__swarm_result__"
+
+
+# =============================================================================
+# SWARM RESULT
+# =============================================================================
+
+@dataclass
+class SwarmResult(Generic[T]):
+    """Result from a single worker (map, filter, bestof candidate).
+
+    Status meanings:
+    - "success": Positive outcome (agent succeeded / condition passed)
+    - "filtered": Neutral outcome (evaluated but didn't pass condition) - filter only
+    - "error": Negative outcome (agent error)
+    """
+    status: Literal["success", "filtered", "error"]
+    data: Optional[T]
+    files: FileMap
+    meta: IndexedMeta
+    error: Optional[str] = None
+    raw_data: Optional[str] = None
+    best_of: Optional['BestOfInfo'] = None
+    verify: Optional['VerifyInfo'] = None
+
+    # Brand for runtime detection (used by is_swarm_result() function)
+    __swarm_result__: bool = field(default=True, repr=False)
+
+
+@dataclass
+class BestOfInfo(Generic[T]):
+    """BestOf information attached to SwarmResult when map used bestOf option."""
+    winner_index: int
+    judge_reasoning: str
+    judge_meta: JudgeMeta
+    candidates: List[SwarmResult[T]]
+
+
+@dataclass
+class VerifyInfo:
+    """Verification info attached to results when verify option used."""
+    passed: bool
+    reasoning: str
+    verify_meta: VerifyMeta
+    attempts: int
+
+
+# =============================================================================
+# SWARM RESULT LIST
+# =============================================================================
+
+class SwarmResultList(List[SwarmResult[T]], Generic[T]):
+    """List of SwarmResults with helper properties.
+
+    Extends list so all normal list operations work.
+
+    Getters:
+    - `.success` - items with positive outcome
+    - `.filtered` - items that didn't pass condition (filter only)
+    - `.error` - items that encountered errors
+
+    Chaining examples:
+    - `swarm.reduce(results.success, ...)` - forward only successful
+    - `swarm.reduce([*results.success, *results.filtered], ...)` - forward all evaluated
+    """
+
+    @property
+    def success(self) -> List[SwarmResult[T]]:
+        """Returns items with status 'success'."""
+        return [r for r in self if r.status == "success"]
+
+    @property
+    def filtered(self) -> List[SwarmResult[T]]:
+        """Returns items with status 'filtered' (didn't pass condition)."""
+        return [r for r in self if r.status == "filtered"]
+
+    @property
+    def error(self) -> List[SwarmResult[T]]:
+        """Returns items with status 'error'."""
+        return [r for r in self if r.status == "error"]
+
+    @classmethod
+    def from_results(cls, results: List[SwarmResult[T]]) -> 'SwarmResultList[T]':
+        """Create SwarmResultList from a list of SwarmResults."""
+        result_list = cls()
+        result_list.extend(results)
+        return result_list
+
+
+# =============================================================================
+# REDUCE RESULT
+# =============================================================================
+
+@dataclass
+class ReduceResult(Generic[T]):
+    """Result from reduce operation."""
+    status: Literal["success", "error"]
+    data: Optional[T]
+    files: FileMap
+    meta: ReduceMeta
+    error: Optional[str] = None
+    raw_data: Optional[str] = None
+    verify: Optional['VerifyInfo'] = None
+
+
+# =============================================================================
+# BESTOF RESULT
+# =============================================================================
+
+@dataclass
+class BestOfResult(Generic[T]):
+    """Result from bestOf operation."""
+    winner: SwarmResult[T]
+    winner_index: int
+    judge_reasoning: str
+    judge_meta: JudgeMeta
+    candidates: List[SwarmResult[T]]
+
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def is_swarm_result(obj: Any) -> bool:
+    """Check if an object is a SwarmResult (for chaining detection)."""
+    return (
+        isinstance(obj, SwarmResult) or
+        (hasattr(obj, SWARM_RESULT_BRAND) and getattr(obj, SWARM_RESULT_BRAND) is True)
+    )