fleet-python 0.1.0__py3-none-any.whl

examples/quickstart.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+Fleet SDK Quickstart Example.
+
+This example demonstrates basic usage of the Fleet SDK for environment management.
+"""
+
+import asyncio
+import logging
+from typing import Dict, Any
+
+import fleet
+
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+async def main():
+    """Main example function."""
+    
+    # Check API health
+    print("🔍 Checking Fleet API health...")
+    try:
+        config = fleet.get_config()
+        client = fleet.FleetAPIClient(config)
+        health = await client.health_check()
+        print(f"✅ API Status: {health.status}")
+        await client.close()
+    except Exception as e:
+        print(f"❌ API Health Check failed: {e}")
+        return
+    
+    # 1. List available environments
+    print("\n📋 Available environments:")
+    try:
+        environments = await fleet.env.list_envs()
+        for env in environments:
+            print(f"  - {env.env_key}: {env.name}")
+            print(f"    Description: {env.description}")
+            print(f"    Default version: {env.default_version}")
+            print(f"    Available versions: {', '.join(env.versions.keys())}")
+    except Exception as e:
+        print(f"❌ Failed to list environments: {e}")
+        return
+    
+    # 2. Create a new environment instance
+    print("\n🚀 Creating new environment...")
+    try:
+        env = await fleet.env.make("fira:v1.2.5", region="us-west-1")
+        print(f"✅ Environment created with instance ID: {env.instance_id}")
+        
+        # Execute a simple action
+        print("\n⚡ Executing a simple action...")
+        action = {"type": "test", "data": {"message": "Hello Fleet!"}}
+        state, reward, done = await env.step(action)
+        print(f"✅ Action executed successfully!")
+        print(f"   Reward: {reward}")
+        print(f"   Done: {done}")
+        print(f"   State keys: {list(state.keys())}")
+        
+        # Check manager API health
+        print("\n🏥 Checking manager API health...")
+        try:
+            manager_health = await env.manager_health_check()
+            if manager_health:
+                print(f"✅ Manager API Status: {manager_health.status}")
+                print(f"   Service: {manager_health.service}")
+                print(f"   Timestamp: {manager_health.timestamp}")
+            else:
+                print("❌ Manager API not available")
+        except Exception as e:
+            print(f"❌ Manager health check failed: {e}")
+        
+        # Clean up
+        print("\n🧹 Cleaning up...")
+        await env.close()
+        print("✅ Environment closed")
+        
+    except Exception as e:
+        print(f"❌ Environment creation failed: {e}")
+        return
+    
+    # 3. List running instances
+    print("\n🏃 Listing running instances...")
+    try:
+        instances = await fleet.env.list_instances(status="running")
+        if instances:
+            print(f"Found {len(instances)} running instances:")
+            for instance in instances:
+                print(f"  - {instance.instance_id}: {instance.env_key} ({instance.status})")
+        else:
+            print("No running instances found")
+    except Exception as e:
+        print(f"❌ Failed to list instances: {e}")
+    
+    # 4. Connect to an existing instance (if any)
+    print("\n🔗 Connecting to existing instance...")
+    try:
+        # Only get running instances
+        running_instances = await fleet.env.list_instances(status="running")
+        if running_instances:
+            # Find a running instance that's not the one we just created/deleted
+            target_instance = running_instances[0]
+            print(f"Connecting to running instance: {target_instance.instance_id}")
+            
+            env = await fleet.env.get(target_instance.instance_id)
+            print(f"✅ Connected to instance: {env.instance_id}")
+            
+            # Execute an action on the existing instance
+            action = {"type": "ping", "data": {"timestamp": "2024-01-01T00:00:00Z"}}
+            state, reward, done = await env.step(action)
+            print(f"✅ Action executed on existing instance!")
+            print(f"   Reward: {reward}")
+            print(f"   Done: {done}")
+            
+            # Clean up (this will delete the instance)
+            await env.close()
+            print("✅ Connection closed (instance deleted)")
+        else:
+            print("No running instances to connect to")
+    except Exception as e:
+        print(f"❌ Failed to connect to existing instance: {e}")
+    
+    print("\n🎉 Quickstart complete!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main()) 

fleet/__init__.py

@@ -0,0 +1,42 @@
+# Copyright 2025 Fleet AI
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Fleet Python SDK - Environment-based AI agent interactions."""
+
+from . import env
+from .exceptions import FleetError, FleetAPIError, FleetTimeoutError, FleetConfigurationError
+from .config import get_config, FleetConfig
+from .client import FleetAPIClient, InstanceRequest, InstanceResponse, EnvDetails as APIEnvironment, HealthResponse, ManagerURLs, InstanceURLs
+from .manager_client import FleetManagerClient, ManagerHealthResponse, TimestampResponse
+
+__version__ = "0.1.0"
+__all__ = [
+    "env",
+    "FleetError",
+    "FleetAPIError", 
+    "FleetTimeoutError",
+    "FleetConfigurationError",
+    "get_config",
+    "FleetConfig",
+    "FleetAPIClient",
+    "InstanceRequest",
+    "InstanceResponse",
+    "APIEnvironment",
+    "HealthResponse",
+    "ManagerURLs",
+    "InstanceURLs",
+    "FleetManagerClient",
+    "ManagerHealthResponse",
+    "TimestampResponse",
+] 

