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

langchain_agentx/__init__.py

@@ -0,0 +1,46 @@
+"""
+LangChain-based agent utilities for CodeBaseX.
+
+This package provides:
+- LangChain-AgentX LangGraph agent factory (`loop`)
+
+Typical usage:
+
+```python
+from langchain_agentx import create_loop_agent
+```
+"""
+
+__version__ = "0.1.0"
+
+from .loop import (  # noqa: F401
+    create_loop_agent,
+)
+
+from .observability import (  # noqa: F401
+    EventAdapterState,
+    LangchainAgentEvent,
+    LangchainAgentEventType,
+    LangGraphToLangchainAgentEventAdapter,
+    TraceCollector,
+    TraceSession,
+    TraceSpan,
+)
+from .provider import CompatibleChatOpenAI  # noqa: F401
+from .session import AgentSession, create_agent_session  # noqa: F401
+from .workflow import BaseWorkflow  # noqa: F401
+
+__all__ = [
+    "create_loop_agent",
+    "create_agent_session",
+    "AgentSession",
+    "BaseWorkflow",
+    "EventAdapterState",
+    "LangchainAgentEvent",
+    "LangchainAgentEventType",
+    "LangGraphToLangchainAgentEventAdapter",
+    "TraceCollector",
+    "TraceSession",
+    "TraceSpan",
+    "CompatibleChatOpenAI",
+]

langchain_agentx/command/__init__.py

@@ -0,0 +1,28 @@
+"""
+command/__init__.py — 命令子系统公共导出。
+
+职责：
+    暴露 command 子系统核心类型、注册表与调度器。
+
+链路位置：
+    由 session 层与上层应用统一 import 使用。
+
+当前裁剪范围：
+    仅导出 P1 落地必需对象。
+"""
+
+from .context import CommandContext
+from .dispatcher import CommandDispatcher
+from .registry import CommandRegistry
+from .result import CommandResult
+from .types import CommandDefinition, CommandType
+
+__all__ = [
+    "CommandContext",
+    "CommandDefinition",
+    "CommandDispatcher",
+    "CommandRegistry",
+    "CommandResult",
+    "CommandType",
+]
+

langchain_agentx/command/builtin/__init__.py

@@ -0,0 +1,25 @@
+"""
+command/builtin/__init__.py — 内置命令工厂导出。
+
+职责：
+    汇总 builtin 命令定义工厂，供 Session 初始化注册时调用。
+
+链路位置：
+    被 session/agent_session.py 与 session/conversation_session.py 依赖。
+
+当前裁剪范围：
+    仅导出 P1 阶段四个内置命令。
+"""
+
+from .clear import make_clear_command
+from .compact import make_compact_command
+from .memory import make_memory_command
+from .reload_plugins import make_reload_plugins_command
+
+__all__ = [
+    "make_clear_command",
+    "make_compact_command",
+    "make_memory_command",
+    "make_reload_plugins_command",
+]
+

langchain_agentx/command/builtin/clear.py

@@ -0,0 +1,33 @@
+"""
+command/builtin/clear.py — 内置 /clear 命令。
+
+职责：
+    触发 Session.clear_context()，清空当前会话上下文。
+
+链路位置：
+    由 CommandRegistry 注册，dispatcher 命中后执行。
+
+当前裁剪范围：
+    仅返回本地输出，不附带 UI 交互状态。
+"""
+
+from __future__ import annotations
+
+from ..context import CommandContext
+from ..result import CommandResult
+from ..types import CommandDefinition
+
+
+def _handle_clear(ctx: CommandContext) -> CommandResult:
+    ctx.session.clear_context()
+    return CommandResult(output="会话上下文已清空")
+
+
+def make_clear_command() -> CommandDefinition:
+    return CommandDefinition(
+        name="clear",
+        description="清空当前会话上下文",
+        command_type="local",
+        handler=_handle_clear,
+    )
+

langchain_agentx/command/builtin/compact.py

