# SDK reference

Import the SDK functions and types from `@omnious/provider`. Wire schemas are available separately from `@omnious/provider/protocol`.

## `defineProvider`

```ts
function defineProvider<M extends EngineLoad>(config: ProviderConfig<M>): ProviderConfig<M>;
```

Returns the configuration unchanged and preserves the engine metric type in policy callbacks. It does not connect or check the engine. Export this configuration as the default export when using the CLI.

## `startProvider`

```ts
function startProvider<M extends EngineLoad>(config: ProviderConfig<M>): Promise<ProviderClient>;
```

Validates the engine, connects, restores session state, and waits for acknowledgement of the first standing-price update. Rejects when startup fails. After startup, the client polls metrics and reconnects automatically.

`ProviderClient.close(): Promise<void>` shuts down the agent and its runtime. Repeated calls share the same promise. See [Lifecycle and caching](/providers/lifecycle) for shutdown responsibilities.

## `checkEngine`

```ts
function checkEngine<M extends EngineLoad>(input: {
  engine: EngineAdapter<M>;
  timeoutMs?: number;
}): Promise<EngineCheck<M>>;
```

Checks health, discovers the selected model, and validates metrics without connecting to Omnious. `timeoutMs` defaults to `3000`.

Returns `{ model, metrics, collectedAt }`, where `collectedAt` is a UTC timestamp. A failed check rejects the promise.

## Engine adapters

```ts
function llamaCpp(options: EngineOptions): EngineAdapter<LlamaCppMetrics>;

function vllm(
  options: EngineOptions & { labels?: Readonly<Record<string, string>> },
): EngineAdapter<VllmMetrics>;
```

`EngineOptions` requires `baseUrl` and `model`; `apiKey` and `metricsUrl` are optional. See [Engines and metrics](/providers/engines) for supported versions and fields.

`EngineAdapter<M>` contains `kind`, `options`, and `parse(text: string): M`. `M` extends `EngineLoad`, which requires numeric `runningRequests` and `waitingRequests`. Collection uses the standard health and model discovery endpoints even with a custom parser.

## `ProviderConfig`

| Property              | Required | Description                                                                                    |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `url`                 | Yes      | Omnious WebSocket URL ending in `/providers/ws`                                                |
| `canonicalModelId`    | Yes      | Active model ID from your Omnious configuration                                                |
| `engine`              | Yes      | Engine adapter                                                                                 |
| `standingPrice`       | Yes      | `(context: PolicyContext<M>) => QuoteTerms \| Promise<QuoteTerms>`                             |
| `quote`               | Yes      | `(context: PolicyContext<M> & { rfq: RfqRequest }) => QuoteDecision \| Promise<QuoteDecision>` |
| `token`               | No       | Provider token; defaults to `OMNIOUS_PROVIDER_TOKEN`                                           |
| `cleanCache`          | No       | Reset cache accounting after physical cache loss; defaults to `false`                          |
| `onAward`             | No       | Award observer with an abort signal                                                            |
| `onQuoteRelease`      | No       | Pending quote release observer                                                                 |
| `onExecutionRelease`  | No       | Execution release observer                                                                     |
| `onCommitment`        | No       | Commitment update and restoration observer                                                     |
| `onCommitmentRelease` | No       | Commitment release observer                                                                    |
| `onError`             | No       | Synchronous `(error: Error) => void` reporter                                                  |

The [policy guide](/providers/policies) describes `PolicyContext`, `QuoteDecision`, and price terms. The [lifecycle guide](/providers/lifecycle#observe-lifecycle-events) describes callback arguments.

### Timing options

All timing options are positive integers in milliseconds.

| Property                | Default | Description                                                                                    |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `pollIntervalMs`        | `1000`  | Delay between health and metrics collection cycles                                             |
| `maxMetricsAgeMs`       | `5000`  | Maximum usable metrics age                                                                     |
| `requestTimeoutMs`      | `3000`  | Collection and ordinary callback timeout                                                       |
| `connectTimeoutMs`      | `10000` | Startup wait for restored connection and initial price acknowledgement, after the engine check |
| `priceUpdateIntervalMs` | `30000` | Delay between standing-price publications                                                      |

RFQ callbacks use the remaining time until `rfq.deadline`, rather than the ordinary callback timeout.

## CLI

```sh
bunx omnious-provider check ./provider.ts
bunx omnious-provider start ./provider.ts
```

Both commands load the file's default-exported configuration. `check` validates the engine and exits. `start` runs until stopped, closing the client on SIGINT or SIGTERM.

## Exported types

The root package exports:

* Configuration and policy: `ProviderConfig`, `PolicyContext`, `QuoteDecision`.
* Engines: `EngineLoad`, `EngineOptions`, `EngineAdapter`, `LlamaCppMetrics`, `VllmMetrics`, `EngineCheck`.
* Client: `ProviderClient`.
* Protocol values: `QuoteTerms`, `RfqRequest`, `QuoteAward`, `QuoteRelease`, `ExecutionRelease`, `Commitment`, `CommitmentRelease`.

The `/protocol` import exposes runtime schemas as well as protocol types, including `Envelope`, `SessionState`, `Welcome`, `PriceUpdatePayload`, and `RfqQuotePayload`. It also exports `PROTOCOL_VERSION`, currently `1`. See the [WebSocket reference](/providers/protocol) for the full server message contract, including welcome fields beyond the SDK's subset schema.