anyscale 0.26.49__tar.gz → 0.26.51__tar.gz

anyscale-0.26.51/.cursor/api-client.mdc

@@ -0,0 +1,189 @@
+---
+type: auto-attached
+globs:
+  - "**/anyscale_client/**/*.py"
+  - "**/openapi_client/**/*.py"
+  - "**/anyscale/client/**/*.py"
+description: OpenAPI client generation and API integration patterns
+---
+
+# API Client Integration
+
+## Client Generation
+
+### Regenerate After Backend Changes
+```bash
+cd frontend/web
+npm run build-api
+
+# Generates:
+# - anyscale/client/openapi_client/  # Internal API
+# - anyscale/sdk/anyscale_client/    # External API
+```
+
+**Never edit generated code** - Always regenerate.
+
+## Using the Client
+
+### ✅ Correct Usage
+```python
+# Use the wrapper
+from anyscale._private.anyscale_client import get_default_client
+client = get_default_client()
+result = client.create_service(name="my-service")
+```
+
+### ❌ Wrong Usage
+```python
+# Never use generated clients directly
+from anyscale.client.openapi_client.api import DefaultApi
+api = DefaultApi()  # Wrong!
+```
+
+## Adding New Endpoints
+
+### 1. Backend First
+```python
+# backend/server/api/product/routers/my_router.py
+@router.post("/my-endpoint")
+async def my_endpoint(request: MyRequest) -> MyResponse:
+    pass
+```
+
+### 2. Regenerate Clients
+```bash
+cd frontend/web && npm run build-api
+```
+
+### 3. Extend AnyscaleClient
+
+**Step 1: Interface** (`common.py`)
+```python
+@abstractmethod
+def new_method(self, param: str) -> ResultType:
+    raise NotImplementedError
+```
+
+**Step 2: Implementation** (`anyscale_client.py`)
+```python
+@handle_api_exceptions
+def new_method(self, param: str) -> ResultType:
+    # Client decides internally whether to use
+    # _internal_api_client or _external_api_client
+    return self._appropriate_api.endpoint(param)
+```
+
+**Step 3: Fake Client** (`fake_anyscale_client.py`)
+```python
+def new_method(self, param: str) -> ResultType:
+    return FakeResult()
+```
+
+### 4. Use in SDK
+```python
+class PrivateModuleSDK:
+    def __init__(self, client: AnyscaleClientInterface):
+        self.client = client
+
+    def my_method(self, param: str):
+        # ✅ Use interface method
+        return self.client.new_method(param)
+
+        # ❌ Never access internal APIs directly
+        # return self.client._internal_api_client.endpoint()
+```
+
+## Key Principle
+
+**SDK code should NEVER know about internal vs external APIs**. The AnyscaleClient handles this distinction internally.
+
+## Error Handling
+
+```python
+from anyscale._private.anyscale_client import handle_api_exceptions
+
+@handle_api_exceptions  # Handles common API errors
+def api_method(self, **kwargs):
+    return self.api.endpoint(**kwargs)
+
+# Manual handling for specific cases
+try:
+    result = api.create_resource(data)
+except ApiException as e:
+    if e.status == 404:
+        raise ResourceNotFoundError(f"Not found: {e.body}")
+    elif e.status == 409:
+        raise ConflictError(f"Already exists: {e.body}")
+    raise
+```
+
+## Common Patterns
+
+### Pagination
+```python
+def list_all(client):
+    all_items = []
+    next_token = None
+
+    while True:
+        response = client.list_resources(
+            limit=100,
+            next_token=next_token
+        )
+        all_items.extend(response.items)
+
+        if not response.next_token:
+            break
+        next_token = response.next_token
+
+    return all_items
+```
+
+### Status Polling
+```python
+def wait_for_ready(resource_id, client, timeout=300):
+    start = time.time()
+
+    while time.time() - start < timeout:
+        resource = client.get_resource(resource_id)
+
+        if resource.status == "READY":
+            return resource
+
+        if resource.status in ["FAILED", "ERROR"]:
+            raise Exception(f"Failed: {resource.error}")
+
+        time.sleep(5)
+
+    raise TimeoutError(f"Timeout: {resource_id}")
+```
+
+## Testing
+
+```python
+@pytest.fixture
+def mock_client():
+    client = Mock()
+    client.create_service.return_value = {
+        "id": "srv_123",
+        "name": "test-service"
+    }
+    return client
+
+def test_with_mock(mock_client):
+    result = create_service("test", client=mock_client)
+    mock_client.create_service.assert_called_once()
+```
+
+## Troubleshooting
+
+```bash
+# Clean regenerate
+cd frontend/web
+rm -rf ../cli/anyscale/client/openapi_client
+rm -rf ../cli/anyscale/sdk/anyscale_client
+npm run build-api
+
+# Check imports
+python -c "from anyscale.client.openapi_client import __version__; print(__version__)"
+```

