ai-lite 0.6.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f7c5581a41c1371b086b33502200da2ad06cab07cc202efd0f943616effb738
-  data.tar.gz: 3a1c897735f7aa945e4cca0fb3bea1a86c3beefc7e823e8a149b78e93ac3b7c8
+  metadata.gz: a6b2ed589de27af46e6ce7babfb4a1ec32808ecfae567f29ed8db35bfd129f26
+  data.tar.gz: ddee8996d702a77709b30bd9bb360994abfbc3e4875386db04b99241541a413d
 SHA512:
-  metadata.gz: 6c5f349cdf43703435f4ab0c08216ce59c73737042ad179ed675339a37238b175dffdc96d5a0014ac0a89dca554e4ed4d4279c417bd13a25fd9dc80d4d9dadc7
-  data.tar.gz: 0475ffdba930c5a5dc6c463f78c6abfc7c14306b233b1d05c17e6e6aa5f20bb706271c994e4aec0f2f350f656bcda3c681716751e280968ec8962222cfdea432
+  metadata.gz: 9591556daadccbb5107f8b52f6d5ca825232003336a87db144e41971ec9921282a38ea884928d0d1f5ee8ea4d84fb8b67698ddcfb1894f678ab2bc615a9dcdb8
+  data.tar.gz: 24aa31e8ddaa48bf6876bc7e4375c212d46994d37709a32bb52c797b3618f0dc770fe831919039781c2f9529b40ff0c85b12c04dea4a7894c61fa4e8515fa282

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## Unreleased
+
+- Add Gemini image generation with base64 results, optional file output, native
+  options, image model configuration, and model checks.
+
+- Add Gemini text embeddings for single and multiple inputs, with dimensions,
+  embedding model configuration, model checks, and the standard result envelope.
+
+## 1.0.0 (unreleased)
+
+- Introduce independent `AiLite::OpenAI` and `AiLite::Gemini` providers.
+- Preserve documented legacy OpenAI entry points through `AiLite`, with deprecation
+  warnings once per entry point per process. Removal is planned for v2.0.
+- Add OpenAI and Gemini text streaming through `chat_stream`.
+- Add `available_models`, `model_available?`, `configured_models`, and
+  `check_configured_models` to both providers; Gemini discovery follows all pages.
+- Add Gemini chat with native structured media input and interaction continuation,
+  plus a YouTube URL helper. Existing OpenAI utility methods remain available.
+- Document model-list limitations, provider-specific debug output, and migration.
+- Treat failed/incomplete OpenAI generations as errors even when HTTP status is 200.
+- Handle fragmented UTF-8 and mixed SSE line endings in both stream parsers.
+
+Gemini image generation, speech, file transcription, additional
+providers, and async convenience methods are deferred beyond v1.

data/README.md

@@ -1,35 +1,330 @@
 # AI Lite
 
-AI Lite is a pure Ruby, dependency-light client for simple OpenAI API calls.
+AI Lite is a lightweight, pure Ruby client for OpenAI and Gemini. Both providers
+support chat, streaming, embeddings, image generation, and model availability
+checks through simple interfaces and a consistent result format.
 
-It is built for Rails apps and plain Ruby projects where installing a full OpenAI SDK is too heavy, incompatible, or unnecessary. It is especially useful in legacy Rails apps where Rails, ActiveSupport, Ruby, or HTTP-client dependency constraints make larger client libraries difficult to add.
-
-Use AI Lite when you want a small OpenAI client that works without tying your app to a specific Rails version or a larger dependency stack.
+It is built for Rails apps and plain Ruby projects that need AI features with
+minimal dependencies. It is especially useful in legacy Rails apps where Ruby,
+Rails, or HTTP-client dependency constraints make larger SDKs difficult to add.
 
 This gem is intentionally small:
 
 - No Rails dependency
-- No official OpenAI gem dependency
+- No provider SDK dependency
 - No Faraday, HTTParty, ActiveSupport, or connection pool dependency
 - Uses only Ruby stdlib: `Net::HTTP`, `URI`, `JSON`, `Base64`, and `SecureRandom`
 
