Metadata-Version: 2.4
Name: highflame-forge
Version: 0.0.3
Summary: Run coding agents like Claude Code in isolated, policy-enforced cloud sandboxes
Project-URL: Homepage, https://github.com/highflame-ai/highflame-forge
Project-URL: Documentation, https://github.com/highflame-ai/highflame-forge#readme
Project-URL: Repository, https://github.com/highflame-ai/highflame-forge
Project-URL: Issues, https://github.com/highflame-ai/highflame-forge/issues
Author-email: Highflame Team <team@highflame.ai>
License: MIT
License-File: LICENSE
Keywords: agent,ai-agent,claude-code,coding-agent,developer-tools,gvisor,isolation,sandbox,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: asyncssh>=2.14.0; extra == 'all'
Requires-Dist: cryptography>=49.0.0; extra == 'all'
Requires-Dist: fastapi>=0.137.0; extra == 'all'
Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'all'
Requires-Dist: google-cloud-compute>=1.14.0; extra == 'all'
Requires-Dist: highflame-policy>=2.2.28; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: modal>=1.5.2; extra == 'all'
Requires-Dist: pydantic-settings>=2.14.2; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'all'
Requires-Dist: runpod>=1.6.0; extra == 'all'
Requires-Dist: starlette>=1.3.1; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.6; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: google-cloud-aiplatform>=1.38.0; extra == 'gcp'
Requires-Dist: google-cloud-compute>=1.14.0; extra == 'gcp'
Provides-Extra: modal
Requires-Dist: modal>=1.5.2; extra == 'modal'
Provides-Extra: runpod
Requires-Dist: asyncssh>=2.14.0; extra == 'runpod'
Requires-Dist: runpod>=1.6.0; extra == 'runpod'
Provides-Extra: seccomp
Requires-Dist: pyseccomp>=0.1.2; (sys_platform == 'linux') and extra == 'seccomp'
Provides-Extra: service
Requires-Dist: cryptography>=49.0.0; extra == 'service'
Requires-Dist: fastapi>=0.137.0; extra == 'service'
Requires-Dist: highflame-policy>=2.2.28; extra == 'service'
Requires-Dist: httpx>=0.27.0; extra == 'service'
Requires-Dist: pydantic-settings>=2.14.2; extra == 'service'
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'service'
Requires-Dist: starlette>=1.3.1; extra == 'service'
Requires-Dist: uvicorn[standard]>=0.23.0; extra == 'service'
Description-Content-Type: text/markdown

# Highflame Forge

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Unified sandbox platform for ML training, model scanning, agent testing, and secure execution.**

Highflame Forge provides a single API for creating sandboxed GPU environments across multiple cloud backends (Modal, RunPod, GCP). Use it for training ML models, running security scans, testing AI agents, or any workload that needs isolated execution with GPUs.

## Features

- **Multi-Backend Support**: Modal (primary), RunPod (cheap GPUs), GCP/Vertex AI
- **Unified API**: Same code works across all backends
- **GPU Orchestration**: A40, A100, H100, T4, and more
- **Training Jobs**: Built-in support for ML training with metric streaming
- **Hyperparameter Sweeps**: Parallel parameter search across multiple sandboxes
- **Cost Estimation**: Compare pricing across backends before running
- **Network Isolation**: Configurable network policies for security testing
- **Presets**: Ready-to-use configurations for common workloads

## Installation

### Using uv (Recommended)

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install base package
uv pip install highflame-forge

# Install with specific backend support
uv pip install highflame-forge[modal]      # Modal backend
uv pip install highflame-forge[runpod]     # RunPod backend
uv pip install highflame-forge[gcp]        # GCP backend
uv pip install highflame-forge[all]        # All backends

# Or add to your project
uv add highflame-forge
uv add highflame-forge[modal]
```

### Using pip

```bash
# Install base package
pip install highflame-forge

# Install with specific backend support
pip install highflame-forge[modal]      # Modal backend
pip install highflame-forge[runpod]     # RunPod backend
pip install highflame-forge[gcp]        # GCP backend
pip install highflame-forge[all]        # All backends
```

## Quick Start

### Python API

```python
from highflame_forge import Forge

forge = Forge()

# Create a sandbox with context manager (auto-cleanup)
with forge.sandbox(gpu="A40", memory_gb=32) as sb:
    sb.run_sync("python train.py")
    sb.download_sync("/workspace/model", "./results")

# Async usage
async with forge.sandbox_async(gpu="A40") as sb:
    await sb.run("python train.py")
    await sb.download("/workspace/model", "./results")
```

### Using Presets

```python
from highflame_forge import Forge

forge = Forge()

# Use predefined configurations
with forge.sandbox(preset="training:medium") as sb:
    sb.run_sync("python train.py")

# Available presets:
# - training:small   (T4, 16GB RAM)
# - training:medium  (A40, 32GB RAM)
# - training:large   (A100-80GB, 80GB RAM)
# - training:xlarge  (4x A100-80GB, 320GB RAM)
# - inference:small  (T4, 8GB RAM)
# - inference:large  (A100-40GB, 40GB RAM)
# - security:scan    (CPU only, no network)
# - agent:standard   (CPU, restricted network)
```

### Training Jobs

```python
from highflame_forge import Forge
from highflame_forge.jobs import TrainingJob

forge = Forge()

# Run a training job with automatic metric extraction
job = TrainingJob(
    forge=forge,
    script="train.py",
    preset="training:medium",
    env={"WANDB_PROJECT": "my-project"},
)

result = await job.run()
print(f"Training completed: {result.metrics}")
```

### Hyperparameter Sweeps

```python
from highflame_forge.jobs import HyperparameterSweep