anyscale-0.26.51/.cursor/architecture.mdc

@@ -0,0 +1,125 @@
+---
+type: agent-requested
+description: System architecture and data flow patterns for the Anyscale CLI
+---
+
+# Architecture
+
+## Layered Design
+
+```
+User → CLI (Click) → SDK → AnyscaleClient → OpenAPI Clients → Backend API
+                       ↓
+                   Telemetry
+```
+
+## Core Components
+
+### CLI Layer (`anyscale/commands/`)
+- Click-based command interface
+- Argument parsing and validation
+- User-friendly error formatting
+
+### SDK Layer (`anyscale/*/commands.py`)
+- Business logic and API orchestration
+- Typed, importable Python functions
+- Used by CLI and external users
+
+### Client Layer (`anyscale/_private/anyscale_client/`)
+- Wraps auto-generated OpenAPI clients
+- Handles auth and error normalization
+- Provides consistent API interface
+
+### Generated Clients
+- Auto-generated from FastAPI specs
+- Located in `anyscale/client/openapi_client/`
+- Regenerate: `cd frontend/web && npm run build-api`
+
+## Directory Structure
+
+```
+frontend/cli/
+├── anyscale/
+│   ├── commands/           # CLI commands (Click)
+│   ├── */commands.py       # SDK functions per module
+│   ├── */models.py         # Pydantic models
+│   ├── _private/
+│   │   └── anyscale_client/  # Client wrapper
+│   └── telemetry.py        # Usage tracking
+├── tests/
+│   └── unit/              # Unit tests
+└── .cursor/               # Dev documentation
+```
+
+## Data Flow
+
+1. **User** → `anyscale service deploy`
+2. **CLI** → Parses args, validates
+3. **SDK** → Business logic, orchestration
+4. **Client** → Auth, API call, error handling
+5. **Response** → Flows back up, formatted for user
+6. **Telemetry** → Records operation in background
+
+## Key Principles
+
+1. **SDK-first**: Business logic in SDK, CLI is thin wrapper
+2. **Type safety**: Full type hints throughout
+3. **Error hierarchy**: API → Client → SDK → CLI
+4. **Never edit generated code**: Regenerate instead
+
+## Dependencies
+
+```
+CLI → SDK → Client → Generated
+        ↓
+     Models
+```
+
+## Common Patterns
+
+### SDK Function
+```python
+@sdk_command(singleton_key, SDKClass)
+def operation(param: str, *, optional: Optional[str] = None) -> Model:
+    """SDK operations are typed and testable."""
+    return _private_sdk.do_operation(param, optional)
+```
+
+### CLI Command
+```python
+@click.command()
+@click.option("--param", required=True)
+def command(param: str):
+    """CLI wraps SDK, handles formatting."""
+    try:
+        result = sdk.operation(param)
+        click.echo(format_output(result))
+    except Exception as e:
+        raise click.ClickException(str(e))
+```
+
+## AnyscaleClient Extension
+
+When adding new API calls:
+
+1. **Add to interface** (`common.py`)
+   ```python
+   @abstractmethod
+   def new_method(self, param: str) -> ResultType:
+       raise NotImplementedError
+   ```
+
+2. **Implement in client** (`anyscale_client.py`)
+   ```python
+   @handle_api_exceptions
+   def new_method(self, param: str) -> ResultType:
+       return self._api.endpoint(param)
+   ```
+
+3. **Add to fake client** (`fake_anyscale_client.py`)
+   ```python
+   def new_method(self, param: str) -> ResultType:
+       return FakeResult()
+   ```
+
+4. **Write tests** - All three must be updated together

anyscale-0.26.51/.cursor/authentication.mdc

