pop-python 1.0.4__py3-none-any.whl → 1.1.0__py3-none-any.whl

POP/providers/doubao_client.py

@@ -0,0 +1,101 @@
+"""Doubao (Volcengine Ark) API client implementation.
+
+This client wraps the Doubao chat completion endpoint.  It requires
+the ``openai`` package because Doubao is compatible with the OpenAI
+client library when configured with a custom base URL.  If the
+package is missing, instantiating :class:`DoubaoClient` will raise an
+error.
+"""
+
+from typing import List, Dict, Any
+from os import getenv
+
+from .llm_client import LLMClient
+
+
+try:
+    from openai import OpenAI
+except Exception:
+    OpenAI = None  # type: ignore
+
+
+class DoubaoClient(LLMClient):
+    """Client for Doubao (Volcengine Ark) LLMs."""
+
+    def __init__(self, model = None) -> None:
+        if OpenAI is None:
+            raise ImportError(
+                "openai package is not installed. Install it to use DoubaoClient."
+            )
+        # Use the custom base URL for Doubao.  Requires DOUBAO_API_KEY.
+        self.client = OpenAI(
+            base_url="https://ark.cn-beijing.volces.com/api/v3",
+            api_key=getenv("DOUBAO_API_KEY"),
+        )
+        self.model_name = model
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str,
+        temperature: float = 0.0,
+        **kwargs: Any,
+    ) -> Any:
+        payload: Dict[str, Any] = {
+            "model": model,
+            "messages": [],
+            "temperature": temperature,
+        }
+
+        # Normalize images input into a list
+        images = kwargs.pop("images", None)
+        if images and not isinstance(images, list):
+            images = [images]
+
+        # Copy through common generation options supported by Doubao
+        passthrough = [
+            "top_p",
+            "max_tokens",
+            "stop",
+            "frequency_penalty",
+            "presence_penalty",
+            "logprobs",
+            "top_logprobs",
+            "logit_bias",
+            "service_tier",
+            "thinking",
+            "stream",
+            "stream_options",
+        ]
+        for key in passthrough:
+            if key in kwargs and kwargs[key] is not None:
+                payload[key] = kwargs[key]
+
+        # Build messages, attaching images to user messages
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if images and role == "user":
+                multi: List[Any] = [{"type": "text", "text": content}]
+                for img in images:
+                    if isinstance(img, str) and img.startswith("http"):
+                        multi.append({"type": "image_url", "image_url": {"url": img}})
+                    else:
+                        multi.append({"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img}"}})
+                content = multi
+            payload["messages"].append({"role": role, "content": content})
+
+        # Function tools
+        tools = kwargs.get("tools")
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = kwargs.get("tool_choice", "auto")
+
+        try:
+            response = self.client.chat.completions.create(**payload)
+        except Exception as exc:
+            raise RuntimeError(f"Doubao chat_completion error: {exc}") from exc
+        return response
+
+
+__all__ = ["DoubaoClient"]

POP/providers/gemini_client.py

