hugpy-platform 0.2.2__tar.gz

hugpy_platform-0.2.2/LICENSE

@@ -0,0 +1,41 @@
+hugpy — Source-Available License
+
+Copyright (c) 2026 putkoff (hugpy.ai). All rights reserved.
+
+Permission is granted, free of charge, to use this software ("hugpy") for
+personal and non-commercial purposes, and for time-limited commercial
+evaluation, subject to the following conditions:
+
+1. Non-commercial use means use by an individual for personal purposes, or
+   use by a non-profit or educational institution for its own internal
+   purposes. Any use by, for, or on behalf of a for-profit business or in
+   connection with revenue-generating activity is commercial use — including
+   internal business use, use in producing goods or services, and use on
+   paid engagements.
+
+2. Commercial use requires a commercial license from the copyright holder.
+   Exception: a business may evaluate the software internally for up to
+   thirty (30) days free of charge; continued use after that requires a
+   commercial license.
+
+3. Redistribution of this software, in source or binary form, modified or
+   unmodified, is not permitted without prior written permission from the
+   copyright holder. Downloading the software from an official distribution
+   channel (PyPI, npm, hugpy.ai) is not redistribution.
+
+4. Modification for personal use or internal evaluation is permitted;
+   distribution of modified versions is not.
+
+5. This notice must be retained in all copies or substantial portions of
+   the software.
+
+6. Any use outside these terms automatically terminates this license.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+For commercial licensing or redistribution permission: https://hugpy.ai

hugpy_platform-0.2.2/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: hugpy-platform
+Version: 0.2.2
+Summary: Hugpy platform: stdlib-first foundation shared by every Hugpy package (env-backed configuration, app dirs, hardware and process probes, central URL, pydantic compatibility shim)
+Author-email: putkoff <support@hugpy.ai>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://hugpy.ai
+Project-URL: Documentation, https://github.com/hugpy/hugpy/blob/main/py/foundation/hugpy_platform/README.md
+Project-URL: Repository, https://github.com/hugpy/hugpy
+Project-URL: Source, https://github.com/hugpy/hugpy/tree/main/py/foundation/hugpy_platform
+Project-URL: Issues, https://github.com/hugpy/hugpy/issues
+Project-URL: Changelog, https://github.com/hugpy/hugpy/releases
+Project-URL: Architecture, https://github.com/hugpy/hugpy/blob/main/PARTITION.md
+Keywords: hugpy,llm,self-hosted,platform,configuration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: abstract_essentials
+Requires-Dist: platformdirs
+Provides-Extra: hardware
+Requires-Dist: psutil; extra == "hardware"
+Provides-Extra: hf
+Requires-Dist: huggingface_hub; extra == "hf"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# hugpy-platform
+
+`hugpy_platform` — extracted from `abstract_hugpy_dev` as part of the Hugpy
+partition. Ownership and allowed dependencies are declared in
+`py/partition.toml`; see `PARTITION.md` at the workspace root.
+
+Allowed Python dependencies inside the ecosystem: none.

hugpy_platform-0.2.2/README.md

@@ -0,0 +1,7 @@
+# hugpy-platform
+
+`hugpy_platform` — extracted from `abstract_hugpy_dev` as part of the Hugpy
+partition. Ownership and allowed dependencies are declared in
+`py/partition.toml`; see `PARTITION.md` at the workspace root.
+
+Allowed Python dependencies inside the ecosystem: none.