@@ -0,0 +1,152 @@
+---
+type: auto-attached
+globs:
+  - "**/authenticate.py"
+  - "**/auth*.py"
+  - "**/controllers/auth_*.py"
+description: Authentication flow and credential management
+---
+
+# Authentication
+
+## How Auth Works
+
+```
+User Token → CLI → API Client → Backend
+      ↓
+Stored in ~/.anyscale/credentials.json
+or ANYSCALE_CLI_TOKEN env var
+```
+
+## Credential Storage
+
+### File Storage
+- Path: `~/.anyscale/credentials.json`
+- Permissions: `0600` (user only)
+- Format: `{"cli_token": "ast_..."}`
+
+### Environment Variable
+- `ANYSCALE_CLI_TOKEN` - Takes precedence
+- Useful for CI/CD and automation
+
+## Using Authentication
+
+### Get Authenticated Client
+```python
+from anyscale.authenticate import get_auth_api_client
+
+# Get authenticated client
+auth = get_auth_api_client()
+client = auth.api_client
+
+# For SDK
+from anyscale._private.anyscale_client import get_default_client
+client = get_default_client()  # Handles auth automatically
+```
+
+### Check Auth Status
+```python
+from anyscale.util import get_user_info
+
+try:
+    user = get_user_info()
+    print(f"Authenticated as: {user.email}")
+except:
+    print("Not authenticated. Run: anyscale auth login")
+```
+
+### Set Credentials
+```python
+# CLI commands
+anyscale auth login    # Interactive browser flow
+anyscale auth set      # Manual token entry
+anyscale auth show     # View current auth
+
+# Programmatic
+from anyscale.controllers.auth_controller import AuthController
+controller = AuthController()
+controller.set(token="ast_...")
+```
+
+## Security Rules
+
+### DO ✅
+- Store tokens in `~/.anyscale/credentials.json` with 0600 perms
+- Use environment variables in CI/CD
+- Validate tokens before use
+- Clear error messages for auth failures
+
+### DON'T ❌
+- Log tokens or include in error messages
+- Commit tokens to version control
+- Share tokens between users
+- Store tokens in code
+
+## Testing Auth
+
+```python
+# Mock authentication
+@patch('anyscale.authenticate.get_auth_api_client')
+def test_with_auth(mock_auth):
+    mock_auth.return_value.api_client = mock_client
+    # Test your code
+
+# Skip auth in tests
+@patch.dict(os.environ, {'ANYSCALE_CLI_TOKEN': 'test_token'})
+def test_with_env_token():
+    # Test with fake token
+```
+
+## Common Patterns
+
+### Auth Required Decorator
+```python
+def auth_required(func):
+    """Decorator to ensure user is authenticated."""
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            get_user_info()
+        except:
+            raise click.ClickException(
+                "Not authenticated. Run: anyscale auth login"
+            )
+        return func(*args, **kwargs)
+    return wrapper
+
+@click.command()
+@auth_required
+def protected_command():
+    pass
+```
+
+### Service Account Auth
+```python
+# For automation/CI
+os.environ['ANYSCALE_CLI_TOKEN'] = service_account_token
+
+# Or use config file
+config = {
+    "auth": {
+        "cli_token": service_account_token
+    }
+}
+```
+
+## Troubleshooting
+
+```bash
+# Check current auth
+anyscale auth show
+
+# Clear credentials
+rm ~/.anyscale/credentials.json
+
+# Test token
+curl -H "Authorization: Bearer $ANYSCALE_CLI_TOKEN" \
+  https://console.anyscale.com/api/v2/userinfo
+
+# Debug auth issues
+export ANYSCALE_DEBUG=1
+anyscale auth show
+```

anyscale-0.26.51/.cursor/cloud-providers.mdc

