padwan-ai 0.11.0__tar.gz

padwan_ai-0.11.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.3
+Name: padwan-ai
+Version: 0.11.0
+Author-email: julien.brayere@polarsen.io
+Requires-Dist: niquests>=3.21.0
+Requires-Dist: qh3>=1.7.1
+Requires-Dist: urllib3-future>=2.24.904
+Requires-Dist: langfuse>=4.9 ; extra == 'langfuse'
+Requires-Dist: opentelemetry-api>=1.44 ; extra == 'langfuse'
+Requires-Dist: opentelemetry-api>=1.44 ; extra == 'otel'
+Requires-Dist: niquests[ws]>=3.21.0 ; extra == 'realtime'
+Requires-Python: >=3.13
+Provides-Extra: langfuse
+Provides-Extra: otel
+Provides-Extra: realtime

padwan_ai-0.11.0/padwan_ai/__init__.py

@@ -0,0 +1,197 @@
+# Python 3.15 defers these imports; older runtimes ignore the declaration.
+__lazy_modules__ = frozenset(
+    {
+        "padwan_ai._base",
+        "padwan_ai._deprecation",
+        "padwan_ai.agent",
+        "padwan_ai.anthropic",
+        "padwan_ai.audio",
+        "padwan_ai.client",
+        "padwan_ai.content",
+        "padwan_ai.conversation",
+        "padwan_ai.errors",
+        "padwan_ai.gemini",
+        "padwan_ai.grok",
+        "padwan_ai.mcp",
+        "padwan_ai.mistral",
+        "padwan_ai.models",
+        "padwan_ai.openai",
+        "padwan_ai.typesafe",
+        "padwan_ai.vision",
+    }
+)
+
+from importlib.metadata import version as _pkg_version
+
+from ._base import ChatStream, LLMClientBase, OnThought, RealtimeClientBase
+from ._deprecation import ModelDeprecationWarning
+from .agent import (
+    AgentOutput,
+    AgentSession,
+    ConversationStore,
+    OnMcpConnect,
+    ToolCallContext,
+)
+from .anthropic import (
+    ANTHROPIC_MODELS,
+    AnthropicClient,
+    AnthropicModel,
+    is_anthropic_model,
+)
+from .audio import supports_audio
+from .client import LLMClient, RealtimeClient
+from .content import (
+    AudioFormat,
+    ContentAudioPart,
+    ContentImagePart,
+    ContentPart,
+    ContentTextPart,
+    audio_part,
+    content_parts,
+    image_part,
+    text_file_part,
+    text_part,
+)
+from .conversation import (
+    AssistantToolMessage,
+    ChatMessage,
+    ConversationSnapshot,
+    ConversationState,
+    Message,
+    ToolResultMessage,
+)
+from .errors import LLMError, OutputError, Provider
+from .gemini import (
+    GEMINI_MODELS,
+    GeminiClient,
+    GeminiModel,
+    GeminiRealtimeClient,
+    GeminiRealtimeConnection,
+    is_gemini_model,
+)
+from .grok import GROK_MODELS, GrokClient, GrokModel, GrokRealtimeClient, is_grok_model
+from .mcp import McpStdio, McpStreamable, McpTool, McpTransport, OnAuth, ProgressEvent
+from .mistral import MISTRAL_MODELS, MistralClient, MistralModel, is_mistral_model
+from .models import (
+    ChatResponse,
+    FinishReason,
+    ToolCall,
+    ToolCallFunction,
+    ToolDefinition,
+    UsageToken,
+)
+from .openai import (
+    OPENAI_CHAT_MODELS,
+    OPENAI_MODELS,
+    OpenAIClient,
+    OpenAIModel,
+    OpenAIRealtimeClient,
+    RealtimeConnection,
+    RealtimeServerEvent,
+    is_openai_model,
+)
+from .typesafe import (
+    TYPESAFE_MODELS,
+    ChoiceAnswer,
+    ChoiceQuestion,
+    NoulAnswer,
+    NoulCriteria,
+    NoulQuestion,
+    ScoreAnswer,
+    ScoreQuestion,
+    SystemOneResponse,
+    TypeSafeClient,
+    TypeSafeModel,
+    TypeSafeUsage,
+)
+from .vision import supports_vision
+
+__all__ = (
+    "ANTHROPIC_MODELS",
+    "GEMINI_MODELS",
+    "GROK_MODELS",
+    "MISTRAL_MODELS",
+    "OPENAI_CHAT_MODELS",
+    "OPENAI_MODELS",
+    "TYPESAFE_MODELS",
+    "AgentOutput",
+    "AgentSession",
+    "AnthropicClient",
+    "AnthropicModel",
+    "AssistantToolMessage",
+    "AudioFormat",
+    "ChatMessage",
+    "ChatResponse",
+    "ChatStream",
+    "ChoiceAnswer",
+    "ChoiceQuestion",
+    "ContentAudioPart",
+    "ContentImagePart",
+    "ContentPart",
+    "ContentTextPart",
+    "ConversationSnapshot",
+    "ConversationState",
+    "ConversationStore",
+    "FinishReason",
+    "GeminiClient",
+    "GeminiModel",
+    "GeminiRealtimeClient",
+    "GeminiRealtimeConnection",
+    "GrokClient",
+    "GrokModel",
+    "GrokRealtimeClient",
+    "LLMClient",
+    "LLMClientBase",
+    "LLMError",
+    "McpStdio",
+    "McpStreamable",
+    "McpTool",
+    "McpTransport",
+    "Message",
+    "MistralClient",
+    "MistralModel",
+    "ModelDeprecationWarning",
+    "OnAuth",
+    "OnMcpConnect",
+    "OnThought",
+    "OpenAIClient",
+    "OpenAIModel",
+    "OpenAIRealtimeClient",
+    "NoulAnswer",
+    "NoulCriteria",
+    "NoulQuestion",
+    "OutputError",
+    "ProgressEvent",
+    "Provider",
+    "RealtimeClient",
+    "RealtimeClientBase",
+    "RealtimeConnection",
+    "RealtimeServerEvent",
+    "ScoreAnswer",
+    "ScoreQuestion",
+    "SystemOneResponse",
+    "ToolCall",
+    "ToolCallContext",
+    "ToolCallFunction",
+    "ToolDefinition",
+    "ToolResultMessage",
+    "TypeSafeClient",
+    "TypeSafeModel",
+    "TypeSafeUsage",
+    "UsageToken",
+    "__version__",
+    "audio_part",
+    "content_parts",
+    "image_part",
+    "is_anthropic_model",
+    "is_gemini_model",
+    "is_grok_model",
+    "is_mistral_model",
+    "is_openai_model",
+    "supports_audio",
+    "supports_vision",
+    "text_file_part",
+    "text_part",
+)
+
+__version__: str = _pkg_version("padwan-ai")

