Provider Adapters
Contributor guide for certified model provider adapters
Provider Adapters
Certified provider adapters are the signed-driver-style integration points that let Nous talk to model vendors without adding one-off runtime branches. A provider leaf declares the vendor metadata, exports an adapter, exports a provider factory, and lets the generated catalogs make the leaf discoverable.
Most contributors work in one provider leaf:
self/subcortex/providers/src/providers/<vendor>/
├── definition.ts
├── adapter.ts
├── provider.ts
├── implementation.ts
└── index.tsSome leaves do not need their own implementation.ts. The OpenAI leaf reuses self/subcortex/providers/src/protocols/openai-api/provider.ts and wraps it with certified openai metadata, adapter, and factory exports.
Boundary Map
| Area | What it owns | Contributor posture |
|---|---|---|
src/providers/<vendor>/ | Certified provider leaf files | Add or update these for a provider |
src/schemas/ | Nous-side provider, adapter, and factory ABI | Read before changing contracts |
src/protocols/<protocol>/ | Reusable protocol logic | Reuse for compatible APIs |
src/shared/ | Truly generic output helpers and fallback adapters | Avoid dumping provider convenience code here |
src/provider-definitions.ts | Generated provider metadata catalog | Regenerate, do not hand-edit |
src/provider-adapters.ts | Generated certified adapter catalog | Regenerate, do not hand-edit |
src/provider-factories.ts | Generated provider factory catalog | Regenerate, do not hand-edit |
src/adapter-resolver.ts | Adapter-key resolution policy | Do not edit for a normal provider addition |
src/runtime/provider-runtime.ts | ProviderRegistry and inference-runtime composition | Do not add vendor branches for normal additions |
Reading Order
- Quickstart for the first working leaf.
- Anthropic Reference for a real native provider walkthrough.
- Provider Leaf Anatomy for file responsibilities and protocol choices.
- Schemas ABI Reference for the contracts.
- Generated Catalogs Workflow for code generation.
- Testing Checklist before opening a PR.
- What Not To Edit when you are unsure where a change belongs.
Use Anthropic as the reference leaf for shape, naming, exports, tests, and failure handling. Do not copy Anthropic's wire protocol unless your provider really has Anthropic Messages API semantics.
For API-key providers, the definition leaf also drives product integration. auth metadata creates the vault-backed Settings key field, and modelListEndpoint/modelListFormat opt the provider into dynamic model discovery. Start with Quickstart, then use Schemas ABI Reference for the discovery and health metadata contract.