constants.py

"""
constants.py - Project-wide constants for FLocKit (FLock.io).

Defines constants used across the FLocKit project, including the canonical
brand identity (product name, vendor, tagline, homepage) and the list of
supported template names. Template registration and discovery is handled by
``templates/__init__.py``; this module simply re-exports the template names
so that entry-point code (``main.py``, ``bootstrap.py``) can validate user
input without importing the full template machinery.

Sections:
    Path constants      - Repository / output path roots.
    Brand constants     - Single source of truth for product / vendor strings
                          consumed by CLI ``--version``, log banners, OCI
                          labels, and the FlockSDK health endpoint.
    Template names      - Canonical template identifiers and tuple.
    SDK constants       - Defaults for the FLock SDK server.
    Helper functions    - Lightweight validators and formatters.

Usage:
    from constants import AVAILABLE_TEMPLATES, is_valid_template
    from constants import REPO_ROOT, DEFAULT_OUTPUT_ROOT
    from constants import PRODUCT_NAME, VENDOR, get_product_version
"""

from __future__ import annotations

import os

# -----------------------------------------------------------------------------
# Path constants
# -----------------------------------------------------------------------------
# Project root directory (parent of this file).
REPO_ROOT: str = os.path.abspath(os.path.dirname(os.path.abspath(__file__)))

# Default root directory for all outputs (checkpoints, logs, cache, inference).
# Overridable via tracking_args.output_root in YAML.
DEFAULT_OUTPUT_ROOT: str = "output"

# -----------------------------------------------------------------------------
# Brand constants
# -----------------------------------------------------------------------------
# Single source of truth for the FLocKit product identity. Any surface that
# shows the brand (CLI ``--version``, argparse epilog, log banners, Docker
# OCI labels, FlockSDK ``/`` health endpoint, persisted artifact metadata)
# must read from these constants so the wording stays consistent.

# Human-readable product name.
PRODUCT_NAME: str = "FLocKit"

# Distribution / installable package name (matches ``pyproject.toml``
# ``[project].name`` and ``importlib.metadata`` lookups).
PRODUCT_DIST_NAME: str = "flockit"

# Short tagline reused as a one-line subtitle / byline beneath the
# product name. Carries the parent brand (FLock.io) so operators see
# product + vendor together at every entry point.
PRODUCT_TAGLINE: str = "FLocKit · FLock.io"

# Parent brand / vendor (used in Docker OCI labels, CLI epilog, etc.).
VENDOR: str = "FLock.io"

# Project homepage; surfaced in --version, OCI labels, and CLI epilog.
HOMEPAGE: str = "https://flock.io"


def get_product_version() -> str:
    """
    Resolve the installed FLocKit version.

    Tries the installed-package metadata first (``importlib.metadata``) so
    `pip install flockit` users get the exact wheel version. Falls back to
    the version declared in ``pyproject.toml`` so source-only checkouts
    (developer machines, ``uv run`` from a clone) still report a real
    version instead of "unknown".

    Returns:
        Semver string (e.g. ``"1.0.0"``) or ``"unknown"`` if neither lookup
        succeeds. Never raises — callers can safely embed the result in a
        log line or HTTP response.
    """
    try:
        from importlib.metadata import version as _pkg_version

        return _pkg_version(PRODUCT_DIST_NAME)
    except Exception:
        pass

    try:
        try:
            import tomllib  # 3.11+
        except ImportError:  # pragma: no cover - 3.10 fallback
            import tomli as tomllib  # type: ignore[no-redef]

        pyproject = os.path.join(
            os.path.dirname(os.path.abspath(__file__)),
            "pyproject.toml",
        )
        if os.path.exists(pyproject):
            with open(pyproject, "rb") as fh:
                data = tomllib.load(fh)
            return str(data.get("project", {}).get("version", "unknown"))
    except Exception:
        pass

    return "unknown"


# -----------------------------------------------------------------------------
# Template name constants
# -----------------------------------------------------------------------------
# These MUST stay in sync with the TEMPLATE_REGISTRY in templates/__init__.py.
# If you add a new template, add its name here AND register it in the registry.

LLM_FINETUNING: str = "llm_finetuning"
AUTOMATIC_SPEECH_RECOGNITION: str = "automatic_speech_recognition"
TIME_SERIES_PREDICTION: str = "time_series_prediction"
GRAPH_NODE_CLASSIFICATION: str = "graph_node_classification"

AVAILABLE_TEMPLATES: tuple[str, ...] = (
    LLM_FINETUNING,
    AUTOMATIC_SPEECH_RECOGNITION,
    TIME_SERIES_PREDICTION,
    GRAPH_NODE_CLASSIFICATION,
)

# -----------------------------------------------------------------------------
# SDK constants
# -----------------------------------------------------------------------------

# Default port for the FLock SDK Flask server.
DEFAULT_SDK_PORT: int = 5000

# Fallback loss value used when evaluation returns non-finite results.
FALLBACK_LOSS_VALUE: float = 999.0


# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------

def is_valid_template(template_name: str) -> bool:
    """
    Check whether *template_name* is a recognised FLocKit template.

    Args:
        template_name: The template identifier to validate.

    Returns:
        True if the name is in the list of available templates.
    """
    return template_name in AVAILABLE_TEMPLATES


def get_template_choices() -> str:
    """
    Return a comma-separated string of available template names.

    Useful for CLI help text and error messages.

    Returns:
        Formatted string listing all template names.
    """
    return ", ".join(AVAILABLE_TEMPLATES)