-It is not meant to replace the official OpenAI SDK. It is a small wrapper for projects that only need a few clean interfaces:
+Choose a provider and call the methods your app needs:
+
+```ruby
+require "ai_lite"
+
+openai = AiLite::OpenAI.new # Reads OPENAI_API_KEY
+gemini = AiLite::Gemini.new # Reads GEMINI_API_KEY
+
+openai.chat("Say hello")
+gemini.chat("Say hello")
+
+openai.embed("Text to vectorize")
+gemini.embed("Text to vectorize")
+
+openai.image("A simple app icon")
+gemini.image("A simple app icon")
+```
+
+Each provider has independent configuration and native API options. OpenAI also
+supports moderation, speech, and file transcription; Gemini supports structured
+media input and a YouTube helper. The table below lists the available methods.
+
+## Provider support
+
+| Method | OpenAI | Gemini |
+| --- | --- | --- |
+| `chat`, `chat_stream` | Yes | Yes |
+| Four model helpers | Yes | Yes |
+| `youtube` | No | Yes |
+| `embed`, `image` | Yes | Yes |
+| `moderate`, `speak`, `transcribe` | Yes | Not implemented |
+
+Unsupported provider methods are absent and raise Ruby's `NoMethodError` if called.
+Configure providers during application startup; do not mutate shared configuration
+or client headers while requests are running. The gem does not provide automatic
+retries, worker threads, or a background-job queue.
+
+## Gemini
+
+```ruby
+require "ai_lite"
+
+gemini = AiLite::Gemini.new # Reads GEMINI_API_KEY
+result = gemini.chat("Tell me a joke")
+puts result["content"]
+warn result["error"] if result["error"]
+```
+
+The lookup order is an explicit `api_key:`, Gemini configuration, then
+`ENV["GEMINI_API_KEY"]`. OpenAI credentials are never used for Gemini. The gem
+does not load `.env` automatically.
+
+```ruby
+AiLite::Gemini.configure do |config|
+  config.api_key = ENV["GEMINI_API_KEY"]
+  config.model = "gemini-3.8-flash"
+  config.embedding_model = "gemini-embedding-001"
+  config.image_model = "gemini-nano-banana-2.1"
+  config.timeout = 120
+  config.max_output_tokens = 2000
+end
+
+AiLite::Gemini.chat("Tell me a joke")
+```
+
+Each provider has independent configuration and a cached client. Constructor
+keywords override configured defaults. Configuration changes reset that provider's
+class-level client; existing instances keep their settings. Gemini uses the
+Interactions API at `https://generativelanguage.googleapis.com/v1beta/interactions`
+with `x-goog-api-key` authentication. Its API version and defaults belong to Gemini.
+
+`chat` accepts a string, a native Gemini content hash, or an array of native
+content blocks or interaction steps. Structured inputs pass through unchanged:
+
+```ruby
+result = gemini.chat([
+  { type: "video", uri: "https://www.youtube.com/watch?v=YOUR_VIDEO_ID" },
+  { type: "text", text: "Summarize the key points." }
+])
+```
+
+Google validates media access and model support. This does not download videos,
+upload local files, or make arbitrary video webpages accessible. Message history
+uses Gemini's native `user_input` / `model_output` steps with `content` arrays;
+OpenAI-style role/message arrays are not automatically translated.
+
+Multi-turn continuation uses the familiar keyword:
+
+```ruby
+first = gemini.chat("My name is William.")
+second = gemini.chat("What is my name?", previous_response_id: first["response_id"])
+```
+
+`instructions:` maps to `system_instruction`; `previous_response_id:` maps to
+`previous_interaction_id`; `max_output_tokens:` maps into `generation_config`.
+Gemini-specific settings remain available through `options:`:
+
+```ruby
+gemini.chat("Say hello", instructions: "Be concise.", options: {
+  store: false,
+  generation_config: { temperature: 0.4 }
+})
+```
+
+Interactions are stored by default by the provider; `store: false` opts out and
+prevents later server-side continuation from that interaction. See Google's
+[Interactions guide](https://ai.google.dev/gemini-api/docs/interactions-overview)
+and [API reference](https://ai.google.dev/api/interactions-api).
+
+Results use the standard `content`, `response_id`, `status`, `error`, and `raw`
+keys. Text is extracted only from `model_output` steps; JSON-looking text is
+parsed. `debug: true` retains the complete response, including non-text output,
+tool calls, and usage. Non-completed interactions (including `requires_action`)
+return an error rather than pretending the answer is complete; no tools are
+executed automatically. Input/API/transport errors return an error envelope;
+constructing a client without a key raises `ArgumentError`.
+
+Gemini speech and file transcription methods are not implemented yet. Use `chat_stream` for streaming; `chat` rejects
+`stream: true`. Both methods reject `background: true` before sending a request.
+Legacy `AiLite` entry points still use OpenAI.
+
+### Gemini embeddings
+
+`embed` mirrors OpenAI's text input and return shape: a string returns one numeric
+vector in `content`; an array returns a list of vectors in input order, including
+an array containing just one string.
+
+```ruby
+gemini = AiLite::Gemini.new
+result = gemini.embed("Text to vectorize")
+result["content"] # [0.12, -0.34, ...]
+
+gemini.embed(["First text", "Second text"], dimensions: 768)
+AiLite::Gemini.embed("Search query", options: { taskType: "RETRIEVAL_QUERY" })
+```
+
+The default is `gemini-embedding-001`. Override it with `embedding_model:` in the
+constructor, `config.embedding_model`, or `model:` per call. Both bare model IDs
+and `models/` prefixes are accepted. Model checks include the embedding model.
+
+Single strings use `embedContent`; arrays use one synchronous `batchEmbedContents`
+request. `dimensions:` maps to `outputDimensionality`. Native request fields in
+`options:` apply to each input; explicit model, input, and dimensions take precedence.
+See Google's [embedding API reference](https://ai.google.dev/api/embeddings).
+
+Gemini returns numeric vectors; `encoding_format:` may be omitted or set to
+`"float"`. Other formats return an error envelope. Empty inputs and invalid dimensions
+also return errors before making a request. `debug: true` retains the provider
+response and any usage metadata in `raw`; `response_id` is `nil` for embeddings.
+
+### Gemini image generation
+
+```ruby
+gemini = AiLite::Gemini.new
+result = gemini.image("A cat astronaut on the moon", output_path: "tmp/cat.jpg")
+result["content"] # Base64 image data, also returned when saving to a file
+
+AiLite::Gemini.image("A mountain landscape", options: {
+  response_format: { type: "image", aspect_ratio: "16:9", image_size: "2K" }
+})
+```
+
+The default image model is `gemini-nano-banana-2.1`. Set `config.image_model`,
+pass `image_model:` to the constructor, or override `model:` per call.
+Model checks include this setting. Requests use the Interactions API, with native
+settings passed through `options:`. Explicit prompt and model take precedence.
+Image requests do not inherit the chat output-token limit.
+
+Like OpenAI's `image`, `content` contains the first generated image as base64.
+Only image blocks from `model_output` steps are selected. `output_path:` saves
+its decoded bytes; the parent directory must already exist. Files retain the
+provider's encoding: the filename does not convert the image. Use `debug: true`
+to inspect MIME type, additional images, text, and usage in `raw`. Gemini can return
+JPEG data even when the output filename ends in `.png`; choose the extension to
+match the returned image MIME type. AI Lite does not transcode images.
+
+The initial interface accepts a text prompt, `model:`, `output_path:`, `debug:`,
+and `options:`. OpenAI-specific size, quality, background, and output format
+keywords are not shared; use Gemini's native `response_format` options as above.
+Streaming and background execution are rejected. Failed/incomplete interactions,
+missing or invalid image data, and file-write errors return error envelopes.
+See Google's [image generation guide](https://ai.google.dev/gemini-api/docs/image-generation).
+
+### Gemini model checks
+
+```ruby
+gemini = AiLite::Gemini.new
+result = gemini.available_models
+puts result["content"] unless result["error"]
+
+gemini.model_available?("gemini-3.8-flash") # true / false / nil on lookup failure
+gemini.configured_models                  # Includes chat, embedding, and image models
+gemini.check_configured_models            # Standard envelope containing a report
+
+# All four also work at class level:
+AiLite::Gemini.available_models(debug: true)
+AiLite::Gemini.model_available?("gemini-3.8-flash")
+AiLite::Gemini.configured_models          # No key or network required
+AiLite::Gemini.check_configured_models
+```
+
+`available_models` follows every page of Gemini's `/v1beta/models` endpoint and
+returns unique model IDs in `content`, with the `models/` resource prefix removed.
+`model_available?` accepts IDs with or without that prefix, uses exact matching
+(no alias resolution), and fetches a fresh complete list. Invalid empty/non-string
+IDs raise `ArgumentError`. Lookup errors return `nil`; inspect `available_models`
+or `check_configured_models` for error details.
+
+`configured_models` returns a local snapshot of the instance's settings; its
+class method reports current Gemini configuration. Currently only `chat` is
+configured: `chat_stream` and `youtube` use that same model.
+
+`check_configured_models` fetches the list once across its pages, then returns:
+
+```ruby
+result["content"]["chat"]
+# { "model" => "gemini-3.8-flash", "usage" => "chat",
+#   "available" => true, "error" => nil } # if listed
+```
+
+Any failed page makes the entire lookup fail; partial lists are not treated as
+complete. Reports use `available: nil` on failure, with both entry-level and
+outer errors. `debug: true` includes original page responses in
+`raw["pages"]`, preserving model metadata and any received error response.
+These methods make only model-list GET requests, never generation requests.
+They do not verify free-tier eligibility, quota, endpoint compatibility, or
+whether a model is temporarily overloaded. See Google's
+[Models API documentation](https://ai.google.dev/api/models).
+
+### YouTube helper
 
 ```ruby
-ai.chat("Say hello")
-ai.moderate("User submitted text")
-ai.embed("Text to vectorize")
-ai.image("A simple app icon")
-ai.speak("Read this aloud")
-ai.transcribe("tmp/meeting.mp3")
+result = gemini.youtube(
+  "https://www.youtube.com/watch?v=DV69qh0BzoA",
+  prompt: "Summarize this video in five bullet points.",
+  model: "gemini-3.5-flash-lite"
+)
+puts result["content"]
+warn result["error"] if result["error"]
 ```
 
+`AiLite::Gemini.youtube(url, prompt: ..., **kwargs)` also works. The helper
+validates one HTTPS YouTube video URL and a nonempty prompt, builds native video
+and text input, and delegates to `chat`. It accepts the same chat keywords,
+including `model:`, `instructions:`, `previous_response_id:`, `max_output_tokens:`,
+`debug:`, and `options:`, and returns the same envelope.
+
+Supported URL forms are `youtube.com/watch?v=...` (including `www` and `m`),
+`youtu.be/...`, and YouTube `/shorts/`, `/embed/`, and `/live/` video paths.
+URLs, including timestamp parameters, pass through unchanged. Validation checks
+URL shape and video ID, not whether the video is public or accessible to Gemini.
+The helper builds the same request as this explicit input:
+
+```ruby
+gemini.chat([
+  { type: "video", uri: url },
+  { type: "text", text: "Summarize this video." }
+])
+# Equivalent convenience call:
+gemini.youtube(url, prompt: "Summarize this video.")
+```
+
+Invalid URLs/prompts return an error envelope without a network request. No video
+is downloaded locally. Gemini controls video support, limits, and processing.
+
+For streaming, pass the video and text blocks directly to `chat_stream`; the
+`youtube` helper itself uses non-streaming `chat`.
+
+### Gemini streaming
+
+```ruby
+result = gemini.chat_stream("Tell me a short story", debug: true) do |text|
+  print text
+  $stdout.flush
+end
+puts
+warn result["error"] if result["error"]
+
+# Class-level calls also work:
+AiLite::Gemini.chat_stream("Hello") { |text| print text }
+```
+
+`chat_stream` accepts the same input and keywords as `chat` and requires a block.
+It yields model-output text fragments as they arrive, excluding reasoning and
+other non-text events, and returns the standard envelope with the accumulated
+answer and interaction ID. JSON-looking final text is parsed just like `chat`.
+It runs in the calling thread without creating background threads.
+
+Gemini's final streaming event may contain only partial interaction metadata.
+With `debug: true`, `raw` therefore contains `{ "interaction" => ..., "events" => [...] }`:
+the latest lifecycle interaction object and every received event, including tool,
+reasoning, and usage events when provided. This differs from non-streaming `chat`,
+whose `raw` is the complete HTTP response. No extra retrieval request is made;
+retaining all events uses additional memory. Without debugging, `raw` is `nil`.
+
+HTTP errors, malformed/disconnected streams, and incomplete or failed interactions
+return an error envelope, retaining partial text when available. Always check
+`error`, even with HTTP status `200`. Missing blocks raise `ArgumentError`, and
+exceptions from your block propagate. The configured timeout applies to each
+network read, not the total stream duration. See Google's
+[streaming event reference](https://ai.google.dev/api/interactions-api#InteractionSseStreamEvent).
+
+The remaining usage sections below describe the OpenAI provider.
+
 ## Usage
 
 ```ruby
 require "ai_lite"
 
-ai = AiLite.new
+ai = AiLite::OpenAI.new
 result = ai.chat("Say hello")
 
 puts result["content"]
@@ -40,7 +335,7 @@ By default, the client looks for an API key in `OPENAI_API_KEY`, then falls back
 You can also pass the key directly:
 
 ```ruby
-ai = AiLite.new(api_key: "sk-...")
+ai = AiLite::OpenAI.new(api_key: "sk-...")
 ```
 
 ## Configuration
@@ -49,7 +344,7 @@ In Rails, configure the default client from an initializer:
 
 ```ruby
 # config/initializers/ai_lite.rb
-AiLite.configure do |config|
+AiLite::OpenAI.configure do |config|
   config.api_key = ENV["OPENAI_API_KEY"]
   config.model = "gpt-5.5"
   config.moderation_model = "omni-moderation-latest"
@@ -80,16 +375,47 @@ Any value left unset falls back to AI Lite's default:
 Then use the configured singleton-style client:
 
 ```ruby
-result = AiLite.chat("Say hello")
+result = AiLite::OpenAI.chat("Say hello")
 ```
 
 You can still instantiate a separate client for another token:
 
 ```ruby
-client = AiLite.new(api_key: "sk-other-token")
+client = AiLite::OpenAI.new(api_key: "sk-other-token")
 result = client.chat("Say hello")
 ```
 
+## Migrating to provider namespaces
+
+Use `AiLite::OpenAI` for OpenAI configuration, class methods, and instances.
+OpenAI owns its API URLs, defaults, configuration, HTTP requests, and response handling.
+Gemini has its own configuration, requests, and response handling; provider capabilities are implemented separately.
+
+Existing `AiLite.new`, `AiLite.chat`, and the other top-level methods continue to
+forward to OpenAI, sharing the same configuration and cached client. They emit a
+deprecation warning to stderr once per legacy entry point per process. They will
+remain available throughout v1.x and will be removed in v2.0.
+
+```ruby
+# Before
+AiLite.configure { |config| config.api_key = ENV["OPENAI_API_KEY"] }
+ai = AiLite.new
+
+# After
+AiLite::OpenAI.configure { |config| config.api_key = ENV["OPENAI_API_KEY"] }
+ai = AiLite::OpenAI.new
+# Class methods work too: AiLite::OpenAI.chat("Hello")
+```
+
+`AiLite.new` returns an `AiLite::OpenAI` instance. Compatibility covers documented
+construction, configuration, utility methods, and constants; subclassing the legacy
+`AiLite` class or relying on its exact instance class is not supported. Migrate such
+code to `AiLite::OpenAI`.
+
+Existing utility calls keep their methods and result envelopes. Legacy
+constants such as `AiLite::DEFAULT_MODEL` and `AiLite::Configuration` remain
+aliases for their OpenAI counterparts. The gem version stays at `AiLite::VERSION`.
+
 ## Chat
 
 ```ruby
@@ -147,6 +473,51 @@ puts follow_up["content"]
 
 Passing `previous_response_id` through `options` remains supported for backward compatibility.
 
+### Streaming Chat
+
+Use `chat_stream` to receive text as it arrives. It accepts the same keywords as
+`chat`, requires a block, and returns the usual result envelope when the stream
+finishes.
+
+```ruby
+ai = AiLite::OpenAI.new
+
+result = ai.chat_stream("Explain Ruby blocks in three sentences.") do |text|
+  print text
+  $stdout.flush
+end
+puts
+
+warn result["error"] if result["error"]
+# result["content"] contains the final answer.
+# result["response_id"] can be passed as previous_response_id on the next call.
+```
+
+Class-level usage is also supported:
+
+```ruby
+AiLite::OpenAI.chat_stream("Say hello") { |text| print text }
+```
+
+The block receives text strings, which are not necessarily whole words or tokens.
+JSON-looking final output is parsed in the returned `content`, just like `chat`;
+the block still receives the original text fragments. With `debug: true`, `raw`
+contains the terminal response object (or the available error/last event on failure),
+not a history of every streaming event. Tool arguments, reasoning, and refusal
+events are not yielded as text; the terminal response retains these outputs in
+`raw` when debugging. See the [OpenAI streaming event reference](https://developers.openai.com/api/reference/resources/responses/streaming-events).
+
+Always check `result["error"]`: failed, incomplete, malformed, or disconnected
+streams return an error, retaining text already received when available. An HTTP
+status of `200` alone does not mean generation completed successfully. Exceptions
+raised by your block propagate to the caller; calling without a block raises
+`ArgumentError` before making a request.
+
+Streaming runs in the calling thread and creates no worker threads. In Rails,
+forwarding chunks to a browser still requires an appropriate streaming response
+or messaging mechanism in the application. The configured read timeout applies
+to individual network reads, not to the total generation duration.
+
 ## Moderation
 
 Use `moderate` to classify user-submitted text or images for potentially harmful content before saving, publishing, or sending it into another AI call.
@@ -508,9 +879,75 @@ result["content"]  # transcript text
 result["raw"]      # full response body when available
 ```
 
+## Model Availability
+
+These helpers are implemented inside the OpenAI provider. Instance and class-level
+calls are supported; class-level network calls use the configured OpenAI client.
+
+```ruby
+ai = AiLite::OpenAI.new
+
+result = ai.available_models
+if result["error"]
+  warn result["error"]
+else
+  puts result["content"] # Array of exact model IDs
+end
+
+ai.model_available?("gpt-5.5") # true, false, or nil if the lookup failed
+AiLite::OpenAI.available_models(debug: true) # raw includes the full model list
+```
+
+`available_models` makes one authenticated `GET /v1/models` request and returns
+the standard envelope. Empty model lists are valid. `model_available?` makes a
+fresh list request and compares the exact ID, without prefix or alias matching.
+It returns `nil` on a lookup error; use `available_models` or
+`check_configured_models` when you need the error details. Empty or non-string
+IDs raise `ArgumentError`. As with other network methods, constructing a client
+without an API key raises `ArgumentError`.
+
+Inspect configured models locally:
+
+```ruby
+ai.configured_models
+# => { "chat" => "gpt-5.5", "moderation" => "omni-moderation-latest",
+#      "embedding" => "text-embedding-3-small", "image" => "gpt-image-2",
+#      "speech" => "gpt-4o-mini-tts", "transcription" => "gpt-transcribe" }
+
+AiLite::OpenAI.configured_models # No API key or network request required
+```
+
+`configured_models` returns a plain hash of usage names to model IDs. An instance
+reports its own settings, including constructor overrides; the class method
+reports the current provider configuration. Neither includes credentials.
+
+Check all configured models with a single list request:
+
+```ruby
+result = ai.check_configured_models
+result["content"]["chat"]
+# => { "model" => "gpt-5.5", "usage" => "chat",
+#      "available" => true, "error" => nil } # if listed for this key
+
+warn result["error"] if result["error"]
+```
+
+Each usage has a report entry. A successful lookup returns `available: true` or
+`false`; lookup failures return `available: nil`, an entry-level error, and the
+same error in the outer envelope. `debug: true` includes the original list or
+error response in `raw`. Network checks use the client's configured timeout and
+do not cache results or run automatically during initialization.
+
+**These are model-list availability checks only.** They do not run chat, image,
+speech, embedding, moderation, or transcription generation requests and create
+no generated output. A listed model does not guarantee endpoint compatibility,
+sufficient quota, or permission for every operation. See the
+[OpenAI List models reference](https://developers.openai.com/api/reference/resources/models/methods/list).
+
 ## Return Shape
 
-Methods return a hash envelope.
+Generation methods, `available_models`, and `check_configured_models` return a hash envelope.
+`configured_models` returns a plain hash; `model_available?` returns `true`, `false`, or `nil`.
 
 Text output:
 
@@ -567,5 +1004,5 @@ result = ai.chat("Say hello", debug: true)
 Run the test suite:
 
 ```sh
-ruby -Ilib:test test/ai_lite_test.rb
+ruby -Ilib:test test/run.rb
 ```

data/lib/ai_lite/gemini/chat.rb

@@ -0,0 +1,78 @@
+class AiLite
+  class Gemini
+    module Chat
+      def chat(message, model: nil, instructions: nil, previous_response_id: nil, max_output_tokens: nil, debug: false, options: {})
+        response = nil
+        raw = nil
+        response_id = nil
+        payload = chat_payload(message, model: model, instructions: instructions,
+                               previous_response_id: previous_response_id,
+                               max_output_tokens: max_output_tokens, options: options)
+        response = post_interaction(payload)
+        raw = response.body
+        raw = JSON.parse(raw)
+        raise "Invalid Gemini response: expected an object" unless raw.is_a?(Hash)
+
+        response_id = raw["id"]
+        unless response.code.to_i.between?(200, 299)
+          return result_envelope(status: response.code.to_i, error: error_message(raw),
+                                 response_id: response_id, raw: raw, debug: debug)
+        end
+
+        error = if raw["error"]
+                  error_message(raw)
+                elsif raw["status"] != "completed"
+                  "Gemini interaction #{raw['status'] || 'has no status'}; inspect raw with debug: true"
+                end
+        steps = raw["steps"]
+        raise "Invalid Gemini response: expected steps" unless steps.is_a?(Array) || error
+
+        text = Array(steps).flat_map do |step|
+          next [] unless step.is_a?(Hash) && step["type"] == "model_output"
+
+          Array(step["content"]).map do |part|
+            part["text"] if part.is_a?(Hash) && part["type"] == "text" && part["text"].is_a?(String)
+          end.compact
+        end.join.strip
+        content = if text.empty?
+                    nil
+                  else
+                    begin
+                      JSON.parse(text)
+                    rescue JSON::ParserError
+                      text
+                    end
+                  end
+        result_envelope(status: response.code.to_i, content: content, error: error,
+                        response_id: response_id, raw: raw, debug: debug)
+      rescue StandardError => e
+        result_envelope(status: response ? response.code.to_i : "unknown", error: e.message,
+                        response_id: response_id, raw: raw, debug: debug)
+      end
+      private
+
+      def chat_payload(message, model:, instructions:, previous_response_id:, max_output_tokens:, options:, stream: false)
+        payload = options.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+        if (!stream && payload["stream"]) || payload["background"]
+          raise ArgumentError, "Use chat_stream for streaming; background execution is not supported"
+        end
+        unless message.is_a?(String) || message.is_a?(Hash) || message.is_a?(Array)
+          raise ArgumentError, "message must be a string, a Gemini content hash, or an array of Gemini content/steps"
+        end
+        generation = payload.fetch("generation_config", {})
+        raise ArgumentError, "generation_config must be a hash" unless generation.is_a?(Hash)
+
+        generation = generation.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+        generation["max_output_tokens"] = max_output_tokens || generation["max_output_tokens"] || self.max_output_tokens
+        payload.merge!("model" => model || self.model, "input" => message, "generation_config" => generation)
+        payload["system_instruction"] = instructions if instructions
+        payload["previous_interaction_id"] = previous_response_id if previous_response_id
+        payload["stream"] = true if stream
+        payload
+      end
+    end
+
+    include Chat
+    private_constant :Chat
+  end
+end