flowent 0.0.0 → 0.0.4

package/backend/src/flowent/providers/configuration.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from flowent.models import ModelInfo
+from flowent.providers.base_url import resolve_provider_base_url
+from flowent.settings import (
+    PROVIDER_MODEL_SOURCE_OPTIONS,
+    ProviderConfig,
+    ProviderModelCatalogEntry,
+    build_model_context_window_tokens,
+    build_model_input_image,
+    build_model_output_image,
+    build_provider_headers,
+    build_provider_retry_429_delay_seconds,
+    serialize_provider_model_catalog_entry,
+)
+from flowent.settings import (
+    serialize_provider as serialize_full_provider,
+)
+
+
+class ProviderModelCatalogPayload(Protocol):
+    model: str
+    source: str
+    context_window_tokens: int | None
+    input_image: bool | None
+    output_image: bool | None
+
+
+def validate_provider_base_url_input(
+    provider_type: str,
+    base_url: str,
+    *,
+    required_message: str = "base_url is required",
+) -> str:
+    raw_base_url = base_url.strip()
+    if not raw_base_url:
+        raise ValueError(required_message)
+    resolve_provider_base_url(provider_type, raw_base_url)
+    return raw_base_url
+
+
+def build_provider_model_catalog_entry(
+    payload: ProviderModelCatalogPayload,
+    *,
+    field_name_prefix: str = "models[]",
+) -> ProviderModelCatalogEntry:
+    model = payload.model.strip()
+    if not model:
+        raise ValueError(f"{field_name_prefix}.model must not be empty")
+
+    source = payload.source.strip().lower()
+    if source not in PROVIDER_MODEL_SOURCE_OPTIONS:
+        raise ValueError(
+            f"{field_name_prefix}.source must be one of: discovered, manual"
+        )
+
+    return ProviderModelCatalogEntry(
+        model=model,
+        source=source,
+        context_window_tokens=build_model_context_window_tokens(
+            payload.context_window_tokens,
+            field_name=f"{field_name_prefix}.context_window_tokens",
+        ),
+        input_image=build_model_input_image(
+            payload.input_image,
+            field_name=f"{field_name_prefix}.input_image",
+        ),
+        output_image=build_model_output_image(
+            payload.output_image,
+            field_name=f"{field_name_prefix}.output_image",
+        ),
+    )
+
+
+def coerce_provider_model_catalog(
+    payloads: Iterable[ProviderModelCatalogPayload] | None,
+    *,
+    field_name_prefix: str = "models[]",
+) -> list[ProviderModelCatalogEntry]:
+    entries: list[ProviderModelCatalogEntry] = []
+    seen_models: set[str] = set()
+    for payload in payloads or ():
+        entry = build_provider_model_catalog_entry(
+            payload,
+            field_name_prefix=field_name_prefix,
+        )
+        if entry.model in seen_models:
+            raise ValueError(f"{field_name_prefix}.model '{entry.model}' is duplicated")
+        seen_models.add(entry.model)
+        entries.append(entry)
+    return entries
+
+
+def build_provider_config(
+    *,
+    provider_id: str,
+    name: str,
+    provider_type: str,
+    base_url: str,
+    api_key: str = "",
+    raw_headers: object = None,
+    raw_retry_429_delay_seconds: object = 0,
+    models: list[ProviderModelCatalogEntry] | None = None,
+    base_url_required_message: str = "base_url is required",
+) -> ProviderConfig:
+    return ProviderConfig(
+        id=provider_id,
+        name=name,
+        type=provider_type,
+        base_url=validate_provider_base_url_input(
+            provider_type,
+            base_url,
+            required_message=base_url_required_message,
+        ),
+        api_key=api_key,
+        headers=build_provider_headers(raw_headers),
+        retry_429_delay_seconds=build_provider_retry_429_delay_seconds(
+            raw_retry_429_delay_seconds
+        ),
+        models=list(models or []),
+    )
+
+
+def apply_provider_update(
+    provider: ProviderConfig,
+    *,
+    name: str | None = None,
+    provider_type: str | None = None,
+    base_url: str | None = None,
+    api_key: str | None = None,
+    raw_headers: object | None = None,
+    raw_retry_429_delay_seconds: object | None = None,
+    models: list[ProviderModelCatalogEntry] | None = None,
+) -> ProviderConfig:
+    next_type = provider_type if provider_type is not None else provider.type
+    next_base_url = base_url.strip() if base_url is not None else provider.base_url
+    raw_base_url = validate_provider_base_url_input(next_type, next_base_url)
+
+    if name is not None:
+        provider.name = name
+    if provider_type is not None:
+        provider.type = provider_type
+    if base_url is not None or provider_type is not None:
+        provider.base_url = raw_base_url
+    if api_key is not None:
+        provider.api_key = api_key
+    if raw_headers is not None:
+        provider.headers = build_provider_headers(raw_headers)
+    if raw_retry_429_delay_seconds is not None:
+        provider.retry_429_delay_seconds = build_provider_retry_429_delay_seconds(
+            raw_retry_429_delay_seconds
+        )
+    if models is not None:
+        provider.models = list(models)
+
+    return provider
+
+
+def serialize_provider(
+    provider: ProviderConfig,
+    *,
+    include_api_key: bool = True,
+) -> dict[str, object]:
+    data = serialize_full_provider(provider)
+    if not include_api_key:
+        data.pop("api_key", None)
+    return data
+
+
+def serialize_discovered_model_catalog_entry(model: ModelInfo) -> dict[str, object]:
+    return serialize_provider_model_catalog_entry(
+        ProviderModelCatalogEntry(
+            model=model.id,
+            source="discovered",
+            context_window_tokens=model.context_window_tokens,
+            input_image=model.capabilities.input_image,
+            output_image=model.capabilities.output_image,
+        )
+    )

