vern-llm 0.2.1 → 0.4.0

package/README.md

@@ -1,6 +1,28 @@
-# vern-llm
+<p align="center">
+  <img src="https://raw.githubusercontent.com/LakBud/vernLLM/main/apps/docs/public/logo.png" alt="vern-llm logo" width="96" />
+</p>
 
-Retry + timeout + cache wrapper for OpenAI-compatible chat completion calls (OpenAI, Groq, Anthropic via adapter).
+<h1 align="center">vern-llm</h1>
+
+<p align="center">
+  <a href="https://github.com/LakBud/vernLLM">GitHub</a> ·
+  <a href="https://vernllm.vercel.app">Documentation</a> ·
+  <a href="https://www.npmjs.com/package/vern-llm">npm</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vern-llm"><img src="https://img.shields.io/npm/v/vern-llm.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/vern-llm"><img src="https://img.shields.io/npm/dm/vern-llm.svg" alt="npm downloads" /></a>
+  <a href="https://bundlephobia.com/package/vern-llm"><img src="https://img.shields.io/bundlephobia/minzip/vern-llm.svg" alt="bundle size" /></a>
+  <a href="https://github.com/LakBud/vernLLM/actions/workflows/test.yml"><img src="https://github.com/LakBud/vernLLM/actions/workflows/test.yml/badge.svg" alt="test status" /></a>
+  <a href="https://github.com/LakBud/vernLLM/blob/main/LICENSE.md"><img src="https://img.shields.io/npm/l/vern-llm.svg" alt="license" /></a>
+  <img src="https://img.shields.io/node/v/vern-llm.svg" alt="node version" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+Production-ready resilience for LLM calls; Retries, timeouts, caching, and circuit breaking for any OpenAI-compatible chat completion API (OpenAI, Groq, Anthropic, Gemini, Bedrock, and more via adapters).
+
+**Full documentation: [vernllm.vercel.app](https://vernllm.vercel.app)** — installation, structured output, caching, circuit breaker, every adapter, and the complete API reference all live there and are kept up to date. This README is a quick pitch, not the manual.
 
 ## Install
 
@@ -8,300 +30,37 @@ Retry + timeout + cache wrapper for OpenAI-compatible chat completion calls (Ope
 pnpm add vern-llm openai
 ```
 
-## Basic usage
+## Quick start
 
 ```ts
 import OpenAI from 'openai';
 import { VernLLM } from 'vern-llm';
 
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-
 const llm = new VernLLM({
-  client: openai,
+  client: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
   model: 'gpt-4o',
+  maxRetries: 3,
+  timeoutMs: 10_000,
+  circuitBreaker: true,
 });
 
-const parsed = await llm.call({
+const result = await llm.call({
   systemPrompt: 'Return JSON: { "skills": string[] }',
   userContent: 'Extract skills from: ...',
 });
-
-// jsonMode: false returns the raw string, no parsing
-const text = await llm.call({
-  systemPrompt: 'Summarize this.',
-  userContent: '...',
-  jsonMode: false,
-});
-```
-
-`VernLLM` is also exported as `RetryLLM` — same class, same behavior, pick whichever name reads better in your codebase:
-
-```ts
-import { RetryLLM } from 'vern-llm';
-
-const llm = new RetryLLM({ client: openai, model: 'gpt-4o' });
-```
-
-## Structured output with Zod
-
-Pass a `schema` and get a typed, validated result. Works with any validator exposing `safeParse` (Zod v3/v4).
-
-```ts
-import { z } from 'zod';
-
-const CandidateSchema = z.object({
-  name: z.string(),
-  skills: z.array(z.string()),
-});
-
-// result is typed as z.infer<typeof CandidateSchema>
-const result = await llm.call({
-  systemPrompt: 'Extract the candidate name and skills as JSON.',
-  userContent: resumeText,
-  schema: CandidateSchema,
-});
-```
-
-On a schema mismatch, `call` throws `LLMError('validation')` with `.issues` set to the validator's error object, without burning a retry (validation failures are deterministic).
-
-## Provider-native JSON Schema mode
-
-`schema` above only validates client-side, after the model has already responded. `jsonSchema` sends the schema to the provider (OpenAI/Groq `response_format: { type: 'json_schema' }`), constraining generation itself — the model can't produce a shape that violates it. Combine both for provider-level constraint plus typed client-side inference:
-
-```ts
-const result = await llm.call({
-  systemPrompt: 'Extract the candidate name and skills.',
-  userContent: resumeText,
-  jsonSchema: {
-    name: 'Candidate',
-    schema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string' },
-        skills: { type: 'array', items: { type: 'string' } },
-      },
-      required: ['name', 'skills'],
-    },
-  },
-  schema: CandidateSchema, // optional client-side type/validation on top
-});
-```
-
-`jsonSchema` implies JSON mode. The Anthropic adapter has no native structured-output equivalent, so it embeds the schema in the system prompt as an instruction instead of provider-enforcing it.
-
-## Per-call model override and reasoning effort
-
-```ts
-const llm = new VernLLM({ client: openai, model: 'gpt-4o-mini' }); // default model
-
-await llm.call({
-  systemPrompt: '...',
-  userContent: '...',
-  model: 'o3', // overrides the instance default for this call only
-  reasoningEffort: 'high', // passed through as `reasoning_effort`; ignored by models that don't support it
-});
 ```
 
-`reasoningEffort` is dropped by the Anthropic adapter — Claude's extended thinking uses a token budget, not an effort tier, so there's no faithful 1:1 mapping.
-
-## Caching + usage metering
-
-```ts
-import { InMemoryCacheAdapter } from 'vern-llm';
-
-const llm = new VernLLM({
-  client: openai,
-  model: 'gpt-4o',
-  cache: new InMemoryCacheAdapter(), // swap for your own Redis/Upstash adapter
-});
-
-const result = await llm.cachedCall({
-  cacheKey: `cv:${cvId}`,
-  ttl: 3600,
-  fn: () => llm.call({ systemPrompt, userContent }),
-  reserveUsage: () => quota.reserve(userId),
-  refundUsage: () => quota.refund(userId),
-});
-```
-
-If `refundUsage` itself throws, that failure is logged and swallowed — the original error from `fn` (or the cache write) is what propagates, so a broken refund path never masks the real failure.
-
-### `cachedLLMCall` — cached + retried in one call
+## Why vern-llm?
 
-`cachedCall` is a thin cache wrapper; it doesn't apply retry/timeout/circuit-breaker behavior on its own — that's up to whatever `fn` does. If `fn` is always going to be `() => llm.call(...)`, `cachedLLMCall` wires that up for you:
-
-```ts
-const result = await llm.cachedLLMCall({
-  cacheKey: `cv:${cvId}`,
-  ttl: 3600,
-  call: { systemPrompt, userContent }, // same shape as call()'s params
-  reserveUsage: () => quota.reserve(userId),
-  refundUsage: () => quota.refund(userId),
-});
-```
-
-### Custom cache adapter
-
-```ts
-import type { CacheAdapter } from 'vern-llm';
-
-class UpstashCacheAdapter implements CacheAdapter {
-  async get(key: string) {
-    /* ... */
-  }
-  async set(key: string, value: unknown, ttl: number) {
-    /* ... */
-  }
-}
-```
-
-## Token usage tracking
-
-```ts
-const llm = new VernLLM({
-  client: openai,
-  model: 'gpt-4o',
-  onUsage: (usage) => {
-    // { promptTokens, completionTokens, totalTokens, requestId, model }
-    billing.record(usage);
-  },
-});
-```
+- **Retries with backoff**: transient failures retry automatically; validation errors and non-retryable status codes fail fast instead
+- **Structured output**: pass a Zod schema, get a typed, validated result back
+- **Provider-native JSON Schema mode**: constrain generation itself, not just validate after the fact
+- **Caching**: wrap any call with `cachedCall`/`cachedLLMCall`, bring your own cache adapter
+- **Circuit breaker**: trips after repeated failures, recovers automatically once the provider's back
+- **One interface, every provider**: OpenAI, Groq, Mistral, DeepSeek, Cerebras, Together, Fireworks, Ollama, Anthropic, Gemini, Bedrock, or raw HTTP via `fromFetch`
+- **Zero bundled deps**: `zod` and provider SDKs are peer dependencies; this package only relies on their shapes structurally
 
-## Circuit breaker
-
-Stops hammering a provider that's down instead of retrying every call.
-
-```ts
-const llm = new VernLLM({
-  client: openai,
-  model: 'gpt-4o',
-  circuitBreaker: { threshold: 5, cooldownMs: 30_000 }, // or `true` for defaults
-});
-
-llm.getCircuitState(); // 'closed' | 'open' | 'half-open' | undefined
-```
-
-Once `threshold` consecutive failures occur, further calls fail immediately with `LLMError('circuit_open')` until `cooldownMs` elapses, at which point one trial call is allowed through (half-open). A successful trial closes the circuit; a failed one reopens it.
-
-## Pluggable logger
-
-```ts
-import type { Logger } from 'vern-llm';
-
-const pinoLogger: Logger = {
-  debug: (msg) => logger.debug(msg),
-  warn: (msg) => logger.warn(msg),
-  error: (msg, meta) => logger.error(meta, msg),
-};
-
-const llm = new VernLLM({ client: openai, model: 'gpt-4o', logger: pinoLogger });
-```
-
-Defaults to a console logger; `debug` logging is gated by the `debug` option (`NODE_ENV !== 'production'` by default), `warn`/`error` always fire.
-
-## Multi-provider adapters
-
-`VernLLM` expects a client shaped like OpenAI's `chat.completions.create`. Some providers already match that shape and need no adapter; others need one that translates their native API into it.
-
-### Already OpenAI-wire-compatible — zero-transform passthrough
-
-Groq, Mistral, DeepSeek, Cerebras, Together AI, Fireworks AI, and Ollama (via its `/v1/chat/completions` endpoint) all speak the same wire format as OpenAI. These are thin named wrappers around the same passthrough — pick whichever name matches your provider for readability:
-
-```ts
-import { VernLLM, fromGroq, fromMistral, fromTogether } from 'vern-llm';
-
-const llm = new VernLLM({
-  client: fromGroq(new Groq({ apiKey: process.env.GROQ_API_KEY })),
-  model: 'llama-3.3-70b-versatile',
-});
-```
-
-`fromOpenAICompatible()` is the underlying function if your provider isn't in the named list — same thing, generic name.
-
-### Anthropic
-
-```ts
-import Anthropic from '@anthropic-ai/sdk';
-import { VernLLM, fromAnthropic } from 'vern-llm';
-
-const llm = new VernLLM({
-  client: fromAnthropic(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })),
-  model: 'claude-sonnet-4-6',
-});
-```
-
-No native `response_format` or `reasoning_effort` equivalent — JSON mode/schema are emulated via a system-prompt instruction (schema text embedded, not provider-enforced); `reasoning_effort` is dropped.
-
-### Gemini
-
-```ts
-import { GoogleGenerativeAI } from '@google/generative-ai';
-import { VernLLM, fromGemini } from 'vern-llm';
-
-const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
-const model = genAI.getGenerativeModel({ model: 'gemini-2.5-flash' });
-
-const llm = new VernLLM({ client: fromGemini(model), model: 'gemini-2.5-flash' });
-```
-
-Unlike Anthropic, `jsonSchema` maps to Gemini's native `responseSchema` + `responseMimeType: 'application/json'`, so it's actually provider-enforced here. `reasoning_effort` is dropped (Gemini's thinking models use a token budget instead).
-
-### AWS Bedrock
-
-Bedrock's SDK v3 exposes `.send(command)`, not a direct method, so wrap it:
-
-```ts
-import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime';
-import { VernLLM, fromBedrock } from 'vern-llm';
-
-const client = new BedrockRuntimeClient({ region: 'us-east-1' });
-
-const llm = new VernLLM({
-  client: fromBedrock({
-    converse: (params, options) =>
-      client.send(new ConverseCommand(params), { abortSignal: options.signal }),
-  }),
-  model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
-});
-```
-
-Uses Bedrock's Converse API, which is unified across model families (Anthropic, Titan, Llama, Mistral, etc. all speak the same request/response shape), so this one adapter works regardless of which `model` you point it at. JSON mode is emulated via system prompt, same as Anthropic; `reasoning_effort` is dropped.
-
-### Anything else — `fromFetch`
-
-For a provider with no SDK, or where pulling one in isn't worth it, `fromFetch` is a raw HTTP escape hatch — supply the URL, headers, and two small mapping functions, and retries/timeouts/circuit-breaker/JSON handling all still apply:
-
-```ts
-import { VernLLM, fromFetch } from 'vern-llm';
-
-const llm = new VernLLM({
-  client: fromFetch({
-    url: 'https://api.example.com/v1/generate',
-    headers: () => ({ Authorization: `Bearer ${process.env.EXAMPLE_API_KEY}` }),
-    mapRequest: (params) => ({
-      model: params.model,
-      prompt: params.messages.map((m) => m.content).join('\n\n'),
-      max_tokens: params.max_tokens,
-    }),
-    mapResponse: (json) => ({
-      content: json.output,
-      usage: { promptTokens: json.usage?.input, completionTokens: json.usage?.output },
-    }),
-  }),
-  model: 'example-model-v1',
-});
-```
-
-Non-2xx responses throw with `.status` set, so `nonRetryableStatus` still fails fast on 401/403 as usual.
-
-## Notes
-
-- Requires Node 20+ (`AbortSignal.any`).
-- Non-retryable status codes (default `400, 401, 403`) fail fast instead of burning a retry, and are reported as `LLMError('api', status)` rather than a generic unknown error.
-- An already-aborted `signal` rejects immediately with `LLMError('aborted')` before any request is dispatched.
-- `jsonMode: false` skips JSON parsing entirely and returns the raw string.
-- `zod` and provider SDKs (`openai`, `groq-sdk`, `@anthropic-ai/sdk`) are not bundled — bring your own; this package only relies on their shapes structurally.
+See the [docs](https://vernllm.vercel.app) for adapter setup, caching, the circuit breaker, and structured output in depth.
 
 ## Development
 
@@ -309,11 +68,13 @@ Non-2xx responses throw with `.status` set, so `nonRetryableStatus` still fails
 pnpm install
 pnpm run build            # tsdown → dist (ESM + CJS + types)
 pnpm run typecheck        # tsc --noEmit on src, since tsdown doesn't fully type-check
-pnpm run typecheck:test   # tsc --noEmit on src + test (separate tsconfig, no rootDir conflict)
 pnpm run test             # vitest run
-pnpm run test:watch       # vitest, watch mode
 pnpm run test:coverage    # vitest run --coverage (v8 provider)
 pnpm run changeset        # record a change for the next release
 ```
 
