feat: align SDK types with Venice API swagger spec v20260314

Comprehensive audit and update of all type definitions against the
official Venice API swagger spec. Adds missing parameters, fixes
incorrect response types, and adds test/example coverage for
previously undocumented features.

Types:
- chat: add enable_e2ee, enable_x_search, stop_token_ids, user, store,
  text, include; response logprobs, stop_reason, prompt_tokens_details,
  reasoning_content, tool_calls, venice_parameters echo with citations
- multimodal: add InputAudioContent, VideoUrlContent, CacheControl
- models: expand Model.type to 9 values, add ModelCapabilities (13 fields),
  ModelPricing variants, ~40 new ModelSpec fields
- audio: add 9 Qwen 3 voices, fix transcription response (timestamps)
- images: fix ListImageStylesResponse to match swagger (string[])
- characters: add id, author, featured, photoUrl, modelId, expanded stats,
  review types
- responses: add XSearch, CodeInterpreter, FileSearch, ComputerUse tools
- embeddings: make model required
- video: clarify image_url required for i2v models

Endpoints:
- characters: add getReviews() method

Tests:
- chat: 6 new parameter pass-through tests
- responses: new test file (16 tests)
- keys: new test file (36 tests)

Examples:
- 15: add web scraping example
- 20: function calling
- 21: structured output (json_schema)
- 22: reasoning config
- 23: video generation workflow
- 24: audio transcription

Docs:
- README: add examples 16-24, fix model names, standardize on VeniceAI

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: georgeglarson

examples/README.md

@@ -111,7 +111,30 @@ Production-ready patterns for experienced developers.
 | [12-streaming-with-abort.ts](typescript/12-streaming-with-abort.ts) | Cancellable streaming requests | AbortController, cleanup, timeouts |
 | [13-api-keys-management.ts](typescript/13-api-keys-management.ts) | Programmatic API key CRUD | Key management, metadata |
 | [14-rate-limit-handling.ts](typescript/14-rate-limit-handling.ts) | Rate limit strategies | Queuing, backoff, batch processing |
-| [15-custom-parameters.ts](typescript/15-custom-parameters.ts) | Venice-specific features | Web search, characters, parameters |
+| [15-custom-parameters.ts](typescript/15-custom-parameters.ts) | Venice-specific features | Web search, web scraping, characters, parameters |
+
+### Professional Patterns
+
+Production-ready patterns and SDK internals.
+
+| Example | Description | Key Concepts |
+|---------|-------------|--------------|
+| [16-middleware-system.ts](typescript/16-middleware-system.ts) | Request/response middleware | Middleware pipeline, logging, timing |
+| [17-streaming-utilities.ts](typescript/17-streaming-utilities.ts) | Stream transformation utilities | Stream filtering, buffering, transforms |
+| [18-error-recovery.ts](typescript/18-error-recovery.ts) | Structured error recovery | Recovery hints, graceful degradation |
+| [19-model-discovery.ts](typescript/19-model-discovery.ts) | Finding models by capability | Model traits, filtering, compatibility |
+
+### API Features
+
+Examples demonstrating specific API capabilities.
+
+| Example | Description | Key Concepts |
+|---------|-------------|--------------|
+| [20-function-calling.ts](typescript/20-function-calling.ts) | Tool/function calling | Tools, tool_choice, tool_calls, multi-turn |
+| [21-structured-output.ts](typescript/21-structured-output.ts) | Structured JSON responses | JSON schema, response_format, extraction |
+| [22-reasoning-config.ts](typescript/22-reasoning-config.ts) | Reasoning/thinking models | Reasoning effort, summary, thinking content |
+| [23-video-generation.ts](typescript/23-video-generation.ts) | Video generation workflow | Queue, retrieve, complete, polling |
+| [24-audio-transcription.ts](typescript/24-audio-transcription.ts) | Speech-to-text transcription | Audio transcription, timestamps, segments |
 
 ### Language-Specific Examples
 
