dot-inference 2.0.3__tar.gz → 2.1.0__tar.gz

{dot_inference-2.0.3 → dot_inference-2.1.0}/.gitlab-ci.yml

@@ -1,7 +1,8 @@
 # Pipeline for a Python library published to PyPI.
 #
 #   quality  lint, format and type checks (pre-commit)
-#   test     pytest on every supported Python version
+#   test     pytest on every supported Python version, plus live API smoke
+#            tests when the provider code or the lockfile changes
 #   publish  tag-only: build, then TestPyPI, then PyPI behind a manual gate
 #
 # Publishing uses PyPI Trusted Publishing (OIDC): GitLab mints a short-lived ID
@@ -71,7 +72,8 @@ test:
   before_script:
     - uv sync --all-extras --all-groups --python "$PYTHON_VERSION"
   script:
-    - uv run --python "$PYTHON_VERSION" pytest --cov=src --cov-report=term --cov-report=xml
+    # Live API tests have their own job below; keep this one offline.
+    - uv run --python "$PYTHON_VERSION" pytest -m "not live" --cov=src --cov-report=term --cov-report=xml
   coverage: '/^TOTAL.*\s+(\d+%)$/'
   artifacts:
     when: always
@@ -80,6 +82,51 @@ test:
         coverage_format: cobertura
         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.
+#
+# 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:
+  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
+    - 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
+    # 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/_client.py
+        - src/dot_inference/_types.py
+        - src/dot_inference/_cost_tracker.py
+        - src/dot_inference/_retry.py
+        - src/dot_inference/_llm_registry.py
+        - src/dot_inference/models.yaml
+        - tests/test_mistral_live.py
+        # SDK upgrades are the main source of silent breakage.
+        - pyproject.toml
+        - uv.lock
+        - .gitlab-ci.yml
+    - when: manual
+      allow_failure: true
+
 # --------------------------------------------------------------------------
 # publish  (release tags only)
 # --------------------------------------------------------------------------

