# GateWay

**The gearbox for your code.** — Run your code in the cloud for the price of a coffee.

GateWay is a Python cloud orchestration platform that lets developers execute code on the cheapest available cloud infrastructure across AWS, GCP, and Azure — all from a simple PyPI package.

---

## The Problem

You're building an ML model, running data processing, or executing compute-heavy tasks. Your laptop isn't powerful enough. You need cloud resources, but:

- Setting up cloud infrastructure is tedious
- Comparing prices across providers is time-consuming
- You don't want to leave your IDE or manage VMs
- You're paying too much for compute you don't need

## The Solution

GateWay lets you wrap any Python code and run it in the cloud with one function call. We automatically:

1. **Estimate resources** your code needs (CPU, memory, GPU)
2. **Compare prices** across all major cloud providers in real-time
3. **Select the cheapest** available instance that fits your requirements
4. **Execute your code** in the cloud
5. **Stream output** back to your terminal in real-time

All without leaving VS Code — starting at just cents per run.

---

## Two Gears

Choose manual or automatic:

| Mode | Flag | Wait Time | Best For |
|------|------|-----------|----------|
| **Performance** | `fast=True` | **Immediate** | Time-sensitive workloads |
| **Standard** | `fast=False` (default) | Up to 10 mins | Batch jobs, cost-sensitive |

### How Standard Mode Works

1. You submit a job with Standard mode (the default)
2. You enter a queue (max 10 minute wait, **guaranteed**)
3. **The longer you wait, the higher your priority becomes**
4. At 10 minutes, you have the same priority as Performance users
5. Your job executes and you saved money compared to Performance

```python
# Performance mode: execute immediately
with verlex.GateWay(api_key="gw_xxx", fast=True) as gw:
    result = gw.run(urgent_task)

# Standard mode (default): wait for lower prices
with verlex.GateWay(api_key="gw_xxx") as gw:
    result = gw.run(batch_job)
```

### Priority Aging

Standard users aren't just waiting — their priority score **improves over time**:

```
Wait Time    Priority Score    Status
0 mins       100 (lowest)      Just joined queue
2 mins       81                Warming up
5 mins       52.5              Middle priority
8 mins       24                High priority
10 mins      5 (highest)       Same as Performance users!
```

This ensures **fairness**: someone who just submitted doesn't cut ahead of someone who's been waiting 7 minutes.

---

## Installation

```bash
pip install verlex
```

## Quick Start

### Manual: Context Manager (Recommended)

The recommended way to use GateWay — you control when code goes to the cloud:

```python
import verlex

with verlex.GateWay(api_key="gw_your_key", fast=True) as gw:

    def train_model():
        import torch
        model = torch.nn.Transformer()
        # Training code...
        return {"accuracy": 0.95}

    # Analyze what resources you need (optional)
    rec = gw.analyze(train_model)
    print(f"Recommended: {rec.gpu_type} GPU, ${rec.estimated_cost_per_hour}/hr")

    # Run in the cloud
    result = gw.run(train_model)
    print(result)  # {"accuracy": 0.95}

# Session summary is printed on exit
```

### Automatic: Overflow

Don't want to choose what runs in the cloud? Let Verlex decide:

```python
import verlex
verlex.overflow()

# Your code runs normally.
# When CPU or memory exceeds 85%, functions are offloaded to the cloud.
data = load_data()
result = train_model(data)   # system overloaded? → cloud
evaluate(result)             # resources free → runs locally
```

Install with: `pip install 'verlex[overflow]'`

### Decorator Pattern

```python
with verlex.GateWay(api_key="gw_xxx", fast=True) as gw:

    @gw.remote(gpu="A100", memory="32GB")
    def train():
        import torch
        return {"done": True}

    result = train()  # Executes in cloud when called!
```

### Alternative: Direct API

```python
import verlex

# Authenticate
verlex.auth(api_key="gw_your_api_key", fast=True)

# Run with decorator
@verlex.resource(gpu="A100", memory="32GB")
def train_model():
    import torch
    return {"accuracy": 0.95}

result = verlex.run(train_model)
```

---

## Execution Modes

GateWay supports two execution modes using one boolean parameter:

| fast | Name | Description |
|------|------|-------------|
| `True` | Performance | Execute **immediately** on the cheapest available provider |
| `False` | Standard | Wait up to 10 mins for the lowest price |

```python
# Performance — execute immediately
with verlex.GateWay(api_key="gw_xxx", fast=True) as gw:
    result = gw.run(urgent_task)

# Standard (default) — wait for lower prices
with verlex.GateWay(api_key="gw_xxx") as gw:
    result = gw.run(batch_job)
```

---

## Resource Configuration

Specify exactly what your code needs:

```python
@verlex.resource(
    cpu=8,              # Number of CPU cores
    memory="64GB",      # RAM allocation
    gpu="A100",         # GPU type (A100, H100, L4, T4, etc.)
    gpu_count=2,        # Number of GPUs
    disk="100GB",       # Disk space
    timeout=3600        # Max execution time in seconds
)
def my_compute_heavy_task():
    # Your code here
    pass
```