@@ -0,0 +1,119 @@
+"""Gemini API client implementation.
+
+This module provides a :class:`LLMClient` implementation for Google
+Gemini models.  It wraps the ``google.genai`` client so that
+responses conform to the expected OpenAI‑like structure used by
+:class:`pop.prompt_function.PromptFunction`.
+
+If the ``google-genai`` library is unavailable, importing
+this module will not error, but instantiating :class:`GeminiClient`
+will raise an :class:`ImportError`.
+"""
+
+from typing import List, Dict, Any, Optional
+from os import getenv
+
+from .llm_client import LLMClient
+
+
+try:
+    from google import genai  # type: ignore
+    from google.genai import types  # type: ignore
+except Exception:
+    genai = None  # type: ignore
+    types = None  # type: ignore
+
+
+class GeminiClient(LLMClient):
+    """Client for Google's Gemini models."""
+
+    def __init__(self, model: str = "gemini-2.5-flash") -> None:
+        if genai is None or types is None:
+            raise ImportError(
+                "google-genai package is not installed. Install it to use GeminiClient."
+            )
+        # Authenticate with the API key
+        self.client = genai.Client(api_key=getenv("GEMINI_API_KEY"))
+        self.model_name = model
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: Optional[str] = None,
+        temperature: float = 0.0,
+        **kwargs: Any,
+    ) -> Any:
+        model_name = model or self.model_name
+
+        # Extract system instruction and collate user/assistant content
+        system_instruction: Optional[str] = None
+        user_contents: List[str] = []
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system" and system_instruction is None:
+                system_instruction = content
+            else:
+                user_contents.append(content)
+
+        # Prepare multimodal contents.  Gemini accepts a list of
+        # strings/images; embed images if passed via kwargs.
+        contents: List[Any] = []
+        images = kwargs.pop("images", None)
+        if images:
+            try:
+                from PIL import Image  # type: ignore
+                import base64
+                from io import BytesIO
+            except Exception:
+                raise ImportError("PIL and base64 are required for image support in GeminiClient.")
+            for img in images:
+                # Accept PIL.Image, base64 string or URL
+                if isinstance(img, Image.Image):
+                    contents.append(img)
+                elif isinstance(img, str):
+                    try:
+                        # Assume base64 encoded image
+                        img_data = base64.b64decode(img)
+                        image = Image.open(BytesIO(img_data))  # type: ignore
+                        contents.append(image)
+                    except Exception:
+                        # Fallback to URL
+                        contents.append(img)
+        # Add concatenated text as the last element
+        if user_contents:
+            contents.append("\n".join(user_contents))
+
+        # Configure generation
+        gen_config = types.GenerateContentConfig(
+            temperature=temperature,
+            system_instruction=system_instruction,
+        )
+
+        try:
+            response = self.client.models.generate_content(
+                model=model_name,
+                contents=contents,
+                config=gen_config,
+            )
+        except Exception as exc:
+            raise RuntimeError(f"Gemini chat_completion error: {exc}") from exc
+
+        # Wrap the Gemini response into an OpenAI‑like structure
+        class FakeMessage:
+            def __init__(self, content: str):
+                self.content = content
+                self.tool_calls = None
+
+        class FakeChoice:
+            def __init__(self, message: FakeMessage):
+                self.message = message
+
+        class FakeResponse:
+            def __init__(self, text: str):
+                self.choices = [FakeChoice(FakeMessage(text))]
+
+        return FakeResponse(response.text or "")
+
+
+__all__ = ["GeminiClient"]

POP/providers/llm_client.py

