langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/plugin/registries.py

@@ -0,0 +1,211 @@
+"""
+plugin/registries.py — Plugin 能力注册表（Skill/Command/Agent）。
+
+职责：
+    管理插件能力索引与按插件来源的批量注销。
+
+链路位置：
+    PluginLoader 注册阶段写入，运行阶段由调用方按 key 查找能力。
+
+当前裁剪范围：
+    仅覆盖 Skill/Command/AgentDefinition；不含 MCP 注册管理。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .types import ComponentLoadFailedError, LoadedPlugin, PluginError
+
+
+@dataclass(frozen=True)
+class SkillEntry:
+    key: str
+    plugin_source: str
+    path: Path
+
+
+@dataclass(frozen=True)
+class CommandEntry:
+    key: str
+    plugin_source: str
+    name: str
+    path: Path
+
+
+@dataclass(frozen=True)
+class AgentDefinitionEntry:
+    key: str
+    plugin_source: str
+    name: str
+    path: Path
+
+
+class SkillRegistry:
+    def __init__(self) -> None:
+        self._skills: dict[str, SkillEntry] = {}
+        self._by_plugin: dict[str, list[str]] = {}
+
+    def register(self, plugin: LoadedPlugin) -> list[PluginError]:
+        if plugin.skills_dir is None or not plugin.skills_dir.exists():
+            self._by_plugin[plugin.source] = []
+            return []
+
+        errors: list[PluginError] = []
+        registered: list[str] = []
+        for skill_dir in sorted(plugin.skills_dir.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            skill_name = skill_dir.name
+            key = f"{plugin.source}:{skill_name}"
+            if key in self._skills:
+                errors.append(
+                    ComponentLoadFailedError(
+                        source=plugin.source,
+                        plugin=plugin.name,
+                        component="skills",
+                        path=str(skill_md),
+                        reason=f"duplicate skill key: {key}",
+                    )
+                )
+                continue
+            self._skills[key] = SkillEntry(key=key, plugin_source=plugin.source, path=skill_md)
+            registered.append(key)
+        self._by_plugin[plugin.source] = registered
+        return errors
+
+    def get(self, key: str) -> SkillEntry | None:
+        if key in self._skills:
+            return self._skills[key]
+        return self._find_by_short_name(key)
+
+    def unregister_plugin(self, plugin_source: str) -> None:
+        for key in self._by_plugin.pop(plugin_source, []):
+            self._skills.pop(key, None)
+
+    def list_all(self) -> list[SkillEntry]:
+        return list(self._skills.values())
+
+    def _find_by_short_name(self, short_name: str) -> SkillEntry | None:
+        matches = [entry for entry in self._skills.values() if entry.key.endswith(f":{short_name}")]
+        return matches[0] if len(matches) == 1 else None
+
+
+class CommandRegistry:
+    def __init__(self) -> None:
+        self._commands: dict[str, CommandEntry] = {}
+        self._by_plugin: dict[str, list[str]] = {}
+
+    def register(self, plugin: LoadedPlugin) -> list[PluginError]:
+        if plugin.commands_dir is None or not plugin.commands_dir.exists():
+            self._by_plugin[plugin.source] = []
+            return []
+
+        errors: list[PluginError] = []
+        registered: list[str] = []
+        for cmd_file in sorted(plugin.commands_dir.glob("*.md")):
+            cmd_name = cmd_file.stem
+            key = f"{plugin.source}:{cmd_name}"
+            if key in self._commands:
+                errors.append(
+                    ComponentLoadFailedError(
+                        source=plugin.source,
+                        plugin=plugin.name,
+                        component="commands",
+                        path=str(cmd_file),
+                        reason=f"duplicate command key: {key}",
+                    )
+                )
+                continue
+            self._commands[key] = CommandEntry(
+                key=key,
+                plugin_source=plugin.source,
+                name=cmd_name,
+                path=cmd_file,
+            )
+            registered.append(key)
+        self._by_plugin[plugin.source] = registered
+        return errors
+
+    def get(self, name: str) -> CommandEntry | None:
+        if name in self._commands:
+            return self._commands[name]
+        return self._find_by_short_name(name)
+
+    def unregister_plugin(self, plugin_source: str) -> None:
+        for key in self._by_plugin.pop(plugin_source, []):
+            self._commands.pop(key, None)
+
+    def list_all(self) -> list[CommandEntry]:
+        return list(self._commands.values())
+
+    def _find_by_short_name(self, short_name: str) -> CommandEntry | None:
+        matches = [entry for entry in self._commands.values() if entry.key.endswith(f":{short_name}")]
+        return matches[0] if len(matches) == 1 else None
+
+
+class AgentRegistry:
+    def __init__(self) -> None:
+        self._agents: dict[str, AgentDefinitionEntry] = {}
+        self._by_plugin: dict[str, list[str]] = {}
+
+    def register(self, plugin: LoadedPlugin) -> list[PluginError]:
+        if plugin.agents_dir is None or not plugin.agents_dir.exists():
+            self._by_plugin[plugin.source] = []
+            return []
+
+        errors: list[PluginError] = []
+        registered: list[str] = []
+        for agent_file in sorted(plugin.agents_dir.glob("*.md")):
+            agent_name = agent_file.stem
+            key = f"{plugin.source}:{agent_name}"
+            if key in self._agents:
+                errors.append(
+                    ComponentLoadFailedError(
+                        source=plugin.source,
+                        plugin=plugin.name,
+                        component="agents",
+                        path=str(agent_file),
+                        reason=f"duplicate agent key: {key}",
+                    )
+                )
+                continue
+            self._agents[key] = AgentDefinitionEntry(
+                key=key,
+                plugin_source=plugin.source,
+                name=agent_name,
+                path=agent_file,
+            )
+            registered.append(key)
+        self._by_plugin[plugin.source] = registered
+        return errors
+
+    def get(self, name: str) -> AgentDefinitionEntry | None:
+        if name in self._agents:
+            return self._agents[name]
+        return self._find_by_short_name(name)
+
+    def unregister_plugin(self, plugin_source: str) -> None:
+        for key in self._by_plugin.pop(plugin_source, []):
+            self._agents.pop(key, None)
+
+    def list_all(self) -> list[AgentDefinitionEntry]:
+        return list(self._agents.values())
+
+    def _find_by_short_name(self, short_name: str) -> AgentDefinitionEntry | None:
+        matches = [entry for entry in self._agents.values() if entry.key.endswith(f":{short_name}")]
+        return matches[0] if len(matches) == 1 else None
+
+
+__all__ = [
+    "AgentDefinitionEntry",
+    "AgentRegistry",
+    "CommandEntry",
+    "CommandRegistry",
+    "SkillEntry",
+    "SkillRegistry",
+]

langchain_agentx/plugin/types.py

@@ -0,0 +1,142 @@
+"""
+plugin/types.py — Plugin 运行时数据类型定义。
+
+职责：
+    定义 LoadedPlugin、PluginError 判别联合与 PluginLoadResult。
+
+链路位置：
+    被 PluginLoader、各 Registry 与容器集成层共享。
+
+当前裁剪范围：
+    仅覆盖 P0/P1 数据类型，不含 MCP/依赖解析相关专用错误类型。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+
+@dataclass
+class LoadedPlugin:
+    """PluginLoader 加载后的运行时表示。"""
+
+    name: str
+    description: str
+    version: str
+    path: str
+    source: str
+    enabled: bool = True
+    is_builtin: bool = False
+    skills_dir: Path | None = None
+    commands_dir: Path | None = None
+    agents_dir: Path | None = None
+    hooks_config: dict[str, Any] | None = None
+    mcp_servers: dict[str, dict[str, Any]] = field(default_factory=dict)
+    dependencies: list[str] = field(default_factory=list)
+    applicable_containers: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ManifestParseError:
+    type: Literal["manifest-parse-error"] = "manifest-parse-error"
+    source: str = ""
+    manifest_path: str = ""
+    parse_error: str = ""
+
+
+@dataclass(frozen=True)
+class ManifestValidationError:
+    type: Literal["manifest-validation-error"] = "manifest-validation-error"
+    source: str = ""
+    manifest_path: str = ""
+    validation_errors: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ComponentLoadFailedError:
+    type: Literal["component-load-failed"] = "component-load-failed"
+    source: str = ""
+    plugin: str = ""
+    component: str = ""
+    path: str = ""
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class HookLoadFailedError:
+    type: Literal["hook-load-failed"] = "hook-load-failed"
+    source: str = ""
+    plugin: str = ""
+    hook_path: str = ""
+    reason: str = ""
+
+
+@dataclass(frozen=True)
+class GenericPluginError:
+    type: Literal["generic-error"] = "generic-error"
+    source: str = ""
+    plugin: str = ""
+    error: str = ""
+
+
+PluginError = (
+    ManifestParseError
+    | ManifestValidationError
+    | ComponentLoadFailedError
+    | HookLoadFailedError
+    | GenericPluginError
+)
+
+
+def get_plugin_error_message(error: PluginError) -> str:
+    """将 PluginError 转换为可日志化消息。"""
+    if isinstance(error, ManifestParseError):
+        return (
+            f"[{error.source}] manifest parse error at {error.manifest_path}: "
+            f"{error.parse_error}"
+        )
+    if isinstance(error, ManifestValidationError):
+        details = ", ".join(error.validation_errors)
+        return (
+            f"[{error.source}] manifest validation error at {error.manifest_path}: "
+            f"{details}"
+        )
+    if isinstance(error, ComponentLoadFailedError):
+        return (
+            f"[{error.source}] {error.component} load failed at {error.path}: "
+            f"{error.reason}"
+        )
+    if isinstance(error, HookLoadFailedError):
+        return f"[{error.source}] hook load failed at {error.hook_path}: {error.reason}"
+    return f"[{error.source}] plugin error: {error.error}"
+
+
+@dataclass
+class PluginLoadResult:
+    """Plugin 加载结果。"""
+
+    enabled: list[LoadedPlugin]
+    errors: list[PluginError]
+
+    @property
+    def has_errors(self) -> bool:
+        return bool(self.errors)
+
+    def log_errors(self, logger: Any) -> None:
+        for error in self.errors:
+            logger.warning("plugin load error: %s", get_plugin_error_message(error))
+
+
+__all__ = [
+    "ComponentLoadFailedError",
+    "GenericPluginError",
+    "HookLoadFailedError",
+    "LoadedPlugin",
+    "ManifestParseError",
+    "ManifestValidationError",
+    "PluginError",
+    "PluginLoadResult",
+    "get_plugin_error_message",
+]

