dot-inference 2.2.0__tar.gz → 3.1.0__tar.gz

{dot_inference-2.2.0 → dot_inference-3.1.0}/.gitlab-ci.yml

@@ -83,36 +83,43 @@ test:
         path: coverage.xml
 
 # The offline suite stubs SDK responses, so it cannot notice the real API or
-# SDK changing shape. This job calls the real Mistral API on Mistral Small 4
-# with tiny prompts (~$0.0005 a run), only when something it guards changed;
-# otherwise it stays available as a manual job.
+# SDK changing shape, nor a provider ignoring a strict schema. This job runs
+# every test marked live: the Mistral smoke tests (tests/test_mistral_live.py)
+# and the constrained-decoding tests on Mistral, GPT and Claude through
+# OpenRouter (tests/test_constrained_live.py), with cheap models and short
+# prompts. It runs only when something it guards changed; otherwise it stays
+# available as a manual job.
 #
-# Needs MISTRAL_API_KEY under Settings > CI/CD > Variables: masked, NOT
-# protected (MR pipelines from unprotected branches would not see it). Use a
-# dedicated key from a workspace with a low spending cap — any developer can
-# read an unprotected variable from their branch.
-test_live_mistral:
+# Needs MISTRAL_API_KEY and OPENROUTER_API_KEY under Settings > CI/CD >
+# Variables: masked, NOT protected (MR pipelines from unprotected branches
+# would not see them). Use dedicated keys with a low spending cap — any
+# developer can read an unprotected variable from their branch.
+test_live:
   stage: test
   before_script:
     - uv sync --all-extras --all-groups
   script:
     - |
-      if [ -z "$MISTRAL_API_KEY" ]; then
-        echo "MISTRAL_API_KEY is not set. Add it under Settings > CI/CD > Variables"
-        echo "(masked, not protected) — see the comment on this job."
-        exit 1
-      fi
+      for key in MISTRAL_API_KEY OPENROUTER_API_KEY; do
+        if [ -z "$(printenv "$key")" ]; then
+          echo "$key is not set. Add it under Settings > CI/CD > Variables"
+          echo "(masked, not protected) — see the comment on this job."
+          exit 1
+        fi
+      done
     - uv run pytest -m live -v
   retry:
     max: 1
     when: script_failure
   rules:
-    # Fork MRs never get the project's key: a maintainer runs the pipeline
+    # Fork MRs never get the project's keys: a maintainer runs the pipeline
     # for the MR in the parent project instead.
     - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_SOURCE_PROJECT_PATH != $CI_MERGE_REQUEST_PROJECT_PATH
       when: never
     - changes:
         - src/dot_inference/_mistral_compat.py
+        - src/dot_inference/_openai_compat.py
+        - src/dot_inference/_strict_schema.py
         - src/dot_inference/_client.py
         - src/dot_inference/_types.py
         - src/dot_inference/_cost_tracker.py
@@ -120,6 +127,7 @@ test_live_mistral:
         - src/dot_inference/_llm_registry.py
         - src/dot_inference/models.yaml
         - tests/test_mistral_live.py
+        - tests/test_constrained_live.py
         # SDK upgrades are the main source of silent breakage.
         - pyproject.toml
         - uv.lock

{dot_inference-2.2.0 → dot_inference-3.1.0}/.pre-commit-config.yaml

@@ -1,6 +1,6 @@
-# Verbatim legal texts: the AGPL and the DCO both forbid modification,
-# so no hook may normalise their whitespace or line endings.
-exclude: '^(LICENSE\.md|DCO)$'
+# Verbatim legal text (MIT licence): no hook may normalise its whitespace
+# or line endings.
+exclude: '^LICENSE\.md$'
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks

{dot_inference-2.2.0 → dot_inference-3.1.0}/AUTHORS.md

@@ -7,6 +7,7 @@ here does not confer any ownership of, or rights in, the project.
 ## Kannon For Deep Tech
 
 - Adrien Marjollet
+- Charles Capon
 - Clément Olivier
 - Jean Fechter
 - Louis Le Tarnec

{dot_inference-2.2.0 → dot_inference-3.1.0}/CHANGELOG.md

