## v0.3.0 (2026-08-11) ### Changed - **Embedding task vocabularies now belong to each provider.** There was a single normalized set of eight atoms translated per provider, plus a `:task_map` to retarget the strings and a verbatim-string escape hatch. That model does not survive contact with real endpoints: Gemini's `taskType` is a closed enum of eight, Jina v5 has four task names plus a separate `prompt_name`, and OpenAI has no task field at all. Translating between them meant either dropping distinctions a model makes or inventing ones it does not - and the built-in map was already wrong, mapping `:retrieval_document` to Jina v3's `"retrieval.passage"`, which v5 removed. Each provider now declares its own atoms and rejects anything outside them. `ExAgent.embedding_tasks/1` lists them, backed by a new optional `c:ExAgent.Provider.embedding_tasks/1` callback. **Removed** from `ExAgent.Embeddings`: `tasks/0`, `valid_task?/1`, the `task_input` type, the `:task_map` option, and verbatim string tasks. A string is now rejected everywhere - an endpoint that does not recognize a task string answers 200 and leaves quietly wrong vectors in an index, so there is no safe version of "send it and hope". Gemini's own atoms are unchanged, so Gemini callers are unaffected. - **`ExAgent.Providers.OpenAICompatible` no longer supports embeddings.** "Any endpoint speaking the OpenAI dialect" cannot have a task vocabulary, which is exactly what the removed `:task_map` was trying to paper over. the `OpenAICompatibleEmbedService` module is gone; the provider is chat-only. Use `ExAgent.Providers.JinaV5`, or a provider of your own, for embeddings against a self-hosted model. ### Fixed Found in a pre-release audit of the code added for this version. - **`ExAgent.Reranking.above/2` kept unscored results.** In Elixir's term ordering every atom sorts above every number, so `nil >= 0.5` is `true` and a result with no score survived any relevance floor. `above/2` now requires a numeric score, and the reranker service rejects the whole response if a result has no numeric `relevance_score`, so the situation cannot arise from a server that omits one. - **`Reranking.take/2` returned `nil` for an out-of-range index**, which would put the string "nil" into a prompt. It now raises, naming the mismatch, and the service rejects a response whose indexes fall outside the documents that were sent. - **A bad `:max_history` or `:max_tool_iterations` crashed the agent mid-turn.** `max_history: 0` was accepted by `start_link/1` and then raised a `FunctionClauseError` at the end of the first turn, pointing at the wrong line entirely. Both are validated when the agent starts. - **`MapReduce` reported `{:error, :all_sections_failed}` with no reason.** The failures now travel with it, since "everything failed" alone cannot be debugged. - **`Consensus` reported `{:error, :no_answers}` when nobody had been asked.** An empty `:voters` list or a non-positive `:samples` is now `{:error, :no_voters}`, distinct from every voter having been asked and failed, which returns the failures alongside. - `MapReduce` and `Consensus` accumulated results with `++` per item, which is quadratic in the number of sections or voters. They prepend and reverse once. ### Changed - **Pattern API is uniform.** Every workflow entry point is now `run/2` or `run/3`, and every builder that hands tools to an agent is `tools/1`. Three conventions had grown up side by side, and the `build_` prefix said nothing that the return type did not. | Before | Now | |---|---| | `Subagents.build_orchestrator_tools/1` | `Subagents.tools/1` | | `Subagents.invoke_subagents_parallel/2` | `Subagents.run/2` | | `Handoff.build_handoff_tool/3` | `Handoff.tools/1` | | `Handoff.execute_handoff/2` | `Handoff.run/2` | | `Router.route/2` | `Router.run/2` | | `Skills.evaluate_skills/2` | `Skills.evaluate/2` | `Handoff.tools/1` now takes a list of `%{name:, agent:, description:}` specs and returns a list, matching `Subagents.tools/1` exactly, so building several handoff targets is one call. `ExAgent.route/2` and `ExAgent.handoff/2` are unchanged. - **The README is now a tutorial**, not a feature tour. Eleven steps from "ask one question" to a composed support pipeline, each a complete program you can paste into `iex -S mix`. Every block was executed against a live API before publishing, and the outputs shown are from real runs with a note that models vary. The step order is the teaching order: tool, then skill, then subagent, then handoff, followed by a table answering the question people actually have - *who answers the next message?* A subagent is a phone call you make while the customer waits; a handoff is passing the customer to a colleague. The handoff step now explains why `ExAgent.handoff/2` has to be called before talking to the target: it is what delivers the conversation, and without it the target agent is a stranger. Includes the before/after of what actually reaches the model, why the returned tuple is a proposal rather than a transfer, and why the async cast is not a race (Erlang orders messages between a pair of processes; measured 0 late arrivals in 200 runs) along with the case where that guarantee does not hold. - Em dashes removed from all documentation and source comments. ### Added - **Four workflow patterns**, filling the gaps against the commonly documented catalogue (Anthropic's prompt chaining / routing / parallelization / orchestrator-workers / evaluator-optimizer, plus the sequential-workflow and reflection patterns that show up in every 2026 survey). ExAgent already had routing, orchestrator-workers, peer transfer, progressive disclosure, and the ReAct-style tool loop; these are the rest: - **`ExAgent.Patterns.Chain`** - a fixed sequence of steps, each working on the last one's output. Steps are plain functions, so validation, parsing, and database lookups sit in the line beside the LLM calls; `Chain.llm/2` builds an LLM step. A step returning `{:halt, value}` stops the line *without* it being a failure, which is how you decline to spend the remaining calls - and where a human approval gate belongs. Errors carry the failing step's index. - **`ExAgent.Patterns.Reflection`** - the evaluator-optimizer loop: draft, critique, revise, until the critic accepts or `max_rounds` (default 3) runs out. Exhausting the ceiling returns **`{:max_rounds, result}`**, not `{:ok, result}`: the last draft is there, but using unreviewed work has to be a choice rather than something handed over as if a reviewer had passed it. An LLM critic can always find something to complain about, so the ceiling is the difference between a workflow and a runaway bill. - **`ExAgent.Patterns.MapReduce`** - parallelization by sectioning: split an oversized input, process the pieces concurrently, combine them with either a function or another model (`reduce: {target, prompt_builder}`). One failing section does not fail the run; the reducer sees what survived and `:failures` reports the rest, because a summary of 38 of 40 interviews is worth having but not worth mistaking for all 40. - **`ExAgent.Patterns.Consensus`** - parallelization by voting: ask several times (or several models) and go with the answer that recurs. `:agreement` is the winner's share, which is the actual product - a low number is the signal to escalate rather than proceed. Ties resolve to the earliest answer deterministically, which needs care because `Enum.frequencies/1` returns a map and a map has no insertion order to fall back on. All four accept either a provider struct (stateless, no process) or a running agent (remembers the conversation) wherever they take a target - previously `Router` took only agents and `Subagents` only provider structs, and neither could be handed the other. Deliberately **not** added: plan-and-execute, which needs an LLM-authored plan parsed into executable steps and is brittle in exactly the way the rest of this library tries not to be - compose it from `Chain` and `Subagents` instead; and blackboard/swarm topologies, which the production write-ups consistently report losing to hierarchical and graph shapes. ### Changed - The README's pattern section is now a **guide to choosing one**, not a feature list: analogies for all eight, a table keyed on when to reach for each, and worked comparisons of the pairs people conflate - Handoff vs Subagents (a lookup versus a transfer, settled by "who is the user talking to now?"), Skills vs Subagents (continuity versus isolation), and Reflection vs Consensus (sloppy work versus wrong work). - **Reranking.** `ExAgent.rerank/4` and `ExAgent.rerank_with/4`, backed by a new optional `c:ExAgent.Provider.rerank/4` callback, returning an `ExAgent.Reranking` struct. Retrieval's second stage: embeddings compare independently computed vectors, which is what makes searching a corpus feasible, while a cross-encoder reads the query and one document together - more accurate, and far too slow to run over everything. `:index` is the contract, pointing back into the list you passed, so results map onto your own records without the server echoing text back. `ExAgent.Reranking.take/2` reorders a list; `above/2` applies a relevance floor, because ranking always returns *something* - the best of an irrelevant set still sorts first, and a floor is how you decline to answer. Scores are model-scoped: higher is more relevant and that is the only guarantee. Providers without a reranking endpoint return `{:error, %ExAgent.Error{type: :unsupported}}`. Emits `[:ex_agent, :rerank, :start | :stop | :exception]` telemetry. - **`ExAgent.Providers.JinaRerankerM0`** - a reranking-only provider for a self-hosted `jina-reranker-m0` server. `chat/3` returns `:unsupported`, and there is no `embed/3`: a reranker scores query/document *pairs* and has no single-text vector to give. `:base_url` is required and takes bearer auth plus arbitrary `:headers`, so Modal's proxy auth works. Empty document lists, non-string documents, batches over 512, a blank query, a non-positive `:top_n`, and unrecognized options are all rejected before the request - the server rejects unknown body fields outright, so a typo has to be caught client-side or it comes back as a validation blob. The wire contract - `POST {base_url}/v1/rerank` with `query`/`documents`/`top_n`/ `return_documents`, answering `results` with `relevance_score` and `document.text` - was verified against a live deployment. `return_documents` defaults to `true` there and `false` here, since `:index` already identifies each document. This is **not** the shape of Jina's hosted `api.jina.ai/v1/rerank`, whose `documents` take `{"text": ...}` / `{"image": ...}` objects. - **`ExAgent.Providers.JinaV5`** - an embeddings-only provider for a self-hosted Jina embeddings v5 server, with v5's own tasks: `:retrieval`, `:text_matching`, `:clustering`, `:classification`. v5 moved the query/document distinction *out* of the task and into a separate `prompt_name`, which is why the module is named for the version: v3 and v4 spelled the same thing as a single `"retrieval.query"` / `"retrieval.passage"` task, so one module covering both would have to lie about one of them. `prompt_name` is required for `:retrieval` and rejected for the other tasks; Matryoshka truncation is validated against the trained widths (32, 64, 128, 256, 512, 768, 1024); batches are capped at 512 inputs. All three are rules the server enforces, checked client-side so the failure names the fix instead of arriving as a 400. The server owns normalization, so vectors are returned untouched - `args: [normalize: false]` really does give you a non-unit vector. `chat/3` returns `{:error, %ExAgent.Error{type: :unsupported}}` pointing at a chat provider. `:base_url` is required and takes bearer auth plus arbitrary `:headers`, so Modal's proxy auth works. The wire contract - `POST {base_url}/embed` with `texts`/`task`/`prompt_name`/ `dimensions`/`normalize`, answering `embeddings` - was verified against a live deployment, not inferred from a model card. It is **not** the shape of Jina's hosted `api.jina.ai` service, which speaks an OpenAI-style `/v1/embeddings`. - **`:args` on `embed/3`** - extra request-body parameters as a keyword list or map, for what this library does not model: ExAgent.embed(jina, chunks, task: :retrieval, args: [prompt_name: :document]) ExAgent.embed(openai, chunks, args: [encoding_format: "base64"]) Each provider validates keys **and** values against what its own endpoint accepts and rejects the rest, so `prompt_nane:` fails naming the accepted keys instead of being ignored by the server. Atoms are accepted where the endpoint wants one of a fixed set of strings. Gemini accepts no extra args and says so; OpenAI accepts `encoding_format` and `user`; Jina v5 accepts `prompt_name` and `normalize`, the only extra fields its server permits. - `ExAgent.Embeddings.normalize_args/1`, for providers implementing the same option. ### Fixed An end-to-end audit of the library found the following. Every one of them shipped with a green suite: the tests covered the shape of each code path but not the behaviour a user would observe. `test/ex_agent/regressions_test.exs` now covers each one. - **Streaming stole messages from the caller's mailbox.** `chat_stream/3` runs in the *calling* process, and the SSE transport used a bare `receive` that matched anything; `Req.parse_message/2` answering `:unknown` then discarded it. Streaming inside a LiveView or GenServer silently ate that process's own messages, and the matching `handle_info` simply never fired. The receive is now selective on the response ref. - **Gemini ignored `:max_tokens` entirely.** The option was merged under one key and read under another, so neither the provider setting nor a per-call override ever reached `generationConfig` and every response used the API default. Google's own `:max_output_tokens` spelling is accepted as an alias. - **A Gemini reasoning part was returned as the answer.** Only the first content part was read, and a `thought` part matched the text clause - so the model's scratchpad became `:content` and the real answer was discarded. Text split across parts was truncated to the first piece for the same reason. Reasoning now lands in `:thinking`, as it already did when streaming. - **Parallel tool calls were silently dropped.** Both dialects returned only the first call, so the model believed tools had run that never did. `c:ExAgent.Provider.chat/3` now answers `{:tool_calls, calls}` with every call; `{:tool_call, name, args}` is still accepted from providers written against the older contract. - **Tool call ids were fabricated.** The assistant message was rebuilt with `id = name`, discarding the id the API issued - so calling one tool twice in a turn produced two colliding ids. The provider's id is now carried through, and a tool result correlates back by it (Gemini correlates by function name, which travels alongside). - **A tool returning anything but a string crashed the turn.** `to_string/1` on a map raised `Protocol.UndefinedError`, killing the task and surfacing as an opaque `:server` error - for the most natural tool shape there is. Non-string results are now JSON encoded. - **A skill never deactivated.** Applying one overwrote the provider's `system_prompt` permanently, so the first activation repainted the agent for the rest of its life - a "SQL expert" answering jokes. Skills are re-evaluated every turn and now restore the agent's own prompt when they stop matching. - **One failing agent took down a whole Router run.** Only `{:exit, :timeout}` was handled, so any other crash raised a `CaseClauseError` in the caller, discarding the routes that had already answered. Both `Router` and `Subagents` now report a failure per route, named. A handoff result no longer falls through unmatched. - **`parse_response/2` raised on a message with no `"content"` key.** A bare refusal gave a `CaseClauseError` instead of a normalized `{:error, %ExAgent.Error{}}`. - **OpenAI could never reference an uploaded image.** Attachments over the inline ceiling were uploaded and then referenced as an `image_file` content part - which is the Assistants API's shape and which chat completions rejects outright. Verified against the live API: no file-id shape works for images there. Oversized images and image `file_refs` now return `{:error, %ExAgent.Error{type: :unsupported}}` with the fix in the message, instead of spending an upload on a request that would always fail. - **API keys were printed by `inspect/1`.** No provider redacted its credential, so every crash report, `dbg`, and Logger metadata dump leaked it. All three providers now derive `Inspect` excluding `:api_key`, `:req`, and (for `OpenAICompatible`) `:headers`, where gateway credentials live. - **Streaming with tools billed twice.** The tool loop ran non-streamed to completion and then *discarded the finished answer* to regenerate it as a stream - two full completions per streamed turn. Every turn is now streamed once, with tools run between turns; the consumer still sees exactly one terminal `:done` chunk. - **SSE multi-line `data:` fields were concatenated without a separator.** The spec joins them with a newline. JSON payloads survived either way; a plain-text stream did not. - Skills, subagents, and the streaming tool loop assumed every provider struct carries `:tools` and `:system_prompt`, reintroducing the `KeyError` already fixed on the chat path. All of them now populate a field only when the provider declares it. - `ExAgent.Agent.chat/3`'s `@spec` still promised `{:ok, Message.t()}` after the switch to `ExAgent.Response`. ### Changed - **`:max_tokens` and `:temperature` now default to `nil`** on every provider and are omitted from the request, so the model's own defaults apply. The previous `max_tokens: 512` truncated most real answers at `finish_reason: :length`, and `temperature: 0.6` broke models that reject the parameter outright (o-series, search-preview). **Set them explicitly if you relied on the old values.** Both now also accept an integer, where `temperature: 1` used to raise. - OpenAI embeddings reject a batch over 2048 inputs up front, naming the limit, rather than letting the API 400. ### Added - **`ExAgent.Telemetry`.** `[:ex_agent, :chat | :embed | :tool, :start | :stop | :exception]` events carrying duration, token counts, model, and - on failure - `:error_type` and `:retryable?`. A library that calls billed APIs has to be measurable; nothing is logged on your behalf. Adds a `:telemetry` dependency. - **`:max_history` on `start_agent/1`** and `ExAgent.Context.trim/2`. History was unbounded, so every turn resent the whole transcript until the model returned `:context_length`. Opt-in, because silently forgetting what a user said is the caller's decision. Leading system messages survive the window, and a tool result is never orphaned from the assistant message that requested it. - **`:max_tool_iterations` on `start_agent/1`**, replacing the hard-coded ceiling of 10. ### Added - **Provider roles.** `config :ex_agent, :roles, chat: {Module, opts}` maps a purpose to a provider, and `ExAgent.provider!(:chat)` returns an ordinary provider struct usable anywhere a hand-built one is - `start_agent/1`, `ExAgent.Provider.chat/3`, subagent specs, every pattern. Role names are arbitrary atoms. `start_agent(role: :vision)` is shorthand; `:role` and `:provider` are mutually exclusive. Purely additive: every existing entry point still takes a struct, unchanged. `ExAgent.chat_with/3`, `stream_with/3` and `embed_with/3` are stateless one-shot wrappers that bypass the agent GenServer. They do **not** run the tool loop - a tool-configured provider returns the raw `{:tool_call, name, args}`. Roles resolve once at application start and cache in `:persistent_term`, so lookups cost nothing on the request path; per-call overrides (`provider!/2`) build a fresh struct rather than writing to the cache. A module that is missing, lacks `new/1`, does not implement `ExAgent.Provider`, or whose `new/1` raises fails the boot with the role name in the message, so a missing credential crashes at deploy time instead of on the first request. Option values may be a zero-arity function or `{m, f, a}`, resolved once at boot, for vault-backed credentials. Note that this is the first thing in `lib/` to read `Application.get_env` - the library was otherwise configured entirely through explicit structs, and still can be. - **`ExAgent.Error`.** A normalized error struct returned by every provider operation, carrying `:type`, `:message`, `:status`, `:provider`, `:raw` and `:retryable?`. HTTP statuses are classified into one vocabulary (`:auth`, `:rate_limit`, `:context_length`, `:invalid_request`, `:not_found`, `:timeout`, `:server`, `:transport`, `:unsupported`), so retry logic is written once rather than per provider. `ExAgent.Error.from_result/2` does the classification for custom providers. The struct is also an exception, so it can be raised where no return value exists. - **URL file sources.** `files: [%{url: "https://..."}]` hands the URL straight to the provider - Gemini as `file_data.file_uri`, OpenAI as `image_url` / `file_url`. ExAgent never fetches the URL, so no bytes cross your application. - **Optional `:mime_type`.** Inferred from the file extension for `:path` and `:url` (query strings ignored) and from magic bytes for `:data` (PNG, JPEG, GIF, WebP, WAV, MP3, MP4/QuickTime/M4A, PDF). An explicit `:mime_type` still wins. When the type cannot be determined the call fails with an error naming `:mime_type` rather than guessing. - **`ExAgent.Source`.** Pure MIME-inference and modality helpers, with no provider knowledge. - **`ExAgent.Attachment`.** Attachments normalize into a struct carrying `:kind`, `:mime_type`, `:modality`, `:byte_size` and `:provider_opts` (video `:fps` / `:max_frames` are lifted into the latter). - **Modality gating.** The optional `c:ExAgent.Provider.supported_modalities/1` callback declares which attachment modalities a provider accepts (`:image`, `:document`, `:video`, `:audio`). `ExAgent.Provider.chat/3` and `stream/3` check every attachment against it before building a request. Providers that omit the callback are text-only, so an unsupported attachment fails loudly instead of being dropped. Every built-in provider takes a `:modalities` option, because modality support is a property of the *model*, not the vendor - `o1-mini` reads no images. Defaults are `[:text, :image, :document]` for OpenAI, those plus `:video` and `:audio` for Gemini, and `[:text]` for `OpenAICompatible` (one container serves one model). Narrowing makes the gate fire locally instead of letting the provider 400 later: OpenAI.new(api_key: key, model: "o1-mini", modalities: [:text]) ExAgent keeps no model-to-modality table on purpose: it would go stale silently, and whoever picked the model already knows. - **Embeddings.** `ExAgent.embed(provider, inputs, opts)` returns an `%ExAgent.Embeddings{}` carrying `vectors`, `model`, `provider`, `dimensions`, `task`, and `usage`. It takes a provider struct rather than an agent pid - embedding is stateless. Backed by a new optional `c:ExAgent.Provider.embed/3` callback; providers without an embeddings endpoint return `{:error, %ExAgent.Error{type: :unsupported}}`. One normalized task vocabulary (`:retrieval_query`, `:retrieval_document`, `:similarity`, `:classification`, `:clustering`, `:question_answering`, `:fact_verification`, `:code_query`) is translated per provider: `gemini-embedding-001` takes a `taskType` enum, `gemini-embedding-2` has no such field and takes a text prefix (with an optional `:title` per input), OpenAI has no task support and **errors** rather than dropping it, and OpenAI-compatible endpoints take a `task` body field whose strings are overridable via `:task_map`. Notable correctness details: `:model` is always resolved to an embedding model and never the provider's chat model; Gemini requests always use `batchEmbedContents` with one `Content` per input, because a flat list returns a single *aggregated* vector on `gemini-embedding-2`; OpenAI responses are re-sorted by `index`, which the API does not guarantee; and truncated `gemini-embedding-001` vectors are L2-normalized client-side, which that model does not do for you. An unknown Gemini embedding model errors rather than guessing a family - pass `:embedding_family` to adopt a newer one. On `OpenAICompatible` only, `:task` also accepts a **raw string**, sent verbatim with no translation and no validation - a self-hosted endpoint serves whatever model you deployed, and those vocabularies change between versions (Jina v3's `"retrieval.passage"` became a `"retrieval"` task plus a prompt in v5, which also added `"text-matching"`). Gemini and OpenAI take atoms only: `taskType` is a closed enum and OpenAI has no task field, so a string there is a typo far more often than a new value and is rejected naming the valid atoms. Atoms stay validated everywhere, and the result carries back exactly what was passed. `ExAgent.Embeddings` also exposes `tasks/0`, `valid_task?/1`, `l2_normalize/1`, and `cosine_similarity/2`. **Persist `model`, `dimensions`, and `task` alongside every vector** - embedding spaces are model-scoped and mixing them degrades retrieval silently. - **`ExAgent.Providers.OpenAICompatible`.** One provider for any endpoint speaking the OpenAI chat-completions dialect - self-hosted vLLM (including behind Modal), OpenRouter, Together, Groq. Takes arbitrary `:headers` (so Modal's `Modal-Key` / `Modal-Secret` proxy auth works, where `ExAgent.Providers.OpenAI` had no way to set them), with `:api_key` as sugar for a bearer header that explicit headers override. `:modalities` is declared per deployment and defaults to `[:text]`. Media is carried in `image_url` / `video_url` / `audio_url` content parts whose URL may be a `data:` URI. There is no Files API, so an attachment past `:max_inline_bytes` (32 MB default) returns `{:error, %ExAgent.Error{type: :unsupported}}` rather than being truncated. `probe/1` checks that the endpoint actually serves the configured model. - **Shared OpenAI dialect helper** (`lib/ex_agent/services/openai_dialect.ex`, internal). Holds the request/response shaping shared by every dialect speaker, so the OpenAI and OpenAI-compatible services no longer duplicate it. - **Adaptive inline-vs-upload.** Both services now choose how each attachment is delivered rather than leaving it to the caller: URLs and existing `FileRef`s are referenced as-is, bytes under the inline ceiling are base64-encoded, and anything larger is uploaded through the provider's Files API and referenced. Gemini inlines up to 20 MB (50 MB for `application/pdf`) and references by URI; OpenAI inlines up to 20 MB and references by `file_id`. Uploads reuse the provider's `Req` client and are deduplicated through `ExAgent.UploadCache`; `upload_cache: false` on the provider opts out. - **Video options.** `:fps` maps to Gemini's `video_metadata`, and string-keyed `:provider_opts` entries are merged into the media part verbatim. The `OpenAICompatible` `video_url` content part and `:fps` passthrough are verified against a live vLLM (Qwen3-VL) deployment, from both an http URL and a base64 data URI. - **Gemini upload polling is configurable.** `:poll_interval_ms` and `:max_poll_attempts` are now options, defaulting to `2_000` / `60` (~2 minutes, up from ~10 seconds) - large files and video need it. - **`ExAgent.UploadCache`.** An ETS-backed cache that lets the same bytes reuse an existing `ExAgent.FileRef` instead of re-uploading. Entries are keyed by `{scope, sha256(bytes)}` where the scope digests the provider module, base URL, and API key - so two accounts never share a file reference, and the key itself is never stored. An expired `FileRef` is treated as a miss and evicted. Added to the supervision tree ahead of the agent supervisor; `clear/0` empties it. ### Fixed - **A failed turn poisoned the agent.** The user message was committed to context even when the turn failed, so a message the provider had already refused - a rejected attachment, say - was resent on every later turn and every one of them failed. "Fails loudly" became "fails forever". A failed turn now leaves no trace, which also stops a retry after a transient 429 from duplicating the question in history. - **`chat_stream/3` raised on a rejected attachment.** The modality gate raises inside `ExAgent.Provider.stream/3` because a lazy enumerable has nowhere to carry an error at construction time, and that escaped to the consumer - contradicting the documented promise that streaming never raises, and leaving the agent stuck in `:processing`. It now arrives as the terminal `:done` chunk like every other stream failure, and the agent is released. - **The agent required a `:tools` field on every provider struct.** `run_tool_loop/3` and the streaming path both did `%{provider | tools: ...}`, so a provider without tool support crashed with a `KeyError` that surfaced as an opaque `{:error, %Error{type: :server}}`. The field is now populated only when the provider declares one. - **`ExAgent.FileRef` rejected custom providers.** `:provider` was validated against a hardcoded `[:openai, :gemini]`, so a third-party provider implementing the optional `c:ExAgent.Provider.upload/4` callback could not build the reference its own callback has to return. The built-in services construct `%FileRef{}` structs directly and never called `new/1`, so the closed list protected nothing - it only walled out everyone else. Any atom is now accepted, and a reference need only carry a `:file_id` or a `:file_uri`; OpenAI's and Gemini's specific field requirements still apply to them, since their services pattern-match on those fields. - **`OpenAICompatible` shaped documents as images.** `:document` was declarable through `:modalities` but `format_attachment/1` fell through to `image_url`, so a PDF was sent as an image part and the gateway either rejected it or read nothing. Documents now use the dialect's `file` part - `file_data` for bytes (with the required `filename`) and `file_url` for a URL - which is what a gateway fronting a document-reading model expects. The moduledoc previously claimed documents were unsupported; a model behind OpenRouter or Modal may well read them, so it is a deployment property like every other modality. - **Gemini streaming produced no text at all.** Gemini terminates SSE events with CRLF, but `ExAgent.SSE.take_events/1` split only on `"\n\n"`. A CRLF stream contains no such boundary, so every frame stayed buffered, no frame was ever decoded, and the stream ended with its terminal chunk and empty content - silently, with no error. Framing now accepts CRLF, LF, and bare CR per the SSE spec, on both event and line boundaries. Found by running against the live API; every mocked test hand-wrote LF bodies. - **Streams ended with two `:done` chunks whenever the model reported a finish reason.** Provider mappers turn a finish-reason frame into a `:done` chunk and the transport appends the terminal one. Since real responses always finish, the documented "exactly one `:done` chunk" invariant was broken in practice for every provider. The transport now consumes the mapper's `:done` for its finish reason and emits the single terminal chunk itself. - **A tool returning a bare value crashed the tool loop.** `ExAgent.Tool`'s `:function` is typed `(map() -> any())` and its own doctest returns a bare `:ok`, but the agent matched only `{:ok, _}` / `{:error, _}` / `{:handoff, _, _}` - anything else raised `CaseClauseError` inside the supervised task, surfacing as an opaque `:server` error. An unwrapped return is now taken as the result. - **Documented that OpenAI's `:web_search` needs `temperature: nil`.** `web_search_options` is only accepted by a `*-search-preview` model, and those reject `temperature` - so the provider's own `temperature: 0.6` default made the shipped example return HTTP 400. ExAgent still forwards `temperature` as configured rather than dropping it when a model objects; a silently ignored sampling parameter is worse than a 400 naming the field. - **Retired Gemini default model.** `gemini-2.0-flash` is no longer served and returns HTTP 429 with a zero free-tier quota rather than a clear 404. The default is now `gemini-3.6-flash`. Pass `:model` explicitly to pin a different one. - **A malformed attachment no longer crashes the agent.** `ExAgent.chat/3` and `ExAgent.chat_stream/3` matched on `{:ok, msg} = Message.new(...)`, so an unreadable path turned into a `MatchError` inside `handle_call` and took the agent process down. Both now return `{:error, %ExAgent.Error{type: :invalid_request}}`. - **Normalized stream chunks.** `ExAgent.chat_stream/3` and `ExAgent.Provider.stream/3` now yield `%ExAgent.Chunk{}` structs instead of bare strings, surfacing what streaming previously discarded: reasoning traces (`:thinking_delta`), tool-call deltas, token usage, and finish reasons. Every stream ends with exactly one `:done` chunk. - **`ExAgent.collect/1`.** Folds a chunk stream into the same `ExAgent.Response` that `chat/3` returns, reassembling fragmented tool-call arguments by index, so streaming and non-streaming share one downstream code path. - **`ExAgent.SSE`.** Server-Sent Events framing extracted from the streaming transport and made public, with `decode/1` returning complete frames plus the unconsumed remainder. A frame split across TCP reads is reassembled correctly - now covered by a test that splits a body at every byte boundary. ### Removed (breaking) - **`ExAgent.Providers.DeepSeek`.** DeepSeek speaks the OpenAI chat-completions dialect, so `ExAgent.Providers.OpenAICompatible` covers it with no loss of capability: # before ExAgent.Providers.DeepSeek.new(api_key: key, model: "deepseek-reasoner") # after ExAgent.Providers.OpenAICompatible.new( base_url: "https://api.deepseek.com/v1", api_key: key, model: "deepseek-reasoner" ) Reasoning traces still arrive as `:thinking_delta` chunks - the `reasoning_content` field is handled by the shared dialect, not by the removed module. The built-in `:thinking` tool went with it; pick the reasoner model instead. ### Changed (breaking) - **`chat/3` returns `%ExAgent.Response{}`.** Previously `{:ok, %ExAgent.Message{}}`. The response carries `:content`, `:usage`, `:finish_reason`, `:tool_calls`, `:thinking`, and the `:message` appended to conversation history: # before {:ok, %ExAgent.Message{content: content}} = ExAgent.chat(agent, "Hi") # after {:ok, %ExAgent.Response{content: content}} = ExAgent.chat(agent, "Hi") # ...or response.message for the Message struct itself This cascades through the `c:ExAgent.Provider.chat/3` callback, so custom providers must return a `Response` - build one with `ExAgent.Response.new/2`. - **Streams yield `%ExAgent.Chunk{}` instead of `String.t()`.** # before agent |> ExAgent.chat_stream("Hi") |> Enum.each(&IO.write/1) # after agent |> ExAgent.chat_stream("Hi") |> Enum.each(fn %ExAgent.Chunk{type: :text_delta, text: text} -> IO.write(text) _chunk -> :ok end) # ...or collect it into a single response {:ok, response} = agent |> ExAgent.chat_stream("Hi") |> ExAgent.collect() - **`ExAgent.StreamError` is removed, and streaming never raises.** A non-200 response, a transport failure, a busy agent, and an idle timeout all arrive as a terminal `:done` chunk carrying an `ExAgent.Error`. Previously `chat_stream/3` raised *eagerly* for a busy agent but *lazily* for an HTTP error, forcing consumers to wrap both the call site and the consumption site in `try`. Partial output already emitted stays valid. - **A stream idling for 5 minutes now reports a timeout** instead of halting silently, which was indistinguishable from clean completion. - **DeepSeek attachments.** Previously `raise`d `ArgumentError` from inside the service (and the README claimed they were silently ignored - neither was right). Attaching a file to DeepSeek now returns `{:error, %ExAgent.Error{type: :unsupported}}` before the request is built. - **`:path` attachments are read lazily.** `Message.new/1` now records only the file's size; the bytes are read when the request is built. This keeps a large file out of conversation history, where it would otherwise be re-encoded on every turn. The behaviour change: a file deleted between attaching and sending now fails at send time rather than at attach time. - **Attachment element type.** `Message.attachments` now holds `%ExAgent.Attachment{}` structs rather than bare maps. Since a struct is a map, code matching on `%{data: data, mime_type: mime_type}` or `%{file_ref: %ExAgent.FileRef{}}` keeps working; code using `Map.keys/1`, exact-map patterns, or `Map.get/3` defaults on optional keys (a struct key is present-but-`nil`, so the default never applies) needs updating. - **Error shape.** All providers, services and upload services now return `{:error, %ExAgent.Error{}}` instead of `{:error, {status, body}}`. The original body is preserved in `:raw`, so the migration is mechanical: # before {:error, {status, body}} -> handle(status, body) # after {:error, %ExAgent.Error{status: status, raw: body}} -> handle(status, body) Replaced along with it: `{:error, {:unexpected_response, body}}` and `{:error, {:unexpected_parts, parts}}` are now `%ExAgent.Error{type: :server}` with the offending payload in `:raw`; `{:error, {:unsupported, :upload, module}}` is now `%ExAgent.Error{type: :unsupported}`; the Gemini upload atoms `:file_processing_timeout` and `:file_processing_failed` are now `%ExAgent.Error{type: :timeout}` and `%ExAgent.Error{type: :server}`; and `ExAgent.upload_file/4` no longer leaks a bare posix atom for an unreadable path. - **`ExAgent.Provider.stream/3`** raises `ExAgent.Error` with `type: :unsupported` instead of `ArgumentError` when a provider does not implement `stream/3`. ## v0.2.0 (2026-07-20) ### Added - **Streaming.** `ExAgent.chat_stream/3` (agent-level) and `ExAgent.Provider.stream/3` (provider-level) return a lazy `Stream` of text chunks. Tool-call turns are resolved non-streamed; only the final assistant turn is streamed. All three providers implement the optional `stream/3` callback. Raises `ExAgent.StreamError` on non-200 responses / when the agent is busy. ### Changed - **Providers are now a behaviour instead of protocols.** The `ExAgent.LlmProvider` and `ExAgent.FileUploader` protocols were removed and replaced by a single `ExAgent.Provider` behaviour (`chat/3` required, `upload/4` optional). Custom providers now declare `@behaviour ExAgent.Provider` and implement `chat/3` (and optionally `upload/4`) as public functions instead of using `defimpl`. - **Non-blocking agent.** `ExAgent.Agent` now runs the tool loop off the GenServer (via a supervised task), so an agent stays responsive to reads (`get_context`) and casts while a request is in flight. A concurrent `chat/3` on a busy agent now returns `{:error, :busy}` instead of serializing behind the mailbox. ## v0.1.0 (2026-03-30) First release!