fllme 0.2.0__py3-none-any.whl

fllme/__init__.py

@@ -0,0 +1,87 @@
+from .models import (
+    AdapterType,
+    AuthPrinciple,
+    BasicOutputType,
+    CacheUsage,
+    Citation,
+    Content,
+    Deployment,
+    FinishReason,
+    GenerationInput,
+    GenerationOutput,
+    ImageConfig,
+    LLMConfig,
+    LLMModel,
+    Provider,
+    Message,
+    SafetyResult,
+    StreamDelta,
+    TextDelta,
+    ThinkingDelta,
+    ThinkingLevel,
+    Tool,
+    ToolsConfig,
+    Usage,
+)
+from .auth import AuthResolver, get_resolver, register_resolver
+from .store import AuthRepository, DeploymentRepository, ModelRepository, SQLiteStore
+from .service import DeploymentService
+from .providers import Adapter, get_adapter
+from .generate import configure, generate, get_service
+from .media import MediaResolver
+from .errors import (
+    AuthError,
+    DeploymentNotFoundError,
+    FuncLLMError,
+    MediaResolutionError,
+    ModelNotFoundError,
+    ProviderError,
+    SerializationError,
+)
+
+__all__ = [
+    "Adapter",
+    "AdapterType",
+    "AuthError",
+    "AuthPrinciple",
+    "AuthRepository",
+    "AuthResolver",
+    "BasicOutputType",
+    "CacheUsage",
+    "Citation",
+    "Content",
+    "Deployment",
+    "DeploymentNotFoundError",
+    "DeploymentRepository",
+    "DeploymentService",
+    "FinishReason",
+    "FuncLLMError",
+    "GenerationInput",
+    "GenerationOutput",
+    "ImageConfig",
+    "LLMConfig",
+    "LLMModel",
+    "MediaResolutionError",
+    "MediaResolver",
+    "Message",
+    "ModelNotFoundError",
+    "ModelRepository",
+    "Provider",
+    "ProviderError",
+    "SQLiteStore",
+    "SafetyResult",
+    "SerializationError",
+    "StreamDelta",
+    "TextDelta",
+    "ThinkingDelta",
+    "ThinkingLevel",
+    "Tool",
+    "ToolsConfig",
+    "Usage",
+    "configure",
+    "generate",
+    "get_adapter",
+    "get_resolver",
+    "get_service",
+    "register_resolver",
+]

fllme/auth/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..errors import AuthError
+from .api_key import ApiKeyResolver
+from .google_adc import GoogleADCResolver
+from .protocol import AuthResolver
+
+if TYPE_CHECKING:
+    pass
+
+RESOLVERS: dict[str, AuthResolver] = {}
+
+
+def _register_builtins() -> None:
+    register_resolver("google_adc", GoogleADCResolver())
+    register_resolver("api_key", ApiKeyResolver())
+
+
+def register_resolver(resolver_id: str, resolver: AuthResolver) -> None:
+    RESOLVERS[resolver_id] = resolver
+
+
+def get_resolver(resolver_id: str) -> AuthResolver:
+    resolver = RESOLVERS.get(resolver_id)
+    if resolver is None:
+        msg = f"Unknown auth resolver: {resolver_id!r}"
+        raise AuthError(msg)
+    return resolver
+
+
+_register_builtins()
+
+__all__ = [
+    "RESOLVERS",
+    "ApiKeyResolver",
+    "AuthResolver",
+    "GoogleADCResolver",
+    "get_resolver",
+    "register_resolver",
+]

