@wrongstack/providers 0.1.3 → 0.1.7

package/LICENSE

@@ -1,17 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   Copyright 2026 ECOSTACK TECHNOLOGY OÜ
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-       http://www.apache.org/licenses/LICENSE-2.0
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @wrongstack/providers
+
+LLM provider adapters for WrongStack: Anthropic, OpenAI, Google, OpenAI-compatible (Mistral, Groq, DeepSeek, Together, Fireworks, OpenRouter, …).
+
+Most providers ride a single declarative `WireFormatConfig` adapter; only the three majors (Anthropic / OpenAI / Google) have hand-written classes. Adding a new provider is usually a 20-line preset, not a new file.
+
+## Install
+
+```bash
+pnpm add @wrongstack/providers @wrongstack/core
+```
+
+`@wrongstack/core` is a peer of every provider — providers depend on the core `Provider` interface, message types, and tool format.
+
+## What's in here
+
+```
+src/
+  anthropic.ts             native Anthropic Messages API
+  openai.ts                native OpenAI Chat Completions API
+  google.ts                native Google Gemini generateContent API
+  openai-compatible.ts     drop-in for any /v1/chat/completions endpoint
+  wire-adapter.ts          declarative adapter — pass a WireFormatConfig
+  presets/                 wire configs for anthropic / openai / google / mistral
+  sse.ts                   SSE parser with 256 KB buffer cap
+  aggregate.ts             tool_use stream-event aggregator
+  tool-format/             tools ↔ Anthropic / OpenAI converters
+  stop-reason.ts           normalize provider stop_reason → canonical
+  error-parse.ts           parse provider HTTP error envelopes
+  capabilities.ts          map models.dev capability strings → bool flags
+```
+
+## Quick example
+
+```ts
+import { AnthropicProvider } from '@wrongstack/providers';
+
+const provider = new AnthropicProvider({
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  modelId: 'claude-sonnet-4-6',
+});
+
+const stream = provider.stream({
+  messages: [{ role: 'user', content: 'hello' }],
+  tools: [],
+});
+
+for await (const event of stream) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+}
+```
+
+## Using a preset (OpenAI-compatible service)
+
+```ts
+import { OpenAICompatibleProvider } from '@wrongstack/providers';
+
+const groq = new OpenAICompatibleProvider({
+  id: 'groq',
+  apiKey: process.env.GROQ_API_KEY!,
+  baseURL: 'https://api.groq.com/openai/v1',
+  modelId: 'llama-3.3-70b-versatile',
+  capabilities: { tools: true, vision: false, maxContext: 128_000 },
+});
+```
+
+## Wire-format adapter (declarative)
+
+For a new provider that doesn't fit one of the existing presets, write a `WireFormatConfig` and plug it into `WireAdapter`. See [docs/provider-author-guide.md](../../docs/provider-author-guide.md) for the full spec.
+
+```ts
+import { WireAdapter } from '@wrongstack/providers';
+import type { WireFormatConfig } from '@wrongstack/core';
+
+const myWire: WireFormatConfig = {
+  family: 'openai',
+  endpoint: 'https://api.myprovider.com/v1/chat/completions',
+  authHeader: (key) => ({ 'Authorization': `Bearer ${key}` }),
+  // tool format, message shape, stream parsing — see WireFormatConfig type
+};
+
+const provider = new WireAdapter({
+  id: 'myprovider',
+  apiKey: '…',
+  modelId: 'my-model-1',
+  wire: myWire,
+  capabilities: { tools: true, maxContext: 32_000 },
+});
+```
+
+## Tool input parsing (`parseToolInput`)
+
+All four stream parsers (anthropic / openai / aggregate + the three OpenAI-compatible presets) run tool-call JSON through one canonical helper: [`_tool-input.ts`](src/_tool-input.ts). It guarantees the agent always receives a `Record<string, unknown>` for `tool_use.input`, never a parse-error or `null`. Invalid or non-object inputs are wrapped under `{ __raw: ... }` instead of crashing the provider runner.
+
+## Capabilities
+
+The capability flags on each provider come from [models.dev](https://models.dev) catalog data, mapped by `capabilitiesFor()`. The agent uses them to pick adaptive context-management thresholds, gate vision/reasoning features, and refuse tools on models that don't support tool calls.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -360,6 +360,9 @@ declare const googleWireFormat: WireFormatConfig<GoogleStreamState>;
  */
 declare function capabilitiesFor(registry: ModelsRegistry, providerId: string, modelId: string): Promise<Capabilities>;
 
+declare const CAPABILITIES_BY_FAMILY: Record<WireFamily, Capabilities>;
+declare function capabilitiesForFamily(family: WireFamily, overrides?: Partial<Capabilities>): Capabilities;
+
 /**
  * Provider HTTP error bodies come in three or four shapes depending on
  * vendor. Rather than dump the raw JSON into the error message (which is
@@ -459,4 +462,4 @@ declare function buildProviderFactoriesFromRegistry(opts: BuildFactoriesOptions)
  */
 declare function makeProviderFromConfig(id: string, cfg: ProviderConfig): Provider;
 
-export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };
+export { AnthropicProvider, type AnthropicProviderOptions, type BuildFactoriesOptions, CAPABILITIES_BY_FAMILY, type CompatibilityQuirks, type ConvertOptions, GoogleProvider, type GoogleProviderOptions, type OpenAIChoice, type OpenAICompatibleOptions, OpenAICompatibleProvider, type OpenAIMessage, OpenAIProvider, type OpenAIProviderOptions, type OpenAIToolCall, WireAdapter, type WireFactoryOptions, type WireFormatConfig, WireFormatProvider, anthropicWireFormat, buildProviderFactoriesFromRegistry, capabilitiesFor, capabilitiesForFamily, contentFromAnthropic, contentFromOpenAI, createWireFormatFactory, defineWireFormat, googleWireFormat, makeProviderFromConfig, messagesToOpenAI, mistralWireFormat, normalizeAnthropic, normalizeOpenAI, openaiWireFormat, parseProviderHttpError, toolsToAnthropic, toolsToOpenAI };