package/backend/src/flowent/providers/content.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any
+
+from flowent.image_assets import (
+    encode_image_asset_as_base64,
+    encode_image_asset_as_data_url,
+)
+from flowent.models import (
+    ContentPart,
+    TextPart,
+    content_parts_to_text,
+    deserialize_content_parts,
+    has_image_parts,
+)
+
+
+def parse_message_content_parts(content: Any) -> list[ContentPart]:
+    if isinstance(content, str):
+        return [TextPart(text=content)] if content else []
+    return deserialize_content_parts(content)
+
+
+def collapse_parts_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    return content_parts_to_text(parse_message_content_parts(content))
+
+
+def has_image_content(content: Any) -> bool:
+    return has_image_parts(parse_message_content_parts(content))
+
+
+def to_openai_chat_content(
+    content: Any, *, allow_images: bool
+) -> str | list[dict[str, Any]]:
+    parts = parse_message_content_parts(content)
+    if not parts:
+        return ""
+    if not allow_images or not has_image_parts(parts):
+        return content_parts_to_text(parts)
+    payload: list[dict[str, Any]] = []
+    for part in parts:
+        if isinstance(part, TextPart):
+            payload.append({"type": "text", "text": part.text})
+            continue
+        _, data_url = encode_image_asset_as_data_url(part.asset_id)
+        payload.append(
+            {
+                "type": "image_url",
+                "image_url": {"url": data_url},
+            }
+        )
+    return payload
+
+
+def to_openai_responses_content(
+    content: Any, *, allow_images: bool
+) -> str | list[dict[str, Any]]:
+    parts = parse_message_content_parts(content)
+    if not parts:
+        return ""
+    if not allow_images or not has_image_parts(parts):
+        return content_parts_to_text(parts)
+    payload: list[dict[str, Any]] = []
+    for part in parts:
+        if isinstance(part, TextPart):
+            payload.append({"type": "input_text", "text": part.text})
+            continue
+        _, data_url = encode_image_asset_as_data_url(part.asset_id)
+        payload.append({"type": "input_image", "image_url": data_url})
+    return payload
+
+
+def to_anthropic_content(
+    content: Any, *, allow_images: bool
+) -> str | list[dict[str, Any]]:
+    parts = parse_message_content_parts(content)
+    if not parts:
+        return ""
+    if not allow_images or not has_image_parts(parts):
+        return content_parts_to_text(parts)
+    payload: list[dict[str, Any]] = []
+    for part in parts:
+        if isinstance(part, TextPart):
+            payload.append({"type": "text", "text": part.text})
+            continue
+        asset, encoded = encode_image_asset_as_base64(part.asset_id)
+        payload.append(
+            {
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": asset.mime_type,
+                    "data": encoded,
+                },
+            }
+        )
+    return payload
+
+
+def to_gemini_parts(content: Any, *, allow_images: bool) -> list[dict[str, Any]]:
+    parts = parse_message_content_parts(content)
+    if not parts:
+        return [{"text": ""}]
+    if not allow_images or not has_image_parts(parts):
+        return [{"text": content_parts_to_text(parts)}]
+    payload: list[dict[str, Any]] = []
+    for part in parts:
+        if isinstance(part, TextPart):
+            payload.append({"text": part.text})
+            continue
+        asset, encoded = encode_image_asset_as_base64(part.asset_id)
+        payload.append(
+            {
+                "inlineData": {
+                    "mimeType": asset.mime_type,
+                    "data": encoded,
+                }
+            }
+        )
+    return payload

