Model provider SDK
A model provider translates its upstream API into Glixo's typed model interface. It declares account settings and network permissions, discovers models, validates configuration and produces a pull stream of response events. The Ollama tutorial supplies a complete project in four languages.
Create a provider
glxdev new --kind llm-provider --language typescript --package-id org.example.ollama --name "Ollama Provider" --publisher org.example --output ./ollama-provider
cd ollama-provider
glxdev doctor
glxdev check
npm ci --prefix vendor/glixo-extension-sdk --ignore-scripts
npm run build --prefix vendor/glixo-extension-sdk
npm ci --install-links
npm run build
Use the provider template's build script: it selects provider-compat rather than contribution. The other language templates have their own recipes. The provider WIT and typed request/event WIT are the component contract. The public examples use the pull-stream world with version 3.0.0; preserve that literal world identifier in the manifest and build settings.
Provider exports
| Operation | Return value and responsibility |
|---|---|
describe(context) |
Descriptor: provider ID, name, version, models and capability names with optional flags. Report only implemented capabilities. |
validate-configuration(config-json,context) |
Configuration report: valid and diagnostic strings. Parse and validate account settings. |
list-models(context) |
Available model IDs, through the approved account connection. Do not return a guessed list after an HTTP failure. |
start(request,context) |
Integer guest stream handle, after opening a checked upstream request. |
next(handle) |
One typed event, or none after completion. Keep incremental stream state in your component. |
cancel(handle) |
Stop upstream work; race with next has one winner. |
drop(handle) |
Release stream state and its HTTP response. |
These functions return WIT results where specified. In TypeScript, success values are direct, failure exports throw a primitive error string, and completion is undefined. Inspect Ollama TypeScript, C#, Go, or Rust for full implementations.
Context, credentials and host imports
The provider context contains configurationJson and approved endpoints. Ollama expects an endpoint named ollama, not a guest-selected arbitrary URL. Its request adapter uses the supplied endpoint handle with the exact methods/paths declared in the manifest. Use the HTTP SDK for upstream bytes and cleanup.
The provider-host interface also supplies secret-use(name), scoped-state-get(key), log(level,message), now-unix-ms() and random-bytes(len). secret-use returns a host-managed reference for an approved slot; it is not a plaintext credential API. Pass the slot name, not the returned opaque reference, in an HTTP request's secretHandle. State access is scoped; this provider interface offers get only, rather than the contribution broker's full state API. The provider-host WIT contains the exact signatures.
Request format
| Field | Meaning |
|---|---|
requestId, model |
Preserve the request ID on every event and use the selected model. |
messages |
Role plus typed content parts; translate each supported part explicitly. |
tools |
Tool name, description and JSON Schema string. |
responseFormat |
Optional kind and schema JSON; validate whether the upstream supports it. |
sampling |
Optional temperature, top-p and output-token limit. |
extensionsJson |
Explicit extension data; unknown fields do not grant host access. |
Content variants include text, reasoning, tool-call details, tool results, structured output, media references, citations, annotations and unknown values. SDK convenience types cover a subset; use the generated WIT types when constructing exported events. Reject unsupported required features clearly instead of silently losing them.
Event format and terminal behavior
Generated TypeScript events have camelCase record fields and WIT variant tags. This illustrative terminal event has a text part and token usage:
{
"requestId": "request-42",
"part": {"tag": "text", "val": "Hello"},
"usage": {"inputTokens": 8, "outputTokens": 1},
"finish": {"tag": "stop"}
}
Absent WIT option fields use undefined in JavaScript and are omitted by JSON serialization. This JSON illustrates the shape, not the WIT wire encoding. SDK ProviderEvent helper records differ from generated variants; explicitly map them. In particular, the TypeScript helper's ContentPart uses {text}, {reasoning} or {toolCallDetails}, whereas the export uses {tag,val}. C#'s convenience event includes error fields; Rust supplies TypedError; TypeScript and Go helpers do not expose the whole generated event contract. The WIT event record includes optional warning, typed error, provider request/response IDs and extensible content variants.
A stream emits one terminal event, followed by none on subsequent reads. Finish reasons are stop, length, tool, cancelled, content-filter, error or unknown with its preserved representation. A tool-call detail carries id, name, optional argumentsFragment, and complete; retain identity across fragments and emit valid final arguments. Distinguish visible answer text from reasoning. Preserve reported usage and upstream IDs; do not fabricate missing counts.
Retain only the stream state needed between start and next. Check cancellation, queue pending events without dropping the terminal, and release every upstream handle in drop. Stream tables are transient; they do not survive extension restart.
Tests and account status
Test discovery, invalid settings, denial, split records, tool-call follow-ups, reasoning/text fidelity, usage, a single terminal, cancellation and cleanup. The Ollama source shows the native /api/tags, /api/show and /api/chat mappings. Follow its real account setup and request checklist after signing and activation. CLI fixture testing requires a compatible installed host and the corrected CLI build runner; see test limitations.
Provider account quota/billing status is an optional companion to inference. The public Ollama SDK snapshot does not implement it. See account status for declaration, metric meanings and compatible-host requirements. Do not make paid inference requests to estimate account quota or substitute local token counters for provider-reported status.