Live provider integration tests and real HTTP client

.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\nfeat: implement API key redaction utility\n\nImplements redactApiKey\\(\\) and containsApiKey\\(\\) functions that detect\nand redact sensitive API key patterns \\(sk-, sk-proj-, anthropic-sk-ant-\\)\nfrom text to prevent credential leakage in error messages and logs.\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>\nEOF\n\\)\")"
+    ]
+  }
+}

CLAUDE.md

@@ -32,14 +32,16 @@ packages/
 
 ### Key Design Patterns
 
-1. **Vtable Pattern**: Interface abstraction for models instead of traits. Each model type (LanguageModelV3, EmbeddingModelV3, etc.) uses vtables for runtime polymorphism.
+1. **Vtable Pattern**: Interface abstraction for models instead of traits. Each model type (LanguageModelV3, EmbeddingModelV3, etc.) uses vtables for runtime polymorphism. See "Pointer Casting and Vtables" section below.
 
 2. **Callback-based Streaming**: Non-async approach using `StreamCallbacks` with `on_part`, `on_error`, and `on_complete` callbacks.
 
 3. **Arena Allocators**: Request-scoped memory management. Use `defer arena.deinit()` for cleanup.
 
 4. **Provider Pattern**: Each provider implements `init()`, `deinit()`, `getProvider()`, and model factory methods (e.g., `languageModel()`).
 
+5. **HttpClient Interface**: Type-erased HTTP client allowing mock injection for testing. Providers accept optional `http_client: ?provider_utils.HttpClient` in settings.
+
 ### Core Types
 
 - `packages/provider/src/`: `JsonValue` (custom JSON type), error hierarchy, model interfaces
