llm_composer

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.16.0] - 2026-02-23

### Added
- Added `LlmComposer.Providers.OpenAIResponses` provider to call OpenAI's `/responses` API, including support for `reasoning_effort` and structured outputs while keeping a normalized `LlmResponse` shape.
- Added `LlmComposer.StreamChunk` and provider-specific stream chunk parsing so streaming events are normalized into typed chunks (`:text_delta`, `:tool_call_delta`, `:done`, etc.).
- Added `LlmComposer.FunctionCallExtractors` to centralize provider-specific function call extraction logic.

### Changed
- Changed `LlmComposer.parse_stream_response` to be provider-aware (`parse_stream_response/2` and `parse_stream_response/3`) and return normalized `%LlmComposer.StreamChunk{}` values instead of raw decoded maps.
- Updated cost/token extraction to include `:open_ai_responses` provider responses.
- Updated OpenAI request handling to use shared timeout/request option helpers (including adapter `receive_timeout` support).
- Refactored provider response parsing into protocol-based adapters (`LlmComposer.ProviderResponse` and `LlmComposer.ProviderStreamChunk`) for clearer provider-specific normalization.
- Updated `README.md` with OpenAI Responses API and normalized streaming chunk documentation.
- Expanded `LlmComposer.Provider` moduledoc with a minimal implementation guide for creating custom providers.
- Updated ExDoc configuration to include `LICENSE` in docs extras.
- Updated dependency `ex_doc` from `0.31` to `0.34` and enabled `warn_if_outdated: true`.

## [0.15.0] - 2026-02-17

### Added
- Added configurable JSON engine for HTTP requests: new `:json_engine` config option allows specifying JSON encoder/decoder library (defaults to JSON, falls back to Jason).

### Changed
- Changed Google provider to keep `additionalProperties` in response schemas instead of removing them, allowing for more flexible schema definitions.
- Updated dependency `ex_aws` from 2.5 to 2.6.
- Updated dependency `tesla` from 1.14 to 1.16.
- Restructured configuration in `config/config.exs` with better provider organization.

## [0.14.2] - 2026-02-10

### Changed
- Changed `LlmResponse.new/3` to return an error tuple instead of raising an exception when encountering unhandled response formats from providers, for easier error handling/debugging.

## [0.14.1] - 2026-02-09

### Fixed
- Fixed `request_params` merging to use deep merge instead of shallow merge, allowing nested configurations (like `generationConfig` in Google provider) to be properly combined with provider defaults.

## [0.14.0] - 2026-02-04

### Added
- Configurable retry/backoff for provider requests: new settings allow configuring retry attempts and backoff behavior for provider calls (e.g. max attempts, base delay, backoff factor). This improves robustness when providers return transient errors.

## [0.13.1] - 2026-01-09

### Added
- Added ability to set custom HTTP request headers for OpenRouter provider.
- Updated README with documentation on configuring custom headers for OpenRouter.

## [0.13.0] - 2025-12-01

### Changed
- Replaced the previous auto function execution workflow with a manual process powered by `FunctionExecutor` and `FunctionCallHelpers`, and added README guidance for executing OpenAI/OpenRouter/Google function calls explicitly.

### Added
- `LlmComposer.FunctionExecutor` for explicit/manual execution of function calls returned by providers.
- `LlmComposer.FunctionCallHelpers` with helpers to build assistant messages and tool-result messages when handling function calls.

### Changed
- Replaced the previous auto function execution workflow with a manual process and updated the public APIs accordingly.
- `LlmComposer.LlmResponse` now exposes `function_calls` instead of the previous `actions` field and normalizes provider-specific function-call formats.
- `LlmComposer.Providers.Utils` message mapping and request/response formatting updated to support explicit `:tool_result` messages and provider-specific assistant formats (OpenAI/Google/OpenRouter).
- `LlmComposer.Helpers` was simplified/trimmed to remove automatic execution helpers in favor of the manual executor.
- `README.md` updated with a new "Function Calls" section demonstrating the manual workflow, API usage, and examples.

### Breaking Changes
- Removed the auto-execution helpers/tests and related documentation that assumed functions ran automatically.
- Settings struct keys `:auto_exec_functions` and `:functions` were removed; function descriptors are expected to be provided per-call or via provider options.
- Tests that relied on automatic function execution were removed (`test/llm_composer/function_calls_auto_execution_test.exs`).

## [0.12.3] - 2025-11-07

### Changed
- decimal dep mandatory

## [0.12.2] - 2025-11-06

### Changed
- Changed license from GPL-3.0 to MIT
- Updated documentation and improved code examples

## [0.12.0] - 2025-10-17

