swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/ai/conversation.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import copy
+import json
+from collections.abc import Iterator, Sequence
+from typing import Any, Self
+
+from swiftpy.ai.providers.base import Message, ToolCall
+
+
+def _clone_message(m: Message) -> Message:
+    """Create a deep clone of a Message preserving tool_calls and tool_call_id."""
+    cloned_tools: list[ToolCall] | None = None
+    if m.tool_calls:
+        cloned_tools = [
+            ToolCall(id=tc.id, name=tc.name, arguments=copy.deepcopy(tc.arguments))
+            for tc in m.tool_calls
+        ]
+    return Message(
+        role=m.role,
+        content=m.content,
+        name=m.name,
+        tool_calls=cloned_tools,
+        tool_call_id=m.tool_call_id,
+    )
+
+
+def _deserialize_tool_call(raw_tc: Any) -> ToolCall | None:
+    """Deserialize an OpenAI-formatted or flat tool call dict into ToolCall."""
+    if not isinstance(raw_tc, dict):
+        return None
+    tc_id = str(raw_tc.get("id") or "")
+    fn = raw_tc.get("function")
+    if isinstance(fn, dict):
+        name = str(fn.get("name") or "")
+        raw_args = fn.get("arguments")
+    else:
+        name = str(raw_tc.get("name") or "")
+        raw_args = raw_tc.get("arguments")
+
+    if isinstance(raw_args, str):
+        try:
+            parsed = json.loads(raw_args)
+            args: dict[str, Any] = parsed if isinstance(parsed, dict) else {"raw": raw_args}
+        except (json.JSONDecodeError, TypeError):
+            args = {"raw": raw_args} if raw_args else {}
+    elif isinstance(raw_args, dict):
+        args = copy.deepcopy(raw_args)
+    else:
+        args = {}
+    return ToolCall(id=tc_id, name=name, arguments=args)
+
+
+class Conversation:
+    """
+    Multi-turn conversation history container.
+
+    Manages ordered messages across dialogue turns with serialization
+    support for persistence and integration with AIClient.
+    """
+
+    def __init__(self, messages: Sequence[Message] | None = None) -> None:
+        self._messages: list[Message] = (
+            [_clone_message(m) for m in messages] if messages else []
+        )
+
+    def add_system(self, content: str) -> Self:
+        """Append a system prompt message."""
+        self._messages.append(Message(role="system", content=content))
+        return self
+
+    def add_user(self, content: str) -> Self:
+        """Append a user dialogue message."""
+        self._messages.append(Message(role="user", content=content))
+        return self
+
+    def add_assistant(self, content: str) -> Self:
+        """Append an assistant response message."""
+        self._messages.append(Message(role="assistant", content=content))
+        return self
+
+    def add_message(self, message: Message) -> Self:
+        """Append a pre-constructed Message instance."""
+        if not isinstance(message, Message):
+            raise TypeError(f"Expected Message instance, got {type(message).__name__}")
+        self._messages.append(message)
+        return self
+
+    @property
+    def messages(self) -> list[Message]:
+        """Return a defensive copy of the ordered messages list."""
+        return list(self._messages)
+
+    @property
+    def system_messages(self) -> list[Message]:
+        """Return all system prompt messages in order."""
+        return [m for m in self._messages if m.role == "system"]
+
+    @property
+    def dialogue_messages(self) -> list[Message]:
+        """Return non-system dialogue messages (user and assistant) in order."""
+        return [m for m in self._messages if m.role != "system"]
+
+    def clear(self) -> None:
+        """Remove all messages from the conversation."""
+        self._messages.clear()
+
+    def clone(self) -> Conversation:
+        """Create an independent deep copy of this conversation."""
+        return Conversation(messages=[_clone_message(m) for m in self._messages])
+
+    def to_dict_list(self) -> list[dict[str, Any]]:
+        """Serialize messages to a list of dictionaries."""
+        return [m.to_dict() for m in self._messages]
+
+    def to_json(self) -> str:
+        """Serialize conversation to JSON string."""
+        return json.dumps(self.to_dict_list())
+
+    @classmethod
+    def from_dict_list(cls, data: Sequence[dict[str, Any]]) -> Conversation:
+        """Construct a Conversation instance from a sequence of message dictionaries."""
+        messages: list[Message] = []
+        for item in data:
+            if not isinstance(item, dict):
+                raise TypeError(f"Expected dictionary for message, got {type(item).__name__}")
+            role = str(item.get("role", "user"))
+            content = str(item.get("content") or "")
+            name = item.get("name")
+            tool_call_id = item.get("tool_call_id")
+            raw_tool_calls = item.get("tool_calls")
+            tool_calls: list[ToolCall] | None = None
+            if isinstance(raw_tool_calls, list):
+                parsed_tcs = [
+                    tc for raw_tc in raw_tool_calls if (tc := _deserialize_tool_call(raw_tc)) is not None
+                ]
+                if parsed_tcs:
+                    tool_calls = parsed_tcs
+            messages.append(
+                Message(
+                    role=role,
+                    content=content,
+                    name=str(name) if name else None,
+                    tool_calls=tool_calls,
+                    tool_call_id=str(tool_call_id) if tool_call_id else None,
+                )
+            )
+        return cls(messages=messages)
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Conversation:
+        """Deserialize a Conversation instance from a JSON string."""
+        if not json_str or not json_str.strip():
+            return cls()
+        try:
+            data = json.loads(json_str)
+        except (json.JSONDecodeError, ValueError) as exc:
+            raise ValueError(f"Invalid JSON string for conversation: {exc}") from exc
+
+        if not isinstance(data, list):
+            raise TypeError(f"Expected a JSON list of messages, got {type(data).__name__}")
+        return cls.from_dict_list(data)
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+    def __iter__(self) -> Iterator[Message]:
+        return iter(self._messages)
+
+    def __getitem__(self, index: int) -> Message:
+        return self._messages[index]

