swarmkit 0.1.34__py3-none-any.whl

swarmkit/swarm/types.py

@@ -0,0 +1,193 @@
+"""Type definitions for Swarm abstractions."""
+
+from dataclasses import dataclass
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+)
+
+from ..config import SandboxProvider, AgentConfig, WorkspaceMode
+from ..retry import RetryConfig
+
+
+# =============================================================================
+# TYPE VARIABLES
+# =============================================================================
+
+T = TypeVar('T')
+
+# =============================================================================
+# FILE MAP
+# =============================================================================
+
+FileMap = Dict[str, Union[str, bytes]]
+
+# =============================================================================
+# CONFIGURATION
+# =============================================================================
+
+@dataclass
+class SwarmConfig:
+    """Configuration for Swarm instance.
+
+    All fields are optional - TS SDK resolves defaults from environment:
+    - agent defaults to SWARMKIT_API_KEY env var with 'claude' type
+    - sandbox defaults to E2B with E2B_API_KEY env var
+    """
+    agent: Optional[AgentConfig] = None
+    sandbox: Optional[SandboxProvider] = None
+    tag: str = "swarm"
+    concurrency: int = 4
+    timeout_ms: int = 3_600_000  # 1 hour
+    workspace_mode: WorkspaceMode = "knowledge"
+    retry: Optional[RetryConfig] = None
+    """Default retry configuration for all operations (per-operation config takes precedence)."""
+    mcp_servers: Optional[Dict[str, Any]] = None
+    """Default MCP servers for all operations (per-operation config takes precedence)."""
+
+
+# Callback types for BestOf
+OnCandidateCompleteCallback = Callable[[int, int, Literal["success", "error"]], None]
+"""(item_index, candidate_index, status)"""
+
+OnJudgeCompleteCallback = Callable[[int, int, str], None]
+"""(item_index, winner_index, reasoning)"""
+
+
+@dataclass
+class BestOfConfig:
+    """Configuration for bestOf operation."""
+    judge_criteria: str
+    n: Optional[int] = None
+    task_agents: Optional[List[AgentConfig]] = None
+    judge_agent: Optional[AgentConfig] = None
+    mcp_servers: Optional[Dict[str, Any]] = None
+    """MCP servers for candidates (defaults to operation mcp_servers)."""
+    judge_mcp_servers: Optional[Dict[str, Any]] = None
+    """MCP servers for judge (defaults to mcp_servers)."""
+    on_candidate_complete: Optional[OnCandidateCompleteCallback] = None
+    """Callback when a candidate completes."""
+    on_judge_complete: Optional[OnJudgeCompleteCallback] = None
+    """Callback when judge completes."""
+
+
+# Callback types for Verify
+OnWorkerCompleteCallback = Callable[[int, int, Literal["success", "error"]], None]
+"""(item_index, attempt, status)"""
+
+OnVerifierCompleteCallback = Callable[[int, int, bool, Optional[str]], None]
+"""(item_index, attempt, passed, feedback)"""
+
+
+@dataclass
+class VerifyConfig:
+    """Configuration for verify operation.
+
+    Verify provides LLM-as-judge quality verification with retry loop.
+    If verification fails, the worker is re-run with feedback from the verifier.
+    """
+    criteria: str
+    """Verification criteria - what the output must satisfy."""
+    max_attempts: int = 3
+    """Maximum attempts with feedback (default: 3). Includes initial attempt."""
+    verifier_agent: Optional[AgentConfig] = None
+    """Optional: override agent for verifier."""
+    verifier_mcp_servers: Optional[Dict[str, Any]] = None
+    """MCP servers for verifier (defaults to operation mcp_servers)."""
+    on_worker_complete: Optional[OnWorkerCompleteCallback] = None
+    """Callback invoked after each worker completion (before verification)."""
+    on_verifier_complete: Optional[OnVerifierCompleteCallback] = None
+    """Callback invoked after each verifier completion."""
+
+
+# =============================================================================
+# METADATA
+# =============================================================================
+
+OperationType = Literal["map", "filter", "reduce", "bestof-cand", "bestof-judge", "verify"]
+
+
+@dataclass
+class BaseMeta:
+    """Base metadata for all operations."""
+    run_id: str
+    operation: OperationType
+    tag: str
+    sandbox_id: str
+
+
+@dataclass
+class IndexedMeta(BaseMeta):
+    """Metadata for indexed operations (map, filter, bestof-cand)."""
+    index: int
+
+
+@dataclass
+class ReduceMeta(BaseMeta):
+    """Metadata for reduce operation."""
+    input_count: int
+    input_indices: List[int]
+
+
+@dataclass
+class JudgeMeta(BaseMeta):
+    """Metadata for bestOf judge."""
+    candidate_count: int
+
+
+@dataclass
+class VerifyMeta(BaseMeta):
+    """Metadata for verify operation."""
+    attempts: int
+    """Total verification attempts made."""
+
+
+# =============================================================================
+# PROMPT TYPES
+# =============================================================================
+
+PromptFn = Callable[[FileMap, int], str]
+Prompt = Union[str, PromptFn]
+
+
+# =============================================================================
+# ITEM INPUT (for chaining)
+# =============================================================================
+
+# Forward reference - actual SwarmResult defined in results.py
+# ItemInput can be a FileMap or a SwarmResult from a previous operation
+ItemInput = Union[FileMap, Any]  # Any here will be SwarmResult at runtime
+
+
+# =============================================================================
+# SCHEMA TYPE
+# =============================================================================
+
+# Schema can be a Pydantic model, dataclass, or JSON Schema dict
+SchemaType = Union[Type[Any], Dict[str, Any]]
+
+
+# =============================================================================
+# JUDGE DECISION
+# =============================================================================
+
+@dataclass
+class JudgeDecision:
+    """Fixed schema for bestOf judge output."""
+    winner: int
+    reasoning: str
+
+
+@dataclass
+class VerifyDecision:
+    """Fixed schema for verify output."""
+    passed: bool
+    reasoning: str
+    feedback: Optional[str] = None

