loomcast 0.1.0__py3-none-any.whl

loomcast/__init__.py

@@ -0,0 +1,130 @@
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from loomcast.adapters.downloader.progress import (
+    NullProgressReporter,
+    ProgressReporter,
+    RichProgressReporter,
+)
+from loomcast.common.config import LoomcastConfig
+from loomcast.common.exceptions import (
+    CacheError,
+    ConfigurationError,
+    LoomcastError,
+    ModelNotFoundError,
+    RuntimeExecutionError,
+    RuntimeUnavailableError,
+)
+from loomcast.adapters.runtimes import LlamaCppRuntime
+from loomcast.core.manager import LoomcastManager
+from loomcast.domain.entities import CatalogEntry, ChatMessage, Model, RuntimeType, VerificationResult
+
+_default_manager: Optional[LoomcastManager] = None
+
+
+def get_manager(
+    config: Optional[LoomcastConfig] = None,
+    refresh: bool = False,
+) -> LoomcastManager:
+    """Get or create global default LoomcastManager instance."""
+    global _default_manager
+    if _default_manager is None or refresh:
+        _default_manager = LoomcastManager(config=config)
+    return _default_manager
+
+
+def search(query: str) -> List[CatalogEntry]:
+    """Search model catalog by query string."""
+    return get_manager().search(query)
+
+
+def recommend(task: str) -> List[CatalogEntry]:
+    """Recommend model catalog entries matching a task or tag."""
+    return get_manager().recommend(task)
+
+
+def install_category(
+    category: str,
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+    max_concurrent: int = 3,
+    progress: Optional[ProgressReporter] = None,
+) -> Tuple[List[str], List[str]]:
+    """Batch install all models in a category."""
+    reporter = progress if progress is not None else NullProgressReporter()
+    return get_manager().install_category(
+        category,
+        runtime_type=runtime_type,
+        max_concurrent=max_concurrent,
+        progress=reporter,
+    )
+
+
+def verify(
+    model: str,
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+) -> VerificationResult:
+    """Verify installed model integrity."""
+    return get_manager().verify(model, runtime_type=runtime_type)
+
+
+def chat(
+    model: str,
+    messages: List[Dict[str, Any]],
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+) -> str:
+    """Send chat messages to a local LLM model."""
+    return get_manager().chat(model, messages, runtime_type=runtime_type)
+
+
+def install(
+    model: str,
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+    progress: Optional[ProgressReporter] = None,
+) -> None:
+    """Install a model into the local runtime."""
+    reporter = progress if progress is not None else NullProgressReporter()
+    get_manager().install(model, runtime_type=runtime_type, progress=reporter)
+
+
+def list_installed(
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+) -> List[str]:
+    """List installed models in the local runtime."""
+    return get_manager().list_installed(runtime_type=runtime_type)
+
+
+def is_model_installed(
+    model: str,
+    runtime_type: Optional[Union[RuntimeType, str]] = None,
+) -> bool:
+    """Check if a model is installed in the local runtime."""
+    return get_manager().is_model_installed(model, runtime_type=runtime_type)
+
+
+__all__ = [
+    "LoomcastManager",
+    "get_manager",
+    "search",
+    "recommend",
+    "install_category",
+    "verify",
+    "chat",
+    "install",
+    "list_installed",
+    "is_model_installed",
+    "ProgressReporter",
+    "RichProgressReporter",
+    "NullProgressReporter",
+    "LlamaCppRuntime",
+    "LoomcastConfig",
+    "LoomcastError",
+    "RuntimeUnavailableError",
+    "ModelNotFoundError",
+    "ConfigurationError",
+    "RuntimeExecutionError",
+    "CacheError",
+    "RuntimeType",
+    "Model",
+    "CatalogEntry",
+    "ChatMessage",
+    "VerificationResult",
+]

loomcast/adapters/__init__.py

