CHANGELOG.md

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.6.1] - 2026-04-22

Added

• Hash options for image_generation=: Pass a Hash of tool options (e.g., chat.image_generation = { size: "1536x1024", quality: "low", model: "gpt-image-2" }) to configure the OpenAI Responses API image generation tool. Useful for selecting a specific GPT Image model, changing size/quality, forcing generate-vs-edit mode with action:, masked edits via input_image_mask:, and the rest of the options from OpenAI's image generation docs. chat.image_generation = true still works and continues to use OpenAI's defaults.

Changed

• image_generation= validates its argument: Only true, false, nil, or a Hash are now accepted. nil is normalized to false. Any other value raises ArgumentError. (Technically breaking: values like truthy strings or integers that silently worked before now raise.)

• Bumped openai runtime dependency from ~> 0.43 to ~> 0.59: Picks up the typed action field on the image_generation tool, gpt-5.4 mini/nano model slugs, and assorted upstream SDK transport fixes. No gem code changes were required for the bump — every method we call kept the same signature.

Fixed

• Saved images now use the correct file extension: Generated images are sniffed with Marcel and saved as .png, .jpg, or .webp based on the decoded bytes. Previously every image was written to 001.png regardless of output_format, which produced misnamed files when callers asked for JPEG or WebP.

[0.6.0] - 2026-04-13

Breaking

• Proxy-aware API key resolution: The gem no longer falls back from AICHAT_PROXY_KEY to OPENAI_API_KEY. When proxy is off, it uses OPENAI_API_KEY. When proxy is on (AICHAT_PROXY=true), it uses AICHAT_PROXY_KEY. Missing the expected var raises a KeyError with guidance on which variable to create.

Added

• proxy: keyword argument on initialize: Override the AICHAT_PROXY env default at construction time, e.g. AI::Chat.new(proxy: true).

• Case-insensitive AICHAT_PROXY: TRUE, True, etc. are now accepted.

• Transactional proxy= setter: Toggling proxy re-resolves the API key and resets validation. If key resolution fails, the instance is rolled back to its previous state.

• Beginner-friendly error messages: Missing env var and auth failure errors now name the specific variable and where to get a key.

Changed

• Boolean coercion for proxy values: proxy: kwarg and proxy= setter coerce values with !!. Only nil defers to the env var.

• Env var names extracted to constants: PROXY_ENV, PROXY_KEY_ENV, OPENAI_KEY_ENV defined once on the class.

[0.5.8] - 2026-03-02

Fixed

• Integration API key test fallback: Updated integration test setup to treat an empty AICHAT_PROXY_KEY as missing before falling back to OPENAI_API_KEY, matching runtime behavior.

[0.5.7] - 2026-03-02

Changed

• Default API key lookup order: AI::Chat.new and AI::Chat.generate_schema! now look for AICHAT_PROXY_KEY first, then fall back to OPENAI_API_KEY when the first value is missing or empty.

• Explicit API key override behavior: Passing api_key: still takes highest precedence, and passing api_key_env_var: still uses that environment variable exactly.

Added

• Unit coverage for API key precedence: Added tests covering default env order, empty AICHAT_PROXY_KEY fallback, explicit api_key_env_var:, and explicit api_key: behavior.

Updated

• Integration test setup: Integration tests now run when either AICHAT_PROXY_KEY or OPENAI_API_KEY is present.

• Documentation: README now documents the new default key lookup order and updates the direct OpenAI::Client example to match.

[0.5.6] - 2026-03-02

Changed

• Proxy default from env: AI::Chat.new now enables proxy mode by default when AICHAT_PROXY is exactly "true".

• Schema generation proxy default: AI::Chat.generate_schema! now uses the same AICHAT_PROXY default when proxy: is omitted.

• Explicit override precedence: Explicit chat.proxy = ... and generate_schema!(..., proxy: ...) continue to override env defaults.

Added

• Unit coverage for proxy defaults: Added tests for env parsing ("true" exact match), explicit override behavior, and generate_schema! precedence.

• Proxy env documentation: README now documents AICHAT_PROXY behavior for both chat generation and schema generation.

[0.5.5] - 2026-02-10

Fixed