swiftpy/ai/embeddings.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import asyncio
+import math
+from collections.abc import Sequence
+from typing import Any
+
+import httpx
+
+_HTTPX_ERRORS: tuple[type[Exception], ...] = (httpx.TimeoutException, httpx.RequestError)
+
+from swiftpy.ai._deterministic import generate_deterministic_embedding
+from swiftpy.ai._fake import AIFake
+from swiftpy.ai.exceptions import (
+    AIAuthenticationError,
+    AIConfigurationError,
+    AIConnectionError,
+    AIModuleDisabledError,
+    AIProviderError,
+    AIRateLimitError,
+)
+from swiftpy.ai.pool import AIHttpPool
+from swiftpy.ai.providers.base import redact_sensitive_text
+from swiftpy.core.config import Config
+
+PROVIDER_MAX_BATCH_SIZE: dict[str, int] = {
+    "openai": 2048,
+}
+
+
+class EmbeddingsClient:
+    """Client for generating text embeddings with batch chunking and concurrency."""
+
+    def __init__(
+        self,
+        config: Config | None = None,
+        http_pool: AIHttpPool | None = None,
+    ) -> None:
+        if config is None:
+            try:
+                self._config = Config.get_instance()
+            except RuntimeError:
+                self._config = Config()
+        else:
+            self._config = config
+
+        self._http_pool = http_pool or AIHttpPool.get_instance()
+
+    def _resolve_provider_and_key(self, provider_override: str | None) -> tuple[str, str, str, str]:
+        if not self._config.get("ai.enabled", True):
+            raise AIModuleDisabledError("AI module is disabled in configuration.")
+
+        provider = (provider_override or str(self._config.get("ai.default", "openai"))).lower()
+        if provider != "openai" and provider != "deterministic":
+            raise AIConfigurationError(
+                f"Embedding provider '{provider}' is not supported. Use 'openai' or 'deterministic'."
+            )
+
+        raw_cfg = self._config.get(f"ai.providers.{provider}", {})
+        prov_cfg: dict[str, Any] = raw_cfg if isinstance(raw_cfg, dict) else {}
+
+        api_key = str(prov_cfg.get("api_key", "")).strip()
+        base_url = str(prov_cfg.get("base_url", "https://api.openai.com/v1")).rstrip("/")
+        default_model = str(prov_cfg.get("embedding_model", "text-embedding-3-small"))
+
+        return provider, api_key, base_url, default_model
+
+    def _resolve_timeout(self, provider: str) -> float:
+        raw_cfg = self._config.get(f"ai.providers.{provider}", {})
+        if isinstance(raw_cfg, dict) and raw_cfg.get("timeout") is not None:
+            return float(raw_cfg["timeout"])
+        return float(self._http_pool.timeout)
+
+    async def _embed_chunk_openai(
+        self,
+        texts: list[str],
+        model: str,
+        base_url: str,
+        api_key: str,
+        timeout: float | None = None,
+    ) -> list[list[float]]:
+        if not api_key:
+            raise AIConfigurationError(
+                "Missing API key for embedding provider 'openai'. "
+                "Please configure 'ai.providers.openai.api_key' or set OPENAI_API_KEY."
+            )
+
+        url = f"{base_url}/embeddings"
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+        payload = {
+            "model": model,
+            "input": texts,
+        }
+
+        effective_timeout = self._resolve_timeout("openai") if timeout is None else timeout
+        client = self._http_pool.get_client()
+        try:
+            response = await client.post(url, headers=headers, json=payload, timeout=effective_timeout)
+        except _HTTPX_ERRORS as exc:
+            safe_exc = redact_sensitive_text(str(exc), api_key=api_key)
+            raise AIConnectionError(
+                f"Failed to connect to embedding endpoint: {safe_exc}",
+                provider="openai",
+            ) from exc
+
+        safe_body = redact_sensitive_text(response.text, api_key=api_key)
+        if response.status_code in (401, 403):
+            raise AIAuthenticationError(
+                f"OpenAI embedding authentication failed: {safe_body}",
+                provider="openai",
+                status_code=response.status_code,
+                response_body=safe_body,
+            )
+        if response.status_code == 429:
+            raise AIRateLimitError(
+                f"OpenAI embedding rate limit exceeded: {safe_body}",
+                provider="openai",
+                status_code=response.status_code,
+                response_body=safe_body,
+            )
+        if response.status_code >= 400:
+            raise AIProviderError(
+                f"OpenAI embedding error ({response.status_code}): {safe_body}",
+                provider="openai",
+                status_code=response.status_code,
+                response_body=safe_body,
+            )
+
+        try:
+            data = response.json()
+        except Exception as exc:
+            raise AIProviderError("Embedding response is not valid JSON", provider="openai") from exc
+
+        if not isinstance(data, dict):
+            raise AIProviderError("Embedding response payload is not a JSON object", provider="openai")
+
+        items = data.get("data")
+        if not isinstance(items, list):
+            raise AIProviderError("Embedding response missing 'data' list", provider="openai")
+
+        if len(items) != len(texts):
+            raise AIProviderError(
+                f"Embedding response items count ({len(items)}) does not match request chunk count ({len(texts)})",
+                provider="openai",
+            )
+
+        seen_indices: set[int] = set()
+        vectors_by_index: dict[int, list[float]] = {}
+        expected_dim: int | None = None
+
+        for pos, item in enumerate(items):
+            if not isinstance(item, dict):
+                raise AIProviderError(f"Embedding item at position {pos} is not a dictionary", provider="openai")
+
+            if "index" not in item:
+                raise AIProviderError(f"Embedding item at position {pos} is missing required 'index' field", provider="openai")
+
+            raw_idx = item["index"]
+            if not isinstance(raw_idx, int) or isinstance(raw_idx, bool):
+                raise AIProviderError(
+                    f"Embedding item 'index' must be an integer, got {type(raw_idx).__name__}",
+                    provider="openai",
+                )
+
+            if raw_idx < 0 or raw_idx >= len(texts):
+                raise AIProviderError(
+                    f"Embedding item index {raw_idx} is out of bounds for chunk of size {len(texts)}",
+                    provider="openai",
+                )
+
+            if raw_idx in seen_indices:
+                raise AIProviderError(f"Duplicate embedding index {raw_idx} received from provider", provider="openai")
+            seen_indices.add(raw_idx)
+
+            if "embedding" not in item:
+                raise AIProviderError(f"Embedding item at index {raw_idx} is missing 'embedding' vector", provider="openai")
+
+            raw_vec = item["embedding"]
+            if not isinstance(raw_vec, list) or not raw_vec:
+                raise AIProviderError(f"Embedding item at index {raw_idx} has invalid or empty vector", provider="openai")
+
+            if expected_dim is None:
+                expected_dim = len(raw_vec)
+            elif len(raw_vec) != expected_dim:
+                raise AIProviderError(
+                    f"Inconsistent vector dimensions: expected {expected_dim}, got {len(raw_vec)} at index {raw_idx}",
+                    provider="openai",
+                )
+
+            parsed_vec: list[float] = []
+            for val in raw_vec:
+                if isinstance(val, (int, float)) and not isinstance(val, bool):
+                    fval = float(val)
+                    if math.isnan(fval) or math.isinf(fval):
+                        raise AIProviderError(
+                            f"Embedding vector at index {raw_idx} contains NaN or infinite value",
+                            provider="openai",
+                        )
+                    parsed_vec.append(fval)
+                else:
+                    raise AIProviderError(
+                        f"Non-numeric value in embedding vector at index {raw_idx}",
+                        provider="openai",
+                    )
+
+            vectors_by_index[raw_idx] = parsed_vec
+
+        # Guarantee preservation of original document order
+        return [vectors_by_index[i] for i in range(len(texts))]
+
+    async def embed(
+        self,
+        text: str,
+        model: str | None = None,
+        provider: str | None = None,
+    ) -> list[float]:
+        """Generate an embedding vector for a single text."""
+        if not isinstance(text, str):
+            raise TypeError(f"Expected string for embedding, got {type(text).__name__}")
+        if not text.strip():
+            raise ValueError("Cannot embed empty or whitespace-only text.")
+
+        results = await self.embed_batch([text], model=model, provider=provider, chunk_size=1)
+        return results[0]
+
+    async def embed_batch(
+        self,
+        texts: Sequence[str],
+        model: str | None = None,
+        provider: str | None = None,
+        chunk_size: int = 100,
+        concurrency: int = 5,
+    ) -> list[list[float]]:
+        """
+        Embed a collection of texts, automatically chunking large lists into
+        provider-safe batches and executing chunks concurrently with bounded parallelism.
+        """
+        if not texts:
+            return []
+        if chunk_size <= 0:
+            raise ValueError(f"chunk_size must be a positive integer, got {chunk_size}")
+        if concurrency <= 0:
+            raise ValueError(f"concurrency must be a positive integer, got {concurrency}")
+
+        for idx, t in enumerate(texts):
+            if not isinstance(t, str):
+                raise TypeError(f"Item at index {idx} must be a string, got {type(t).__name__}")
+            if not t.strip():
+                raise ValueError(f"Item at index {idx} is empty or whitespace only.")
+
+        active_fake = AIFake.get_active()
+        if active_fake is not None:
+            return await active_fake.handle_embed(
+                texts,
+                model=model,
+                provider=provider,
+            )
+
+        prov_name, api_key, base_url, default_model = self._resolve_provider_and_key(provider)
+        target_model = model or default_model
+
+        if prov_name == "deterministic":
+            return [generate_deterministic_embedding(t) for t in texts]
+        if not api_key:
+            raise AIConfigurationError(
+                f"Missing API key for embedding provider '{prov_name}'. "
+                f"Please configure 'ai.providers.{prov_name}.api_key' or set OPENAI_API_KEY."
+            )
+
+        effective_timeout = self._resolve_timeout(prov_name)
+
+        # Respect provider-specific maximum batch size limits
+        max_allowed = PROVIDER_MAX_BATCH_SIZE.get(prov_name, chunk_size)
+        effective_chunk_size = min(chunk_size, max_allowed)
+
+        # Chunk the input texts into slices of effective_chunk_size
+        text_list = list(texts)
+        chunks: list[list[str]] = [
+            text_list[i : i + effective_chunk_size]
+            for i in range(0, len(text_list), effective_chunk_size)
+        ]
+
+        semaphore = asyncio.Semaphore(concurrency)
+
+        async def _process_chunk(chunk: list[str]) -> list[list[float]]:
+            async with semaphore:
+                return await self._embed_chunk_openai(
+                    chunk,
+                    model=target_model,
+                    base_url=base_url,
+                    api_key=api_key,
+                    timeout=effective_timeout,
+                )
+
+        # Create tasks and handle cancellation on failure
+        tasks = [asyncio.create_task(_process_chunk(c)) for c in chunks]
+        try:
+            chunk_results = await asyncio.gather(*tasks)
+        except Exception:
+            for task in tasks:
+                if not task.done():
+                    task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            raise
+
+        # Flatten in original order
+        embeddings: list[list[float]] = []
+        for res in chunk_results:
+            embeddings.extend(res)
+
+        return embeddings
+
+
+__all__ = [
+    "PROVIDER_MAX_BATCH_SIZE",
+    "EmbeddingsClient",
+    "generate_deterministic_embedding",
+]

