loomcast 0.1.0__tar.gz

loomcast-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Loomcast Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loomcast-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: loomcast
+Version: 0.1.0
+Summary: Python SDK and CLI for seamlessly managing local LLM runtimes (Ollama, LM Studio, llama.cpp)
+Author: Loomcast Contributors
+License: MIT
+Keywords: llm,ollama,lmstudio,llamacpp,ai,sdk,cli,local-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
+Requires-Dist: typing-extensions>=4.5.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# Loomcast
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/<owner>/<repo>/ci.yml?branch=main&label=CI)](https://github.com/<owner>/<repo>/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
+
+Python SDK and CLI for seamlessly managing local LLM runtimes (**Ollama**, **LM Studio**, and **llama.cpp**).
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Check status of local runtimes
+loomcast status
+
+# List installed models
+loomcast list
+
+# Search catalog for models
+loomcast search code
+
+# Recommend models for a specific task or tag
+loomcast recommend coding
+
+# Batch install all models in a category
+loomcast install-category code --backend ollama
+
+# Send a prompt to a model
+loomcast chat llama3 "Hello world!" --backend ollama
+
+# Verify installed model integrity
+loomcast verify llama3 --backend ollama
+```
+
+### Python SDK Usage
+
+```python
+import loomcast
+
+# Initialize manager
+manager = loomcast.LoomcastManager()
+
+# Search catalog
+results = loomcast.search("code")
+for model in results:
+    print(model.name, model.description)
+
+# Recommend models for a task
+recs = loomcast.recommend("coding")
+
+# Batch install category
+installed, failed = loomcast.install_category("code", runtime_type="ollama")
+
+# Send chat messages
+response = loomcast.chat("llama3", [{"role": "user", "content": "Hello!"}], runtime_type="ollama")
+print(response)
+
+# Verify model integrity
+verification = loomcast.verify("llama3", runtime_type="ollama")
+print(f"Verified: {verification.verified}, Digest: {verification.digest}")
+```
+
+## Documentation
+
+Detailed documentation guides are available in the [`docs/`](docs/) directory:
+
+- [Prise en main (Getting Started)](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Runtimes Supportés](docs/runtimes.md)
+- [Extension & Architecture](docs/extending.md)
+- [Référence CLI](docs/cli-reference.md)
+

loomcast-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Loomcast
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/<owner>/<repo>/ci.yml?branch=main&label=CI)](https://github.com/<owner>/<repo>/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org)
+
+Python SDK and CLI for seamlessly managing local LLM runtimes (**Ollama**, **LM Studio**, and **llama.cpp**).
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Check status of local runtimes
+loomcast status
+
+# List installed models
+loomcast list
+
+# Search catalog for models
+loomcast search code
+
+# Recommend models for a specific task or tag
+loomcast recommend coding
+
+# Batch install all models in a category
+loomcast install-category code --backend ollama
+
+# Send a prompt to a model
+loomcast chat llama3 "Hello world!" --backend ollama
+
+# Verify installed model integrity
+loomcast verify llama3 --backend ollama
+```
+
+### Python SDK Usage
+
+```python
+import loomcast
+
+# Initialize manager
+manager = loomcast.LoomcastManager()
+
+# Search catalog
+results = loomcast.search("code")
+for model in results:
+    print(model.name, model.description)
+
+# Recommend models for a task
+recs = loomcast.recommend("coding")
+
+# Batch install category
+installed, failed = loomcast.install_category("code", runtime_type="ollama")
+
+# Send chat messages
+response = loomcast.chat("llama3", [{"role": "user", "content": "Hello!"}], runtime_type="ollama")
+print(response)
+
+# Verify model integrity
+verification = loomcast.verify("llama3", runtime_type="ollama")
+print(f"Verified: {verification.verified}, Digest: {verification.digest}")
+```
+
+## Documentation
+
+Detailed documentation guides are available in the [`docs/`](docs/) directory:
+
+- [Prise en main (Getting Started)](docs/getting-started.md)
+- [Configuration](docs/configuration.md)
+- [Runtimes Supportés](docs/runtimes.md)
+- [Extension & Architecture](docs/extending.md)
+- [Référence CLI](docs/cli-reference.md)
+

loomcast-0.1.0/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-0.1.0/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-0.1.0/loomcast/adapters/cache/__init__.py

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

loomcast-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/loomcast/adapters/downloader/__init__.py

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