flowai-cli 0.2.0__py3-none-any.whl

flowai/providers/base.py

@@ -0,0 +1,180 @@
+"""Provider Abstraction Layer - Core data structures and BaseProvider."""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, Field
+
+from flowai.errors import ConfigurationError, ProviderError
+
+
+class ToolCall(BaseModel):
+    """Represents a model tool/function call request."""
+    id: str
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    """Result of an executed tool call."""
+    tool_call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+
+
+class Message(BaseModel):
+    """Unified message structure across all LLM providers."""
+    role: str  # "system" | "user" | "assistant" | "tool"
+    content: str | None = None
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    tool_call_id: str | None = None
+    name: str | None = None
+
+
+class ProviderUsage(BaseModel):
+    """Token and cost telemetry for a model invocation."""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+    estimated_cost_usd: float = 0.0
+
+
+class ProviderResponse(BaseModel):
+    """Standard non-streaming completion output."""
+    content: str = ""
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    finish_reason: str = "stop"
+    usage: ProviderUsage = Field(default_factory=ProviderUsage)
+
+
+class StreamChunk(BaseModel):
+    """Incremental chunk emitted during streaming."""
+    text_delta: str = ""
+    tool_call_delta: ToolCall | None = None
+    finish_reason: str | None = None
+    usage: ProviderUsage | None = None
+
+
+class BaseProvider(ABC):
+    """Abstract Base Class for all LLM Provider implementations in FlowAI.
+
+    Subclasses must implement:
+      - generate(): non-streaming text/tool generation
+      - stream(): asynchronous token/tool streaming
+      - embeddings(): vector embedding generation
+
+    Streaming contract: a provider yields text as `text_delta` chunks, and
+    emits every tool call the model requested exactly once as a *complete*
+    `tool_call_delta` (fragments are assembled inside the provider). Agents
+    rely on that, so they can act on a streamed tool call.
+    """
+
+    #: Environment variable holding this provider's key, if it needs one.
+    api_key_env: str | None = None
+    #: Local providers such as Ollama need no key.
+    requires_api_key: bool = True
+
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        **kwargs: Any,
+    ):
+        self.model = model
+        self.api_key = api_key
+        self.base_url = base_url
+        self.timeout = timeout
+        self.extra_kwargs = kwargs
+
+    @abstractmethod
+    async def generate(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> ProviderResponse:
+        """Execute a non-streaming completion."""
+        ...
+
+    @abstractmethod
+    async def stream(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamChunk]:
+        """Execute a streaming completion yielding token/tool deltas."""
+        ...
+
+    @abstractmethod
+    async def embeddings(
+        self,
+        texts: list[str],
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        """Compute text vector embeddings."""
+        ...
+
+    @property
+    def provider_name(self) -> str:
+        """Short lowercase name, e.g. 'anthropic' for AnthropicProvider."""
+        return self.__class__.__name__.replace("Provider", "").lower()
+
+    def require_api_key(self) -> None:
+        """Fail early, and in plain words, when the key for this provider is missing."""
+        if not self.requires_api_key or self.api_key:
+            return
+        env_hint = f" Set {self.api_key_env}," if self.api_key_env else ""
+        raise ConfigurationError(
+            f"No API key for the {self.provider_name} provider.{env_hint}"
+            " or run 'flowai configure' to save one."
+        )
+
+    async def _raise_for_status(self, response: httpx.Response) -> None:
+        """Turn an HTTP error into a ProviderError that quotes the API's own message."""
+        if response.status_code < 400:
+            return
+        # A streamed response has not been read yet; read it before touching .text.
+        if not response.is_closed:
+            await response.aread()
+        detail = response.text.strip()
+        try:
+            payload = json.loads(detail)
+            error = payload.get("error", payload)
+            if isinstance(error, dict):
+                detail = error.get("message") or json.dumps(error)
+            elif isinstance(error, str):
+                detail = error
+        except (json.JSONDecodeError, AttributeError):
+            pass
+        if len(detail) > 500:
+            detail = detail[:500] + "..."
+        raise ProviderError(self.provider_name, response.status_code, detail or response.reason_phrase)
+
+    def parse_tool_call(self, raw_call: dict[str, Any]) -> ToolCall:
+        """Helper to safely parse tool call dictionary into ToolCall object."""
+        tc_id = raw_call.get("id", "")
+        function_data = raw_call.get("function", {})
+        name = function_data.get("name", "")
+        args_raw = function_data.get("arguments", "{}")
+        if isinstance(args_raw, str):
+            try:
+                args = json.loads(args_raw)
+            except Exception:
+                args = {"raw": args_raw}
+        else:
+            args = args_raw or {}
+        return ToolCall(id=tc_id, name=name, arguments=args)

flowai/providers/gemini.py

@@ -0,0 +1,230 @@
+"""Google Gemini Provider implementation."""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+import httpx
+
+from flowai.providers.base import (
+    BaseProvider,
+    Message,
+    ProviderResponse,
+    ProviderUsage,
+    StreamChunk,
+    ToolCall,
+)
+
+
+class GeminiProvider(BaseProvider):
+    """Google Gemini Provider (Gemini 2.5 Flash, Gemini 1.5 Pro, etc.)."""
+
+    DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+    api_key_env = "GEMINI_API_KEY"
+
+    def __init__(
+        self,
+        model: str = "gemini-2.0-flash",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        **kwargs: Any,
+    ):
+        resolved_key = api_key or os.getenv("GEMINI_API_KEY", "")
+        resolved_url = base_url or os.getenv("GEMINI_BASE_URL", self.DEFAULT_BASE_URL)
+        super().__init__(
+            model=model,
+            api_key=resolved_key,
+            base_url=resolved_url,
+            timeout=timeout,
+            **kwargs,
+        )
+
+    def _convert_messages(self, messages: Sequence[Message]) -> tuple[dict[str, Any] | None, list[dict[str, Any]]]:
+        system_instruction = None
+        contents = []
+
+        for m in messages:
+            if m.role == "system":
+                system_instruction = {"parts": [{"text": m.content or ""}]}
+            elif m.role == "tool":
+                contents.append({
+                    "role": "function",
+                    "parts": [{
+                        "functionResponse": {
+                            "name": m.name or "tool",
+                            "response": {"result": m.content or ""},
+                        }
+                    }],
+                })
+            elif m.role == "assistant":
+                parts: list[dict[str, Any]] = []
+                if m.content:
+                    parts.append({"text": m.content})
+                for tc in m.tool_calls:
+                    parts.append({
+                        "functionCall": {
+                            "name": tc.name,
+                            "args": tc.arguments,
+                        }
+                    })
+                contents.append({"role": "model", "parts": parts})
+            else:
+                contents.append({"role": "user", "parts": [{"text": m.content or ""}]})
+
+        return system_instruction, contents
+
+    def _convert_tools(self, tools: Sequence[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Translate OpenAI-style tool schemas into Gemini functionDeclarations."""
+        declarations = []
+        for t in tools:
+            fn = t.get("function", t)
+            parameters = dict(fn.get("parameters") or {"type": "object", "properties": {}})
+            # Gemini rejects an empty-property object schema, so omit it entirely.
+            if not parameters.get("properties"):
+                parameters = None
+            declaration = {
+                "name": fn.get("name"),
+                "description": fn.get("description", ""),
+            }
+            if parameters:
+                declaration["parameters"] = parameters
+            declarations.append(declaration)
+        return [{"functionDeclarations": declarations}]
+
+    @staticmethod
+    def _usage_from(meta: dict[str, Any]) -> ProviderUsage:
+        return ProviderUsage(
+            prompt_tokens=meta.get("promptTokenCount", 0),
+            completion_tokens=meta.get("candidatesTokenCount", 0),
+            total_tokens=meta.get("totalTokenCount", 0),
+        )
+
+    async def generate(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> ProviderResponse:
+        url = f"{self.base_url.rstrip('/')}/models/{self.model}:generateContent?key={self.api_key}"
+        system_instruction, contents = self._convert_messages(messages)
+        payload: dict[str, Any] = {
+            "contents": contents,
+            "generationConfig": {"temperature": temperature},
+        }
+        if max_tokens:
+            payload["generationConfig"]["maxOutputTokens"] = max_tokens
+        if system_instruction:
+            payload["systemInstruction"] = system_instruction
+        if tools:
+            payload["tools"] = self._convert_tools(tools)
+
+        self.require_api_key()
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, json=payload)
+            await self._raise_for_status(resp)
+            data = resp.json()
+
+        candidates = data.get("candidates", [])
+        content_text = ""
+        tool_calls: list[ToolCall] = []
+
+        if candidates:
+            cand = candidates[0]
+            parts = cand.get("content", {}).get("parts", [])
+            for p in parts:
+                if "text" in p:
+                    content_text += p["text"]
+                elif "functionCall" in p:
+                    fc = p["functionCall"]
+                    tool_calls.append(
+                        ToolCall(
+                            id=fc.get("name", "call"),
+                            name=fc.get("name", ""),
+                            arguments=fc.get("args", {}),
+                        )
+                    )
+
+        usage = self._usage_from(data.get("usageMetadata", {}))
+
+        return ProviderResponse(
+            content=content_text,
+            tool_calls=tool_calls,
+            finish_reason="stop",
+            usage=usage,
+        )
+
+    async def stream(
+        self,
+        messages: Sequence[Message],
+        tools: Sequence[dict[str, Any]] | None = None,
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[StreamChunk]:
+        url = f"{self.base_url.rstrip('/')}/models/{self.model}:streamGenerateContent?key={self.api_key}&alt=sse"
+        system_instruction, contents = self._convert_messages(messages)
+        payload: dict[str, Any] = {
+            "contents": contents,
+            "generationConfig": {"temperature": temperature},
+        }
+        if max_tokens:
+            payload["generationConfig"]["maxOutputTokens"] = max_tokens
+        if system_instruction:
+            payload["systemInstruction"] = system_instruction
+        if tools:
+            payload["tools"] = self._convert_tools(tools)
+
+        self.require_api_key()
+        call_index = 0
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            async with client.stream("POST", url, json=payload) as response:
+                await self._raise_for_status(response)
+                async for line in response.aiter_lines():
+                    line = line.strip()
+                    if not line.startswith("data: "):
+                        continue
+                    try:
+                        data = json.loads(line[6:])
+                    except json.JSONDecodeError:
+                        continue
+
+                    for candidate in data.get("candidates", []):
+                        for part in candidate.get("content", {}).get("parts", []):
+                            if "text" in part:
+                                yield StreamChunk(text_delta=part["text"])
+                            elif "functionCall" in part:
+                                fc = part["functionCall"]
+                                call_index += 1
+                                yield StreamChunk(
+                                    tool_call_delta=ToolCall(
+                                        id=f"{fc.get('name', 'call')}_{call_index}",
+                                        name=fc.get("name", ""),
+                                        arguments=fc.get("args", {}) or {},
+                                    )
+                                )
+                        if candidate.get("finishReason"):
+                            yield StreamChunk(finish_reason=candidate["finishReason"])
+
+                    if data.get("usageMetadata"):
+                        yield StreamChunk(usage=self._usage_from(data["usageMetadata"]))
+
+    async def embeddings(
+        self,
+        texts: list[str],
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        url = f"{self.base_url.rstrip('/')}/models/{model or 'text-embedding-004'}:batchEmbedContents?key={self.api_key}"
+        requests = [{"model": f"models/{model or 'text-embedding-004'}", "content": {"parts": [{"text": t}]}} for t in texts]
+        self.require_api_key()
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, json={"requests": requests})
+            await self._raise_for_status(resp)
+            data = resp.json()
+        return [e["values"] for e in data.get("embeddings", [])]

flowai/providers/nvidia.py

@@ -0,0 +1,57 @@
+"""NVIDIA API Catalog Provider implementation.
+
+The catalog speaks the OpenAI chat-completions protocol, so this provider is
+the OpenAI one pointed at NVIDIA's endpoint. Only the embeddings call differs:
+NVIDIA's models require an input_type.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from flowai.providers.openai import OpenAIProvider
+
+
+class NvidiaProvider(OpenAIProvider):
+    """NVIDIA API Catalog Provider for models like DeepSeek-R1 and Llama 3.1."""
+
+    DEFAULT_BASE_URL = "https://integrate.api.nvidia.com/v1"
+    api_key_env = "NVIDIA_API_KEY"
+
+    def __init__(
+        self,
+        model: str = "meta/llama-3.1-70b-instruct",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 60.0,
+        **kwargs: Any,
+    ):
+        super().__init__(
+            model=model,
+            api_key=api_key or os.getenv("NVIDIA_API_KEY", ""),
+            base_url=base_url or os.getenv("NVIDIA_BASE_URL", self.DEFAULT_BASE_URL),
+            timeout=timeout,
+            **kwargs,
+        )
+
+    async def embeddings(
+        self,
+        texts: list[str],
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> list[list[float]]:
+        url = f"{self.base_url.rstrip('/')}/embeddings"
+        payload = {
+            "input": texts,
+            "model": model or "nvidia/nv-embed-v1",
+            "input_type": kwargs.get("input_type", "query"),
+        }
+        self.require_api_key()
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            resp = await client.post(url, headers=self._get_headers(), json=payload)
+            await self._raise_for_status(resp)
+            data = resp.json()
+        return [item["embedding"] for item in data.get("data", [])]