fleet/client.py

@@ -0,0 +1,318 @@
+# Copyright 2025 Fleet AI
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Fleet API Client for making HTTP requests to Fleet services."""
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional, Union
+from datetime import datetime
+import aiohttp
+from pydantic import BaseModel, Field
+
+from .config import FleetConfig
+from .exceptions import (
+    FleetAPIError,
+    FleetAuthenticationError,
+    FleetRateLimitError,
+    FleetTimeoutError,
+    FleetError,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class InstanceRequest(BaseModel):
+    """Request model for creating instances."""
+    
+    env_key: str = Field(..., description="Environment key to create instance for")
+    version: Optional[str] = Field(None, description="Version of the environment")
+    region: Optional[str] = Field("us-west-1", description="AWS region")
+    seed: Optional[int] = Field(None, description="Random seed for deterministic behavior")
+    timestamp: Optional[int] = Field(None, description="Timestamp for environment state")
+    p_error: Optional[float] = Field(None, description="Error probability")
+    avg_latency: Optional[float] = Field(None, description="Average latency")
+    run_id: Optional[str] = Field(None, description="Run ID for tracking")
+    task_id: Optional[str] = Field(None, description="Task ID for tracking")
+
+
+class ManagerURLs(BaseModel):
+    """Model for manager API URLs."""
+    
+    api: str = Field(..., description="Manager API URL")
+    docs: str = Field(..., description="Manager docs URL")
+    reset: str = Field(..., description="Reset URL")
+    diff: str = Field(..., description="Diff URL")
+    snapshot: str = Field(..., description="Snapshot URL")
+    execute_verifier_function: str = Field(..., description="Execute verifier function URL")
+    execute_verifier_function_with_upload: str = Field(..., description="Execute verifier function with upload URL")
+
+
+class InstanceURLs(BaseModel):
+    """Model for instance URLs."""
+    
+    root: str = Field(..., description="Root URL")
+    app: str = Field(..., description="App URL")
+    api: Optional[str] = Field(None, description="API URL")
+    health: Optional[str] = Field(None, description="Health check URL")
+    api_docs: Optional[str] = Field(None, description="API documentation URL")
+    manager: ManagerURLs = Field(..., description="Manager API URLs")
+
+
+class InstanceResponse(BaseModel):
+    """Response model for instance operations."""
+    
+    instance_id: str = Field(..., description="Instance ID")
+    env_key: str = Field(..., description="Environment key")
+    version: str = Field(..., description="Environment version")
+    status: str = Field(..., description="Instance status")
+    subdomain: str = Field(..., description="Instance subdomain")
+    created_at: str = Field(..., description="Creation timestamp")
+    updated_at: str = Field(..., description="Last update timestamp")
+    terminated_at: Optional[str] = Field(None, description="Termination timestamp")
+    team_id: str = Field(..., description="Team ID")
+    region: str = Field(..., description="AWS region")
+    urls: InstanceURLs = Field(..., description="Instance URLs")
+    health: Optional[bool] = Field(None, description="Health status")
+
+
+class EnvDetails(BaseModel):
+    """Model for environment details and metadata."""
+    
+    env_key: str = Field(..., description="Environment key")
+    name: str = Field(..., description="Environment name")
+    description: Optional[str] = Field(..., description="Environment description")
+    default_version: Optional[str] = Field(..., description="Default version")
+    versions: Dict[str, str] = Field(..., description="Available versions")
+
+
+class HealthResponse(BaseModel):
+    """Response model for health checks."""
+    
+    status: str = Field(..., description="Health status")
+    timestamp: str = Field(..., description="Timestamp")
+    mode: str = Field(..., description="Operation mode")
+    region: str = Field(..., description="AWS region")
+    docker_status: str = Field(..., description="Docker status")
+    docker_error: Optional[str] = Field(None, description="Docker error if any")
+    instances: int = Field(..., description="Number of instances")
+    regions: Optional[Dict[str, "HealthResponse"]] = Field(None, description="Regional health info")
+
+
+class FleetAPIClient:
+    """Client for making requests to the Fleet API."""
+    
+    def __init__(self, config: FleetConfig):
+        """Initialize the Fleet API client.
+        
+        Args:
+            config: Fleet configuration with API key and base URL
+        """
+        self.config = config
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._base_url = config.base_url
+        
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self._ensure_session()
+        return self
+        
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+        
+    async def _ensure_session(self):
+        """Ensure HTTP session is created."""
+        if self._session is None or self._session.closed:
+            headers = {}
+            if self.config.api_key:
+                headers["Authorization"] = f"Bearer {self.config.api_key}"
+                
+            timeout = aiohttp.ClientTimeout(total=60)
+            self._session = aiohttp.ClientSession(
+                headers=headers,
+                timeout=timeout,
+                connector=aiohttp.TCPConnector(limit=100),
+            )
+            
+    async def close(self):
+        """Close the HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self._session = None
+            
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Make an HTTP request to the Fleet API.
+        
+        Args:
+            method: HTTP method (GET, POST, DELETE, etc.)
+            path: API endpoint path
+            data: Request body data
+            params: Query parameters
+            headers: Additional headers
+            timeout: Request timeout in seconds
+            
+        Returns:
+            Response data as dictionary
+            
+        Raises:
+            FleetAPIError: If the API returns an error
+            FleetAuthenticationError: If authentication fails
+            FleetRateLimitError: If rate limit is exceeded
+            FleetTimeoutError: If request times out
+        """
+        await self._ensure_session()
+        
+        url = f"{self._base_url}{path}"
+        request_headers = headers or {}
+        
+        try:
+            logger.debug(f"Making {method} request to {url}")
+            
+            async with self._session.request(
+                method=method,
+                url=url,
+                json=data,
+                params=params,
+                headers=request_headers,
+                timeout=aiohttp.ClientTimeout(total=timeout or 60),
+            ) as response:
+                response_data = await response.json() if response.content_type == "application/json" else {}
+                
+                if response.status == 200:
+                    logger.debug(f"Request successful: {response.status}")
+                    return response_data
+                    
+                elif response.status == 401:
+                    raise FleetAuthenticationError("Authentication failed - check your API key")
+                    
+                elif response.status == 429:
+                    raise FleetRateLimitError("Rate limit exceeded - please retry later")
+                    
+                else:
+                    error_message = response_data.get("detail", f"API request failed with status {response.status}")
+                    raise FleetAPIError(
+                        error_message,
+                        status_code=response.status,
+                        response_data=response_data,
+                    )
+                    
+        except asyncio.TimeoutError:
+            raise FleetTimeoutError(f"Request to {url} timed out")
+            
+        except aiohttp.ClientError as e:
+            raise FleetAPIError(f"HTTP client error: {e}")
+            
+    # Environment operations
+    async def list_environments(self) -> List[EnvDetails]:
+        """List all available environments.
+        
+        Returns:
+            List of EnvDetails objects
+        """
+        response = await self._request("GET", "/v1/env/")
+        return [EnvDetails(**env_data) for env_data in response]
+        
+    async def get_environment(self, env_key: str) -> EnvDetails:
+        """Get details for a specific environment.
+        
+        Args:
+            env_key: Environment key
+            
+        Returns:
+            EnvDetails object
+        """
+        response = await self._request("GET", f"/v1/env/{env_key}")
+        return EnvDetails(**response)
+        
+    # Instance operations
+    async def create_instance(self, request: InstanceRequest) -> InstanceResponse:
+        """Create a new environment instance.
+        
+        Args:
+            request: Instance creation request
+            
+        Returns:
+            InstanceResponse object
+        """
+        response = await self._request("POST", "/v1/env/instances", data=request.model_dump(exclude_none=True))
+        return InstanceResponse(**response)
+        
+    async def list_instances(self, status: Optional[str] = None) -> List[InstanceResponse]:
+        """List all instances, optionally filtered by status.
+        
+        Args:
+            status: Optional status filter (pending, running, stopped, error)
+            
+        Returns:
+            List of InstanceResponse objects
+        """
+        params = {}
+        if status:
+            params["status"] = status
+            
+        response = await self._request("GET", "/v1/env/instances", params=params)
+        return [InstanceResponse(**instance_data) for instance_data in response]
+        
+    async def get_instance(self, instance_id: str) -> InstanceResponse:
+        """Get details for a specific instance.
+        
+        Args:
+            instance_id: Instance ID
+            
+        Returns:
+            InstanceResponse object
+        """
+        response = await self._request("GET", f"/v1/env/instances/{instance_id}")
+        return InstanceResponse(**response)
+        
+    async def delete_instance(self, instance_id: str) -> Dict[str, Any]:
+        """Delete an instance.
+        
+        Args:
+            instance_id: Instance ID
+            
+        Returns:
+            Deletion response data
+        """
+        response = await self._request("DELETE", f"/v1/env/instances/{instance_id}")
+        return response
+        
+    # Health check operations
+    async def health_check(self) -> HealthResponse:
+        """Check the health of the Fleet API.
+        
+        Returns:
+            HealthResponse object
+        """
+        response = await self._request("GET", "/health")
+        return HealthResponse(**response)
+        
+    async def health_check_simple(self) -> HealthResponse:
+        """Simple health check without authentication.
+        
+        Returns:
+            HealthResponse object
+        """
+        response = await self._request("GET", "/health-check")
+        return HealthResponse(**response) 

fleet/config.py

@@ -0,0 +1,125 @@
+"""Fleet SDK Configuration Management."""
+
+import os
+import logging
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, Field, validator
+from .exceptions import FleetAuthenticationError, FleetConfigurationError
+
+
+logger = logging.getLogger(__name__)
+
+
+class FleetConfig(BaseModel):
+    """Fleet SDK Configuration."""
+    
+    api_key: Optional[str] = Field(None, description="Fleet API key")
+    base_url: str = Field(default="https://fleet.new", description="Fleet API base URL (hardcoded)")
+    
+    @validator('api_key')
+    def validate_api_key(cls, v):
+        """Validate API key format."""
+        if v is not None and not _is_valid_api_key(v):
+            raise FleetAuthenticationError(
+                "Invalid API key format. Fleet API keys should start with 'sk_' followed by alphanumeric characters."
+            )
+        return v
+    
+    @validator('base_url')
+    def validate_base_url(cls, v):
+        """Validate base URL format."""
+        if not v.startswith(('http://', 'https://')):
+            raise FleetConfigurationError("Base URL must start with 'http://' or 'https://'")
+        return v.rstrip('/')
+    
+    def mask_sensitive_data(self) -> Dict[str, Any]:
+        """Return config dict with sensitive data masked."""
+        data = self.dict()
+        if data.get('api_key'):
+            data['api_key'] = _mask_api_key(data['api_key'])
+        return data
+    
+    class Config:
+        """Pydantic configuration."""
+        extra = 'allow'
+
+
+def get_config(**kwargs: Any) -> FleetConfig:
+    """Get Fleet configuration from environment variables.
+    
+    Loads FLEET_API_KEY from environment variables. The base URL is hardcoded to https://fleet.new.
+    
+    Args:
+        **kwargs: Override specific configuration values
+        
+    Returns:
+        FleetConfig instance
+        
+    Raises:
+        FleetAuthenticationError: If API key is invalid
+        FleetConfigurationError: If configuration is invalid
+    """
+    # Load from environment variables
+    config_data = _load_env_config()
+    
+    # Apply any overrides
+    config_data.update(kwargs)
+    
+    # Create and validate configuration
+    try:
+        config = FleetConfig(**config_data)
+        return config
+        
+    except Exception as e:
+        if isinstance(e, (FleetAuthenticationError, FleetConfigurationError)):
+            raise
+        raise FleetConfigurationError(f"Invalid configuration: {e}")
+
+
+def _load_env_config() -> Dict[str, Any]:
+    """Load configuration from environment variables."""
+    env_mapping = {
+        'FLEET_API_KEY': 'api_key',
+        # base_url is hardcoded, not configurable via env var
+    }
+    
+    config = {}
+    for env_var, config_key in env_mapping.items():
+        value = os.getenv(env_var)
+        if value is not None:
+            config[config_key] = value
+    
+    return config
+
+
+def _is_valid_api_key(api_key: str) -> bool:
+    """Validate API key format."""
+    if not api_key:
+        return False
+    
+    # Fleet API keys start with 'sk_' followed by alphanumeric characters
+    # This is a basic format check - actual validation happens on the server
+    if not api_key.startswith('sk_'):
+        return False
+    
+    # Check if the rest contains only alphanumeric characters and underscores
+    key_part = api_key[3:]  # Remove 'sk_' prefix
+    if not key_part or not key_part.replace('_', '').isalnum():
+        return False
+    
+    # Minimum length check
+    if len(api_key) < 20:
+        return False
+    
+    return True
+
+
+def _mask_api_key(api_key: str) -> str:
+    """Mask API key for logging."""
+    if not api_key:
+        return api_key
+    
+    if len(api_key) < 8:
+        return '*' * len(api_key)
+    
+    return api_key[:4] + '*' * (len(api_key) - 8) + api_key[-4:] 

fleet/env/__init__.py

@@ -0,0 +1,30 @@
+"""Fleet SDK Environment Module."""
+
+from .base import Environment, EnvironmentConfig
+from .factory import (
+    make, 
+    get, 
+    list_instances, 
+    list_envs, 
+    list_environments,
+    list_categories,
+    list_names,
+    list_versions,
+    is_environment_supported,
+    EnvironmentInstance
+)
+
+__all__ = [
+    "Environment",
+    "EnvironmentConfig", 
+    "EnvironmentInstance",
+    "make",
+    "get",
+    "list_instances",
+    "list_envs",
+    "list_environments",
+    "list_categories",
+    "list_names",
+    "list_versions",
+    "is_environment_supported",
+]