Metadata-Version: 2.4
Name: gravixlayer
Version: 0.1.19
Summary: GravixLayer Python SDK - Cloud runtime environments and template management for AI workloads
Author-email: Team Gravix <info@gravixlayer.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/gravixlayer/gravixlayer-python
Project-URL: Repository, https://github.com/gravixlayer/gravixlayer-python
Project-URL: Issues, https://github.com/gravixlayer/gravixlayer-python/issues
Keywords: gravixlayer,ai,cloud,runtime,sdk,templates
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[http2]>=0.24.0
Provides-Extra: dev
Requires-Dist: pylint>=3.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: radon>=6.0.0; extra == "dev"
Requires-Dist: types-requests>=2.25.0; extra == "dev"
Dynamic: license-file

# GravixLayer Python SDK

[![PyPI version](https://badge.fury.io/py/gravixlayer.svg)](https://badge.fury.io/py/gravixlayer)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Official Python SDK for [GravixLayer](https://gravixlayer.com) -- AI agent runtime.

## Installation

```bash
pip install gravixlayer
```

## Configuration

Set your API key and optional cloud/region via environment variables:

```bash
export GRAVIXLAYER_API_KEY="your-api-key"
export GRAVIXLAYER_CLOUD="azure"       # default: azure
export GRAVIXLAYER_REGION="eastus2"    # default: eastus2
```

Or pass them directly to the client:

```python
from gravixlayer import GravixLayer

client = GravixLayer(
    api_key="your-api-key",           # or GRAVIXLAYER_API_KEY env var
<<<<<<< Updated upstream
<<<<<<< Updated upstream
    base_url="https://api.gravixlayer.com", # or GRAVIXLAYER_BASE_URL env var (default: https://api.gravixlayer.com)
=======
    base_url="https://app.gravixlayer.ai",  # or GRAVIXLAYER_BASE_URL env var
>>>>>>> Stashed changes
=======
    base_url="https://app.gravixlayer.ai",  # or GRAVIXLAYER_BASE_URL env var
>>>>>>> Stashed changes
    cloud="azure",                     # or GRAVIXLAYER_CLOUD env var (default: azure)
    region="eastus2",                  # or GRAVIXLAYER_REGION env var (default: eastus2)
)
```

If `cloud` and `region` are not specified, the SDK defaults to `azure` / `eastus2`.

## Multi-Cloud Support

GravixLayer supports multiple cloud providers. The default provider is Azure.

| Provider | Region | Status |
|----------|--------|--------|
| azure | `eastus2` (Virginia) | Available |
| aws | `us-east-1` (Virginia) | Coming Soon |
| gcp | `us-east1` (South Carolina) | Coming Soon |

## Public Base Templates

GravixLayer provides pre-built public templates that are ready to use. These templates are built on [python:3.12.13-slim](https://hub.docker.com/layers/library/python/3.12.13-slim) and are available in all supported regions.

| Template | Resources | Provider / Region |
|----------|-----------|-------------------|
| `python-3.12-base-small` | 1 vCPU / 1 GB RAM / 2 GB disk | azure / eastus2 |
| `python-3.12-base-medium` | 1 vCPU / 2 GB RAM / 4 GB disk | azure / eastus2 |
| `python-3.12-base-large` | 2 vCPU / 4 GB RAM / 8 GB disk | azure / eastus2 |

## Quick Start

### 1. Get Your API Key

Sign up at [platform.gravixlayer.com](https://platform.gravixlayer.com) to obtain your API key.

### 2. Create an Agent Runtime

```python
from gravixlayer import GravixLayer

client = GravixLayer()

# Create an agent runtime (runs indefinitely if a timeout is not specified)
runtime = client.runtime.create(template="python-3.12-base-small")

print(f"Runtime ID: {runtime.runtime_id}")
print(f"Status: {runtime.status}")

# Run Python code
result = client.runtime.run_code(
    runtime.runtime_id,
    code="print('Hello from agent runtime!')",
)
print(f"Output: {result.text}")

# Run a shell command
cmd = client.runtime.run_cmd(runtime.runtime_id, command="uname", args=["-a"])
print(f"System: {cmd.stdout.strip()}")

# Clean up
client.runtime.kill(runtime.runtime_id)
```

## Agent Runtime

```python
from gravixlayer import GravixLayer

client = GravixLayer()

# Create an agent runtime (runs indefinitely if timeout is not specified)
runtime = client.runtime.create(template="python-3.12-base-small")

# Run Python code
result = client.runtime.run_code(runtime.runtime_id, code="print(42)")
print(result.text)

# Run shell commands
cmd = client.runtime.run_cmd(runtime.runtime_id, command="ls", args=["-la"])
print(cmd.stdout)

# File operations
client.runtime.write_file(runtime.runtime_id, path="/app/main.py", content="print('hello')")
content = client.runtime.read_file(runtime.runtime_id, path="/app/main.py")
files = client.runtime.list_files(runtime.runtime_id, path="/app")

# Get runtime info and metrics
info = client.runtime.get(runtime.runtime_id)
metrics = client.runtime.get_metrics(runtime.runtime_id)

# List all runtimes
result = client.runtime.list(limit=50)
for rt in result.runtimes:
    print(f"{rt.runtime_id}: {rt.status}")

# Extend timeout
client.runtime.set_timeout(runtime.runtime_id, timeout=600)

# Kill runtime
client.runtime.kill(runtime.runtime_id)
```

## SSH Access

```python
from gravixlayer import GravixLayer

client = GravixLayer()
runtime = client.runtime.create(template="python-3.12-base-small")

# Enable SSH
ssh_info = client.runtime.enable_ssh(runtime.runtime_id)
print(f"Username: {ssh_info.username}")
print(f"Port: {ssh_info.port}")
print(f"Connect: {ssh_info.connect_cmd}")
print(f"Private Key:\n{ssh_info.private_key}")

# Check SSH status
status = client.runtime.ssh_status(runtime.runtime_id)
print(f"Enabled: {status.enabled}")

# Disable SSH
client.runtime.disable_ssh(runtime.runtime_id)

# Re-enable SSH with new keys
ssh_info = client.runtime.enable_ssh(runtime.runtime_id, regenerate_keys=True)
print(f"SSH re-enabled: {ssh_info.enabled}")

client.runtime.kill(runtime.runtime_id)
```

### Pause and Resume

```python
client.runtime.pause(runtime.runtime_id)
client.runtime.resume(runtime.runtime_id)
```

## Build Custom Templates

Build your own templates from public Docker images. Currently supports Ubuntu, Alpine, and Debian based images.

```python
from gravixlayer import GravixLayer, TemplateBuilder

client = GravixLayer()

builder = (
    TemplateBuilder("my-app")
    .from_image("python:3.11-slim")
    .vcpu(2)
    .memory(512)
    .pip_install("requests", "flask")
)

status = client.templates.build_and_wait(builder, timeout_secs=600)
print(f"Template ID: {status.template_id}")

# List templates
templates = client.templates.list()
for t in templates.templates:
    print(f"{t.name}: {t.description}")

# Delete a template
client.templates.delete(template_id="your-template-id")
```

## Async Support

For scripts and standalone applications:

```python
import asyncio
from gravixlayer import AsyncGravixLayer

async def main():
    async with AsyncGravixLayer() as client:
        runtime = await client.runtime.create(template="python-3.12-base-small")
        result = await client.runtime.run_code(
            runtime.runtime_id,
            code="print('Hello async!')",
        )
        print(result.text)
        await client.runtime.kill(runtime.runtime_id)

asyncio.run(main())
```

## Error Handling

```python
from gravixlayer import GravixLayer
from gravixlayer.types.exceptions import (
    GravixLayerAuthenticationError,
    GravixLayerRateLimitError,
    GravixLayerBadRequestError,
    GravixLayerServerError,
    GravixLayerConnectionError,
)

client = GravixLayer()

try:
    runtime = client.runtime.create(template="python-3.12-base-small")
except GravixLayerAuthenticationError:
    print("Invalid API key")
except GravixLayerRateLimitError:
    print("Too many requests")
except GravixLayerBadRequestError as e:
    print(f"Bad request: {e}")
except GravixLayerServerError as e:
    print(f"Server error: {e}")
except GravixLayerConnectionError as e:
    print(f"Connection error: {e}")
```

## Examples

See the [examples/](examples/) directory for complete working examples:

- **[Agent Runtimes](examples/runtimes/)** -- Create, manage, and interact with agent runtime environments
- **[Custom Templates](examples/templates/)** -- Build custom runtime templates
- **[Sample Apps](examples/apps/)** -- Sample applications used by template examples

## Support

- **Documentation**: [docs.gravixlayer.com](https://docs.gravixlayer.com)
- **Issues**: [GitHub Issues](https://github.com/gravixlayer/gravixlayer-python/issues)
- **Email**: info@gravixlayer.com

## License

Apache License 2.0