@@ -169,9 +192,9 @@ VENICE_LOG_LEVEL=1
 ### Text Generation
 
 ```typescript
-import { VeniceClient } from '@venice-dev-tools/core';
+import { VeniceAI } from '@venice-dev-tools/core';
 
-const client = new VeniceClient({ apiKey: process.env.VENICE_API_KEY });
+const client = new VeniceAI({ apiKey: process.env.VENICE_API_KEY! });
 
 const response = await client.chat.completions.create({
   model: 'llama-3.3-70b',
@@ -235,7 +258,7 @@ See: [11-vision-multimodal.ts](typescript/11-vision-multimodal.ts)
 
 ```typescript
 const response = await client.embeddings.create({
-  model: 'text-embedding-004',
+  model: 'text-embedding-bge-m3',
   input: 'The quick brown fox jumps over the lazy dog',
 });
 
@@ -249,9 +272,9 @@ See: [07-embeddings.ts](typescript/07-embeddings.ts)
 
 ```typescript
 const audio = await client.audio.speech.create({
-  model: 'musicgen-stereo-small',
+  model: 'tts-kokoro',
   input: 'Hello, this is a test of the Venice AI text to speech system.',
-  voice: 'alloy',
+  voice: 'af_sky',
 });
 
 await fs.promises.writeFile('output.mp3', Buffer.from(await audio.arrayBuffer()));
@@ -294,7 +317,7 @@ See: [03-error-handling.ts](typescript/03-error-handling.ts)
 ## Configuration Options
 
 ```typescript