@@ -0,0 +1,33 @@
+"""
+command/builtin/compact.py — 内置 /compact 命令。
+
+职责：
+    调用 Session.compact_context() 并返回压缩前后统计。
+
+链路位置：
+    由 CommandRegistry 注册，作为 local 命令执行。
+
+当前裁剪范围：
+    仅输出 token 粗估统计，不暴露阶段级 compaction meta。
+"""
+
+from __future__ import annotations
+
+from ..context import CommandContext
+from ..result import CommandResult
+from ..types import CommandDefinition
+
+
+async def _handle_compact(ctx: CommandContext) -> CommandResult:
+    before, after = await ctx.session.compact_context()
+    return CommandResult(output=f"上下文已压缩：{before} -> {after} tokens")
+
+
+def make_compact_command() -> CommandDefinition:
+    return CommandDefinition(
+        name="compact",
+        description="压缩当前会话上下文",
+        command_type="local",
+        handler=_handle_compact,
+    )
+

langchain_agentx/command/builtin/memory.py

@@ -0,0 +1,37 @@
+"""
+command/builtin/memory.py — 内置 /memory 命令。
+
+职责：
+    读取 args 子命令并调用 Session.get_memory_summary()。
+
+链路位置：
+    由 CommandRegistry 注册，dispatcher 通过 context.extra 传入 args。
+
+当前裁剪范围：
+    支持 show(默认)/clear，输出文本由 Session API 统一生成。
+"""
+
+from __future__ import annotations
+
+from ..context import CommandContext
+from ..result import CommandResult
+from ..types import CommandDefinition
+
+
+def _handle_memory(ctx: CommandContext) -> CommandResult:
+    args = str(ctx.extra.get("args", "")).strip().lower()
+    sub_cmd = args if args else "show"
+    if sub_cmd not in {"show", "clear"}:
+        return CommandResult(error=f"[command/execute] invalid /memory sub-command: {sub_cmd}")
+    output = ctx.session.get_memory_summary(sub_cmd=sub_cmd)
+    return CommandResult(output=output)
+
+
+def make_memory_command() -> CommandDefinition:
+    return CommandDefinition(
+        name="memory",
+        description="查看或清理会话记忆摘要",
+        command_type="local",
+        handler=_handle_memory,
+    )
+

langchain_agentx/command/builtin/reload_plugins.py

@@ -0,0 +1,42 @@
+"""
+command/builtin/reload_plugins.py — 内置 /reload-plugins 命令。
+
+职责：
+    触发 Session.reload_plugins() 并返回加载摘要。
+
+链路位置：
+    由 CommandRegistry 注册，命中后走 local 异步执行。
+
+当前裁剪范围：
+    输出成功/失败计数，不展开逐条错误详情。
+"""
+
+from __future__ import annotations
+
+from ..context import CommandContext
+from ..result import CommandResult
+from ..types import CommandDefinition
+
+
+async def _handle_reload_plugins(ctx: CommandContext) -> CommandResult:
+    if ctx.plugin_loader is None:
+        return CommandResult(output="Plugin 系统未启用")
+    result = await ctx.session.reload_plugins()
+    if result.errors:
+        return CommandResult(
+            output=(
+                f"插件重载完成（{len(result.enabled)} 个成功，"
+                f"{len(result.errors)} 个错误）"
+            )
+        )
+    return CommandResult(output=f"插件重载完成：{len(result.enabled)} 个插件已加载")
+
+
+def make_reload_plugins_command() -> CommandDefinition:
+    return CommandDefinition(
+        name="reload-plugins",
+        description="热重载插件并刷新命令/技能注册",
+        command_type="local",
+        handler=_handle_reload_plugins,
+    )
+

langchain_agentx/command/context.py

