Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

6.0 KB
Raw Blame
from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, AsyncIterator, Literal, Optional


# --- Errors ---------------------------------------------------------------

class LLMError(Exception):
    """Base class for provider failures. Subclasses let the runtime show
    the user a friendly message instead of a stack trace."""

    code: str = "unknown"

    def __init__(self, message: str, *, retryable: bool = False, status: Optional[int] = None):
        super().__init__(message)
        self.retryable = retryable
        self.status = status


class LLMAuthError(LLMError):
    code = "auth"


class LLMRateLimitError(LLMError):
    code = "rate_limit"

    def __init__(self, message: str, *, status: Optional[int] = None):
        super().__init__(message, retryable=True, status=status)


class LLMUnavailableError(LLMError):
    code = "unavailable"

    def __init__(self, message: str, *, status: Optional[int] = None):
        super().__init__(message, retryable=True, status=status)


class LLMNotSupportedError(LLMError):
    code = "not_supported"


# --- Messages, tools, chunks ---------------------------------------------

Role = Literal["system", "user", "assistant", "tool"]


@dataclass
class ToolCall:
    id: str
    name: str
    arguments: dict[str, Any]
    # Opaque Gemini signature; replay unchanged, never pass to the tool itself.
    thought_signature: Optional[str] = None


@dataclass
class ChatMessage:
    role: Role
    content: Optional[str] = None
    tool_calls: list[ToolCall] = field(default_factory=list)
    # For role="tool":
    tool_call_id: Optional[str] = None
    name: Optional[str] = None


@dataclass
class ToolDefinition:
    """Provider-agnostic tool spec. Matches MCP/JSON-Schema shape."""
    name: str
    description: str
    parameters: dict[str, Any]  # JSON Schema for the arguments object


@dataclass
class Usage:
    input_tokens: int = 0
    output_tokens: int = 0


@dataclass
class ChatChunk:
    """Streaming event. Exactly one of these fields is populated per chunk."""
    type: Literal["text_delta", "tool_call_start", "tool_call_args_delta", "tool_call_end", "finish", "usage"]
    text: Optional[str] = None
    tool_call_id: Optional[str] = None
    tool_name: Optional[str] = None
    args_delta: Optional[str] = None  # incremental JSON args while streaming
    finish_reason: Optional[str] = None
    usage: Optional[Usage] = None
    # Delivered on tool_call_end, after all streaming deltas have arrived.
    thought_signature: Optional[str] = None


@dataclass
class ChatResponse:
    content: str
    tool_calls: list[ToolCall] = field(default_factory=list)
    finish_reason: str = "stop"
    usage: Usage = field(default_factory=Usage)


# --- Provider interface ---------------------------------------------------

class LLMProvider(ABC):
    name: str
    supports_native_tools: bool = True
    # Embedding capability — Anthropic returns False, others True.
    supports_embeddings: bool = True

    def __init__(self, *, api_key: str = "", base_url: Optional[str] = None, model: Optional[str] = None):
        self.api_key = api_key
        self.base_url: str = base_url or ""
        self.default_model = model
        # Stable per-conversation id, set by the executor before each run.
        # Providers whose backends route on it send it as a request header.
        self.session_id: Optional[str] = None

    @abstractmethod
    def chat_stream(
        self,
        messages: list[ChatMessage],
        *,
        model: str,
        tools: Optional[list[ToolDefinition]] = None,
        temperature: float = 0.4,
        max_tokens: Optional[int] = None,
    ) -> AsyncIterator[ChatChunk]:
        """Yield streaming chunks. Implementations are async generators."""
        ...

    async def chat(
        self,
        messages: list[ChatMessage],
        *,
        model: str,
        tools: Optional[list[ToolDefinition]] = None,
        temperature: float = 0.4,
        max_tokens: Optional[int] = None,
    ) -> ChatResponse:
        """Convenience: collect a streaming response into one ChatResponse."""
        text_parts: list[str] = []
        tool_calls: dict[str, dict] = {}
        finish: str = "stop"
        usage = Usage()
        async for chunk in self.chat_stream(
            messages, model=model, tools=tools, temperature=temperature, max_tokens=max_tokens
        ):
            if chunk.type == "text_delta" and chunk.text:
                text_parts.append(chunk.text)
            elif chunk.type == "tool_call_start" and chunk.tool_call_id:
                tool_calls[chunk.tool_call_id] = {"id": chunk.tool_call_id, "name": chunk.tool_name or "", "args_buf": ""}
            elif chunk.type == "tool_call_args_delta" and chunk.tool_call_id:
                tc = tool_calls.setdefault(chunk.tool_call_id, {"id": chunk.tool_call_id, "name": chunk.tool_name or "", "args_buf": ""})
                tc["args_buf"] += chunk.args_delta or ""
            elif chunk.type == "tool_call_end" and chunk.tool_call_id in tool_calls:
                tool_calls[chunk.tool_call_id]["thought_signature"] = chunk.thought_signature
            elif chunk.type == "finish" and chunk.finish_reason:
                finish = chunk.finish_reason
            elif chunk.type == "usage" and chunk.usage:
                usage = chunk.usage
        import json
        parsed_calls = []
        for tc in tool_calls.values():
            try:
                args = json.loads(tc["args_buf"]) if tc["args_buf"] else {}
            except json.JSONDecodeError:
                args = {"_raw": tc["args_buf"]}
            parsed_calls.append(ToolCall(
                id=tc["id"], name=tc["name"], arguments=args,
                thought_signature=tc.get("thought_signature"),
            ))
        return ChatResponse(content="".join(text_parts), tool_calls=parsed_calls, finish_reason=finish, usage=usage)

    @abstractmethod
    async def embed(self, texts: list[str], *, model: str) -> list[list[float]]:
        ...