fusion-core 0.12.1__py3-none-any.whl

fusion_core/__init__.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import logging as _stdlib_logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("fusion-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+_logger = _stdlib_logging.getLogger("fusion_core")
+if not _logger.handlers:
+    _handler = _stdlib_logging.NullHandler()
+    _logger.addHandler(_handler)
+
+from fusion_core.config import (  # noqa: E402
+    admin_key,
+    clear_cache,
+    client_key,
+    default_gateway_base_url,
+    default_guard_sock,
+    default_mlx_base_url,
+    gateway_admin_key,
+    gateway_base_url,
+    get_env,
+    load_api_key,
+    load_dotenv,
+    load_settings,
+    profile,
+    resolve_api_key,
+    service_data_dir,
+    service_port,
+)
+from fusion_core.dsl_schema import (  # noqa: E402
+    SOCRATIC_DSL_V3_SCHEMA,
+    validate_dsl,
+    validate_dsl_str,
+)
+from fusion_core.errors import FusionError  # noqa: E402
+from fusion_core.guard_client import (  # noqa: E402
+    AllChainsVerification,
+    ChainVerification,
+    FusionGuardClient,
+    GuardEngineError,
+    GuardError,
+    GuardInvalidParamsError,
+    GuardInvalidRequestError,
+    GuardMethodNotFoundError,
+    GuardParseError,
+    GuardRateLimitError,
+    GuardRule,
+    GuardUnauthorizedError,
+    GuardVerdict,
+    RedactResult,
+    StaleEpochError,
+)
+from fusion_core.http_client import (  # noqa: E402
+    close_all,
+    gateway_circuit_breaker_ok,
+    get_async_client,
+    get_metrics_snapshot,
+    reset_metrics,
+    set_metrics_callback,
+    with_retry,
+)
+from fusion_core.logging import get_logger, setup_logging  # noqa: E402
+from fusion_core.mcp_client import (  # noqa: E402
+    McpToolClient,
+    McpToolError,
+    known_servers,
+)
+from fusion_core.mcp_registry import (  # noqa: E402
+    ApprovalVerdict,
+    McpRegistryError,
+    McpServerRecord,
+    RegistryIntegrityError,
+    RegistryLookupError,
+    check_approval,
+    load_registry,
+    resolve_server,
+)
+from fusion_core.mlx_client import (  # noqa: E402
+    EmbeddingResponse,
+    FusionMLXClient,
+    LLMResponse,
+    create_async_client,
+)
+from fusion_core.parse import (  # noqa: E402
+    ParseError,
+    parse_llm_json,
+    parse_llm_json_lenient,
+    parse_llm_json_safe,
+    strip_code_fence,
+)
+from fusion_core.proc import set_process_title  # noqa: E402
+from fusion_core.prompt import PromptManager  # noqa: E402
+from fusion_core.prompt_registry import (  # noqa: E402
+    PromptVersionError,
+    PromptVersionRecord,
+    PromptVersionRegistry,
+    SnapshotIntegrityError,
+    UnknownPromptVersionError,
+    compute_version_id,
+    is_valid_version_id,
+)
+
+try:
+    from fusion_core.tenant import (  # noqa: F401
+        TenantContext,
+        TenantContextError,
+        TenantMiddleware,
+        current,
+        decode_jwt_claims,
+        from_mapping,
+        has_scope,
+        install_tenant_middleware,
+        reset,
+        set_context,
+        tenant_context_from_token,
+    )
+
+    _tenant_available = True
+except ImportError:
+    _tenant_available = False
+    _logger.debug("fusion_core.tenant unavailable (missing dep?)")
+
+__all__ = [
+    "__version__",
+    "ParseError",
+    "parse_llm_json",
+    "parse_llm_json_lenient",
+    "parse_llm_json_safe",
+    "strip_code_fence",
+    "get_env",
+    "load_api_key",
+    "load_dotenv",
+    "FusionError",
+    "resolve_api_key",
+    "load_settings",
+    "clear_cache",
+    "client_key",
+    "admin_key",
+    "gateway_admin_key",
+    "gateway_base_url",
+    "service_port",
+    "service_data_dir",
+    "profile",
+    "default_mlx_base_url",
+    "default_gateway_base_url",
+    "default_guard_sock",
+    "get_logger",
+    "setup_logging",
+    "FusionMLXClient",
+    "LLMResponse",
+    "EmbeddingResponse",
+    "create_async_client",
+    "McpServerRecord",
+    "ApprovalVerdict",
+    "McpRegistryError",
+    "RegistryIntegrityError",
+    "RegistryLookupError",
+    "load_registry",
+    "resolve_server",
+    "check_approval",
+    "McpToolClient",
+    "McpToolError",
+    "known_servers",
+    "get_async_client",
+    "with_retry",
+    "gateway_circuit_breaker_ok",
+    "close_all",
+    "set_metrics_callback",
+    "get_metrics_snapshot",
+    "reset_metrics",
+    "PromptManager",
+    "set_process_title",
+    "PromptVersionRegistry",
+    "PromptVersionRecord",
+    "PromptVersionError",
+    "UnknownPromptVersionError",
+    "SnapshotIntegrityError",
+    "compute_version_id",
+    "is_valid_version_id",
+    "SOCRATIC_DSL_V3_SCHEMA",
+    "validate_dsl",
+    "validate_dsl_str",
+    "FusionGuardClient",
+    "GuardVerdict",
+    "GuardRule",
+    "RedactResult",
+    "ChainVerification",
+    "AllChainsVerification",
+    "GuardError",
+    "GuardParseError",
+    "GuardInvalidRequestError",
+    "GuardMethodNotFoundError",
+    "GuardInvalidParamsError",
+    "GuardRateLimitError",
+    "GuardUnauthorizedError",
+    "GuardEngineError",
+    "StaleEpochError",
+]
+
+try:
+    from fusion_core.http import create_app, install_auth, standard_error_handler  # noqa: F401
+
+    __all__.extend(["create_app", "install_auth", "standard_error_handler"])
+except ImportError:
+    _logger.debug("fastapi not installed; fusion_core.http factory unavailable")
+
+if _tenant_available:
+    __all__.extend(
+        [
+            "TenantContext",
+            "TenantContextError",
+            "TenantMiddleware",
+            "current",
+            "decode_jwt_claims",
+            "from_mapping",
+            "has_scope",
+            "install_tenant_middleware",
+            "reset",
+            "set_context",
+            "tenant_context_from_token",
+        ]
+    )

fusion_core/config.py

@@ -0,0 +1,291 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MLX_PORT = 11434
+DEFAULT_GATEWAY_PORT = 11432
+
+_SETTINGS_CACHE: dict[str, tuple[dict, float]] = {}
+
+_BOOL_TRUE = {"1", "true", "yes", "on", "y", "t"}
+_BOOL_FALSE = {"0", "false", "no", "off", "n", "f"}
+
+
+def default_mlx_base_url() -> str:
+    return os.environ.get("FUSION_MLX_URL", f"http://localhost:{DEFAULT_MLX_PORT}/v1")
+
+
+def default_gateway_base_url() -> str:
+    return os.environ.get("FUSION_GATEWAY_URL", f"http://localhost:{DEFAULT_GATEWAY_PORT}")
+
+
+DEFAULT_GUARD_SOCK = "/tmp/fusion-guard.sock"
+
+
+def default_guard_sock() -> str:
+    return os.environ.get("FUSION_GUARD_SOCK", DEFAULT_GUARD_SOCK)
+
+
+def get_env(key: str, default: Any = None, *, cast: type = str) -> Any:
+    raw = os.environ.get(key)
+    if raw is None or raw == "":
+        return default
+    if cast is bool:
+        return raw.strip().lower() in _BOOL_TRUE
+    try:
+        return cast(raw)
+    except (TypeError, ValueError) as exc:
+        logger.warning("get_env cast %s for %s failed: %s", cast.__name__, key, exc)
+        return default
+
+
+def load_settings(path: str | Path | None = None) -> dict:
+    if path is None:
+        path = Path.home() / ".fusion-mlx" / "settings.json"
+    key = str(path)
+    p = Path(path)
+    try:
+        mtime = p.stat().st_mtime
+    except FileNotFoundError:
+        raise FileNotFoundError(f"settings file not found: {key}") from None
+    cached = _SETTINGS_CACHE.get(key)
+    if cached is not None:
+        data, cached_mtime = cached
+        if cached_mtime == mtime:
+            return data
+        logger.info("load_settings cache invalidated (mtime changed) for %s", key)
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        logger.warning("load_settings malformed json %s: %s", key, exc)
+        raise
+    except OSError as exc:
+        logger.warning("load_settings read %s failed: %s", key, exc)
+        raise
+    if not isinstance(data, dict):
+        raise ValueError(f"settings file {key} is not a json object")
+    _SETTINGS_CACHE[key] = (data, mtime)
+    return data
+
+
+def resolve_api_key(
+    explicit: str | None = None,
+    *,
+    env_var: str = "FUSION_MLX_API_KEY",
+    settings_path: str | Path | None = None,
+) -> str:
+    if explicit:
+        return explicit
+    key = os.environ.get(env_var, "")
+    if key:
+        return key
+    try:
+        cfg = load_settings(settings_path)
+    except FileNotFoundError:
+        logger.debug("resolve_api_key: settings.json absent, no api_key resolved")
+        return ""
+    auth = cfg.get("auth", {})
+    if not isinstance(auth, dict):
+        logger.warning(
+            "resolve_api_key: auth is not a dict in settings, got %s; cannot read api_key",
+            type(auth).__name__,
+        )
+        return ""
+    raw = auth.get("api_key", "")
+    if raw is None:
+        logger.warning("resolve_api_key: auth.api_key is null in settings.json")
+        return ""
+    if not isinstance(raw, str):
+        logger.warning("resolve_api_key: auth.api_key not a string, got %s", type(raw).__name__)
+        return ""
+    return raw
+
+
+def load_api_key(name: str = "fusion-mlx") -> str:
+    short = name.removeprefix("fusion-")
+    env_var = f"FUSION_{short.upper().replace('-', '_')}_API_KEY"
+    key = resolve_api_key(env_var=env_var)
+    if not key:
+        raise KeyError(f"api key not found for {name}: set env {env_var} or auth.api_key in settings.json")
+    return key
+
+
+def clear_cache() -> None:
+    _SETTINGS_CACHE.clear()
+    logger.debug("config cache cleared")
+
+
+# --- dotenv env-file loading (issue #47, config-conventions §1) ---
+
+
+def _parse_dotenv_line(line: str) -> tuple[str, str] | None:
+    stripped = line.strip()
+    if not stripped or stripped.startswith("#"):
+        return None
+    if stripped.startswith("export "):
+        stripped = stripped[len("export ") :].lstrip()
+    key, sep, value = stripped.partition("=")
+    if not sep or not key.strip() or not key.strip().replace("_", "a").replace("-", "a").isalnum():
+        logger.debug("load_dotenv: skipping malformed line: %s", line.strip()[:60])
+        return None
+    key = key.strip()
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+        value = value[1:-1]
+    else:
+        # strip trailing inline comment on unquoted values
+        if " #" in value:
+            value = value.split(" #", 1)[0].rstrip()
+    return key, value
+
+
+def load_dotenv(path: str | Path | None = None, *, override: bool = False) -> dict[str, str]:
+    # Load KEY=VALUE pairs from a dotenv file into os.environ.
+    # Resolution: explicit path arg -> ENV_FILE env var -> no-op (empty dict).
+    # Default does NOT overwrite variables already set in the environment
+    # (standard dotenv semantics); override=True forces them.
+    if path is None:
+        env_file = os.environ.get("ENV_FILE", "")
+        if not env_file:
+            logger.debug("load_dotenv: no path arg and ENV_FILE unset, no-op")
+            return {}
+        path = env_file
+    p = Path(path)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        logger.warning("load_dotenv: env file not found: %s", p)
+        raise
+    loaded: dict[str, str] = {}
+    for line in text.splitlines():
+        parsed = _parse_dotenv_line(line)
+        if parsed is None:
+            continue
+        key, value = parsed
+        if not override and os.environ.get(key, "") != "":
+            logger.debug("load_dotenv: %s already set, keeping existing value", key)
+            continue
+        os.environ[key] = value
+        loaded[key] = value
+    logger.info("load_dotenv: %d vars loaded from %s (override=%s)", len(loaded), p, override)
+    return loaded
+
+
+# --- config-conventions single-point resolution (config-conventions.md §1/§3) ---
+
+_DEFAULT_GATEWAY_BASE_URL = "http://127.0.0.1:11432"
+_ANON_WARNED: set[str] = set()
+
+
+def profile() -> str:
+    return os.environ.get("FUSION_PROFILE", "dev")
+
+
+def _resolve_secret(env: str, *, hint: str) -> str:
+    key = os.environ.get(env, "")
+    if key:
+        return key
+    if profile() == "prod":
+        raise RuntimeError(f"{env} not set — {hint}, see architecture/config-conventions.md")
+    if env not in _ANON_WARNED:
+        _ANON_WARNED.add(env)
+        logger.warning("anonymous dev mode: %s not set (%s)", env, hint)
+    return ""
+
+
+def client_key() -> str:
+    for env in ("FUSION_CLIENT_KEY", "FUSION_MLX_API_KEY", "MLX_API_KEY"):
+        key = os.environ.get(env, "")
+        if key:
+            if env != "FUSION_CLIENT_KEY":
+                logger.warning("%s is deprecated, set FUSION_CLIENT_KEY instead (config-conventions §6)", env)
+            return key
+    if profile() == "prod":
+        raise RuntimeError(
+            "FUSION_CLIENT_KEY not set — obtain from gateway admin API, see architecture/config-conventions.md"
+        )
+    if "FUSION_CLIENT_KEY" not in _ANON_WARNED:
+        _ANON_WARNED.add("FUSION_CLIENT_KEY")
+        logger.warning("anonymous dev mode: FUSION_CLIENT_KEY not set (obtain from gateway admin API)")
+    return ""
+
+
+def admin_key() -> str:
+    return _resolve_secret("FUSION_ADMIN_KEY", hint="obtain from gateway admin API")
+
+
+def gateway_base_url() -> str:
+    url = os.environ.get("FUSION_GATEWAY_BASE_URL", "")
+    if url:
+        return url
+    legacy = os.environ.get("FUSION_GATEWAY_URL", "")
+    if legacy:
+        logger.warning("FUSION_GATEWAY_URL is deprecated, set FUSION_GATEWAY_BASE_URL instead (config-conventions §6)")
+        return legacy
+    return _DEFAULT_GATEWAY_BASE_URL
+
+
+def service_port(app: str, default: int | None = None) -> int:
+    if not app:
+        raise ValueError("service_port: app name required")
+    short = app.removeprefix("fusion-")
+    env = f"FUSION_{short.upper().replace('-', '_')}_PORT"
+    raw = os.environ.get(env, "")
+    if raw:
+        try:
+            return int(raw)
+        except ValueError as exc:
+            raise ValueError(f"{env} is not an integer: {raw!r}") from exc
+    if default is not None:
+        return default
+    raise ValueError(
+        f"{env} not set and no default given — "
+        "register the port in architecture/port-registry.yaml and set the env or pass default="
+    )
+
+
+def service_data_dir(app: str, default: str | Path | None = None) -> Path:
+    if not app:
+        raise ValueError("service_data_dir: app name required")
+    short = app.removeprefix("fusion-")
+    raw = os.environ.get(f"FUSION_{short.upper().replace('-', '_')}_DATA_DIR", "")
+    if raw:
+        return Path(raw)
+    if default is not None:
+        return Path(default)
+    return Path.home() / f".{short}"
+
+
+def gateway_admin_key(settings_path: str | Path | None = None) -> str:
+    key = os.environ.get("FUSION_GATEWAY_API_KEY", "")
+    if key:
+        return key
+    cfg: dict = {}
+    try:
+        cfg = load_settings(settings_path)
+    except (FileNotFoundError, OSError, ValueError) as exc:
+        logger.debug("gateway_admin_key: settings unavailable: %s", exc)
+    shell = cfg.get("shell", {})
+    if isinstance(shell, dict):
+        raw = shell.get("gateway_admin_key", "")
+        if raw is None:
+            logger.warning("gateway_admin_key: shell.gateway_admin_key is null in settings.json")
+        elif not isinstance(raw, str):
+            logger.warning("gateway_admin_key: shell.gateway_admin_key not a string, got %s", type(raw).__name__)
+        elif raw:
+            return raw
+    if profile() == "prod":
+        raise RuntimeError(
+            "FUSION_GATEWAY_API_KEY not set and shell.gateway_admin_key absent — "
+            "obtain from gateway admin API, see architecture/config-conventions.md"
+        )
+    if "FUSION_GATEWAY_API_KEY" not in _ANON_WARNED:
+        _ANON_WARNED.add("FUSION_GATEWAY_API_KEY")
+        logger.warning("anonymous dev mode: FUSION_GATEWAY_API_KEY not set (obtain from gateway admin API)")
+    return ""

fusion_core/dsl_schema.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+_VISUAL_TYPES = (
+    "array_grid",
+    "tape_diagram",
+    "geometry_2d",
+    "isometric_3d",
+    "track_timeline",
+    "bucket_divider",
+    "data_chart",
+    "flow_card",
+)
+
+_FALLBACK_TYPES = ("tape_diagram", "flow_card")
+
+SOCRATIC_DSL_V3_SCHEMA: dict = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Socratic DSL v3.0",
+    "description": "Canonical JSON Schema for the Fusion Socratic DSL v3.0 (k12-train-model spec).",
+    "type": "object",
+    "required": ["meta", "parameters", "entities", "pipeline"],
+    "additionalProperties": False,
+    "properties": {
+        "meta": {
+            "type": "object",
+            "required": ["id", "grade", "topic", "visual_type", "fallback_type"],
+            "additionalProperties": False,
+            "properties": {
+                "id": {"type": "string"},
+                "grade": {"type": "number"},
+                "topic": {"type": "string"},
+                "visual_type": {"type": "string", "enum": list(_VISUAL_TYPES)},
+                "fallback_type": {"type": "string", "enum": list(_FALLBACK_TYPES)},
+            },
+        },
+        "parameters": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "required": ["label", "value", "unit"],
+                "additionalProperties": False,
+                "properties": {
+                    "label": {"type": "string"},
+                    "value": {"type": "number"},
+                    "unit": {"type": "string"},
+                },
+            },
+        },
+        "entities": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["id", "type", "label", "properties"],
+                "additionalProperties": False,
+                "properties": {
+                    "id": {"type": "string"},
+                    "type": {"type": "string"},
+                    "label": {"type": "string"},
+                    "properties": {"type": "object"},
+                },
+            },
+        },
+        "pipeline": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["step", "title", "formula", "eval", "result_unit", "visual_state"],
+                "additionalProperties": False,
+                "properties": {
+                    "step": {"type": "number"},
+                    "title": {"type": "string"},
+                    "formula": {"type": "string"},
+                    "eval": {"type": "string"},
+                    "result_unit": {"type": "string"},
+                    "visual_state": {
+                        "type": "object",
+                        "required": ["progress_range", "active_entities", "action"],
+                        "additionalProperties": False,
+                        "properties": {
+                            "progress_range": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 2,
+                                "maxItems": 2,
+                            },
+                            "active_entities": {"type": "array", "items": {"type": "string"}},
+                            "action": {"type": "string"},
+                        },
+                    },
+                },
+            },
+        },
+    },
+}
+
+_VALIDATOR = None
+
+
+def _get_validator():
+    global _VALIDATOR
+    if _VALIDATOR is None:
+        try:
+            from jsonschema import Draft202012Validator
+        except ImportError as exc:
+            raise ImportError(
+                "dsl_schema requires jsonschema: pip install 'fusion-core[schema]' or pip install jsonschema"
+            ) from exc
+        _VALIDATOR = Draft202012Validator(SOCRATIC_DSL_V3_SCHEMA)
+        logger.debug("dsl_schema validator initialized (jsonschema Draft202012)")
+    return _VALIDATOR
+
+
+def validate_dsl(dsl_dict: dict) -> bool:
+    if not isinstance(dsl_dict, dict):
+        logger.warning("validate_dsl expects dict, got %s", type(dsl_dict).__name__)
+        return False
+    validator = _get_validator()
+    errors = sorted(validator.iter_errors(dsl_dict), key=lambda e: list(e.path))
+    if not errors:
+        return True
+    first = errors[0]
+    path = ".".join(str(p) for p in first.path) or "<root>"
+    logger.warning("dsl validation failed at %s: %s", path, first.message)
+    return False
+
+
+def validate_dsl_str(dsl_str: str) -> tuple[bool, str]:
+    if not isinstance(dsl_str, str):
+        return False, f"expected str, got {type(dsl_str).__name__}"
+    if not dsl_str.strip():
+        return False, "empty input"
+    try:
+        parsed = json.loads(dsl_str)
+    except json.JSONDecodeError as exc:
+        logger.debug("validate_dsl_str json parse fail: %s", exc)
+        return False, f"json parse error: {exc}"
+    if not isinstance(parsed, dict):
+        return False, f"expected dict, got {type(parsed).__name__}"
+    validator = _get_validator()
+    errors = sorted(validator.iter_errors(parsed), key=lambda e: list(e.path))
+    if not errors:
+        return True, ""
+    first = errors[0]
+    path = ".".join(str(p) for p in first.path) or "<root>"
+    return False, f"{path}: {first.message}"