Provider drivers

Provider drivers connect Faimulus model execution to a concrete AI backend while keeping workflows role-first and provider-agnostic.

Package contract

Create a trusted driver package under workspace/drivers/provider/<name>/.

manifest.yaml:

apiVersion: 1
kind: provider
type: my-provider
entrypoint: ./driver.ts

The type must be unique across loaded provider drivers.

Driver implementation

Export an AiProviderDefinition from the entrypoint file.

driver.ts:

import type {
  AiModel,
  AiModelRequest,
  AiProviderDefinition,
} from "@faimulus/driver-sdk";

interface ProviderConfig {
  apiKey: string;
  model: string;
}

class MyProviderModel implements AiModel {
  constructor(private readonly config: ProviderConfig) {}

  async execute(request: AiModelRequest): Promise<unknown> {
    return {
      model: this.config.model,
      nodeId: request.nodeId,
      role: request.modelRole,
      input: request.input,
    };
  }
}

const definition: AiProviderDefinition<ProviderConfig> = {
  type: "my-provider",
  displayName: "My provider",
  configSchema: {
    type: "object",
    additionalProperties: false,
    required: ["apiKey"],
    properties: {
      apiKey: { type: "string", writeOnly: true },
      model: { type: "string" },
    },
  },
  async createModel(config) {
    return new MyProviderModel(config);
  },
};

export default definition;

Agent-capable providers implement executeAgentTurn. Faimulus supplies structured assistant tool calls and tool results; each tool result contains its toolCallId, workflow-visible name, and serialized content. Translate these neutral messages to the provider protocol instead of reconstructing tool identity from earlier messages.

Workspace configuration

Register a provider instance and map model roles.

config/providers.yaml:

version: 1
providers:
  primary:
    type: my-provider
    config:
      apiKey: ${MY_PROVIDER_API_KEY}

config/models.yaml:

version: 1
models:
  general:
    provider: primary
    config:
      model: fast-model

Startup and verification

1. Restart the server so startup discovery recompiles and loads the driver.
2. Verify model roles resolve through this provider by running a workflow that uses model.role.
3. Check startup logs for discovery and registration messages if loading fails.