langchain_agentx/provider/__init__.py

@@ -0,0 +1,27 @@
+"""
+Provider layer for langchain_agentx.
+
+职责：
+    对外提供模型 Provider 兼容封装入口。
+
+链路位置：
+    被 examples 与 loop/integration 侧导入，用于构建可替换的 ChatModel。
+
+当前裁剪范围：
+    - CompatibleChatOpenAI（OpenAI 兼容 reasoning_content 透传）
+    - get_chat_openai / get_chat_anthropic（从环境变量构造 ChatModel 的可复用组合件）
+"""
+
+from .anthropic import get_chat_anthropic
+from .compatible_chat_openai import CompatibleChatOpenAI
+from .model_profile import ModelProfile, ModelProfileRegistry
+from .openai import get_chat_openai
+
+__all__ = [
+    "CompatibleChatOpenAI",
+    "get_chat_anthropic",
+    "get_chat_openai",
+    "ModelProfile",
+    "ModelProfileRegistry",
+]
+

langchain_agentx/provider/anthropic.py

@@ -0,0 +1,121 @@
+"""provider/anthropic.py — Anthropic ChatModel 工厂（可复用组合件）。
+
+职责：
+    - 从环境变量读取 Anthropic 配置（auth token/base_url/model）。
+    - 处理部分企业代理环境下 httpx 对 socks:// 的不兼容。
+    - 组装并返回 ChatAnthropic。
+
+约束：
+    - 不加载 .env；由调用方（例如 examples）负责把 .env 注入到环境变量。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from .env import get_env_first, parse_positive_int
+from .model_profile import ModelProfileRegistry
+
+
+def _sanitize_proxy_env_for_anthropic() -> None:
+    """Anthropic/httpx 不接受 socks://，保留 http/https 代理并移除异常 all_proxy。"""
+    for key in ("all_proxy", "ALL_PROXY"):
+        value = os.environ.get(key)
+        if not value:
+            continue
+        if value.strip().lower().startswith("socks://"):
+            os.environ.pop(key, None)
+
+
+def _resolve_claude_max_tokens(explicit: int | None, *, profile_default: int) -> int:
+    if explicit is not None:
+        return int(explicit)
+    override = get_env_first("CLAUDE_MAX_OUTPUT_TOKENS", "CLAUDE_CODE_MAX_OUTPUT_TOKENS")
+    parsed = parse_positive_int(override)
+    return parsed if parsed is not None else profile_default
+
+
+def _is_thinking_enabled(thinking_option: Any) -> bool:
+    if isinstance(thinking_option, bool):
+        return thinking_option
+    if isinstance(thinking_option, dict):
+        enabled = thinking_option.get("enabled")
+        if isinstance(enabled, bool):
+            return enabled
+        return bool(thinking_option)
+    return False
+
+
+def get_chat_anthropic(
+    *,
+    model: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    top_p: float | None = None,
+    streaming: bool = True,
+    model_profile_registry: ModelProfileRegistry | None = None,
+    **kwargs: Any,
+) -> BaseChatModel:
+    from langchain_anthropic import ChatAnthropic  # pyright: ignore[reportMissingImports]
+
+    _sanitize_proxy_env_for_anthropic()
+
+    resolved_api_key = api_key or get_env_first(
+        "LANGCHAIN_AGENTX_ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_AUTH_TOKEN",
+        "ANTHROPIC_API_KEY",
+    )
+    resolved_base_url = base_url or get_env_first(
+        "LANGCHAIN_AGENTX_ANTHROPIC_BASE_URL",
+        "ANTHROPIC_BASE_URL",
+    )
+    resolved_model = (
+        model
+        or get_env_first("LANGCHAIN_AGENTX_ANTHROPIC_MODEL", "ANTHROPIC_MODEL")
+        or "claude-sonnet-4-20250514"
+    )
+    profile = (
+        model_profile_registry.get(resolved_model)
+        if model_profile_registry is not None
+        else ModelProfileRegistry().defaults
+    )
+
+    if not resolved_api_key or not resolved_base_url:
+        raise RuntimeError(
+            "缺少 Anthropic 配置：请设置 ANTHROPIC_AUTH_TOKEN（或 ANTHROPIC_API_KEY /"
+            " LANGCHAIN_AGENTX_ANTHROPIC_AUTH_TOKEN）以及 ANTHROPIC_BASE_URL"
+            "（或 LANGCHAIN_AGENTX_ANTHROPIC_BASE_URL）。默认模型名可通过"
+            " ANTHROPIC_MODEL / LANGCHAIN_AGENTX_ANTHROPIC_MODEL 或 model 参数指定。"
+        )
+
+    resolved_max_tokens = _resolve_claude_max_tokens(
+        max_tokens,
+        profile_default=profile.max_output_tokens,
+    )
+    thinking_enabled = _is_thinking_enabled(kwargs.get("thinking"))
+    resolved_temperature = profile.default_temperature if temperature is None else float(temperature)
+    resolved_top_p = profile.default_top_p if top_p is None else float(top_p)
+    
+    anthropic_kwargs: dict[str, Any] = {
+        "model": resolved_model,
+        "anthropic_api_key": resolved_api_key,
+        "anthropic_api_url": resolved_base_url.rstrip("/"),
+        "max_tokens": resolved_max_tokens,
+        "streaming": streaming,
+        **kwargs,
+    }
+    if resolved_top_p is not None:
+        anthropic_kwargs["top_p"] = resolved_top_p
+    if not thinking_enabled:
+        anthropic_kwargs["temperature"] = resolved_temperature
+
+    return ChatAnthropic(**anthropic_kwargs)
+
+
+__all__ = ["get_chat_anthropic"]
+

