ReqLLM 1.x Compatibility Policy

ReqLLM 1.x evolves without requiring applications or third-party providers to rewrite working integrations. Internal architecture may change substantially, but stable observable behavior follows semantic versioning.

This policy applies to the 1.x release line.

Contract classifications

Every supported surface is classified as stable, experimental, deprecated, or internal.

Stable

A surface is stable when it is documented without an experimental or deprecated label. Stable contracts may gain additive behavior in a minor release, but an incompatible removal, rename, default change, or semantic replacement waits for a major release.

Stable does not mean frozen. Internal implementation and private data may change when existing observable behavior remains compatible. A narrowly scoped bug fix may correct behavior that contradicts the documented contract or types, provided the change has regression evidence and does not introduce unrelated differences.

Experimental

A surface is experimental only when its module, function, option, event, or guide explicitly says so. Experimental contracts may change or be removed in a minor release, but changes must still be intentional, documented, and tested. New public behavior is not implicitly experimental.

Applications should isolate experimental use behind their own adapter. ReqLLM will prefer an additive migration path and warning when practical, especially when an experimental surface has meaningful adoption.

Deprecated

A deprecated contract remains functional while users migrate. A deprecation must provide:

• an actionable warning where runtime detection is practical;
• the supported replacement and a migration example;
• the release that introduced the deprecation;
• the earliest release in which removal may occur; and
• at least two minor releases of overlap before removal is considered.

Stable runtime APIs are not removed during V1 merely because the overlap window has elapsed. Their removal belongs to a major release. The window creates a usable V1 bridge before that release.

The versioned priv/deprecations.json ledger records every active deprecation and its owner, replacement, window, target, approved or unapproved V2 scope status, guide, and precise detector. Run mix req_llm.migration_audit to inventory mechanical V2 work without evaluating or rewriting application source.

Internal

A surface is internal only when it is hidden from public documentation or explicitly documented as internal. File paths, private functions, intermediate maps, and module organization are not contracts by themselves.

Visibility alone does not make an extension point internal. Documented provider callbacks, configuration, telemetry, and value shapes remain protected even when most applications use them indirectly.

Compatibility-protected contracts

The following categories are stable unless their documentation explicitly classifies a particular surface otherwise.

Public functions and inputs

• Documented facade and operation functions, their names, arities, bang variants, defaults, and return tuples.
• Accepted model forms, including "provider:model" strings, supported tuple forms, full plain-map model specs, and %LLMDB.Model{} values.
• Documented option names, types, precedence, and default behavior, including provider-specific escape hatches.
• The ability to use a full model specification without requiring LLMDB catalog membership when enough routing metadata is present.

Adding an opt-in function or option is compatible. Silently changing an existing default, precedence rule, or accepted input is not.

Results, values, and errors

• Success and error tuple shapes, normalized content, usage, warnings, finish reasons, provider metadata, and ordering.
• Public struct modules, keys, defaults, equality behavior, Map.from_struct/1 output, Inspect representation, and Jason encoding.
• Public error terms and fields plus the exception module and message raised by bang functions.

Richer information must use a computed projection, a new value, or an explicit opt-in return mode when adding fields would change an existing value's observable shape.

Streaming

• The StreamResponse.stream and StreamChunk contract, element order and meaning, and single-consumer behavior.
• Terminal success and failure delivery, cancellation, timeout semantics, metadata availability, and transport resource cleanup.
• Semantic parity between a buffered stream and the equivalent non-streaming operation where both surfaces support the same provider capability.

A richer event view may project from the existing stream. V1 does not replace the legacy stream with a second independently consumable source.

Provider extensions

• The documented ReqLLM.Provider callbacks and default implementations.
• Provider registration, :custom_providers, inline model specs, and documented request customization.
• Callback inputs, return forms, option precedence, and routing behavior relied upon by third-party provider modules.

ReqLLM may introduce narrower internal seams, but the current provider behavior remains available through V1. A first-party refactor must include conformance evidence that an external provider would continue to work.

Configuration and telemetry

• Documented application configuration, environment variables, per-request options, precedence, defaults, and credential-source behavior.
• Existing documented telemetry event names, metadata and measurement keys, value types, meanings, units, and redaction behavior.

New telemetry is additive. Existing events are not silently renamed or corrected in place when that would reinterpret a consumer's data. Provider-specific or detail events may use an experimental classification only when that status is explicit in their documentation.

Compatibility evidence

• Public scenario identifiers, fixture naming and lookup rules, replay/live behavior, semantic test tags, support-state meanings, and generated evidence schemas.
• Existing fixture request contracts outside the exact behavior being fixed.

Recorded provider responses may be refreshed when a provider changes, but the pull request must distinguish provider drift from a library regression. Internal refactoring alone must not churn fixture payloads or support claims.

Elixir and OTP support

The Elixir requirement in mix.exs and the versions exercised by GitHub CI are the source of truth for the supported toolchain. Toolchain support is managed independently from the ReqLLM API major version because language, OTP, security, dependency, and CI constraints have their own lifecycle.

Raising the minimum Elixir or OTP version does not by itself require ReqLLM 2.0, but it is never treated as incidental maintenance. Except for an urgent security or ecosystem incompatibility, ReqLLM will:

1. announce the intended minimum-version change at least one minor release in advance;
2. explain the EOL, security, dependency, or maintenance evidence behind it;
3. keep the old version in CI during the notice window;
4. include a concrete upgrade path in release notes; and
5. change package metadata, CI coverage, and documentation together.

Supporting an additional Elixir or OTP release is compatible when the existing matrix remains green.

ReqLLM and Jido ownership

ReqLLM owns one model interaction. It resolves and validates the selected model, translates options, performs one request or stream, and normalizes provider data into responses, tool calls, usage, warnings, and errors. It may provide pure helpers that let a host append matched tool calls and results to a context.

Jido or another application host owns orchestration across model interactions:

• deciding whether and where a tool runs;
• approvals and tool-execution policy;
• appending application results and deciding whether to call a model again;
• loop termination, step limits, model selection, and cross-call retry policy;
• memory, checkpoints, resumption, delegation, and durable execution; and
• sandbox creation, permissions, lifecycle, and cleanup.

Concrete boundaries include:

ReqLLM core does not add an agent loop, approval engine, memory store, workflow checkpoint, delegation runtime, or Jido dependency. Optional integration code may adapt stable ReqLLM values for Jido without moving those responsibilities across the boundary.

Evaluating a V1 change

Before merging a V1 change, identify every affected contract above and prove that behavior outside the accepted scope remains compatible. Exact request, serialization, error, exception, telemetry, and fixture assertions are required when those contracts are touched.

If the valuable implementation cannot satisfy the V1 compatibility gate, narrow it to an additive bridge or move it to the V2 roadmap. Compatibility uncertainty is a reason to pause, not permission to guess.