Providers

A provider answers the typed questions asked by rules. Compass has no default provider: choose one with the provider option, as shown in Getting Started. Learn why providers are separate from rules in How Compass works.

Providers are named after the API they speak, not after the model behind it:

Provider	API	Use it with
typesafe()	The System One API, which returns calibrated typed answers.	TypeSafe’s Jev.
openaiCompatible()	The OpenAI chat completions API with structured outputs, which many services implement.	OpenAI, OpenRouter, DeepSeek, Ollama, vLLM and similar.

Write your own provider for any other API.

typesafe()

import { typesafe } from "starlight-compass";

typesafe({ apiKey: process.env.MY_KEY, model: "jev-1.13.0" });

Queries a TypeSafe System One model, like Jev. These models answer typed questions directly with calibrated probabilities, which is what rules ask for. Learn how to set it up.

apiKey

Type: string
Default: the TYPESAFE_API_KEY environment variable

The TypeSafe API key. Prefer the environment variable to keep the key out of your repository.

model

Type: string
Default: "jev-latest"

The model to query. Pin a version for reproducible results.

fetch

Type: typeof fetch
Default: globalThis.fetch

A custom fetch implementation, e.g. to route requests through a proxy. The ask option recreates the provider on the server without it.

openaiCompatible()

import { openaiCompatible } from "starlight-compass";

// OpenAI
openaiCompatible({ model: "gpt-4o-mini" });

// Any other service or server that implements the API
openaiCompatible({ baseUrl: "https://openrouter.ai/api/v1", model: "deepseek/deepseek-chat" });

// A local model, e.g. served by Ollama. No API key needed.
openaiCompatible({ baseUrl: "http://localhost:11434/v1", model: "llama3.1" });

Queries any model through the chat completions API with structured outputs. Many services and servers implement this API, so one provider covers all of them: you only choose the baseUrl and the model. Learn how to set it up. Compass asks for the probabilities as JSON, then validates them, normalizes them and turns them into the same answers as any other provider.

Caution

Chat models state probabilities they have not calibrated, and they can change between model versions. Use typesafe() when you fail builds on findings, and treat this provider as a fallback for reviews in the dev toolbar or with failOn: "never".

apiKey

Type: string
Default: the OPENAI_API_KEY environment variable

The API key of the service. Prefer the environment variable to keep the key out of your repository. Without a key, the provider is only configured when you set a custom baseUrl, as local servers don’t need one.

baseUrl

Type: string
Default: "https://api.openai.com/v1"

The base URL of the API, without /chat/completions.

model

Type: string
Default: "gpt-4o-mini"

The model to query. It must support structured outputs. Pin a dated version for reproducible results.

fetch

Type: typeof fetch
Default: globalThis.fetch

A custom fetch implementation, e.g. to route requests through a proxy. The ask option recreates the provider on the server without it.

CompassProvider

Caution

The provider API is experimental and may change in minor releases before 1.0.

interface CompassProvider {
  name: string;
  serialization?: { factory: "typesafe" | "openaiCompatible"; options: unknown };
  setupHint: string;
  createClient(context: {
    env: Record<string, string | undefined>;
  }): CompassClient | undefined;
}

interface CompassClient {
  id: string;
  ask(request: CompassRequest): Promise<CompassResponse>;
}

• name: a unique name, e.g. "typesafe".
• serialization: describes how to recreate a built-in provider in the server bundle. The ask option needs it, so custom providers only work with the manual setup.
• setupHint: a sentence explaining how to configure the provider, logged when createClient() returns undefined.
• createClient(): returns a client, or undefined when the provider is not configured, e.g. because an API key is missing. env includes variables from .env files.
• id: identifies the provider and requested model, e.g. "typesafe/jev-latest". Part of the cache key.
• ask(): answers every question of a request in a single call.

Questions and answers

Question type	Question fields	Answer fields
"boolean"	instructions, criteria?: { true, false }	probability (0 to 1)
"choice"	instructions, options: Record<string, string | null>	choice, probabilities, confidence
"score"	instructions, levels: string[]	score, probabilities: number[], confidence

A CompassResponse has an answers map with the same keys as the request’s questions, and the exact model that answered.