dot-inference 2.0.2__py3-none-any.whl

dot_inference/_sync.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Sync helpers — run async code from synchronous contexts.
+
+Uses a single persistent background event loop in a daemon thread so that:
+- httpx / SDK async clients can clean up properly (no "Event loop is closed").
+- Multiple sync calls reuse the same loop (no per-call overhead).
+- The daemon thread is cleaned up automatically on process exit.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import Coroutine
+from typing import Any
+
+_loop: asyncio.AbstractEventLoop | None = None
+_thread: threading.Thread | None = None
+_lock = threading.Lock()
+
+
+def _get_loop() -> asyncio.AbstractEventLoop:
+    """Return the shared background event loop, creating it on first use."""
+    global _loop, _thread
+    if _loop is not None and _loop.is_running():
+        return _loop
+
+    with _lock:
+        # Double-check under lock.
+        if _loop is not None and _loop.is_running():
+            return _loop
+
+        _loop = asyncio.new_event_loop()
+        _thread = threading.Thread(target=_loop.run_forever, daemon=True)
+        _thread.start()
+        return _loop
+
+
+def run_sync[T](coro: Coroutine[Any, Any, T]) -> T:
+    """Run an awaitable synchronously, blocking until it completes.
+
+    Safe to call from any synchronous context — even after a previous
+    ``asyncio.run()`` has closed its loop.
+    """
+    loop = _get_loop()
+    future = asyncio.run_coroutine_threadsafe(coro, loop)
+    return future.result()

dot_inference/_types.py

