Quickstart

This path is for a new certified model provider adapter. It assumes Node.js 22+, pnpm 10+, and repository dependencies installed with pnpm install.

Choose The Protocol Path

Add The Leaf

Create a lowercase ASCII kebab-case vendor folder:

self/subcortex/providers/src/providers/<vendor>/
├── definition.ts
├── adapter.ts
├── provider.ts
├── implementation.ts
└── index.ts

implementation.ts is needed when the leaf owns request execution. It is not required when the provider leaf wraps a shared protocol implementation, as src/providers/openai/ does.

Fill The Contracts

1. In definition.ts, export providerDefinition.
2. In adapter.ts, export providerAdapter.
3. In provider.ts, export providerFactory.
4. In index.ts, re-export the leaf's public surface. The generator requires this file as part of leaf validation, but imports definition.ts, adapter.ts, and provider.ts directly.
5. Keep definitions as metadata only: no environment reads, network calls, concrete provider instantiation, or bootstrap branches.
6. Do not hand-author wellKnownProviderId. Built-in provider IDs are deterministically derived from the provider-definition vendorKey; use a semantic vendorKey instead.
7. For API-key providers, declare auth.purpose: 'api_key', auth.required: true, auth.envVar, auth.vaultKeyNamespace, and auth.header. Add modelListEndpoint and modelListFormat when the provider should support dynamic model discovery; add healthCheckEndpoint when key testing should use a dedicated health endpoint. See Schemas ABI Reference for the field contract.
8. For CLI-style providers, declare executionCapabilityProfile on the provider definition (e.g. session_bound_command or persistent_process). Selection-time role compatibility filtering uses this profile to determine which model roles the provider can fill. See the CLI Provider Guide for the full CLI contributor contract, Schemas & ABI Reference for profile values, and Testing Checklist for role assignment test expectations.

The definition should use as const satisfies ProviderDefinitionLeaf. The generated provider catalog hydrates each leaf into a full ProviderDefinition by deriving the built-in wellKnownProviderId from vendorKey. The factory should use as const satisfies ProviderFactoryModule.

Declaring the API-key metadata is enough for the Settings key field. Declaring the discovery metadata opts the provider into the shared model-list path. Do not add provider-specific Settings UI, model-family allowlists, or runtime vendor branches for a normal provider leaf.

Regenerate Catalogs

pnpm --filter @nous/subcortex-providers run generate:providers
pnpm --filter @nous/subcortex-providers run check:generated

Generated files are expected to change when a provider leaf is added or renamed:

self/subcortex/providers/src/provider-definitions.ts
self/subcortex/providers/src/provider-adapters.ts
self/subcortex/providers/src/provider-factories.ts

Do not edit those files by hand.

Run Focused Checks

pnpm --filter @nous/subcortex-providers run typecheck
pnpm --filter @nous/subcortex-providers exec vitest run src/__tests__/provider-codegen.test.ts src/__tests__/public-exports.test.ts src/__tests__/provider-definitions src/__tests__/adapter-resolver.test.ts src/__tests__/provider-pipeline-integration.test.ts --config vitest.config.ts

For docs-only changes, run:

pnpm --filter docs lint
pnpm --filter docs build