swarmkit/utils.py

@@ -0,0 +1,82 @@
+"""File utilities for SwarmKit SDK."""
+
+import base64
+import os
+from pathlib import Path
+from typing import Any, Dict, Union
+
+
+def _filter_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    """Filter out None values from a dict. Used for building RPC params."""
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _encode_files_for_transport(
+    files: Dict[str, Union[str, bytes]]
+) -> Dict[str, Dict[str, str]]:
+    """Encode files dict for JSON-RPC transport.
+
+    Handles both text (str) and binary (bytes) content with appropriate encoding.
+    Uses 'content' field consistently for both input and output files.
+    """
+    result = {}
+    for name, file_content in files.items():
+        if isinstance(file_content, bytes):
+            result[name] = {
+                'content': base64.b64encode(file_content).decode('utf-8'),
+                'encoding': 'base64'
+            }
+        else:
+            result[name] = {'content': file_content, 'encoding': 'text'}
+    return result
+
+
+def read_local_dir(local_path: str, recursive: bool = False) -> Dict[str, bytes]:
+    """Read files from a local directory into a dict for upload.
+
+    Args:
+        local_path: Path to local directory
+        recursive: Include subdirectories (default: False)
+
+    Returns:
+        Dict mapping relative paths to file content as bytes
+    """
+    result: Dict[str, bytes] = {}
+    root = Path(local_path)
+
+    paths = root.rglob('*') if recursive else root.iterdir()
+
+    for p in paths:
+        if p.is_file():
+            result[str(p.relative_to(root))] = p.read_bytes()
+
+    return result
+
+
+def save_local_dir(local_path: str, files: Dict[str, Union[str, bytes]]) -> None:
+    """Save files dict to a local directory, creating nested directories as needed.
+
+    Args:
+        local_path: Base directory to save files to
+        files: Dict mapping relative paths to content (from get_output_files().files or other source)
+
+    Example:
+        >>> output = await agent.get_output_files(recursive=True)
+        >>> save_local_dir('./output', output.files)
+        # Creates: ./output/file.txt, ./output/subdir/nested.txt, etc.
+    """
+    for name, content in files.items():
+        file_path = os.path.join(local_path, name)
+        parent = os.path.dirname(file_path)
+
+        # Create parent directories if needed
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+
+        # Write content
+        if isinstance(content, bytes):
+            with open(file_path, 'wb') as f:
+                f.write(content)
+        else:
+            with open(file_path, 'w', encoding='utf-8') as f:
+                f.write(content)