@@ -70,4 +72,70 @@ defer arena.deinit();
 // Use arena.allocator() for request-scoped allocations
 ```
 
-Always document whether functions take ownership of allocations or expect the caller to manage memory.
+### Ownership Conventions
+
+- **Caller-owned**: Function returns data allocated by the passed allocator. Caller must free.
+- **Arena-owned**: Data lives until arena is deinitialized. No manual free needed.
+- **Static**: Compile-time data (string literals, const slices). Never free.
+
+### Header Functions
+
+Provider `getHeaders()` functions return `std.StringHashMap([]const u8)`. Caller owns the returned map and must call `deinit()`:
+
+```zig
+var headers = provider.getHeaders(allocator);
+defer headers.deinit();
+```
+
+## Pointer Casting and Vtables
+
+The SDK uses vtables for runtime polymorphism. This requires `@ptrCast` and `@alignCast` when converting between `*anyopaque` and concrete types.
+
+### Pattern
+
+```zig
+// Interface definition
+pub const HttpClient = struct {
+    vtable: *const VTable,
+    impl: *anyopaque,  // Type-erased implementation pointer
+
+    pub const VTable = struct {
+        request: *const fn (impl: *anyopaque, ...) void,
+    };
+
+    pub fn request(self: HttpClient, ...) void {
+        self.vtable.request(self.impl, ...);
+    }
+};
+
+// Implementation
+pub const MockHttpClient = struct {
+    // ... fields ...
+
+    pub fn asInterface(self: *MockHttpClient) HttpClient {
+        return .{
+            .vtable = &vtable,
+            .impl = self,  // Implicit cast to *anyopaque
+        };
+    }
+
+    const vtable = HttpClient.VTable{
+        .request = doRequest,
+    };
+
+    fn doRequest(impl: *anyopaque, ...) void {
+        // Cast back to concrete type - alignment is guaranteed since
+        // impl was originally a *MockHttpClient
+        const self: *MockHttpClient = @ptrCast(@alignCast(impl));
+        // ... implementation ...
+    }
+};
+```
+
+### Alignment Safety
+
+The `@alignCast` is safe when:
+1. The pointer was originally the concrete type before being cast to `*anyopaque`
+2. The vtable and impl are always paired correctly (same instance)
+
+All vtable implementations in this codebase follow this pattern, ensuring alignment is preserved through the type-erasure round-trip.

README.md

@@ -14,6 +14,8 @@ A comprehensive AI SDK for Zig, ported from the Vercel AI SDK. This SDK provides
 - **Transcription**: Speech-to-text capabilities
 - **Middleware**: Extensible request/response transformation
 - **Memory Safe**: Uses arena allocators for efficient memory management
+- **Testable**: MockHttpClient for unit testing without network calls
+- **Type-Erased HTTP**: Pluggable HTTP client interface via vtables
 
 ## Supported Providers
 
@@ -187,9 +189,34 @@ zig build run-example
 The SDK uses several key patterns:
 
 1. **Arena Allocators**: Request-scoped memory management
-2. **Vtable Pattern**: Interface abstraction for models
-3. **Callback-based Streaming**: Non-blocking I/O
+2. **Vtable Pattern**: Interface abstraction for models and HTTP clients
+3. **Callback-based Streaming**: Non-blocking I/O with SSE parsing
 4. **Provider Abstraction**: Unified interface across providers
+5. **Type-Erased HTTP**: Pluggable `HttpClient` interface for real and mock implementations
+
+### HTTP Client Interface
+
+The SDK uses a type-erased HTTP client interface that allows dependency injection:
+
+```zig
+const provider_utils = @import("provider-utils");
+
+// Use the standard HTTP client (default)
+var provider = openai.createOpenAI(allocator);
+
+// Or inject a mock client for testing
+var mock = provider_utils.MockHttpClient.init(allocator);
+defer mock.deinit();
+
+mock.setResponse(.{
+    .status_code = 200,
+    .body = "{\"choices\":[{\"message\":{\"content\":\"Hello!\"}}]}",
+});
+
+var provider = openai.createOpenAIWithSettings(allocator, .{
+    .http_client = mock.asInterface(),
+});
+```
 
 ## Memory Management
 
@@ -251,7 +278,56 @@ zig-ai-sdk/
 
 ## Requirements
 
-- Zig 0.13.0 or later
+- Zig 0.15.0 or later
+
+## Testing
+
+The SDK includes comprehensive unit tests for all providers:
+
+```bash
+# Run all tests
+zig build test
+```
+
+### MockHttpClient
+
+For unit testing provider implementations without network calls:
+
+```zig
+const allocator = std.testing.allocator;
+
+var mock = provider_utils.MockHttpClient.init(allocator);
+defer mock.deinit();
+
+// Configure expected response
+mock.setResponse(.{
+    .status_code = 200,
+    .body = "{\"id\":\"123\",\"choices\":[...]}",
+});
+
+// Pass to provider
+var provider = openai.createOpenAIWithSettings(allocator, .{
+    .http_client = mock.asInterface(),
+});
+
+// Make request...
+
+// Verify request was made correctly
+const req = mock.lastRequest().?;
+try std.testing.expectEqualStrings("POST", req.method.toString());
+```
+
+## Recent Changes
+
+### v0.2.0 (Current Fork)
+
+- **HTTP Client Interface**: Standardized `HttpClient` type across all providers with vtable-based polymorphism
+- **MockHttpClient**: Added mock HTTP client for testing without network calls
+- **Memory Safety**: Improved allocator passing to `getHeaders()` functions
+- **Google/Vertex HTTP**: Implemented full HTTP layer for Google and Vertex providers (language, embedding, image models)
+- **Response Types**: Added proper response parsing types for Google and Vertex APIs
+- **Anthropic API**: Updated to API version `2024-06-01`
+- **Compliance Tests**: Added comprehensive tests for OpenAI, Anthropic, Azure, Google, and Vertex providers
 
 ## Contributing
 

build.zig

@@ -65,6 +65,7 @@ pub fn build(b: *std.Build) void {
     });
     google_vertex_mod.addImport("provider", provider_mod);
     google_vertex_mod.addImport("provider-utils", provider_utils_mod);
+    google_vertex_mod.addImport("google", google_mod);
 
     // Azure provider
     const azure_mod = b.addModule("azure", .{
@@ -329,8 +330,44 @@ pub fn build(b: *std.Build) void {
         .{ .path = "packages/groq/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod }, .{ .name = "openai-compatible", .mod = openai_compatible_mod } } },
         .{ .path = "packages/elevenlabs/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
         .{ .path = "packages/deepgram/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/hume/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
         .{ .path = "packages/replicate/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/fal/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/luma/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/lmnt/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/assemblyai/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/gladia/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/revai/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
+        .{ .path = "packages/black-forest-labs/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod } } },
         .{ .path = "packages/azure/src/index.zig", .imports = &.{ .{ .name = "provider", .mod = provider_mod }, .{ .name = "provider-utils", .mod = provider_utils_mod }, .{ .name = "openai", .mod = openai_mod } } },
+        // Integration tests
+        .{ .path = "tests/integration/provider_test.zig", .imports = &.{
+            .{ .name = "provider", .mod = provider_mod },
+            .{ .name = "provider-utils", .mod = provider_utils_mod },
+            .{ .name = "ai", .mod = ai_mod },
+            .{ .name = "openai", .mod = openai_mod },
+            .{ .name = "anthropic", .mod = anthropic_mod },
+            .{ .name = "google", .mod = google_mod },
+            .{ .name = "azure", .mod = azure_mod },
+            .{ .name = "mistral", .mod = mistral_mod },
+            .{ .name = "cohere", .mod = cohere_mod },
+            .{ .name = "groq", .mod = groq_mod },
+            .{ .name = "xai", .mod = xai_mod },
+            .{ .name = "perplexity", .mod = perplexity_mod },
+            .{ .name = "togetherai", .mod = togetherai_mod },
+            .{ .name = "fireworks", .mod = fireworks_mod },
+            .{ .name = "cerebras", .mod = cerebras_mod },
+            .{ .name = "huggingface", .mod = huggingface_mod },
+            .{ .name = "replicate", .mod = replicate_mod },
+            .{ .name = "elevenlabs", .mod = elevenlabs_mod },
+            .{ .name = "deepgram", .mod = deepgram_mod },
+        } },
+        .{ .path = "tests/integration/similarity_test.zig", .imports = &.{
+            .{ .name = "ai", .mod = ai_mod },
+        } },
+        .{ .path = "tests/integration/tool_test.zig", .imports = &.{
+            .{ .name = "ai", .mod = ai_mod },
+        } },
     };
 
     for (test_configs) |config| {
@@ -348,6 +385,25 @@ pub fn build(b: *std.Build) void {
         test_step.dependOn(&b.addRunArtifact(tests).step);
     }
 
+    // Live provider integration tests (requires API keys)
+    const test_live_step = b.step("test-live", "Run live provider integration tests (requires API keys)");
+    const live_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("tests/integration/live_provider_test.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+        .test_runner = .{ .path = b.path("test_runner.zig"), .mode = .simple },
+    });
+    live_tests.root_module.addImport("ai", ai_mod);
+    live_tests.root_module.addImport("provider", provider_mod);
+    live_tests.root_module.addImport("provider-utils", provider_utils_mod);
+    live_tests.root_module.addImport("openai", openai_mod);
+    live_tests.root_module.addImport("azure", azure_mod);
+    live_tests.root_module.addImport("xai", xai_mod);
+    // TODO: Add anthropic, google, google-vertex once their vtable serialization bugs are fixed
+    test_live_step.dependOn(&b.addRunArtifact(live_tests).step);
+
     // Example executable
     const example = b.addExecutable(.{
         .name = "ai-example",

examples/lifetime_example.zig

@@ -0,0 +1,67 @@
+const std = @import("std");
+
+// This example demonstrates correct lifetime management for vtable-based
+// interfaces (LanguageModelV3, EmbeddingModelV3, HttpClient, etc.).
+
+// ============================================================
+// CORRECT: The model outlives the interface
+// ============================================================
+//
+//   var provider = createAnthropic(allocator);
+//   defer provider.deinit();
+//
+//   var model = provider.messages("claude-sonnet-4-5");
+//   // model.asLanguageModel() borrows a pointer to model's vtable + impl.
+//   // The returned LanguageModelV3 is valid as long as `model` is alive.
+//   const iface = model.asLanguageModel();
+//   _ = iface;  // safe to use here
+//
+// ============================================================
+// INCORRECT: Dangling pointer - model goes out of scope
+// ============================================================
+//
+//   fn getModel(provider: *AnthropicProvider) LanguageModelV3 {
+//       var model = provider.messages("claude-sonnet-4-5");
+//       return model.asLanguageModel();
+//       // BUG: `model` is stack-allocated and destroyed when this
+//       // function returns. The returned LanguageModelV3.impl now
+//       // points to freed stack memory.
+//   }
+//
+// ============================================================
+// CORRECT: Keep the concrete model alive alongside the interface
+// ============================================================
+//
+//   const ModelHandle = struct {
+//       model: AnthropicMessagesLanguageModel,
+//
+//       pub fn asLanguageModel(self: *ModelHandle) LanguageModelV3 {
+//           return self.model.asLanguageModel();
+//       }
+//   };
+//
+//   var handle = ModelHandle{ .model = provider.messages("claude-sonnet-4-5") };
+//   const iface = handle.asLanguageModel();
+//   // iface is valid as long as handle is alive
+//   _ = iface;
+//
+// ============================================================
+// Key Rules
+// ============================================================
+//
+// 1. The concrete implementation (model, http client, etc.) MUST outlive
+//    the type-erased interface (LanguageModelV3, HttpClient, etc.).
+//
+// 2. The vtable pointer should reference a file-level `const` with static
+//    lifetime. All implementations in this SDK follow this pattern.
+//
+// 3. Never return a type-erased interface from a function where the
+//    concrete implementation is a local variable.
+//
+// 4. When storing interfaces in structs, also store (or reference) the
+//    concrete implementation to keep it alive.
+
+pub fn main() void {
+    // This file is documentation only. See the comments above for
+    // lifetime management patterns.
+}