### Removed
- Removed support for deprecated `:provider` and `:provider_opts` settings keys. Use `:providers` list instead.
- Removed support for global `:api_key` setting in Settings struct. Specify `:api_key` per-provider in the `:providers` list.
- Removed backward compatibility handling for deprecated settings in `LlmComposer` and `ProvidersRunner`.

### Added
- Automatic cost tracking for OpenAI, Google, and OpenRouter providers:
  - Fetches real-time pricing from provider APIs (models.dev for OpenAI/Google, OpenRouter API).
  - `CostInfo` struct in responses with token usage and cost breakdowns.
  - Support for automatic and manual pricing configuration.
- `Pricing` module for cost calculations.
- Supporting modules for OpenRouter pricing and tracking.

### Changed
- Enhanced `LlmResponse` to include cost information.
- Updated provider implementations (OpenAI, Google, OpenRouter) to support cost tracking.
- Updated README with examples for cost tracking.
- Refactored cost information retrieval and pricing module structure for improved maintainability.
- Updated AGENTS.md with current development guidelines.

## [0.11.2] - 2025-09-25

- Updated README a bit more docs and examples. Included in new release for hex docs too.

## [0.11.1] - 2025-09-23

- Added OpenRouter function-call support and provider message-mapping fixes; preserved assistant tool_calls during auto-executed functions.

## [0.11.0] - 2025-09-23

- **Implement multi-provider support with provider routing and failover:**
  - Introduced a new `:providers` list in `LlmComposer.Settings` to replace deprecated `:provider` and `:provider_opts` keys.
  - Added validation in `LlmComposer` to enforce/suggest exclusive use of `:providers` and warn about deprecated keys.
  - Implemented `LlmComposer.ProvidersRunner` to handle provider execution, supporting multiple providers with fallback logic.
  - Added `LlmComposer.ProviderRouter` behaviour for routing strategies on provider selection, failure handling, and blocking.
  - Provided a simple default provider router `LlmComposer.ProviderRouter.Simple` with exponential backoff blocking on provider failures.
  - Refactored `LlmComposer.run_completion/3` to delegate to `ProvidersRunner` for provider selection and execution.
- Optimized `LlmComposer.Cache.Ets` by switching `put` and `delete` calls to asynchronous casts, improving performance.
- Maintained backward compatibility with deprecated settings keys, issuing warnings and supporting legacy calls until version 0.12.0.
- Changed `response_format` key to `response_schema` for better structured output definition that works across multiple providers.
  - Structured outputs now available for OpenAI provider as well.
  - Default JSON module is JSON; falls back to Jason if JSON is not loaded.

## [0.10.0] - 2025-09-03
- **Add Google (Gemini) provider**: Full feature support including chat, functions, streaming, and structured outputs.
- **Add Vertex AI integration**: Same Google provider but can be used with it's Vertex API. Enterprise support with OAuth 2.0 authentication via Goth library.

## [0.9.0] - 2025-09-01
- Update elixir(1.18) and erlang(28).

## [0.8.0] - 2025-08-12
- **Add tracking costs for OpenRouter provider**: Introduced cost tracking functionality specifically for the OpenRouter provider to monitor API usage expenses.

## [0.7.0] - 2025-07-31
- **Add HttpClient module**: Introduced a new HttpClient module for improved HTTP handling.
- **Add streaming read capability**: Added the capability of streaming read for LLM providers completions.
- **Documentation and config updates**: Updates to README.md and configuration files.

## [0.6.0] - 2025-07-17
- **Refactor Models to Providers**: Renamed the "Models" module to "Providers" to better reflect the architecture and improve code organization.
- **Fix optional ex_aws dependency**: Fixed the ex_aws dependency to be truly optional by adding missing `Code.ensure_loaded` checks that were making the dependency mandatory.

## [0.5.5] - 2025-07-08
- **Fix typos**: Fixed various typos throughout the codebase.

## [0.5.4] - 2025-07-07
- **Add support for structured outputs in OpenRouter**: Added functionality to support structured outputs when using the OpenRouter model.

## [0.5.3] - 2025-06-30
- **Remove provider_routing from OpenRouter**: Removed the `provider_routing` functionality from the OpenRouter model, simplifying the model configuration and request building process.

## [0.5.2] - 2025-06-19
- **Making `ex_aws` dependency optional**: `ex_aws` is only required for the Bedrock provider. Making it optional so it is not included in case Bedrock is not used. Additionally, removing the `Logger.error()` in case of a model error, delegating this to the caller of the library.

## [0.5.1] - 2025-06-12
- **Adjust `Message.content` specs**: For Bedrock, the `content` field of the message has to be a list, allowing for messages with with multi-type content (image + text).

## [0.5.0] - 2025-06-12
- **Include Bedrock Support**: Included Bedrock support as provider only with `completion()`s support.

## [0.3.5] - 2024-12-18
- **Fix default api_key setting value**: The default value was en empty string. Now it is nil to be evaluated as false when getting the key from the map later. 

