AI & models.
How tiers map to providers, and how to override them.
Every AI call in SpecGraph goes through a small factory: code asks for a use case, not a model. The factory resolves the use case to a specific model, so the model behind each call can be swapped centrally without changing the calling code.
Five tiers #
| Tier | Used for |
|---|---|
interview | Q&A and structured extraction during phase chats |
enhance | Short rewrites — the "Improve" menu on any text field |
content | Long-form drafting — the consolidated brief, the spec narrative |
file | Multimodal ingestion — pasted PDFs, screenshots, OCR'd images |
default | Fallback for anything not yet categorized |
These tiers are stable. The model behind each tier can change as providers ship new releases.
Why tiers, not direct provider calls #
Two reasons:
- Swap once, applies everywhere. Moving the
contenttier from one provider to another is a single configuration change. Every call site picks up the new model on the next request. - Right-size per use case. Short rewrites use a fast model tuned for editing; the spec narrative uses a high-quality model tuned for long-form writing. Each tier picks the model best suited to its job.
Defaults today #
| Tier | Model |
|---|---|
interview | Gemini 2.0 Flash or Claude Haiku 4.5 |
enhance | Mistral Small 3.2 or Claude Haiku 4.5 |
content | Claude Sonnet 4.6 |
file | Gemini 2.5 Flash or Claude Haiku 4.5 |
default | Mistral Small 3.2 or Claude Haiku 4.5 |
These can change as we evaluate new releases. The factory pattern means a model swap doesn't require a SpecGraph release.
Overriding a model #
Workspace admins can pin a tier to a specific model in Settings → AI. The pin applies for everyone in the workspace and is recorded in the project audit log whenever a pinned tier is used.
Bring your own Claude (Azure AI Foundry / AWS Bedrock) #
Workspaces with stricter data-residency or procurement requirements can route the Claude tiers (interview, content, file) through their own Claude deployment hosted on:
- Azure AI Foundry — Claude models deployed inside your Azure subscription.
- AWS Bedrock — Claude models served through Amazon Bedrock in your AWS account.
When this is enabled, Specgraph stops calling Anthropic directly for those tiers and instead calls your endpoint with credentials you supply. Prompts, completions, and any attached files travel only between Specgraph and your tenant — never through a shared key.
This is a per-workspace capability that the workspace admin enables in Settings → AI → Bring your own model:
- Pick the provider (Azure AI Foundry or AWS Bedrock).
- Paste the endpoint URL + the credential (Azure key or AWS IAM role / access keys).
- Map each Claude tier to the deployment name you registered with the provider.
- Save — the next AI call for that tier routes through your endpoint.
Other tiers (e.g. enhance, default) keep using Specgraph's hosted models unless they're also explicitly mapped. Admins can revert to Specgraph-hosted Claude at any time without affecting saved project data.
When AI is not used #
Locking a phase is a human action. So is approving an amendment. So is publishing a knowledge base entry. AI drafts content; humans commit it. The system never auto-approves AI output.
If you want a clean record of which paragraphs were AI-drafted vs hand-written, every phase tracks the provenance per field — visible in the project audit page.