@@ -7,6 +7,88 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-10-29
+
+### Added
+
+- Image input: `image_part()` builds an image content part from an `http(s)://`
+  or `data:` URL, a local file path or raw bytes (inlined as base64, media type
+  guessed from the extension or the bytes), with an optional `detail`;
+  `text_part()` builds the text part next to it. `has_images()` tells whether
+  messages carry any. Both the OpenAI-compatible and the Mistral clients send
+  the parts as-is.
+- Registry: `supports_vision` (default `false`, can be overridden per
+  provider). Sending an image to a model registered without it raises
+  `ValueError` before any request; unregistered models are not checked. Set to
+  `true` for the GPT-5/GPT-6, Gemini, Gemma 4, Mistral, Qwen 3.5 and Claude
+  entries.
+- Request summaries in warning logs count each message's images, never their
+  content.
+- `max_tokens` per call on `call`, `stream`, `stream_text` and `call_sync`, and
+  as an override on `get_llm_client`.
+- `list_served_models(base_url)`: the model ids an OpenAI-compatible server
+  reports via `GET /models`, for any model, registered or not.
+- `reasoning_tokens` on `LLMResponse` and `StreamUsage`, read from
+  `usage.completion_tokens_details.reasoning_tokens` (or `usage.reasoning_tokens`).
+- `ProviderModelConfig` is now exported, so `register_model` can declare
+  provider routes.
+- `ToolDef.strict`: when true, the tool is sent with `"strict": true` so the
+  server constrains its arguments to the schema. Defaults to `false`, and the
+  field is omitted then.
+- `tool_choice` also accepts the name of one of the provided tools, to force
+  that tool. An unknown name raises `ValueError` before any request.
+- `extra_body` per call on `call`, `stream`, `stream_text` and `call_sync`:
+  provider-specific request fields (e.g. vLLM's `ignore_eos`), merged over the
+  client's own. The Mistral client rejects it.
+- `max_attempts` on `OpenAICompatClient` and `MistralClient`, and as an override
+  on `get_llm_client`: total attempts per request (1 = no retry). Defaults are
+  unchanged (4 and 2).
+- `ToolDef.parameters` also takes a Pydantic model. Its schema is sent; with
+  `strict=True` it is rewritten to OpenAI's strict rules for every provider
+  (OpenAI and Claude reject a strict tool whose objects are not closed).
+  `ToolDef.parse_arguments()` validates a call's `arguments` into the model
+  (`None` for a dict schema).
+- `to_strict_schema()` is exported, to rewrite a hand-written schema to
+  OpenAI's strict rules.
+
+### Fixed
+
+- OpenAI-compatible clients no longer stack the OpenAI SDK's own retries (2 by
+  default) on top of theirs: a failing request is now sent at most 4 times by
+  default, not up to 12. A client passed in through `client=` keeps its own
+  settings.
+- Structured output on OpenAI models (the `openai` provider, or `openai/...`
+  on OpenRouter, gpt-oss aside): a Pydantic `response_format` with a nested
+  model or a field with a default no longer fails with a 400. Its schema is
+  rewritten to OpenAI's strict rules (every object closed, every property
+  required, optional ones nullable). Dict schemas and other providers are
+  unchanged.
+- A dict `response_format` is no longer modified in place: the top-level
+  `additionalProperties: false` was added to the caller's own dict.
+
+## [3.0.0] - 2026-10-15
+
+### Added
+
+- Registry: `supports_temperature` (default `true`, can be overridden per
+  provider), independent of `supports_reasoning`. OpenAI's `gpt-5*` and
+  `gpt-6*` models are marked `false`: their API accepts only the default
+  temperature (1).
+
+### Changed
+
+- **Breaking** — temperature no longer depends on reasoning: a temperature is
+  sent whenever one is set, reasoning model or not (gpt-oss, Claude, Mistral,
+  Qwen… honour it), and dropped only for a model whose registry entry says
+  `supports_temperature: false`. A per-call `temperature=` is treated the
+  same way.
+- **Breaking** — `GenerationSettings.temperature` defaults to `None` instead of
+  `0`: unset, no temperature is sent and the provider applies its own default.
+  Set `DOTI_GENERATION__TEMPERATURE=0` to keep the previous behaviour for
+  non-reasoning models.
+- Licence: from `AGPL-3.0-or-later` to `MIT`. Releases already published
+  stay under the AGPL.
+
 ## [2.2.0] - 2026-10-08
 
 ### Added