package/backend/src/flowent/providers/errors.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from flowent.network import truncate_text
+
+
+class LLMProviderError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        transient: bool,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.transient = transient
+        self.status_code = status_code
+
+
+def is_transient_status_code(status_code: int) -> bool:
+    return status_code == 429 or 500 <= status_code < 600
+
+
+def build_status_error(
+    *,
+    provider_name: str,
+    provider_type: str,
+    model: str,
+    base_url: str,
+    status_code: int,
+    body: str,
+) -> LLMProviderError:
+    return LLMProviderError(
+        (
+            "LLM API error\n"
+            f"Provider: {provider_name}\n"
+            f"Type: {provider_type}\n"
+            f"Model: {model}\n"
+            f"Base URL: {base_url}\n"
+            f"Status: {status_code}\n"
+            f"Detail: {_normalize_status_detail(body)}"
+        ),
+        transient=is_transient_status_code(status_code),
+        status_code=status_code,
+    )
+
+
+def build_network_error(
+    *,
+    provider_name: str,
+    provider_type: str,
+    model: str,
+    base_url: str,
+    error: Exception,
+) -> LLMProviderError:
+    return LLMProviderError(
+        (
+            "LLM API network error\n"
+            f"Provider: {provider_name}\n"
+            f"Type: {provider_type}\n"
+            f"Model: {model}\n"
+            f"Base URL: {base_url}\n"
+            f"Error: {_normalize_network_error(error)}"
+        ),
+        transient=True,
+    )
+
+
+def build_configuration_error(
+    *,
+    provider_name: str,
+    provider_type: str,
+    model: str,
+    base_url: str,
+    detail: str,
+) -> LLMProviderError:
+    return LLMProviderError(
+        (
+            "LLM configuration error\n"
+            f"Provider: {provider_name}\n"
+            f"Type: {provider_type}\n"
+            f"Model: {model}\n"
+            f"Base URL: {base_url}\n"
+            f"Detail: {_compact_text(detail)}"
+        ),
+        transient=False,
+    )
+
+
+def build_access_blocked_error(
+    *,
+    provider_name: str,
+    provider_type: str,
+    model: str,
+    base_url: str,
+    status_code: int | None = None,
+    detail: str,
+) -> LLMProviderError:
+    status_line = f"Status: {status_code}\n" if status_code is not None else ""
+    return LLMProviderError(
+        (
+            "LLM API access blocked\n"
+            f"Provider: {provider_name}\n"
+            f"Type: {provider_type}\n"
+            f"Model: {model}\n"
+            f"Base URL: {base_url}\n"
+            f"{status_line}"
+            f"Detail: {_normalize_access_blocked_detail(detail)}"
+        ),
+        transient=False,
+        status_code=status_code,
+    )
+
+
+def _normalize_status_detail(body: str) -> str:
+    stripped = body.strip()
+    if not stripped:
+        return "Provider returned an empty error response"
+    if _looks_like_html(stripped):
+        return "Provider returned a non-API HTML response"
+    parsed = _parse_json_body(stripped)
+    if parsed is not None:
+        detail = _extract_detail(parsed)
+        if detail is not None:
+            return detail
+    first_line = stripped.splitlines()[0]
+    detail = _compact_text(first_line)
+    if not detail or detail.lower().startswith("traceback"):
+        return "Provider returned an unexpected error response"
+    return detail
+
+
+def _normalize_network_error(error: Exception) -> str:
+    detail = str(error).strip()
+    detail = re.sub(r"^[A-Za-z_][A-Za-z0-9_]*(?:Error|Exception):\s*", "", detail)
+    detail = re.sub(r"^Failed to perform,\s*", "", detail)
+    detail = re.sub(r"^curl:\s*\(\d+\)\s*", "", detail, flags=re.IGNORECASE)
+    detail = re.sub(r"^curl\s+error:\s*", "", detail, flags=re.IGNORECASE)
+    detail = re.sub(r"See https?://\S+ for more details\.?", "", detail)
+    detail = _compact_text(detail)
+    if not detail:
+        return "Request failed before the provider returned a response"
+    return detail
+
+
+def _normalize_access_blocked_detail(detail: str) -> str:
+    stripped = detail.strip()
+    if not stripped:
+        return "Challenge or interstitial response from upstream"
+    if _looks_like_html(stripped):
+        return "Challenge or interstitial HTML response from upstream"
+    normalized = _compact_text(stripped)
+    if not normalized:
+        return "Challenge or interstitial response from upstream"
+    return normalized
+
+
+def _parse_json_body(body: str) -> Any | None:
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return None
+
+
+def _extract_detail(value: Any) -> str | None:
+    if isinstance(value, str):
+        return _normalize_detail_text(value)
+    if isinstance(value, list):
+        for item in value:
+            detail = _extract_detail(item)
+            if detail is not None:
+                return detail
+        return None
+    if not isinstance(value, dict):
+        return None
+
+    nested_error = value.get("error")
+    if nested_error is not None:
+        detail = _extract_detail(nested_error)
+        if detail is not None:
+            return detail
+
+    for key in (
+        "message",
+        "detail",
+        "error_description",
+        "title",
+        "status",
+        "code",
+    ):
+        detail = _extract_detail(value.get(key))
+        if detail is not None:
+            return detail
+
+    for key in ("details", "errors"):
+        detail = _extract_detail(value.get(key))
+        if detail is not None:
+            return detail
+
+    return None
+
+
+def _normalize_detail_text(value: str) -> str | None:
+    normalized = _compact_text(value)
+    if not normalized:
+        return None
+    if normalized.lower().startswith("traceback"):
+        return "Upstream returned an unexpected error response"
+    return normalized
+
+
+def _compact_text(value: str, *, limit: int = 240) -> str:
+    return truncate_text(re.sub(r"\s+", " ", value).strip(), limit=limit)
+
+
+def _looks_like_html(value: str) -> bool:
+    lowered = value.lstrip().lower()
+    return lowered.startswith("<!doctype html") or (
+        lowered.startswith("<") and ">" in lowered
+    )