{dot_inference-2.0.3 → dot_inference-2.1.0}/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-10-07
+
+### Added
+
+- `LLMResponse.finish_reason`: why the model stopped, as the provider reports
+  it (`stop`, `tool_calls`, `length`, `content_filter`, `error`…), for both
+  `call()` and `stream()`, OpenAI-compatible and Mistral clients.
+- Every LLM response is logged once with its `finish_reason` and body —
+  `response from '<model>': finish_reason=… id=… body=…`. `call()` logs the
+  raw response; `stream()` the assembled content and tool calls, the chunk
+  count and the usage — plus, on OpenRouter, `native_finish_reason`. DEBUG when the model ended on its own (`stop`,
+  `tool_calls`), WARNING otherwise — including a stream that ends without any
+  finish reason, which previously left no trace.
+- An abnormal response's line also summarizes the request that produced it,
+  without its content: parameters (`extra_body` included), tool names, each
+  message's role, size, cache markers and tool calls, and its total size. Its `id` is the provider's id for the call — OpenRouter's
+  `x-generation-id` header for streams (present even when no chunk arrives),
+  the response id otherwise.
+
+### Changed
+
+- `mistral/mistral-small-latest` and `mistral/mistral-small-2603` (Mistral
+  Small 4) are now declared with `supports_reasoning: true`, accepting
+  `reasoning_effort` `none` (the default, matching the API's) or `high`. As
+  for every reasoning model, `temperature` is no longer forwarded for them.
+
 ## [2.0.3] - 2026-09-30
 
 ### Fixed
@@ -72,7 +98,8 @@ 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.0.3...main
+[Unreleased]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/compare/v2.1.0...main
+[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
 [2.0.2]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v2.0.2
 [2.0.0]: https://gitlab.com/deepika6190303/deepika-open-toolbox/dot-inference/-/tags/v2.0.0

{dot_inference-2.0.3 → dot_inference-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dot-inference
-Version: 2.0.3
+Version: 2.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

{dot_inference-2.0.3 → dot_inference-2.1.0}/docs/DEVELOPMENT.md

@@ -70,17 +70,35 @@ uv run pytest
 uv run pytest --cov=src --cov-report=term-missing
 ```
 
-### Before upgrading the Mistral SDK
+### Live API tests
 
 The regular suite builds SDK responses from local stubs, so it stays green even
 when the real SDK changes shape — a passing run does not prove an upgrade is
-safe. `tests/test_mistral_live.py` checks the four silent-failure spots against
-the real API; it is skipped when no key is present.
+safe. Tests marked `live` call the real provider API instead: today that is
+`tests/test_mistral_live.py`, which covers reasoning, structured output, tool
+calling, usage/cost reporting, embeddings and retry behavior on Mistral Small 4
+(`mistral/mistral-small-2603`), with short prompts and capped `max_tokens` — a
+full run costs about $0.0005.
+
+They are skipped when no key is present. Run them before and after any
+`mistralai` upgrade:
 
 ```shell
-MISTRAL_API_KEY=... uv run pytest tests/test_mistral_live.py -v
+MISTRAL_API_KEY=... uv run pytest -m live -v
 ```
 
+In CI, the `test` job deselects them (`-m "not live"`) and the
+`test_live_mistral` job runs them when the Mistral client, the shared client
+code, the model registry or the lockfile change; on other pipelines it can be
+started by hand. It needs a `MISTRAL_API_KEY` CI/CD variable, masked but not
+protected, from a dedicated key with a low spending cap. MRs from forks do not
+run it.
+
+When adding live tests for another provider, keep the same rules: mark them
+`live`, use the provider's cheapest model that supports the feature under test,
+assert on the shape of the response rather than its wording, and give them
+their own CI job gated on that provider's files.
+
 ## Examples
 
 The examples read credentials from a local env file — see `.env.template`

{dot_inference-2.0.3 → dot_inference-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dot-inference"
-version = "2.0.3"
+version = "2.1.0"
 description = "Unified async Python library for LLM inference and embeddings across multiple providers"
 readme = "README.md"
 authors = [{ name = "Kannon For Deep Tech", email = "louis.letarnec@deepika.ai" }]
@@ -102,6 +102,9 @@ pythonpath = ["src"]
 testpaths = ["tests"]
 addopts = "--strict-markers"
 asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "live: calls a real provider API (needs credentials, costs money); deselect with -m 'not live'",
+]
 
 # For TestPyPI
 [[tool.uv.index]]

{dot_inference-2.0.3 → dot_inference-2.1.0}/src/dot_inference/_client.py

@@ -11,6 +11,7 @@ and provider configuration automatically.
 
 from __future__ import annotations
 
+import json
 import logging
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, Callable
@@ -39,6 +40,52 @@ from dot_inference.settings import InferenceSettings, Provider, ReasoningEffort
 
 logger = logging.getLogger(__name__)
 
+#: Finish reasons of a model that ended its answer on its own.
+_NORMAL_FINISH = frozenset({"stop", "tool_calls"})
+
+
+def _dump(obj: Any) -> Any:
+    """JSON-ready view of an SDK object, provider extension fields included
+    (OpenRouter's ``provider``, ``native_finish_reason``, ``error``…)."""
+    model_dump = getattr(obj, "model_dump", None)
+    return model_dump(exclude_none=True) if callable(model_dump) else obj
+
+
+def _to_json(obj: Any) -> str:
+    return json.dumps(obj, ensure_ascii=False, default=str)
+
+
+def _message_shape(message: Any) -> dict[str, Any]:
+    """Role and size of one message, without its content."""
+    msg = _dump(message)
+    if not isinstance(msg, dict):
+        return {"type": type(message).__name__}
+    content = msg.get("content")
+    shape: dict[str, Any] = {"role": str(msg.get("role")), "chars": len(_to_json(content))}
+    if isinstance(content, list):
+        shape["parts"] = len(content)
+    if "cache_control" in _to_json(content):
+        shape["cache_control"] = True
+    if msg.get("tool_calls"):
+        shape["tool_calls"] = len(msg["tool_calls"])
+    if msg.get("tool_call_id"):
+        shape["tool_call_id"] = msg["tool_call_id"]
+    return shape
+
+
+def _summarize_request(request: dict[str, Any]) -> dict[str, Any]:
+    """The request minus its content: parameters, tool names, message shapes."""
+    messages = request.get("messages") or []
+    tools = request.get("tools") or []
+    return {
+        "chars": len(_to_json(request)),
+        "params": {k: v for k, v in request.items() if k not in ("messages", "tools")},
+        "tools": [
+            (t.get("function") or {}).get("name") if isinstance(t, dict) else str(t) for t in tools
+        ],
+        "messages": [_message_shape(m) for m in messages],
+    }
+
 
 class LLMClient(ABC):
     """Abstract base class for LLM clients.
@@ -66,6 +113,40 @@ class LLMClient(ABC):
         is a human-readable description of the failure.
         """
 
+    def _log_response(
+        self,
+        logger: logging.Logger,
+        finish_reason: str | None,
+        body: Any,
+        request: dict[str, Any],
+        response_id: str | None = None,
+    ) -> None:
+        """Log one response; an abnormal one also summarizes ``request``.
+
+        ``response_id`` is the provider's id for the call (e.g. OpenRouter's
+        ``x-generation-id``), to look it up on the provider's side.
+        """
+        if not isinstance(response_id, str):
+            response_id = None
+        if finish_reason in _NORMAL_FINISH:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(
+                    "response from '%s': finish_reason=%s id=%s body=%s",
+                    self._model,
+                    finish_reason,
+                    response_id,
+                    _to_json(body),
+                )
+            return
+        logger.warning(
+            "response from '%s': finish_reason=%s id=%s body=%s request=%s",
+            self._model,
+            finish_reason,
+            response_id,
+            _to_json(body),
+            _to_json(_summarize_request(request)),
+        )
+
     @abstractmethod
     async def call(
         self,

{dot_inference-2.0.3 → dot_inference-2.1.0}/src/dot_inference/_mistral_compat.py

@@ -19,7 +19,7 @@ from typing import Any
 import httpx
 from pydantic import BaseModel
 
-from dot_inference._client import EmbeddingClient, LLMClient
+from dot_inference._client import EmbeddingClient, LLMClient, _dump
 from dot_inference._cost_tracker import compute_cost
 from dot_inference._llm_registry import ResolvedModelConfig
 from dot_inference._retry import compute_wait
@@ -268,6 +268,9 @@ class MistralClient(LLMClient):
                 cost or "?",
             )
 
+        finish_reason = response.choices[0].finish_reason if response.choices else None
+        self._log_response(LOGGER, finish_reason, _dump(response), create_kwargs, response.id)
+
         msg = response.choices[0].message
         # Reasoning models return content as list[ContentChunk]; keep the
         # answer text only (thinking is display-only and dropped here).
@@ -294,6 +297,7 @@ class MistralClient(LLMClient):
             content=text_content or None,
             tool_calls=tool_calls,
             structured_output=structured_output,
+            finish_reason=finish_reason,
             cost=cost,
             prompt_tokens=prompt_tokens,
             completion_tokens=completion_tokens,
@@ -331,6 +335,7 @@ class MistralClient(LLMClient):
         prompt_tokens: int | None = None
         completion_tokens: int | None = None
         last_usage: Any = None
+        finish_reason: str | None = None
 
         for attempt in range(1, _MAX_ATTEMPTS + 1):
             has_yielded = False
@@ -341,6 +346,9 @@ class MistralClient(LLMClient):
             prompt_tokens = None
             completion_tokens = None
             last_usage = None
+            finish_reason = None
+            response_id = None
+            n_chunks = 0
             response = None
 
             try:
@@ -348,6 +356,8 @@ class MistralClient(LLMClient):
 
                 async for event in response:
                     data = event.data
+                    n_chunks += 1
+                    response_id = response_id or getattr(data, "id", None)
 
                     if data.usage:
                         prompt_tokens = data.usage.prompt_tokens
@@ -413,6 +423,9 @@ class MistralClient(LLMClient):
                             yield ToolCallDone(tool_call=tc)
                         tool_acc.clear()
 
+                    if choice.finish_reason:
+                        finish_reason = choice.finish_reason
+
                 break  # Stream completed successfully
 
             except (MistralError, httpx.TransportError) as exc:
@@ -466,6 +479,18 @@ class MistralClient(LLMClient):
             )
 
         content = "".join(content_parts) or None
+        self._log_response(
+            LOGGER,
+            finish_reason,
+            {
+                "content": content,
+                "tool_calls": [tc.model_dump() for tc in finished_tool_calls],
+                "chunks": n_chunks,
+                "usage": _dump(last_usage),
+            },
+            create_kwargs,
+            response_id,
+        )
         structured_output = None
         if response_model is not None:
             if not content:
@@ -476,6 +501,7 @@ class MistralClient(LLMClient):
             content=content,
             tool_calls=finished_tool_calls or None,
             structured_output=structured_output,
+            finish_reason=finish_reason,
             cost=cost,
             prompt_tokens=prompt_tokens,
             completion_tokens=completion_tokens,

{dot_inference-2.0.3 → dot_inference-2.1.0}/src/dot_inference/_openai_compat.py

@@ -19,7 +19,7 @@ import openai
 from openai import AsyncOpenAI
 from pydantic import BaseModel
 
-from dot_inference._client import EmbeddingClient, LLMClient
+from dot_inference._client import EmbeddingClient, LLMClient, _dump
 from dot_inference._cost_tracker import compute_cost
 from dot_inference._llm_registry import ResolvedModelConfig
 from dot_inference._retry import compute_wait
@@ -112,6 +112,14 @@ def _reported_cost(usage: Any) -> float | None:
     return float(cost)
 
 
+def _generation_id(stream: Any) -> str | None:
+    """OpenRouter's id for the call (``x-generation-id`` header) — there even
+    when the stream carries no chunk at all."""
+    headers = getattr(getattr(stream, "response", None), "headers", None)
+    value = headers.get("x-generation-id") if headers is not None else None
+    return value if isinstance(value, str) else None
+
+
 class OpenAICompatClient(LLMClient):
     """LLM client for any OpenAI-compatible endpoint.
 
@@ -302,6 +310,9 @@ class OpenAICompatClient(LLMClient):
                 cost or "?",
             )
 
+        finish_reason = response.choices[0].finish_reason if response.choices else None
+        self._log_response(LOGGER, finish_reason, _dump(response), create_kwargs, response.id)
+
         msg = response.choices[0].message
 
         # Parse native tool calls if present
@@ -320,7 +331,6 @@ class OpenAICompatClient(LLMClient):
         structured_output = None
         if response_model is not None:
             if not msg.content:
-                finish_reason = response.choices[0].finish_reason
                 refusal = getattr(msg, "refusal", None)
                 raise RuntimeError(
                     f"LLM returned empty content with response_format set "
@@ -334,6 +344,7 @@ class OpenAICompatClient(LLMClient):
             content=msg.content,
             tool_calls=tool_calls,
             structured_output=structured_output,
+            finish_reason=finish_reason,
             cost=cost,
             prompt_tokens=prompt_tokens,
             completion_tokens=completion_tokens,
@@ -374,6 +385,8 @@ class OpenAICompatClient(LLMClient):
         completion_tokens: int | None = None
         cached_tokens: int | None = None
         last_usage: Any = None
+        finish_reason: str | None = None
+        native_finish_reason: str | None = None
 
         for attempt in range(1, _MAX_ATTEMPTS + 1):
             has_yielded = False
@@ -385,12 +398,19 @@ class OpenAICompatClient(LLMClient):
             completion_tokens = None
             cached_tokens = None
             last_usage = None
+            finish_reason = None
+            native_finish_reason = None
+            response_id = None
+            n_chunks = 0
             response = None
 
             try:
                 response = await self._client.chat.completions.create(**create_kwargs)
+                response_id = _generation_id(response)
 
                 async for chunk in response:
+                    n_chunks += 1
+                    response_id = response_id or getattr(chunk, "id", None)
                     if chunk.usage:
                         prompt_tokens = chunk.usage.prompt_tokens
                         completion_tokens = chunk.usage.completion_tokens
@@ -464,6 +484,11 @@ class OpenAICompatClient(LLMClient):
                             yield ToolCallDone(tool_call=tc)
                         tool_acc.clear()
 
+                    if choice.finish_reason:
+                        finish_reason = choice.finish_reason
+                        # OpenRouter: the provider's own reason, before normalization
+                        native_finish_reason = getattr(choice, "native_finish_reason", None)
+
                 break  # Stream completed successfully
 
             except openai.APIError as exc:
@@ -512,6 +537,19 @@ class OpenAICompatClient(LLMClient):
 
         # Final assembled response
         content = "".join(content_parts) or None
+        self._log_response(
+            LOGGER,
+            finish_reason,
+            {
+                "content": content,
+                "tool_calls": [tc.model_dump() for tc in finished_tool_calls],
+                "chunks": n_chunks,
+                "usage": _dump(last_usage),
+                "native_finish_reason": native_finish_reason,
+            },
+            create_kwargs,
+            response_id,
+        )
         structured_output = None
         if response_model is not None:
             if not content:
@@ -522,6 +560,7 @@ class OpenAICompatClient(LLMClient):
             content=content,
             tool_calls=finished_tool_calls or None,
             structured_output=structured_output,
+            finish_reason=finish_reason,
             cost=cost,
             prompt_tokens=prompt_tokens,
             completion_tokens=completion_tokens,

{dot_inference-2.0.3 → dot_inference-2.1.0}/src/dot_inference/_types.py

@@ -80,6 +80,10 @@ class LLMResponse(BaseModel):
     content: str | None = None
     tool_calls: list[ToolCall] | None = None
     structured_output: BaseModel | None = None
+    #: Why the model stopped, as the provider reports it (``stop``,
+    #: ``tool_calls``, ``length``, ``content_filter``, ``error``…); None when
+    #: the provider gave none.
+    finish_reason: str | None = None
     cost: float | None = None
     prompt_tokens: int | None = None
     completion_tokens: int | None = None

{dot_inference-2.0.3 → dot_inference-2.1.0}/src/dot_inference/models.yaml

@@ -309,14 +309,14 @@ mistral/mistral-large-latest:
 # Alias — always resolves to the latest Mistral Small release.
 # Use this when you want automatic upgrades as Mistral ships new versions.
 # Note: behavior may change silently when the alias is reassigned.
-#
-# Reasoning: the Mistral REST API supports reasoning_effort ("high"/"none")
-# for this model, but the Python SDK (mistralai v2.0.2) does not yet expose
-# the parameter.  Reasoning is disabled at the model level to keep behavior
-# consistent across providers.  Re-enable once the SDK adds support.
 mistral/mistral-small-latest:
   default_provider: mistral
   supports_strict_json: true
+  # Adjustable reasoning, same contract as Medium 3.5: "none" (no thinking
+  # chunk — also the API default) or "high" (full thinking chunk).
+  supports_reasoning: true
+  reasoning_effort_options: [none, high]
+  default_reasoning_effort: none
   input_token_cost: 1.5e-7    # $0.15/M
   output_token_cost: 6e-7     # $0.60/M
   context_window: 256000
@@ -335,10 +335,14 @@ mistral/mistral-small-latest:
 # Kept alongside the alias for production stability: pipelines that require
 # reproducible behavior should reference this ID so they are unaffected when
 # mistral-small-latest is reassigned to a future release.
-# Same SDK limitation as the alias above — see comment there.
+# Also the model the live CI tests run against (tests/test_mistral_live.py).
 mistral/mistral-small-2603:
   default_provider: mistral
   supports_strict_json: true
+  # Reasoning: see the alias above.
+  supports_reasoning: true
+  reasoning_effort_options: [none, high]
+  default_reasoning_effort: none
   input_token_cost: 1.5e-7    # $0.15/M
   output_token_cost: 6e-7     # $0.60/M
   providers:

{dot_inference-2.0.3 → dot_inference-2.1.0}/tests/test_mistral_compat.py

@@ -339,3 +339,22 @@ async def test_call_collapses_structured_content_to_text():
     result = await client.call([Message(role=Role.USER, content="Hi")])
 
     assert result.content == "answer"
+
+
+# --- Response log: finish_reason + body ---
+
+
+@pytest.mark.asyncio
+async def test_stream_logs_finish_reason(caplog):
+    client = _reasoning_client(supports_reasoning=False)
+    events = [_stream_event(content="answer"), _stream_event(finish_reason="error")]
+    client._client.chat.stream_async = AsyncMock(return_value=_async_iter(events))
+
+    with caplog.at_level("DEBUG", logger="dot_inference._mistral_compat"):
+        out = [ev async for ev in client.stream([Message(role=Role.USER, content="Hi")])]
+
+    assert out[-1].response.finish_reason == "error"
+    [log] = [r for r in caplog.records if r.getMessage().startswith("response from")]
+    assert log.levelname == "WARNING"
+    assert "finish_reason=error" in log.getMessage()
+    assert '"content": "answer"' in log.getMessage()