HTTP Provider

@namzu/http is the generic provider package in the Namzu lineup. It is designed for endpoints that already speak an OpenAI-compatible or Anthropic-compatible wire format but do not need a dedicated vendor package in your dependency graph.

1. When to Use It

Choose this package when the backend is compatible but not best represented by a first-party Namzu package, or when you want the smallest possible provider dependency surface.

2. When Not to Use It

Choose another provider when:

• you want vendor-native SDK behavior and better vendor-specific ergonomics
• you need AWS-native Bedrock auth or region support
• you already know you want the dedicated Ollama or LM Studio integrations

3. Install

pnpm add @namzu/sdk @namzu/http

4. Register and Create the Provider

import { ProviderRegistry } from '@namzu/sdk'
import { registerHttp } from '@namzu/http'
 
registerHttp()
 
const { provider } = ProviderRegistry.create({
  type: 'http',
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  dialect: 'openai',
})

5. Typical Endpoint Patterns

Use the same provider shape for several classes of endpoint:

5.1 OpenAI-compatible cloud endpoint

const { provider } = ProviderRegistry.create({
  type: 'http',
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  dialect: 'openai',
  model: 'gpt-4o-mini',
})

5.2 Anthropic native Messages API

const { provider } = ProviderRegistry.create({
  type: 'http',
  baseURL: 'https://api.anthropic.com/v1',
  apiKey: process.env.ANTHROPIC_API_KEY!,
  dialect: 'anthropic',
})

5.3 Local or self-hosted compatible endpoint

const { provider } = ProviderRegistry.create({
  type: 'http',
  baseURL: 'http://localhost:11434/v1',
  dialect: 'openai',
  model: 'llama3.2',
})

6. Configuration

7. Capability Snapshot

The package exports HTTP_CAPABILITIES:

{
  supportsTools: true,
  supportsStreaming: true,
  supportsFunctionCalling: true,
}

The actual endpoint still has to support those features correctly.

8. Operational Notes

• The package exports DialectMismatchError, which is thrown when the declared dialect does not match the actual response shape.
• Use dialect: 'anthropic' only for native Anthropic-style endpoints.
• This package is a good fit for self-hosted gateways, vLLM, TGI, Groq-style OpenAI-compatible APIs, and similar targets.
• The provider also implements listModels() and healthCheck().

9. Why Dialect Choice Matters

The package does not silently auto-detect wire shape. That is deliberate:

• OpenAI-compatible and Anthropic-compatible responses are not interchangeable
• silent coercion can corrupt tool-call arguments or stream parsing
• fail-fast configuration errors are easier to debug than partial runtime corruption

10. Common Errors

Related

• Providers Overview
• Provider Selection Guide
• OpenAI Provider
• Anthropic Provider
• Provider Registry
• HTTP Provider Entry
• HTTP Config Types