velune-cli 1.0.0__py3-none-any.whl

velune/providers/discovery/openrouter.py

@@ -0,0 +1,113 @@
+"""OpenRouter model discovery with 1-hour local cache."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import httpx
+
+from velune.core.types.model import CapabilityLevel, ModelCapabilityProfile, ModelDescriptor
+from velune.providers.keystore import get_key
+
+_CACHE_TTL = 3600.0  # seconds
+
+
+def _cache_path() -> Path:
+    """Resolve the cache file location, preferring the project .velune dir."""
+    project = Path.cwd() / ".velune"
+    if project.exists():
+        return project / "openrouter_models_cache.json"
+    home = Path.home() / ".velune"
+    home.mkdir(parents=True, exist_ok=True)
+    return home / "openrouter_models_cache.json"
+
+
+class OpenRouterDiscovery:
+    """Fetches the full OpenRouter model catalogue with a 1-hour disk cache."""
+
+    provider_id = "openrouter"
+
+    async def discover(self) -> list[ModelDescriptor]:
+        if not get_key("openrouter"):
+            return []
+
+        cached = self._load_cache()
+        if cached is not None:
+            return cached
+
+        models = await self._fetch()
+        self._save_cache(models)
+        return models
+
+    def _load_cache(self) -> list[ModelDescriptor] | None:
+        path = _cache_path()
+        if not path.exists():
+            return None
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if time.time() - data.get("cached_at", 0) > _CACHE_TTL:
+                return None
+            return [self._raw_to_descriptor(m) for m in data.get("models", [])]
+        except Exception:
+            return None
+
+    def _save_cache(self, models: list[ModelDescriptor]) -> None:
+        path = _cache_path()
+        try:
+            raw = [
+                {
+                    "id": m.model_id,
+                    "name": m.display_name,
+                    "context_length": m.context_length,
+                    "cost_per_1k_tokens": m.cost_per_1k_tokens,
+                }
+                for m in models
+            ]
+            path.write_text(
+                json.dumps({"cached_at": time.time(), "models": raw}, indent=2),
+                encoding="utf-8",
+            )
+        except Exception:
+            pass
+
+    async def _fetch(self) -> list[ModelDescriptor]:
+        api_key = get_key("openrouter")
+        try:
+            headers = {
+                "Authorization": f"Bearer {api_key}",
+                "HTTP-Referer": "Velune CLI",
+                "X-Title": "Velune CLI",
+            }
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                resp = await client.get(
+                    "https://openrouter.ai/api/v1/models",
+                    headers=headers,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                return [self._raw_to_descriptor(m) for m in data.get("data", [])]
+        except Exception:
+            return []
+
+    def _raw_to_descriptor(self, raw: dict) -> ModelDescriptor:
+        model_id = raw.get("id", "unknown")
+        context = raw.get("context_length") or 4096
+        pricing = raw.get("pricing", {})
+        cost = float(pricing.get("prompt", 0) or 0) * 1000
+        return ModelDescriptor(
+            model_id=model_id,
+            provider_id="openrouter",
+            display_name=raw.get("name") or model_id,
+            context_length=context,
+            capabilities=ModelCapabilityProfile(
+                coding=CapabilityLevel.INTERMEDIATE,
+                reasoning=CapabilityLevel.INTERMEDIATE,
+                instruction_following=CapabilityLevel.ADVANCED,
+            ),
+            speed_tier="medium",
+            cost_per_1k_tokens=cost if cost > 0 else None,
+            tags=["cloud", "openrouter"],
+            metadata={},
+        )

velune/providers/discovery/scanner.py

@@ -0,0 +1,114 @@
+"""Unified model discovery coordinator."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from velune.core.types.model import ModelDescriptor
+from velune.providers.discovery.anthropic import AnthropicDiscovery
+from velune.providers.discovery.fireworks import FireworksDiscovery
+from velune.providers.discovery.gguf import GGUFDiscovery
+from velune.providers.discovery.google import GoogleDiscovery
+from velune.providers.discovery.groq import GroqDiscovery
+from velune.providers.discovery.huggingface import HuggingFaceDiscovery
+from velune.providers.discovery.lmstudio import LMStudioDiscovery
+from velune.providers.discovery.ollama import OllamaDiscovery
+from velune.providers.discovery.openai import OpenAIDiscovery
+from velune.providers.discovery.openrouter import OpenRouterDiscovery
+from velune.providers.discovery.together import TogetherDiscovery
+from velune.providers.discovery.xai import XAIDiscovery
+
+logger = logging.getLogger("velune.providers.discovery.scanner")
+
+# Providers that run locally and need no API key
+_LOCAL_PROVIDERS: frozenset[str] = frozenset({"ollama", "lmstudio", "gguf", "llamacpp"})
+
+
+class ModelDiscoveryScanner:
+    """Coordinates model discovery across all configured providers.
+
+    Cloud discoverers are only invoked when a key is available for that
+    provider.  Local discoverers always run; Ollama and LM Studio are
+    additionally gated on their daemon being reachable.
+    """
+
+    def __init__(self) -> None:
+        self.discoverers = [
+            OllamaDiscovery(),
+            LMStudioDiscovery(),
+            GGUFDiscovery(),
+            HuggingFaceDiscovery(),
+            OpenAIDiscovery(),
+            AnthropicDiscovery(),
+            XAIDiscovery(),
+            GoogleDiscovery(),
+            GroqDiscovery(),
+            OpenRouterDiscovery(),
+            TogetherDiscovery(),
+            FireworksDiscovery(),
+        ]
+
+    def _should_run(self, discoverer) -> bool:
+        """Return True if this discoverer should be queried."""
+        if discoverer.provider_id in _LOCAL_PROVIDERS:
+            return True
+        from velune.providers.keystore import has_key
+        return has_key(discoverer.provider_id)
+
+    async def _collect(self, discoverer) -> list[ModelDescriptor]:
+        """Run a single discoverer, returning [] on any failure."""
+        try:
+            return await discoverer.discover()
+        except Exception as e:
+            logger.debug("Discovery failed for %s: %s", discoverer.provider_id, e)
+            return []
+
+    async def scan_all(self) -> list[ModelDescriptor]:
+        """Scan all providers for models in parallel."""
+        # Gate server-dependent local providers on reachability
+        ollama_ok, lmstudio_ok = await asyncio.gather(
+            OllamaDiscovery.is_running(),
+            LMStudioDiscovery.is_running(),
+        )
+
+        tasks = []
+        for d in self.discoverers:
+            if d.provider_id == "ollama" and not ollama_ok:
+                continue
+            if d.provider_id == "lmstudio" and not lmstudio_ok:
+                continue
+            if self._should_run(d):
+                tasks.append(self._collect(d))
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        all_models: list[ModelDescriptor] = []
+        for result in results:
+            if isinstance(result, list):
+                all_models.extend(result)
+
+        # Summary log
+        counts: dict[str, int] = {"gguf": 0, "ollama": 0, "lmstudio": 0, "cloud": 0}
+        for m in all_models:
+            if m.provider_id in counts:
+                counts[m.provider_id] += 1
+            elif m.provider_id not in _LOCAL_PROVIDERS:
+                counts["cloud"] += 1
+
+        logger.info(
+            "Local: %d GGUF, %d Ollama, %d LM Studio | Cloud: %d models",
+            counts["gguf"],
+            counts["ollama"],
+            counts["lmstudio"],
+            counts["cloud"],
+        )
+
+        return all_models
+
+    async def scan_provider(self, provider_id: str) -> list[ModelDescriptor]:
+        """Scan a specific provider by ID."""
+        for discoverer in self.discoverers:
+            if discoverer.provider_id == provider_id:
+                return await self._collect(discoverer)
+        return []