package/backend/src/flowent/providers/gateway.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from loguru import logger
+
+from flowent.models import LLMResponse, ModelInfo
+from flowent.providers import LLMProvider
+from flowent.providers.errors import build_configuration_error
+from flowent.settings import merge_model_params
+
+MODEL_DIRECTORY_TIMEOUT_SECONDS = 120.0
+
+ProviderCacheKey = tuple[
+    str,
+    str,
+    str,
+    str,
+    tuple[tuple[str, str], ...],
+    str,
+    str,
+    int,
+]
+
+
+class ProviderGateway:
+    def __init__(self) -> None:
+        self._cache: dict[ProviderCacheKey, LLMProvider] = {}
+        self._lock = threading.Lock()
+
+    def invalidate_cache(self) -> None:
+        with self._lock:
+            self._cache.clear()
+
+    def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[dict[str, Any]] | None = None,
+        on_chunk: Callable[[str, str], None] | None = None,
+        register_interrupt: Callable[[Callable[[], None] | None], None] | None = None,
+        role_name: str | None = None,
+    ) -> LLMResponse:
+        from flowent.settings import find_role, get_settings
+
+        settings = get_settings()
+        role_cfg = find_role(settings, role_name) if role_name else None
+        provider = self._resolve(settings=settings, role_cfg=role_cfg)
+        model_params = merge_model_params(
+            settings.model.params,
+            role_cfg.model_params if role_cfg is not None else None,
+        )
+        return provider.chat(
+            messages,
+            tools,
+            on_chunk,
+            register_interrupt,
+            model_params,
+        )
+
+    def list_models_for(
+        self,
+        provider_id: str,
+        register_interrupt: Callable[[Callable[[], None] | None], None] | None = None,
+    ) -> list[ModelInfo]:
+        from flowent.providers.registry import create_provider
+        from flowent.settings import find_provider, get_settings
+
+        settings = get_settings()
+        cfg = find_provider(settings, provider_id)
+        if cfg is None:
+            return []
+
+        provider = create_provider(
+            provider_type=cfg.type,
+            base_url=cfg.base_url,
+            api_key=cfg.api_key,
+            headers=cfg.headers,
+            model="",
+            provider_name=cfg.name,
+            request_timeout_seconds=MODEL_DIRECTORY_TIMEOUT_SECONDS,
+        )
+        return provider.list_models(register_interrupt)
+
+    def _resolve(
+        self,
+        *,
+        settings=None,
+        role_cfg=None,
+        role_name: str | None = None,
+    ) -> LLMProvider:
+        from flowent.providers.registry import create_provider
+        from flowent.settings import find_provider, find_role, get_settings
+
+        if settings is None:
+            settings = get_settings()
+        provider_id = settings.model.active_provider_id
+        model = settings.model.active_model
+
+        if role_cfg is None and role_name:
+            role_cfg = find_role(settings, role_name)
+        if (
+            role_cfg is not None
+            and role_cfg.model is not None
+            and role_cfg.model.provider_id
+            and role_cfg.model.model
+        ):
+            provider_id = role_cfg.model.provider_id
+            model = role_cfg.model.model
+
+        if not provider_id:
+            raise RuntimeError("No active provider configured")
+
+        cfg = find_provider(settings, provider_id)
+        if cfg is None:
+            raise RuntimeError(f"Provider '{provider_id}' not found")
+
+        if not model.strip():
+            raise build_configuration_error(
+                provider_name=cfg.name,
+                provider_type=cfg.type,
+                model=model,
+                base_url=cfg.base_url,
+                detail="No active model configured",
+            )
+
+        provider_type = cfg.type
+        base_url = cfg.base_url
+        api_key = cfg.api_key
+        provider_name = cfg.name
+        request_timeout_seconds = settings.model.timeout_ms / 1000
+        cache_key = (
+            cfg.id,
+            provider_type,
+            base_url,
+            api_key,
+            tuple(sorted(cfg.headers.items())),
+            provider_name,
+            model,
+            settings.model.timeout_ms,
+        )
+
+        with self._lock:
+            if cache_key in self._cache:
+                return self._cache[cache_key]
+
+            logger.debug(
+                "ProviderGateway resolved: name={}, type={}, model={}",
+                provider_name,
+                provider_type,
+                model,
+            )
+
+            provider = create_provider(
+                provider_type=provider_type,
+                base_url=base_url,
+                api_key=api_key,
+                headers=cfg.headers,
+                model=model,
+                provider_name=provider_name,
+                request_timeout_seconds=request_timeout_seconds,
+            )
+
+            self._cache[cache_key] = provider
+            return provider
+
+
+gateway = ProviderGateway()