langchain-agentx-python 0.3.2__tar.gz → 0.3.4__tar.gz

{langchain-agentx-python-0.3.2/langchain_agentx_python.egg-info → langchain-agentx-python-0.3.4}/PKG-INFO

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

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/__init__.py

@@ -20,6 +20,8 @@ from .stages import (
     ToolResultBudgetStage,
 )
 from .types import (
+    CompactProgress,
+    CompactProgressCallback,
     CompactionConfig,
     ContextCompactionContext,
     StageResult,
@@ -40,6 +42,8 @@ __all__ = [
     "active_compaction_settings",
     "AutocompactLlmPromptKind",
     "AutocompactStage",
+    "CompactProgress",
+    "CompactProgressCallback",
     "CompactionBlockingGuard",
     "CompactionConfig",
     "CompactionSettings",

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/compaction_service.py

@@ -11,6 +11,7 @@
 
 注意：
 - 不修改 `should_end` / `finish_reason` 等 exit 字段；只产出 `messages` 增量补丁。
+- `arun` 方法为 async 版本，支持进度回调（供 /compact 命令使用）。
 """
 
 from __future__ import annotations
@@ -19,7 +20,7 @@ from typing import Any, Dict, Mapping
 
 from .pipeline import ContextPipeline
 from .settings import CompactionSettings
-from .types import ContextCompactionContext
+from .types import CompactProgressCallback, ContextCompactionContext
 
 
 class LoopContextCompaction:
@@ -42,6 +43,26 @@ class LoopContextCompaction:
         ctx = ContextCompactionContext.from_state(state, model)
         return self._pipeline.run(state, ctx)
 
+    async def arun(
+        self,
+        state: Mapping[str, Any],
+        model: Any | None = None,
+        progress_callback: CompactProgressCallback = None,
+    ) -> Dict[str, Any]:
+        """Async 版本（供 /compact 命令使用），支持进度回调。
+
+        参数：
+            state: LangGraph state
+            model: 可选的 LLM model（供 autocompact 使用）
+            progress_callback: 进度回调函数，接收 CompactProgress 对象
+
+        返回:
+            与 run() 相同的补丁格式
+        """
+        ctx = ContextCompactionContext.from_state(state, model)
+        ctx.progress_callback = progress_callback
+        return await self._pipeline.arun(state, ctx)
+
 
 _default_loop_context_compaction: LoopContextCompaction | None = None
 

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/pipeline.py

@@ -30,7 +30,7 @@ from .stages import (
     ToolResultBudgetStage,
 )
 from .stages.base import CompactionStage
-from .types import ContextCompactionContext
+from .types import CompactProgress, ContextCompactionContext
 
 
 class DefaultCompactionStages:
@@ -120,6 +120,86 @@ class ContextPipeline:
             return {}
         return patch
 
+    async def arun(
+        self,
+        state: dict[str, Any],
+        ctx: ContextCompactionContext,
+    ) -> dict[str, Any]:
+        """Async 版本：每个 stage 完成后 emit 进度（供 /compact 进度条使用）。
+
+        与 run() 的区别：
+            - 走 async 路径，支持 AutocompactStage 的流式 LLM 调用。
+            - 通过 ctx.progress_callback 回调进度更新。
+        """
+        messages = state.get("messages")
+        if not isinstance(messages, list) or not messages:
+            return {}
+
+        s = self._settings_override or get_active_compaction_settings()
+        estimator = TokenEstimator(num_chars_per_token=s.num_chars_per_token)
+        original_input = list(messages)
+        current = original_input
+        guard = CompactionBlockingGuard(settings=s)
+        tw = guard.calculate_token_warning_state(original_input)
+        tokens_before = estimator.estimate_messages_tokens(original_input)
+        stages_meta: list[dict[str, Any]] = []
+        total_freed = 0
+        n = len(self._stages)
+
+        for i, stage in enumerate(self._stages):
+            if ctx.progress_callback:
+                ctx.progress_callback(
+                    CompactProgress(
+                        stage=stage.name,
+                        stage_index=i,
+                        total_stages=n,
+                        percent=int(i / n * 100),
+                    )
+                )
+            # autocompact 走 async（内部 streaming），其余走 sync
+            sr = await stage.arun(current, ctx)
+            total_freed += sr.tokens_freed
+            stages_meta.append(
+                {
+                    "name": stage.name,
+                    "tokens_freed": sr.tokens_freed,
+                    "extra": dict(sr.extra),
+                }
+            )
+            current = sr.messages
+            ctx.snip_tokens_freed_carry += sr.tokens_freed
+
+        if ctx.progress_callback:
+            ctx.progress_callback(
+                CompactProgress(
+                    stage="done",
+                    stage_index=n,
+                    total_stages=n,
+                    percent=100,
+                )
+            )
+
+        patch: dict[str, Any] = {}
+        if current is not original_input:
+            patch["messages"] = current
+
+        tokens_after = estimator.estimate_messages_tokens(current)
+        if s.emit_compaction_pipeline_meta and (
+            "messages" in patch or total_freed > 0
+        ):
+            patch["compaction_pipeline_meta"] = {
+                "estimated_tokens_before": tokens_before,
+                "estimated_tokens_after": tokens_after,
+                "tokens_freed_sum": total_freed,
+                "snip_tokens_freed_carry_final": ctx.snip_tokens_freed_carry,
+                "token_warning_level": tw.level,
+                "stages": stages_meta,
+            }
+
+        if not patch:
+            return {}
+        return patch
+
 
 __all__ = [
     "ContextPipeline",

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/stages/autocompact.py

@@ -13,6 +13,7 @@ Autocompact 阶段：超阈值时折叠前缀消息（对齐 CC `deps.autocompac
 
 注意：
 - `query_source in autocompact_skip_query_sources`（如 `compact`）时跳过，防递归压缩。
+- `arun()` 方法为 async 版本，支持流式 LLM 调用与进度回调。
 """
 
 from __future__ import annotations
@@ -25,7 +26,7 @@ from ..blocking_guard import CompactionBlockingGuard
 from ..message_utils import stringify_content, total_estimated_tokens_for_messages
 from ...prompt.compact import build_autocompact_llm_instruction_prompt, get_compact_user_summary_message
 from ..settings import CompactionSettings, get_active_compaction_settings
-from ..types import ContextCompactionContext, StageResult
+from ..types import CompactProgress, ContextCompactionContext, StageResult
 from .base import CompactionStage
 
 
@@ -105,6 +106,70 @@ class AutocompactStage(CompactionStage):
             extra={"autocompact_mode": mode, "folded_messages": len(head)},
         )
 
+    async def arun(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        """Async 版本：LLM 摘要使用 astream 流式生成，支持进度回调。"""
+        s = self._effective_settings()
+        if ctx.query_source in s.autocompact_skip_query_sources:
+            return StageResult(messages=messages, tokens_freed=0, extra={"autocompact_skipped": "query_source"})
+
+        total = total_estimated_tokens_for_messages(messages, s.num_chars_per_token)
+        threshold = int(s.default_max_context_tokens * s.default_compress_trigger_fraction)
+        slack = ctx.snip_tokens_freed_carry if s.autocompact_snip_carry_threshold_slack else 0
+        if total <= threshold + slack:
+            return StageResult(messages=messages, tokens_freed=0)
+
+        # 跳过所有 SystemMessages（不保留），对齐 SystemMessage 单一来源原则
+        idx = 0
+        while idx < len(messages) and isinstance(messages[idx], SystemMessage):
+            idx += 1
+        rest = messages[idx:]
+        k = max(1, s.default_compress_keep_recent_messages)
+        if len(rest) <= k:
+            return StageResult(messages=messages, tokens_freed=0)
+
+        head = rest[:-k]
+        tail = rest[-k:]
+
+        block_llm = CompactionBlockingGuard(settings=s).should_block_compact_llm(messages)
+        if (
+            s.autocompact_use_llm_when_available
+            and ctx.model is not None
+            and not block_llm
+        ):
+            summary = await _astream_summary(ctx.model, s, head, ctx.progress_callback)
+            if summary:
+                folded = [
+                    HumanMessage(
+                        content=get_compact_user_summary_message(
+                            summary,
+                            recent_messages_preserved=True,
+                        )
+                    )
+                ] + tail
+                new_total = total_estimated_tokens_for_messages(folded, s.num_chars_per_token)
+                return StageResult(
+                    messages=folded,
+                    tokens_freed=max(0, total - new_total),
+                    extra={"autocompact_mode": "llm", "folded_messages": len(head)},
+                )
+
+        # fallback: prune
+        folded = [
+            HumanMessage(
+                content=(
+                    f"[Context autocompacted: {len(head)} earlier messages omitted; "
+                    "details dropped for token budget.]"
+                )
+            )
+        ] + tail
+        new_total = total_estimated_tokens_for_messages(folded, s.num_chars_per_token)
+        mode = "prune_blocked_llm" if block_llm else "prune"
+        return StageResult(
+            messages=folded,
+            tokens_freed=max(0, total - new_total),
+            extra={"autocompact_mode": mode, "folded_messages": len(head)},
+        )
+
 
 def _resolve_autocompact_llm_instruction(s: CompactionSettings) -> str:
     if s.autocompact_llm_instructions_override is not None:
@@ -139,3 +204,50 @@ def _invoke_summary(model: Any, s: CompactionSettings, head: list[Any]) -> str |
         return None
     text = stringify_content(getattr(resp, "content", None))
     return text if text else None
+
+
+async def _astream_summary(
+    model: Any, s: CompactionSettings, head: list[Any], progress_callback: Any = None
+) -> str | None:
+    """流式生成摘要，每个 chunk 触发 progress callback。
+
+    进度计算：
+        - autocompact 占 80%-100%，用 chunk 数做粗略进度。
+        - 每收到约 10 个 chunk 增加 2%，上限 99%。
+    """
+    cap = max(256, s.autocompact_llm_excerpt_chars_per_message)
+    parts: list[str] = []
+    for m in head:
+        label = getattr(m, "type", type(m).__name__)
+        chunk = stringify_content(getattr(m, "content", None))[:cap]
+        parts.append(f"{label}: {chunk}")
+    body = "\n\n---\n\n".join(parts)
+    excerpt_msg = HumanMessage(
+        content="[Conversation excerpt to summarize]\n\n" + body
+    )
+    instruction = _resolve_autocompact_llm_instruction(s)
+    instruction_msg = HumanMessage(content=instruction)
+
+    try:
+        chunks: list[str] = []
+        async for chunk in model.astream([excerpt_msg, instruction_msg]):
+            token = stringify_content(getattr(chunk, "content", None))
+            if token:
+                chunks.append(token)
+                if progress_callback:
+                    # autocompact 占 80%-100%，用 chunk 数做粗略进度
+                    pct = min(80 + len(chunks) * 2 // 10, 99)
+                    from ..types import CompactProgress
+
+                    progress_callback(
+                        CompactProgress(
+                            stage="autocompact",
+                            stage_index=4,
+                            total_stages=5,
+                            percent=pct,
+                            detail="generating summary...",
+                        )
+                    )
+        return "".join(chunks) or None
+    except Exception:
+        return None

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/stages/base.py

@@ -30,3 +30,12 @@ class CompactionStage(ABC):
     @abstractmethod
     def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
         """输入当前消息列表，返回更新后的列表与可选 tokens_freed。"""
+
+    async def arun(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        """Async 版本，默认委托 sync run()。AutocompactStage 覆盖此方法。
+
+        子类覆盖说明：
+            - 仅 AutocompactStage 需要覆盖以支持流式 LLM 调用。
+            - 其他阶段继承此默认实现即可。
+        """
+        return self.run(messages, ctx)

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/context/types.py

@@ -11,10 +11,12 @@
 
 注意：
 - `TokenWarningState` 供 `blocking_guard` 与 `compaction_pipeline_meta` 观测对齐 CC token 告警语义。
+- `CompactProgress` 用于 /compact 进度条回调，CLI 通过 progress_callback 接收进度更新。
 """
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from typing import Any, Literal, Mapping
 
@@ -37,6 +39,7 @@ class ContextCompactionContext:
     snip_tokens_freed_carry: int = 0
     query_source: str | None = None
     config: CompactionConfig = field(default_factory=CompactionConfig)
+    progress_callback: CompactProgressCallback = None
 
     @classmethod
     def from_state(
@@ -70,8 +73,32 @@ class TokenWarningState:
     level: TokenWarningLevel
 
 
+@dataclass(frozen=True)
+class CompactProgress:
+    """压缩进度通知（供 CLI 进度条消费）。
+
+    属性：
+        stage: 当前阶段名（tool_result_budget / snip / microcompact / collapse / autocompact / done）
+        stage_index: 0-based 阶段序号
+        total_stages: 总阶段数（默认 5）
+        percent: 0-100 整体进度百分比
+        detail: 可选描述（如 "generating summary..."）
+    """
+
+    stage: str
+    stage_index: int
+    total_stages: int
+    percent: int
+    detail: str | None = None
+
+
+CompactProgressCallback = Callable[[CompactProgress], None] | None
+
+
 __all__ = [
     "CompactionConfig",
+    "CompactProgress",
+    "CompactProgressCallback",
     "ContextCompactionContext",
     "StageResult",
     "TokenWarningLevel",

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/graph/factory.py

@@ -35,7 +35,7 @@ from typing import (
 )
 
 from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.messages import SystemMessage
+from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.runnables import RunnableConfig
 from langgraph._internal._runnable import RunnableCallable
 from langgraph.constants import END, START
@@ -92,11 +92,8 @@ from ...memory.memdir.agent_memory import (
 )
 from ...memory.memdir.runtime import MemoryPromptBootstrap
 from ...memory.memdir.extractor import MemoryExtractionCoordinator
-from ...memory.session import (
-    SessionMemoryCompactBridge,
-    SessionMemoryManager,
-    make_session_memory_section,
-)
+# Session memory imports use lazy imports to avoid circular dependency
+# SessionMemoryCompactBridge uses lazy import to avoid circular dependency with memory.session.session_memory
 from ..prompt import SystemPromptSection, build_effective_system_prompt
 from ..prompt.session_context import get_default_session_context_sections
 from ...tools.agent.prompt import build_explore_plan_guidance
@@ -263,9 +260,10 @@ class LoopGraphBuilder:
             )
         self._model_profile_registry = self._raw_capabilities.model_profile_registry
         self._model_context_resolver = ModelContextResolver()
-        self._session_memory_manager: SessionMemoryManager | None = None
-        self._session_memory_compact_bridge: SessionMemoryCompactBridge | None = None
+        # Lazy imports to avoid circular dependency with memory.session
         if self._raw_enable_session_memory:
+            from ...memory.session import SessionMemoryManager, make_session_memory_section
+            from ...memory.session.compact_bridge import SessionMemoryCompactBridge
             session_memory_path = self._workspace_cfg.session_memory_path(session_id)
             self._session_memory_manager = SessionMemoryManager(
                 session_memory_path=session_memory_path,
@@ -277,6 +275,9 @@ class LoopGraphBuilder:
                 extraction_state=self._session_memory_manager.extraction_state,
             )
             self._dynamic_sections.append(make_session_memory_section(session_memory_path))
+        else:
+            self._session_memory_manager = None
+            self._session_memory_compact_bridge = None
         if self._raw_include_default_session_context:
             self._dynamic_sections.extend(
                 get_default_session_context_sections(
@@ -1113,7 +1114,10 @@ class LoopGraphBuilder:
                 hint = skill_prefetch_provider._build_listing_hint(scope=skill_init_scope)
                 if hint is None:
                     return {}
-                return {"messages": [SystemMessage(content=f"[skill_listing] {hint.summary}")]}
+                # 对齐 CC：skill_listing 是 UserMessage，不是 SystemMessage
+                # CC src/utils/messages.ts: createUserMessage({ isMeta: true, ... })
+                # CC 中包裹在 <system-reminder> 中，但 role 是 "user"
+                return {"messages": [HumanMessage(content=f"[skill_listing] {hint.summary}")]}
 
             graph_inner.add_node(
                 "skill_init",

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/loop/model/model_node.py

@@ -22,7 +22,7 @@ import os
 from typing import Any, Dict, List
 
 from langchain.agents.structured_output import ResponseFormat
-from langchain_core.messages import AIMessage, SystemMessage
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
 from langchain_core.runnables import Runnable
 from langchain_core.runnables.config import RunnableConfig
 from langgraph.types import Command
@@ -97,6 +97,9 @@ def _messages_for_model_invoke(req: Any) -> list[Any]:
 
     对齐 CC normalizeMessagesForAPI：剥离 state["messages"] 中的违规 SystemMessage，
     确保 OpenAI 兼容 API "System message must be at the beginning" 约束。
+
+    L2 兜底：确保至少一条 HumanMessage 存在（对齐 CC prependUserContext 的防御层），
+    防止 compaction 路径遗漏导致 provider 400 "No user query found"。
     """
     messages = list(req.messages or [])
     s = get_active_compaction_settings()
@@ -138,6 +141,18 @@ def _messages_for_model_invoke(req: Any) -> list[Any]:
 
         messages = filtered
 
+    # L2 兜底：确保至少一条 HumanMessage 存在（防止 compaction 路径遗漏）
+    has_human = any(isinstance(m, HumanMessage) for m in messages)
+    if not has_human:
+        logger.warning(
+            "No HumanMessage found in messages after sanitization; "
+            "injecting placeholder to avoid provider 400 error."
+        )
+        messages = [
+            HumanMessage(content="[No user message available after context compaction.]"),
+            *messages,
+        ]
+
     if req.system_message:
         return [req.system_message, *messages]
     return messages

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/memory/session/compact_bridge.py

@@ -19,7 +19,7 @@ from pathlib import Path
 import time
 from typing import Any
 
-from langchain_core.messages import AIMessage, BaseMessage, SystemMessage, ToolMessage
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
 
 from langchain_agentx.memory.session.prompts import (
     DEFAULT_SESSION_MEMORY_TEMPLATE,
@@ -124,8 +124,15 @@ def adjust_index_to_preserve_api_invariants(
     return 0
 
 
-def _build_summary_message(session_memory_summary: str) -> SystemMessage:
-    return SystemMessage(
+def _build_summary_message(session_memory_summary: str) -> HumanMessage:
+    """Return HumanMessage summary for compaction (not SystemMessage).
+
+    对齐原则 #10「SystemPrompt 单一来源」与 CC summaryMessages: UserMessage[]：
+    - 压缩输出禁止包含 SystemMessage
+    - 压缩后第一条必须是 HumanMessage（summary）
+    - 确保 L1 sanitizer 剥离后仍有 user 消息存在
+    """
+    return HumanMessage(
         content=(
             f"{SUMMARY_PREFIX}\n\n"
             f"<session_memory_summary>\n{session_memory_summary}\n</session_memory_summary>\n"
@@ -158,17 +165,20 @@ def try_session_memory_compaction(
     if cut_index == 0:
         return None
 
-    head_system: list[BaseMessage] = []
-    remaining: list[BaseMessage] = messages
-    if isinstance(messages[0], SystemMessage):
-        head_system = [messages[0]]
-        remaining = messages[1:]
-        cut_index = max(0, cut_index - 1)
+    # 跳过所有 leading SystemMessages（对齐原则 #10 与 autocompact.py:56-60）
+    idx = 0
+    while idx < len(messages) and isinstance(messages[idx], SystemMessage):
+        idx += 1
+    remaining = messages[idx:]
+    if idx > 0:
+        cut_index = max(0, cut_index - idx)
+
     tail = remaining[cut_index:]
     if not tail:
         return None
 
-    rebuilt = [*head_system, _build_summary_message(truncated_summary), *tail]
+    # 重建: [HumanMessage(summary), ...tail] — 不含 SystemMessage
+    rebuilt = [_build_summary_message(truncated_summary), *tail]
     return rebuilt
 
 

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/langchain_agentx/session/agent_session.py

@@ -202,9 +202,25 @@ class AgentSession:
     def clear_context(self) -> None:
         self._messages.clear()
 
-    async def compact_context(self) -> tuple[int, int]:
+    async def compact_context(
+        self, *, progress_callback: Any = None
+    ) -> tuple[int, int]:
+        """压缩会话上下文，可选传入进度回调。
+
+        参数:
+            progress_callback: 可选的进度回调函数，接收 CompactProgress 对象
+
+        返回:
+            (before_tokens, after_tokens) 元组
+        """
         before_tokens = total_estimated_tokens_for_messages(self._messages, num_chars_per_token=4)
-        patch = default_loop_context_compaction().run({"messages": self._messages})
+        # 注意：model=None 表示不使用 LLM 摘要，仅走 prune 路径
+        # 如果需要 LLM 摘要，调用方需要通过其他方式提供 model
+        patch = await default_loop_context_compaction().arun(
+            {"messages": self._messages},
+            model=None,
+            progress_callback=progress_callback,
+        )
         if isinstance(patch.get("messages"), list):
             self._messages = list(patch["messages"])
         after_tokens = total_estimated_tokens_for_messages(self._messages, num_chars_per_token=4)

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4/langchain_agentx_python.egg-info}/PKG-INFO

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

{langchain-agentx-python-0.3.2 → langchain-agentx-python-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@
 
  [project]
  name = "langchain-agentx-python"
- version = "0.3.2"
+ version = "0.3.4"
  description = "LangChain/LangGraph-based agent utilities for CodeBaseX."
  readme = "README.md"
  requires-python = ">=3.11"