@@ -0,0 +1,60 @@
+"""Abstract interface for LLM clients.
+
+This module defines the :class:`LLMClient` abstract base class used by
+provider implementations.  Each provider must implement a
+``chat_completion`` method that accepts a list of message dictionaries
+([{role: str, content: str}]), a ``model`` name, a ``temperature``, and
+any additional keyword arguments.  The method should return an object
+with a ``choices`` attribute similar to OpenAI's response schema where
+``choices[0].message.content`` contains the generated text.  If the
+provider supports tool calling it should also populate
+``choices[0].message.tool_calls`` accordingly.
+
+Original POP placed all provider implementations in a single file.
+This module holds only the abstract base class; see the
+``pop/providers`` subpackage for concrete clients.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any
+
+
+class LLMClient(ABC):
+    """Abstract base class for LLM clients."""
+
+    @abstractmethod
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str,
+        temperature: float = 0.0,
+        **kwargs: Any,
+    ) -> Any:
+        """Generate a chat completion.
+
+        Parameters
+        ----------
+        messages : list of dict
+            Messages in the conversation.  Each dict must have a
+            ``role`` (e.g. ``"system"``, ``"user"``, ``"assistant"``) and
+            ``content`` (the text of the message).  Implementations may
+            support additional keys (for example a list of
+            ``images``) but should document this behaviour.
+        model : str
+            Identifier for the model variant (e.g. ``"gpt-3.5-turbo"`` or
+            provider‑specific names).
+        temperature : float, optional
+            Controls the randomness of the output.  The default of 0.0
+            yields deterministic output for many providers.
+        **kwargs : Any
+            Provider‑specific options such as ``tools``, ``response_format``
+            or image attachments.
+        Returns
+        -------
+        Any
+            A provider‑specific response object.  Consumers should not
+            rely on the exact type; instead they should access
+            ``response.choices[0].message.content`` for the text and
+            ``response.choices[0].message.tool_calls`` if present.
+        """
+        raise NotImplementedError

POP/providers/local_client.py

@@ -0,0 +1,45 @@
+"""Local PyTorch LLM client.
+
+This client provides a minimal placeholder implementation of an
+LLM client that runs locally using PyTorch.  Because actual model
+weights are not included in this distribution, the client returns a
+static response indicating that it is a stub.  You can extend this
+class to load and run a local model (for example via HuggingFace
+transformers) if desired.
+"""
+
+from typing import List, Dict, Any
+
+from .llm_client import LLMClient
+
+
+class LocalPyTorchClient(LLMClient):
+    """Placeholder client for local PyTorch models."""
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str,
+        temperature: float = 0.0,
+        **kwargs: Any,
+    ) -> Any:
+        # This stub simply returns a canned response.  Real
+        # implementations should load a local model and generate a
+        # response based on the messages and parameters.
+        class FakeMessage:
+            def __init__(self, content: str):
+                self.content = content
+                self.tool_calls = None
+
+        class FakeChoice:
+            def __init__(self, message: FakeMessage):
+                self.message = message
+
+        class FakeResponse:
+            def __init__(self, text: str):
+                self.choices = [FakeChoice(FakeMessage(text))]
+
+        return FakeResponse("Local PyTorch LLM response (stub)")
+
+
+__all__ = ["LocalPyTorchClient"]

POP/providers/ollama_client.py

@@ -0,0 +1,129 @@
+"""Ollama-compatible LLM client.
+
+This client sends requests to an Ollama instance via its HTTP API.  It
+implements the :class:`LLMClient` interface by translating chat
+messages into the prompt format expected by Ollama’s `/api/generate`
+endpoint.  The default model and base URL can be customised on
+instantiation.
+"""
+
+from typing import List, Dict, Any
+from os import getenv
+import requests
+
+from .llm_client import LLMClient
+
+
+class OllamaClient(LLMClient):
+    """Client for Ollama's generate endpoint."""
+
+    def __init__(
+        self,
+        model: str = "llama3:latest",
+        base_url: str = "http://localhost:11434",
+        default_options: Dict[str, Any] | None = None,
+        timeout: int = 300,
+    ) -> None:
+        self.model = model
+        self.model_name = model
+        self.base_url = base_url
+        # Reasonable defaults for extraction and summarisation tasks
+        self.default_options = default_options or {
+            "num_ctx": 8192,
+            "temperature": 0.02,
+            "top_p": 0.9,
+            "top_k": 40,
+            "repeat_penalty": 1.05,
+            "mirostat": 0,
+        }
+        self.timeout = timeout
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: str | None = None,
+        temperature: float = 0.0,
+        **kwargs: Any,
+    ) -> Any:
+        # Build the system and prompt strings for Ollama
+        system_parts: List[str] = []
+        user_assistant_lines: List[str] = []
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                system_parts.append(content)
+            elif role == "assistant":
+                user_assistant_lines.append(f"[Assistant]: {content}")
+            else:
+                user_assistant_lines.append(f"[User]: {content}")
+        system = "\n".join(system_parts) if system_parts else None
+        prompt = "\n".join(user_assistant_lines)
+
+        # Merge caller options with defaults.  Accept both a nested
+        # ``ollama_options`` dict and top-level parameters (e.g. max_tokens)
+        caller_opts = kwargs.pop("ollama_options", {}) or {}
+        options = {**self.default_options, **caller_opts}
+        # Keep ``temperature`` in sync with options if provided
+        if temperature is not None:
+            options["temperature"] = temperature
+
+        payload: Dict[str, Any] = {
+            "model": model or self.model,
+            "prompt": prompt,
+            "stream": False,
+            "num_predict": kwargs.get("max_tokens", 1024),
+            "options": options,
+        }
+        # Add system instruction separately
+        if system:
+            payload["system"] = system
+        # Handle JSON schema formatting
+        fmt = kwargs.get("response_format")
+        if fmt:
+            fmt = self._normalize_schema(fmt)
+            payload["format"] = fmt
+        # Optional stop sequences and keep-alive
+        if "stop" in kwargs and kwargs["stop"]:
+            payload["stop"] = kwargs["stop"]
+        if "keep_alive" in kwargs and kwargs["keep_alive"]:
+            payload["keep_alive"] = kwargs["keep_alive"]
+
+        try:
+            response = requests.post(f"{self.base_url}/api/generate", json=payload, timeout=self.timeout)
+            response.raise_for_status()
+            content = response.json().get("response", "")
+        except Exception as exc:
+            raise RuntimeError(f"OllamaClient error: {exc}") from exc
+        return self._wrap_response(content)
+
+    def _normalize_schema(self, fmt: Any) -> Any:
+        import json, os
+        if fmt is None:
+            return None
+        if isinstance(fmt, str):
+            # Interpret as a file path or JSON string
+            if os.path.exists(fmt):
+                return json.load(open(fmt, "r", encoding="utf-8"))
+            return json.loads(fmt)
+        if isinstance(fmt, dict) and "schema" in fmt and isinstance(fmt["schema"], dict):
+            return fmt["schema"]  # unwrap OpenAI‑style wrapper
+        if isinstance(fmt, dict):
+            return fmt
+        raise TypeError("response_format must be a JSON schema dict, a JSON string, or a file path")
+
+    def _wrap_response(self, content: str) -> Any:
+        class Message:
+            def __init__(self, content: str) -> None:
+                self.content = content
+                self.tool_calls = None
+        class Choice:
+            def __init__(self, message: Message) -> None:
+                self.message = message
+        class Response:
+            def __init__(self, content: str) -> None:
+                self.choices = [Choice(Message(content))]
+        return Response(content)
+
+
+__all__ = ["OllamaClient"]