sweep = HyperparameterSweep(
    forge=forge,
    script="train.py",
    preset="training:medium",
    param_space={
        "learning_rate": [1e-4, 1e-3, 1e-2],
        "batch_size": [8, 16, 32],
    },
    max_parallel=4,
)

results = await sweep.run()
print(f"Best config: {results.best_config}")
print(f"Best loss: {results.best_result.metrics.get('loss')}")
```

### Cost Estimation

```python
from highflame_forge import Forge

forge = Forge()

# Compare costs across backends
estimates = forge.estimate_cost(gpu="A40", memory_gb=32, duration_hours=2)

for backend, estimate in estimates.items():
    print(f"{backend}: ${estimate.estimated_total:.2f}")

# Find cheapest backend
cheapest = forge.cheapest_backend(gpu="A40", duration_hours=2)
print(f"Cheapest: {cheapest}")
```

## CLI Usage

```bash
# Create a sandbox interactively
forge create --gpu A40 --memory 32

# Run a training job
forge train --script train.py --gpu A40 --backend modal

# Run hyperparameter sweep
forge sweep --script train.py --param learning_rate=1e-4,1e-3 --max-parallel 4

# Estimate costs
forge estimate --gpu A40 --hours 2

# List running sandboxes
forge list

# Terminate a sandbox
forge terminate <sandbox-id>

# Show available GPUs
forge gpus

# List available presets
forge presets
```

## Configuration

### Environment Variables

```bash
# Modal (primary backend)
MODAL_TOKEN_ID=...
MODAL_TOKEN_SECRET=...

# RunPod
RUNPOD_API_KEY=...

# GCP
GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
GCP_PROJECT_ID=your-project

# Optional
HF_TOKEN=...              # HuggingFace access
WANDB_API_KEY=...         # Experiment tracking
```

### Backend Selection

```python
from highflame_forge import Forge, BackendSelector

# Use specific backend
forge = Forge(backend="modal")

# Auto-select cheapest backend
forge = Forge(selector=BackendSelector.COST_OPTIMIZED)

# Auto-select fastest startup
forge = Forge(selector=BackendSelector.SPEED_OPTIMIZED)

# Limit to specific backends
forge = Forge(backends=["modal", "runpod"])
```

### Network Policies

```python
from highflame_forge import Forge, SandboxConfig, NetworkConfig

# Fully isolated (for security scanning)
config = SandboxConfig(
    gpu="T4",
    network=NetworkConfig(
        allow_outbound=False,
        allow_internet=False,
    ),
)

# Restricted access (for agents)
config = SandboxConfig(
    gpu="none",
    network=NetworkConfig(
        allow_outbound=True,
        allowed_hosts=[
            "api.anthropic.com",
            "github.com",
            "pypi.org",
        ],
    ),
)
```

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                      Highflame Forge                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  from highflame_forge import Forge                              │
│                                                                 │
│  forge = Forge()  # Auto-selects best backend                   │
│                                                                 │
│  with forge.sandbox(gpu="A40") as sb:                           │
│      sb.run("python train.py")                                  │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Backends:                                                      │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │  Modal  │  │ RunPod  │  │   GCP   │  │ Vertex  │            │
│  │(primary)│  │ (cheap) │  │(credits)│  │  (mgd)  │            │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │
│                                                                 │
│  High-Level APIs:                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │TrainingJob  │  │InferenceScan│  │WhiteboxTest │             │
│  │   Sweep     │  │ (Palisade)  │  │  (Redteam)  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Use Cases

### ML Training

GPU-accelerated model training with workflow orchestration, metric streaming, and hyperparameter sweeps.

```python
job = TrainingJob(
    forge=forge,
    script="train.py",
    preset="training:large",
    requirements=["torch", "transformers"],
)
result = await job.run()
```

### Palisade Integration

Safe inference-time backdoor detection with network isolation and syscall monitoring.

```python
with forge.sandbox(preset="security:inference") as sb:
    sb.upload_sync("./model", "/workspace/model")
    result = sb.run_sync("python scan.py --model /workspace/model")
```

### Agent Testing

Isolated execution environments for testing AI agents with controlled network access.

```python
with forge.sandbox(preset="agent:standard") as sb:
    sb.run_sync("python agent.py --task 'implement feature X'")
```

## Backend Comparison

| Feature | Modal | RunPod | GCP |
|---------|-------|--------|-----|
| Startup Time | ~10s | ~60s | ~120s |
| Billing | Per-second | Per-hour | Per-minute |
| GPU Selection | Good | Excellent | Good |
| Spot Pricing | Yes | Yes | Yes |
| Best For | Dev/iteration | Cost-sensitive | Credits |

## Development

### Using uv (Recommended)

```bash
# Clone the repository
git clone https://github.com/highflame-ai/highflame-forge.git
cd highflame-forge

# Install from lockfile (reproducible)
uv sync --group dev

# Run tests
uv run pytest tests/

# Type checking
uv run mypy src/highflame_forge

# Linting
uv run ruff check src/

# Update dependencies and regenerate lockfile
uv lock --upgrade
```

Note: The `uv.lock` file is committed to ensure reproducible builds across environments.

### Using pip

```bash
# Clone the repository
git clone https://github.com/highflame-ai/highflame-forge.git
cd highflame-forge

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Type checking
mypy src/highflame_forge

# Linting
ruff check src/
```

## License

MIT License - see [LICENSE](LICENSE) for details.

## Related Projects

- [Palisade](https://github.com/highflame-ai/palisade) - ML model security scanning
- [Redteam](https://github.com/highflame-ai/redteam) - Agent security testing
- [Overwatch](https://github.com/highflame-ai/overwatch) - Agent monitoring
