portkey-sdk 0.2.0

Unofficial Rust SDK for Portkey AI Gateway: route, observe, and optimize LLM requests across 200+ providers
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# Portkey SDK

[![Crates.io](https://img.shields.io/crates/v/portkey-sdk?style=flat-square&color=black)](https://crates.io/crates/portkey-sdk)
[![Documentation](https://img.shields.io/docsrs/portkey-sdk?style=flat-square&color=black)](https://docs.rs/portkey-sdk)
[![Build](https://img.shields.io/github/actions/workflow/status/martsokha/portkey/build.yml?style=flat-square&color=black)](https://github.com/martsokha/portkey/actions)

A Rust client library for the [Portkey AI Gateway](https://portkey.ai/). 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`:

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

## Quick Start

### Builder Configuration

```rust,no_run
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](https://app.portkey.ai/) |
| `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                               |

```rust,no_run
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:

```toml
# 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`](https://crates.io/crates/tracing) crate. 
Tracing targets are defined in `lib.rs` for fine-grained control over log output:

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

### JSON Schema Support for Structured Outputs

Enable JSON Schema support via the [`schemars`](https://crates.io/crates/schemars) crate to use structured outputs with custom types. 
This feature provides helper methods to create JSON schema configurations and parse structured responses:

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

See the [structured outputs example](examples/structured_outputs.rs) for a complete working example.

## Examples

The `examples/` directory contains usage examples:

```bash
# 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](CONTRIBUTING.md)
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](LICENSE.txt) file for details.

## Resources

- [Portkey Documentation](https://portkey.ai/docs)
- [Portkey API Reference](https://portkey.ai/docs/api-reference)
- [Full API Documentation](https://docs.rs/portkey-sdk)