## [0.3.4] - 2024-12-17
- **OpenAI API Keys**: Use an API key passed as a parameter when calling chat_completion — overriding the global API key defined in the config. The param is sent inside the settings. 

## [0.3.3] - 2024-12-04
- **Timeouts**: Configurable OpenAI's timeout. Default set to 50 seconds.

## [0.3.2] - 2024-12-03
- **Timeouts**: Fix OpenAI-timeout handling and increase Tesla's timeout to 5 seconds.

## [0.3.1] - 2024-10-14

### Added
- **Error Handling**: Introduced a new module `LlmComposer.Errors` with a custom `MissingKeyError` for better error management.
- **Removed Legacy Code**: Removed the `get_messages/4` function from `LlmComposer` to streamline message handling.

## [0.3.0] - 2024-10-10

### Added
- **System Prompt Handling**: Added support for an optional system prompt in `run_completion/3`. The `system_prompt` is now treated as `nil` when not provided.
- **Custom Message Flow Example**: Updated the `README.md` with an example of how to use the `run_completion/3` function directly with a custom message history.
- **Nil Message Handling in Models**: Handling the `nil` case when system_prompt not provided

## [0.2.0] - 2024-10-10

### Added
- Initial release with support for basic message handling, interaction with OpenAI and Ollama models, and a foundational structure for model settings and function execution.

---
[Unreleased]: https://github.com/doofinder/llm_composer/compare/0.16.0...HEAD
[0.16.0]: https://github.com/doofinder/llm_composer/compare/0.15.0...0.16.0
[0.15.0]: https://github.com/doofinder/llm_composer/compare/0.14.2...0.15.0
[0.14.2]: https://github.com/doofinder/llm_composer/compare/0.14.1...0.14.2
[0.14.1]: https://github.com/doofinder/llm_composer/compare/0.14.0...0.14.1
[0.14.0]: https://github.com/doofinder/llm_composer/compare/0.13.1...0.14.0
[0.13.1]: https://github.com/doofinder/llm_composer/compare/0.13.0...0.13.1
[0.13.0]: https://github.com/doofinder/llm_composer/compare/0.12.3...0.13.0
[0.12.3]: https://github.com/doofinder/llm_composer/compare/0.12.2...0.12.3
[0.12.2]: https://github.com/doofinder/llm_composer/compare/0.12.0...0.12.2
[0.12.0]: https://github.com/doofinder/llm_composer/compare/0.11.2...0.12.0
[0.11.2]: https://github.com/doofinder/llm_composer/compare/0.11.1...0.11.2
[0.11.1]: https://github.com/doofinder/llm_composer/compare/0.11.0...0.11.1
[0.11.0]: https://github.com/doofinder/llm_composer/compare/0.10.0...0.11.0
[0.10.0]: https://github.com/doofinder/llm_composer/compare/0.9.0...0.10.0
[0.9.0]: https://github.com/doofinder/llm_composer/compare/0.8.0...0.9.0
[0.8.0]: https://github.com/doofinder/llm_composer/compare/0.7.0...0.8.0
[0.7.0]: https://github.com/doofinder/llm_composer/compare/0.6.0...0.7.0
[0.6.0]: https://github.com/doofinder/llm_composer/compare/0.5.5...0.6.0
[0.5.5]: https://github.com/doofinder/llm_composer/compare/0.5.4...0.5.5
[0.5.4]: https://github.com/doofinder/llm_composer/compare/0.5.3...0.5.4
[0.5.3]: https://github.com/doofinder/llm_composer/compare/0.5.2...0.5.3
[0.5.2]: https://github.com/doofinder/llm_composer/compare/0.5.1...0.5.2
[0.5.1]: https://github.com/doofinder/llm_composer/compare/0.5.0...0.5.1
[0.3.5]: https://github.com/doofinder/llm_composer/compare/0.3.4...0.3.5
[0.5.0]: https://github.com/doofinder/llm_composer/compare/0.3.5...0.5.0
[0.3.4]: https://github.com/doofinder/llm_composer/compare/0.3.3...0.3.4
[0.3.3]: https://github.com/doofinder/llm_composer/compare/0.3.2...0.3.3
[0.3.2]: https://github.com/doofinder/llm_composer/compare/0.3.1...0.3.2
[0.3.1]: https://github.com/doofinder/llm_composer/compare/0.3.0...0.3.1
[0.3.0]: https://github.com/doofinder/llm_composer/compare/0.2.0...0.3.0
[0.2.0]: https://github.com/doofinder/llm_composer/compare/d9f96d55859300d779d9c3899b4c33578bb2e362...0.2.0
[first commit]: https://github.com/doofinder/llm_composer/commit/d9f96d55859300d779d9c3899b4c33578bb2e362