Repository Public Research preview
1/** Short, verified guidance per topic. Behavioural claims match knowledge.json (live probes, 2026-11-09). */2export const GUIDES = {3 models: `Current generation: claude-fable-5-2 (most capable), claude-opus-5-5 (default choice), claude-sonnet-5-5 (speed/cost balance), claude-haiku-5-5 (cheapest, high volume). All four: 1M-token context, 128K max output. Current ids carry no date suffix; the three 4.5 models do (claude-opus-4-5-20251101, claude-sonnet-4-5-20250929, claude-haiku-4-5-20251001). Never invent an id: call list_models. Limits and capabilities come from GET /v1/models (max_input_tokens, max_tokens, capabilities).`,4 thinking: `Use thinking: {type: "adaptive"} on every model except the 4.5 family, which needs {type: "enabled", budget_tokens: N} (N ≥ 1024 and below max_tokens). budget_tokens is rejected on Fable 5.x, Opus 4.7 and later, Sonnet 5 and later, Haiku 5.5; still accepted (deprecated) on Opus 4.6 and Sonnet 4.6. Thinking cannot be disabled on Fable 5/5.1/5.2 and Opus 5.5: omit the field and lower effort. Sonnet 5.5 rejects "disabled" and accepts {type: "between_tools"} instead (only that model). Opus 5 and Haiku 5.5 reject "disabled" combined with effort xhigh/max. Thinking text is hidden by default on recent models: add display: "summarized" to read a summary. Thinking tokens are billed as output. Return thinking blocks unchanged when you resend the conversation.`,5 effort: `output_config: {effort} — never top-level. Levels: low, medium, high, xhigh, max on Fable 5.x, Opus 4.7+, Sonnet 5+, Haiku 5.5; low/medium/high/max on Opus 4.6 and Sonnet 4.6; low/medium/high on Opus 4.5; unsupported on Sonnet 4.5 and Haiku 4.5. Set it explicitly: defaults differ by model. Lower effort means fewer tool calls and shorter work, not just shorter text.`,6 sampling: `Under API version 2026-10-21 (the default of current SDKs) temperature, top_p and top_k are rejected on every model ("Extra inputs are not permitted"). Under 2023-06-01 they are still accepted by the 4.5 models and by Opus 4.6 / Sonnet 4.6, and rejected by newer models. For determinism use structured outputs, explicit instructions and lower effort.`,7 tools: `Define tools with name, description, input_schema. Add strict: true (on the tool, with additionalProperties: false and every property required) to guarantee schema-valid input. tool_choice "any" and "tool" are rejected by Fable 5.1/5.2, Opus 5.5 and Sonnet 5.5: use "auto" and name the tool in the prompt. One assistant turn may contain several tool_use blocks: run them and return every tool_result in a single user message (is_error: true for failures). Append the full assistant content to history, not only the text. Stop reasons to handle: tool_use, end_turn, max_tokens, pause_turn (resend to resume), refusal.`,8 structured_outputs: `output_config: {format: {type: "json_schema", schema}}. Object schemas need additionalProperties: false. The reply's text block is JSON matching the schema when stop_reason is end_turn; check stop_reason first (max_tokens truncates JSON). The old top-level output_format is deprecated. Assistant prefill is rejected by every model from 4.6 on, so do not use "{" prefill to force JSON. Not combinable with citations.`,9 caching: `Cache is a prefix match over tools → system → messages. Mark up to 4 breakpoints with cache_control: {type: "ephemeral"}, or set it top-level for automatic placement. Keep stable content first; any change before a breakpoint invalidates what follows (timestamps, unsorted JSON, changing tool lists). Verify with usage.cache_read_input_tokens. Writes cost 1.25× (5 min) or 2× (1 h) input price; reads are a small fraction of it (see estimate_cost).`,10 streaming: `Stream anything long. SDK helpers: TypeScript client.messages.stream(...).finalMessage(); Python with client.messages.stream(...) as s: s.get_final_message(). Events: message_start, content_block_start/delta/stop, message_delta (carries stop_reason and usage), message_stop. Large max_tokens without streaming risks HTTP timeouts.`,11 batches: `client.messages.batches.create({requests: [{custom_id, params}]}) → poll retrieve(id).processing_status until "ended" → iterate results(id). 50% of standard prices. Results arrive in any order: key by custom_id. Result types: succeeded, errored, canceled, expired. No fast mode in batches.`,12 files: `client.files.upload(...) returns an id; reference it as {type: "document", source: {type: "file", file_id}} (PDF/text) or {type: "image", source: {type: "file", file_id}}. Also: files.list, files.retrieveMetadata, files.download, files.delete. Inline alternatives: base64 image/PDF blocks, or {type: "text"} document sources.`,13 citations: `Add citations: {enabled: true} to each document block. Cited text blocks carry a citations array (cited_text, document_index, location). Supported on every probed model. Cannot be combined with structured outputs.`,14 server_tools: `Declared in tools, executed by Anthropic: web_search_20260209, web_fetch_20260209 (all probed models except Haiku 4.5, which needs web_search_20250305 / web_fetch_20250910), code_execution_20260521, tool search (tool_search_tool_bm25_20251119 / _regex_; mark other tools defer_loading: true, never all of them). Results arrive as content blocks in the same response; errors come back as HTTP 200 with an error object in the result block.`,15 context: `Long conversations: compaction (beta compact-2026-01-12, context_management.edits [{type: "compact_20260112"}]; not on the 4.5 family) summarises old turns; context editing (beta context-management-2025-06-27; clear_tool_uses_20250919, clear_thinking_20251015) drops old tool results or thinking. Task budgets (beta task-budgets-2026-03-13, output_config.task_budget {type: "tokens", total ≥ 20000}) let the model pace an agentic run; not on 4.5/4.6 models. Mid-conversation system messages ({role: "system"} inside messages) work on Fable 5.x, Opus 4.8+, Sonnet 5+, Haiku 5.5; the entry must come directly AFTER the user message it applies to (the API rejects it after an assistant turn).`,16 agents: `Four ways to build an agent: (1) manual loop over client.messages.create — you own everything; (2) SDK tool runner (client.beta.messages.toolRunner / tool_runner) — SDK loops over tools you define; (3) Managed Agents (beta) — Anthropic runs the loop and a sandbox; create agent + environment once, then sessions; (4) Claude Agent SDK — Claude Code as a library with built-in file/shell tools (separate package). Start with the simplest tier that works: many tasks need a single call or a fixed workflow, not an agent. Use scaffold_agent for runnable starters.`,17 errors: `400 invalid_request_error (fix the request: see lint_request), 401 authentication_error (key), 403 permission_error, 404 not_found_error (model id or resource), 413 request_too_large, 429 rate_limit_error (honour retry-after), 500 api_error, 529 overloaded_error (retry with backoff). SDKs retry 408/409/429/5xx twice by default. A refusal is HTTP 200 with stop_reason "refusal". Quote the request-id header when reporting problems.`,18 cost: `Price = input + output (+ cache writes/reads). Thinking tokens are output tokens. Levers in order: prompt caching, smaller prompts, batches (50%), lower effort, cheaper model. Measure cost per completed task, not per request. Use estimate_cost and compare_costs; verify with response.usage.`,19};20