fllme/auth/api_key.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from ..errors import AuthError
+
+if TYPE_CHECKING:
+    from ..models.auth import AuthPrinciple
+
+
+class ApiKeyResolver:
+    async def get_headers(self, principle: AuthPrinciple) -> dict[str, str]:
+        if not principle.required_env_vars:
+            msg = "API key auth requires at least one env var in required_env_vars"
+            raise AuthError(msg)
+
+        env_var = principle.required_env_vars[0]
+        value = os.environ.get(env_var)
+        if value is None:
+            msg = f"Missing required environment variable: {env_var}"
+            raise AuthError(msg)
+
+        header_name = principle.config.get("header_name", "api-key")
+        return {header_name: value}
+
+    def check_env(self, principle: AuthPrinciple) -> list[str]:
+        missing: list[str] = []
+        for var in principle.required_env_vars:
+            if var not in os.environ:
+                missing.append(var)
+        return missing

fllme/auth/google_adc.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from ..errors import AuthError
+
+if TYPE_CHECKING:
+    from ..models.auth import AuthPrinciple
+
+
+class GoogleADCResolver:
+    def __init__(self) -> None:
+        self._credentials: Any | None = None
+        self._lock = asyncio.Lock()
+
+    async def get_headers(self, principle: AuthPrinciple) -> dict[str, str]:
+        try:
+            import google.auth
+            import google.auth.transport.requests
+        except ImportError as exc:
+            msg = (
+                "google-auth is required for Google ADC authentication. "
+                "Install it with: pip install google-auth"
+            )
+            raise AuthError(msg) from exc
+
+        async with self._lock:
+            if self._credentials is None:
+                try:
+                    self._credentials, _ = await asyncio.to_thread(
+                        google.auth.default,
+                    )
+                except Exception as exc:
+                    msg = f"Failed to obtain Google ADC credentials: {exc}"
+                    raise AuthError(msg) from exc
+
+            creds: Any = self._credentials
+            if not creds.valid:
+                try:
+                    auth_req = google.auth.transport.requests.Request()
+                    await asyncio.to_thread(creds.refresh, auth_req)
+                except Exception as exc:
+                    msg = f"Failed to refresh Google ADC credentials: {exc}"
+                    raise AuthError(msg) from exc
+
+            token: str = creds.token
+        return {"Authorization": f"Bearer {token}"}
+        return {"Authorization": f"Bearer {token}"}
+
+    def check_env(self, principle: AuthPrinciple) -> list[str]:
+        return []

fllme/auth/protocol.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from ..models.auth import AuthPrinciple
+
+
+class AuthResolver(Protocol):
+    async def get_headers(self, principle: AuthPrinciple) -> dict[str, str]: ...
+
+    def check_env(self, principle: AuthPrinciple) -> list[str]: ...

fllme/errors.py

@@ -0,0 +1,35 @@
+class FuncLLMError(Exception):
+    pass
+
+
+class ModelNotFoundError(FuncLLMError):
+    pass
+
+
+class DeploymentNotFoundError(FuncLLMError):
+    pass
+
+
+class AuthError(FuncLLMError):
+    pass
+
+
+class ProviderError(FuncLLMError):
+    def __init__(self, status_code: int, body: str) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"Provider returned {status_code}: {body}")
+
+
+class SerializationError(FuncLLMError):
+    pass
+
+
+class MediaResolutionError(FuncLLMError):
+    def __init__(self, failed_ids: list[str] | None = None, msg: str = "") -> None:
+        self.failed_ids = failed_ids
+        if not msg:
+            msg = "Media resolution failed"
+            if failed_ids:
+                msg += f" for IDs: {', '.join(failed_ids)}"
+        super().__init__(msg)