### Auto Resource Estimation

Don't know what you need? Let GateWay profile your code:

```python
# Dry-run profiling to estimate resources
profile = gateway.profile(my_function)
print(profile)
# {
#     "estimated_cpu": 4,
#     "estimated_memory": "16GB",
#     "estimated_gpu_memory": "24GB",
#     "estimated_duration": "45 minutes",
#     "recommended_instance": "AWS g5.2xlarge"
# }
```

---

## Agent Daemon

Monitor your system and offload heavy Python processes:

```bash
# Watch for heavy processes and offer to offload
verlex agent watch

# Auto-offload without prompting
verlex agent watch --auto

# Submit a script directly
verlex agent run train.py --gpu A100
```

Install with: `pip install 'verlex[agent]'`

---

## Authentication

### Option 1: Environment Variable

```bash
export VERLEX_API_KEY="gw_your_api_key"
```

```python
import verlex
with verlex.GateWay(fast=True) as gw:
    result = gw.run(my_function)
```

### Option 2: Credentials File

```bash
verlex login
# Opens browser for authentication
```

### Option 3: Direct API Key

```python
with verlex.GateWay(api_key="gw_your_api_key", fast=True) as gw:
    result = gw.run(my_function)
```

---

## Pricing Tiers

| Tier | Warm Pools | Features | Price |
|------|------------|----------|-------|
| **Free** | 0 | Basic execution, Performance/Standard modes | Pay per use |
| **Pro** | 2 containers | All features, priority queue | $29/month + usage |
| **Enterprise** | 10+ containers | Custom SLAs, dedicated support | Contact us |

Compute is billed per second at provider rates + GateWay fee.

---

## CLI Commands

```bash
# Authentication
verlex login              # Browser-based login
verlex logout             # Clear credentials
verlex whoami             # Show current user

# Execution
verlex run script.py      # Run a script in the cloud
verlex run script.py --fast  # Performance mode

# Monitoring
verlex status             # Show warm pool status
verlex jobs               # List running/completed jobs
verlex logs <job_id>      # Stream logs for a job
verlex logs --follow      # Live tail logs

# Profiling
verlex profile script.py  # Estimate resource requirements

# Pricing
verlex prices                            # Show all prices
verlex prices --cheapest                 # Find the single cheapest option
verlex prices -c 4 -m 16                # With CPU/memory requirements
verlex prices -g A100 --cheapest        # Find cheapest A100 GPU
verlex prices --json                    # Output as JSON
verlex estimate script.py               # Estimate execution cost
```

---

## Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Your IDE      │────▶│  GateWay Client  │────▶│  GateWay API    │
│   (VS Code)     │◀────│  (PyPI Package)  │◀────│  (Backend)      │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
        ▲                        │                        │
        │                   cloudpickle              ┌────▼────┐
        │                   serialization            │ Pricing │
   WebSocket                     │                   │ Service │
   stdout/stderr                 ▼                   └────┬────┘
        │               ┌──────────────────┐              │
        └───────────────│  Cloud Providers │◀─────────────┘
                        │  AWS │ GCP│Azure │       cost comparison
                        └────────┬─────────┘
                                 │
                        ┌────────▼─────────┐
                        │ Checkpoint Store │
                        │ (S3/GCS/Blob)    │
                        └──────────────────┘
```

### How It Works

1. **Serialization**: Your function and its dependencies are serialized using `cloudpickle`
2. **Resource Estimation**: GateWay analyzes your code to estimate CPU/memory/GPU needs
3. **Price Comparison**: Real-time queries to AWS, GCP, Azure pricing APIs
4. **Provider Selection**: Based on your `fast` setting, the optimal provider is selected
5. **Execution**: Your code runs in a secure container on the selected cloud
6. **Streaming**: stdout/stderr stream back to your terminal via WebSocket
7. **Recovery**: If spot instances are interrupted, automatic retry with state restoration

---

## Security

- API keys are stored securely using OS keychain (via `keyring`)
- All communication is encrypted (TLS 1.3)
- Code is executed in isolated containers
- Checkpoints are encrypted at rest
- No code is stored after execution completes
- SOC 2 Type II compliant (Enterprise tier)

---

## Supported Cloud Providers

| Provider | Instance Types | Spot/Preemptible | Regions |
|----------|---------------|------------------|---------|
| **AWS** | EC2, Lambda, ECS | Up to 90% off | 25+ |
| **GCP** | Compute Engine, Cloud Run | Up to 91% off | 35+ |
| **Azure** | VMs, Container Instances | Up to 81% off | 60+ |

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
git clone https://github.com/gateway-cloud/gateway.git
cd gateway
pip install -e ".[dev]"
pytest
```

---

## License

Apache 2.0 - See [LICENSE](LICENSE) for details.

---

## Links

- **Website**: [verlex.dev](https://verlex.dev)
- **Documentation**: [verlex.dev/docs](https://verlex.dev/docs)
- **Support**: support@verlex.dev

---

<p align="center">
  <b>Stop managing infrastructure. Start shipping code.</b><br>
  Built by the Verlex team
</p>