POP/providers/openai_client.py

@@ -0,0 +1,100 @@
+"""OpenAI client implementation.
+
+This module provides a concrete :class:`LLMClient` for interacting with
+OpenAI's chat completion endpoint.  It mirrors the behaviour of the
+original POP ``OpenAIClient`` but lives in its own file as part of a
+modular provider architecture.  If the ``openai`` package is not
+installed in your environment this client will raise an
+ImportError on instantiation.
+"""
+
+from typing import List, Dict, Any, Optional
+from os import getenv
+from pydantic import BaseModel
+
+from .llm_client import LLMClient
+
+
+try:
+    from openai import OpenAI
+except Exception:
+    OpenAI = None  # type: ignore
+
+
+class OpenAIClient(LLMClient):
+    """Client for the OpenAI Chat Completions API."""
+
+    def __init__(self, model: str = "gpt-5-nano") -> None:
+        if OpenAI is None:
+            raise ImportError(
+                "openai package is not installed. Install it to use OpenAIClient."
+            )
+        # The API key is pulled from the environment.  You must set
+        # OPENAI_API_KEY before using this client.
+        self.client = OpenAI(api_key=getenv("OPENAI_API_KEY"))
+        self.model_name = model
+
+    def chat_completion(
+        self,
+        messages: List[Dict[str, Any]],
+        model: Optional[str] = None,
+        temperature: float = 1.0,
+        **kwargs: Any,
+    ) -> Any:
+        # Build the request payload according to OpenAI's API.
+        model_name = model or self.model_name
+        request_payload: Dict[str, Any] = {
+            "model": model_name,
+            "messages": [],
+            "temperature": temperature,
+        }
+
+        # Optional image attachments
+        images: Optional[List[str]] = kwargs.pop("images", None)
+
+        # Construct messages list.  If images are present they are
+        # attached to the last user message (OpenAI multi‑content
+        # messages).  Other roles are passed verbatim.
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if images and role == "user":
+                multi: List[Any] = [{"type": "text", "text": content}]
+                for img in images:
+                    if isinstance(img, str) and img.startswith("http"):
+                        multi.append({"type": "image_url", "image_url": {"url": img}})
+                    else:
+                        multi.append({"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{img}"}})
+                content = multi
+            request_payload["messages"].append({"role": role, "content": content})
+
+        # Response format: can be a pydantic model or raw JSON schema
+        fmt: Any = kwargs.get("response_format")
+        if fmt:
+            if isinstance(fmt, BaseModel):
+                request_payload["response_format"] = fmt
+            else:
+                # wrap raw schema into OpenAI's wrapper
+                request_payload["response_format"] = {"type": "json_schema", "json_schema": fmt}
+
+        # Tools support: list of function descriptors
+        tools = kwargs.get("tools")
+        if tools:
+            request_payload["tools"] = tools
+            request_payload["tool_choice"] = kwargs.get("tool_choice", "auto")
+
+        # Temporary patch for models not supporting a system role (as in the
+        # original POP).  Convert the first system message to a user
+        # message when using the "o1-mini" model.
+        if model_name == "o1-mini" and request_payload["messages"] and request_payload["messages"][0]["role"] == "system":
+            request_payload["messages"][0]["role"] = "user"
+
+        # Send the request.  If something goes wrong, raise a runtime error.
+        try:
+            response = self.client.chat.completions.create(**request_payload)
+        except Exception as exc:
+            raise RuntimeError(f"OpenAI chat_completion error: {exc}") from exc
+        return response
+
+
+__all__ = ["OpenAIClient"]

POP/stream.py