hugpy_platform-0.2.2/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hugpy-platform"
+dynamic = ["version"]
+description = "Hugpy platform: stdlib-first foundation shared by every Hugpy package (env-backed configuration, app dirs, hardware and process probes, central URL, pydantic compatibility shim)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "putkoff", email = "support@hugpy.ai" }]
+keywords = [
+    "hugpy",
+    "llm",
+    "self-hosted",
+    "platform",
+    "configuration",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "abstract_essentials",
+    "platformdirs",
+]
+
+[project.urls]
+Homepage = "https://hugpy.ai"
+Documentation = "https://github.com/hugpy/hugpy/blob/main/py/foundation/hugpy_platform/README.md"
+Repository = "https://github.com/hugpy/hugpy"
+Source = "https://github.com/hugpy/hugpy/tree/main/py/foundation/hugpy_platform"
+Issues = "https://github.com/hugpy/hugpy/issues"
+Changelog = "https://github.com/hugpy/hugpy/releases"
+Architecture = "https://github.com/hugpy/hugpy/blob/main/PARTITION.md"
+
+[project.optional-dependencies]
+# hardware.free_ram_bytes() prefers psutil off-Linux; /proc/meminfo otherwise.
+hardware = ["psutil"]
+# constants.hfApi (lazy) — only callers that talk to the Hub need it.
+hf = ["huggingface_hub"]
+test = ["pytest>=8", "pytest-timeout"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hugpy_platform = ["py.typed", "**/*.json", "**/*.sh", "**/*.md", "**/*.txt"]
+
+# ---------------------------------------------------------------------------
+# Lockstep workspace version (2026-09-22): every in-tree hugpy-* distribution
+# takes ONE version from the workspace git tag (vX.Y.Z at the repo root), so a
+# release is a tag and a build always carries the commit it came from
+# (X.Y.Z.devN+g<sha>[.dirty] between tags). A checkout without git metadata
+# builds as 0.0.0+unknown, which central refuses to advertise to workers.
+[tool.setuptools_scm]
+root = "../../.."
+fallback_version = "0.0.0+unknown"

hugpy_platform-0.2.2/setup.cfg

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

hugpy_platform-0.2.2/src/hugpy_platform/__init__.py

@@ -0,0 +1,105 @@
+"""hugpy-platform: the stdlib-first foundation every Hugpy package stands on.
+
+What lives here (and nothing above it — no engine, storage, fleet or server):
+
+    central          canonical central base URL (``HUGPY_BASE_URL`` + aliases)
+    platform_facade  OS facts (``IS_WINDOWS``/``IS_MACOS``/``IS_LINUX``) and the
+                     sanitising ``env_value`` seam over ``abstract_essentials``
+    app_dirs         per-OS data/config/cache/engine dirs and the ``~/.hugpy``
+                     runtime-file accessors
+    constants        storage roots, HF cache layout, fleet-wide defaults
+                     (import has side effects: creates dirs — import it explicitly)
+    utils            small filesystem / message / naming helpers
+    module_imports   ``get_<package>()`` lazy accessors for heavy ML libraries
+    async_runtime    one process-wide asyncio loop + sync bridges
+    client_liveness  "is the HTTP client still there" probe (Flask optional)
+    binaries / procutil / hardware   executables, process trees, RAM/GPU probes
+    compat_pydantic  pure-Python pydantic stand-in for platforms without pydantic_core
+    except_utils     ``caught`` / ``attempt`` / ``catching`` logging helpers
+    trust            Hugging Face publisher trust tiers
+    buildinfo        which build is this process: workspace version, sha/dirty,
+                     editable source, lockstep check (``/health``, ``/build``, heartbeat)
+
+This ``__init__`` re-exports only the light, side-effect-free names below; the
+heavier modules are imported by dotted path. ``buildinfo`` is exported lazily
+(``hugpy_platform.buildinfo`` resolves on first attribute access, PEP 562) so
+importing the package never pays for it.
+"""
+from __future__ import annotations
+
+from hugpy_platform.app_dirs import (
+    cache_dir,
+    config_dir,
+    data_dir,
+    engine_dir,
+    ensure_hugpy_home,
+    hugpy_config_dir,
+    hugpy_home,
+    hugpy_logs_dir,
+    hugpy_run_dir,
+    hugpy_state_dir,
+    models_root,
+)
+from hugpy_platform.central import CENTRAL_ENV_VARS, DEFAULT_CENTRAL, central_base_url
+from hugpy_platform.compat_pydantic import ensure_pydantic
+from hugpy_platform.except_utils import FAILED, attempt, catching, caught, caught_block
+from hugpy_platform.platform_facade import EXE_SUFFIX, IS_LINUX, IS_MACOS, IS_WINDOWS, env_value
+from hugpy_platform.trust import trust_label, trust_tier
+
+try:  # the installed distribution's version: the workspace tag/commit, never a literal
+    from importlib.metadata import version as _dist_version
+    __version__ = _dist_version("hugpy-platform")
+except Exception:  # noqa: BLE001 — source tree without metadata
+    __version__ = "0.0.0+unknown"
+
+_LAZY_SUBMODULES = ("buildinfo",)
+
+
+def __getattr__(name: str):
+    """Lazy submodule export: ``hugpy_platform.buildinfo`` without an import-time cost."""
+    if name in _LAZY_SUBMODULES:
+        import importlib
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    # central
+    "CENTRAL_ENV_VARS",
+    "DEFAULT_CENTRAL",
+    "central_base_url",
+    # platform facts + env seam
+    "EXE_SUFFIX",
+    "IS_LINUX",
+    "IS_MACOS",
+    "IS_WINDOWS",
+    "env_value",
+    # app dirs
+    "cache_dir",
+    "config_dir",
+    "data_dir",
+    "engine_dir",
+    "ensure_hugpy_home",
+    "hugpy_config_dir",
+    "hugpy_home",
+    "hugpy_logs_dir",
+    "hugpy_run_dir",
+    "hugpy_state_dir",
+    "models_root",
+    # pydantic shim
+    "ensure_pydantic",
+    # exception helpers
+    "FAILED",
+    "attempt",
+    "catching",
+    "caught",
+    "caught_block",
+    # trust tiers
+    "trust_label",
+    "trust_tier",
+    # build identity (lazy submodule)
+    "buildinfo",
+]