@@ -107,7 +189,9 @@ this release.
 - `LLMCallable` and `EmbeddingCallable` return a `Coroutine` rather than the
   looser `Awaitable`, matching what `asyncio.run_coroutine_threadsafe` accepts.
 
-[Unreleased]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/compare/v2.2.0...main
+[Unreleased]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/compare/v3.1.0...main
+[3.1.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v3.1.0
+[3.0.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v3.0.0
 [2.2.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v2.2.0
 [2.1.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v2.1.0
 [2.0.3]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v2.0.3

dot_inference-3.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for your interest in this project. Contributions are welcome.
+
+This project is maintained by **Kannon For Deep Tech** and released under the
+MIT License (`MIT`).
+
+## 1. Licensing of your contribution
+
+By contributing to this project, you agree that your contribution is licensed
+under the MIT License, the same terms as the rest of the project. You remain
+the author and copyright holder of your contribution.
+
+You confirm that you are entitled to do so: that your contribution is your
+original work or that you hold the necessary rights over it, and that it does
+not infringe any third-party rights. If you are contributing in the course of
+your employment or under a service agreement, you confirm that your employer or
+client has authorised you to contribute under these terms.
+
+## 2. Contractors and employees of Kannon For Deep Tech
+
+If you are working for Kannon For Deep Tech as an employee or under a service
+agreement, the assignment of rights set out in your contract governs, and takes
+precedence over this file.
+
+## 3. Submitting a change
+
+1. Open an issue first for anything substantial, so we can agree on the approach.
+2. Fork, branch, and keep commits focused.
+3. Add or update tests where relevant.
+4. If you would like to be credited individually, add yourself to
+   [AUTHORS.md](AUTHORS.md) in the same pull request.
+5. Open a pull request.
+
+## 4. Questions
+
+For anything about licensing, contact <louis.letarnec@deepika.ai>.

dot_inference-3.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Kannon For Deep Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{dot_inference-2.2.0 → dot_inference-3.1.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: dot-inference
-Version: 2.2.0
+Version: 3.1.0
 Summary: Unified async Python library for LLM inference and embeddings across multiple providers
 Project-URL: Homepage, https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference
 Project-URL: Repository, https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference
 Project-URL: Issues, https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/issues
 Author-email: Kannon For Deep Tech <louis.letarnec@deepika.ai>
-License-Expression: AGPL-3.0-or-later
+License-Expression: MIT
 License-File: LICENSE.md
 Keywords: embeddings,inference,llm,providers
 Classifier: Development Status :: 3 - Alpha
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/dot-inference)](https://pypi.org/project/dot-inference/)
 ![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)
-[![Licence: AGPL v3](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENSE.md)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE.md)
 [![Pipeline](https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/badges/main/pipeline.svg)](https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/pipelines)
 
 **One async interface for LLM inference and embeddings, across every provider.**
@@ -61,7 +61,9 @@ instead of silently doing nothing.
 - Multi-provider: OpenAI, Mistral, OpenRouter, and any OpenAI-compatible server (vLLM, SGLang, Ollama)
 - Structured outputs backed by Pydantic models
 - Rich event streaming: text, reasoning, incremental tool-call arguments, tool calls, usage and cost
-- Native tool calling with `tool_choice` control (`auto` / `required` / `none`)
+- Image input: URLs, local files or bytes, with per-model vision support in the registry
+- Native tool calling with `tool_choice` control (`auto` / `required` / `none` / a tool name) and strict tool schemas
+- Provider-specific request fields per call (`extra_body`)
 - Embeddings with automatic batching
 - Retries on transient errors, honouring `Retry-After`, with exponential backoff
 - Cost tracking in tokens and USD
@@ -90,10 +92,14 @@ nesting delimiter — or from an env file, modelled on `.env.template`:
 
 ```bash
 DOTI_GENERATION__PROVIDER=openai
-DOTI_GENERATION__OPENAI__MODEL_NAME=gpt-5-mini
+DOTI_GENERATION__OPENAI__MODEL_NAME=openai/gpt-5-mini
 DOTI_GENERATION__OPENAI__API_KEY=sk-...
 ```
 
+Model names are registry ids (`openai/gpt-5-mini`, whatever the provider); each
+provider is sent its own API name. A name missing from the registry is sent as
+is, with a warning, and without the registry's capabilities and prices.
+
 API keys are held as `SecretStr`, so a settings object caught in a traceback or
 an error report never carries the key in clear text.
 
@@ -121,7 +127,7 @@ print(response.content)
 from dot_inference import InferenceSettings, Message, Provider, Role, get_llm_client
 
 settings = InferenceSettings()
-client = get_llm_client(settings, provider=Provider.OPENAI, model="gpt-5-mini")
+client = get_llm_client(settings, provider=Provider.OPENAI, model="openai/gpt-5-mini")
 response = asyncio.run(client.call([Message(role=Role.USER, content="Hello!")]))
 ```
 
@@ -143,7 +149,7 @@ settings = InferenceSettings()
 client = get_llm_client(
     settings,
     provider=Provider.OPENAI,
-    model="gpt-5-mini",
+    model="openai/gpt-5-mini",
     reasoning_effort=ReasoningEffort.HIGH,
 )
 response = asyncio.run(client.call([Message(role=Role.USER, content="Solve this step by step...")]))
@@ -162,7 +168,7 @@ class Answer(BaseModel):
 
 
 settings = InferenceSettings()
-client = get_llm_client(settings, provider=Provider.OPENAI, model="gpt-5-mini")
+client = get_llm_client(settings, provider=Provider.OPENAI, model="openai/gpt-5-mini")
 response = asyncio.run(
     client.call(
         [Message(role=Role.USER, content="What is 2+2?")],
@@ -172,6 +178,32 @@ response = asyncio.run(
 print(response.structured_output)  # Answer(answer='4', confidence=1.0)
 ```
 
+OpenAI's strict mode wants every object closed (`"additionalProperties": false`) and every property listed in `required`. When the request reaches OpenAI (the `openai` provider, or an `openai/...` model on OpenRouter), a Pydantic model's schema is rewritten to those rules: an optional field becomes required but nullable, so the model answers `null` and Pydantic still gives `None`. A dict schema is sent as written and must follow the rules itself. Details and examples: [docs/provider-quirks/strict-schemas.md](docs/provider-quirks/strict-schemas.md).
+
+### Images
+
+Give a message a list of content parts: `text_part()` for text, `image_part()`
+for an image — an `http(s)://` or `data:` URL, a local file path, or raw bytes
+(inlined as base64).
+
+```python
+from dot_inference import Message, Role, image_part, text_part
+
+message = Message(
+    role=Role.USER,
+    content=[
+        text_part("What is on this receipt?"),
+        image_part("receipt.jpg"),
+        image_part("https://example.com/logo.png", detail="low"),
+    ],
+)
+response = client.call_sync([message])
+```
+
+The registry marks the models that read images (`supports_vision`). Sending an
+image to a model registered without it raises `ValueError` before any request;
+an unregistered model gets the request as-is.
+
 ### Streaming
 
 `stream()` yields typed `StreamEvent` objects:
@@ -279,6 +311,37 @@ client = get_llm_client(settings)
 client.on_retry = lambda attempt, max_attempts, err: print(f"Retry {attempt}/{max_attempts}: {err}")
 ```
 
+`max_attempts` sets the total number of attempts per request (default 4 for OpenAI-compatible clients, 2 for Mistral). Set it to 1 to surface every error immediately, e.g. when measuring latency:
+
+```python
+client = get_llm_client(settings, max_attempts=1)
+```
+
+### Strict tools, forced tool, provider-specific fields
+
+```python
+class WeatherArgs(BaseModel):
+    city: str
+    unit: Literal["C", "F"] | None = None
+
+
+tools = [
+    ToolDef(name="get_weather", description="Get weather", parameters=WeatherArgs, strict=True)
+]
+
+response = await client.call(
+    messages,
+    tools=tools,
+    tool_choice="get_weather",          # force this tool; or "auto" / "required" / "none"
+    extra_body={"ignore_eos": True},    # sent as-is (vLLM, SGLang, llama.cpp…)
+)
+args = tools[0].parse_arguments(response.tool_calls[0].arguments)  # WeatherArgs(city='Paris', unit=None)
+```
+
+`parameters` is a JSON schema dict, sent as written, or a Pydantic model. A model's schema is sent, rewritten to OpenAI's strict rules when `strict=True` (for every provider: OpenAI and Claude both reject a strict tool with an open object). A call's `arguments` stays the JSON string the provider sent; `ToolDef.parse_arguments()` validates it into the model, raising `ValidationError` when it does not match.
+
+`strict=True` asks the server to constrain the arguments to the schema exactly; it is only sent when set, and OpenAI then imposes its own schema rules ([strict-schemas.md](docs/provider-quirks/strict-schemas.md)). Some models cannot be forced to call a tool (Claude Opus 5.5 and Sonnet 5.5): `"required"` or a tool name raises `ValueError` there ([tool-choice.md](docs/provider-quirks/tool-choice.md)). `extra_body` fields win over those the client adds itself (OpenRouter routing, `cache_control`); the Mistral client rejects `extra_body`.
+
 ## On-premise inference (vLLM, SGLang, Ollama)
 
 Point the `local` provider at any OpenAI-compatible endpoint:
@@ -297,6 +360,25 @@ response = client.call_sync([Message(role=Role.USER, content="How tall is the Ei
 print(response.content)
 ```
 
+`list_served_models(base_url)` returns the model ids the server actually loaded
+(`GET /models`), for any model. To send `reasoning_effort` to a model the
+registry does not know, declare it (`temperature` is still sent alongside
+it, as for any model with `supports_temperature`, the default):
+
+```python
+from dot_inference import ModelConfig, ProviderModelConfig, list_served_models, register_model
+
+base_url = "http://localhost:8000/v1"
+served = (await list_served_models(base_url))[0]
+register_model(ModelConfig(
+    model_id=served,
+    supports_reasoning=True,
+    supports_vision=True,  # if the served model reads images
+    default_provider="local",
+    providers={"local": ProviderModelConfig(api_model_name=served)},
+))
+```
+
 ## Testing without API calls
 
 ```python
@@ -313,7 +395,7 @@ package is covered, anything underscore-prefixed is internal and may change in
 any release. Public names are never removed without a deprecation period.
 
 ```toml
-dependencies = ["dot-inference>=2.0,<3"]
+dependencies = ["dot-inference>=3.0,<4"]
 ```
 
 See [docs/VERSIONING.md](docs/VERSIONING.md) for the full policy.
@@ -332,21 +414,17 @@ See [docs/VERSIONING.md](docs/VERSIONING.md) for the full policy.
 | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Environment setup, tests, code style |
 | [docs/VERSIONING.md](docs/VERSIONING.md) | Versioning, deprecation policy, how to depend on this package |
 | [docs/PUBLISHING.md](docs/PUBLISHING.md) | Cutting a release |
-| [docs/provider-quirks/](docs/provider-quirks/) | Provider behaviours that differ from the OpenAI format: `tool_choice` support, OpenRouter error bodies |
+| [docs/provider-quirks/](docs/provider-quirks/) | Provider behaviours that differ from the OpenAI format: `tool_choice` support, strict schemas, OpenRouter error bodies |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |
 
 ## Contributing
 
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the DCO
-sign-off requirement, the licensing terms that apply to contributions, and how to
-submit a change.
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+licensing terms that apply to contributions and how to submit a change.
 
 ## Licence
 
 Copyright (C) 2026 Kannon For Deep Tech (deepika)
 
-This software is distributed under the GNU Affero General Public License,
-version 3 or later — see [LICENSE.md](LICENSE.md).
-
-A commercial licence is available for use in proprietary environments.
-Contact: louis.letarnec@deepika.ai
+This software is distributed under the MIT License — see
+[LICENSE.md](LICENSE.md).

{dot_inference-2.2.0 → dot_inference-3.1.0}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/dot-inference)](https://pypi.org/project/dot-inference/)
 ![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)
-[![Licence: AGPL v3](https://img.shields.io/badge/licence-AGPL--3.0--or--later-blue)](LICENSE.md)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE.md)
 [![Pipeline](https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/badges/main/pipeline.svg)](https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/pipelines)
 
 **One async interface for LLM inference and embeddings, across every provider.**
@@ -34,7 +34,9 @@ instead of silently doing nothing.
 - Multi-provider: OpenAI, Mistral, OpenRouter, and any OpenAI-compatible server (vLLM, SGLang, Ollama)
 - Structured outputs backed by Pydantic models
 - Rich event streaming: text, reasoning, incremental tool-call arguments, tool calls, usage and cost
-- Native tool calling with `tool_choice` control (`auto` / `required` / `none`)
+- Image input: URLs, local files or bytes, with per-model vision support in the registry
+- Native tool calling with `tool_choice` control (`auto` / `required` / `none` / a tool name) and strict tool schemas
+- Provider-specific request fields per call (`extra_body`)
 - Embeddings with automatic batching
 - Retries on transient errors, honouring `Retry-After`, with exponential backoff
 - Cost tracking in tokens and USD
@@ -63,10 +65,14 @@ nesting delimiter — or from an env file, modelled on `.env.template`:
 
 ```bash
 DOTI_GENERATION__PROVIDER=openai
-DOTI_GENERATION__OPENAI__MODEL_NAME=gpt-5-mini
+DOTI_GENERATION__OPENAI__MODEL_NAME=openai/gpt-5-mini
 DOTI_GENERATION__OPENAI__API_KEY=sk-...
 ```
 
+Model names are registry ids (`openai/gpt-5-mini`, whatever the provider); each
+provider is sent its own API name. A name missing from the registry is sent as
+is, with a warning, and without the registry's capabilities and prices.
+
 API keys are held as `SecretStr`, so a settings object caught in a traceback or
 an error report never carries the key in clear text.
 
@@ -94,7 +100,7 @@ print(response.content)
 from dot_inference import InferenceSettings, Message, Provider, Role, get_llm_client
 
 settings = InferenceSettings()
-client = get_llm_client(settings, provider=Provider.OPENAI, model="gpt-5-mini")
+client = get_llm_client(settings, provider=Provider.OPENAI, model="openai/gpt-5-mini")
 response = asyncio.run(client.call([Message(role=Role.USER, content="Hello!")]))
 ```
 
@@ -116,7 +122,7 @@ settings = InferenceSettings()
 client = get_llm_client(
     settings,
     provider=Provider.OPENAI,
-    model="gpt-5-mini",
+    model="openai/gpt-5-mini",
     reasoning_effort=ReasoningEffort.HIGH,
 )
 response = asyncio.run(client.call([Message(role=Role.USER, content="Solve this step by step...")]))
@@ -135,7 +141,7 @@ class Answer(BaseModel):
 
 
 settings = InferenceSettings()
-client = get_llm_client(settings, provider=Provider.OPENAI, model="gpt-5-mini")
+client = get_llm_client(settings, provider=Provider.OPENAI, model="openai/gpt-5-mini")
 response = asyncio.run(
     client.call(
         [Message(role=Role.USER, content="What is 2+2?")],
@@ -145,6 +151,32 @@ response = asyncio.run(
 print(response.structured_output)  # Answer(answer='4', confidence=1.0)
 ```
 
+OpenAI's strict mode wants every object closed (`"additionalProperties": false`) and every property listed in `required`. When the request reaches OpenAI (the `openai` provider, or an `openai/...` model on OpenRouter), a Pydantic model's schema is rewritten to those rules: an optional field becomes required but nullable, so the model answers `null` and Pydantic still gives `None`. A dict schema is sent as written and must follow the rules itself. Details and examples: [docs/provider-quirks/strict-schemas.md](docs/provider-quirks/strict-schemas.md).
+
+### Images
+
+Give a message a list of content parts: `text_part()` for text, `image_part()`
+for an image — an `http(s)://` or `data:` URL, a local file path, or raw bytes
+(inlined as base64).
+
+```python
+from dot_inference import Message, Role, image_part, text_part
+
+message = Message(
+    role=Role.USER,
+    content=[
+        text_part("What is on this receipt?"),
+        image_part("receipt.jpg"),
+        image_part("https://example.com/logo.png", detail="low"),
+    ],
+)
+response = client.call_sync([message])
+```
+
+The registry marks the models that read images (`supports_vision`). Sending an
+image to a model registered without it raises `ValueError` before any request;
+an unregistered model gets the request as-is.
+
 ### Streaming
 
 `stream()` yields typed `StreamEvent` objects:
@@ -252,6 +284,37 @@ client = get_llm_client(settings)
 client.on_retry = lambda attempt, max_attempts, err: print(f"Retry {attempt}/{max_attempts}: {err}")
 ```
 
+`max_attempts` sets the total number of attempts per request (default 4 for OpenAI-compatible clients, 2 for Mistral). Set it to 1 to surface every error immediately, e.g. when measuring latency:
+
+```python
+client = get_llm_client(settings, max_attempts=1)
+```
+
+### Strict tools, forced tool, provider-specific fields
+
+```python
+class WeatherArgs(BaseModel):
+    city: str
+    unit: Literal["C", "F"] | None = None
+
+
+tools = [
+    ToolDef(name="get_weather", description="Get weather", parameters=WeatherArgs, strict=True)
+]
+
+response = await client.call(
+    messages,
+    tools=tools,
+    tool_choice="get_weather",          # force this tool; or "auto" / "required" / "none"
+    extra_body={"ignore_eos": True},    # sent as-is (vLLM, SGLang, llama.cpp…)
+)
+args = tools[0].parse_arguments(response.tool_calls[0].arguments)  # WeatherArgs(city='Paris', unit=None)
+```
+
+`parameters` is a JSON schema dict, sent as written, or a Pydantic model. A model's schema is sent, rewritten to OpenAI's strict rules when `strict=True` (for every provider: OpenAI and Claude both reject a strict tool with an open object). A call's `arguments` stays the JSON string the provider sent; `ToolDef.parse_arguments()` validates it into the model, raising `ValidationError` when it does not match.
+
+`strict=True` asks the server to constrain the arguments to the schema exactly; it is only sent when set, and OpenAI then imposes its own schema rules ([strict-schemas.md](docs/provider-quirks/strict-schemas.md)). Some models cannot be forced to call a tool (Claude Opus 5.5 and Sonnet 5.5): `"required"` or a tool name raises `ValueError` there ([tool-choice.md](docs/provider-quirks/tool-choice.md)). `extra_body` fields win over those the client adds itself (OpenRouter routing, `cache_control`); the Mistral client rejects `extra_body`.
+
 ## On-premise inference (vLLM, SGLang, Ollama)
 
 Point the `local` provider at any OpenAI-compatible endpoint:
@@ -270,6 +333,25 @@ response = client.call_sync([Message(role=Role.USER, content="How tall is the Ei
 print(response.content)
 ```
 
+`list_served_models(base_url)` returns the model ids the server actually loaded
+(`GET /models`), for any model. To send `reasoning_effort` to a model the
+registry does not know, declare it (`temperature` is still sent alongside
+it, as for any model with `supports_temperature`, the default):
+
+```python
+from dot_inference import ModelConfig, ProviderModelConfig, list_served_models, register_model
+
+base_url = "http://localhost:8000/v1"
+served = (await list_served_models(base_url))[0]
+register_model(ModelConfig(
+    model_id=served,
+    supports_reasoning=True,
+    supports_vision=True,  # if the served model reads images
+    default_provider="local",
+    providers={"local": ProviderModelConfig(api_model_name=served)},
+))
+```
+
 ## Testing without API calls
 
 ```python
@@ -286,7 +368,7 @@ package is covered, anything underscore-prefixed is internal and may change in
 any release. Public names are never removed without a deprecation period.
 
 ```toml
-dependencies = ["dot-inference>=2.0,<3"]
+dependencies = ["dot-inference>=3.0,<4"]
 ```
 
 See [docs/VERSIONING.md](docs/VERSIONING.md) for the full policy.
@@ -305,21 +387,17 @@ See [docs/VERSIONING.md](docs/VERSIONING.md) for the full policy.
 | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Environment setup, tests, code style |
 | [docs/VERSIONING.md](docs/VERSIONING.md) | Versioning, deprecation policy, how to depend on this package |
 | [docs/PUBLISHING.md](docs/PUBLISHING.md) | Cutting a release |
-| [docs/provider-quirks/](docs/provider-quirks/) | Provider behaviours that differ from the OpenAI format: `tool_choice` support, OpenRouter error bodies |
+| [docs/provider-quirks/](docs/provider-quirks/) | Provider behaviours that differ from the OpenAI format: `tool_choice` support, strict schemas, OpenRouter error bodies |
 | [CHANGELOG.md](CHANGELOG.md) | Release history |
 
 ## Contributing
 
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the DCO
-sign-off requirement, the licensing terms that apply to contributions, and how to
-submit a change.
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
+licensing terms that apply to contributions and how to submit a change.
 
 ## Licence
 
 Copyright (C) 2026 Kannon For Deep Tech (deepika)
 
-This software is distributed under the GNU Affero General Public License,
-version 3 or later — see [LICENSE.md](LICENSE.md).
-
-A commercial licence is available for use in proprietary environments.
-Contact: louis.letarnec@deepika.ai
+This software is distributed under the MIT License — see
+[LICENSE.md](LICENSE.md).