fllme/generate.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from .errors import ProviderError
+from .http import get_client
+from .media import MediaResolver, resolve_references, store_output_media
+from .models.input import GenerationInput
+from .models.output import GenerationOutput, StreamDelta
+from .providers import get_adapter
+from .providers.base import Adapter
+from .service import DeploymentService
+
+DEFAULT_SERVICE: DeploymentService | None = None
+
+
+def configure(service: DeploymentService) -> None:
+    global DEFAULT_SERVICE  # noqa: PLW0603
+    DEFAULT_SERVICE = service
+
+
+def get_service() -> DeploymentService:
+    if DEFAULT_SERVICE is None:
+        msg = "No service configured. Call fllme.configure(service) first."
+        raise RuntimeError(msg)
+    return DEFAULT_SERVICE
+
+
+async def generate(
+    gen_input: GenerationInput,
+    *,
+    deployment_id: str | None = None,
+    service: DeploymentService | None = None,
+    media_resolver: MediaResolver | None = None,
+) -> GenerationOutput | AsyncIterator[StreamDelta | GenerationOutput]:
+    svc = service or get_service()
+
+    if media_resolver is not None:
+        resolved = await resolve_references(gen_input.conversation, media_resolver)
+        gen_input = gen_input.model_copy(update={"conversation": resolved})
+
+    deployment = await svc.resolve_deployment(gen_input.model, deployment_id)
+    adapter = get_adapter(deployment.adapter)
+    payload: dict[str, Any] = adapter.serialize(gen_input)
+    headers = await svc.get_auth_headers(deployment)
+
+    if gen_input.stream:
+        return _stream(deployment.url, headers, payload, adapter, media_resolver)
+
+    return await _collect(deployment.url, headers, payload, adapter, media_resolver)
+
+
+async def _collect(
+    url: str,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    adapter: Adapter,
+    media_resolver: MediaResolver | None = None,
+) -> GenerationOutput:
+    result: GenerationOutput | None = None
+    async for item in _stream(url, headers, payload, adapter, media_resolver):
+        if isinstance(item, GenerationOutput):
+            result = item
+    if result is None:
+        msg = "Stream ended without a final GenerationOutput"
+        raise ProviderError(0, msg)
+    return result
+
+
+async def _stream(
+    url: str,
+    headers: dict[str, str],
+    payload: dict[str, Any],
+    adapter: Adapter,
+    media_resolver: MediaResolver | None = None,
+) -> AsyncIterator[StreamDelta | GenerationOutput]:
+    client = get_client()
+    async with client.stream("POST", url, headers=headers, json=payload) as response:
+        if response.status_code != 200:
+            body = await response.aread()
+            raise ProviderError(response.status_code, body.decode())
+        async for item in adapter.parse_stream(response.aiter_lines()):
+            if isinstance(item, GenerationOutput) and media_resolver is not None:
+                item = await store_output_media(item, media_resolver)
+            yield item

fllme/http.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import httpx
+
+_client: httpx.AsyncClient | None = None
+
+
+def get_client() -> httpx.AsyncClient:
+    global _client  # noqa: PLW0603
+    if _client is None:
+        _client = httpx.AsyncClient(timeout=httpx.Timeout(120.0))
+    return _client
+
+
+async def close() -> None:
+    global _client  # noqa: PLW0603
+    if _client is not None:
+        await _client.aclose()
+        _client = None