@@ -0,0 +1,77 @@
+"""Streaming support for LLM responses.
+
+This module defines a simple generator function that yields events
+during a call to an LLM client.  Each event is represented by a
+dictionary with an ``event`` key and optionally additional data.  The
+sequence of events loosely follows the pattern used by the TypeScript
+``pi‑ai`` project: ``start`` → ``text_start`` → ``text_delta`` →
+``text_end`` → ``done``.
+
+The generator hides the blocking nature of LLM calls behind an
+iterator interface.  For providers that support true streaming
+responses, you can extend this function to yield tokens as they
+arrive.
+"""
+
+from typing import Generator, Dict, Any, Optional
+
+from .context import Context
+from .api_registry import get_client, get_default_model
+
+
+def stream(
+    provider: str,
+    context: Context,
+    model: Optional[str] = None,
+    **kwargs: Any,
+) -> Generator[Dict[str, Any], None, None]:
+    """Yield events representing a streamed LLM response.
+
+    Parameters
+    ----------
+    provider : str
+        Identifier of the provider to use (e.g. ``"openai"``).
+    context : Context
+        Conversation context containing messages and optional system prompt.
+    model : str, optional
+        Model name; if not provided the provider's default is used.
+    **kwargs : Any
+        Additional options passed directly to the provider's
+        ``chat_completion`` method (e.g. ``temperature``, ``tools``).
+    Yields
+    ------
+    dict
+        Streaming events with at least an ``event`` key.  Events are:
+        ``start`` (begin request), ``text_start`` (before first token),
+        ``text_delta`` (with ``value`` containing the full text for
+        synchronous providers), ``text_end`` (after last token), and
+        ``done`` (request completed).
+    """
+    client = get_client(provider)
+    if client is None:
+        raise ValueError(f"Unknown provider: {provider}")
+    # Determine model: fallback to default models
+    if model is None:
+        model = get_default_model(provider)
+    yield {"event": "start"}
+    # Convert context into messages
+    messages = context.to_messages()
+    yield {"event": "text_start"}
+    # Call the provider synchronously.  If providers support streaming,
+    # you could instead iterate over a streaming response here.
+    response = client.chat_completion(messages=messages, model=model, **kwargs)
+    # Extract the content; OpenAI‑style responses put the text in
+    # response.choices[0].message.content
+    text = ""
+    try:
+        text = response.choices[0].message.content
+    except Exception:
+        # If the response is a simple string or dict, fall back
+        text = str(response)
+    # For synchronous providers we send the entire text in one delta
+    yield {"event": "text_delta", "value": text}
+    yield {"event": "text_end"}
+    yield {"event": "done"}
+
+
+__all__ = ["stream"]

POP/utils/__init__.py

@@ -0,0 +1,9 @@
+"""
+Utility subpackage for the restructured POP project.
+
+This subpackage contains helper modules for event streaming, HTTP
+proxy configuration, JSON parsing, overflow management, Unicode
+sanitisation, basic validation, web snapshots, and OAuth configuration.
+The layout mirrors the utilities present in the pi‑ai project to
+provide similar functionality within POP.
+"""

POP/utils/event_stream.py

@@ -0,0 +1,43 @@
+"""
+Utility helpers for streaming events.
+
+This module provides a simple event streaming interface.  In POP's
+rewritten architecture we mirror the ``event-stream`` helper from
+the original pi-ai project but do not implement a full server-sent
+events protocol.  Instead, we define a ``EventStream`` class and
+a helper function ``to_event_stream`` that can wrap a generator.
+"""
+
+from typing import Iterable, Iterator, Any, Dict
+
+class EventStream:
+    """Wrap a generator to provide an iterator of event dictionaries.
+
+    An event dictionary contains at least a ``type`` key (e.g.
+    ``start``, ``text_start``, ``text_delta``, ``text_end``, ``done``)
+    and a ``data`` key.  Consumers of this class can send these events
+    to clients over websockets or Server‑Sent Events.
+    """
+    def __init__(self, generator: Iterable):
+        self._iterator = iter(generator)
+
+    def __iter__(self) -> Iterator[Dict[str, Any]]:
+        return self
+
+    def __next__(self) -> Dict[str, Any]:
+        return next(self._iterator)
+
+def to_event_stream(generator: Iterable) -> EventStream:
+    """Convert a plain generator into an EventStream.
+
+    Parameters
+    ----------
+    generator:
+        A generator which yields dictionaries representing events.
+
+    Returns
+    -------
+    EventStream
+        An iterator wrapper around the generator.
+    """
+    return EventStream(generator)