Crate portkey_sdk

Expand description

§Portkey SDK

A Rust client library for the Portkey AI Gateway. This SDK provides a type-safe, ergonomic interface for managing AI gateway operations, chat completions, embeddings, images, audio, and analytics.

§Features

Complete API Coverage: Support for all Portkey API endpoints
Type Safety: Strongly typed models with comprehensive validation
Async/Await: Built on modern async Rust with tokio and reqwest

§Installation

Add this to your Cargo.toml:

[dependencies]
tokio = { version = "1.0", features = ["macros", "rt-multi-thread"] }
portkey-sdk = { version = "0.2", features = [] }

§Quick Start

§Builder Configuration

use portkey_sdk::{builder::AuthMethod, PortkeyConfig, Result};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<()> {
    let client = PortkeyConfig::builder()
        .with_api_key("your-portkey-api-key")
        .with_auth_method(AuthMethod::virtual_key("your-virtual-key"))
        .with_base_url("https://api.portkey.ai/v1")
        .with_timeout(Duration::from_secs(60))
        .build_client()?;

    // Use the client for API calls...

    Ok(())
}

§Environment Variables

The SDK can be configured using environment variables:

Variable	Required	Default	Description
`PORTKEY_API_KEY`	Yes	-	Your Portkey API key from console
`PORTKEY_BASE_URL`	No	`https://api.portkey.ai/v1`	Custom API base URL
`PORTKEY_TIMEOUT_SECS`	No	`30`	Request timeout in seconds (max: 300)
`PORTKEY_VIRTUAL_KEY`	No	-	Virtual key for routing
`PORTKEY_TRACE_ID`	No	-	Trace ID for request tracking
`PORTKEY_CACHE_NAMESPACE`	No	-	Cache namespace for response caching
`PORTKEY_CACHE_FORCE_REFRESH`	No	`false`	Force refresh cached responses

use portkey_sdk::{PortkeyClient, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client: PortkeyClient = PortkeyClient::from_env()?;
    Ok(())
}

§Optional Features

§TLS Backend

Choose between two TLS implementations:

# Default: rustls-tls (recommended)
portkey-sdk = { version = "0.2", features = [] }

# Alternative: native-tls
portkey-sdk = { version = "0.2", features = ["native-tls"], default-features = false }

§Tracing Support

Enable comprehensive logging and tracing via the tracing crate. Tracing targets are defined in lib.rs for fine-grained control over log output:

portkey-sdk = { version = "0.2", features = ["tracing"] }

§JSON Schema Support for Structured Outputs

Enable JSON Schema support via the schemars crate to use structured outputs with custom types. This feature provides helper methods to create JSON schema configurations and parse structured responses:

portkey-sdk = { version = "0.2", features = ["schema"] }
schemars = { version = "0.8", features = ["derive"] }

See the structured outputs example for a complete working example.

§Examples

The examples/ directory contains usage examples:

# Set your API key
export PORTKEY_API_KEY="your-api-key"
export PORTKEY_VIRTUAL_KEY="your-virtual-key"

# Run the chat completion example
cargo run --example chat_completion

# Run the embeddings example
cargo run --example embeddings

# Run the structured outputs example (requires schema feature)
cargo run --example structured_outputs --features schema

§Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and contribute to the project.

§License

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

§Resources

Modules§

builder: Configuration builder types for Portkey clients.
model: Portkey API data models.
service: Portkey API services.

Structs§

PortkeyClient: Main Portkey API client for interacting with all Portkey services.
PortkeyConfig: Configuration for the Portkey API client.

Enums§

Error: Error type for Portkey API operations.

Constants§

TRACING_TARGET_CLIENTtracing: Tracing target for client-level operations (HTTP requests, client creation).
TRACING_TARGET_CONFIGtracing: Tracing target for configuration operations (config creation, validation).
TRACING_TARGET_SERVICEtracing: Tracing target for service-level operations (API calls, business logic).

Type Aliases§

Result: Result type for Portkey API operations.