fllme/media.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import copy
+from typing import Protocol, runtime_checkable
+
+from .errors import MediaResolutionError
+from .models.message import (
+    Base64Source,
+    MediaContent,
+    Message,
+    ReferenceSource,
+    UrlSource,
+)
+from .models.output.main import GenerationOutput
+
+
+@runtime_checkable
+class MediaResolver(Protocol):
+    async def resolve(
+        self, references: list[ReferenceSource]
+    ) -> list[Base64Source | UrlSource]:
+        """Outbound: convert user-domain IDs to provider-sendable sources."""
+        ...
+
+    async def store(
+        self, media: list[Base64Source | UrlSource]
+    ) -> list[ReferenceSource]:
+        """Inbound: upload AI-generated media, return user-domain IDs."""
+        ...
+
+
+async def resolve_references(
+    messages: list[Message], resolver: MediaResolver
+) -> list[Message]:
+    refs: list[ReferenceSource] = []
+    positions: list[tuple[int, int]] = []
+
+    for msg_idx, msg in enumerate(messages):
+        for blk_idx, block in enumerate(msg.contents):
+            if isinstance(block, MediaContent) and isinstance(
+                block.source, ReferenceSource
+            ):
+                refs.append(block.source)
+                positions.append((msg_idx, blk_idx))
+
+    if not refs:
+        return messages
+
+    try:
+        resolved = await resolver.resolve(refs)
+    except Exception as exc:
+        raise MediaResolutionError(
+            failed_ids=[r.id for r in refs],
+        ) from exc
+
+    out = copy.deepcopy(messages)
+    for (msg_idx, blk_idx), new_source in zip(positions, resolved):
+        block = out[msg_idx].contents[blk_idx]
+        assert isinstance(block, MediaContent)
+        block.source = new_source
+
+    return out
+
+
+async def store_media(message: Message, resolver: MediaResolver) -> Message:
+    sources: list[Base64Source | UrlSource] = []
+    positions: list[int] = []
+
+    for blk_idx, block in enumerate(message.contents):
+        if isinstance(block, MediaContent) and isinstance(
+            block.source, Base64Source | UrlSource
+        ):
+            sources.append(block.source)
+            positions.append(blk_idx)
+
+    if not sources:
+        return message
+
+    try:
+        stored = await resolver.store(sources)
+    except Exception as exc:
+        raise MediaResolutionError() from exc
+
+    out = message.model_copy(deep=True)
+    for blk_idx, new_ref in zip(positions, stored):
+        block = out.contents[blk_idx]
+        assert isinstance(block, MediaContent)
+        block.source = new_ref
+
+    return out
+
+
+async def store_output_media(
+    output: GenerationOutput, resolver: MediaResolver
+) -> GenerationOutput:
+    new_message = await store_media(output.message, resolver)
+    if new_message is output.message:
+        return output
+    return output.model_copy(update={"message": new_message})

fllme/models/__init__.py

@@ -0,0 +1,103 @@
+from .message import (
+    Base64Source,
+    Content,
+    ContentType,
+    ErrorContent,
+    MediaContent,
+    MediaSource,
+    Message,
+    MessageSource,
+    ReferenceSource,
+    SourceType,
+    TextContent,
+    ThinkingContent,
+    ToolCallContent,
+    ToolResponseContent,
+    UrlSource,
+)
+from .input import (
+    BasicOutputType,
+    GenerationInput,
+    ImageConfig,
+    LLMConfig,
+    MimeType,
+    OutputType,
+    PersonGeneration,
+    Ratio,
+    Resolution,
+    ThinkingLevel,
+    Tool,
+    ToolsCallingMode,
+    ToolsConfig,
+)
+from .auth import AuthPrinciple
+from .deployment import AdapterType, Deployment
+from .model import LLMModel, Provider
+from .output import (
+    CacheUsage,
+    Citation,
+    CitationType,
+    FinishReason,
+    GenerationOutput,
+    SafetyCategory,
+    SafetyRating,
+    SafetyResult,
+    SafetySeverity,
+    StreamDelta,
+    StreamEventType,
+    TextDelta,
+    TextSpan,
+    ThinkingDelta,
+    Usage,
+)
+
+__all__ = [
+    "AdapterType",
+    "AuthPrinciple",
+    "Base64Source",
+    "BasicOutputType",
+    "CacheUsage",
+    "Citation",
+    "CitationType",
+    "Content",
+    "ContentType",
+    "Deployment",
+    "ErrorContent",
+    "FinishReason",
+    "GenerationInput",
+    "GenerationOutput",
+    "ImageConfig",
+    "LLMConfig",
+    "LLMModel",
+    "MediaContent",
+    "MediaSource",
+    "Message",
+    "MessageSource",
+    "MimeType",
+    "OutputType",
+    "PersonGeneration",
+    "Provider",
+    "Ratio",
+    "ReferenceSource",
+    "Resolution",
+    "SafetyCategory",
+    "SafetyRating",
+    "SafetyResult",
+    "SafetySeverity",
+    "SourceType",
+    "StreamDelta",
+    "StreamEventType",
+    "TextContent",
+    "TextDelta",
+    "TextSpan",
+    "ThinkingContent",
+    "ThinkingDelta",
+    "ThinkingLevel",
+    "Tool",
+    "ToolCallContent",
+    "ToolResponseContent",
+    "ToolsCallingMode",
+    "ToolsConfig",
+    "UrlSource",
+    "Usage",
+]

