replicate-rs

A Rust client library for Replicate. This library allows you to run AI models, create predictions, stream outputs, and manage various Replicate resources from your Rust applications.

Overview

replicate-rs is an async-first Rust implementation of the Replicate API client, designed to provide a safe, efficient, and ergonomic interface to Replicate's AI model platform. Built with tokio for async runtime and reqwest for HTTP client capabilities.

Production-ready features include: retry logic with exponential backoff, configurable timeouts, comprehensive error handling, and full async support.

Features

Core Functionality

• ✅ Async/Await Support: Built on tokio for high-performance async operations
• ✅ Type Safety: Leverages Rust's type system for compile-time correctness
• ✅ HTTP Client: Uses reqwest for robust HTTP communications
• ✅ Authentication: Secure API token management
• ✅ Error Handling: Comprehensive error types with detailed context

API Operations

• ✅ Predictions: Create, get, list, and cancel predictions
• 🔲 Models: Access and manage AI models
• 🔲 Streaming: Real-time server-sent events for model outputs
• ✅ Files: Upload and manage files with multipart form data
• 🔲 Versions: Access specific model versions
• 🔲 Collections: Browse model collections
• 🔲 Deployments: Manage model deployments
• 🔲 Training: Create and manage fine-tuning jobs
• 🔲 Webhooks: Configure webhooks for async notifications
• 🔲 Hardware: Query available hardware options

Advanced Features

• ✅ Pagination: Efficient handling of paginated responses
• ✅ Retry Logic: Automatic retry with exponential backoff
• ✅ Timeout Configuration: Configurable connect and request timeouts
• 🔲 Rate Limiting: Built-in rate limit handling
• ✅ File Handling: Multipart uploads, encoding strategies, metadata support
• 🔲 Progress Tracking: Monitor long-running predictions
• 🔲 Concurrent Operations: Run multiple predictions in parallel

Quick Start

[dependencies]
replicate-rs = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

use replicate_client::{Client, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Initialize the client with your API token
    let client = Client::new("your-api-token")?;
    
    // Run a simple prediction
    let output = client
        .run("stability-ai/sdxl")
        .input("prompt", "A futuristic city skyline")
        .await?;
    
    println!("Generated image: {}", output);
    Ok(())
}

Configuration

Retry Configuration

The client includes built-in retry logic with exponential backoff for handling transient failures:

use replicate_client::{Client, RetryConfig};
use std::time::Duration;

// Create client with custom retry settings
let retry_config = RetryConfig {
    max_retries: 5,
    min_delay: Duration::from_millis(100),
    max_delay: Duration::from_secs(30),
    base_multiplier: 2,
};

let client = Client::with_retry_config("your-api-token", retry_config)?;

// Or configure an existing client
let mut client = Client::new("your-api-token")?;
client.configure_retries(
    3,                               // max_retries
    Duration::from_millis(500),      // min_delay  
    Duration::from_secs(30),         // max_delay
)?;

Timeout Configuration

Configure connection and request timeouts for better control over network operations:

use replicate_client::{Client, TimeoutConfig, HttpConfig, RetryConfig};
use std::time::Duration;

// Configure timeouts on existing client
let mut client = Client::new("your-api-token")?;
client.configure_timeouts(
    Some(Duration::from_secs(10)),   // connect_timeout
    Some(Duration::from_secs(120)),  // request_timeout
)?;

// Create client with custom timeout and retry configuration
let http_config = HttpConfig {
    retry: RetryConfig {
        max_retries: 3,
        min_delay: Duration::from_millis(500),
        max_delay: Duration::from_secs(30),
        base_multiplier: 2,
    },
    timeout: TimeoutConfig {
        connect_timeout: Some(Duration::from_secs(15)),
        request_timeout: Some(Duration::from_secs(90)),
    },
};

let client = Client::with_http_config("your-api-token", http_config)?;

// Disable timeouts (use with caution!)
client.configure_timeouts(None, None)?;

File Uploads and Multipart Form Data

The library provides comprehensive file handling with multipart form data support for efficient file uploads:

Basic File Upload

