rosetta-ai 1.0.1 → 1.2.0

package/README.md

@@ -2,7 +2,9 @@
 
 The translation layer for LLM provider messages.
 
-Rosetta converts messages between different LLM providers using a standardized intermediate format (GenAI). Just pass in messages from any provider—OpenAI, Anthropic, Google, or even custom formats—and get consistent output. No manual mapping required.
+Rosetta converts messages between different LLM providers using [**GenAI**](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/), a standardized intermediate format. Just pass in messages from any provider—OpenAI, Anthropic, Google, or even custom formats—and get consistent output. No manual mapping required.
+
+> Rosetta was made by [Latitude](https://latitude.so?utm_source=github&utm_medium=oss&utm_campaign=rosetta_ai) as an effort to standardize the observability layer for any LLM application!
 
 ## Features
 
@@ -29,92 +31,265 @@ yarn add rosetta-ai
 ## Quick Start
 
 ```typescript
-import { translate, Provider } from "rosetta-ai";
+import { translate } from "rosetta-ai";
 
-// Your messages
-const messages = [
-  { role: "user", parts: [{ type: "text", content: "Hello!" }] },
+// Translate any LLM messages - provider is auto-detected
+const openAIMessages = [
+  { role: "system", content: "You are a helpful assistant." },
+  { role: "user", content: "Hello!" },
+  { role: "assistant", content: "Hi there! How can I help you today?" },
 ];
 
-// Convert to GenAI (intermediate format) - auto-infers source
-const { messages: genaiMessages } = translate(messages);
+const { messages, system } = translate(openAIMessages);
+// messages: GenAI format messages (user + assistant)
+// system: extracted system instructions
+```
 
-// Specify source provider explicitly
-const { messages: result } = translate(messages, {
-  from: Provider.GenAI,
-  to: Provider.GenAI,
-});
+Works with messages from any provider:
+
+```typescript
+// OpenAI Chat Completions
+const openAI = [{ role: "user", content: "Hello" }];
+translate(openAI); // Just works
+
+// Anthropic
+const anthropic = [{ role: "user", content: [{ type: "text", text: "Hello" }] }];
+translate(anthropic); // Just works
+
+// Vercel AI SDK
+const vercelAI = [{ role: "user", content: "Hello" }];
+translate(vercelAI); // Just works
+
+// More providers...
+
+// Unknown provider? Also works (uses Compat fallback)
+const unknown = [{ role: "user", content: "Hello" }];
+translate(unknown); // Still works
 ```
 
 ## API
 
-### translate / safeTranslate
+### translate
+
+The main function for translating messages between providers.
 
 ```typescript
-import { translate, safeTranslate, Provider } from "rosetta-ai";
+import { translate, Provider } from "rosetta-ai";
 
-// translate throws on error
 const { messages, system } = translate(inputMessages, {
-  from: Provider.GenAI,       // Source provider (optional, auto-inferred if not provided)
-  to: Provider.GenAI,         // Target provider (optional, defaults to GenAI)
-  system: systemInstructions, // Separated system instructions (optional)
-  direction: "input",         // "input" (default) or "output" - affects role interpretation (e.g. "user" vs "assistant")
+  from: Provider.OpenAICompletions, // Source provider (optional, auto-detected if omitted)
+  to: Provider.GenAI,               // Target provider (optional, defaults to GenAI)
+  system: "You are helpful",        // Separated system instructions (optional)
+  direction: "input",               // "input" (default) or "output"
 });
+```
 
-// safeTranslate returns error instead of throwing
-const result = safeTranslate(inputMessages);
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `from` | `Provider` | auto-detected | Source provider format |
+| `to` | `Provider` | `Provider.GenAI` | Target provider format |
+| `system` | `string \| object \| object[]` | - | System instructions (for providers that separate them) |
+| `direction` | `"input" \| "output"` | `"input"` | Affects role interpretation when translating strings |
+
+**Returns:** `{ messages, system? }` - translated messages and optional system instructions
+
+### safeTranslate
+
+Same as `translate`, but returns an error object instead of throwing.
+
+```typescript
+import { safeTranslate } from "rosetta-ai";
+
+const result = safeTranslate(messages, options);
 
 if (result.error) {
-  console.error("Translation failed:", result.error.message);
+  // Handle error: result.error is Error
 } else {
-  console.log("Translated:", result.messages);
+  // Use result.messages (properly typed)
 }
 ```
 
+### Translator Class
+
+For advanced configuration, create a `Translator` instance:
+
+```typescript
+import { Translator, Provider } from "rosetta-ai";
+
+const translator = new Translator({
+  // Custom priority order for provider auto-detection
+  inferPriority: [Provider.OpenAICompletions, Provider.Anthropic, Provider.GenAI],
+  
+  // Filter out empty messages during translation (default: false)
+  filterEmptyMessages: true,
+});
+
+const { messages } = translator.translate(inputMessages);
+const safeResult = translator.safeTranslate(inputMessages);
+```
+
+**Configuration Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `inferPriority` | `Provider[]` | `DEFAULT_INFER_PRIORITY` | Priority order for provider auto-detection |
+| `filterEmptyMessages` | `boolean` | `false` | Remove empty messages (no parts, or only empty text) during translation |
+
 ### Input Flexibility
 
-Messages and system instructions accept flexible input formats:
+Messages and system instructions accept flexible formats:
 
 ```typescript
-// Messages: string or array of provider messages
-translate("Hello!");                              // Simple string
-translate([{ role: "user", content: "Hello!" }]); // Provider message array
+// Messages: string or array
+translate("Hello!");                              // String → single message
+translate([{ role: "user", content: "Hello!" }]); // Array of provider messages
 
-// System: string, single object, or array
+// System: string, object, or array
 translate(messages, { system: "You are helpful" });
 translate(messages, { system: { type: "text", content: "Be helpful" } });
-translate(messages, { system: [{ type: "text", content: "Instructions" }] });
+translate(messages, { system: [{ type: "text", content: "Part 1" }, { type: "text", content: "Part 2" }] });
 ```
 
-Each provider validates messages with its own Zod schema at runtime.
+## Common Use Cases
 
-### Translator Class
+### Translate API responses for storage or display
+
+```typescript
+import OpenAI from "openai";
+import { translate, Provider } from "rosetta-ai";
+
+const openai = new OpenAI();
+const completion = await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "What's the weather?" }],
+});
+
+// Translate OpenAI response to unified GenAI format
+const { messages } = translate([completion.choices[0].message], {
+  from: Provider.OpenAICompletions,
+});
+
+// Now you have a consistent format regardless of which provider you used
+console.log(messages[0].parts[0]); // { type: "text", content: "..." }
+```
 
-For advanced configuration, use the `Translator` class:
+### Cross-provider translation
 
 ```typescript
-import { Translator, Provider } from "rosetta-ai";
+import { translate, Provider } from "rosetta-ai";
 
-const translator = new Translator({
-  // Custom priority order for provider inference
-  inferPriority: [Provider.GenAI],
+// Translate OpenAI messages to Vercel AI SDK format
+const openAIMessages = [
+  { role: "system", content: "You are helpful." },
+  { role: "user", content: "Hello!" },
+];
+
+const { messages } = translate(openAIMessages, {
+  from: Provider.OpenAICompletions,
+  to: Provider.VercelAI,
 });
+// Result: Vercel AI SDK compatible messages
+```
 
-const { messages } = translator.translate(inputMessages);
+### Handle tool calls across providers
+
+```typescript
+import { translate, Provider } from "rosetta-ai";
+
+// OpenAI tool call format
+const openAIWithToolCall = [
+  {
+    role: "assistant",
+    content: null,
+    tool_calls: [{
+      id: "call_abc123",
+      type: "function",
+      function: { name: "get_weather", arguments: '{"location":"Paris"}' },
+    }],
+  },
+  {
+    role: "tool",
+    tool_call_id: "call_abc123",
+    content: '{"temp": 20}',
+  },
+];
+
+// Translates to unified GenAI format with tool_call and tool_call_response parts
+const { messages } = translate(openAIWithToolCall, {
+  from: Provider.OpenAICompletions,
+});
+
+// Tool call part
+messages[0].parts[0]; // { type: "tool_call", name: "get_weather", arguments: { location: "Paris" }, ... }
+
+// Tool response part  
+messages[1].parts[0]; // { type: "tool_call_response", call_id: "call_abc123", content: {...}, ... }
+```
+
+### Translate multimodal content
+
+```typescript
+import { translate, Provider } from "rosetta-ai";
+
+const anthropicWithImage = [
+  {
+    role: "user",
+    content: [
+      { type: "text", text: "What's in this image?" },
+      {
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: "image/png",
+          data: "iVBORw0KGgo...",
+        },
+      },
+    ],
+  },
+];
+
+const { messages } = translate(anthropicWithImage, {
+  from: Provider.Anthropic,
+});
+
+// Image converted to blob part
+messages[0].parts[1]; // { type: "blob", modality: "image", mime_type: "image/png", content: "..." }
+```
+
+### Safe translation with error handling
+
+```typescript
+import { safeTranslate } from "rosetta-ai";
+
+const result = safeTranslate(unknownMessages);
+
+if (result.error) {
+  console.error("Translation failed:", result.error.message);
+} else {
+  console.log("Translated:", result.messages);
+}
 ```
 
+
+
 ## Supported Providers
 
-| Provider           | Status       | toGenAI | fromGenAI |
-| ------------------ | ------------ | ------- | --------- |
-| GenAI              | ✅ Available | ✅      | ✅        |
-| Promptl            | ✅ Available | ✅      | ✅        |
-| VercelAI           | ✅ Available | ✅      | ✅        |
-| OpenAI Completions | ✅ Available | ✅      | -         |
-| OpenAI Responses   | ✅ Available | ✅      | -         |
-| Anthropic          | ✅ Available | ✅      | -         |
-| Google Gemini      | ✅ Available | ✅      | -         |
-| Compat             | ✅ Available | ✅      | -         |
+| Provider | toGenAI | fromGenAI | Separated System | Description |
+|----------|---------|-----------|-----------------|-------------|
+| GenAI | ✅ | ✅ | Optional | Intermediate format (default target) |
+| Promptl | ✅ | ✅ | - | [promptl-ai](https://github.com/latitude-dev/promptl) format |
+| Vercel AI | ✅ | ✅ | - | Vercel AI SDK messages |
+| OpenAI Completions | ✅ | - | - | Chat Completions API |
+| OpenAI Responses | ✅ | - | - | Responses API |
+| Anthropic | ✅ | - | Yes | Messages API |
+| Google Gemini | ✅ | - | Yes | GenerateContent API |
+| Compat | ✅ | - | Optional | Universal fallback |
+
+- **toGenAI** = Can translate *from* this provider to GenAI (source)
+- **fromGenAI** = Can translate *to* this provider from GenAI (target)
+- **Separated System** = Provider separates system instructions from messages (use the `system` option if needed)
 
 ### Universal Compatibility
 
@@ -127,29 +302,31 @@ The **Compat** provider is a universal fallback that handles messages from *any*
 
 ```typescript
 // Works with any provider - no need to specify the source
-const weirdMessages = [
+const messages = [
   { role: "user", content: "Hello" },
-  { role: "assistant", tool_calls: [{ id: "1", function: { name: "search", arguments: "{}" } }] },
+  { role: "assistant", toolCalls: [{ id: "1", function: { name: "search", arguments: "{}" } }] },
 ];
 
-const { messages } = translate(weirdMessages); // Just works™
+const { messages: translated } = translate(messages); // Auto-detected and translated
 ```
 
 More providers will be added. See [AGENTS.md](./AGENTS.md) for contribution guidelines.
 
 ## GenAI Format
 
-GenAI is the intermediate format used for translation. It provides a unified representation of LLM messages:
+GenAI is the intermediate format used for translation, inspired by the [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/). It provides a unified representation of LLM messages across all providers:
 
 ```typescript
-import type { GenAIMessage, GenAIPart, GenAISystem } from "rosetta-ai";
+import type { GenAIMessage, GenAISystem } from "rosetta-ai";
 
 const message: GenAIMessage = {
-  role: "user",
-  parts: [
-    { type: "text", content: "Hello!" },
-    { type: "blob", modality: "image", content: "base64...", mime_type: "image/png" },
+  role: "user",           // "user" | "assistant" | "system" | "tool" | string
+  parts: [                // Array of content parts
+    { type: "text", content: "What's in this image?" },
+    { type: "uri", uri: "https://example.com/cat.jpg", modality: "image" },
   ],
+  name: "Alice",          // Optional: participant name
+  finish_reason: "stop",  // Optional: why the model stopped
 };
 
 const system: GenAISystem = [
@@ -159,32 +336,90 @@ const system: GenAISystem = [
 
 ### Part Types
 
-- `text` - Plain text content
-- `blob` - Binary data (base64 encoded)
-- `file` - File reference by ID
-- `uri` - URI reference
-- `reasoning` - Model reasoning/thinking
-- `tool_call` - Tool call request
-- `tool_call_response` - Tool call result
-- `generic` - Custom/extensible part type
+| Type | Description | Key Fields |
+|------|-------------|------------|
+| `text` | Plain text content | `content` |
+| `blob` | Binary data (base64) | `content`, `mime_type`, `modality` |
+| `file` | File reference by ID | `file_id`, `modality` |
+| `uri` | URL reference | `uri`, `modality` |
+| `reasoning` | Model thinking/reasoning | `content` |
+| `tool_call` | Tool/function call request | `call_id`, `name`, `arguments` |
+| `tool_call_response` | Tool/function result | `call_id`, `content` |
+| `generic` | Custom/extensible type | `content`, any additional fields |
 
 ### Provider Metadata
 
-All GenAI entities support `_provider_metadata` to preserve provider-specific data:
+All GenAI entities support `_provider_metadata` to preserve data during translation. The metadata has two types of fields:
+
+1. **Root-level shared fields** (camelCase): Cross-provider semantic data accessible to any target provider
+2. **Provider-specific slots** (snake_case): Data for same-provider round-trips only
 
 ```typescript
 const message: GenAIMessage = {
-  role: "assistant",
-  parts: [{ type: "text", content: "Hello!" }],
-  _provider_metadata: {
-    genai: { custom: "data" },
-  },
+  role: "tool",
+  parts: [{
+    type: "tool_call_response",
+    id: "call_123",
+    response: "Error occurred",
+    _provider_metadata: {
+      // Root-level shared fields - any target provider can read these
+      toolName: "get_weather",  // Tool name (GenAI schema doesn't include it)
+      isError: true,            // Error indicator
+      
+      // Provider-specific slot - only for same-provider round-trips
+      openai_completions: { annotations: [...] },
+    },
+  }],
 };
 ```
 
+**Shared fields**: `toolName`, `isError`, `isRefusal`, `originalType`
+
+**Provider slots**: `openai_completions`, `openai_responses`, `anthropic`, `google`, `vercel_ai`, `promptl`, `compat`
+
+This design enables lossless cross-provider translation while keeping providers isolated from each other.
+
+## TypeScript Support
+
+All types are exported for type-safe usage:
+
+```typescript
+import {
+  // Core types
+  type GenAIMessage,
+  type GenAIPart,
+  type GenAISystem,
+  
+  // API types
+  type TranslateOptions,
+  type TranslateResult,
+  
+  // Provider types
+  Provider,
+  type ProviderMessage,
+  type ProviderSystem,
+} from "rosetta-ai";
+
+// Type-safe translation
+const result: TranslateResult<Provider.GenAI> = translate(messages);
+
+// Access provider-specific message types
+type OpenAIMsg = ProviderMessage<Provider.OpenAICompletions>;
+```
+
 ## Examples
 
-Check out the [examples](./examples) folder for usage examples (requires building the package first).
+The [examples](./examples) folder contains E2E tests demonstrating real-world usage with actual provider SDKs:
+
+```bash
+cd examples
+pnpm install
+pnpm test  # Runs tests (imports directly from src, no build needed)
+```
+
+Tests include:
+- **Real API calls** (when API keys are set) - validates against actual provider responses
+- **Hardcoded messages** - runs without API keys for fast iteration
 
 ## Development