@@ -0,0 +1,13 @@
+from loomcast.adapters.cache.store import FileSystemCache
+from loomcast.adapters.catalog.dynamic import DynamicCatalog
+from loomcast.adapters.catalog.static import StaticCatalog
+from loomcast.adapters.runtimes.lmstudio import LMStudioRuntime
+from loomcast.adapters.runtimes.ollama import OllamaRuntime
+
+__all__ = [
+    "OllamaRuntime",
+    "LMStudioRuntime",
+    "FileSystemCache",
+    "StaticCatalog",
+    "DynamicCatalog",
+]

loomcast/adapters/cache/__init__.py

@@ -0,0 +1,3 @@
+from loomcast.adapters.cache.store import FileSystemCache
+
+__all__ = ["FileSystemCache"]

loomcast/adapters/cache/store.py

@@ -0,0 +1,56 @@
+import hashlib
+from pathlib import Path
+from typing import Optional, Union
+
+from loomcast.common.exceptions import CacheError
+from loomcast.common.paths import get_cache_dir
+from loomcast.ports.cache import CachePort
+
+
+class FileSystemCache(CachePort):
+    """File system implementation of CachePort."""
+
+    def __init__(self, cache_dir: Optional[Union[str, Path]] = None):
+        if cache_dir is None:
+            self.cache_dir = get_cache_dir()
+        else:
+            self.cache_dir = Path(cache_dir)
+
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            raise CacheError(f"Failed to create cache directory '{self.cache_dir}': {e}") from e
+
+    def _get_path(self, key: str) -> Path:
+        return self.cache_dir / key
+
+    def get(self, key: str) -> Optional[bytes]:
+        """Retrieve cached bytes by key, returning None if non-existent."""
+        path = self._get_path(key)
+        if not path.is_file():
+            return None
+        try:
+            return path.read_bytes()
+        except OSError as e:
+            raise CacheError(f"Failed to read cache entry '{key}': {e}") from e
+
+    def put(self, key: str, value: bytes) -> None:
+        """Store bytes into cache under key."""
+        path = self._get_path(key)
+        try:
+            path.write_bytes(value)
+        except OSError as e:
+            raise CacheError(f"Failed to write cache entry '{key}': {e}") from e
+
+    def exists(self, key: str) -> bool:
+        """Check if key exists in cache without reading contents."""
+        path = self._get_path(key)
+        try:
+            return path.is_file()
+        except OSError as e:
+            raise CacheError(f"Failed to check existence for cache entry '{key}': {e}") from e
+
+    @staticmethod
+    def compute_key(data: bytes) -> str:
+        """Compute hexadecimal SHA-256 hash of content."""
+        return hashlib.sha256(data).hexdigest()

loomcast/adapters/catalog/__init__.py

@@ -0,0 +1,4 @@
+from loomcast.adapters.catalog.dynamic import DynamicCatalog
+from loomcast.adapters.catalog.static import StaticCatalog
+
+__all__ = ["StaticCatalog", "DynamicCatalog"]

loomcast/adapters/catalog/dynamic.py

