velune-cli 0.9.0__py3-none-any.whl

velune/providers/adapters/openai.py

@@ -0,0 +1,213 @@
+"""OpenAI provider adapter implementation."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import AsyncIterator
+
+import httpx
+from pydantic import SecretStr
+
+from velune.core.errors.provider import (
+    InferenceError,
+    ProviderAuthenticationError,
+)
+from velune.core.types.inference import InferenceRequest, InferenceResponse, StreamChunk
+from velune.core.types.model import CapabilityLevel, ModelDescriptor
+from velune.core.types.provider import ProviderCapabilities, ProviderHealth
+from velune.providers.base import ModelProvider
+from velune.providers.keystore import get_key
+
+
+class OpenAIProvider(ModelProvider):
+    """OpenAI provider for GPT chat and embedding models."""
+
+    def __init__(
+        self, api_key: str | SecretStr | None = None, base_url: str = "https://api.openai.com/v1"
+    ) -> None:
+        self._api_key = api_key or get_key("openai")
+        if hasattr(self._api_key, "get_secret_value"):
+            self._api_key = self._api_key.get_secret_value()
+        self._base_url = base_url
+        self.client: httpx.AsyncClient | None = None
+        self._capabilities = ProviderCapabilities(
+            supports_streaming=True,
+            supports_function_calling=True,
+            supports_embeddings=True,
+            max_context_window=128000,
+        )
+
+    @property
+    def provider_id(self) -> str:
+        return "openai"
+
+    async def initialize(self) -> None:
+        """Initialize headers and async client connection."""
+        if not self._api_key:
+            raise ProviderAuthenticationError(
+                "OpenAI API key not found in configuration or environment"
+            )
+        if not self.client:
+            headers = {"Authorization": f"Bearer {self._api_key}"}
+            self.client = httpx.AsyncClient(base_url=self._base_url, headers=headers, timeout=300.0)
+
+    async def list_models(self) -> list[ModelDescriptor]:
+        """Return the current OpenAI model lineup."""
+        await self.initialize()
+        return [
+            ModelDescriptor(
+                model_id="gpt-4o",
+                display_name="GPT-4o",
+                provider_id="openai",
+                context_length=128000,
+                capabilities={
+                    "coding": CapabilityLevel.EXPERT,
+                    "reasoning": CapabilityLevel.EXPERT,
+                    "planning": CapabilityLevel.EXPERT,
+                    "summarization": CapabilityLevel.EXPERT,
+                    "instruction_following": CapabilityLevel.EXPERT,
+                    "tool_use": CapabilityLevel.EXPERT,
+                    "long_context": CapabilityLevel.EXPERT,
+                },
+                is_local=False,
+            ),
+            ModelDescriptor(
+                model_id="gpt-4o-mini",
+                display_name="GPT-4o Mini",
+                provider_id="openai",
+                context_length=128000,
+                capabilities={
+                    "coding": CapabilityLevel.ADVANCED,
+                    "reasoning": CapabilityLevel.ADVANCED,
+                    "planning": CapabilityLevel.ADVANCED,
+                    "summarization": CapabilityLevel.ADVANCED,
+                    "instruction_following": CapabilityLevel.EXPERT,
+                    "tool_use": CapabilityLevel.EXPERT,
+                    "long_context": CapabilityLevel.ADVANCED,
+                },
+                is_local=False,
+            ),
+            ModelDescriptor(
+                model_id="gpt-3.5-turbo",
+                display_name="GPT-3.5 Turbo",
+                provider_id="openai",
+                context_length=16385,
+                capabilities={
+                    "coding": CapabilityLevel.INTERMEDIATE,
+                    "reasoning": CapabilityLevel.INTERMEDIATE,
+                    "planning": CapabilityLevel.INTERMEDIATE,
+                    "summarization": CapabilityLevel.ADVANCED,
+                    "instruction_following": CapabilityLevel.ADVANCED,
+                    "tool_use": CapabilityLevel.INTERMEDIATE,
+                    "long_context": CapabilityLevel.BASIC,
+                },
+                is_local=False,
+                tags=["fallback"],
+            ),
+        ]
+
+    async def infer(self, request: InferenceRequest) -> InferenceResponse:
+        """Standard chat inference."""
+        await self.initialize()
+        assert self.client is not None
+        start = time.perf_counter()
+        try:
+            payload = {
+                "model": request.model_id,
+                "messages": request.messages,
+                "temperature": request.temperature,
+                "max_tokens": request.max_tokens,
+                "top_p": request.top_p,
+            }
+            if request.stop_sequences:
+                payload["stop"] = request.stop_sequences
+
+            response = await self.client.post("/chat/completions", json=payload)
+            response.raise_for_status()
+            data = response.json()
+            latency = (time.perf_counter() - start) * 1000.0
+
+            usage = data.get("usage", {})
+            return InferenceResponse(
+                content=data["choices"][0]["message"]["content"],
+                model_id=request.model_id,
+                finish_reason=data["choices"][0]["finish_reason"] or "stop",
+                tokens_used=usage.get("total_tokens", 0),
+                prompt_tokens=usage.get("prompt_tokens", 0),
+                completion_tokens=usage.get("completion_tokens", 0),
+                latency_ms=latency,
+            )
+        except httpx.HTTPError as e:
+            raise InferenceError(f"OpenAI completion failed: {e}")
+
+    async def stream(self, request: InferenceRequest) -> AsyncIterator[StreamChunk]:
+        """Streaming chat completions."""
+        await self.initialize()
+        assert self.client is not None
+        try:
+            payload = {
+                "model": request.model_id,
+                "messages": request.messages,
+                "temperature": request.temperature,
+                "max_tokens": request.max_tokens,
+                "top_p": request.top_p,
+                "stream": True,
+            }
+            if request.stop_sequences:
+                payload["stop"] = request.stop_sequences
+
+            async with self.client.stream("POST", "/chat/completions", json=payload) as response:
+                response.raise_for_status()
+                async for line in response.aiter_lines():
+                    if line.startswith("data: "):
+                        data_str = line[6:]
+                        if data_str == "[DONE]":
+                            break
+                        try:
+                            data = json.loads(data_str)
+                            delta = data["choices"][0]["delta"]
+                            yield StreamChunk(
+                                content=delta.get("content", ""),
+                                finish_reason=data["choices"][0].get("finish_reason"),
+                            )
+                        except (json.JSONDecodeError, KeyError):
+                            continue
+        except httpx.HTTPError as e:
+            raise InferenceError(f"OpenAI stream failed: {e}")
+
+    async def embed(self, texts: list[str], model_id: str) -> list[list[float]]:
+        """Generate batch embeddings."""
+        await self.initialize()
+        assert self.client is not None
+        try:
+            response = await self.client.post(
+                "/embeddings", json={"model": model_id, "input": texts}
+            )
+            response.raise_for_status()
+            data = response.json()
+            # Sort by index to maintain token alignments
+            sorted_data = sorted(data["data"], key=lambda x: x["index"])
+            return [item["embedding"] for item in sorted_data]
+        except httpx.HTTPError as e:
+            raise InferenceError(f"OpenAI embedding failed: {e}")
+
+    async def health_check(self) -> ProviderHealth:
+        """Verifies API credentials and connectivity."""
+        try:
+            await self.initialize()
+            assert self.client is not None
+            resp = await self.client.get("/models")
+            if resp.status_code == 200:
+                return ProviderHealth.HEALTHY
+            return ProviderHealth.DEGRADED
+        except Exception:
+            return ProviderHealth.UNAVAILABLE
+
+    def get_capabilities(self) -> ProviderCapabilities:
+        return self._capabilities
+
+    async def shutdown(self) -> None:
+        if self.client:
+            await self.client.aclose()
+            self.client = None

velune/providers/adapters/openrouter.py

@@ -0,0 +1,81 @@
+"""OpenRouter provider adapter — OpenAI-compatible with dynamic model listing."""
+
+from __future__ import annotations
+
+import httpx
+
+from velune.core.errors.provider import ProviderAuthenticationError
+from velune.core.types.model import CapabilityLevel, ModelCapabilityProfile, ModelDescriptor
+from velune.providers.adapters.openai import OpenAIProvider
+from velune.providers.keystore import get_key
+
+_REFERER_HEADERS = {
+    "HTTP-Referer": "Velune CLI",
+    "X-Title": "Velune CLI",
+}
+
+
+class OpenRouterProvider(OpenAIProvider):
+    """OpenRouter provider — routes to many upstream models via the OpenAI API shape."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://openrouter.ai/api/v1",
+    ) -> None:
+        super().__init__(api_key=api_key or get_key("openrouter"), base_url=base_url)
+
+    @property
+    def provider_id(self) -> str:
+        return "openrouter"
+
+    async def initialize(self) -> None:
+        """Override to inject the OpenRouter-required headers."""
+        if not self._api_key:
+            raise ProviderAuthenticationError(
+                "OpenRouter API key not found — set OPENROUTER_API_KEY or run: velune config set-key openrouter"
+            )
+        if not self.client:
+            headers = {
+                "Authorization": f"Bearer {self._api_key}",
+                **_REFERER_HEADERS,
+            }
+            self.client = httpx.AsyncClient(
+                base_url=self._base_url,
+                headers=headers,
+                timeout=300.0,
+            )
+
+    async def list_models(self) -> list[ModelDescriptor]:
+        """Fetch the current model catalogue from the OpenRouter API."""
+        await self.initialize()
+        assert self.client is not None
+        try:
+            resp = await self.client.get("/models")
+            resp.raise_for_status()
+            data = resp.json()
+            return [self._parse_model(m) for m in data.get("data", [])]
+        except Exception:
+            return []
+
+    def _parse_model(self, raw: dict) -> ModelDescriptor:
+        model_id = raw.get("id", "unknown")
+        context = raw.get("context_length") or 4096
+        pricing = raw.get("pricing", {})
+        cost_prompt = float(pricing.get("prompt", 0) or 0) * 1000
+        profile = ModelCapabilityProfile(
+            coding=CapabilityLevel.INTERMEDIATE,
+            reasoning=CapabilityLevel.INTERMEDIATE,
+            instruction_following=CapabilityLevel.ADVANCED,
+        )
+        return ModelDescriptor(
+            model_id=model_id,
+            display_name=raw.get("name") or model_id,
+            provider_id="openrouter",
+            context_length=context,
+            capabilities=profile,
+            is_local=False,
+            cost_per_1k_tokens=cost_prompt if cost_prompt > 0 else None,
+            tags=["cloud", "openrouter"],
+            metadata={"raw": raw},
+        )

