llm-messages 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.6] - 2026-06-04
+
+### Added
+
+- Added a public conformance fixtures plan describing how API credits should be
+  used to refresh deterministic OpenAI/provider conversion fixtures without
+  putting secrets in public CI.
+
 ## [0.4.5] - 2026-06-04
 
 ### Changed

package/README.md

@@ -175,7 +175,9 @@ via `dropped-content` rather than failing.
 
 See [ROADMAP.md](./ROADMAP.md) for current maintenance priorities, including
 OpenAI Responses API coverage, live conformance fixtures and tool-call edge
-cases.
+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.
 
 ## Provider portability suite
 

package/ROADMAP.md

@@ -20,6 +20,8 @@ fallback behavior matter.
    payloads, keeping the committed test fixtures deterministic and safe to run
    without API keys.
 
+   Plan: [docs/conformance-fixtures.md](./docs/conformance-fixtures.md)
+
 3. **Tool-call edge cases**
 
    Expand tests for parallel tool calls, missing provider ids, invalid JSON

package/docs/conformance-fixtures.md

@@ -0,0 +1,58 @@
+# Conformance fixtures plan
+
+`llm-messages` keeps OpenAI Chat Completions-compatible messages as its hub
+shape. Provider-backed conformance fixtures are the next layer for proving that
+the conversions stay correct as OpenAI, Anthropic and Gemini payloads evolve.
+
+The fixture workflow should be safe to run in public CI without secrets, while
+still allowing maintainers to refresh source payloads with API credits when
+needed.
+
+## Fixture classes
+
+| Class               | What it proves                                                                 |
+| ------------------- | ------------------------------------------------------------------------------ |
+| Text response       | Basic assistant text maps into the canonical OpenAI message shape.             |
+| Tool call           | Provider tool/function calls preserve name, arguments and ids where available. |
+| Tool result         | Tool result placement remains valid after provider conversion.                 |
+| Parallel tools      | Multiple tool calls and results keep deterministic ordering.                   |
+| Multimodal input    | Image, audio and document parts are preserved or warned consistently.          |
+| Responses API shape | OpenAI Responses API output can be mapped or rejected with explicit warnings.  |
+| Lossy conversion    | Unsupported or ambiguous provider data emits stable warning codes.             |
+
+## Refresh flow
+
+1. Generate provider payloads locally with maintainer-controlled API keys.
+2. Minimize each payload to the fields needed for conversion coverage.
+3. Remove request ids, timestamps, account metadata and provider-specific
+   tracking fields.
+4. Commit only deterministic JSON fixtures and expected normalized output.
+5. Run public CI without any API keys.
+
+## OpenAI API credit use
+
+Credits should be used only for fixture refreshes that improve public coverage:
+
+- Responses API text and tool-call payloads.
+- Streaming/tool-call examples that differ from Chat Completions.
+- Multimodal message examples relevant to provider conversion.
+- Regression checks before releases when provider payload formats change.
+
+Credits should not be used for hidden benchmarks, private app traffic or tests
+that require secrets in public CI.
+
+## Fixture contract
+
+Every committed fixture should include:
+
+- Provider name and source API family.
+- Input payload.
+- Expected canonical OpenAI-compatible message.
+- Expected provider output when round-tripping is supported.
+- Expected warning codes for lossy or unsupported conversions.
+- A short note explaining why the case matters.
+
+## Public CI rule
+
+Public CI must remain offline and deterministic. Live provider calls belong in a
+maintainer-only refresh script, not in the default test suite.

package/package.json

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