@@ -0,0 +1,154 @@
+import json
+import re
+import time
+from typing import List, Optional, Tuple
+
+import httpx
+
+from loomcast.adapters.cache.store import FileSystemCache
+from loomcast.adapters.catalog.static import StaticCatalog
+from loomcast.common.logging import logger
+from loomcast.domain.entities import CatalogEntry, RuntimeType
+from loomcast.ports.cache import CachePort
+from loomcast.ports.catalog import CatalogPort
+
+CACHE_SNAPSHOT_KEY = "catalog_dynamic_snapshot"
+
+
+def _parse_library_html(html: str) -> List[CatalogEntry]:
+    """Parse HTML from ollama.com/library into a list of CatalogEntry items."""
+    entries: List[CatalogEntry] = []
+    seen_names = set()
+
+    # Pattern matches <a href="/library/<model_name>">...</a>
+    card_pattern = re.compile(
+        r'<a\s+[^>]*href=["\']/library/([a-zA-Z0-9._-]+)["\'][^>]*>(.*?)</a>',
+        re.DOTALL | re.IGNORECASE,
+    )
+    desc_pattern = re.compile(r'<p[^>]*>(.*?)</p>', re.DOTALL | re.IGNORECASE)
+    tag_pattern = re.compile(r'<span[^>]*>(.*?)</span>', re.DOTALL | re.IGNORECASE)
+    strip_tags_pattern = re.compile(r'<[^>]+>')
+
+    for match in card_pattern.finditer(html):
+        name = match.group(1).lower()
+        if name in seen_names:
+            continue
+        seen_names.add(name)
+
+        card_content = match.group(2)
+
+        # Extract description from <p>
+        desc_match = desc_pattern.search(card_content)
+        description = None
+        if desc_match:
+            clean_desc = strip_tags_pattern.sub("", desc_match.group(1)).strip()
+            if clean_desc:
+                description = clean_desc
+
+        # Extract tags from <span>
+        tags = []
+        for t_match in tag_pattern.finditer(card_content):
+            clean_tag = strip_tags_pattern.sub("", t_match.group(1)).strip()
+            if clean_tag and len(clean_tag) < 30:
+                tags.append(clean_tag)
+
+        if not tags:
+            tags = ["ollama"]
+
+        entries.append(
+            CatalogEntry(
+                name=name,
+                description=description,
+                publisher="ollama",
+                tags=tags,
+                default_runtime=RuntimeType.OLLAMA,
+            )
+        )
+
+    return entries
+
+
+class DynamicCatalog(CatalogPort):
+    """Dynamic CatalogPort implementation with TTL caching and static fallback."""
+
+    def __init__(
+        self,
+        cache: Optional[CachePort] = None,
+        fallback_catalog: Optional[CatalogPort] = None,
+        ttl_hours: int = 24,
+    ):
+        self.cache: CachePort = cache if cache is not None else FileSystemCache()
+        self.fallback_catalog: CatalogPort = (
+            fallback_catalog if fallback_catalog is not None else StaticCatalog()
+        )
+        self.ttl_hours = ttl_hours
+
+    def _get_entries(self) -> Tuple[Optional[List[CatalogEntry]], bool]:
+        """Fetch entries from cache or network, or indicate fallback required."""
+        # 1. Try cache
+        raw_cache = self.cache.get(CACHE_SNAPSHOT_KEY)
+        if raw_cache:
+            try:
+                data = json.loads(raw_cache.decode("utf-8"))
+                timestamp = data.get("timestamp", 0)
+                if (time.time() - timestamp) < (self.ttl_hours * 3600):
+                    entries_data = data.get("entries", [])
+                    entries = [CatalogEntry.model_validate(item) for item in entries_data]
+                    if entries:
+                        return entries, False
+            except Exception as e:
+                logger.warning(f"Failed to read dynamic catalog cache snapshot: {e}")
+
+        # 2. Try scraping Ollama library
+        try:
+            response = httpx.get("https://ollama.com/library", timeout=10.0)
+            if response.status_code != 200:
+                raise ValueError(f"HTTP error status code {response.status_code}")
+            entries = _parse_library_html(response.text)
+
+            if not entries:
+                raise ValueError("No catalog entries parsed from HTML response")
+
+            # Save snapshot to cache
+            cache_payload = {
+                "timestamp": time.time(),
+                "entries": [e.model_dump() for e in entries],
+            }
+            self.cache.put(CACHE_SNAPSHOT_KEY, json.dumps(cache_payload).encode("utf-8"))
+            return entries, False
+        except Exception as e:
+            logger.warning(
+                f"Failed to fetch dynamic catalog from Ollama library ({e}). "
+                "Falling back to static catalog."
+            )
+            return None, True
+
+    def search(self, query: str) -> List[CatalogEntry]:
+        """Search catalog for entries matching query, falling back to static catalog if needed."""
+        entries, is_fallback = self._get_entries()
+        if is_fallback or entries is None:
+            return self.fallback_catalog.search(query)
+
+        query_lower = query.lower()
+        results: List[CatalogEntry] = []
+        for entry in entries:
+            name_match = query_lower in entry.name.lower()
+            desc_match = bool(entry.description and query_lower in entry.description.lower())
+            tag_match = any(query_lower in tag.lower() for tag in entry.tags)
+
+            if name_match or desc_match or tag_match:
+                results.append(entry)
+
+        return results
+
+    def get_entry(self, name: str) -> Optional[CatalogEntry]:
+        """Retrieve catalog entry by name, falling back to static catalog if needed."""
+        entries, is_fallback = self._get_entries()
+        if is_fallback or entries is None:
+            return self.fallback_catalog.get_entry(name)
+
+        name_lower = name.lower()
+        for entry in entries:
+            if entry.name.lower() == name_lower:
+                return entry
+        return None

