No standardized way to create custom AI providers with validation and metadata

[morozow]

Context

The AIProvider interface defines the contract for providers, but there is no framework for creating new providers. Users who want to integrate a private LLM endpoint, AWS Bedrock, Mistral, or any other service must implement the interface manually.

Problem

1. No option validation. A custom provider receives raw options with no schema validation. A typo in the API key field name or a missing required field is only discovered at the first API call, not at construction time.
2. No metadata contract. Custom providers have no standard way to declare their kind, capabilities, displayName, or description. These fields are ad-hoc and inconsistent.
3. Second-class citizens. Built-in providers (OpenAI, Anthropic, Gemini) have structured initialization, but custom providers are just raw class implementations with no shared tooling.
4. No introspection. There is no way to inspect a provider's option schema programmatically (e.g., for generating configuration UIs or JSON Schema).

Expected behavior

• A defineProvider() function that accepts a Zod schema for options, a create function, and metadata.
• Options validated at creation time with clear error messages.
• Static metadata accessible on the factory function without calling it.
• Custom providers treated identically to built-in ones in discovery and registration.

[morozow]

Resolved. Introduced defineProvider() as the universal provider contract:

defineProvider(config) (src/provider/defineProvider.ts) — accepts id, schema (Zod), create function, and optional kind, displayName, description, capabilities. Returns a callable factory (options) => AIProvider with static metadata properties.

Zod validation at creation time — options are parsed through the Zod schema before create is called. Invalid options throw BridgeError CONFIG with field names and descriptions. The create function is never called with invalid input.

Result validation — the object returned by create() is checked for required AIProvider fields (id, models, complete). Missing fields throw BridgeError CONFIG.

Static metadata — the factory function has readonly properties: factory.id, factory.kind, factory.schema, factory.capabilities, factory.displayName, factory.description. Accessible without calling the factory.

Built-in parity — openAI, anthropic, and gemini factories are themselves implemented via defineProvider(). Custom and built-in providers are structurally identical.