6. Add New Model Adapter

Purpose: Scaffold a new model adapter, register it, and validate it through the smoke and eligibility pipelines.

Prerequisites:

Model API key (for full eligibility run)
Supabase credentials (for full eligibility run)
Familiarity with the adapter interface in packages/ai/src/models/types.ts

Cost / Duration: $0 for scaffold + smoke test | ~$8-25 for eligibility run

Prompt

Add a new model adapter to the Eko AI system.

Model to add: [specify model ID and provider, e.g., "claude-sonnet-4-5" from Anthropic]

Step 1 — Scaffold the adapter file:

Create `packages/ai/src/models/adapters/<model-id>.ts` following the
existing adapter pattern. Reference these files:
- `packages/ai/src/models/types.ts` (ModelAdapter interface)
- `packages/ai/src/models/adapters/gemini-2.5-flash.ts` (example: standard adapter with json_schema support, v5 with extensive tuning)
- `packages/ai/src/models/adapters/deepseek-chat.ts` (example: V4 free-text adapter for models without json_schema)
- `packages/ai/src/models/adapters/grok-4-1-fast-non-reasoning.ts` (example: accuracy-focused guardrails)
- `packages/ai/src/models/adapters/gpt-5.4-nano.ts` (example: topic exclusion via getExcludedTopics)

The adapter must implement:
- `getPromptCustomization(task: AdaptableTask)` for all 7 tasks:
  fact_extraction, evergreen_generation, seed_explosion,
  challenge_content_generation, notability_scoring, fact_validation,
  signoff_review
- `getKnownWeaknesses(): string[]` (model-specific quality concerns)
- `getSignoffGuidance(): string` (instructions for AI-judge review)
- `getExcludedTopics?(): string[]` (optional — topic prefixes this model
  should not handle due to persistent quality failures, e.g., `['sports']`.
  The model router falls back to `gemini-3-flash-preview` for excluded topics.
  See `packages/ai/src/models/adapters/gpt-5.4-nano.ts` for an example.)

For `challenge_content_generation`, the adapter's prompt suffix should include:
- **TARGET FACT KEY DIVERSITY** rules — FCG groups require 3+ unique keys
  across 5 challenges (4 if 5+ keys available), max 2 per key. Groups are
  validated by `validateGroupDiversity()` and retried with explicit key
  assignments on failure. See `gemini-3-flash-preview.ts` or `gpt-5.4-nano.ts`
  for reference prompts.

Step 2 — Register in ADAPTER_FACTORIES:

Edit `packages/ai/src/models/registry.ts`:
- Import the create function
- Add entry to `ADAPTER_FACTORIES` map

Step 3 — Register in model-registry-data:

Edit `packages/config/src/model-registry-data.ts`:
- Add entry with provider, status, and pricing info

Step 4 — Add to test harness MODEL_CONFIGS:

Edit `scripts/seed/lib/llm-test-harness.ts`:
- Add entry to `MODEL_CONFIGS` with tier, provider, and model ID

Step 5 — If the model needs a custom fetch wrapper (e.g., non-standard API
compatibility like DeepSeek's json_schema downgrade), add the wrapper in
`packages/ai/src/model-router.ts` and wire it into `createLanguageModel()`.

Step 6 — Run light smoke test to verify contract compliance:
See [Light Model Adapter Smoke Test](./02-light-adapter-smoke-test.md)

Step 7 — Run iterative eligibility gate (start cheap, escalate if passing):
See [Iterative Eligibility Gate](./03-iterative-eligibility-gate.md)

Step 8 — Run full eligibility pipeline with the new model
to verify it meets the ≥97% threshold across all 7 dimensions:
See [Full Model Adapter Test](./04-full-model-adapter-test.md)

Verification

Adapter file created at packages/ai/src/models/adapters/<model-id>.ts
Adapter implements all required interface methods (7 tasks, getKnownWeaknesses, getSignoffGuidance, optionally getExcludedTopics)
Registered in ADAPTER_FACTORIES in packages/ai/src/models/registry.ts
Registered in packages/config/src/model-registry-data.ts with pricing
Added to MODEL_CONFIGS in scripts/seed/lib/llm-test-harness.ts
Light smoke test passes (Light Model Adapter Smoke Test)
TypeScript compiles (bun run typecheck)
Iterative gate T1 canary passes ≥90% (Iterative Eligibility Gate)
Full eligibility pipeline passes thresholds (≥97% structural, ≥90% subjective) (Full Model Adapter Test)

Currently Registered Adapters (13)

Model	Provider	Adapter Notes
`gpt-5.4-mini`	OpenAI	High-tier escalation model
`gpt-5.4-nano`	OpenAI	Excludes `sports` and `music` topics; default tier candidate
`gpt-5-mini`	OpenAI	Deprecated — use gpt-5.4-mini
`gpt-4o-mini`	OpenAI	Quiz-show register mitigation
`claude-haiku-4-5`	Anthropic	Minimal suffix guidance
`grok-4-1-fast-non-reasoning`	xAI	Accuracy guardrails, sports/hallucination focus
`gemini-2.0-flash-lite`	Google	Ultra-low-cost, minimal guidance
`gemini-2.5-flash`	Google	v5 adapter, most thoroughly tuned
`gemini-3-flash-preview`	Google	Textbook register override, default signoff reviewer, topic fallback model
`deepseek-chat`	DeepSeek	V4 free-text mode, custom fetch wrapper for json_schema downgrade
`mistral-large-latest`	Mistral	Native json_schema
`mistral-medium-latest`	Mistral	Native json_schema
`mistral-small-latest`	Mistral	Native json_schema, cheapest Mistral

Light Model Adapter Smoke Test — Quick contract validation
Iterative Eligibility Gate — Graduated eligibility testing
Full Model Adapter Test — Full eligibility pipeline
Compare Models Head-to-Head — Compare new adapter against existing

Back to index

#6. Add New Model Adapter

#Prompt

#Verification

#Currently Registered Adapters (13)

#Related Prompts

6. Add New Model Adapter

Prompt

Verification

Currently Registered Adapters (13)

Related Prompts