-const client = new VeniceClient({
+const client = new VeniceAI({
   apiKey: process.env.VENICE_API_KEY,
 
   // Timeout settings
@@ -372,7 +395,7 @@ bun run examples/typescript/01-hello-world.ts
 
 **Solution:**
 ```typescript
-const client = new VeniceClient({
+const client = new VeniceAI({
   apiKey: process.env.VENICE_API_KEY,
   timeout: 120000, // Increase to 120 seconds
 });
@@ -410,12 +433,12 @@ pnpm install
 
 ```typescript
 // ✅ Good
-const client = new VeniceClient({ 
+const client = new VeniceAI({ 
   apiKey: process.env.VENICE_API_KEY 
 });
 
 // ❌ Bad - never hardcode keys
-const client = new VeniceClient({ 
+const client = new VeniceAI({ 
   apiKey: 'sk-1234567890' 
 });
 ```
@@ -481,7 +504,7 @@ const stream = await client.chat.completions.create({
 
 ```typescript
 // ✅ Good - robust retry configuration
-const client = new VeniceClient({
+const client = new VeniceAI({
   apiKey: process.env.VENICE_API_KEY,
   retry: {
     maxRetries: 3,
@@ -493,7 +516,7 @@ const client = new VeniceClient({
 });
 
 // ❌ Bad - default retry may not suit production needs
-const client = new VeniceClient({
+const client = new VeniceAI({
   apiKey: process.env.VENICE_API_KEY,
 });
 ```

examples/typescript/15-custom-parameters.ts

@@ -6,6 +6,7 @@
  * 
  * Features:
  * - Web search integration
+ * - Web scraping (Firecrawl) for URL content extraction
  * - Character personas
  * - Custom system prompts
  * - Temperature and creativity controls
@@ -69,8 +70,35 @@ async function main() {
     console.error('❌ Error:', error.message);
   }
 
-  // Example 2: Character Personas
-  console.log('\n👤 Example 2: Character Personas');
+  // Example 2: Web Scraping (Firecrawl)
+  console.log('\n🔍 Example 2: Web Scraping (URL Content Extraction)');
+  console.log('═'.repeat(50));
+
+  try {
+    const rawScrapingResponse = await venice.chat.completions.create({
+      model: 'llama-3.3-70b',
+      messages: [
+        {
+          role: 'user',
+          content: 'Summarize the content at https://venice.ai/blog'
+        }
+      ],
+      venice_parameters: {
+        enable_web_scraping: true,  // Scrapes URLs in the user message via Firecrawl
+      } as any
+    });
+    const scrapingResponse = ensureChatCompletionResponse(rawScrapingResponse, 'Web scraping example');
+
+    console.log('✅ Response with web scraping:');
+    console.log(toText(scrapingResponse.choices[0].message.content));
+    console.log('');
+
+  } catch (error: any) {
+    console.error('❌ Error:', error.message);
+  }
+
+  // Example 3: Character Personas
+  console.log('\n👤 Example 3: Character Personas');
   console.log('═'.repeat(50));
 
   try {
@@ -109,8 +137,8 @@ async function main() {
     console.error('❌ Error:', error.message);
   }
 
-  // Example 3: Creativity Controls
-  console.log('\n🎨 Example 3: Creativity Controls');
+  // Example 4: Creativity Controls
+  console.log('\n🎨 Example 4: Creativity Controls');
   console.log('═'.repeat(50));
 
   const prompt = 'Write a creative tagline for a coffee shop';
@@ -143,8 +171,8 @@ async function main() {
   console.log(toText(creativeResponse.choices[0].message.content));
   console.log('');
 
-  // Example 4: Response Format Control
-  console.log('\n📋 Example 4: Response Format Control');
+  // Example 5: Response Format Control
+  console.log('\n📋 Example 5: Response Format Control');
   console.log('═'.repeat(50));
 
   const rawFormatResponse = await venice.chat.completions.create({
@@ -175,6 +203,8 @@ async function main() {
   console.log('');
   console.log('   Venice-specific:');
   console.log('   • enable_web_search: real-time web results');
+  console.log('   • enable_web_scraping: extract content from URLs via Firecrawl');
+  console.log('   • enable_web_citations: annotate responses with sources');
   console.log('   • character_slug: use character personas');
   console.log('   • include_venice_system_prompt: use Venice defaults');
 }

examples/typescript/20-function-calling.ts

@@ -0,0 +1,173 @@
+/**
+ * Function Calling - Tool use with chat completions
+ *
+ * This example demonstrates how to use function/tool calling
+ * with Venice AI's chat completions API.
+ *
+ * Features:
+ * - Defining function tools with JSON Schema
+ * - Automatic tool choice by the model
+ * - Parsing tool_calls from assistant responses
+ * - Sending tool results back with role: 'tool'
+ * - Multi-turn conversation with tool use
+ *
+ * Prerequisites:
+ * - VENICE_API_KEY environment variable set
+ *
+ * Run with: npx tsx examples/typescript/20-function-calling.ts
+ */
+
+import { VeniceAI } from '@venice-dev-tools/core';
+import { ensureChatCompletionResponse } from './utils';
+import { requireEnv } from './env-config';
+
+// Simulated weather database
+function getWeather(location: string, unit: string = 'fahrenheit'): string {
+  const weatherData: Record<string, { temp_f: number; temp_c: number; condition: string }> = {
+    'san francisco': { temp_f: 62, temp_c: 17, condition: 'foggy' },
+    'new york': { temp_f: 78, temp_c: 26, condition: 'sunny' },
+    'london': { temp_f: 59, temp_c: 15, condition: 'rainy' },
+    'tokyo': { temp_f: 85, temp_c: 29, condition: 'humid' },
+  };
+
+  const key = location.toLowerCase();
+  const data = weatherData[key];
+  if (!data) {
+    return JSON.stringify({ error: `No weather data available for "${location}"` });
+  }
+
+  const temp = unit === 'celsius' ? data.temp_c : data.temp_f;
+  const unitLabel = unit === 'celsius' ? 'C' : 'F';
+  return JSON.stringify({
+    location,
+    temperature: temp,
+    unit: unitLabel,
+    condition: data.condition,
+  });
+}
+
+// Define the tool for the model
+const weatherTool = {
+  type: 'function' as const,
+  function: {
+    name: 'get_weather',
+    description: 'Get the current weather for a given location',
+    parameters: {
+      type: 'object',
+      properties: {
+        location: {
+          type: 'string',
+          description: 'The city name, e.g. "San Francisco"',
+        },
+        unit: {
+          type: 'string',
+          enum: ['celsius', 'fahrenheit'],
+          description: 'Temperature unit (default: fahrenheit)',
+        },
+      },
+      required: ['location'],
+    },
+  },
+};
+
+async function main() {
+  const apiKey = requireEnv('VENICE_API_KEY');
+  const venice = new VeniceAI({ apiKey });
+
+  console.log('🔧 Function Calling Demo\n');
+
+  // Step 1: Send a message that should trigger tool use
+  console.log('📤 Step 1: Sending user message with tools defined');
+  console.log('═'.repeat(50));
+
+  const messages: any[] = [
+    {
+      role: 'user',
+      content: 'What is the weather like in San Francisco and Tokyo?',
+    },
+  ];
+
+  try {
+    const rawResponse = await venice.chat.completions.create({
+      model: 'llama-3.3-70b',
+      messages,
+      tools: [weatherTool],
+      tool_choice: 'auto',
+    });
+    const response = ensureChatCompletionResponse(rawResponse, 'Function calling step 1');
+
+    const assistantMessage = response.choices[0].message;
+    console.log('✅ Model response received');
+
+    // Check if the model wants to call tools
+    if (assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+      console.log(`🔧 Model requested ${assistantMessage.tool_calls.length} tool call(s):\n`);
+
+      // Add the assistant message (with tool_calls) to conversation
+      messages.push(assistantMessage);
+
+      // Step 2: Execute each tool call and send results back
+      console.log('📤 Step 2: Executing tool calls and sending results');
+      console.log('═'.repeat(50));
+
+      for (const toolCall of assistantMessage.tool_calls) {
+        const functionName = toolCall.function.name;
+        const args = JSON.parse(toolCall.function.arguments);
+
+        console.log(`  📌 Calling: ${functionName}(${JSON.stringify(args)})`);
+
+        let result: string;
+        if (functionName === 'get_weather') {
+          result = getWeather(args.location, args.unit);
+        } else {
+          result = JSON.stringify({ error: `Unknown function: ${functionName}` });
+        }
+
+        console.log(`  📋 Result: ${result}\n`);
+
+        // Add the tool result to the conversation
+        messages.push({
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          content: result,
+        });
+      }
+
+      // Step 3: Get the final response with tool results
+      console.log('📤 Step 3: Getting final response with tool results');
+      console.log('═'.repeat(50));
+
+      const rawFinalResponse = await venice.chat.completions.create({
+        model: 'llama-3.3-70b',
+        messages,
+        tools: [weatherTool],
+      });
+      const finalResponse = ensureChatCompletionResponse(rawFinalResponse, 'Function calling step 3');
+
+      const finalContent = finalResponse.choices[0].message.content;
+      console.log('✅ Final response:');
+      console.log(typeof finalContent === 'string' ? finalContent : JSON.stringify(finalContent));
+    } else {
+      // Model responded directly without tool calls
+      console.log('ℹ️  Model responded without using tools:');
+      const content = assistantMessage.content;
+      console.log(typeof content === 'string' ? content : JSON.stringify(content));
+    }
+
+  } catch (error: any) {
+    console.error('❌ Error:', error.message);
+  }
+
+  // Summary
+  console.log('\n💡 Function Calling Tips:');
+  console.log('   • Define tools with clear descriptions and JSON Schema parameters');
+  console.log('   • Use tool_choice: "auto" to let the model decide when to call tools');
+  console.log('   • Use tool_choice: "required" to force tool use');
+  console.log('   • Always include tool_call_id when sending tool results back');
+  console.log('   • The model can request multiple tool calls in a single response');
+}
+
+main().catch((error) => {
+  console.error('❌ Fatal error:', error.message);
+  process.exit(1);
+});