langchain_agentx/provider/compatible_chat_openai.py

@@ -0,0 +1,86 @@
+"""
+CompatibleChatOpenAI
+====================
+
+为 **任意 OpenAI 兼容聊天服务** 提供一个轻量级的 LangChain ChatModel 封装，
+在不 fork `langchain-openai` 的前提下：
+
+- 复用官方 `ChatOpenAI` 的绝大部分行为（重试、流式、usage 统计等）
+- 额外把流式响应中的 `reasoning_content` 注入到
+  `AIMessageChunk.additional_kwargs["reasoning_content"]`，让下游组件按
+  LangChain v2 标准路径解析 reasoning。
+- 在组请求体时把历史 ``AIMessage.additional_kwargs["reasoning_content"]`` 写回
+  ``messages[].reasoning_content``（``langchain_openai`` 默认不落该字段）。
+  部分 OpenAI 兼容思考模型要求多轮必须把上一轮 reasoning 原样带回，否则会 400。
+
+与 loop 终局契约：
+    若 HTTP/鉴权等错误在 invoke/ainvoke 阶段以异常抛出，
+    由 model_nodes 统一合成带 response_metadata.langchain_agentx_api_error/error 的 AIMessage。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Type
+
+from langchain_core.language_models import LanguageModelInput
+from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessageChunk
+from langchain_core.outputs import ChatGenerationChunk
+from langchain_openai import ChatOpenAI
+
+
+class CompatibleChatOpenAI(ChatOpenAI):
+    """OpenAI 兼容 ChatModel 封装（支持 reasoning_content）。"""
+
+    def _get_request_payload(
+        self,
+        input_: LanguageModelInput,
+        *,
+        stop: list[str] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """与基类一致，并为 chat/completions 的 assistant 历史补上 ``reasoning_content``。"""
+        lc_messages = self._convert_input(input_).to_messages()
+        payload = super()._get_request_payload(input_, stop=stop, **kwargs)
+        serialized = payload.get("messages")
+        if not isinstance(serialized, list) or len(serialized) != len(lc_messages):
+            return payload
+        for msg_dict, lc_msg in zip(serialized, lc_messages):
+            if not isinstance(lc_msg, AIMessage):
+                continue
+            rc = lc_msg.additional_kwargs.get("reasoning_content")
+            if isinstance(rc, str) and rc:
+                msg_dict["reasoning_content"] = rc
+        return payload
+
+    def _convert_chunk_to_generation_chunk(
+        self,
+        chunk: Dict[str, Any],
+        default_chunk_class: Type[BaseMessageChunk],
+        base_generation_info: Dict[str, Any] | None,
+    ) -> ChatGenerationChunk | None:
+        gen_chunk = super()._convert_chunk_to_generation_chunk(
+            chunk, default_chunk_class, base_generation_info
+        )
+        if gen_chunk is None:
+            return None
+
+        message = gen_chunk.message
+        if not isinstance(message, AIMessageChunk):
+            return gen_chunk
+
+        choices = chunk.get("choices", []) or chunk.get("chunk", {}).get("choices", [])
+        if not choices:
+            return gen_chunk
+
+        delta = choices[0].get("delta") or {}
+        rc = delta.get("reasoning_content")
+        if isinstance(rc, str) and rc:
+            ak = getattr(message, "additional_kwargs", None) or {}
+            ak["reasoning_content"] = rc
+            message.additional_kwargs = ak
+
+        return gen_chunk
+
+
+__all__ = ["CompatibleChatOpenAI"]
+

langchain_agentx/provider/env.py

@@ -0,0 +1,45 @@
+"""provider/env.py — provider 工厂的环境变量解析工具。
+
+职责：
+    为 provider 工厂函数提供一致的 env 读取与布尔/数值解析。
+
+约束：
+    - 只读取 os.environ，不加载 .env（示例层负责）
+"""
+
+from __future__ import annotations
+
+import os
+
+
+def get_env_first(*names: str) -> str | None:
+    for name in names:
+        v = os.environ.get(name)
+        if v and str(v).strip():
+            return str(v).strip()
+    return None
+
+
+def parse_positive_int(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    try:
+        value = int(str(raw).strip())
+    except ValueError:
+        return None
+    return value if value > 0 else None
+
+
+def parse_bool(raw: str | None) -> bool | None:
+    if raw is None:
+        return None
+    v = str(raw).strip().lower()
+    if v in {"1", "true", "yes", "y", "on"}:
+        return True
+    if v in {"0", "false", "no", "n", "off"}:
+        return False
+    return None
+
+
+__all__ = ["get_env_first", "parse_bool", "parse_positive_int"]
+