chub-dev 0.2.0-beta.1 → 0.2.0-beta.2

package/dist/anthropic/docs/sdk/javascript/DOC.md

@@ -0,0 +1,499 @@
+---
+name: sdk
+description: "Claude AI assistant API for text generation, analysis, conversation, streaming, tool use, vision, and batch processing"
+metadata:
+  languages: "javascript"
+  versions: "0.67.0"
+  updated-on: "2025-10-24"
+  source: maintainer
+  tags: "anthropic,sdk,llm,ai,claude"
+---
+
+# Anthropic JavaScript/TypeScript SDK Coding Guidelines
+
+You are an Anthropic API coding expert. Help me with writing code using the Anthropic API calling the official libraries and SDKs.
+
+You can find the official SDK documentation and code samples here:
+https://docs.anthropic.com/claude/reference/
+
+## Golden Rule: Use the Correct and Current SDK
+
+Always use the Anthropic TypeScript SDK to call the Claude models, which is the standard library for all Anthropic API interactions. Do not use legacy libraries or unofficial SDKs.
+
+- **Library Name:** Anthropic TypeScript SDK
+- **NPM Package:** `@anthropic-ai/sdk`
+- **Legacy Libraries**: Other unofficial packages are not recommended
+
+**Installation:**
+
+- **Correct:** `npm install @anthropic-ai/sdk`
+
+**APIs and Usage:**
+
+- **Correct:** `import Anthropic from '@anthropic-ai/sdk'`
+- **Correct:** `const client = new Anthropic({})`
+- **Correct:** `await client.messages.create(...)`
+- **Correct:** `await client.messages.stream(...)`
+- **Incorrect:** `AnthropicClient` or `AnthropicAPI`
+- **Incorrect:** `client.generate` or `client.completions`
+- **Incorrect:** Legacy completion endpoints
+
+## Initialization and API key
+
+The `@anthropic-ai/sdk` library requires creating an `Anthropic` instance for all API calls.
+
+- Always use `const client = new Anthropic({})` to create an instance.
+- Set the `ANTHROPIC_API_KEY` environment variable, which will be picked up automatically.
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+// Uses the ANTHROPIC_API_KEY environment variable if apiKey not specified
+const client = new Anthropic({});
+
+// Or pass the API key directly
+// const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+```
+
+## Models
+
+- By default, use the following models when using `@anthropic-ai/sdk`:
+  - **General Tasks:** `claude-sonnet-4-20250514`
+  - **Legacy Model (if needed):** `claude-3-7-sonnet-latest`
+
+- Advanced models available:
+  - **High-performance:** `claude-opus-4-20250514`
+
+## Basic Inference (Text Generation)
+
+Here's how to generate a response from a text prompt.
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({}); // Assumes ANTHROPIC_API_KEY is set
+
+async function run() {
+  const message = await client.messages.create({
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'Hello, Claude' }],
+    model: 'claude-sonnet-4-20250514',
+  });
+
+  console.log(message.content);
+}
+
+run();
+```
+
+Multimodal inputs are supported by passing image data in the messages array. You can include images, documents, and other file types using base64 encoding or file uploads.
+
+For file uploads, use the `client.beta.files.upload` method:
+
+```javascript
+import fs from 'fs';
+import Anthropic, { toFile } from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+// File upload example
+await client.beta.files.upload({
+  file: await toFile(fs.createReadStream('/path/to/file'), undefined, { type: 'application/json' }),
+  betas: ['files-api-2025-04-14'],
+});
+```
+
+## Streaming Responses
+
+We provide comprehensive support for streaming responses using Server Sent Events (SSE).
+
+### Basic Streaming
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+const stream = await client.messages.create({
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello, Claude' }],
+  model: 'claude-sonnet-4-20250514',
+  stream: true,
+});
+
+for await (const messageStreamEvent of stream) {
+  console.log(messageStreamEvent.type);
+}
+```
+
+### Advanced Streaming with Helpers
+
+The SDK provides powerful streaming helpers for convenience:
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+async function main() {
+  const stream = client.messages
+    .stream({
+      model: 'claude-sonnet-4-20250514',
+      max_tokens: 1024,
+      messages: [
+        {
+          role: 'user',
+          content: 'Say hello there!',
+        },
+      ],
+    })
+    .on('text', (text) => {
+      console.log(text);
+    });
+
+  const message = await stream.finalMessage();
+  console.log(message);
+}
+
+main();
+```
+
+You can cancel streams by calling `stream.controller.abort()` or breaking from loops.
+
+## Tool Use (Function Calling)
+
+The SDK supports tool use (function calling) for extending Claude's capabilities.
+
+### Custom Tools
+
+Define custom functions that Claude can call:
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+async function run() {
+  const response = await client.messages.create({
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: "What's the weather like in San Francisco?" }],
+    tools: [
+      {
+        name: 'get_weather',
+        description: 'Get the current weather in a given location',
+        input_schema: {
+          type: 'object',
+          properties: {
+            location: { description: 'The city and state, e.g. San Francisco, CA', type: 'string' },
+            unit: { description: 'Unit for the output - one of (celsius, fahrenheit)', type: 'string' },
+          },
+          required: ['location'],
+        },
+        type: 'custom',
+      },
+    ],
+    tool_choice: { type: 'auto' },
+  });
+
+  // Handle tool use in the response
+  if (response.content.some((block) => block.type === 'tool_use')) {
+    // Process tool calls and provide results back to Claude
+    console.log('Claude wants to use a tool!');
+  }
+}
+
+run();
+```
+
+### Built-in Beta Tools
+
+The beta API provides specialized built-in tools.
+
+#### Bash Tool
+
+```javascript
+const response = await client.beta.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'List the files in the current directory' }],
+  tools: [{ type: 'bash_20250124', name: 'bash' }],
+});
+```
+
+#### Computer Use Tool
+
+```javascript
+const response = await client.beta.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Take a screenshot' }],
+  tools: [
+    {
+      type: 'computer_20250124',
+      name: 'computer',
+      display_width_px: 1920,
+      display_height_px: 1080,
+    },
+  ],
+});
+```
+
+#### Text Editor Tool
+
+```javascript
+const response = await client.beta.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Create a Python script' }],
+  tools: [{ type: 'text_editor_20250124', name: 'str_replace_editor' }],
+});
+```
+
+### Tool Choice Configuration
+
+Control how Claude uses tools:
+
+- `{ type: 'auto' }` - Claude decides when to use tools
+- `{ type: 'any' }` - Claude must use a tool
+- `{ type: 'tool', name: 'specific_tool' }` - Force a specific tool
+- `{ disable_parallel_tool_use: true }` - Disable parallel tool execution
+
+## Message Batches
+
+The SDK supports the Message Batches API for processing multiple requests efficiently.
+
+### Creating a Batch
+
+```javascript
+await client.messages.batches.create({
+  requests: [
+    {
+      custom_id: 'my-first-request',
+      params: {
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: 'Hello, world' }],
+      },
+    },
+    {
+      custom_id: 'my-second-request',
+      params: {
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: 'Hi again, friend' }],
+      },
+    },
+  ],
+});
+```
+
+### Getting Batch Results
+
+```javascript
+const results = await client.messages.batches.results(batch_id);
+for await (const entry of results) {
+  if (entry.result.type === 'succeeded') {
+    console.log(entry.result.message.content);
+  }
+}
+```
+
+## Additional Capabilities
+
+### System Instructions
+
+Guide Claude's behavior with system instructions:
+
+```javascript
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello' }],
+  system: [{ text: 'You are a helpful assistant that responds in a pirate voice.', type: 'text' }],
+});
+```
+
+### Thinking (Beta Feature)
+
+Configure Claude's reasoning process:
+
+```javascript
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Solve this complex problem...' }],
+  thinking: { budget_tokens: 1024, type: 'enabled' },
+});
+```
+
+### Temperature and Generation Parameters
+
+Control randomness and output:
+
+```javascript
+const response = await client.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Write a creative story' }],
+  temperature: 0.7,
+  top_k: 5,
+  top_p: 0.9,
+});
+```
+
+### Token Counting
+
+Count tokens before making requests:
+
+```javascript
+const tokenCount = await client.messages.countTokens({
+  messages: [{ role: 'user', content: 'Hello, Claude' }],
+  model: 'claude-sonnet-4-20250514',
+});
+console.log(tokenCount); // { input_tokens: 25, output_tokens: 13 }
+```
+
+### Auto-pagination
+
+Handle paginated responses automatically:
+
+```javascript
+async function fetchAllMessageBatches(params) {
+  const allMessageBatches = [];
+  // Automatically fetches more pages as needed.
+  for await (const messageBatch of client.messages.batches.list({ limit: 20 })) {
+    allMessageBatches.push(messageBatch);
+  }
+  return allMessageBatches;
+}
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling with specific error types:
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+try {
+  const message = await client.messages.create({
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: 'Hello, Claude' }],
+    model: 'claude-sonnet-4-20250514',
+  });
+} catch (err) {
+  if (err instanceof Anthropic.APIError) {
+    console.log(err.status); // 400
+    console.log(err.name); // BadRequestError
+    console.log(err.headers); // {server: 'nginx', ...}
+    console.log(err.requestID); // request id string
+  } else {
+    throw err;
+  }
+}
+```
+
+### Error Types
+
+| Status Code | Error Type                 |
+| ----------- | -------------------------- |
+| 400         | `BadRequestError`          |
+| 401         | `AuthenticationError`      |
+| 403         | `PermissionDeniedError`    |
+| 404         | `NotFoundError`            |
+| 422         | `UnprocessableEntityError` |
+| 429         | `RateLimitError`           |
+| >=500       | `InternalServerError`      |
+| N/A         | `APIConnectionError`       |
+
+All errors extend from `AnthropicError` which extends the standard `Error` class.
+
+### Request IDs
+
+All responses include a `_request_id` property for debugging:
+
+```javascript
+const message = await client.messages.create({
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello, Claude' }],
+  model: 'claude-sonnet-4-20250514',
+});
+console.log(message._request_id);
+```
+
+## Advanced Configuration
+
+### Retries
+
+Configure automatic retry behavior:
+
+```javascript
+// Configure default retries for all requests
+const client = new Anthropic({
+  maxRetries: 3, // default is 2
+});
+
+// Or configure per-request
+await client.messages.create(
+  { max_tokens: 1024, messages: [{ role: 'user', content: 'Hello, Claude' }], model: 'claude-sonnet-4-20250514' },
+  { maxRetries: 5 },
+);
+```
+
+### Timeouts
+
+Set custom timeout values:
+
+```javascript
+// Configure default timeout for all requests
+const client = new Anthropic({
+  timeout: 20 * 1000, // 20 seconds (default is 10 minutes)
+});
+
+// Override per-request
+await client.messages.create(
+  { max_tokens: 1024, messages: [{ role: 'user', content: 'Hello, Claude' }], model: 'claude-sonnet-4-20250514' },
+  { timeout: 5 * 1000 },
+);
+```
+
+### Logging
+
+Enable debug logging:
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({
+  logLevel: 'debug', // Show all log messages
+});
+
+// Or use environment variable
+// ANTHROPIC_LOG=debug
+```
+
+### Custom Fetch Options
+
+Customize the underlying fetch behavior:
+
+```javascript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({
+  fetchOptions: {
+    // Custom RequestInit options
+  },
+});
+```
+
+## Useful Links
+
+- Documentation: https://docs.anthropic.com/
+- API Reference: https://docs.anthropic.com/claude/reference/
+- Models: https://docs.anthropic.com/claude/docs/models-overview
+- API Pricing: https://www.anthropic.com/pricing
+- Rate Limits: https://docs.anthropic.com/claude/reference/rate-limits
+