swiftpy/ai/exceptions.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+
+class AIError(Exception):
+    """Base exception for all SwiftPY AI module errors."""
+
+
+class AIModuleDisabledError(AIError):
+    """Raised when an AI operation is attempted but the AI module is disabled in configuration."""
+
+
+class AIConfigurationError(AIError):
+    """Raised when AI configuration is missing, incomplete, or invalid."""
+
+
+class AIProviderError(AIError):
+    """Raised when an LLM provider encounters an error during request execution."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: str = "",
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class AIAuthenticationError(AIProviderError):
+    """Raised when provider authentication fails (e.g. invalid or missing API key)."""
+
+
+class AIRateLimitError(AIProviderError):
+    """Raised when a provider rejects a request due to rate or quota limits."""
+
+    def __init__(
+        self,
+        message: str,
+        provider: str = "",
+        status_code: int | None = 429,
+        response_body: str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(
+            message=message,
+            provider=provider,
+            status_code=status_code,
+            response_body=response_body,
+        )
+        self.retry_after = retry_after
+
+
+class AIConnectionError(AIProviderError):
+    """Raised when an HTTP connection or network timeout error occurs while contacting a provider."""
+
+
+class AgentLoopError(AIError):
+    """Raised when an autonomous agent or tool execution loop exceeds configured bounds (e.g. max_iterations)."""
+
+    def __init__(self, message: str, iterations: int = 0) -> None:
+        super().__init__(message)
+        self.iterations = iterations
+
+
+class AIBudgetExceededError(AIError):
+    """Raised when an operation exceeds the configured daily token or cost budget."""
+
+
+class AIContentModerationError(AIError):
+    """Raised when content fails moderation policy checks."""
+
+