@@ -0,0 +1,30 @@
+"""
+command/context.py — 命令执行上下文。
+
+职责：
+    为命令 handler 提供 Session API、workspace 与插件重载所需依赖。
+
+链路位置：
+    由 Session 在 dispatch 前构造，贯穿单次命令执行。
+
+当前裁剪范围：
+    以 session 注入为主，不暴露内部消息容器引用。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..workspace.config import AgentWorkspaceConfig
+
+
+@dataclass
+class CommandContext:
+    session_id: str
+    session: Any
+    workspace_cfg: AgentWorkspaceConfig
+    hook_engine: Any | None = None
+    plugin_loader: Any | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+

langchain_agentx/command/dispatcher.py

@@ -0,0 +1,183 @@
+"""
+command/dispatcher.py — 用户输入命令分流与执行器。
+
+职责：
+    解析 slash 输入、查找命令、执行 local/prompt 分派并返回 CommandResult。
+
+链路位置：
+    位于 Session 用户输入入口与 loop 调用之间，属于 loop 上游控制层。
+
+当前裁剪范围：
+    当前阶段只处理内置命令与普通 prompt，不处理 CLI local-tui 语义。
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from pathlib import Path
+
+from .context import CommandContext
+from .registry import CommandRegistry
+from .result import CommandResult
+from .types import CommandDefinition
+from ..plugin.registries import CommandEntry, CommandRegistry as PluginCommandRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class CommandDispatcher:
+    def __init__(
+        self,
+        registry: CommandRegistry,
+        plugin_command_registry: PluginCommandRegistry | None = None,
+    ) -> None:
+        self._registry = registry
+        self._plugin_registry = plugin_command_registry
+        self._plugin_markdown_cache: dict[Path, tuple[int, tuple[str, str]]] = {}
+
+    def is_slash_command(self, user_input: str) -> bool:
+        return user_input.strip().startswith("/")
+
+    async def dispatch(self, user_input: str, context: CommandContext) -> CommandResult:
+        stripped = user_input.strip()
+        if not stripped.startswith("/"):
+            return CommandResult(should_query=True)
+
+        name, args = self._parse(stripped)
+        if not name:
+            return CommandResult(error=self._format_error("parse", "command must be `/name [args]`"))
+        command = self._registry.find(name)
+        if command is None:
+            command, lookup_error = self._find_plugin_command(name)
+            if lookup_error is not None:
+                return CommandResult(error=self._format_error("lookup", lookup_error))
+        if command is None:
+            return CommandResult(error=self._format_error("lookup", f"unknown command: /{name}"))
+        if not command.user_invocable:
+            return CommandResult(
+                error=self._format_error("permission", f"/{command.name} is not user-invocable")
+            )
+        if bool(context.extra.get("is_remote")) and not command.remote_safe:
+            return CommandResult(
+                error=self._format_error("permission", f"/{command.name} is not remote-safe")
+            )
+
+        context.extra["args"] = args
+        return await self._execute(command, args, context)
+
+    def _parse(self, slash_input: str) -> tuple[str, str]:
+        body = slash_input[1:]
+        parts = body.split(None, 1)
+        if not parts:
+            return "", ""
+        name = parts[0].lower()
+        args = parts[1].strip() if len(parts) > 1 else ""
+        return name, args
+
+    async def _execute(
+        self,
+        command: CommandDefinition,
+        args: str,
+        context: CommandContext,
+    ) -> CommandResult:
+        if command.command_type == "prompt":
+            return self._execute_prompt(command, args)
+        return await self._execute_local(command, context)
+
+    async def _execute_local(
+        self,
+        command: CommandDefinition,
+        context: CommandContext,
+    ) -> CommandResult:
+        if command.handler is None:
+            return CommandResult(error=self._format_error("execute", f"/{command.name}: handler not set"))
+        try:
+            result = command.handler(context)
+            if inspect.isawaitable(result):
+                result = await result
+            if not isinstance(result, CommandResult):
+                return CommandResult(
+                    error=self._format_error(
+                        "execute",
+                        f"/{command.name}: handler returned unexpected type",
+                    )
+                )
+            return result
+        except Exception as exc:  # pragma: no cover - defensive path
+            logger.error("command /%s execution failed: %s", command.name, exc, exc_info=True)
+            return CommandResult(error=self._format_error("execute", f"/{command.name} failed: {exc}"))
+
+    @staticmethod
+    def _execute_prompt(command: CommandDefinition, args: str) -> CommandResult:
+        if command.prompt_template is None:
+            return CommandResult(
+                error=CommandDispatcher._format_error(
+                    "execute",
+                    f"/{command.name}: prompt_template not set",
+                )
+            )
+        rendered = command.prompt_template.replace("{args}", args)
+        return CommandResult(should_query=True, injected_prompt=rendered)
+
+    def _find_plugin_command(
+        self,
+        name: str,
+    ) -> tuple[CommandDefinition | None, str | None]:
+        if self._plugin_registry is None or not name:
+            return None, None
+        all_entries = list(self._plugin_registry.list_all())
+        # 先匹配完整 key（/plugin@local:cmd）以规避短名冲突歧义。
+        exact_matches = [item for item in all_entries if item.key == name]
+        if len(exact_matches) == 1:
+            return self._entry_to_definition(exact_matches[0]), None
+        same_short_name = [item for item in all_entries if item.name == name]
+        if len(same_short_name) == 1:
+            return self._entry_to_definition(same_short_name[0]), None
+        if len(same_short_name) > 1:
+            candidates = ", ".join(f"/{item.key}" for item in same_short_name)
+            return None, f"unknown command: /{name} (ambiguous plugin command: {candidates})"
+        return None, None
+
+    @staticmethod
+    def _format_error(error_type: str, detail: str) -> str:
+        return f"[command/{error_type}] {detail}"
+
+    def _entry_to_definition(self, entry: CommandEntry) -> CommandDefinition:
+        prompt_template, description = self._load_md(entry.path)
+        return CommandDefinition(
+            name=entry.name,
+            description=description or f"Plugin command from {entry.plugin_source}",
+            command_type="prompt",
+            prompt_template=prompt_template,
+            source=entry.plugin_source,
+        )
+
+    @staticmethod
+    def _parse_markdown(text: str) -> tuple[str, str]:
+        description = ""
+        body = text
+        if text.startswith("---"):
+            parts = text.split("---", 2)
+            if len(parts) == 3:
+                frontmatter = parts[1]
+                body = parts[2]
+                for line in frontmatter.splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("description:"):
+                        description = stripped[len("description:") :].strip().strip("'\"")
+                        break
+        return body.strip(), description
+
+    def _load_md(self, path: Path) -> tuple[str, str]:
+        stat = path.stat()
+        current_mtime_ns = stat.st_mtime_ns
+        cached = self._plugin_markdown_cache.get(path)
+        if cached is not None and cached[0] == current_mtime_ns:
+            return cached[1]
+
+        text = path.read_text(encoding="utf-8")
+        parsed = self._parse_markdown(text)
+        self._plugin_markdown_cache[path] = (current_mtime_ns, parsed)
+        return parsed
+