swarmkit-0.1.34.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: swarmkit
+Version: 0.1.34
+Summary: Pythonic wrapper around the TypeScript SwarmKit SDK for multi-agent orchestration in E2B sandboxes
+Author-email: "Swarmlink, Inc." <brandomagnani@swarmlink.ai>
+License: Proprietary Beta Evaluation License - See LICENSE file
+Project-URL: Homepage, https://github.com/brandomagnani/swarmkit.git
+Project-URL: Repository, https://github.com/brandomagnani/swarmkit.git
+Keywords: ai,agents,sandbox,e2b,orchestration,codex,claude,gemini
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# SwarmKit Python SDK
+
+SwarmKit lets you run and orchestrate terminal-based AI agents in secure sandboxes with built-in observability.
+
+## Get Started
+
+1. Get your **SwarmKit API key** at [dashboard.swarmlink.ai](https://dashboard.swarmlink.ai/) (new users: [request access](https://dashboard.swarmlink.ai/request-access) first)
+
+2. Get an **E2B API key** at [e2b.dev](https://e2b.dev) for sandbox execution
+
+3. Install the SDK:
+   ```bash
+   pip install swarmkit
+   ```
+   **Note:** Requires [Node.js 18+](https://nodejs.org/) (the SDK uses a lightweight Node.js bridge).
+
+4. Check out the [official documentation](https://github.com/brandomagnani/swarmkit/tree/main/docs) and [cookbooks](https://github.com/brandomagnani/swarmkit/tree/main/cookbooks) to start shipping with SwarmKit!
+
+## Streaming Events
+
+You can subscribe to streaming events:
+
+- `stdout`: Raw NDJSON output from the agent/CLI (may arrive in chunks).
+- `stderr`: Process stderr (may arrive in chunks).
+- `content`: Parsed ACP-style events (messages, tool calls, plan updates).
+
+### Large Outputs
+
+The Node bridge enforces per-event size limits for responsiveness.
+
+- `stdout`/`stderr` are chunked when very large; your callback receives each chunk normally.
+- `content` events are lossless: if a payload is too large to stream safely, you receive a truncated preview plus a `ref` to a local JSON file containing the full payload.
+
+Example:
+
+```py
+def on_content(evt):
+    if evt.get("truncated") and evt.get("ref"):
+        full_update = open(evt["ref"]["path"], "r", encoding="utf-8").read()
+        # full_update is the original ACP update JSON
+
+swarmkit.on("content", on_content)
+```
+
+## Reporting Bugs
+
+We welcome your feedback. File a [GitHub issue](https://github.com/brandomagnani/swarmkit/issues) to report bugs or request features.
+
+## Connect on Discord
+
+Join the [SwarmKit Developers Discord](https://discord.gg/Q36D8dGyNF) to connect with other developers using SwarmKit. Get help, share feedback, and discuss your projects with the community.
+
+## License
+
+See [LICENSE](https://github.com/brandomagnani/swarmkit/blob/main/LICENSE) for details.

swarmkit-0.1.34.dist-info/RECORD

@@ -0,0 +1,29 @@
+bridge/__init__.py,sha256=oakDP-wspBW61TEuKMKb4fwHRWqX0MJMtwJONqk_664,165
+bridge/dist/bridge.bundle.cjs,sha256=4Sng2mj48hT9SRQvB962vVZXSaaeBOfDjBWX04KFuBE,3170378
+swarmkit/__init__.py,sha256=Bftb7kCJLI48PhkCpQzGxAbbjlVscIaD_krgjNVgTvE,3048
+swarmkit/agent.py,sha256=LMJZJ_shgrXG4T3twYa3fpH8K8NTsuYwgxL7t40IpX8,18265
+swarmkit/bridge.py,sha256=u6MK4Q3RTqjFwHDgic0u0pHL4wOVMq2MzHynL-oR8CY,17546
+swarmkit/config.py,sha256=0WXesMF1RuoHEQ0-0XDDunMe_dJy-0qocAxoEG2f5Ck,2687
+swarmkit/results.py,sha256=aP4TvXDfk75AQCt1GVuiMn3nMi-fhWLOJpaSQ6fcCH4,1245
+swarmkit/retry.py,sha256=8yeqW4qogNpf1tTCts-XrC5jVzvlFp1Crg12qrFTeTA,4631
+swarmkit/schema.py,sha256=hmmpBxdsI7FWNf7Gd8dDhIWICwVcowodMQ0mKiu9_xs,2988
+swarmkit/utils.py,sha256=h7o9hisfFSHhmqzNDT5ZSpAeLCyudayT14BT8W_O-Pw,2638
+swarmkit/pipeline/__init__.py,sha256=FfRHkWeY1p7YruUJ9cqKlO64mkOngKyxi3GRaADU0ns,1134
+swarmkit/pipeline/pipeline.py,sha256=dPcOZM7WgmzfwtsMJmntwCJdY1dAG8ZCWxw0Bmw--bk,18756
+swarmkit/pipeline/types.py,sha256=UfnMjfQZGqr6Z5IwnzNTw2K67pVeiYCDRd30PDDnzkA,7816
+swarmkit/prompts/__init__.py,sha256=k9eJNq4NlaZvgGWLH6KPfT0UxI4jLqanJHWV_Jx7VvQ,4731
+swarmkit/prompts/agent_md/judge.md,sha256=RbBH58q-A_7ZyG3vMGEMMUI1V7owhvK17qAnjkFPdQs,1019
+swarmkit/prompts/agent_md/reduce.md,sha256=nzG5cuIfoHhp-m80Z2CUA9kBYjggtagX1tA_ERPx2rs,117
+swarmkit/prompts/agent_md/verify.md,sha256=96tNr4UOp8c64xqC6kSJPnH4RHW27l88oJRsU8lUYAY,1012
+swarmkit/prompts/user/judge.md,sha256=voZSLTXCte2-94D_Wx0JrCPKjv093DBrnBrnkzQy5Tg,111
+swarmkit/prompts/user/retry_feedback.md,sha256=-dUWfAbknKsrPArHd38jE1ShQ-3quKInrhcm6x1W4fc,237
+swarmkit/prompts/user/verify.md,sha256=Tuq8FQotrBTFOm_lngEpNx8j7l12J96QrVKPnmuxQpU,109
+swarmkit/swarm/__init__.py,sha256=3qLm8TqAPbcpXH7vuWLr3IqJ7bUj9hz_qpCdTjBjln4,1430
+swarmkit/swarm/results.py,sha256=vNWCOkJ_fnEUsCipWq7xAADxg4hJdV3Wh4YI57drR8s,4516
+swarmkit/swarm/swarm.py,sha256=196wqLvgWzl94WIGwx1E3Uc1Wp6KbdUeEwpS8nlHnvs,66672
+swarmkit/swarm/types.py,sha256=JDNGcGXOnyzKmmahFlwmOZ_0xhyk3Of64e_A02EMZY4,6128
+swarmkit-0.1.34.dist-info/licenses/LICENSE,sha256=QLecPBFjABXODzKI22IEci6OaBCjpOVdCYgtmXVKXBY,799
+swarmkit-0.1.34.dist-info/METADATA,sha256=MgYFx84vA-mv1k3aHtlKmNFSq4JLGO9C9rtmP97Q_bY,3258
+swarmkit-0.1.34.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+swarmkit-0.1.34.dist-info/top_level.txt,sha256=-3mxmF3ggfuPa9StJHAdsaGjGmb26BhWwKs6s2kjz74,16
+swarmkit-0.1.34.dist-info/RECORD,,

swarmkit-0.1.34.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

swarmkit-0.1.34.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+SWARMKIT PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2025 Swarmlink, Inc. All rights reserved.
+
+BETA EVALUATION LICENSE
+
+The SwarmKit SDK is provided for evaluation and beta testing purposes only.
+
+PERMITTED:
+- Install SwarmKit via npm/PyPI for evaluation and development
+- Build applications using the SwarmKit SDK during the beta period
+- Deploy applications using the SwarmKit SDK to production
+
+PROHIBITED:
+- Redistribute the SwarmKit SDK itself
+- Reverse engineer, decompile, or extract source code from the SDK
+- Create derivative works of the SwarmKit SDK
+- Use SwarmKit in competing products or services
+
+NO WARRANTY. THIS SOFTWARE IS PROVIDED "AS IS" FOR BETA EVALUATION.
+
+This license may be revised upon general availability.
+
+For licensing inquiries, contact: brandomagnani@swarmlink.ai

swarmkit-0.1.34.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+bridge
+swarmkit