velune/providers/discovery/together.py

@@ -0,0 +1,114 @@
+"""Together.AI model discovery."""
+
+from __future__ import annotations
+
+from velune.core.types.model import CapabilityLevel, ModelCapabilityProfile, ModelDescriptor
+from velune.providers.keystore import get_key
+
+
+class TogetherDiscovery:
+    """Returns the hardcoded Together.AI model list when a key is configured."""
+
+    provider_id = "together"
+
+    async def discover(self) -> list[ModelDescriptor]:
+        if not get_key("together"):
+            return []
+
+        return [
+            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=ModelCapabilityProfile(
+                    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",
+                cost_per_1k_tokens=0.00088,
+                tags=["cloud", "together", "llama", "turbo"],
+                metadata={},
+            ),
+            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=ModelCapabilityProfile(
+                    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",
+                cost_per_1k_tokens=0.00018,
+                tags=["cloud", "together", "llama", "vision", "cheap"],
+                metadata={},
+            ),
+            ModelDescriptor(
+                model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
+                display_name="Qwen 2.5 Coder 32B Instruct",
+                provider_id="together",
+                context_length=131072,
+                capabilities=ModelCapabilityProfile(
+                    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",
+                cost_per_1k_tokens=0.0008,
+                tags=["cloud", "together", "qwen", "coding"],
+                metadata={},
+            ),
+            ModelDescriptor(
+                model_id="deepseek-ai/DeepSeek-R1",
+                display_name="DeepSeek R1",
+                provider_id="together",
+                context_length=163840,
+                capabilities=ModelCapabilityProfile(
+                    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",
+                cost_per_1k_tokens=0.003,
+                tags=["cloud", "together", "deepseek", "reasoning"],
+                metadata={},
+            ),
+            ModelDescriptor(
+                model_id="mistralai/Mistral-7B-Instruct-v0.3",
+                display_name="Mistral 7B Instruct v0.3",
+                provider_id="together",
+                context_length=32768,
+                capabilities=ModelCapabilityProfile(
+                    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",
+                cost_per_1k_tokens=0.0002,
+                tags=["cloud", "together", "mistral", "cheap"],
+                metadata={},
+            ),
+        ]

velune/providers/discovery/xai.py

@@ -0,0 +1,57 @@
+"""xAI (Grok) model discovery."""
+
+from __future__ import annotations
+
+from velune.core.types.model import CapabilityLevel, ModelCapabilityProfile, ModelDescriptor
+from velune.providers.keystore import get_key
+
+
+class XAIDiscovery:
+    """Returns the hardcoded xAI Grok model list when a key is configured."""
+
+    provider_id = "xai"
+
+    async def discover(self) -> list[ModelDescriptor]:
+        if not get_key("xai"):
+            return []
+
+        return [
+            ModelDescriptor(
+                model_id="grok-2",
+                provider_id="xai",
+                display_name="Grok 2",
+                context_length=131072,
+                capabilities=ModelCapabilityProfile(
+                    coding=CapabilityLevel.ADVANCED,
+                    reasoning=CapabilityLevel.ADVANCED,
+                    planning=CapabilityLevel.ADVANCED,
+                    summarization=CapabilityLevel.ADVANCED,
+                    instruction_following=CapabilityLevel.EXPERT,
+                    tool_use=CapabilityLevel.ADVANCED,
+                    long_context=CapabilityLevel.ADVANCED,
+                ),
+                speed_tier="medium",
+                cost_per_1k_tokens=0.005,
+                tags=["cloud", "xai"],
+                metadata={},
+            ),
+            ModelDescriptor(
+                model_id="grok-2-mini",
+                provider_id="xai",
+                display_name="Grok 2 Mini",
+                context_length=131072,
+                capabilities=ModelCapabilityProfile(
+                    coding=CapabilityLevel.INTERMEDIATE,
+                    reasoning=CapabilityLevel.INTERMEDIATE,
+                    planning=CapabilityLevel.INTERMEDIATE,
+                    summarization=CapabilityLevel.ADVANCED,
+                    instruction_following=CapabilityLevel.ADVANCED,
+                    tool_use=CapabilityLevel.INTERMEDIATE,
+                    long_context=CapabilityLevel.ADVANCED,
+                ),
+                speed_tier="fast",
+                cost_per_1k_tokens=0.0005,
+                tags=["cloud", "xai", "mini"],
+                metadata={},
+            ),
+        ]

velune/providers/keystore.py

@@ -0,0 +1,83 @@
+"""BYOK key storage backed by the OS keyring with env-var fallback."""
+
+from __future__ import annotations
+
+import os
+
+import keyring
+import keyring.errors
+
+_SERVICE = "velune/{}"
+_USERNAME = "api_key"
+
+PROVIDER_ENV_VARS: dict[str, str] = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "xai": "XAI_API_KEY",
+    "google": "GOOGLE_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+    "huggingface": "HF_TOKEN",
+    "together": "TOGETHER_API_KEY",
+    "fireworks": "FIREWORKS_API_KEY",
+}
+
+_ENV_VARS = PROVIDER_ENV_VARS
+
+
+def save_key(provider_id: str, api_key: str) -> None:
+    """Persist *api_key* for *provider_id* in the OS keyring."""
+    keyring.set_password(_SERVICE.format(provider_id), _USERNAME, api_key)
+
+
+def get_key(provider_id: str) -> str | None:
+    """Return the API key for *provider_id*.
+
+    Lookup order:
+    1. OS keyring (``velune/{provider_id}`` / ``api_key``)
+    2. Environment variable mapped in ``_ENV_VARS``
+    3. ``None``
+    """
+    try:
+        key = keyring.get_password(_SERVICE.format(provider_id), _USERNAME)
+        if key:
+            return key
+    except Exception:
+        pass
+
+    env_var = _ENV_VARS.get(provider_id)
+    if env_var:
+        return os.getenv(env_var) or None
+
+    return None
+
+
+def delete_key(provider_id: str) -> None:
+    """Remove the stored key for *provider_id* from the OS keyring."""
+    try:
+        keyring.delete_password(_SERVICE.format(provider_id), _USERNAME)
+    except keyring.errors.PasswordDeleteError:
+        pass
+
+
+def has_key(provider_id: str) -> bool:
+    """Return True if a key is available for *provider_id*."""
+    return get_key(provider_id) is not None
+
+
+def list_configured_providers() -> list[str]:
+    """Return provider IDs that have a key in the keyring or environment.
+
+    Ollama is local and keyless — it counts as configured when its server
+    is reachable, not when a key is present.
+    """
+    configured = [pid for pid in _ENV_VARS if has_key(pid)]
+    # Ollama is local — check if it's running, not if it has a key.
+    try:
+        import httpx
+        r = httpx.get("http://localhost:11434/api/tags", timeout=2.0)
+        if r.status_code == 200 and "ollama" not in configured:
+            configured.insert(0, "ollama")
+    except Exception:
+        pass
+    return configured

velune/providers/local_paths.py

@@ -0,0 +1,49 @@
+"""Persistent JSON cache that maps model_id strings to resolved GGUF file paths."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def _cache_path() -> Path:
+    project = Path.cwd() / ".velune"
+    if project.exists():
+        return project / "model_paths.json"
+    home = Path.home() / ".velune"
+    home.mkdir(parents=True, exist_ok=True)
+    return home / "model_paths.json"
+
+
+def _load() -> dict[str, str]:
+    path = _cache_path()
+    if path.exists():
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return {}
+
+
+def _save(data: dict[str, str]) -> None:
+    try:
+        _cache_path().write_text(json.dumps(data, indent=2), encoding="utf-8")
+    except Exception:
+        pass
+
+
+def save_model_path(model_id: str, path: Path) -> None:
+    """Persist the resolved *path* for *model_id* in the cache."""
+    data = _load()
+    data[model_id] = str(path)
+    _save(data)
+
+
+def get_model_path(model_id: str) -> Path | None:
+    """Return the cached path for *model_id*, or None if missing/stale."""
+    val = _load().get(model_id)
+    if val:
+        p = Path(val)
+        if p.exists():
+            return p
+    return None