langchain_agentx/command/registry.py

@@ -0,0 +1,110 @@
+"""
+command/registry.py — 统一命令注册表。
+
+职责：
+    管理命令注册、冲突检测、别名查找与来源批量注销。
+
+链路位置：
+    由 Session 初始化并注入 dispatcher，作为命令发现入口。
+
+当前裁剪范围：
+    本阶段仅注册内置命令；register_plugin 接口已预留。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from .types import CommandDefinition
+
+
+class CommandRegistry:
+    """统一命令注册表。"""
+
+    def __init__(self) -> None:
+        self._commands: dict[str, CommandDefinition] = {}
+        self._alias_to_name: dict[str, str] = {}
+        self._by_source: dict[str, set[str]] = {}
+
+    def register(self, command: CommandDefinition) -> None:
+        normalized_name = self._normalize(command.name)
+        if normalized_name in self._commands:
+            raise ValueError(f"duplicate command name: {normalized_name}")
+        self._ensure_aliases_available(command.aliases)
+        self._commands[normalized_name] = command
+        self._by_source.setdefault(command.source, set()).add(normalized_name)
+        for alias in command.aliases:
+            self._alias_to_name[self._normalize(alias)] = normalized_name
+
+    def register_plugin(
+        self,
+        commands: Iterable[CommandDefinition],
+        *,
+        plugin_source: str,
+    ) -> None:
+        for command in commands:
+            if command.source != plugin_source:
+                command = CommandDefinition(
+                    name=command.name,
+                    description=command.description,
+                    command_type=command.command_type,
+                    handler=command.handler,
+                    prompt_template=command.prompt_template,
+                    aliases=command.aliases,
+                    user_invocable=command.user_invocable,
+                    source=plugin_source,
+                )
+            self.register(command)
+
+    def unregister_plugin(self, plugin_source: str) -> None:
+        names = self._by_source.pop(plugin_source, set())
+        for name in names:
+            command = self._commands.pop(name, None)
+            if command is None:
+                continue
+            for alias in command.aliases:
+                self._alias_to_name.pop(self._normalize(alias), None)
+
+    def find(self, name: str) -> CommandDefinition | None:
+        normalized = self._normalize(name)
+        command = self._commands.get(normalized)
+        if command is not None:
+            return command
+        mapped_name = self._alias_to_name.get(normalized)
+        if mapped_name is None:
+            return None
+        return self._commands.get(mapped_name)
+
+    def list_all(self, *, include_non_user_invocable: bool = True) -> list[CommandDefinition]:
+        commands = list(self._commands.values())
+        if include_non_user_invocable:
+            return commands
+        return [cmd for cmd in commands if cmd.user_invocable]
+
+    def list_for_help(self) -> list[dict[str, object]]:
+        items: list[dict[str, object]] = []
+        for command in self.list_all(include_non_user_invocable=False):
+            items.append(
+                {
+                    "name": command.name,
+                    "description": command.description,
+                    "aliases": command.aliases,
+                    "source": command.source,
+                    "command_type": command.command_type,
+                }
+            )
+        items.sort(key=lambda item: str(item["name"]))
+        return items
+
+    @staticmethod
+    def _normalize(name: str) -> str:
+        return name.strip().lower()
+
+    def _ensure_aliases_available(self, aliases: tuple[str, ...]) -> None:
+        for alias in aliases:
+            normalized = self._normalize(alias)
+            if normalized in self._commands:
+                raise ValueError(f"alias conflicts with command name: {normalized}")
+            if normalized in self._alias_to_name:
+                raise ValueError(f"duplicate alias: {normalized}")
+

langchain_agentx/command/result.py

@@ -0,0 +1,25 @@
+"""
+command/result.py — 命令分发执行结果模型。
+
+职责：
+    统一表达命令分发后的去向（是否进入 loop）与可见输出/错误。
+
+链路位置：
+    由 dispatcher 返回给 Session/调用方，用于决定后续控制流。
+
+当前裁剪范围：
+    仅保留 P0/P1 所需字段；不包含 UI 渲染细节。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CommandResult:
+    should_query: bool = False
+    output: str | None = None
+    injected_prompt: str | None = None
+    error: str | None = None
+