@@ -0,0 +1,229 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Shared types for dot-llm."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Callable, Coroutine
+from enum import StrEnum
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# --- Message types ---
+# Duplicated in dot_agent/types.py to keep both packages independent.
+# If you change these, update the dot-agent copy too.
+
+
+class Role(StrEnum):
+    """Roles in an LLM conversation."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+# to expose to the front user
+class Message(BaseModel):
+    """A single message in OpenAI chat-completion format.
+
+    Only ``role`` is required. Provider-specific keys (e.g. ``name``,
+    ``function_call``, multimodal content arrays) are accepted via
+    ``extra="allow"`` and passed through untouched.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    role: Role
+    content: str | list[dict[str, Any]] | None = None
+    # Present on assistant messages when the model invokes tools.
+    tool_calls: list[Any] | None = None
+    # Present on tool-role messages to link the result back to the call.
+    tool_call_id: str | None = None
+
+
+# --- LLM interface types ---
+# Duplicated in dot_agent/types.py to keep both packages independent.
+# If you change these, update the dot-agent copy too.
+
+
+class ToolDef(BaseModel):
+    """A tool definition passed to the LLM via the native tool-calling API."""
+
+    name: str
+    description: str
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+
+# --- LLM response types ---
+
+
+# to expose to the front USER
+class ToolCall(BaseModel):
+    """A tool-call request emitted by the LLM via native tool calling."""
+
+    id: str = Field(description="Provider-assigned call ID (needed for the tool role)")
+    name: str
+    arguments: str = Field(description="JSON-encoded arguments")
+
+
+# Tool-call results are sent back via Message(role=Role.TOOL, tool_call_id=..., content=...).
+# No dedicated class needed — the Message model already covers this. (delegated properly to dot-agent)
+
+
+# TODO: vitrine pour le streaming à exposer pour le front.
+class LLMResponse(BaseModel):
+    """Normalized response from an LLM call."""
+
+    content: str | None = None
+    tool_calls: list[ToolCall] | None = None
+    structured_output: BaseModel | None = None
+    cost: float | None = None
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    cached_tokens: int | None = None
+
+
+# --- Streaming event types ---
+
+
+# to expose to the front USER
+class TextDelta(BaseModel):
+    """A chunk of text content from the LLM."""
+
+    type: Literal["text_delta"] = "text_delta"
+    content: str
+
+
+# to expose to the front USER
+class ToolCallDone(BaseModel):
+    """A fully assembled tool call."""
+
+    type: Literal["tool_call_done"] = "tool_call_done"
+    tool_call: ToolCall
+
+
+# to expose after each message sent to user
+class StreamUsage(BaseModel):
+    """Token usage and cost info, emitted near the end of the stream."""
+
+    type: Literal["usage"] = "usage"
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    cached_tokens: int | None = None
+    cost: float | None = None
+
+
+class ReasoningDelta(BaseModel):
+    """A chunk of reasoning/thinking text from the LLM.
+
+    What this carries depends on the provider: open models served by
+    vLLM/DeepSeek-style backends stream the raw chain of thought
+    (``delta.reasoning_content``), OpenRouter normalizes reasoning to
+    ``delta.reasoning``, while OpenAI models never expose raw reasoning
+    — at best a summarized version, and nothing at all on the plain
+    Chat Completions API. Display-only: never feed it back into the
+    conversation.
+    """
+
+    type: Literal["reasoning_delta"] = "reasoning_delta"
+    content: str
+
+
+class InputJsonDelta(BaseModel):
+    """A chunk of tool-call argument JSON from the LLM.
+
+    Emitted incrementally as the LLM streams tool-call input, *before*
+    the fully assembled ``ToolCallDone`` event.  Consumers can use this
+    to extract and display partial structured output (e.g. streaming the
+    text part of a final-answer tool).
+    """
+
+    type: Literal["input_json_delta"] = "input_json_delta"
+    tool_call_index: int
+    tool_name: str
+    partial_json: str
+
+
+class StreamDone(BaseModel):
+    """Sentinel event: the stream is complete. Carries the final assembled LLMResponse."""
+
+    type: Literal["done"] = "done"
+    response: LLMResponse
+
+
+StreamEvent = TextDelta | ReasoningDelta | InputJsonDelta | ToolCallDone | StreamUsage | StreamDone
+
+
+async def text_stream(
+    events: AsyncGenerator[StreamEvent, None],
+) -> AsyncGenerator[str, None]:
+    """Extract just the text deltas from a stream."""
+    async for event in events:
+        if isinstance(event, TextDelta):
+            yield event.content
+
+
+# --- Callable signature ---
+
+
+class LLMCallable(Protocol):
+    """Async LLM call: ``(messages, response_format, tools) -> LLMResponse``.
+
+    A Protocol rather than a plain ``Callable`` alias so that
+    ``response_format`` and ``tools`` stay optional at the call site, which
+    is how every implementation and caller actually uses them.
+
+    The return is a ``Coroutine`` rather than the looser ``Awaitable``:
+    ``make_sync()`` drives these through ``asyncio.run_coroutine_threadsafe``,
+    which rejects awaitables that aren't coroutines.
+    """
+
+    def __call__(
+        self,
+        messages: list[Message],
+        response_format: type[BaseModel] | dict[str, Any] | None = None,
+        tools: list[ToolDef] | None = None,
+    ) -> Coroutine[Any, Any, LLMResponse]: ...
+
+
+SyncLLMCallable = Callable[
+    [list[Message], type[BaseModel] | dict[str, Any] | None, list[ToolDef] | None],
+    LLMResponse,
+]
+"""Synchronous version of ``LLMCallable``."""
+
+
+def make_sync(fn: LLMCallable) -> SyncLLMCallable:
+    """Wrap an async ``LLMCallable`` into a synchronous callable.
+
+    Uses a persistent background event loop so that async SDK clients
+    (httpx, etc.) can clean up properly without "Event loop is closed" errors.
+    """
+    from dot_inference._sync import run_sync
+
+    def wrapper(
+        messages: list[Message],
+        schema: type[BaseModel] | dict[str, Any] | None = None,
+        tools: list[ToolDef] | None = None,
+    ) -> LLMResponse:
+        return run_sync(fn(messages, schema, tools))
+
+    return wrapper
+
+
+"""Signature: (messages, response_format_or_none, tools_or_none) -> LLMResponse"""
+
+LLMStreamCallable = Callable[
+    [list[Message], type[BaseModel] | dict[str, Any] | None, list[ToolDef] | None],
+    AsyncGenerator[StreamEvent, None],
+]
+"""Signature: (messages, response_format, tools) -> AsyncGenerator yielding StreamEvent."""
+
+EmbeddingCallable = Callable[
+    [list[str]],
+    Coroutine[Any, Any, list[list[float]]],
+]
+"""Signature: (texts) -> list of embedding vectors. Batching is handled internally."""

dot_inference/mock.py

