hestia-system 0.1.0__tar.gz

hestia_system-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include project.ini
+include README.md

hestia_system-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: hestia-system
+Version: 0.1.0
+Summary: System discovery, hardware and software analysis, and AI model recommendations.
+Author: Damon S. Green II (nomadiidamon)
+License: MIT
+Project-URL: Homepage, https://github.com/nomadiidamon/Hestia
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: nvidia
+Requires-Dist: nvidia-ml-py>=12.0.0; extra == "nvidia"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# Hestia for Python
+
+Hestia provides system discovery and AI model intelligence. The Python package
+currently exposes accelerator and model-size types, a model catalog, and model
+information lookup.
+
+The distribution is named `hestia-system`; import it as `Hestia`.
+
+## Installation
+
+```bash
+python -m pip install hestia-system
+```
+
+Optional dependencies are available as extras:
+
+```bash
+python -m pip install "hestia-system[nvidia]"  # NVIDIA telemetry support
+python -m pip install "hestia-system[dev]"     # pytest
+```
+
+## Usage
+
+```python
+from Hestia import AcceleratorType, ModelSize, get_model_info
+
+info = get_model_info(AcceleratorType.NVIDIA_CUDA, ModelSize.SMALL)
+print(info)
+```
+
+The package supports Python versions declared by the project metadata (Python
+3.10 and later).
+
+## Development
+
+From the repository checkout:
+
+```bash
+cd python
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Package metadata is maintained in the repository's `project.ini`. Source
+distributions include a copy of that file so they can be built independently
+of the repository checkout.

hestia_system-0.1.0/README.md

@@ -0,0 +1,46 @@
+# Hestia for Python
+
+Hestia provides system discovery and AI model intelligence. The Python package
+currently exposes accelerator and model-size types, a model catalog, and model
+information lookup.
+
+The distribution is named `hestia-system`; import it as `Hestia`.
+
+## Installation
+
+```bash
+python -m pip install hestia-system
+```
+
+Optional dependencies are available as extras:
+
+```bash
+python -m pip install "hestia-system[nvidia]"  # NVIDIA telemetry support
+python -m pip install "hestia-system[dev]"     # pytest
+```
+
+## Usage
+
+```python
+from Hestia import AcceleratorType, ModelSize, get_model_info
+
+info = get_model_info(AcceleratorType.NVIDIA_CUDA, ModelSize.SMALL)
+print(info)
+```
+
+The package supports Python versions declared by the project metadata (Python
+3.10 and later).
+
+## Development
+
+From the repository checkout:
+
+```bash
+cd python
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Package metadata is maintained in the repository's `project.ini`. Source
+distributions include a copy of that file so they can be built independently
+of the repository checkout.

hestia_system-0.1.0/project.ini

@@ -0,0 +1,32 @@
+; project.ini
+;
+; Single source of truth for metadata shared across the C++ and Python
+; implementations. Both build systems (premake5 on the C++ side, the Python
+; packaging/build scripts on the Python side) should parse this file rather
+; than duplicating these values in language-specific manifests.
+;
+; Keep keys flat and simple (INI has no native nesting) so both a C++ INI
+; parser and Python's configparser can read it without custom logic.
+
+[project]
+name = Hestia
+python_package = hestia-system
+version = 0.1.0
+description = "System discovery, hardware and software analysis, and AI model recommendations."
+homepage = https://github.com/nomadiidamon/Hestia
+license = MIT
+
+[contributors]
+; Comma-separated list; expand as needed, or switch to one key per person
+; (e.g. contributor.1, contributor.2) if you want per-person metadata later.
+maintainers = Damon S. Green II (nomadiidamon)
+contributors =
+
+[compatibility]
+; Minimum/target language versions both implementations should track.
+cpp_standard = c++17
+python_requires = >=3.10
+
+[build]
+; Freeform notes/flags both build scripts may want to agree on.
+default_build_type = release

