llm-messages 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.9] - 2026-06-04
+
+### Added
+
+- Added a public adoption guide for teams evaluating OpenAI-compatible provider
+  fallback, local validation, and production conversion checks.
+- Included the examples directory in the published npm package.
+
+## [0.4.8] - 2026-06-04
+
+### Changed
+
+- Updated CI to run on Node 20 and 22, matching the secure Vitest development
+  tooling while keeping the package runtime build target at Node 18.
+
 ## [0.4.7] - 2026-06-04
 
 ### Changed

package/README.md

@@ -179,6 +179,10 @@ cases. The [conformance fixtures plan](./docs/conformance-fixtures.md) describes
 how API credits should be used to refresh deterministic public fixtures without
 putting secrets in CI.
 
+For teams evaluating the package, the
+[adoption guide](./docs/adoption-guide.md) covers the OpenAI-compatible boundary,
+local validation and production checks.
+
 ## Provider portability suite
 
 `llm-messages` is the conversation boundary in a small provider-portability

package/docs/adoption-guide.md

@@ -0,0 +1,93 @@
+# llm-messages adoption guide
+
+`llm-messages` is meant for teams that use OpenAI Chat Completions as their
+internal conversation shape but need to run the same agent loop against
+Anthropic, Gemini, or a fallback provider.
+
+Use it when you need:
+
+- one canonical OpenAI-compatible message history in your app
+- provider fallback without rewriting stored conversations
+- tool-call and tool-result conversion across providers
+- multimodal inputs that keep image, audio, and document parts explicit
+- deterministic warnings instead of hidden conversion loss
+
+## Five minute local check
+
+```sh
+npm install llm-messages
+```
+
+```ts
+import { convert, toAnthropic, toGemini } from 'llm-messages';
+
+const openaiMessages = [
+  { role: 'system', content: 'You are a concise support agent.' },
+  { role: 'user', content: 'Summarize this ticket and call the right tool.' },
+  {
+    role: 'assistant',
+    content: null,
+    tool_calls: [
+      {
+        id: 'call_route',
+        type: 'function',
+        function: {
+          name: 'route_ticket',
+          arguments: '{"priority":"high","team":"billing"}',
+        },
+      },
+    ],
+  },
+  { role: 'tool', tool_call_id: 'call_route', content: '{"ok":true}' },
+];
+
+const anthropicBody = toAnthropic(openaiMessages);
+const geminiBody = toGemini(openaiMessages);
+const geminiFromAnthropic = convert(anthropicBody, {
+  from: 'anthropic',
+  to: 'gemini',
+});
+```
+
+No API key is required for this check. The conversion runs locally and returns
+plain request bodies you can inspect in tests.
+
+## Integration pattern
+
+1. Keep OpenAI Chat Completions messages as the canonical persisted shape.
+2. Convert only at the provider boundary.
+3. Log conversion warnings from `onWarning`.
+4. Normalize provider responses before saving assistant messages.
+5. Cover important agent loops with fixtures before enabling provider fallback.
+
+```ts
+import { normalizeResponse, toAnthropic } from 'llm-messages';
+
+const requestBody = toAnthropic(messages, {
+  onWarning: (warning) => logger.warn({ warning }, 'message conversion warning'),
+});
+
+const providerResponse = await anthropic.messages.create(requestBody);
+const { message, finishReason, usage } = normalizeResponse(providerResponse, {
+  from: 'anthropic',
+});
+```
+
+## What to validate before production
+
+- tool-call IDs stay stable across your retry and replay path
+- provider-specific system prompt rules match your app assumptions
+- unsupported modalities are surfaced through warnings
+- saved fixtures cover tool calls, tool results, images, and fallback
+- provider SDK versions are pinned or tested in CI
+
+## Related public material
+
+- [Conformance fixture plan](./conformance-fixtures.md)
+- [Roadmap](../ROADMAP.md)
+- [Offline portability demo](https://github.com/slegarraga/llm-portability-demo)
+- [OpenAI-compatible agent portability note](https://github.com/slegarraga/llm-portability-demo/blob/main/docs/openai-compatible-agent-portability.md)
+
+Questions, bug reports, and real-world fixture requests are welcome through
+[GitHub Issues](https://github.com/slegarraga/llm-messages/issues) or
+[sebastian@0a.cl](mailto:sebastian@0a.cl).

package/examples/usage.mjs

@@ -0,0 +1,26 @@
+// Run from the repo root after `npm run build`:
+//   node examples/usage.mjs
+import { toAnthropic, toGemini, convert } from '../dist/index.js';
+
+const messages = [
+  { role: 'system', content: 'You are a weather assistant.' },
+  { role: 'user', content: "What's the weather in Paris?" },
+  {
+    role: 'assistant',
+    content: null,
+    tool_calls: [
+      { id: 'call_abc', type: 'function', function: { name: 'get_weather', arguments: '{"location":"Paris"}' } },
+    ],
+  },
+  { role: 'tool', tool_call_id: 'call_abc', content: '15C partly cloudy' },
+];
+
+console.log('--- OpenAI -> Anthropic ---');
+console.log(JSON.stringify(toAnthropic(messages), null, 2));
+
+console.log('\n--- OpenAI -> Gemini ---');
+console.log(JSON.stringify(toGemini(messages), null, 2));
+
+console.log('\n--- Anthropic -> Gemini (via convert) ---');
+const anthropic = toAnthropic(messages);
+console.log(JSON.stringify(convert(anthropic, { from: 'anthropic', to: 'gemini' }), null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-messages",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Convert chat conversations and responses between OpenAI, Anthropic and Gemini. Tool calls, images, audio, documents and roles handled. Zero dependencies.",
   "keywords": [
     "openai",
@@ -55,6 +55,7 @@
   "files": [
     "dist",
     "docs",
+    "examples",
     "README.md",
     "ROADMAP.md",
     "LICENSE",