langchain_agentx/command/types.py

@@ -0,0 +1,41 @@
+"""
+command/types.py — 命令定义与类型约束。
+
+职责：
+    定义命令类型枚举与 CommandDefinition，不承载调度逻辑。
+
+链路位置：
+    由 registry/dispatcher/session 共同依赖，作为命令子系统的数据契约层。
+
+当前裁剪范围：
+    仅覆盖 local/prompt 两类框架命令，不包含 CLI local-tui 扩展类型。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from .context import CommandContext
+    from .result import CommandResult
+
+CommandType = Literal["local", "prompt"]
+CommandHandler = Callable[
+    ["CommandContext"], "CommandResult | Awaitable[CommandResult]"
+]
+
+
+@dataclass(frozen=True)
+class CommandDefinition:
+    name: str
+    description: str
+    command_type: CommandType
+    handler: CommandHandler | None = None
+    prompt_template: str | None = None
+    aliases: tuple[str, ...] = field(default_factory=tuple)
+    user_invocable: bool = True
+    remote_safe: bool = True
+    source: str = "builtin"
+

langchain_agentx/config/__init__.py

@@ -0,0 +1,14 @@
+"""langchain_agentx/config — SDK 内置配置资源（随包发布）。
+
+职责：
+    存放内置的、可被外部覆盖的参数表与基线配置资源（例如 model_profiles.yaml）。
+
+链路位置：
+    provider/model_profile.py 通过包内路径读取内置 yaml。
+
+当前裁剪范围：
+    本包不负责 env/.env 加载，也不提供动态热重载能力。
+"""
+
+__all__ = []
+