velune/providers/adapters/together.py

@@ -0,0 +1,134 @@
+"""Together.AI provider adapter — OpenAI-compatible REST API."""
+
+from __future__ import annotations
+
+from velune.core.types.model import CapabilityLevel, ModelDescriptor
+from velune.core.types.provider import ProviderCapabilities
+from velune.providers.adapters.openai import OpenAIProvider
+from velune.providers.keystore import get_key
+
+TOGETHER_MODELS: list[ModelDescriptor] = [
+    ModelDescriptor(
+        model_id="meta-llama/Llama-3.3-70B-Instruct-Turbo",
+        display_name="Llama 3.3 70B Instruct Turbo",
+        provider_id="together",
+        context_length=131072,
+        capabilities={
+            "coding": CapabilityLevel.ADVANCED,
+            "reasoning": CapabilityLevel.ADVANCED,
+            "planning": CapabilityLevel.ADVANCED,
+            "summarization": CapabilityLevel.EXPERT,
+            "instruction_following": CapabilityLevel.EXPERT,
+            "tool_use": CapabilityLevel.ADVANCED,
+            "long_context": CapabilityLevel.ADVANCED,
+        },
+        speed_tier="fast",
+        is_local=False,
+        cost_per_1k_tokens=0.00088,
+        tags=["cloud", "together", "llama", "turbo"],
+    ),
+    ModelDescriptor(
+        model_id="meta-llama/Llama-3.2-11B-Vision-Instruct-Turbo",
+        display_name="Llama 3.2 11B Vision Instruct",
+        provider_id="together",
+        context_length=131072,
+        capabilities={
+            "coding": CapabilityLevel.INTERMEDIATE,
+            "reasoning": CapabilityLevel.INTERMEDIATE,
+            "planning": CapabilityLevel.INTERMEDIATE,
+            "summarization": CapabilityLevel.ADVANCED,
+            "instruction_following": CapabilityLevel.ADVANCED,
+            "tool_use": CapabilityLevel.INTERMEDIATE,
+            "long_context": CapabilityLevel.INTERMEDIATE,
+        },
+        speed_tier="fast",
+        is_local=False,
+        cost_per_1k_tokens=0.00018,
+        tags=["cloud", "together", "llama", "vision", "cheap"],
+    ),
+    ModelDescriptor(
+        model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
+        display_name="Qwen 2.5 Coder 32B Instruct",
+        provider_id="together",
+        context_length=131072,
+        capabilities={
+            "coding": CapabilityLevel.EXPERT,
+            "reasoning": CapabilityLevel.ADVANCED,
+            "planning": CapabilityLevel.ADVANCED,
+            "summarization": CapabilityLevel.ADVANCED,
+            "instruction_following": CapabilityLevel.EXPERT,
+            "tool_use": CapabilityLevel.ADVANCED,
+            "long_context": CapabilityLevel.ADVANCED,
+        },
+        speed_tier="medium",
+        is_local=False,
+        cost_per_1k_tokens=0.0008,
+        tags=["cloud", "together", "qwen", "coding"],
+    ),
+    ModelDescriptor(
+        model_id="deepseek-ai/DeepSeek-R1",
+        display_name="DeepSeek R1",
+        provider_id="together",
+        context_length=163840,
+        capabilities={
+            "coding": CapabilityLevel.EXPERT,
+            "reasoning": CapabilityLevel.EXPERT,
+            "planning": CapabilityLevel.EXPERT,
+            "summarization": CapabilityLevel.ADVANCED,
+            "instruction_following": CapabilityLevel.EXPERT,
+            "tool_use": CapabilityLevel.ADVANCED,
+            "long_context": CapabilityLevel.ADVANCED,
+        },
+        speed_tier="slow",
+        is_local=False,
+        cost_per_1k_tokens=0.003,
+        tags=["cloud", "together", "deepseek", "reasoning"],
+    ),
+    ModelDescriptor(
+        model_id="mistralai/Mistral-7B-Instruct-v0.3",
+        display_name="Mistral 7B Instruct v0.3",
+        provider_id="together",
+        context_length=32768,
+        capabilities={
+            "coding": CapabilityLevel.INTERMEDIATE,
+            "reasoning": CapabilityLevel.INTERMEDIATE,
+            "planning": CapabilityLevel.INTERMEDIATE,
+            "summarization": CapabilityLevel.ADVANCED,
+            "instruction_following": CapabilityLevel.ADVANCED,
+            "tool_use": CapabilityLevel.INTERMEDIATE,
+            "long_context": CapabilityLevel.BASIC,
+        },
+        speed_tier="fast",
+        is_local=False,
+        cost_per_1k_tokens=0.0002,
+        tags=["cloud", "together", "mistral", "cheap"],
+    ),
+]
+
+
+class TogetherProvider(OpenAIProvider):
+    """Together.AI — 50+ open models via OpenAI-compatible inference."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.together.xyz/v1",
+    ) -> None:
+        self._api_key = api_key or get_key("together")
+        if hasattr(self._api_key, "get_secret_value"):
+            self._api_key = self._api_key.get_secret_value()
+        self._base_url = base_url
+        self.client = None
+        self._capabilities = ProviderCapabilities(
+            supports_streaming=True,
+            supports_function_calling=True,
+            supports_embeddings=False,
+            max_context_window=131072,
+        )
+
+    @property
+    def provider_id(self) -> str:
+        return "together"
+
+    async def list_models(self) -> list[ModelDescriptor]:
+        return list(TOGETHER_MODELS)

velune/providers/adapters/xai.py

@@ -0,0 +1,60 @@
+"""xAI (Grok) provider adapter — OpenAI-compatible endpoint."""
+
+from __future__ import annotations
+
+from velune.core.types.model import CapabilityLevel, ModelDescriptor
+from velune.providers.adapters.openai import OpenAIProvider
+from velune.providers.keystore import get_key
+
+
+class XAIProvider(OpenAIProvider):
+    """xAI Grok provider.  Wire-compatible with the OpenAI chat API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.x.ai/v1",
+    ) -> None:
+        super().__init__(api_key=api_key or get_key("xai"), base_url=base_url)
+
+    @property
+    def provider_id(self) -> str:
+        return "xai"
+
+    async def list_models(self) -> list[ModelDescriptor]:
+        return [
+            ModelDescriptor(
+                model_id="grok-2",
+                display_name="Grok 2",
+                provider_id="xai",
+                context_length=131072,
+                capabilities={
+                    "coding": CapabilityLevel.ADVANCED,
+                    "reasoning": CapabilityLevel.ADVANCED,
+                    "planning": CapabilityLevel.ADVANCED,
+                    "summarization": CapabilityLevel.ADVANCED,
+                    "instruction_following": CapabilityLevel.EXPERT,
+                    "tool_use": CapabilityLevel.ADVANCED,
+                    "long_context": CapabilityLevel.ADVANCED,
+                },
+                is_local=False,
+                tags=["cloud", "xai"],
+            ),
+            ModelDescriptor(
+                model_id="grok-2-mini",
+                display_name="Grok 2 Mini",
+                provider_id="xai",
+                context_length=131072,
+                capabilities={
+                    "coding": CapabilityLevel.INTERMEDIATE,
+                    "reasoning": CapabilityLevel.INTERMEDIATE,
+                    "planning": CapabilityLevel.INTERMEDIATE,
+                    "summarization": CapabilityLevel.ADVANCED,
+                    "instruction_following": CapabilityLevel.ADVANCED,
+                    "tool_use": CapabilityLevel.INTERMEDIATE,
+                    "long_context": CapabilityLevel.ADVANCED,
+                },
+                is_local=False,
+                tags=["cloud", "xai", "mini"],
+            ),
+        ]