-Tests live in `tests/`, mirroring `src/`: `VernLLM.call.test.ts` and `VernLLM.schema.test.ts` cover retry/backoff/timeout/abort/schema/model-override/usage behavior, `circuitBreaker.test.ts` covers the breaker as a unit and its integration with `call()`, `cachedCall.test.ts` covers caching and usage reservation/refund, `logger.test.ts` covers the injectable logger, and `test/adapters/*.test.ts` cover each provider adapter's request/response translation against a fake client, no real API calls are made anywhere in the suite.
+Tests live in `tests/`, mirroring `src/`, and cover retry/backoff/timeout/abort/schema/model-override/usage behavior, the circuit breaker (unit + integration), caching, the injectable logger, and every provider adapter's request/response translation against a fake client — no real API calls anywhere in the suite.
+
+## License
+
+[MIT](https://github.com/LakBud/vernLLM/blob/main/LICENSE.md) © LakBud

package/dist/index.cjs

@@ -135,9 +135,12 @@ function extractStatus(err) {
 * Runs an async function and cancels it if it takes longer than the given
 * timeout. Creates an internal abort controller that fires after the
 * timeout elapses, and combines it with any external signal the caller
-* passed in so either one can cancel the underlying call. The internal
-* timer is always cleared afterward, whether the function succeeds,
-* fails, or is aborted, so nothing is left running in the background
+* passed in so either one can cancel the underlying call. If the internal
+* timeout triggers and the underlying operation aborts, the error is
+* converted into an LLMError with type "timeout". External cancellations
+* continue to propagate as aborted errors. The internal timer is always
+* cleared afterward, whether the function succeeds, fails, or is aborted,
+* so nothing is left running in the background.
 */
 async function withTimeout(fn, timeoutMs, externalSignal) {
 	const controller = new AbortController();
@@ -147,6 +150,9 @@ async function withTimeout(fn, timeoutMs, externalSignal) {
 	const signal = externalSignal ? AbortSignal.any([externalSignal, controller.signal]) : controller.signal;
 	try {
 		return await fn(signal);
+	} catch (err) {
+		if (controller.signal.aborted && !externalSignal?.aborted && err instanceof DOMException && err.name === "AbortError") throw new LLMError("Request timed out", "timeout");
+		throw err;
 	} finally {
 		clearTimeout(timer);
 	}
@@ -351,28 +357,53 @@ var VernLLM = class {
 		return this.parseAndValidate(content, params.schema);
 	}
 	/**
+	* Anthropic and Gemini both require strict user/assistant alternation
+	* (and reject or silently mishandle two consecutive same-role turns), so
+	* this validates `history` up front rather than letting a malformed
+	* request surface as a confusing provider-side error. Thrown as a
+	* validation LLMError, which `shouldRetry` never retries, since retrying
+	* the same malformed input can't succeed
+	*/
+	validateHistory(history) {
+		let previousRole;
+		for (const [index, turn] of history.entries()) {
+			if (turn.role !== "user" && turn.role !== "assistant") throw new LLMError(`Invalid history[${index}].role "${turn.role}": must be "user" or "assistant"`, "validation");
+			if (turn.role === previousRole) throw new LLMError(`history must alternate user/assistant turns: consecutive "${turn.role}" turns at history[${index - 1}] and history[${index}]`, "validation");
+			previousRole = turn.role;
+		}
+		if (previousRole === "user") throw new LLMError("The last entry in history is a \"user\" turn, which would collide with the current userContent turn. history must end with an \"assistant\" turn (or be empty).", "validation");
+	}
+	/**
 	* Applies per call defaults and shapes the params into the request
 	* object expected by the underlying client, including the resolved
 	* response format. Also returns whether JSON parsing should be
 	* applied to the response and which model was ultimately used
 	*/
 	buildRequestPayload(params) {
-		const { systemPrompt, userContent, temperature = .2, jsonMode = true, maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema } = params;
+		const { systemPrompt, userContent, history = [], temperature = .2, jsonMode = true, maxTokens = this.defaultMaxTokens, model = this.model, reasoningEffort, jsonSchema } = params;
 		const useJson = jsonMode || Boolean(jsonSchema);
 		const responseFormat = this.buildResponseFormat(jsonSchema, useJson);
+		this.validateHistory(history);
 		const request = {
 			model,
 			temperature,
 			max_tokens: maxTokens,
 			...responseFormat ? { response_format: responseFormat } : {},
 			...reasoningEffort ? { reasoning_effort: reasoningEffort } : {},
-			messages: [{
-				role: "system",
-				content: systemPrompt
-			}, {
-				role: "user",
-				content: userContent
-			}]
+			messages: [
+				{
+					role: "system",
+					content: systemPrompt
+				},
+				...history.map((turn) => ({
+					role: turn.role,
+					content: turn.content
+				})),
+				{
+					role: "user",
+					content: userContent
+				}
+			]
 		};
 		return {
 			useJson,
@@ -509,19 +540,33 @@ var VernLLM = class {
 //#region src/adapters/anthropic.ts
 /**
 * Wraps an Anthropic SDK client so it satisfies the same `LLMClient`
-* interface VernLLM uses for OpenAI/Groq. Anthropics Messages API has no
-* `response_format: json_object` equivalent, so when the caller requests
-* JSON mode, this adapter appends an instruction to the system prompt
-* asking the model to respond with JSON only
+* interface VernLLM uses for OpenAI/Groq.
+*
+* `response_format: json_schema` is mapped to Anthropics forced tool-use:
+* a single tool is defined with `input_schema` set to the caller's schema,
+* and `tool_choice` forces the model to call it, so the output is
+* provider-constrained to match the schema rather than merely instructed
+* to via prompt text (the same guarantee OpenAIs native `json_schema` mode
+* gives, built on Anthropics tool-calling primitive instead).
+*
+* `response_format: json_object` (no schema to build a tool from) falls
+* back to a system-prompt instruction, since theres nothing to constrain
+* generation against.
 */
 function fromAnthropic(anthropicClient) {
 	return { chat: { completions: { async create(params, options) {
 		const systemMessage = params.messages.find((m) => m.role === "system");
-		const userMessages = params.messages.filter((m) => m.role === "user");
+		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
+		const toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name : void 0;
 		let jsonInstruction;
-		if (params.response_format?.type === "json_schema") {
-			const { name, schema } = params.response_format.json_schema;
-			jsonInstruction = `Respond with valid JSON only, no prose or markdown fences. The JSON must conform to this schema (name: "${name}"):\n${JSON.stringify(schema)}`;
+		let tools;
+		if (params.response_format?.type === "json_schema" && toolName) {
+			const { schema, description } = params.response_format.json_schema;
+			tools = [{
+				name: toolName,
+				description,
+				input_schema: schema
+			}];
 		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
 		const system = [systemMessage?.content, jsonInstruction].filter(Boolean).join("\n\n");
 		const response = await anthropicClient.messages.create({
@@ -529,12 +574,23 @@ function fromAnthropic(anthropicClient) {
 			max_tokens: params.max_tokens,
 			temperature: params.temperature,
 			system: system || void 0,
-			messages: userMessages.map((m) => ({
-				role: "user",
+			messages: conversationMessages.map((m) => ({
+				role: m.role,
 				content: m.content
-			}))
+			})),
+			...tools ? {
+				tools,
+				tool_choice: {
+					type: "tool",
+					name: toolName
+				}
+			} : {}
 		}, options);
-		const text = response.content.find((block) => block.type === "text")?.text ?? "";
+		let text;
+		if (toolName) {
+			const toolUse = response.content.find((block) => block.type === "tool_use" && block.name === toolName);
+			text = toolUse ? JSON.stringify(toolUse.input) : "";
+		} else text = response.content.find((block) => block.type === "text")?.text ?? "";
 		return {
 			choices: [{ message: { content: text } }],
 			usage: {
@@ -562,7 +618,7 @@ function fromAnthropic(anthropicClient) {
 function fromGemini(geminiClient) {
 	return { chat: { completions: { async create(params, options) {
 		const systemMessage = params.messages.find((m) => m.role === "system");
-		const userMessages = params.messages.filter((m) => m.role === "user");
+		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
 		const wantsJson = Boolean(params.response_format);
 		const generationConfig = {
 			temperature: params.temperature,
@@ -572,8 +628,8 @@ function fromGemini(geminiClient) {
 		if (params.response_format?.type === "json_schema") generationConfig.responseSchema = params.response_format.json_schema.schema;
 		const response = await geminiClient.generateContent({
 			model: params.model,
-			contents: userMessages.map((m) => ({
-				role: "user",
+			contents: conversationMessages.map((m) => ({
+				role: m.role === "assistant" ? "model" : "user",
 				parts: [{ text: m.content }]
 			})),
 			systemInstruction: systemMessage ? { parts: [{ text: systemMessage.content }] } : void 0,
@@ -601,35 +657,53 @@ function fromGemini(geminiClient) {
 * regardless of which underlying model `modelId` points at, as long as
 * that model supports Converse (most current-generation ones do)
 *
-* Theres no uniform native JSON Schema enforcement across families here
-* (some support it via forced tool-use, which varies per model), so
-* `jsonSchema`/`jsonMode` are emulated via a system-prompt instruction, same
-* approach as the Anthropic adapter. `reasoning_effort` has no Converse
-* equivalent and is dropped
+* `response_format: json_schema` is mapped to Converses `toolConfig`: a
+* single tool is defined from the schema and `toolChoice` forces the model
+* to call it, constraining output at generation time rather than merely
+* instructing for it via prompt text. Native tool support varies by model
+* family (most current-generation ones support it via Converse; check your
+* specific `modelId` if a call fails with an unsupported-parameter error).
+* `response_format: json_object` (no schema to build a tool from) and
+* `reasoning_effort` (no Converse equivalent) fall back to a system-prompt
+* instruction and are dropped respectively.
 */
 function fromBedrock(bedrockClient) {
 	return { chat: { completions: { async create(params, options) {
 		const systemMessage = params.messages.find((m) => m.role === "system");
-		const userMessages = params.messages.filter((m) => m.role === "user");
+		const conversationMessages = params.messages.filter((m) => m.role === "user" || m.role === "assistant");
+		const toolName = params.response_format?.type === "json_schema" ? params.response_format.json_schema.name : void 0;
 		let jsonInstruction;
-		if (params.response_format?.type === "json_schema") {
-			const { name, schema } = params.response_format.json_schema;
-			jsonInstruction = `Respond with valid JSON only, no prose or markdown fences. The JSON must conform to this schema (name: "${name}"):\n${JSON.stringify(schema)}`;
+		let toolConfig;
+		if (params.response_format?.type === "json_schema" && toolName) {
+			const { schema, description } = params.response_format.json_schema;
+			toolConfig = {
+				tools: [{ toolSpec: {
+					name: toolName,
+					description,
+					inputSchema: { json: schema }
+				} }],
+				toolChoice: { tool: { name: toolName } }
+			};
 		} else if (params.response_format?.type === "json_object") jsonInstruction = "Respond with valid JSON only, no prose or markdown fences.";
 		const systemParts = [systemMessage?.content, jsonInstruction].filter((s) => Boolean(s));
 		const response = await bedrockClient.converse({
 			modelId: params.model,
-			messages: userMessages.map((m) => ({
-				role: "user",
+			messages: conversationMessages.map((m) => ({
+				role: m.role,
 				content: [{ text: m.content }]
 			})),
 			system: systemParts.length ? systemParts.map((text$1) => ({ text: text$1 })) : void 0,
 			inferenceConfig: {
 				temperature: params.temperature,
 				maxTokens: params.max_tokens
-			}
+			},
+			...toolConfig ? { toolConfig } : {}
 		}, options);
-		const text = response.output?.message?.content?.map((c) => c.text ?? "").join("") ?? "";
+		let text;
+		if (toolName) {
+			const toolUseBlock = response.output?.message?.content?.find((block) => block.toolUse?.name === toolName);
+			text = toolUseBlock?.toolUse ? JSON.stringify(toolUseBlock.toolUse.input) : "";
+		} else text = response.output?.message?.content?.map((c) => c.text ?? "").join("") ?? "";
 		return {
 			choices: [{ message: { content: text } }],
 			usage: {