nat-engine 1__py3-none-any.whl

mannf/product/doctor.py

@@ -0,0 +1,509 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""``nat doctor`` — pre-flight environment validation checks.
+
+Run via ``nat doctor [--json] [--verbose]``.
+
+Exit codes:
+    0  All checks passed (no FAILs)
+    1  One or more checks failed
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+# ---------------------------------------------------------------------------
+# Result model
+# ---------------------------------------------------------------------------
+
+_STATUS_PASS = "pass"
+_STATUS_FAIL = "fail"
+_STATUS_WARN = "warn"
+_STATUS_SKIP = "skip"
+
+_STATUS_ICON = {
+    _STATUS_PASS: "✅",
+    _STATUS_FAIL: "❌",
+    _STATUS_WARN: "⚠️ ",
+    _STATUS_SKIP: "⏭️ ",
+}
+
+_STATUS_LABEL = {
+    _STATUS_PASS: "PASS",
+    _STATUS_FAIL: "FAIL",
+    _STATUS_WARN: "WARN",
+    _STATUS_SKIP: "SKIP",
+}
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: str  # "pass" | "fail" | "warn" | "skip"
+    message: str
+    detail: Optional[str] = field(default=None)
+
+
+# ---------------------------------------------------------------------------
+# Individual checks
+# ---------------------------------------------------------------------------
+
+
+def _check_python_version() -> CheckResult:
+    """Check Python >= 3.10."""
+    info = sys.version_info
+    major = info.major
+    minor = info.minor
+    micro = info.micro
+    version_str = f"{major}.{minor}.{micro}"
+    if (major, minor) >= (3, 10):
+        return CheckResult(
+            name="Python version",
+            status=_STATUS_PASS,
+            message=f"Python {version_str} ✓",
+        )
+    return CheckResult(
+        name="Python version",
+        status=_STATUS_FAIL,
+        message=f"Python {version_str} is below the minimum required 3.10",
+        detail=(
+            "NAT requires Python 3.10 or later. "
+            "Please upgrade your Python installation."
+        ),
+    )
+
+
+def _check_pip_extras() -> CheckResult:
+    """Check that critical optional dependencies are importable."""
+    required = {
+        "yaml": "pyyaml",
+        "alembic": "alembic",
+        "httpx": "httpx",
+        "uvicorn": "uvicorn",
+    }
+    missing: List[str] = []
+    for module_name, package_name in required.items():
+        try:
+            importlib.import_module(module_name)
+        except ImportError:
+            missing.append(package_name)
+
+    if not missing:
+        return CheckResult(
+            name="Required pip extras",
+            status=_STATUS_PASS,
+            message="All critical dependencies are installed.",
+        )
+    joined = ", ".join(missing)
+    return CheckResult(
+        name="Required pip extras",
+        status=_STATUS_WARN,
+        message=f"Missing optional dependencies: {joined}",
+        detail=(
+            f"Install missing packages with: pip install {' '.join(missing)}\n"
+            "Or reinstall NAT with all extras: pip install 'nat-engine[all]'"
+        ),
+    )
+
+
+def _check_env_vars(natrc: dict) -> CheckResult:
+    """Check critical environment variables based on the configured mode."""
+    mode = natrc.get("mode", "") if natrc else ""
+
+    if mode == "cli":
+        return CheckResult(
+            name="Critical environment variables",
+            status=_STATUS_SKIP,
+            message="Mode is 'cli' — no server-side env vars required.",
+        )
+
+    missing: List[str] = []
+    hints: List[str] = []
+
+    if mode in ("", "self-hosted"):
+        if not os.environ.get("DATABASE_URL"):
+            missing.append("DATABASE_URL")
+            hints.append("Set DATABASE_URL in your .env file — see .env.example for the format.")
+
+    if mode in ("", "saas"):
+        if not os.environ.get("NAT_API_KEY"):
+            missing.append("NAT_API_KEY")
+            hints.append("Set NAT_API_KEY in your .env file or export it in your shell.")
+
+    if not missing:
+        return CheckResult(
+            name="Critical environment variables",
+            status=_STATUS_PASS,
+            message="All required environment variables are set.",
+        )
+
+    joined = ", ".join(missing)
+    return CheckResult(
+        name="Critical environment variables",
+        status=_STATUS_FAIL,
+        message=f"Missing required environment variable(s): {joined}",
+        detail="\n".join(hints),
+    )
+
+
+def _check_natrc(config_path: Optional[str] = None) -> CheckResult:
+    """Attempt to load .natrc and report results."""
+    # Lazy import to avoid circular deps
+    from mannf.product.cli import _load_natrc  # noqa: PLC0415
+
+    try:
+        data = _load_natrc(config_path)
+    except ValueError as exc:
+        return CheckResult(
+            name=".natrc configuration",
+            status=_STATUS_FAIL,
+            message="Found .natrc but could not parse it.",
+            detail=f"Parse error: {exc}\nFix the YAML syntax in your .natrc file.",
+        )
+    except OSError as exc:
+        return CheckResult(
+            name=".natrc configuration",
+            status=_STATUS_FAIL,
+            message="Error reading .natrc file.",
+            detail=f"I/O error: {exc}",
+        )
+
+    if not data and data is not None:
+        # File found but empty
+        return CheckResult(
+            name=".natrc configuration",
+            status=_STATUS_WARN,
+            message=".natrc was found but is empty.",
+            detail="Add at minimum a 'mode' key. Run `nat setup` to generate a config.",
+        )
+
+    if data:
+        key_count = len(data)
+        # Try to detect the path used
+        import pathlib  # noqa: PLC0415
+
+        candidates = [
+            str(pathlib.Path.cwd() / ".natrc"),
+            str(pathlib.Path.home() / ".natrc"),
+        ]
+        found_path = next((p for p in candidates if os.path.isfile(p)), "<config>")
+        return CheckResult(
+            name=".natrc configuration",
+            status=_STATUS_PASS,
+            message=f"Loaded {found_path} ({key_count} key{'s' if key_count != 1 else ''}).",
+        )
+
+    return CheckResult(
+        name=".natrc configuration",
+        status=_STATUS_WARN,
+        message=".natrc not found in cwd or home directory.",
+        detail="Run `nat setup` to create a .natrc configuration file.",
+    )
+
+
+def _check_database() -> CheckResult:
+    """Try a simple SELECT 1 against DATABASE_URL."""
+    db_url = os.environ.get("DATABASE_URL")
+    if not db_url:
+        return CheckResult(
+            name="Database connectivity",
+            status=_STATUS_SKIP,
+            message="DATABASE_URL is not set — skipping DB connectivity check.",
+        )
+
+    try:
+        import sqlalchemy  # noqa: PLC0415
+
+        engine = sqlalchemy.create_engine(db_url, pool_pre_ping=True)
+        with engine.connect() as conn:
+            conn.execute(sqlalchemy.text("SELECT 1"))
+        engine.dispose()
+    except ImportError:
+        return CheckResult(
+            name="Database connectivity",
+            status=_STATUS_SKIP,
+            message="SQLAlchemy is not installed — skipping DB connectivity check.",
+            detail="Install with: pip install sqlalchemy",
+        )
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(
+            name="Database connectivity",
+            status=_STATUS_FAIL,
+            message="Could not connect to the database.",
+            detail=(
+                f"Error: {exc}\n"
+                "Check that DATABASE_URL is correct and the database server is running."
+            ),
+        )
+
+    return CheckResult(
+        name="Database connectivity",
+        status=_STATUS_PASS,
+        message="Successfully connected to the database.",
+    )
+
+
+def _check_alembic_migrations() -> CheckResult:
+    """Compare Alembic current head vs DB revision."""
+    db_url = os.environ.get("DATABASE_URL")
+    if not db_url:
+        return CheckResult(
+            name="Alembic migration state",
+            status=_STATUS_SKIP,
+            message="DATABASE_URL is not set — skipping migration check.",
+        )
+
+    try:
+        from alembic import command as alembic_command  # noqa: PLC0415
+        from alembic.config import Config as AlembicConfig  # noqa: PLC0415
+        from alembic.runtime.migration import MigrationContext  # noqa: PLC0415
+        from alembic.script import ScriptDirectory  # noqa: PLC0415
+        import sqlalchemy  # noqa: PLC0415
+    except ImportError:
+        return CheckResult(
+            name="Alembic migration state",
+            status=_STATUS_SKIP,
+            message="Alembic is not installed — skipping migration state check.",
+            detail="Install with: pip install alembic",
+        )
+
+    # Try to find alembic.ini
+    import pathlib  # noqa: PLC0415
+
+    alembic_ini_candidates = [
+        pathlib.Path.cwd() / "alembic.ini",
+        pathlib.Path(__file__).parent.parent.parent.parent / "alembic.ini",
+    ]
+    alembic_ini = next((str(p) for p in alembic_ini_candidates if p.exists()), None)
+    if not alembic_ini:
+        return CheckResult(
+            name="Alembic migration state",
+            status=_STATUS_SKIP,
+            message="alembic.ini not found — skipping migration state check.",
+        )
+
+    try:
+        cfg = AlembicConfig(alembic_ini)
+        cfg.set_main_option("sqlalchemy.url", db_url)
+        script = ScriptDirectory.from_config(cfg)
+        heads = set(script.get_heads())
+
+        engine = sqlalchemy.create_engine(db_url)
+        with engine.connect() as conn:
+            context = MigrationContext.configure(conn)
+            current_revs = set(context.get_current_heads())
+        engine.dispose()
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(
+            name="Alembic migration state",
+            status=_STATUS_WARN,
+            message="Could not determine migration state.",
+            detail=f"Error: {exc}",
+        )
+
+    if current_revs == heads:
+        return CheckResult(
+            name="Alembic migration state",
+            status=_STATUS_PASS,
+            message="Database is up-to-date with the latest migrations.",
+        )
+
+    pending = heads - current_revs
+    return CheckResult(
+        name="Alembic migration state",
+        status=_STATUS_WARN,
+        message=f"Database has {len(pending)} pending migration(s).",
+        detail=(
+            f"Pending revision(s): {', '.join(sorted(pending))}\n"
+            "Run `alembic upgrade head` or `nat upgrade --migrate` to apply them."
+        ),
+    )
+
+
+def _check_llm_keys() -> CheckResult:
+    """Check for at least one LLM provider API key."""
+    openai = os.environ.get("OPENAI_API_KEY")
+    anthropic = os.environ.get("ANTHROPIC_API_KEY")
+
+    if openai or anthropic:
+        providers: List[str] = []
+        if openai:
+            providers.append("OpenAI")
+        if anthropic:
+            providers.append("Anthropic")
+        return CheckResult(
+            name="LLM provider keys",
+            status=_STATUS_PASS,
+            message=f"LLM key(s) found: {', '.join(providers)}.",
+        )
+
+    return CheckResult(
+        name="LLM provider keys",
+        status=_STATUS_SKIP,
+        message="No LLM provider keys set (OPENAI_API_KEY, ANTHROPIC_API_KEY). LLM features will be disabled.",
+        detail=(
+            "To enable LLM-powered features set one of:\n"
+            "  export OPENAI_API_KEY=sk-...\n"
+            "  export ANTHROPIC_API_KEY=sk-ant-..."
+        ),
+    )
+
+
+def _check_exporter(natrc: dict) -> CheckResult:
+    """If an exporter is configured in .natrc, test its connection."""
+    if not natrc:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_SKIP,
+            message="No .natrc loaded — skipping exporter connectivity check.",
+        )
+
+    export_config = natrc.get("export")
+    if not export_config:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_SKIP,
+            message="No 'export' key in .natrc — skipping exporter connectivity check.",
+        )
+
+    exporter_name = export_config.get("type") if isinstance(export_config, dict) else None
+    if not exporter_name:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_SKIP,
+            message="'export.type' not specified in .natrc — skipping exporter connectivity check.",
+        )
+
+    try:
+        from mannf.product.exporters import loader as exporter_loader  # noqa: PLC0415
+    except ImportError as exc:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_SKIP,
+            message="Exporter loader not available.",
+            detail=f"Import error: {exc}",
+        )
+
+    all_exporters = exporter_loader.load_all_exporters()
+    exporter = exporter_loader.get_exporter_by_name(exporter_name, all_exporters)
+    if exporter is None:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_FAIL,
+            message=f"Exporter '{exporter_name}' not found.",
+            detail=(
+                f"Check that 'export.type' in .natrc is a valid exporter name. "
+                f"Available exporters: {', '.join(e.name for e in all_exporters) or 'none'}."
+            ),
+        )
+
+    try:
+        ok, msg = exporter.test_connection(export_config)
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_FAIL,
+            message=f"Exporter '{exporter_name}' raised an error during test_connection().",
+            detail=f"Error: {exc}",
+        )
+
+    if ok:
+        return CheckResult(
+            name="Exporter connectivity",
+            status=_STATUS_PASS,
+            message=f"Exporter '{exporter_name}' connection test passed.",
+        )
+
+    return CheckResult(
+        name="Exporter connectivity",
+        status=_STATUS_FAIL,
+        message=f"Exporter '{exporter_name}' connection test failed: {msg}",
+        detail=(
+            f"Check your '{exporter_name}' credentials in .natrc under the 'export' key."
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+async def run_doctor(args: argparse.Namespace) -> int:
+    """Run all pre-flight checks and print results.
+
+    Parameters
+    ----------
+    args:
+        Parsed CLI arguments.  Reads ``json_output`` (bool) and ``verbose`` (bool).
+
+    Returns
+    -------
+    int
+        0 if no checks failed, 1 if any check failed.
+    """
+    json_output: bool = getattr(args, "json_output", False)
+    verbose: bool = getattr(args, "verbose", False)
+    config_path: Optional[str] = getattr(args, "config", None)
+
+    # Load .natrc first so we can pass it to checks that need it.
+    try:
+        from mannf.product.cli import _load_natrc  # noqa: PLC0415
+        natrc = _load_natrc(config_path)
+    except Exception:  # noqa: BLE001
+        natrc = {}
+
+    results: List[CheckResult] = [
+        _check_python_version(),
+        _check_pip_extras(),
+        _check_env_vars(natrc),
+        _check_natrc(config_path),
+        _check_database(),
+        _check_alembic_migrations(),
+        _check_llm_keys(),
+        _check_exporter(natrc),
+    ]
+
+    if json_output:
+        output = [
+            {
+                "name": r.name,
+                "status": r.status,
+                "message": r.message,
+                **({"detail": r.detail} if r.detail is not None else {}),
+            }
+            for r in results
+        ]
+        print(json.dumps(output, indent=2))
+    else:
+        print("🩺 NAT Doctor — Pre-flight Checks")
+        print()
+        for result in results:
+            icon = _STATUS_ICON[result.status]
+            label = _STATUS_LABEL[result.status]
+            print(f"  {icon} [{label}] {result.name}: {result.message}")
+            if verbose and result.detail:
+                for line in result.detail.splitlines():
+                    print(f"           {line}")
+        print()
+
+        n_pass = sum(1 for r in results if r.status == _STATUS_PASS)
+        n_fail = sum(1 for r in results if r.status == _STATUS_FAIL)
+        n_warn = sum(1 for r in results if r.status == _STATUS_WARN)
+        n_skip = sum(1 for r in results if r.status == _STATUS_SKIP)
+        print(
+            f"  {n_pass} passed, {n_fail} failed, {n_warn} warning{'s' if n_warn != 1 else ''}, {n_skip} skipped"
+        )
+
+    any_fail = any(r.status == _STATUS_FAIL for r in results)
+    return 1 if any_fail else 0

mannf/product/exporters/__init__.py

@@ -0,0 +1,65 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Exporter plugins package — public API."""
+
+from __future__ import annotations
+
+from mannf.product.exporters.azuredevops_exporter import AzureDevOpsExporter
+from mannf.product.exporters.base import ExportResult, ExportSummary, ExporterPlugin, TestConnectionResult
+from mannf.product.exporters.bugzilla_exporter import BugzillaExporter
+from mannf.product.exporters.github_exporter import GitHubIssuesExporter
+from mannf.product.exporters.gitlab_exporter import GitLabExporter
+from mannf.product.exporters.jira_exporter import JiraExporter
+from mannf.product.exporters.linear_exporter import LinearExporter
+from mannf.product.exporters.pagerduty_exporter import PagerDutyExporter
+from mannf.product.exporters.sentry_exporter import SentryExporter
+from mannf.product.exporters.servicenow_exporter import ServiceNowExporter
+from mannf.product.exporters.shortcut_exporter import ShortcutExporter
+from mannf.product.exporters.webhook_exporter import WebhookExporter
+from mannf.product.exporters.loader import (
+    get_exporter_by_name,
+    load_all_exporters,
+    load_exporters_from_directory,
+    load_exporters_from_entry_points,
+)
+
+# Built-in exporters that are always available without entry-point registration.
+BUILTIN_EXPORTERS: list[ExporterPlugin] = [
+    JiraExporter(),
+    LinearExporter(),
+    GitHubIssuesExporter(),
+    GitLabExporter(),
+    AzureDevOpsExporter(),
+    ShortcutExporter(),
+    ServiceNowExporter(),
+    PagerDutyExporter(),
+    WebhookExporter(),
+    SentryExporter(),
+    BugzillaExporter(),
+]
+
+__all__ = [
+    "ExporterPlugin",
+    "ExportResult",
+    "ExportSummary",
+    "TestConnectionResult",
+    "JiraExporter",
+    "LinearExporter",
+    "GitHubIssuesExporter",
+    "GitLabExporter",
+    "AzureDevOpsExporter",
+    "ShortcutExporter",
+    "ServiceNowExporter",
+    "PagerDutyExporter",
+    "WebhookExporter",
+    "SentryExporter",
+    "BugzillaExporter",
+    "BUILTIN_EXPORTERS",
+    "load_all_exporters",
+    "load_exporters_from_directory",
+    "load_exporters_from_entry_points",
+    "get_exporter_by_name",
+]