@@ -0,0 +1,206 @@
+---
+type: auto-attached
+globs:
+  - "**/cloud*.py"
+  - "**/aws*.py"
+  - "**/gcp*.py"
+  - "**/anyscale-cloud-setup*.yaml"
+description: Cloud provider abstractions and implementations
+---
+
+# Cloud Providers
+
+## Supported Clouds
+
+- **AWS** - Primary, full feature support
+- **GCP** - Secondary, most features supported
+- **Azure** - Limited/experimental
+
+## Cloud Configuration
+
+### Setup Files
+```yaml
+# anyscale-cloud-setup.yaml (AWS)
+# anyscale-cloud-setup-gcp.yaml (GCP)
+
+cloud_name: my-cloud
+provider: aws  # or gcp
+region: us-west-2
+vpc_id: vpc-xxx
+subnet_ids:
+  - subnet-xxx
+security_group_ids:
+  - sg-xxx
+```
+
+### Using Clouds
+```python
+# Specify cloud in SDK
+from anyscale.cloud.commands import get_cloud
+
+cloud = get_cloud("my-aws-cloud")
+print(f"Provider: {cloud.provider}")
+print(f"Region: {cloud.region}")
+
+# CLI commands
+anyscale cloud list
+anyscale cloud verify --name my-cloud
+anyscale service deploy --cloud my-cloud
+```
+
+## Provider Abstraction
+
+```python
+# Common interface for all providers
+class CloudProvider(ABC):
+    @abstractmethod
+    def create_instance(self, config: dict) -> str:
+        pass
+
+    @abstractmethod
+    def get_instance_types(self) -> List[str]:
+        pass
+
+# Provider-specific implementations
+class AWSProvider(CloudProvider):
+    def create_instance(self, config: dict) -> str:
+        # AWS-specific logic using boto3
+        pass
+
+class GCPProvider(CloudProvider):
+    def create_instance(self, config: dict) -> str:
+        # GCP-specific logic using google-cloud
+        pass
+```
+
+## AWS Specifics
+
+### IAM Policies
+```python
+from anyscale.aws_iam_policies import get_required_policies
+
+policies = get_required_policies()
+# Returns list of required AWS IAM policies
+```
+
+### Instance Types
+```python
+# Common AWS instance types used
+INSTANCE_TYPES = {
+    "cpu": ["m5.large", "m5.xlarge", "m5.2xlarge"],
+    "gpu": ["g4dn.xlarge", "p3.2xlarge"],
+    "memory": ["r5.large", "r5.xlarge"]
+}
+```
+
+### Regions
+```python
+AWS_REGIONS = [
+    "us-east-1",
+    "us-west-2",
+    "eu-west-1",
+    "ap-southeast-1"
+]
+```
+
+## GCP Specifics
+
+### Machine Types
+```python
+GCP_MACHINE_TYPES = {
+    "cpu": ["n1-standard-4", "n1-standard-8"],
+    "gpu": ["n1-standard-4 + nvidia-tesla-t4"],
+    "memory": ["n1-highmem-4", "n1-highmem-8"]
+}
+```
+
+### Regions
+```python
+GCP_REGIONS = [
+    "us-central1",
+    "europe-west1",
+    "asia-east1"
+]
+```
+
+### Service Account
+```python
+# GCP requires service account for operations
+os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = '/path/to/key.json'
+```
+
+## Cloud Detection
+
+```python
+def detect_cloud_provider() -> str:
+    """Auto-detect cloud provider from environment."""
+
+    # Check AWS
+    if os.environ.get('AWS_REGION'):
+        return 'aws'
+
+    # Check GCP
+    if os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'):
+        return 'gcp'
+
+    # Default
+    return 'aws'
+```
+
+## Multi-Cloud Patterns
+
+```python
+def get_provider(cloud_name: str) -> CloudProvider:
+    """Get provider instance for cloud."""
+    cloud = get_cloud(cloud_name)
+
+    if cloud.provider == 'aws':
+        return AWSProvider(region=cloud.region)
+    elif cloud.provider == 'gcp':
+        return GCPProvider(project=cloud.project)
+    else:
+        raise ValueError(f"Unsupported provider: {cloud.provider}")
+
+# Use provider abstraction
+provider = get_provider("my-cloud")
+instances = provider.list_instances()
+```
+
+## Testing with Clouds
+
+```python
+@pytest.fixture
+def mock_aws_cloud():
+    """Mock AWS cloud for testing."""
+    cloud = Mock()
+    cloud.provider = 'aws'
+    cloud.region = 'us-west-2'
+    cloud.vpc_id = 'vpc-test'
+    return cloud
+
+def test_with_cloud(mock_aws_cloud):
+    result = deploy_to_cloud(mock_aws_cloud)
+    assert result.cloud_id == mock_aws_cloud.id
+```
+
+## Common Issues
+
+### AWS
+- Missing IAM permissions
+- VPC/subnet misconfiguration
+- Security group rules
+
+### GCP
+- Service account key issues
+- API not enabled
+- Quota limits
+
+### Debug
+```bash
+# Verify cloud setup
+anyscale cloud verify --name my-cloud
+
+# Check credentials
+aws sts get-caller-identity  # AWS
+gcloud auth list  # GCP
+```