langchain-agentx-python 0.6.5__tar.gz → 0.7.1__tar.gz

{langchain-agentx-python-0.6.5 → langchain-agentx-python-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.6.5
+Version: 0.7.1
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.6.5 → langchain-agentx-python-0.7.1}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "0.6.5"
+__version__ = "0.7.1"
 
 from .loop import (  # noqa: F401
     create_loop_agent,
@@ -35,6 +35,7 @@ from .observability import (  # noqa: F401
 )
 from .provider import CompatibleChatOpenAI  # noqa: F401
 from .session import AgentSession, create_agent_session  # noqa: F401
+from .health import HealthCheck, HealthReport, PreflightResult, preflight, sdk_health  # noqa: F401
 from .workflow import BaseWorkflow  # noqa: F401
 
 __all__ = [
@@ -55,4 +56,9 @@ __all__ = [
     "TraceSession",
     "TraceSpan",
     "CompatibleChatOpenAI",
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
 ]

langchain-agentx-python-0.7.1/langchain_agentx/health/__init__.py

@@ -0,0 +1,53 @@
+"""
+health/ — L6 启动期健康检查（sdk_health / preflight）
+
+职责：
+    结构化 HealthReport 供 CLI agentx doctor 消费；检查逻辑 SSOT 在 SDK，CLI 仅渲染。
+
+链路位置：
+    启动 / doctor 命令 → sdk_health() / preflight()
+
+当前裁剪范围：
+    本地环境 + 可选网络 preflight；不含运行期 observability 采集。
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from .checks import HealthCheckContext, HealthCoordinator, default_health_checkers
+from .models import HealthCheck, HealthReport, PreflightResult
+from .preflight import preflight
+
+__all__ = [
+    "HealthCheck",
+    "HealthReport",
+    "PreflightResult",
+    "preflight",
+    "sdk_health",
+]
+
+
+def sdk_health(
+    workspace_root: str | Path | None = None,
+    agent_home: str | None = None,
+    *,
+    quick: bool = False,
+    coordinator: HealthCoordinator | None = None,
+) -> HealthReport:
+    """运行 L6 健康检查；quick=True 跳过外部命令探测（预算 < 50ms）。"""
+    ctx = HealthCheckContext(
+        workspace_root=workspace_root,
+        agent_home=agent_home,
+        quick=quick,
+    )
+    runner = coordinator or HealthCoordinator()
+    checks = runner.run(ctx)
+    from .checks import _module_sdk_version
+
+    return HealthReport(
+        checks=checks,
+        sdk_version=_module_sdk_version(),
+        timestamp=time.time(),
+    )

langchain-agentx-python-0.7.1/langchain_agentx/health/checks.py

@@ -0,0 +1,569 @@
+"""
+health/checks.py — L6 健康检查协作者（OOP checker 分层）
+
+职责：
+    HealthChecker 基类 + Runtime / Workspace / ExternalCommand / Provider / Config 子类；
+    每条返回 HealthCheck(name, status, detail, hint)。
+
+链路位置：
+    sdk_health() → HealthCoordinator → 各 HealthChecker.run()
+
+当前裁剪范围：
+    启动期本地/轻量探测；网络可达性由 preflight.py 负责。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version as pkg_version
+from pathlib import Path
+from typing import Protocol
+
+from langchain_agentx.provider.env import get_env_first
+from langchain_agentx.provider.model_profile import ModelProfileRegistry
+from langchain_agentx.utils.host_platform import HostPlatform, get_host_platform
+from langchain_agentx.utils.rg_executable import default_rg_executable
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .models import HealthCheck
+
+MIN_PYTHON = (3, 11)
+EXPECTED_VENV_NAME = "langchain_agentx_venv"
+
+
+def _module_sdk_version() -> str:
+    init = Path(__file__).resolve().parents[1] / "__init__.py"
+    for line in init.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if stripped.startswith("__version__"):
+            return stripped.split("=", 1)[1].strip().strip('"').strip("'")
+    return "0.0.0"
+
+
+class CommandLocator(Protocol):
+    def locate(self, name: str) -> str | None: ...
+
+
+@dataclass
+class HealthCheckContext:
+    workspace_root: str | Path | None
+    agent_home: str | None
+    quick: bool
+
+
+class DefaultCommandLocator:
+    """跨平台可执行文件探测（Windows 优先 where.exe，对齐 A15）。"""
+
+    def __init__(self, *, host_platform: HostPlatform | None = None) -> None:
+        self._host = host_platform or get_host_platform()
+
+    def locate(self, name: str) -> str | None:
+        if self._host == HostPlatform.WINDOWS:
+            return self._locate_windows(name)
+        found = shutil.which(name)
+        return found if found else None
+
+    @staticmethod
+    def _locate_windows(name: str) -> str | None:
+        try:
+            result = subprocess.run(
+                ["where.exe", name],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+        if result.returncode != 0:
+            return None
+        for line in result.stdout.splitlines():
+            candidate = line.strip()
+            if candidate:
+                return candidate
+        return None
+
+
+class HealthChecker(ABC):
+    category: str
+
+    @abstractmethod
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        ...
+
+
+class RuntimeChecker(HealthChecker):
+    category = "runtime"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        del ctx
+        return self._check_python()
+
+    @staticmethod
+    def _check_python() -> HealthCheck:
+        current = sys.version_info[:3]
+        ver_str = f"{current[0]}.{current[1]}.{current[2]}"
+        if current[:2] >= MIN_PYTHON:
+            return HealthCheck(
+                name="python_version",
+                status="ok",
+                detail=f"Python {ver_str}",
+                category="runtime",
+            )
+        return HealthCheck(
+            name="python_version",
+            status="fail",
+            detail=f"Python {ver_str}",
+            hint=f"升级 Python；当前 {ver_str}，需要 ≥ 3.11",
+            category="runtime",
+        )
+
+
+class SdkVersionChecker(HealthChecker):
+    category = "runtime"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        del ctx
+        installed = _module_sdk_version()
+        try:
+            dist_ver = pkg_version("langchain-agentx-python")
+        except PackageNotFoundError:
+            return HealthCheck(
+                name="sdk_version",
+                status="warn",
+                detail=f"package __version__={installed}",
+                hint="pip install -e . 重新装载 SDK",
+                category="runtime",
+            )
+        if dist_ver == installed:
+            return HealthCheck(
+                name="sdk_version",
+                status="ok",
+                detail=f"v{installed}",
+                category="runtime",
+            )
+        return HealthCheck(
+            name="sdk_version",
+            status="warn",
+            detail=f"installed={dist_ver}, __version__={installed}",
+            hint="pip install -e . 重新装载",
+            category="runtime",
+        )
+
+
+class VenvChecker(HealthChecker):
+    category = "runtime"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        del ctx
+        in_venv = sys.prefix != sys.base_prefix
+        virtual_env = os.environ.get("VIRTUAL_ENV")
+        if in_venv:
+            detail = virtual_env or sys.prefix
+            return HealthCheck(
+                name="venv",
+                status="ok",
+                detail=detail,
+                category="runtime",
+            )
+        return HealthCheck(
+            name="venv",
+            status="warn",
+            detail="未检测到激活的 virtualenv",
+            hint=f"激活 {EXPECTED_VENV_NAME}（source ~/langchain_agentx_venv/bin/activate）",
+            category="runtime",
+        )
+
+
+class WorkspaceChecker(HealthChecker):
+    category = "workspace"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        try:
+            cfg = resolve_agent_workspace_config(
+                workspace_root=ctx.workspace_root,
+                agent_home=ctx.agent_home,
+            )
+        except Exception as exc:
+            return HealthCheck(
+                name="workspace_root",
+                status="fail",
+                detail=str(exc),
+                hint="检查 workspace_root / agent_home 配置",
+                category="workspace",
+            )
+        root = cfg.workspace_root
+        if not root.exists():
+            return HealthCheck(
+                name="workspace_root",
+                status="fail",
+                detail=f"路径不存在: {root}",
+                hint="chmod +w 或换路径",
+                category="workspace",
+            )
+        if not os.access(root, os.W_OK):
+            return HealthCheck(
+                name="workspace_root",
+                status="fail",
+                detail=f"不可写: {root}",
+                hint="chmod +w 或换路径",
+                category="workspace",
+            )
+        return HealthCheck(
+            name="workspace_root",
+            status="ok",
+            detail=str(root),
+            category="workspace",
+        )
+
+
+class AgentHomeChecker(HealthChecker):
+    category = "workspace"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        try:
+            cfg = resolve_agent_workspace_config(
+                workspace_root=ctx.workspace_root,
+                agent_home=ctx.agent_home,
+            )
+        except Exception as exc:
+            return HealthCheck(
+                name="agent_home",
+                status="fail",
+                detail=str(exc),
+                hint="显式传 agent_home，不要依赖目录扫描",
+                category="workspace",
+            )
+        return HealthCheck(
+            name="agent_home",
+            status="ok",
+            detail=f"{cfg.agent_home} → {cfg.agent_home_dir}",
+            category="workspace",
+        )
+
+
+class DatabasePathsChecker(HealthChecker):
+    category = "workspace"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        try:
+            cfg = resolve_agent_workspace_config(
+                workspace_root=ctx.workspace_root,
+                agent_home=ctx.agent_home,
+            )
+        except Exception as exc:
+            return HealthCheck(
+                name="database_paths",
+                status="fail",
+                detail=str(exc),
+                hint="清理或换路径",
+                category="workspace",
+            )
+        db_dir = cfg.db_dir
+        try:
+            db_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            return HealthCheck(
+                name="database_paths",
+                status="fail",
+                detail=f"无法创建 db 目录: {exc}",
+                hint="清理或换路径",
+                category="workspace",
+            )
+        if not os.access(db_dir, os.W_OK):
+            return HealthCheck(
+                name="database_paths",
+                status="fail",
+                detail=f"db 目录不可写: {db_dir}",
+                hint="清理或换路径",
+                category="workspace",
+            )
+        traces = db_dir / "traces.db"
+        task_db = db_dir / "task_runtime.db"
+        return HealthCheck(
+            name="database_paths",
+            status="ok",
+            detail=f"traces={traces.name}, task_runtime={task_db.name} under {db_dir}",
+            category="workspace",
+        )
+
+
+class ExternalCommandChecker(HealthChecker):
+    category = "external"
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        executable: str,
+        hint: str,
+        locator: CommandLocator | None = None,
+    ) -> None:
+        self._check_name = name
+        self._executable = executable
+        self._hint = hint
+        self._locator = locator or DefaultCommandLocator()
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        if ctx.quick:
+            return HealthCheck(
+                name=self._check_name,
+                status="skip",
+                detail="quick 模式跳过外部命令探测",
+                category="external",
+            )
+        found = self._locator.locate(self._executable)
+        if found:
+            return HealthCheck(
+                name=self._check_name,
+                status="ok",
+                detail=found,
+                category="external",
+            )
+        return HealthCheck(
+            name=self._check_name,
+            status="warn",
+            detail=f"{self._executable} 不在 PATH",
+            hint=self._hint,
+            category="external",
+        )
+
+
+class ShellChecker(HealthChecker):
+    category = "external"
+
+    def __init__(self, *, locator: CommandLocator | None = None) -> None:
+        self._locator = locator or DefaultCommandLocator()
+        self._host = get_host_platform()
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        if ctx.quick:
+            return HealthCheck(
+                name="shell",
+                status="skip",
+                detail="quick 模式跳过 shell 探测",
+                category="external",
+            )
+        if self._host == HostPlatform.WINDOWS:
+            bash = self._locator.locate("bash")
+            pwsh = self._locator.locate("pwsh")
+            if bash or pwsh:
+                parts = []
+                if bash:
+                    parts.append(f"bash={bash}")
+                if pwsh:
+                    parts.append(f"pwsh={pwsh}")
+                return HealthCheck(
+                    name="shell",
+                    status="ok",
+                    detail="; ".join(parts),
+                    category="external",
+                )
+            return HealthCheck(
+                name="shell",
+                status="warn",
+                detail="未找到 bash 或 pwsh",
+                hint="安装 Git for Windows（bash）或 PowerShell 7（pwsh）",
+                category="external",
+            )
+        bash = self._locator.locate("bash")
+        if bash:
+            return HealthCheck(
+                name="shell",
+                status="ok",
+                detail=bash,
+                category="external",
+            )
+        return HealthCheck(
+            name="shell",
+            status="warn",
+            detail="bash 不在 PATH",
+            hint="安装 bash 并加入 PATH",
+            category="external",
+        )
+
+
+class ProviderApiKeyChecker(HealthChecker):
+    category = "provider"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        del ctx
+        key = get_env_first(
+            "LANGCHAIN_AGENTX_OPENAI_API_KEY",
+            "OPENAI_API_KEY",
+        )
+        if key:
+            return HealthCheck(
+                name="openai_api_key",
+                status="ok",
+                detail="OPENAI_API_KEY 已设置",
+                category="provider",
+            )
+        return HealthCheck(
+            name="openai_api_key",
+            status="fail",
+            detail="未检测到 OPENAI_API_KEY",
+            hint="设置 OPENAI_API_KEY 或 LANGCHAIN_AGENTX_OPENAI_API_KEY（勿在日志中打印值）",
+            category="provider",
+        )
+
+
+class ProviderModelChecker(HealthChecker):
+    category = "provider"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        model = get_env_first("LANGCHAIN_AGENTX_MODEL") or "gpt-4o-mini"
+        try:
+            cfg = resolve_agent_workspace_config(
+                workspace_root=ctx.workspace_root,
+                agent_home=ctx.agent_home,
+            )
+            registry = ModelProfileRegistry.from_files(agent_home_dir=cfg.agent_home_dir)
+        except Exception as exc:
+            return HealthCheck(
+                name="provider_model",
+                status="warn",
+                detail=f"模型配置加载失败: {exc}",
+                hint="检查 model_profiles.yaml",
+                category="provider",
+            )
+        if _model_has_explicit_profile(registry, model):
+            return HealthCheck(
+                name="provider_model",
+                status="ok",
+                detail=model,
+                category="provider",
+            )
+        return HealthCheck(
+            name="provider_model",
+            status="warn",
+            detail=f"unknown model: {model}",
+            hint="在 model_profiles.yaml 中添加模型前缀或更换 LANGCHAIN_AGENTX_MODEL",
+            category="provider",
+        )
+
+
+class ConfigChecker(HealthChecker):
+    category = "config"
+
+    def run(self, ctx: HealthCheckContext) -> HealthCheck:
+        try:
+            cfg = resolve_agent_workspace_config(
+                workspace_root=ctx.workspace_root,
+                agent_home=ctx.agent_home,
+            )
+        except Exception as exc:
+            return HealthCheck(
+                name="tool_runtime_config",
+                status="fail",
+                detail=str(exc),
+                category="config",
+            )
+        config_path = cfg.tool_runtime_config_path
+        if not config_path.is_file():
+            return HealthCheck(
+                name="tool_runtime_config",
+                status="ok",
+                detail="配置文件不存在（使用默认）",
+                category="config",
+            )
+        try:
+            raw_text = config_path.read_text(encoding="utf-8")
+            parsed = json.loads(raw_text)
+        except json.JSONDecodeError as exc:
+            return HealthCheck(
+                name="tool_runtime_config",
+                status="fail",
+                detail=f"JSON 解析错误 行 {exc.lineno}: {exc.msg}",
+                hint="修复 tool_runtime_config.json 语法",
+                category="config",
+            )
+        except OSError as exc:
+            return HealthCheck(
+                name="tool_runtime_config",
+                status="fail",
+                detail=str(exc),
+                category="config",
+            )
+        if not isinstance(parsed, dict):
+            return HealthCheck(
+                name="tool_runtime_config",
+                status="fail",
+                detail="根节点必须是 JSON object",
+                category="config",
+            )
+        return HealthCheck(
+            name="tool_runtime_config",
+            status="ok",
+            detail=str(config_path),
+            category="config",
+        )
+
+
+def _model_has_explicit_profile(registry: ModelProfileRegistry, model_id: str) -> bool:
+    for profile in registry.profiles.values():
+        if model_id.startswith(profile.model_id_prefix):
+            return True
+    return False
+
+
+class HealthCoordinator:
+    """编排各 HealthChecker，产出 HealthReport。"""
+
+    def __init__(self, checkers: list[HealthChecker] | None = None) -> None:
+        self._checkers = checkers if checkers is not None else default_health_checkers()
+
+    def run(self, ctx: HealthCheckContext) -> list[HealthCheck]:
+        return [checker.run(ctx) for checker in self._checkers]
+
+
+def default_health_checkers() -> list[HealthChecker]:
+    rg_exe = default_rg_executable()
+    return [
+        RuntimeChecker(),
+        SdkVersionChecker(),
+        VenvChecker(),
+        WorkspaceChecker(),
+        AgentHomeChecker(),
+        DatabasePathsChecker(),
+        ExternalCommandChecker(
+            name="ripgrep",
+            executable=rg_exe,
+            hint="安装 rg 并将其加入 PATH",
+        ),
+        ExternalCommandChecker(
+            name="git",
+            executable="git",
+            hint="安装 git",
+        ),
+        ShellChecker(),
+        ProviderApiKeyChecker(),
+        ProviderModelChecker(),
+        ConfigChecker(),
+    ]
+
+
+__all__ = [
+    "AgentHomeChecker",
+    "ConfigChecker",
+    "DatabasePathsChecker",
+    "DefaultCommandLocator",
+    "ExternalCommandChecker",
+    "HealthCheckContext",
+    "HealthChecker",
+    "HealthCoordinator",
+    "ProviderApiKeyChecker",
+    "ProviderModelChecker",
+    "RuntimeChecker",
+    "SdkVersionChecker",
+    "ShellChecker",
+    "VenvChecker",
+    "WorkspaceChecker",
+    "default_health_checkers",
+]