use replicate_client::{Client, FileInput, FileEncodingStrategy};
use std::collections::HashMap;

let client = Client::new("your-api-token")?;

// Upload file from bytes with metadata
let file_content = b"Hello, World!";
let mut metadata = HashMap::new();
metadata.insert("description".to_string(), serde_json::Value::String("Test file".to_string()));

let uploaded_file = client.files().create_from_bytes(
    file_content,
    Some("hello.txt"),
    Some("text/plain"),
    Some(&metadata),
).await?;

println!("Uploaded file ID: {}", uploaded_file.id);
println!("File URL: {}", uploaded_file.urls.get("get").unwrap());

// Upload from local file path
let file = client.files().create_from_path("./image.jpg", None).await?;

// Upload using FileInput abstraction
let file_input = FileInput::from_bytes_with_metadata(
    image_data,
    Some("image.jpg".to_string()),
    Some("image/jpeg".to_string()),
);
let file = client.files().create_from_file_input(&file_input, None).await?;

File Management

// List all uploaded files
let files = client.files().list().await?;
for file in files {
    println!("File: {} ({})", file.name, file.id);
}

// Get file by ID
let file = client.files().get("file-id").await?;
println!("File size: {} bytes", file.size);

// Delete file
let deleted = client.files().delete("file-id").await?;
assert!(deleted);

File Encoding Strategies

The library supports two file encoding strategies for use with predictions:

// 1. Multipart Upload (recommended for larger files)
let prediction = client
    .create_prediction("stability-ai/sdxl:version")
    .file_input_with_strategy("image", file_input, FileEncodingStrategy::Multipart)
    .input("prompt", "Enhance this image")
    .send()
    .await?;

// 2. Base64 Data URL (for smaller files < 1MB)
let prediction = client
    .create_prediction("stability-ai/sdxl:version")
    .file_input_with_strategy("image", file_input, FileEncodingStrategy::Base64DataUrl)
    .input("prompt", "Analyze this image")
    .send()
    .await?;

// Default strategy is Multipart
let prediction = client
    .create_prediction("stability-ai/sdxl:version")
    .file_input("image", file_input)  // Uses Multipart by default
    .send()
    .await?;

File Input Types

// From URL (for reference, not upload)
let file_from_url = FileInput::from_url("https://example.com/image.jpg");

// From local file path
let file_from_path = FileInput::from_path("./local_image.jpg");

// From bytes with metadata
let file_from_bytes = FileInput::from_bytes_with_metadata(
    image_data,
    Some("image.jpg".to_string()),
    Some("image/jpeg".to_string()),
);

// Simple bytes input
let file_simple = FileInput::from_bytes(image_data);

Advanced File Operations

// Upload with custom metadata
let mut metadata = HashMap::new();
metadata.insert("source".to_string(), serde_json::Value::String("user_upload".to_string()));
metadata.insert("category".to_string(), serde_json::Value::String("profile_image".to_string()));
metadata.insert("user_id".to_string(), serde_json::Value::Number(serde_json::Number::from(12345)));

let file = client.files().create_from_bytes(
    image_data,
    Some("profile.jpg"),
    Some("image/jpeg"),
    Some(&metadata),
).await?;

// Access file metadata
println!("File metadata: {:?}", file.metadata);
println!("File checksums: {:?}", file.checksums);
println!("Created at: {}", file.created_at);

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup
• Code style and formatting
• Testing requirements
• Pull request process
• Issue reporting

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Replicate for providing the AI model platform
• replicate-python for API design inspiration
• The Rust community for excellent async and HTTP libraries

Status

🚧 This project is under active development. APIs may change before the 1.0 release.

Current status: Phase 4 - Production Features (60% complete)

Recent milestones:

• ✅ Phase 1: Core Infrastructure (100% complete)
• ✅ Phase 2: Core API Operations (85% complete)
• ✅ Phase 3: Advanced Features (80% complete)
• 🔄 Phase 4: Production Features - Retry logic ✅, Timeout configuration ✅
• ⏳ Phase 5: Polish & Release

For the latest updates, check our project milestones and issues.