hugpy_platform-0.2.2/src/hugpy_platform/app_dirs.py

@@ -0,0 +1,305 @@
+"""Per-OS application directories — one source of truth.
+
+Replaces the scattered hardcoded ``/srv/abstractendeavors/...``,
+``~/.local/share/hugpy``, ``/etc/llama-swap``, and ``/mnt/llm_storage`` literals.
+Every path is overridable by the same env vars the code already honoured, so
+existing Linux deployments are unaffected; only the *defaults* become per-OS:
+
+    data_dir()    Linux ~/.local/share/hugpy   macOS ~/Library/Application Support/hugpy   Windows %LOCALAPPDATA%\\hugpy
+    config_dir()  Linux ~/.config/hugpy        macOS ~/Library/Application Support/hugpy   Windows %LOCALAPPDATA%\\hugpy
+    cache_dir()   Linux ~/.cache/hugpy         macOS ~/Library/Caches/hugpy                Windows %LOCALAPPDATA%\\hugpy\\Cache
+    engine_dir()  data_dir()/engine            — where the fetched llama.cpp binary lands
+    models_root() DEFAULT_ROOT or data_dir()/llm_storage
+
+We use ``platformdirs`` when available (added to base deps) and fall back to a
+hand-rolled per-OS layout so this module never hard-fails on import.
+"""
+from __future__ import annotations
+
+import os
+
+from hugpy_platform.platform_facade import IS_MACOS, IS_WINDOWS, env_value
+
+_APP = "hugpy"
+
+
+def _home(*parts: str) -> str:
+    return os.path.join(os.path.expanduser("~"), *parts)
+
+
+def _fallback_data() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP)
+    if IS_MACOS:
+        return _home("Library", "Application Support", _APP)
+    return os.path.join(os.environ.get("XDG_DATA_HOME") or _home(".local", "share"), _APP)
+
+
+def _fallback_config() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP)
+    if IS_MACOS:
+        return _home("Library", "Application Support", _APP)
+    return os.path.join(os.environ.get("XDG_CONFIG_HOME") or _home(".config"), _APP)
+
+
+def _fallback_cache() -> str:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA") or _home("AppData", "Local")
+        return os.path.join(base, _APP, "Cache")
+    if IS_MACOS:
+        return _home("Library", "Caches", _APP)
+    return os.path.join(os.environ.get("XDG_CACHE_HOME") or _home(".cache"), _APP)
+
+
+def _dirs():
+    try:
+        import platformdirs
+
+        return platformdirs.PlatformDirs(_APP, appauthor=False)
+    except Exception:
+        return None
+
+
+def data_dir() -> str:
+    override = env_value("HUGPY_DATA_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_data_dir if d else _fallback_data())
+
+
+def config_dir() -> str:
+    override = env_value("HUGPY_CONFIG_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_config_dir if d else _fallback_config())
+
+
+def cache_dir() -> str:
+    override = env_value("HUGPY_CACHE_DIR")
+    if override:
+        return _ensure(override)
+    d = _dirs()
+    return _ensure(d.user_cache_dir if d else _fallback_cache())
+
+
+def engine_dir() -> str:
+    """Where ``hugpy install-engine`` unpacks the native llama.cpp binaries."""
+    override = env_value("HUGPY_ENGINE_DIR") or env_value("LLAMA_CPP_DIR")
+    if override:
+        return _ensure(override)
+    return _ensure(os.path.join(data_dir(), "engine"))
+
+
+def models_root() -> str:
+    """Model/upload/dataset storage root.
+
+    Honours the legacy ``DEFAULT_ROOT``/``MODELS_HOME`` env vars first — but only
+    if that path can actually be created and written. A stale/un-writable override
+    (e.g. ``DEFAULT_ROOT=/mnt/llm_storage`` carried in a server ``.env`` onto a
+    worker or a phone where ``/mnt`` is read-only) is ignored in favour of a
+    per-user dir under ``data_dir()``, so storage never lands on a dead path.
+    """
+    override = env_value("DEFAULT_ROOT")
+    if override and _usable(override):
+        return override
+    # Preserve the historical Linux mount when it exists and is writable.
+    legacy = "/mnt/llm_storage"
+    try:
+        if os.path.isdir(legacy) and os.access(legacy, os.W_OK):
+            return legacy
+    except OSError:
+        pass
+    return _ensure(os.path.join(data_dir(), "llm_storage"))
+
+
+def demo_media_base() -> str:
+    """Base URL the video arm's canned demo loads its sample media from."""
+    return env_value("HUGPY_DEMO_MEDIA_BASE") or "https://hugpy.ai/demo-media"
+
+
+def demo_media_dir() -> str:
+    """Local demo-media tree to serve at ``/demo-media/`` (self-hosters).
+
+    Empty string means "not configured" — deliberately NO default and NO
+    directory creation; the ``/demo-media/`` route only exists when this is set.
+    """
+    return env_value("HUGPY_DEMO_MEDIA_DIR") or ""
+
+
+def _usable(path: str) -> bool:
+    """True only if *path* exists (or can be created) AND is writable."""
+    try:
+        os.makedirs(path, exist_ok=True)
+        return os.path.isdir(path) and os.access(path, os.W_OK)
+    except OSError:
+        return False
+
+
+def _ensure(path: str) -> str:
+    try:
+        os.makedirs(path, exist_ok=True)
+    except OSError:
+        pass
+    return path
+
+
+# ---------------------------------------------------------------------------
+# hugpy runtime "mechanic" files  (HUGPY_HOME, default ~/.hugpy)
+# ---------------------------------------------------------------------------
+# Historically these state/config/log files were written straight into $HOME
+# (``~/todo.json``, ``~/steward-state.json``, ``~/.abstract_hugpy_worker.json``,
+# ``~/model_metadata.db`` …), strewing the home directory. They now live under a
+# single base dir — ``HUGPY_HOME`` (default ``~/.hugpy``) — split into::
+#
+#     state/   todo.json, steward-state.json, model_metadata.db, flow.json, …
+#     config/  abstract_hugpy_worker.json (+ .settings.json/.update.json)
+#     logs/    bridge-mail.jsonl, bugreport.json
+#     run/     *.lock
+#
+# Each named accessor MIGRATES a legacy ``~/<name>`` file into its new home the
+# first time it is resolved (atomic same-fs rename, cross-fs copy fallback), so
+# upgrades are seamless and idempotent — no flag-day, no data loss. Every path
+# stays overridable so existing deployments and tests can pin locations.
+#
+# NOTE: standalone station-stack scripts (keeper_relay.py, bugreport/scanner.py)
+# run under the system interpreter and cannot import this package; they carry a
+# byte-identical inline resolver. Keep the two in sync — this module is the spec.
+
+def hugpy_home() -> str:
+    """Single base directory for hugpy's runtime files. Default ``~/.hugpy``."""
+    return _ensure(env_value("HUGPY_HOME") or _home(".hugpy"))
+
+
+def hugpy_state_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "state"))
+
+
+def hugpy_config_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "config"))
+
+
+def hugpy_logs_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "logs"))
+
+
+def hugpy_run_dir() -> str:
+    return _ensure(os.path.join(hugpy_home(), "run"))
+
+
+def _relocate(new_path: str, *legacy_names: str) -> str:
+    """Return *new_path*, first migrating a legacy ``~/<name>`` into it once.
+
+    Idempotent and safe: if *new_path* already exists nothing moves. Uses an
+    atomic rename on the same filesystem and falls back to a copy+unlink across
+    filesystems. Any failure leaves the legacy file untouched and returns the
+    new path anyway (a fresh file is then created there).
+    """
+    try:
+        if os.path.exists(new_path):
+            return new_path
+        for name in legacy_names:
+            old = _home(name)
+            if not os.path.exists(old):
+                continue
+            if os.path.abspath(old) == os.path.abspath(new_path):
+                continue
+            try:
+                os.replace(old, new_path)          # atomic, same filesystem
+            except OSError:
+                import shutil
+                shutil.move(old, new_path)          # cross-filesystem fallback
+            break
+    except OSError:
+        pass
+    return new_path
+
+
+# --- named accessors --------------------------------------------------------
+
+def worker_id_file() -> str:
+    """``config/abstract_hugpy_worker.json`` — the worker identity file.
+
+    Honors an explicit ``WORKER_ID_FILE`` override (used by tests / multi-worker
+    hosts); otherwise migrates the legacy ``~/.abstract_hugpy_worker.json`` plus
+    its ``.settings.json`` / ``.update.json`` sidecars into ``config/``.
+    """
+    override = env_value("WORKER_ID_FILE")
+    if override:
+        return override
+    new = os.path.join(hugpy_config_dir(), "abstract_hugpy_worker.json")
+    _relocate(new, ".abstract_hugpy_worker.json")
+    for suffix in (".settings.json", ".update.json"):
+        _relocate(new + suffix, ".abstract_hugpy_worker.json" + suffix)
+    return new
+
+
+def gguf_worker_id_file() -> str:
+    """``config/gguf_worker.json`` — sibling worker identity (same pattern)."""
+    override = env_value("WORKER_ID_FILE")
+    if override:
+        return override
+    new = os.path.join(hugpy_config_dir(), "gguf_worker.json")
+    return _relocate(new, ".gguf_worker.json")
+
+
+def todo_file() -> str:
+    return _relocate(os.path.join(hugpy_state_dir(), "todo.json"), "todo.json")
+
+
+def todo_history_file() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "todo-history.jsonl"), "todo-history.jsonl"
+    )
+
+
+def todo_lock() -> str:
+    return _relocate(os.path.join(hugpy_run_dir(), "todo.lock"), ".todo.lock")
+
+
+def steward_config() -> str:
+    return _relocate(os.path.join(hugpy_config_dir(), "steward.json"), "steward.json")
+
+
+def steward_state() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "steward-state.json"), "steward-state.json"
+    )
+
+
+def model_metadata_db() -> str:
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "model_metadata.db"), "model_metadata.db"
+    )
+
+
+def model_physical_json() -> str:
+    # The ``.lock`` sidecar is derived by callers as ``path + ".lock"`` and rides
+    # along in state/ next to the file — intentionally not split into run/.
+    return _relocate(
+        os.path.join(hugpy_state_dir(), "model_physical.json"), "model_physical.json"
+    )
+
+
+def flow_json() -> str:
+    return _relocate(os.path.join(hugpy_state_dir(), "flow.json"), "flow.json")
+
+
+def bridge_mail() -> str:
+    return _relocate(
+        os.path.join(hugpy_logs_dir(), "bridge-mail.jsonl"), ".bridge-mail.jsonl"
+    )
+
+
+def bugreport_json() -> str:
+    return _relocate(os.path.join(hugpy_logs_dir(), "bugreport.json"), "bugreport.json")
+
+
+def ensure_hugpy_home() -> str:
+    """Create the full ``HUGPY_HOME`` skeleton. Called by installers/postinst."""
+    hugpy_state_dir(); hugpy_config_dir(); hugpy_logs_dir(); hugpy_run_dir()
+    return hugpy_home()