• IRB display for get_items: chat.get_items now shows the formatted AI::Items output in IRB/Rails console (without requiring puts ...inspect). This avoids pp unwrapping Delegator objects.

[0.5.4] - 2026-02-03

Changed

• Updated dependencies:
  • openai gem updated from ~> 0.34 to ~> 0.43 (fixes CGI.parse issue in Ruby 4)
  • standard (dev) updated from 1.50.0 to ~> 1.53

Removed

• Unused dependencies:
  • Removed ostruct runtime dependency (not used in library code)
  • Removed refinements dev dependency (not used)

[0.5.3] - 2026-02-03

Added

• Truncate base64 data URIs in output: Long base64-encoded images in messages are now truncated in inspect and to_html output for readability. Displays as "data:image/png;base64,iVBORw0K... (12345 chars)".

[0.5.2] - 2026-02-03

Fixed

• to_html compatibility with awesome_print: Use AmazingPrint::Inspector directly instead of the ai() method to avoid conflicts when the awesome_print gem is also present in a project.

• to_html formatting: Wrap output in <pre> tags with proper styling to preserve newlines and formatting in HTML views.

Changed

• Ruby version requirement: Now supports Ruby 4.0+ (changed from ~> 3.2 to >= 3.2).

• Updated dependencies:

  • amazing_print updated from ~> 1.8 to ~> 2.0

[0.5.0] - 2025-12-05

Breaking Changes

• Renamed items to get_items: The method now clearly indicates it makes an API call. Returns an AI::Items wrapper that delegates to the underlying response while providing nice display formatting.

Added

• Reasoning summaries: When reasoning_effort is set, the API now returns reasoning summaries in get_items (e.g., "Planning Ruby version search", "Confirming image tool usage").

• Improved console display: AI::Chat, AI::Message, and AI::Items now display nicely in IRB and Rails console with colorized, formatted output via AmazingPrint.

• HTML output for ERB templates: All display objects have a to_html method for rendering in views. Includes dark terminal-style background for readability.

• AI::Message class: Messages are now AI::Message instances (a Hash subclass) with custom display methods.

• AI::Items class: Wraps the conversation items API response with nice display methods while delegating all other methods (like .data, .has_more, etc.) to the underlying response.

• TTY-aware display: Console output automatically detects TTY and disables colors when output is piped or redirected.

• New example: examples/16_get_items.rb demonstrates inspecting conversation items including reasoning, web searches, and image generation.

Changed

• Default model: Changed from gpt-5.1 to gpt-5.2.

[0.4.0] - 2025-11-25

Breaking Changes

• Removed previous_response_id: Use conversation_id instead for managing conversation state. The gem now exclusively uses OpenAI's Conversations API for continuity. Simply store the conversation_id and set it on a new AI::Chat instance to continue a conversation.

• Renamed assistant! to generate!: The method that sends messages to the API and generates a response is now called generate! to better reflect its purpose.

Changed

• Default model: Changed from gpt-4.1-nano to gpt-5.1.

• Default reasoning effort: Remains nil. For gpt-5.1, this is equivalent to "none" reasoning.

• Web search tool: Renamed from web_search_preview to web_search to match OpenAI's GA release.

Added

• last_response_id reader: New public accessor to get the ID of the most recent response. Useful for background mode workflows where you need to track, retrieve, or cancel a specific response from another process.

• Automatic conversation management: The gem now automatically creates and manages conversations via OpenAI's Conversations API. The conversation_id is set after the first generate! call and maintained across subsequent calls.

• items method: Retrieve all conversation items (messages, tool calls, reasoning) from OpenAI's API with chat.items.

• Improved test coverage: Added integration tests for conversation continuity, file handling, and conversation items retrieval.

Notes

• Background mode limitation: There is currently no serialization-friendly hook to resume a background response from a different process. You can use last_response_id to track the response, but resuming requires the original AI::Chat instance or manual API calls.

• Manual message manipulation: If you manually add assistant messages to the messages array without a :response object, the prepare_messages_for_api method may not slice the history as expected on the next generate! call. This is an edge case for users who directly manipulate the messages array.

[0.0.0] - 2025-07-22

• Initial implementation.