fllme/models/auth.py

@@ -0,0 +1,28 @@
+from pydantic import BaseModel
+
+
+class AuthPrinciple(BaseModel):
+    id: str
+    name: str
+    resolver_id: str
+    required_env_vars: list[str] = []
+    config: dict[str, str] = {}
+
+
+GOOGLE_ADC_PRINCIPLE = AuthPrinciple(
+    id="google_adc",
+    name="Google ADC",
+    resolver_id="google_adc",
+    required_env_vars=[],
+    config={},
+)
+
+API_KEY_PRINCIPLE = AuthPrinciple(
+    id="api_key",
+    name="API Key",
+    resolver_id="api_key",
+    required_env_vars=[],
+    config={"header_name": "api-key"},
+)
+
+BUILTIN_PRINCIPLES: list[AuthPrinciple] = [GOOGLE_ADC_PRINCIPLE, API_KEY_PRINCIPLE]

fllme/models/deployment.py

@@ -0,0 +1,21 @@
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+
+class AdapterType(StrEnum):
+    ANTHROPIC_VERTEX_V1 = "anthropic_vertex_v1"
+    ANTHROPIC_VERTEX_V2 = "anthropic_vertex_v2"
+    GEMINI_VERTEX_V1 = "gemini_vertex_v1"
+    MISTRAL_VERTEX_V1 = "mistral_vertex_v1"
+    OPENAI_AZURE_V1 = "openai_azure_v1"
+    OPENAI_AZURE_V2 = "openai_azure_v2"
+    OPENAI_AZURE_V3 = "openai_azure_v3"
+
+
+class Deployment(BaseModel):
+    id: str
+    url: str
+    model_id: str
+    adapter: AdapterType
+    auth_id: str

fllme/models/input/__init__.py

@@ -0,0 +1,31 @@
+from .main import (
+    BasicOutputType,
+    GenerationInput,
+    LLMConfig,
+    OutputType,
+    ThinkingLevel,
+)
+from .tools import Tool, ToolsCallingMode, ToolsConfig
+from .image import (
+    ImageConfig,
+    MimeType,
+    PersonGeneration,
+    Ratio,
+    Resolution,
+)
+
+__all__ = [
+    "BasicOutputType",
+    "GenerationInput",
+    "ImageConfig",
+    "LLMConfig",
+    "MimeType",
+    "OutputType",
+    "PersonGeneration",
+    "Ratio",
+    "Resolution",
+    "ThinkingLevel",
+    "Tool",
+    "ToolsCallingMode",
+    "ToolsConfig",
+]

fllme/models/input/image.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel
+from enum import StrEnum
+
+
+class Ratio(StrEnum):
+    _1_1 = "1:1"
+    _2_3 = "2:3"
+    _3_2 = "3:2"
+    _3_4 = "3:4"
+    _4_3 = "4:3"
+    _9_16 = "9:16"
+    _16_9 = "16:9"
+    _21_9 = "21:9"
+
+
+class Resolution(StrEnum):
+    _1K = "1K"
+    _2K = "2K"
+    _4K = "4K"
+
+
+class PersonGeneration(StrEnum):
+    ALL = "ALLOW_ALL"
+    ADULT = "ALLOW_ADULT"
+    NONE = "ALLOW_NONE"
+
+
+class MimeType(StrEnum):
+    PNG = "image/png"
+    JPEG = "image/jpeg"
+
+
+class ImageConfig(BaseModel):
+    ratio: Ratio = Ratio._1_1
+    resolution: Resolution = Resolution._1K
+    person_generation: PersonGeneration = PersonGeneration.ALL
+    mime_type: MimeType = MimeType.PNG