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

package/src/lib/registry.js

@@ -1,8 +1,10 @@
-import { loadSourceRegistry } from './cache.js';
+import { loadSourceRegistry, loadSearchIndex } from './cache.js';
 import { loadConfig } from './config.js';
 import { normalizeLanguage } from './normalize.js';
+import { search as bm25Search } from './bm25.js';
 
 let _merged = null;
+let _searchIndex = null;
 
 /**
  * Load and merge entries from all configured sources.
@@ -14,11 +16,16 @@ function getMerged() {
   const config = loadConfig();
   const allDocs = [];
   const allSkills = [];
+  const searchIndexes = [];
 
   for (const source of config.sources) {
     const registry = loadSourceRegistry(source);
     if (!registry) continue;
 
+    // Load BM25 search index if available
+    const idx = loadSearchIndex(source);
+    if (idx) searchIndexes.push(idx);
+
     // Support both new format (docs/skills) and old format (entries)
     if (registry.docs) {
       for (const doc of registry.docs) {
@@ -46,6 +53,53 @@ function getMerged() {
     }
   }
 
+  // Merge search indexes (combine documents and recompute IDF)
+  if (searchIndexes.length > 0) {
+    if (searchIndexes.length === 1) {
+      _searchIndex = searchIndexes[0];
+    } else {
+      // Merge multiple indexes: combine documents, recompute global IDF
+      const allDocuments = searchIndexes.flatMap((idx) => idx.documents);
+      const N = allDocuments.length;
+      const dfMap = {};
+      const fieldLengths = { name: [], description: [], tags: [] };
+
+      for (const doc of allDocuments) {
+        const allTerms = new Set([
+          ...(doc.tokens.name || []),
+          ...(doc.tokens.description || []),
+          ...(doc.tokens.tags || []),
+        ]);
+        for (const term of allTerms) {
+          dfMap[term] = (dfMap[term] || 0) + 1;
+        }
+        fieldLengths.name.push((doc.tokens.name || []).length);
+        fieldLengths.description.push((doc.tokens.description || []).length);
+        fieldLengths.tags.push((doc.tokens.tags || []).length);
+      }
+
+      const idf = {};
+      for (const [term, df] of Object.entries(dfMap)) {
+        idf[term] = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+      }
+
+      const avg = (arr) => arr.length === 0 ? 0 : arr.reduce((a, b) => a + b, 0) / arr.length;
+      _searchIndex = {
+        version: '1.0.0',
+        algorithm: 'bm25',
+        params: searchIndexes[0].params,
+        totalDocs: N,
+        avgFieldLengths: {
+          name: avg(fieldLengths.name),
+          description: avg(fieldLengths.description),
+          tags: avg(fieldLengths.tags),
+        },
+        idf,
+        documents: allDocuments,
+      };
+    }
+  }
+
   _merged = { docs: allDocs, skills: allSkills };
   return _merged;
 }
@@ -121,11 +175,10 @@ export function getDisplayId(entry) {
 
 /**
  * Search entries by query string. Searches both docs and skills.
+ * Uses BM25 when a search index is available, falls back to keyword matching.
  */
 export function searchEntries(query, filters = {}) {
   const entries = applySourceFilter(getAllEntries());
-  const q = query.toLowerCase();
-  const words = q.split(/\s+/);
 
   // Deduplicate: same id+source appearing as both doc and skill → show once
   const seen = new Set();
@@ -138,27 +191,50 @@ export function searchEntries(query, filters = {}) {
     }
   }
 
-  let results = deduped.map((entry) => {
-    let score = 0;
+  // Build entry lookup by id
+  const entryById = new Map();
+  for (const entry of deduped) {
+    entryById.set(entry.id, entry);
+  }
+
+  let results;
+
+  if (_searchIndex) {
+    // BM25 search
+    const bm25Results = bm25Search(query, _searchIndex);
+    results = bm25Results
+      .map((r) => {
+        const entry = entryById.get(r.id);
+        return entry ? { entry, score: r.score } : null;
+      })
+      .filter(Boolean);
+  } else {
+    // Fallback: keyword matching
+    const q = query.toLowerCase();
+    const words = q.split(/\s+/);
 
-    if (entry.id === q) score += 100;
-    else if (entry.id.includes(q)) score += 50;
+    results = deduped.map((entry) => {
+      let score = 0;
 
-    const nameLower = entry.name.toLowerCase();
-    if (nameLower === q) score += 80;
-    else if (nameLower.includes(q)) score += 40;
+      if (entry.id === q) score += 100;
+      else if (entry.id.includes(q)) score += 50;
 
-    for (const word of words) {
-      if (entry.id.includes(word)) score += 10;
-      if (nameLower.includes(word)) score += 10;
-      if (entry.description?.toLowerCase().includes(word)) score += 5;
-      if (entry.tags?.some((t) => t.toLowerCase().includes(word))) score += 15;
-    }
+      const nameLower = entry.name.toLowerCase();
+      if (nameLower === q) score += 80;
+      else if (nameLower.includes(q)) score += 40;
 
-    return { entry, score };
-  });
+      for (const word of words) {
+        if (entry.id.includes(word)) score += 10;
+        if (nameLower.includes(word)) score += 10;
+        if (entry.description?.toLowerCase().includes(word)) score += 5;
+        if (entry.tags?.some((t) => t.toLowerCase().includes(word))) score += 15;
+      }
+
+      return { entry, score };
+    });
 
-  results = results.filter((r) => r.score > 0);
+    results = results.filter((r) => r.score > 0);
+  }
 
   const filtered = applyFilters(results.map((r) => r.entry), filters);
   const filteredSet = new Set(filtered);
@@ -255,6 +331,13 @@ export function resolveDocPath(entry, language, version) {
   let verObj = null;
   if (version) {
     verObj = langObj.versions?.find((v) => v.version === version);
+    if (!verObj) {
+      return {
+        versionNotFound: true,
+        requested: version,
+        available: langObj.versions?.map((v) => v.version) || [],
+      };
+    }
   } else {
     const rec = langObj.recommendedVersion;
     verObj = langObj.versions?.find((v) => v.version === rec) || langObj.versions?.[0];
@@ -272,7 +355,7 @@ export function resolveDocPath(entry, language, version) {
  * Given a resolved path and a type ("doc" or "skill"), return the entry file path.
  */
 export function resolveEntryFile(resolved, type) {
-  if (!resolved || resolved.needsLanguage) return { error: 'unresolved' };
+  if (!resolved || resolved.needsLanguage || resolved.versionNotFound) return { error: 'unresolved' };
 
   const fileName = type === 'skill' ? 'SKILL.md' : 'DOC.md';
 

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

@@ -1,499 +0,0 @@
----
-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
-