onwards 0.16.1

A flexible LLM proxy library
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

# Configuration

Onwards is configured through a JSON file. Each key in the `targets` object defines a model alias that clients can request.

## Global options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `strict_mode` | bool | No | Enable strict mode globally for all targets (see [Strict Mode](strict-mode.md)). Default: false |
| `auth` | object | No | Global authentication configuration (see [Authentication](authentication.md)) |
| `targets` | object | Yes | Map of model aliases to target configurations |

## Target options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `url` | string | Yes | Base URL of the AI provider |
| `onwards_key` | string | No | API key to include in requests to the target |
| `onwards_model` | string | No | Model name to use when forwarding requests |
| `keys` | string[] | No | API keys required for authentication to this target |
| `rate_limit` | object | No | Per-target rate limiting (see [Rate Limiting](rate-limiting.md)) |
| `concurrency_limit` | object | No | Per-target concurrency limiting (see [Concurrency Limiting](concurrency.md)) |
| `upstream_auth_header_name` | string | No | Custom header name for upstream auth (default: `Authorization`) |
| `upstream_auth_header_prefix` | string | No | Custom prefix for upstream auth header value (default: `Bearer `) |
| `response_headers` | object | No | Key-value pairs to add or override in the response headers |
| `sanitize_response` | bool | No | Enforce strict OpenAI schema compliance for responses only (see [Sanitization](sanitization.md)) |
| `strategy` | string | No | Load balancing strategy: `weighted_random` or `priority` |
| `fallback` | object | No | Retry configuration (see [Load Balancing](load-balancing.md)) |
| `providers` | array | No | Array of provider configurations for load balancing |

## Rate limit object

| Field | Type | Description |
|-------|------|-------------|
| `requests_per_second` | float | Number of requests allowed per second |
| `burst_size` | integer | Maximum burst size of requests |

## Concurrency limit object

| Field | Type | Description |
|-------|------|-------------|
| `max_concurrent_requests` | integer | Maximum number of concurrent requests |

## Auth configuration

The top-level `auth` object configures global authentication:

| Field | Type | Description |
|-------|------|-------------|
| `global_keys` | string[] | Keys that grant access to all authenticated targets |
| `key_definitions` | object | Named key definitions with per-key rate/concurrency limits |

See [Authentication](authentication.md) for details.

## Minimal example

```json
{
  "targets": {
    "gpt-4": {
      "url": "https://api.openai.com",
      "onwards_key": "sk-your-openai-key"
    }
  }
}
```

## Full example

```json
{
  "strict_mode": true,
  "auth": {
    "global_keys": ["global-api-key-1"],
    "key_definitions": {
      "premium_user": {
        "key": "sk-premium-67890",
        "rate_limit": {
          "requests_per_second": 100,
          "burst_size": 200
        },
        "concurrency_limit": {
          "max_concurrent_requests": 10
        }
      }
    }
  },
  "targets": {
    "gpt-4": {
      "url": "https://api.openai.com",
      "onwards_key": "sk-your-openai-key",
      "onwards_model": "gpt-4-turbo",
      "keys": ["premium_user"],
      "rate_limit": {
        "requests_per_second": 50,
        "burst_size": 100
      },
      "concurrency_limit": {
        "max_concurrent_requests": 20
      },
      "response_headers": {
        "Input-Price-Per-Token": "0.0001",
        "Output-Price-Per-Token": "0.0002"
      },
      "sanitize_response": true
    }
  }
}
```