hestia_system-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hestia-system"
+dynamic = ["version", "description", "readme", "license", "authors", "requires-python", "urls"]  # from ../project.ini via setup.py
+
+dependencies = [
+    "psutil>=5.9.0",
+]
+
+[project.optional-dependencies]
+nvidia = [
+    "nvidia-ml-py>=12.0.0",
+]
+dev = [
+    "pytest>=7.0",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

hestia_system-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hestia_system-0.1.0/setup.py

@@ -0,0 +1,39 @@
+"""Reads shared metadata from ../project.ini (the single source of truth)."""
+import configparser
+import re
+import shutil
+from pathlib import Path
+
+from setuptools import setup
+
+HERE = Path(__file__).resolve().parent
+REPO_INI = HERE.parent / "project.ini"
+LOCAL_INI = HERE / "project.ini"
+
+# An sdist has no parent repo, so ship a copy of project.ini alongside setup.py.
+if REPO_INI.is_file():
+    shutil.copyfile(REPO_INI, LOCAL_INI)
+if not LOCAL_INI.is_file():
+    raise FileNotFoundError(f"project.ini not found at {REPO_INI} or {LOCAL_INI}")
+
+cfg = configparser.ConfigParser()
+with open(LOCAL_INI, encoding="utf-8-sig") as ini:
+    cfg.read_file(ini)
+project = cfg["project"]
+
+people = [p.strip() for p in cfg["contributors"]["maintainers"].split(",") if p.strip()]
+# "Name (handle) <email>" -> "Name (handle)"
+names = [re.sub(r"\s*<.*>$", "", p) for p in people]
+emails = [m.group(1) for p in people if (m := re.search(r"<(.*)>$", p))]
+
+setup(
+    version=project["version"],
+    description=project["description"].strip('"'),
+    long_description=(HERE / "README.md").read_text(encoding="utf-8"),
+    long_description_content_type="text/markdown",
+    license=project["license"],
+    python_requires=cfg["compatibility"]["python_requires"],
+    author=", ".join(names),
+    author_email=", ".join(emails) or None,
+    project_urls={"Homepage": project["homepage"]},
+)

hestia_system-0.1.0/src/Hestia/__init__.py

@@ -0,0 +1,10 @@
+"""Hestia - system discovery and AI model intelligence."""
+
+from .models import ModelInfo, get_model_info
+from .types import AcceleratorType, ModelSize
+
+
+__version__ = "0.1.0"
+
+
+__all__ = ["AcceleratorType", "ModelSize", "ModelInfo", "get_model_info"]

hestia_system-0.1.0/src/Hestia/model_catalog.py

@@ -0,0 +1,11 @@
+"""Legacy import path; use Hestia.models instead."""
+
+from .models.catalog import (
+    KNOWN_CATEGORIES,
+    MODEL_DATABASE,
+    TIER_FALLBACK_ORDER,
+    TierEntry,
+    TierMap,
+    get_category,
+    get_tier,
+)

hestia_system-0.1.0/src/Hestia/models/__init__.py

@@ -0,0 +1,24 @@
+"""AI model catalog and metadata."""
+
+from .catalog import (
+    KNOWN_CATEGORIES,
+    MODEL_DATABASE,
+    TIER_FALLBACK_ORDER,
+    TierEntry,
+    TierMap,
+    get_category,
+    get_tier,
+)
+from .info import ModelInfo, get_model_info
+
+__all__ = [
+    "KNOWN_CATEGORIES",
+    "MODEL_DATABASE",
+    "TIER_FALLBACK_ORDER",
+    "TierEntry",
+    "TierMap",
+    "ModelInfo",
+    "get_category",
+    "get_model_info",
+    "get_tier",
+]

hestia_system-0.1.0/src/Hestia/models/catalog.py

@@ -0,0 +1,438 @@
+# ---------------------------------------------------------------------------
+# To add new categories
+# ---------------------------------------------------------------------------
+# 1.) Add the new category key to KNOWN_CATEGORIES
+    # KNOWN_CATEGORIES = [ '...' , '...' , 'coding']
+
+# 2.) Add the new category key to each tier entry that supports it in MODEL_DATABASE
+    # 'coding': ['qwen2.5-coder:7b']
+
+# 3.) Add the field to ModelInfo in models/info.py and the ModelRecommendation dataclass
+    # coding_models: List[str]
+
+# 4.) Add to ModelRecommender.recommend() in hardware.py
+    # coding_models=get_category(tier, 'coding_models'),
+
+# 5.) Add to print_hardware_report() in hardware.py
+    # if recommendation.coding_models:
+        #print(f"Coding:       {', '.join(recommendation.coding_models)}")
+
+
+"""
+model_catalog.py - Model recommendation database for Local AI Runtime.
+
+Defines what models are appropriate per hardware tier, accelerator type,
+and capability category. Add new categories here without touching hardware.py.
+
+Category keys per tier entry:
+  models   - best general-purpose models for balanced use
+  thinking - chain-of-thought / extended reasoning (/think mode)
+  tools    - native function/tool-call support
+  vision   - multimodal image + text understanding
+  quantization - recommended quantization level for this tier
+  batch_size   - safe concurrent request count
+  context      - practical max context window in tokens
+  performance  - human-readable speed description
+
+@todo: Abstract the model recommendation logic to allow dynamic updates and easier maintenance.
+@todo: Create a class to hold a model, size, and category for easier management and retrieval.
+"""
+
+from typing import Dict, List
+from ..types import AcceleratorType, ModelSize
+
+
+# ---------------------------------------------------------------------------
+# Type alias for a single tier entry
+# ---------------------------------------------------------------------------
+TierEntry = Dict[str, object]
+TierMap   = Dict[ModelSize, TierEntry]
+
+
+# ---------------------------------------------------------------------------
+# MODEL DATABASE
+# Outer key: AcceleratorType
+# Inner key: ModelSize (memory tier)
+# ---------------------------------------------------------------------------
+
+MODEL_DATABASE: Dict[AcceleratorType, TierMap] = {
+
+    # ==========================================================================
+    # NVIDIA CUDA
+    # Fast VRAM access - highest quality quant per tier
+    # ==========================================================================
+    AcceleratorType.NVIDIA_CUDA: {
+
+        ModelSize.TINY: {
+            # <2 GB - ultra-constrained, phone/edge-class VRAM
+            'models':      ['qwen3:0.6b', 'llama3.2:1b', 'deepseek-r1:1.5b', 'smollm2:1.7b'],
+            'thinking':    ['deepseek-r1:1.5b', 'qwen3:0.6b'],
+            'tools':       ['qwen3:0.6b', 'llama3.2:1b', 'smollm2:1.7b'],
+            'vision':      [],  # No reliable sub-2 GB vision models on Ollama
+            'quantization': 'q8_0',
+            'batch_size':   4,
+            'context':      8192,
+            'performance':  'Fast (tiny model)',
+        },
+
+        ModelSize.SMALL: {
+            # 2-4 GB - entry-level discrete GPU or shared VRAM laptop
+            'models':      ['qwen3:1.7b', 'llama3.2:3b', 'phi4-mini:3.8b', 'granite3.3:2b'],
+            'thinking':    ['qwen3:1.7b', 'deepseek-r1:1.5b'],
+            'tools':       ['qwen3:1.7b', 'llama3.2:3b', 'granite3.1-dense:2b', 'xlam:1b'],
+            'vision':      ['llama3.2-vision:3b', 'moondream:1.8b', 'minicpm-v:3b'],
+            'quantization': 'q6_k',
+            'batch_size':   4,
+            'context':      16384,
+            'performance':  'Fast',
+        },
+
+        ModelSize.MEDIUM: {
+            # 4-12 GB - GTX 1080 / RTX 3060 / RX 6700 XT class
+            'models':      ['qwen3:8b', 'llama3.1:8b', 'mistral:7b', 'mistral-nemo:12b', 'qwen2.5:7b'],
+            'thinking':    ['qwen3:8b', 'deepseek-r1:8b', 'cogito:8b', 'exaone-deep:7.8b'],
+            'tools':       ['qwen3:8b', 'llama3.1:8b', 'qwen2.5:7b', 'hermes3:8b',
+                            'mistral:7b', 'xlam:8b', 'functionary:7b', 'granite3.1-dense:8b'],
+            'vision':      ['llava:7b', 'llava:13b', 'llama3.2-vision:11b', 'qwen2.5vl:7b',
+                            'minicpm-v:8b', 'moondream:1.8b', 'bakllava:7b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   2,
+            'context':      32768,
+            'performance':  'Fast',
+        },
+
+        ModelSize.LARGE: {
+            # 12-40 GB - RTX 3090 / RTX 4090 / A100 40 GB class
+            'models':      ['qwen3:14b', 'qwen3:32b', 'qwen2.5:32b',
+                            'deepseek-r1:14b', 'command-r:35b'],
+            'thinking':    ['qwen3:14b', 'qwen3:32b', 'deepseek-r1:14b', 'deepseek-r1:32b',
+                            'qwq:32b', 'cogito:14b', 'cogito:32b',
+                            'phi4-reasoning:14b', 'exaone-deep:32b'],
+            'tools':       ['qwen3:14b', 'qwen3:32b', 'command-r:35b', 'qwen2.5:32b',
+                            'hermes3:8b', 'aya-expanse:32b', 'functionary:7b', 'xlam:7b'],
+            'vision':      ['llava:34b', 'qwen2.5vl:14b', 'qwen2.5vl:32b',
+                            'llama3.2-vision:11b', 'minicpm-v:8b', 'gemma3:27b',
+                            'mistral-small3.1:22b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   2,
+            'context':      32768,
+            'performance':  'Moderate',
+        },
+
+        ModelSize.XLARGE: {
+            # 40+ GB - A100 80 GB / H100 / multi-GPU NVLink
+            'models':      ['llama3.3:70b', 'qwen2.5:72b', 'qwen3:30b-a3b',
+                            'deepseek-r1:70b', 'command-r-plus:104b'],
+            'thinking':    ['deepseek-r1:70b', 'qwen3:30b-a3b', 'cogito:70b',
+                            'qwq:32b', 'exaone-deep:32b'],
+            'tools':       ['llama3.3:70b', 'qwen2.5:72b', 'qwen3:30b-a3b',
+                            'hermes3:70b', 'command-r-plus:104b',
+                            'firefunction-v2:70b', 'functionary:70b'],
+            'vision':      ['llava:34b', 'qwen2.5vl:72b', 'llama3.2-vision:90b',
+                            'mistral-small3.1:22b', 'gemma3:27b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   4,
+            'context':      131072,
+            'performance':  'Fast (large model)',
+        },
+    },
+
+    # ==========================================================================
+    # AMD ROCm
+    # Slightly less efficient memory bandwidth than CUDA; drop quant one step
+    # ==========================================================================
+    AcceleratorType.AMD_ROCM: {
+
+        ModelSize.TINY: {
+            'models':      ['qwen3:0.6b', 'llama3.2:1b', 'deepseek-r1:1.5b'],
+            'thinking':    ['deepseek-r1:1.5b', 'qwen3:0.6b'],
+            'tools':       ['qwen3:0.6b', 'llama3.2:1b'],
+            'vision':      [],
+            'quantization': 'q8_0',
+            'batch_size':   2,
+            'context':      8192,
+            'performance':  'Moderate (tiny model)',
+        },
+
+        ModelSize.SMALL: {
+            'models':      ['qwen3:1.7b', 'llama3.2:3b', 'phi4-mini:3.8b'],
+            'thinking':    ['qwen3:1.7b', 'deepseek-r1:1.5b'],
+            'tools':       ['qwen3:1.7b', 'llama3.2:3b', 'xlam:1b'],
+            'vision':      ['llama3.2-vision:3b', 'moondream:1.8b', 'minicpm-v:3b'],
+            'quantization': 'q5_k_m',
+            'batch_size':   2,
+            'context':      16384,
+            'performance':  'Moderate',
+        },
+
+        ModelSize.MEDIUM: {
+            'models':      ['qwen3:8b', 'llama3.1:8b', 'mistral:7b', 'qwen2.5:7b'],
+            'thinking':    ['qwen3:8b', 'deepseek-r1:8b', 'cogito:8b'],
+            'tools':       ['qwen3:8b', 'llama3.1:8b', 'qwen2.5:7b',
+                            'hermes3:8b', 'mistral:7b', 'granite3.1-dense:8b'],
+            'vision':      ['llava:7b', 'llama3.2-vision:11b', 'qwen2.5vl:7b',
+                            'minicpm-v:8b', 'moondream:1.8b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   2,
+            'context':      32768,
+            'performance':  'Moderate',
+        },
+
+        ModelSize.LARGE: {
+            'models':      ['qwen3:14b', 'qwen3:32b', 'deepseek-r1:14b', 'command-r:35b'],
+            'thinking':    ['qwen3:14b', 'qwen3:32b', 'deepseek-r1:14b', 'deepseek-r1:32b',
+                            'qwq:32b', 'cogito:14b', 'phi4-reasoning:14b'],
+            'tools':       ['qwen3:14b', 'qwen3:32b', 'command-r:35b',
+                            'qwen2.5:32b', 'aya-expanse:32b'],
+            'vision':      ['qwen2.5vl:14b', 'qwen2.5vl:32b', 'llava:34b',
+                            'gemma3:27b', 'mistral-small3.1:22b'],
+            'quantization': 'q3_k_m',
+            'batch_size':   1,
+            'context':      32768,
+            'performance':  'Slow',
+        },
+
+        ModelSize.XLARGE: {
+            'models':      ['llama3.3:70b', 'qwen2.5:72b', 'deepseek-r1:70b'],
+            'thinking':    ['deepseek-r1:70b', 'qwen3:30b-a3b', 'cogito:70b'],
+            'tools':       ['llama3.3:70b', 'qwen2.5:72b', 'hermes3:70b',
+                            'firefunction-v2:70b'],
+            'vision':      ['qwen2.5vl:72b', 'llama3.2-vision:90b', 'llava:34b'],
+            'quantization': 'q3_k_m',
+            'batch_size':   2,
+            'context':      65536,
+            'performance':  'Moderate (large model)',
+        },
+    },
+
+    # ==========================================================================
+    # Intel Arc / Xe (OneAPI)
+    # Typically 8-16 GB on Arc A770/B580; lower throughput than NVIDIA/AMD
+    # ==========================================================================
+    AcceleratorType.INTEL_ONEAPI: {
+
+        ModelSize.TINY: {
+            'models':      ['qwen3:0.6b', 'llama3.2:1b', 'smollm2:1.7b'],
+            'thinking':    ['deepseek-r1:1.5b', 'qwen3:0.6b'],
+            'tools':       ['qwen3:0.6b', 'llama3.2:1b'],
+            'vision':      [],
+            'quantization': 'q8_0',
+            'batch_size':   2,
+            'context':      8192,
+            'performance':  'Moderate (tiny model)',
+        },
+
+        ModelSize.SMALL: {
+            'models':      ['qwen3:1.7b', 'llama3.2:3b', 'granite3.3:2b'],
+            'thinking':    ['qwen3:1.7b', 'deepseek-r1:1.5b'],
+            'tools':       ['qwen3:1.7b', 'llama3.2:3b', 'granite3.1-dense:2b'],
+            'vision':      ['moondream:1.8b', 'minicpm-v:3b'],
+            'quantization': 'q5_k_m',
+            'batch_size':   2,
+            'context':      8192,
+            'performance':  'Moderate',
+        },
+
+        ModelSize.MEDIUM: {
+            'models':      ['qwen3:8b', 'llama3.1:8b', 'mistral:7b'],
+            'thinking':    ['qwen3:8b', 'deepseek-r1:8b'],
+            'tools':       ['qwen3:8b', 'llama3.1:8b', 'mistral:7b',
+                            'granite3.1-dense:8b', 'hermes3:8b'],
+            'vision':      ['llava:7b', 'qwen2.5vl:7b', 'minicpm-v:8b', 'moondream:1.8b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   1,
+            'context':      16384,
+            'performance':  'Slow',
+        },
+
+        ModelSize.LARGE: {
+            'models':      ['qwen3:14b', 'qwen2.5:14b', 'phi4-reasoning:14b'],
+            'thinking':    ['qwen3:14b', 'deepseek-r1:14b', 'phi4-reasoning:14b', 'cogito:14b'],
+            'tools':       ['qwen3:14b', 'qwen2.5:14b', 'hermes3:8b'],
+            'vision':      ['qwen2.5vl:14b', 'gemma3:12b', 'mistral-small3.1:22b'],
+            'quantization': 'q3_k_m',
+            'batch_size':   1,
+            'context':      16384,
+            'performance':  'Slow',
+        },
+
+        # XLARGE unrealistic for Arc - fallback to LARGE handled in ModelRecommender
+    },
+
+    # ==========================================================================
+    # Apple Metal (Apple Silicon - unified memory)
+    # M1/M2/M3/M4 share RAM with GPU; 16-192 GB depending on config
+    # Metal is highly optimised for Ollama via llama.cpp
+    # ==========================================================================
+    AcceleratorType.APPLE_METAL: {
+
+        ModelSize.TINY: {
+            'models':      ['qwen3:0.6b', 'llama3.2:1b', 'smollm2:1.7b'],
+            'thinking':    ['deepseek-r1:1.5b', 'qwen3:0.6b'],
+            'tools':       ['qwen3:0.6b', 'llama3.2:1b'],
+            'vision':      [],
+            'quantization': 'q8_0',
+            'batch_size':   4,
+            'context':      8192,
+            'performance':  'Fast (tiny model)',
+        },
+
+        ModelSize.SMALL: {
+            'models':      ['qwen3:1.7b', 'llama3.2:3b', 'phi4-mini:3.8b'],
+            'thinking':    ['qwen3:1.7b', 'deepseek-r1:1.5b'],
+            'tools':       ['qwen3:1.7b', 'llama3.2:3b', 'granite3.1-dense:2b'],
+            'vision':      ['llama3.2-vision:3b', 'moondream:1.8b', 'minicpm-v:3b'],
+            'quantization': 'q6_k',
+            'batch_size':   4,
+            'context':      16384,
+            'performance':  'Fast',
+        },
+
+        ModelSize.MEDIUM: {
+            'models':      ['qwen3:8b', 'llama3.1:8b', 'mistral:7b', 'mistral-nemo:12b'],
+            'thinking':    ['qwen3:8b', 'deepseek-r1:8b', 'cogito:8b', 'exaone-deep:7.8b'],
+            'tools':       ['qwen3:8b', 'llama3.1:8b', 'mistral:7b', 'qwen2.5:7b',
+                            'hermes3:8b', 'granite3.1-dense:8b'],
+            'vision':      ['llava:7b', 'llama3.2-vision:11b', 'qwen2.5vl:7b',
+                            'minicpm-v:8b', 'gemma3:12b', 'moondream:1.8b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   2,
+            'context':      32768,
+            'performance':  'Fast',
+        },
+
+        ModelSize.LARGE: {
+            # M2 Max / M3 Pro 36-48 GB unified memory
+            'models':      ['qwen3:14b', 'qwen3:32b', 'deepseek-r1:14b', 'command-r:35b'],
+            'thinking':    ['qwen3:14b', 'qwen3:32b', 'deepseek-r1:14b', 'deepseek-r1:32b',
+                            'qwq:32b', 'cogito:14b', 'phi4-reasoning:14b', 'exaone-deep:32b'],
+            'tools':       ['qwen3:14b', 'qwen3:32b', 'command-r:35b', 'qwen2.5:32b',
+                            'aya-expanse:32b', 'hermes3:8b'],
+            'vision':      ['llava:34b', 'qwen2.5vl:14b', 'qwen2.5vl:32b',
+                            'llama3.2-vision:11b', 'gemma3:27b', 'mistral-small3.1:22b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   2,
+            'context':      65536,
+            'performance':  'Fast (Apple Silicon advantage)',
+        },
+
+        ModelSize.XLARGE: {
+            # M2 Ultra / M3 Max / M4 Max 64-192 GB unified memory
+            'models':      ['llama3.3:70b', 'qwen2.5:72b', 'qwen3:30b-a3b', 'deepseek-r1:70b'],
+            'thinking':    ['deepseek-r1:70b', 'qwen3:30b-a3b', 'cogito:70b',
+                            'qwq:32b', 'exaone-deep:32b'],
+            'tools':       ['llama3.3:70b', 'qwen2.5:72b', 'qwen3:30b-a3b',
+                            'hermes3:70b', 'command-r-plus:104b', 'firefunction-v2:70b'],
+            'vision':      ['llava:34b', 'qwen2.5vl:72b', 'llama3.2-vision:90b',
+                            'gemma3:27b', 'mistral-small3.1:22b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   4,
+            'context':      131072,
+            'performance':  'Fast (Apple Silicon advantage)',
+        },
+    },
+
+    # ==========================================================================
+    # CPU only - no GPU
+    # ==========================================================================
+    AcceleratorType.NONE: {
+
+        ModelSize.TINY: {
+            'models':      ['qwen3:0.6b', 'llama3.2:1b', 'smollm2:1.7b'],
+            'thinking':    ['deepseek-r1:1.5b', 'qwen3:0.6b'],
+            'tools':       ['qwen3:0.6b', 'llama3.2:1b'],
+            'vision':      ['moondream:1.8b'],
+            'quantization': 'q8_0',
+            'batch_size':   1,
+            'context':      4096,
+            'performance':  'Slow (CPU only)',
+        },
+
+        ModelSize.SMALL: {
+            'models':      ['qwen3:1.7b', 'llama3.2:3b'],
+            'thinking':    ['qwen3:1.7b', 'deepseek-r1:1.5b'],
+            'tools':       ['qwen3:1.7b', 'llama3.2:3b'],
+            'vision':      ['moondream:1.8b', 'minicpm-v:3b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   1,
+            'context':      8192,
+            'performance':  'Very Slow (CPU only)',
+        },
+
+        ModelSize.MEDIUM: {
+            'models':      ['qwen3:8b', 'mistral:7b', 'llama3.1:8b'],
+            'thinking':    ['qwen3:8b', 'deepseek-r1:8b'],
+            'tools':       ['qwen3:8b', 'mistral:7b', 'llama3.1:8b'],
+            'vision':      ['llava:7b', 'qwen2.5vl:7b', 'minicpm-v:8b'],
+            'quantization': 'q4_k_m',
+            'batch_size':   1,
+            'context':      8192,
+            'performance':  'Very Slow (CPU only)',
+        },
+
+        # LARGE / XLARGE on CPU-only is impractical - fallback handled in ModelRecommender
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers - consumed by ModelInfo and the model recommender
+# ---------------------------------------------------------------------------
+
+# All categories present in any tier entry. Add new ones here as they are added
+# to the database so get_category() degrades gracefully for old entries.
+KNOWN_CATEGORIES: List[str] = ['models', 'thinking', 'tools', 'vision']
+
+# Tier fallback order when the exact tier has no entry for an accelerator
+TIER_FALLBACK_ORDER: List[ModelSize] = [
+    ModelSize.LARGE,
+    ModelSize.MEDIUM,
+    ModelSize.SMALL,
+    ModelSize.TINY,
+]
+
+
+def get_tier(accelerator: AcceleratorType, size: ModelSize) -> TierEntry:
+    """
+    Return the tier entry for an accelerator + memory size combination.
+
+    Walks down TIER_FALLBACK_ORDER if the exact size is missing, then
+    falls back to CPU MEDIUM as a last resort.
+
+    Args:
+        accelerator: The detected primary accelerator.
+        size:        The memory-based model size tier.
+
+    Returns:
+        TierEntry dict ready for ModelRecommendation construction.
+    """
+    db = MODEL_DATABASE.get(accelerator, {})
+    entry = db.get(size)
+
+    if entry is None:
+        for fallback in TIER_FALLBACK_ORDER:
+            entry = db.get(fallback)
+            if entry is not None:
+                break
+
+    if entry is None:
+        entry = MODEL_DATABASE[AcceleratorType.NONE][ModelSize.MEDIUM]
+
+    return entry
+
+
+def get_category(tier: TierEntry, category: str) -> List[str]:
+    """
+    Safely retrieve a model list for a given category from a tier entry.
+
+    Returns an empty list if the category is not present, so callers never
+    need to guard against missing keys when new categories are added.
+
+    Args:
+        tier:     A tier entry dict from MODEL_DATABASE.
+        category: Category name, e.g. 'vision', 'tools', 'thinking'.
+
+    Returns:
+        List of model name strings.
+    """
+    return tier.get(category, [])

hestia_system-0.1.0/src/Hestia/models/info.py

@@ -0,0 +1,68 @@
+"""Typed view over the model catalog."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Union
+
+from ..types import AcceleratorType, ModelSize
+from .catalog import KNOWN_CATEGORIES, MODEL_DATABASE, TierEntry, get_category, get_tier
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    """Catalog entry for one accelerator + memory tier."""
+
+    accelerator: AcceleratorType
+    size: ModelSize
+    categories: Dict[str, List[str]] = field(default_factory=dict)
+    quantization: str = ""
+    batch_size: int = 1
+    context: int = 0
+    performance: str = ""
+
+    @classmethod
+    def from_entry(
+        cls, accelerator: AcceleratorType, size: ModelSize, entry: TierEntry
+    ) -> "ModelInfo":
+        return cls(
+            accelerator=accelerator,
+            size=size,
+            categories={c: list(get_category(entry, c)) for c in KNOWN_CATEGORIES},
+            quantization=str(entry.get("quantization", "")),
+            batch_size=int(entry.get("batch_size", 1)),
+            context=int(entry.get("context", 0)),
+            performance=str(entry.get("performance", "")),
+        )
+
+    def get(self, category: str) -> List[str]:
+        return list(self.categories.get(category, []))
+
+    def to_dict(self) -> dict:
+        return {
+            "accelerator": self.accelerator.value,
+            "size": self.size.value,
+            "categories": {k: list(v) for k, v in self.categories.items()},
+            "quantization": self.quantization,
+            "batch_size": self.batch_size,
+            "context": self.context,
+            "performance": self.performance,
+        }
+
+
+def get_model_info(
+    accelerator: Optional[AcceleratorType] = None,
+    size: Optional[ModelSize] = None,
+) -> Union[ModelInfo, List[ModelInfo]]:
+    """Return one ModelInfo when both arguments are given, else all matching entries.
+
+    A single lookup uses get_tier() and so applies its fallback rules.
+    """
+    if accelerator is not None and size is not None:
+        return ModelInfo.from_entry(accelerator, size, get_tier(accelerator, size))
+
+    return [
+        ModelInfo.from_entry(acc, sz, entry)
+        for acc, tiers in MODEL_DATABASE.items()
+        if accelerator is None or acc == accelerator
+        for sz, entry in tiers.items()
+        if size is None or sz == size
+    ]

hestia_system-0.1.0/src/Hestia/types.py

@@ -0,0 +1,19 @@
+from enum import Enum
+
+
+class AcceleratorType(Enum):
+    NONE = "none"
+    NVIDIA_CUDA = "nvidia_cuda"
+    NVIDIA_MPS = "nvidia_mps"
+    AMD_ROCM = "amd_rocm"
+    INTEL_ONEAPI = "intel_oneapi"
+    APPLE_METAL = "apple_metal"
+    QUALCOMM_HEXAGON = "qualcomm_hexagon"
+
+
+class ModelSize(Enum):
+    TINY = "tiny"
+    SMALL = "small"
+    MEDIUM = "medium"
+    LARGE = "large"
+    XLARGE = "xlarge"

hestia_system-0.1.0/src/hestia_system.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: hestia-system
+Version: 0.1.0
+Summary: System discovery, hardware and software analysis, and AI model recommendations.
+Author: Damon S. Green II (nomadiidamon)
+License: MIT
+Project-URL: Homepage, https://github.com/nomadiidamon/Hestia
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: nvidia
+Requires-Dist: nvidia-ml-py>=12.0.0; extra == "nvidia"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# Hestia for Python
+
+Hestia provides system discovery and AI model intelligence. The Python package
+currently exposes accelerator and model-size types, a model catalog, and model
+information lookup.
+
+The distribution is named `hestia-system`; import it as `Hestia`.
+
+## Installation
+
+```bash
+python -m pip install hestia-system
+```
+
+Optional dependencies are available as extras:
+
+```bash
+python -m pip install "hestia-system[nvidia]"  # NVIDIA telemetry support
+python -m pip install "hestia-system[dev]"     # pytest
+```
+
+## Usage
+
+```python
+from Hestia import AcceleratorType, ModelSize, get_model_info
+
+info = get_model_info(AcceleratorType.NVIDIA_CUDA, ModelSize.SMALL)
+print(info)
+```
+
+The package supports Python versions declared by the project metadata (Python
+3.10 and later).
+
+## Development
+
+From the repository checkout:
+
+```bash
+cd python
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Package metadata is maintained in the repository's `project.ini`. Source
+distributions include a copy of that file so they can be built independently
+of the repository checkout.

hestia_system-0.1.0/src/hestia_system.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+MANIFEST.in
+README.md
+project.ini
+pyproject.toml
+setup.py
+src/Hestia/__init__.py
+src/Hestia/model_catalog.py
+src/Hestia/types.py
+src/Hestia/models/__init__.py
+src/Hestia/models/catalog.py
+src/Hestia/models/info.py
+src/hestia_system.egg-info/PKG-INFO
+src/hestia_system.egg-info/SOURCES.txt
+src/hestia_system.egg-info/dependency_links.txt
+src/hestia_system.egg-info/requires.txt
+src/hestia_system.egg-info/top_level.txt
+tests/test_examples.py
+tests/test_models.py

hestia_system-0.1.0/src/hestia_system.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hestia_system-0.1.0/src/hestia_system.egg-info/requires.txt

@@ -0,0 +1,7 @@
+psutil>=5.9.0
+
+[dev]
+pytest>=7.0
+
+[nvidia]
+nvidia-ml-py>=12.0.0

hestia_system-0.1.0/src/hestia_system.egg-info/top_level.txt

@@ -0,0 +1 @@
+Hestia

hestia_system-0.1.0/tests/test_examples.py

@@ -0,0 +1,21 @@
+"""Run every example script and require a clean exit."""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+SRC = ROOT / "python" / "src"
+EXAMPLES = sorted((ROOT / "examples" / "python").rglob("*.py"))
+
+
+@pytest.mark.parametrize("example", EXAMPLES, ids=lambda p: p.relative_to(ROOT).as_posix())
+def test_example_runs(example):
+    env = {**os.environ, "PYTHONPATH": os.pathsep.join([str(SRC), os.environ.get("PYTHONPATH", "")])}
+    result = subprocess.run(
+        [sys.executable, str(example)], capture_output=True, text=True, timeout=60, env=env
+    )
+    assert result.returncode == 0, result.stderr

hestia_system-0.1.0/tests/test_models.py

@@ -0,0 +1,75 @@
+import os
+import subprocess
+import sys
+
+import pytest
+
+import Hestia
+from Hestia.models import (
+    KNOWN_CATEGORIES,
+    MODEL_DATABASE,
+    ModelInfo,
+    get_category,
+    get_model_info,
+    get_tier,
+)
+from Hestia.types import AcceleratorType, ModelSize
+
+
+def test_enum_values():
+    assert AcceleratorType("nvidia_cuda") is AcceleratorType.NVIDIA_CUDA
+    assert [s.value for s in ModelSize] == ["tiny", "small", "medium", "large", "xlarge"]
+
+
+def test_every_entry_has_required_keys():
+    for tiers in MODEL_DATABASE.values():
+        for entry in tiers.values():
+            for key in (*KNOWN_CATEGORIES, "quantization", "batch_size", "context", "performance"):
+                assert key in entry
+
+
+@pytest.mark.parametrize("acc", list(MODEL_DATABASE))
+@pytest.mark.parametrize("size", list(ModelSize))
+def test_get_tier_always_resolves(acc, size):
+    assert get_tier(acc, size)["models"]
+
+
+def test_fallback_for_missing_tier():
+    assert get_tier(AcceleratorType.INTEL_ONEAPI, ModelSize.XLARGE) is MODEL_DATABASE[
+        AcceleratorType.INTEL_ONEAPI
+    ][ModelSize.LARGE]
+
+
+def test_unknown_accelerator_falls_back_to_cpu():
+    entry = get_tier(AcceleratorType.QUALCOMM_HEXAGON, ModelSize.TINY)
+    assert entry is MODEL_DATABASE[AcceleratorType.NONE][ModelSize.MEDIUM]
+
+
+def test_get_category_unknown_is_empty():
+    assert get_category(get_tier(AcceleratorType.NONE, ModelSize.TINY), "nope") == []
+
+
+def test_get_model_info_single_and_all():
+    info = get_model_info(AcceleratorType.NVIDIA_CUDA, ModelSize.SMALL)
+    assert isinstance(info, ModelInfo)
+    assert info.to_dict()["accelerator"] == "nvidia_cuda"
+    assert info.get("tools")
+    total = sum(len(t) for t in MODEL_DATABASE.values())
+    assert len(get_model_info()) == total
+    assert all(i.size is ModelSize.TINY for i in get_model_info(size=ModelSize.TINY))
+
+
+def test_legacy_import_path():
+    from Hestia.model_catalog import MODEL_DATABASE as legacy
+
+    assert legacy is MODEL_DATABASE
+
+
+def test_public_api():
+    assert Hestia.get_model_info is get_model_info
+
+
+def test_models_does_not_import_hardware():
+    code = "import sys, Hestia.models; assert not any(m.startswith('Hestia.hardware') for m in sys.modules)"
+    env = {**os.environ, "PYTHONPATH": os.pathsep.join(sys.path)}
+    subprocess.run([sys.executable, "-c", code], check=True, env=env)