padwan_ai-0.11.0/padwan_ai/__main__.py

@@ -0,0 +1,127 @@
+import argparse
+import asyncio
+import json
+import sys
+from typing import Any
+
+from ._base import OnThought
+from .client import LLMClient
+from .conversation import Message
+
+
+def _make_thought_streamer() -> OnThought:
+    def on_thought(chunk: str) -> None:
+        sys.stderr.write(chunk)
+        sys.stderr.flush()
+
+    return on_thought
+
+
+async def _run(
+    model: str,
+    prompt: str,
+    base_url: str | None = None,
+    extra_params: dict[str, Any] | None = None,
+    stream_thinking: bool = False,
+    debug: bool = False,
+    pretty: bool = False,
+) -> None:
+    on_thought: OnThought | None = _make_thought_streamer() if stream_thinking else None
+    client = LLMClient(model=model, base_url=base_url, on_thought=on_thought)
+    messages: list[Message] = [Message(role="user", content=prompt)]
+    async with client:
+        if debug:
+            body: dict[str, Any] = {
+                "model": model,
+                "messages": list(messages),
+                "temperature": client.temperature,
+                "stream_options": {"include_usage": True},
+            }
+            if extra_params:
+                body.update(extra_params)
+            async for raw in client.stream(body):
+                sys.stderr.write(json.dumps(raw, indent=2 if pretty else None) + "\n")
+                sys.stderr.flush()
+                if choices := raw.get("choices"):
+                    delta = choices[0].get("delta") or {}
+                    if text := delta.get("content"):
+                        sys.stdout.write(text)
+                        sys.stdout.flush()
+        else:
+            stream = client.stream_chat(messages, extra_params=extra_params)
+            async for chunk in stream:
+                sys.stdout.write(chunk)
+                sys.stdout.flush()
+            if reason := getattr(stream, "finish_reason", None):
+                if reason != "stop":
+                    sys.stderr.write(f"\n[finish_reason: {reason}]\n")
+                    sys.stderr.flush()
+    print()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="padwan-ai",
+        description="One-shot LLM query",
+    )
+    parser.add_argument("prompt", help="Prompt to send")
+    parser.add_argument("-m", "--model", default="gpt-4o-mini", help="Model to use")
+    parser.add_argument(
+        "--base-url", default=None, help="Custom base URL for the LLM provider"
+    )
+    parser.add_argument(
+        "--extra-params",
+        default=None,
+        metavar="JSON",
+        help="Extra JSON parameters merged into the request body (e.g. '{\"temperature\": 0}')",
+    )
+    parser.add_argument(
+        "--stream-thinking",
+        action="store_true",
+        default=False,
+        help="Stream model reasoning/thinking tokens to stderr",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Print raw SSE chunks as JSON to stderr",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        default=False,
+        help="Pretty-print --debug JSON output (implies --debug)",
+    )
+    args = parser.parse_args()
+
+    extra_params: dict[str, Any] | None = None
+    if args.extra_params is not None:
+        try:
+            extra_params = json.loads(args.extra_params)
+        except json.JSONDecodeError as e:
+            print(f"Error: --extra-params is not valid JSON: {e}", file=sys.stderr)
+            raise SystemExit(1)
+        if not isinstance(extra_params, dict):
+            print("Error: --extra-params must be a JSON object", file=sys.stderr)
+            raise SystemExit(1)
+
+    try:
+        asyncio.run(
+            _run(
+                args.model,
+                args.prompt,
+                args.base_url,
+                extra_params,
+                args.stream_thinking,
+                args.debug or args.pretty,
+                args.pretty,
+            )
+        )
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

