Skip to content

v0.5.0

Choose a tag to compare

@cldmv-bot cldmv-bot released this 06 Nov 14:01
· 8 commits to master since this release
3d7744f

llm-translator v0.5.0 Changelog

Release Date: November 2026
Release Type: Minor
Branch: next → master


Overview

Version 0.5.0 makes everything the library logs available to the application as events, and makes logging itself opt-in. It also sends OpenAI's response_format: { type: "json_object" } to Anthropic upstreams instead of dropping it, falling back to a system-prompt instruction by itself when an upstream refuses the schema form, and fills in Anthropic's stop_details for refusals.

The one behaviour change to look at: used as a library, the translator no longer prints warnings to the console unless logs is set. The CLI still prints them by default.


✨ Features

Events for everything the library logs, and opt-in logging (#111)

translator.events.on(name, fn) subscribes to an event and returns a function that removes the listener; translator.events.off(name, fn) removes it by reference. An onEvent callback in the config is registered before startup, so it also sees the startup events (the detection run and the PDF libraries loading). The general events are log, warning and error; the specific ones are fallback, failover, effort, dropped, detect and usage. One occurrence fires its specific event, then the general events that fit, then "*", all with the same { type, kind?, level, message, time, ...details } payload. Listeners only observe: one that throws or rejects is caught and never affects a request. events: false turns events off.

Logging is a separate switch and is off by default. logs: true prints warnings and errors to the console, and logs: "<path>" (relative or absolute) appends every event as a JSON line to that file. Server mode also passes events to the Fastify logger. The CLI keeps console output on by default and gains --logs [path]; --silent is the same as logs: false. The full catalogue is in docs/events.md. Resolves #109.

response_format: json_object to Anthropic, with a self-healing fallback (#108)

Anthropic has no JSON mode, so json_object used to be dropped on the way to an Anthropic-protocol upstream. The new jsonObject setting picks how it is sent: "schema" (the default) sends output_config.format as a json_schema with the schema { "type": "object" }, "instruction" adds "Respond with a single valid JSON object and nothing else." to the system prompt, and "drop" keeps the old behaviour.

Not every upstream accepts structured outputs, so with jsonObjectFallback (on by default) a 400 or 422 answer to the schema form is retried once with the instruction. When the retry works, that upstream and model are remembered until the process ends, and a fallback warning carries the upstream's status and error message, so known upstreams can get their own setting later. When the retry fails too, the original error is returned and nothing is remembered. A json_schema the client sent itself is never retried. Resolves #59.

stop_details for refusals (#107)

A content_filter finish now produces stop_reason: "refusal" with stop_details: { type: "refusal", category: null, explanation }, using the upstream's refusal text as the explanation, both streamed and not. A streamed refusal with no answer text now comes through as the text block, the same as the non-streaming reply. Resolves #21.

📚 Documentation

🔧 Dependencies

No dependency updates.


Upgrade notes

  • Library warnings are quiet by default. Set logs: true to get the console warnings back, or logs: "<path>" to write them to a file. Subscribing to warning or log is the other way to see them, and events fire whether logging is on or not.
  • silent is deprecated. It still works and means logs: false; logs wins when both are set.
  • json_object requests to an Anthropic-protocol upstream now carry a schema instead of being dropped. Set jsonObject: "instruction" on an upstream known to lack structured outputs to skip the failed first attempt, or jsonObject: "drop" for the old behaviour.

coverage

Metric Coverage
Statements 100.0%
Branches 100.0%
Functions 100.0%
Lines 100.0%

Avg: 100.0% · ed7053e · Node lts/*

👥 Contributors