@@ -0,0 +1,151 @@
+# SPDX-FileCopyrightText: Kannon For Deep Tech
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Mock clients for testing without API calls."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from pydantic import BaseModel
+
+from dot_inference._client import EmbeddingClient, LLMClient
+from dot_inference._types import (
+    LLMResponse,
+    Message,
+    StreamDone,
+    StreamEvent,
+    StreamUsage,
+    TextDelta,
+    ToolCall,
+    ToolCallDone,
+    ToolDef,
+)
+
+
+def make_dummy_instance(model_cls: type[BaseModel]) -> BaseModel:
+    """Recursively build a dummy instance of a Pydantic model."""
+    values: dict[str, Any] = {}
+    for name, field_info in model_cls.model_fields.items():
+        annotation = field_info.annotation
+        if annotation is bool:
+            values[name] = True
+        elif annotation is int:
+            values[name] = 42
+        elif annotation is float:
+            values[name] = 3.14
+        elif annotation is str:
+            values[name] = f"mock_{name}"
+        elif hasattr(annotation, "__members__"):  # Enum types
+            values[name] = next(iter(annotation.__members__.values()))
+        elif isinstance(annotation, type) and issubclass(annotation, BaseModel):
+            values[name] = make_dummy_instance(annotation)
+        else:
+            values[name] = None
+    return model_cls(**values)
+
+
+class MockLLMClient(LLMClient):
+    """LLM client that returns canned responses without API calls.
+
+    Useful for testing pipelines without incurring costs or requiring
+    API keys.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._client = None
+        self._model = "mock"
+        self._model_config = None
+        self._temperature = None
+        self._reasoning_effort = None
+        self._max_tokens = None
+
+    async def call(
+        self,
+        messages: list[Message],
+        response_format: type[BaseModel] | dict[str, Any] | None = None,
+        tools: list[ToolDef] | None = None,
+        *,
+        temperature: float | None = None,
+        reasoning_effort: str | None = None,
+        tool_choice: str | None = None,
+    ) -> LLMResponse:
+        structured_output = None
+        if isinstance(response_format, type) and issubclass(response_format, BaseModel):
+            structured_output = make_dummy_instance(response_format)
+
+        user_content = (messages[-1].content or "") if messages else ""
+        content = f"[MOCK] User: {user_content}"
+
+        return LLMResponse(
+            content=content,
+            structured_output=structured_output,
+            cost=0.0,
+            prompt_tokens=0,
+            completion_tokens=0,
+        )
+
+    async def stream(
+        self,
+        messages: list[Message],
+        response_format: type[BaseModel] | dict[str, Any] | None = None,
+        tools: list[ToolDef] | None = None,
+        *,
+        temperature: float | None = None,
+        reasoning_effort: str | None = None,
+        tool_choice: str | None = None,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        user_content = (messages[-1].content or "") if messages else ""
+
+        if tools:
+            mock_tool_calls: list[ToolCall] = []
+            for i, tool in enumerate(tools):
+                mock_args = '{"mock": true}'
+                tc = ToolCall(id=f"mock_call_{i}", name=tool.name, arguments=mock_args)
+                yield ToolCallDone(tool_call=tc)
+                mock_tool_calls.append(tc)
+            yield StreamUsage(prompt_tokens=0, completion_tokens=0, cost=0.0)
+            yield StreamDone(
+                response=LLMResponse(
+                    tool_calls=mock_tool_calls,
+                    cost=0.0,
+                    prompt_tokens=0,
+                    completion_tokens=0,
+                )
+            )
+        else:
+            fake_response = f"[MOCK STREAM] {user_content}"
+            for i in range(0, len(fake_response), 10):
+                await asyncio.sleep(0.01)
+                yield TextDelta(content=fake_response[i : i + 10])
+
+            structured_output = None
+            if isinstance(response_format, type) and issubclass(response_format, BaseModel):
+                structured_output = make_dummy_instance(response_format)
+
+            yield StreamUsage(prompt_tokens=0, completion_tokens=0, cost=0.0)
+            yield StreamDone(
+                response=LLMResponse(
+                    content=fake_response,
+                    structured_output=structured_output,
+                    cost=0.0,
+                    prompt_tokens=0,
+                    completion_tokens=0,
+                )
+            )
+
+
+class MockEmbeddingClient(EmbeddingClient):
+    """Embedding client that returns deterministic vectors without API calls."""
+
+    def __init__(self, dimension: int = 8) -> None:
+        self._client = None
+        self._model = "mock-embed"
+        self._batch_size = 0
+        self._dimension = dimension
+
+    async def embed(self, texts: list[str]) -> list[list[float]]:
+        return [[float(i) * 0.1] * self._dimension for i in range(len(texts))]