loomcast/adapters/catalog/static.py

@@ -0,0 +1,68 @@
+import json
+from pathlib import Path
+from typing import List, Optional, Union
+from pydantic import ValidationError
+
+from loomcast.common.exceptions import LoomcastError
+from loomcast.domain.entities import CatalogEntry
+from loomcast.ports.catalog import CatalogPort
+
+
+class StaticCatalog(CatalogPort):
+    """CatalogPort implementation loading entries from an embedded JSON file."""
+
+    def __init__(self, catalog_path: Optional[Union[str, Path]] = None):
+        if catalog_path is None:
+            self.catalog_path = Path(__file__).parent / "data" / "catalog.json"
+        else:
+            self.catalog_path = Path(catalog_path)
+
+        self._entries: List[CatalogEntry] = self._load_catalog()
+
+    def _load_catalog(self) -> List[CatalogEntry]:
+        if not self.catalog_path.is_file():
+            raise LoomcastError(f"Catalog file not found at '{self.catalog_path}'.")
+
+        try:
+            with open(self.catalog_path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except Exception as e:
+            raise LoomcastError(f"Failed to read catalog JSON file '{self.catalog_path}': {e}") from e
+
+        if not isinstance(data, list):
+            raise LoomcastError(f"Catalog JSON file '{self.catalog_path}' must contain a list of entries.")
+
+        entries: List[CatalogEntry] = []
+        for idx, item in enumerate(data):
+            try:
+                entry = CatalogEntry.model_validate(item)
+                entries.append(entry)
+            except ValidationError as ve:
+                raise LoomcastError(
+                    f"Invalid CatalogEntry format at index {idx} in '{self.catalog_path}': {ve}"
+                ) from ve
+
+        return entries
+
+    def search(self, query: str) -> List[CatalogEntry]:
+        """Search catalog entries matching query in name, description, or tags (case-insensitive)."""
+        query_lower = query.lower()
+        results: List[CatalogEntry] = []
+
+        for entry in self._entries:
+            name_match = query_lower in entry.name.lower()
+            desc_match = bool(entry.description and query_lower in entry.description.lower())
+            tag_match = any(query_lower in tag.lower() for tag in entry.tags)
+
+            if name_match or desc_match or tag_match:
+                results.append(entry)
+
+        return results
+
+    def get_entry(self, name: str) -> Optional[CatalogEntry]:
+        """Retrieve exact catalog entry by name (case-insensitive comparison)."""
+        name_lower = name.lower()
+        for entry in self._entries:
+            if entry.name.lower() == name_lower:
+                return entry
+        return None

loomcast/adapters/downloader/__init__.py

@@ -0,0 +1,13 @@
+from loomcast.adapters.downloader.progress import (
+    NullProgressReporter,
+    ProgressReporter,
+    RichProgressReporter,
+    SubProgressReporter,
+)
+
+__all__ = [
+    "ProgressReporter",
+    "RichProgressReporter",
+    "NullProgressReporter",
+    "SubProgressReporter",
+]

loomcast/adapters/downloader/progress.py

@@ -0,0 +1,112 @@
+from typing import Any, Dict, Optional
+from rich.console import Console
+from rich.progress import BarColumn, DownloadColumn, Progress, TaskID, TextColumn, TransferSpeedColumn
+
+
+class ProgressReporter:
+    """Base callback object for model download progress tracking."""
+
+    def on_progress(self, status: str, completed: Optional[int] = None, total: Optional[int] = None) -> None:
+        """Receive a progress update callback.
+
+        Args:
+            status: Status description text (e.g. 'downloading sha256:...', 'verifying').
+            completed: Total bytes completed so far, if available.
+            total: Total expected bytes, if available.
+        """
+        pass
+
+    def create_sub_reporter(self, prefix: str) -> "ProgressReporter":
+        """Create a child progress reporter for concurrent task isolation."""
+        return self
+
+
+class NullProgressReporter(ProgressReporter):
+    """Silent progress reporter that ignores all progress events."""
+
+    def on_progress(self, status: str, completed: Optional[int] = None, total: Optional[int] = None) -> None:
+        pass
+
+
+class SubProgressReporter(ProgressReporter):
+    """Child progress reporter bound to a dedicated task in a parent RichProgressReporter."""
+
+    def __init__(self, parent: "RichProgressReporter", prefix: str):
+        self.parent = parent
+        self.prefix = prefix
+        self._task_id: Optional[TaskID] = None
+
+    def on_progress(self, status: str, completed: Optional[int] = None, total: Optional[int] = None) -> None:
+        self.parent.start()
+        desc = f"[{self.prefix}] {status}" if self.prefix else status
+        if self._task_id is None:
+            self._task_id = self.parent._progress.add_task(
+                description=desc,
+                total=total,
+                completed=completed or 0,
+            )
+        else:
+            kwargs: Dict[str, Any] = {"description": desc}
+            if total is not None:
+                kwargs["total"] = total
+            if completed is not None:
+                kwargs["completed"] = completed
+            self.parent._progress.update(self._task_id, **kwargs)
+
+
+class RichProgressReporter(ProgressReporter):
+    """Terminal visual progress reporter powered by rich.progress."""
+
+    def __init__(self, console: Optional[Console] = None):
+        self.console = console
+        self._progress: Optional[Progress] = None
+        self._task_id: Optional[TaskID] = None
+
+    def start(self) -> None:
+        """Start the Rich Progress display if not already running."""
+        if self._progress is None:
+            self._progress = Progress(
+                TextColumn("[progress.description]{task.description}"),
+                BarColumn(),
+                DownloadColumn(),
+                TransferSpeedColumn(),
+                console=self.console,
+            )
+            self._progress.start()
+
+    def stop(self) -> None:
+        """Stop and clean up the Rich Progress display."""
+        if self._progress is not None:
+            self._progress.stop()
+            self._progress = None
+            self._task_id = None
+
+    def create_sub_reporter(self, prefix: str) -> ProgressReporter:
+        """Create a child progress reporter dedicated to a specific task prefix."""
+        return SubProgressReporter(self, prefix=prefix)
+
+    def __enter__(self) -> "RichProgressReporter":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.stop()
+
+    def on_progress(self, status: str, completed: Optional[int] = None, total: Optional[int] = None) -> None:
+        """Update progress bar display with status and byte metrics."""
+        if self._progress is None:
+            self.start()
+
+        if self._task_id is None:
+            self._task_id = self._progress.add_task(
+                description=status,
+                total=total,
+                completed=completed or 0,
+            )
+        else:
+            kwargs: Dict[str, Any] = {"description": status}
+            if total is not None:
+                kwargs["total"] = total
+            if completed is not None:
+                kwargs["completed"] = completed
+            self._progress.update(self._task_id, **kwargs)

loomcast/adapters/runtimes/__init__.py

@@ -0,0 +1,9 @@
+from loomcast.adapters.runtimes.llamacpp import LlamaCppRuntime
+from loomcast.adapters.runtimes.lmstudio import LMStudioRuntime
+from loomcast.adapters.runtimes.ollama import OllamaRuntime
+
+__all__ = [
+    "OllamaRuntime",
+    "LMStudioRuntime",
+    "LlamaCppRuntime",
+]

loomcast/adapters/runtimes/_openai_compat.py

@@ -0,0 +1,33 @@
+from typing import Any, Dict, List
+import httpx
+
+from loomcast.common.exceptions import RuntimeExecutionError
+
+
+def send_openai_compat_chat(
+    base_url: str,
+    model: str,
+    messages: List[Dict[str, Any]],
+    timeout: float,
+    runtime_name: str = "OpenAI-compatible",
+) -> str:
+    """Send a chat completion request to an OpenAI-compatible /v1/chat/completions endpoint."""
+    try:
+        payload = {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+        }
+        response = httpx.post(
+            f"{base_url.rstrip('/')}/v1/chat/completions",
+            json=payload,
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        data = response.json()
+        choices = data.get("choices", [])
+        if not choices:
+            raise RuntimeExecutionError(f"Empty choices returned from {runtime_name} chat API.")
+        return choices[0].get("message", {}).get("content", "")
+    except httpx.HTTPError as e:
+        raise RuntimeExecutionError(f"{runtime_name} chat execution failed for model '{model}': {e}") from e

loomcast/adapters/runtimes/llamacpp.py

@@ -0,0 +1,73 @@
+from typing import Any, Dict, List, Optional
+import httpx
+
+from loomcast.adapters.downloader.progress import ProgressReporter
+from loomcast.adapters.runtimes._openai_compat import send_openai_compat_chat
+from loomcast.common.exceptions import RuntimeExecutionError, RuntimeUnavailableError
+from loomcast.ports.runtime import RuntimePort
+
+
+class LlamaCppRuntime(RuntimePort):
+    """Adapter for local llama.cpp server (llama-server) running on port 8080 (default)."""
+
+    def __init__(self, base_url: str = "http://localhost:8080", timeout: float = 30.0):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def is_available(self) -> bool:
+        """Check if llama-server is running via GET /health."""
+        try:
+            response = httpx.get(f"{self.base_url}/health", timeout=2.0)
+            return response.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    def list_installed(self) -> List[str]:
+        """List model currently loaded in llama-server.
+
+        Note:
+            llama-server typically serves a single model specified at server launch.
+            This queries GET /v1/models to retrieve the active model identifier.
+        """
+        if not self.is_available():
+            raise RuntimeUnavailableError("llamacpp", self.base_url)
+        try:
+            response = httpx.get(f"{self.base_url}/v1/models", timeout=self.timeout)
+            response.raise_for_status()
+            data = response.json()
+            models = data.get("data", [])
+            return [m["id"] for m in models if "id" in m]
+        except httpx.HTTPError as e:
+            raise RuntimeExecutionError(f"Failed to list llama.cpp models: {e}") from e
+
+    def is_model_installed(self, model: str) -> bool:
+        """Check if a model is currently loaded in llama-server."""
+        installed = self.list_installed()
+        return model in installed
+
+    def install(self, model: str, progress: Optional[ProgressReporter] = None) -> None:
+        """llama.cpp model installation directive.
+
+        Note:
+            llama.cpp does not support remote model downloading via HTTP API.
+            Models must be loaded by launching llama-server with command-line flags.
+        """
+        if not self.is_available():
+            raise RuntimeUnavailableError("llamacpp", self.base_url)
+        if not self.is_model_installed(model):
+            raise RuntimeExecutionError(
+                f"Model '{model}' is not currently loaded in llama.cpp. "
+                "Please launch llama-server with your desired model specified via command-line flags."
+            )
+
+    def chat(self, model: str, messages: List[Dict[str, Any]]) -> str:
+        """Send chat completion request to llama-server OpenAI-compatible endpoint."""
+        if not self.is_available():
+            raise RuntimeUnavailableError("llamacpp", self.base_url)
+        return send_openai_compat_chat(
+            base_url=self.base_url,
+            model=model,
+            messages=messages,
+            timeout=self.timeout,
+            runtime_name="llama.cpp",
+        )