Repository navigation
v0.5.0
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
- NEW: docs/changelog/v0/v0.5.0.md: this changelog.
- NEW: docs/events.md: the event catalogue, payload shape and logging options.
- docs/settings.md covers
jsonObjectandjsonObjectFallback; docs/server.md, docs/protocol-support.md, the feature inventory and known limitations are updated to match.
🔧 Dependencies
No dependency updates.
Upgrade notes
- Library warnings are quiet by default. Set
logs: trueto get the console warnings back, orlogs: "<path>"to write them to a file. Subscribing towarningorlogis the other way to see them, and events fire whether logging is on or not. silentis deprecated. It still works and meanslogs: false;logswins when both are set.json_objectrequests to an Anthropic-protocol upstream now carry a schema instead of being dropped. SetjsonObject: "instruction"on an upstream known to lack structured outputs to skip the failed first attempt, orjsonObject: "drop"for the old behaviour.
| Metric | Coverage |
|---|---|
| Statements | 100.0% |
| Branches | 100.0% |
| Functions | 100.0% |
| Lines | 100.0% |
Avg: 100.0% · ed7053e · Node lts/*