Skip to content

Commit d3b4668

Browse files
mchencomchenco
committed
[Workers AI] Add Model Deprecations reference page with redirects
- Add deprecation data source (src/util/deprecated-models.ts) - Add reference page listing deprecated and planned-deprecation models (src/content/docs/workers-ai/platform/model-deprecations.mdx) - Add reusable content component (src/components/models/DeprecatedModelPage.astro) - Add deprecation banner on planned-deprecation model pages (src/components/models/ModelDetailPage.astro) - Redirect deprecated model URLs to reference page (public/__redirects) - Revert getStaticPaths to original (redirects handle deprecated URLs)
1 parent 808c62e commit d3b4668

6,860 files changed

Lines changed: 6880153 additions & 6318 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/workers-ai-docs/SKILL.md‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# Workers AI Documentation
2+
3+
Guidelines for maintaining Workers AI documentation, including model schemas, release notes, and changelog entries.
4+
5+
## Key Workflows
6+
7+
### 1. Model Schema Updates
8+
9+
Run the API sync script:
10+
11+
```bash
12+
node bin/fetch-ai-models.js
13+
```
14+
15+
**Review changes carefully** - watch for RED FLAGS:
16+
17+
- Pricing removed (major issue)
18+
- Schema structure changes or disappearing completely
19+
- Created_at dates going backwards
20+
- Internal/test naming (e.g., "Dumb Pipe")
21+
22+
Stage only safe changes (feature additions, metadata updates). Exclude files with pricing or breaking schema changes.
23+
24+
### 2. New Model Launch (End-to-End Checklist)
25+
26+
When launching a new model on Workers AI, you need to touch **4 files**. Use this checklist:
27+
28+
1. **Fetch model JSON** — Run `node bin/fetch-ai-models.js` to pull the model from the API into `src/content/workers-ai-models/`. The script fetches ALL models, so verify the specific new file was created.
29+
2. **Verify schema is populated** — The API can be flaky and return an empty `"schema": {}`. If the schema is empty, re-run the fetch script until it populates. Always inspect the JSON file before committing.
30+
3. **Create changelog entry** — `src/content/changelog/workers-ai/{YYYY-MM-DD}-{slug}.mdx`. The changelog URL is derived from the filename: `https://developers.cloudflare.com/changelog/post/{filename-without-extension}/`. If a URL has already been shared externally, the filename must match exactly.
31+
4. **Add release notes entry** — Add a new entry at the TOP of `src/content/release-notes/workers-ai.yaml`. Include a link to the model page and a cross-link to the changelog.
32+
5. **Add pricing row** — Add a row to the LLM pricing table in `src/content/docs/workers-ai/platform/pricing.mdx` (or the appropriate category table for non-LLM models).
33+
6. **Stage selectively** — The fetch script overwrites all model files. Only `git add` the new model file and your other changes. Exclude:
34+
- Unrelated new models the API added
35+
- Existing model files with minor upstream changes (do those in a separate PR)
36+
37+
**New model release notes example:**
38+
39+
```yaml
40+
- publish_date: "YYYY-MM-DD"
41+
title: Model Name now available on Workers AI
42+
description: |-
43+
- [`@cf/vendor/model-name`](/workers-ai/models/model-name/) now available on Workers AI! Description of the model. Read [changelog](/changelog/post/YYYY-MM-DD-slug/) to get started.
44+
```
45+
46+
### 3. Pricing Page
47+
48+
**Location:** `src/content/docs/workers-ai/platform/pricing.mdx`
49+
50+
The pricing page has separate tables for LLMs, embeddings, image, audio, and other models. Each row has three columns: Model, Price in Tokens, Price in Neurons.
51+
52+
**Neuron conversion formula:** The billing rate is `$0.011 per 1,000 Neurons`, so `1 Neuron = $0.000011`. To convert:
53+
54+
```
55+
neurons per M tokens = dollar_price_per_M_tokens / 0.000011
56+
```
57+
58+
Round to the nearest whole number. For example: `$0.50 per M input tokens` → `45455 neurons per M input tokens`.
59+
60+
**Row format:**
61+
62+
```markdown
63+
| @cf/vendor/model-name | $X.XXX per M input tokens <br/> $X.XXX per M output tokens | XXXXX neurons per M input tokens <br/> XXXXX neurons per M output tokens |
64+
```
65+
66+
### 4. Best Practice: Separate Concerns
67+
68+
- **New model additions:** Stage only the relevant new model files
69+
- **API syncs:** Do in a separate PR from model additions
70+
- This makes reviews easier and reduces risk of mixing safe/unsafe changes
71+
72+
### 5. Release Notes
73+
74+
**Location:** `src/content/release-notes/workers-ai.yaml`
75+
76+
**Format:**
77+
78+
- Use `[Bug fix]` prefix for bug fixes
79+
- Use specific endpoint paths like `/v1/chat/completions` instead of generic terms
80+
- Use actual release date (not commit date)
81+
- Avoid internal implementation terms unless users understand them
82+
83+
**Example:**
84+
85+
```yaml
86+
- publish_date: "2026-02-17"
87+
title: Chat Completions API support for gpt-oss models and tool calling improvements
88+
description: |-
89+
- [Bug fix] `/v1/chat/completions` now preserves original tool call IDs...
90+
```
91+
92+
### 6. Changelog (Big Releases Only)
93+
94+
**Location:** `src/content/changelog/workers-ai/YYYY-MM-DD-description.mdx`
95+
96+
Use for major model launches, significant features, or breaking changes. Not for routine bug fixes or minor updates (use release notes instead).
97+
98+
### 7. Model Pages
99+
100+
**Code components:** `src/components/models/code/`
101+
102+
- Use descriptive endpoint names in documentation
103+
- Document all supported API formats for multi-format models (e.g., GPT-OSS supports Responses API, Workers AI Run, and Chat Completions)
104+
105+
## Key Files
106+
107+
| File/Directory | Purpose |
108+
| ------------------------------------------- | ------------------------------------- |
109+
| `src/content/workers-ai-models/*.json` | Model schemas |
110+
| `src/content/release-notes/workers-ai.yaml` | Release notes |
111+
| `src/content/changelog/workers-ai/*.mdx` | Changelog entries (big releases only) |
112+
| `src/components/models/code/*.astro` | Model page code examples |
113+
| `src/pages/workers-ai/models/[name].astro` | Model page template |
114+
| `src/content/docs/workers-ai/platform/pricing.mdx` | Pricing tables (per-model) |
115+
| `bin/fetch-ai-models.js` | API sync script |
116+
117+
## Common Patterns
118+
119+
**API Endpoints:**
120+
121+
- Responses API: `/ai/v1/responses`
122+
- Workers AI Run: `/ai/run` (dynamic format detection)
123+
- Chat Completions: `/v1/chat/completions`
124+
125+
**Bug Fix Descriptions:**
126+
Explain what was broken and why it works now. Do not link to internal MRs.
127+
128+
**Example:**
129+
130+
> [Bug fix] `/v1/chat/completions` now preserves original tool call IDs from models instead of regenerating them. Previously, the endpoint was generating new IDs which broke multi-turn tool calling because AI SDK clients could not match tool results to their original calls.
131+
132+
## Git Conventions
133+
134+
### Branch Naming
135+
136+
Use descriptive branch names that start with the product abbreviation:
137+
138+
- **Format:** `wai-{description}` (wai = Workers AI)
139+
- **Model syncs:** `wai-models-sync`, `wai-update-models-2024-02`
140+
- **New models:** `wai-add-gpt-oss`, `wai-add-llama-4-scout`
141+
- **Bug fixes:** `wai-fix-tool-call-ids`, `wai-fix-streaming-finish-reason`
142+
- **Features:** `wai-add-chat-completions`, `wai-update-model-schemas`
143+
144+
Keep names lowercase with dashes. Avoid generic names like `wai-fix-bugs` or `wai-updates`.
145+
146+
### Commit Messages
147+
148+
Use repository conventions:
149+
150+
- **Format:** `[Product] description` or `type: description`
151+
- **Examples:**
152+
- `[Workers AI] Update model schemas and add GPT-OSS Chat Completions support`
153+
- `[Workers AI] Fix tool call ID validation in streaming responses`
154+
- `fix: correct content field schema to accept array types`
155+
156+
Use imperative mood (add, fix, update, remove). Keep under 72 characters.
157+
158+
### Pull Requests
159+
160+
**Title format:** `{Product}: {short description}`
161+
162+
- Keep description under 50 characters
163+
- Use imperative mood
164+
- **Examples:**
165+
- `Workers AI: add Chat Completions support for GPT-OSS models`
166+
- `Workers AI: fix content field schema for multi-modal inputs`
167+
168+
**PR Body structure:**
169+
170+
Use headers to organize the PR body. Include:
171+
172+
1. **Summary** - 1-2 sentences explaining WHY the PR exists
173+
2. **Changes** - Bullet points of what changed (group related changes)
174+
3. **Key Details** - Any important notes (e.g., excluded files, breaking changes)
175+
176+
Keep bullet points concise (< 10 words). Use formatting for readability.
177+
178+
**Example:**
179+
180+
```markdown
181+
## Summary
182+
183+
Syncs Workers AI models from API and adds Chat Completions support for GPT-OSS models.
184+
185+
## Changes
186+
187+
- Update 45 model files with content field schema fixes
188+
- Add Chat Completions API support for GPT-OSS-120B and GPT-OSS-20B
189+
- Fix tool call ID validation and streaming finish_reason issues
190+
- Update release notes with 2026-02-17 changelog entry
191+
192+
## Notes
193+
194+
4 files excluded due to pricing/schema issues (flux-2-dev, flux-2-klein-4b, flux-2-klein-9b, smart-turn-v2)
195+
```

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,4 +170,4 @@
170170
"onFail": "error"
171171
}
172172
}
173-
}
173+
}

0 commit comments

Comments
 (0)