padwan_ai-0.11.0/padwan_ai/_base.py

@@ -0,0 +1,338 @@
+from __future__ import annotations
+
+import abc
+import os
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping, Sequence
+from contextlib import AbstractAsyncContextManager
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, ClassVar, Self
+
+import niquests
+from niquests.typing import JSONEncoderType
+from urllib3.util.retry import Retry
+
+from ._deprecation import warn_if_deprecated
+from .conversation import ChatMessage
+from .errors import LLMError, Provider
+from .logs import log
+from .models import ChatResponse, ToolCall, ToolDefinition, UsageToken
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+__all__ = (
+    "NO_TURN_DETECTION",
+    "ChatStream",
+    "LLMClientBase",
+    "OnThought",
+    "Provider",
+    "RealtimeClientBase",
+)
+
+OnThought = Callable[[str], None]
+
+# Pass as ``turn_detection`` to disable server-side VAD (manual / push-to-talk);
+# you then drive each turn yourself with the provider's manual-turn methods.
+NO_TURN_DETECTION = "none"
+
+
+class ChatStream(abc.ABC):
+    """Async iterator that yields text chunks and captures usage/tool_calls after iteration."""
+
+    usage: UsageToken | None = None
+    tool_calls: list[ToolCall] | None = None
+
+    @abc.abstractmethod
+    def __aiter__(self) -> AsyncIterator[str]:
+        """Iterate over text chunks from the stream."""
+        ...
+
+
+def env_api_key(provider: Provider, var: str) -> str:
+    """Read an API key from environment variable *var*, raising :class:`LLMError` if unset."""
+    api_key = os.environ.get(var)
+    if not api_key:
+        raise LLMError(provider, f"{var} not set")
+    return api_key
+
+
+def to_sse_url(url: str) -> str:
+    """Convert http(s):// URL to the niquests SSE scheme (``sse://`` or ``psse://``)."""
+    stripped = url.removeprefix("https://")
+    if stripped is not url:
+        return "sse://" + stripped
+    return "psse://" + url.removeprefix("http://")
+
+
+@dataclass
+class LLMClientBase[RetryT: Retry](abc.ABC):
+    """Abstract base class for LLM provider clients.
+
+    Use provider-specific clients (OpenAIClient, GeminiClient, etc.) instead.
+    """
+
+    provider: ClassVar[Provider]
+    _deprecations: ClassVar[Mapping[str, str]] = {}
+    """Model id -> retirement date for provider-deprecated models. Set per provider."""
+    _retry: RetryT
+
+    model: str | None = None
+    """Default model to use (e.g., 'gpt-4o', 'gemini-2.5-flash')."""
+    temperature: float = 0.2
+    """Sampling temperature."""
+    timeout: float = 60
+    """Request timeout in seconds."""
+    api_key: str | None = field(default=None, repr=False)
+    """API key. If None, reads from provider's environment variable."""
+    on_thought: OnThought | None = field(default=None, repr=False)
+    """Callback invoked with each chunk of model "thinking" / reasoning text.
+    Clients that don't support thinking yet simply never
+    invoke it."""
+    json_encoder: JSONEncoderType | None = field(default=None, repr=False)
+    """Serializer applied to ``json=`` request payloads (e.g. a msgspec/pydantic
+    encoder returning str or bytes). None keeps niquests' default encoding."""
+
+    _api_key: str = field(init=False, repr=False)
+    base_url: str = field(init=False, default="", repr=False)
+    _session: niquests.AsyncSession | None = field(init=False, default=None, repr=False)
+
+    @property
+    def max_retries(self) -> int | None:
+        """Maximum retry attempts, derived from _retry config. None means unlimited, 0 means disabled."""
+        total = self._retry.total
+        if total is False:
+            return 0
+        if total is None:
+            return None
+        return int(total)
+
+    def __post_init__(self) -> None:
+        warn_if_deprecated(self.provider, self.model, self._deprecations)
+        self._api_key = self.api_key or self._get_default_api_key()
+
+    @abc.abstractmethod
+    def _get_default_api_key(self) -> str:
+        """Get API key from environment."""
+        ...
+
+    @abc.abstractmethod
+    def _set_auth_headers(self, session: niquests.AsyncSession) -> None:
+        """Set provider-specific authentication headers."""
+        ...
+
+    @property
+    def session(self) -> niquests.AsyncSession:
+        """Get active session, raising if not initialized."""
+        if self._session is None:
+            raise LLMError(
+                self.provider, "Client not initialized. Use async context manager."
+            )
+        return self._session
+
+    async def _iter_sse(
+        self, resp: niquests.Response, done_sentinel: str | None = None
+    ) -> AsyncGenerator[dict]:
+        """Yield parsed JSON payloads from an SSE response, stopping at
+        *done_sentinel* and closing a half-read stream so its pooled
+        connection is released (a leaked lease starves later requests)."""
+        ext = resp.extension
+        if ext is None:
+            raise LLMError(self.provider, "SSE extension not available on response")
+        try:
+            while not ext.closed:
+                event = await ext.next_payload()
+                if event is None:
+                    break
+                if not event.data:
+                    continue
+                if event.data == done_sentinel:
+                    break
+                try:
+                    yield event.json()
+                except ValueError as e:
+                    raise LLMError(self.provider, f"Stream parse error: {e}") from e
+        finally:
+            if not ext.closed:
+                # Best-effort: aborting an already-finished HTTP/2 stream raises
+                # inside urllib3-future (KeyError on the stream id); a cleanup
+                # failure must never corrupt an otherwise successful stream.
+                try:
+                    await ext.close()
+                except Exception as e:
+                    log.debug("SSE extension close failed: %s", e)
+                if (raw := resp.raw) is not None:
+                    try:
+                        await raw.close()
+                    except Exception as e:
+                        log.debug("SSE raw close failed: %s", e)
+                    release_conn = getattr(raw, "release_conn", None)
+                    if release_conn is not None:
+                        try:
+                            release_conn()
+                        except Exception as e:
+                            log.debug("SSE connection release failed: %s", e)
+
+    def _sse_url(self, path: str) -> str:
+        """Build a full SSE-scheme URL for the given path.
+
+        niquests activates its SSE extension (``r.extension``) only when
+        the request URL uses the ``sse://`` (TLS) or ``psse://`` (plain)
+        scheme. This helper resolves *path* against ``base_url`` and
+        swaps the scheme so streaming requests get proper SSE parsing.
+        """
+        return to_sse_url(self.base_url.rstrip("/") + "/" + path.lstrip("/"))
+
+    async def __aenter__(self) -> Self:
+        if self._session is not None:
+            raise RuntimeError(
+                f"{type(self).__name__} is already open; "
+                "using the same client in nested `async with` blocks is not supported"
+            )
+        self._session = niquests.AsyncSession(
+            timeout=self.timeout,
+            retries=self._retry,
+            base_url=self.base_url,
+            json_encoder=self.json_encoder,
+        )
+        self._set_auth_headers(self._session)
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._session:
+            try:
+                await self._session.close()
+            finally:
+                self._session = None
+
+    @abc.abstractmethod
+    async def complete(self, body: Any) -> tuple[Any, UsageToken]:
+        """Fetch a structured completion from the provider.
+
+        Each provider defines its own body and response types.
+        """
+        ...
+
+    @abc.abstractmethod
+    def stream(self, body: Any) -> AsyncIterator[Any]:
+        """Stream chat completions, yielding response chunks as they arrive.
+
+        Each provider defines its own body and response types.
+        """
+        ...
+
+    @abc.abstractmethod
+    def stream_chat(
+        self,
+        messages: Sequence[ChatMessage],
+        tools: Sequence[ToolDefinition] | None = None,
+        extra_params: dict[str, Any] | None = None,
+    ) -> ChatStream:
+        """Stream a chat conversation, yielding text chunks.
+
+        This is a higher-level API than stream() that handles provider-specific
+        body building and response extraction. Usage and tool_calls are available
+        on the returned ChatStream object after iteration completes.
+
+        The optional ``extra_params`` dict is merged into the request body before
+        it is sent, letting callers pass provider-specific fields that are not
+        part of the standard interface (e.g. NVIDIA's ``chat_template_kwargs``).
+        Providers that don't support extra body fields may silently ignore it.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def complete_chat(
+        self,
+        messages: Sequence[ChatMessage],
+        tools: Sequence[ToolDefinition] | None = None,
+    ) -> tuple[ChatResponse, UsageToken]:
+        """Send a chat conversation and return the structured response.
+
+        Returns a ChatResponse with content, optional tool_calls, and finish_reason,
+        along with token usage.
+        """
+        ...
+
+
+@dataclass
+class RealtimeClientBase[ConnT](abc.ABC):
+    """Abstract base for realtime speech-to-speech clients over a WebSocket."""
+
+    provider: ClassVar[Provider]
+
+    model: str
+    api_key: str | None = field(default=None, repr=False)
+    base_url: str = field(kw_only=True)
+    timeout: float = 30.0
+    session_kwargs: Mapping[str, Any] | None = field(default=None, repr=False)
+    """Constructor arguments (e.g. proxies) for the managed ``AsyncSession``."""
+
+    _api_key: str = field(init=False, repr=False)
+    _session: niquests.AsyncSession | None = field(init=False, default=None, repr=False)
+    _conn_cm: AbstractAsyncContextManager[Any] | None = field(
+        init=False, default=None, repr=False
+    )
+
+    def __post_init__(self) -> None:
+        self._api_key = self.api_key or self._get_default_api_key()
+
+    @property
+    def session(self) -> niquests.AsyncSession:
+        """Get active session, raising if not initialized."""
+        if self._session is None:
+            raise LLMError(
+                self.provider, "Client not initialized. Use async context manager."
+            )
+        return self._session
+
+    async def __aenter__(self) -> ConnT:
+        if self._session is not None:
+            raise RuntimeError(
+                f"{type(self).__name__} is already open; "
+                "using the same client in nested `async with` blocks is not supported"
+            )
+        self._session = niquests.AsyncSession(**(self.session_kwargs or {}))
+        self._set_auth_headers(self._session)
+        try:
+            self._conn_cm = self._connect()
+            return await self._conn_cm.__aenter__()
+        except BaseException:
+            await self.__aexit__(None, None, None)
+            raise
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        try:
+            if self._conn_cm is not None:
+                await self._conn_cm.__aexit__(exc_type, exc_val, exc_tb)
+        finally:
+            self._conn_cm = None
+            if self._session:
+                try:
+                    await self._session.close()
+                finally:
+                    self._session = None
+
+    @abc.abstractmethod
+    def _get_default_api_key(self) -> str:
+        """Get API key from environment."""
+        ...
+
+    @abc.abstractmethod
+    def _set_auth_headers(self, session: niquests.AsyncSession) -> None:
+        """Set provider-specific authentication headers."""
+        ...
+
+    @abc.abstractmethod
+    def _connect(self) -> AbstractAsyncContextManager[ConnT]:
+        """Open the provider handshake over the client's session."""
+        ...