velune/providers/base.py

@@ -0,0 +1,86 @@
+"""Provider abstraction base interfaces and capabilities."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Protocol, runtime_checkable
+
+from velune.core.types.inference import InferenceRequest, InferenceResponse, StreamChunk
+from velune.core.types.model import ModelDescriptor
+from velune.core.types.provider import ProviderCapabilities, ProviderHealth
+
+
+@runtime_checkable
+class ModelProvider(Protocol):
+    """Core provider contract. All LLM and Embedding adapters implement this."""
+
+    @property
+    def provider_id(self) -> str:
+        """The distinct ID slug of this provider (e.g., 'ollama', 'openai')."""
+        ...
+
+    async def list_models(self) -> list[ModelDescriptor]:
+        """Query and list all active/available models for this provider."""
+        ...
+
+    async def infer(self, request: InferenceRequest) -> InferenceResponse:
+        """Single-turn, non-streaming model completion."""
+        ...
+
+    async def stream(self, request: InferenceRequest) -> AsyncIterator[StreamChunk]:
+        """Multi-turn, token-streaming model completion."""
+        ...
+
+    async def embed(self, texts: list[str], model_id: str) -> list[list[float]]:
+        """Generate vector embeddings. Raises NotImplementedError if unsupported."""
+        ...
+
+    async def health_check(self) -> ProviderHealth:
+        """Query host or ping API to verify provider state."""
+        ...
+
+    def get_capabilities(self) -> ProviderCapabilities:
+        """Query static/dynamic capabilities of the provider."""
+        ...
+
+    async def initialize(self) -> None:
+        """Perform provider connection setup and warmups."""
+        ...
+
+    async def shutdown(self) -> None:
+        """Gracefully release provider connection resource pools."""
+        ...
+
+
+class InferenceEngine(ABC):
+    """Abstract inference engine for unified task executions."""
+
+    @abstractmethod
+    async def infer(self, request: InferenceRequest) -> InferenceResponse:
+        """Perform non-streaming inference."""
+        pass
+
+    @abstractmethod
+    async def infer_stream(self, request: InferenceRequest) -> AsyncIterator[StreamChunk]:
+        """Perform streaming inference."""
+        pass
+
+
+class EmbeddingProvider(ABC):
+    """Abstract embedding provider interface."""
+
+    @abstractmethod
+    async def embed(self, text: str) -> list[float]:
+        """Generate embedding for a single text."""
+        pass
+
+    @abstractmethod
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for a batch of texts."""
+        pass
+
+    @abstractmethod
+    def get_dimension(self) -> int:
+        """Get the embedding dimension vector width."""
+        pass