langchain-agentx-python 0.3.2__py3-none-any.whl → 0.3.3__py3-none-any.whl

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/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/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/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/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/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/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.dist-info → langchain_agentx_python-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.3.2
+Version: 0.3.3
 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.dist-info → langchain_agentx_python-0.3.3.dist-info}/RECORD

@@ -21,16 +21,16 @@ langchain_agentx/loop/config/agent_loop_config.py,sha256=ZzmrFO9nIVQst9-mAICTgG0
 langchain_agentx/loop/config/model_context_resolver.py,sha256=qZWDLyGlvr0YVZkvpDk72h6_Qbe0mvhWwlvTRsTfJ_E,3916
 langchain_agentx/loop/config/runtime_settings.py,sha256=uKkwyxgx5u34qbjP1DFrIRt0EygRCtsH8tMN0kWA0Yo,1551
 langchain_agentx/loop/config/token_estimator.py,sha256=2-Rp2Bdc5a-60D1nm88z4-sNzS25nv8hkKIfaBqE78E,4883
-langchain_agentx/loop/context/__init__.py,sha256=HUuKNwysY-RNCvenEhN5CuoHSInY94a16aC9hMAG-go,1896
+langchain_agentx/loop/context/__init__.py,sha256=VMYkkJSqjLpkx_6MqGpiASQIW-QDF8L7OwffSn_CnoI,2000
 langchain_agentx/loop/context/blocking_guard.py,sha256=Rmt5qZdE8Zf0bt-Q6WwMSfG869772PE8w1mNPvBQRCQ,3789
-langchain_agentx/loop/context/compaction_service.py,sha256=dJG24qbJ2t93_UwrXoPacRazpGf2l429310PHzLAz9A,2183
+langchain_agentx/loop/context/compaction_service.py,sha256=nvLG8dfEqoJouuE9BHczmIZEb7pxU5lcuhIJJ8Pi5Sg,3004
 langchain_agentx/loop/context/message_utils.py,sha256=6qIwtHeh63OlMqOnPUpEEWRknU9KJTGkcY1v3tz6feY,2010
-langchain_agentx/loop/context/pipeline.py,sha256=mQA5CcSrXaYb3kM3bO3MqrBPRzQebodmhRMG-9waIN8,4461
+langchain_agentx/loop/context/pipeline.py,sha256=P_3oK_dfnx1BT5nCPYo3cmD94QhZP9xeiSOXv3-oCeU,7418
 langchain_agentx/loop/context/settings.py,sha256=cbfb5RyBupsIY1CF-QZ8OsuIrpdx9QzNwXRAezkMl8U,5918
-langchain_agentx/loop/context/types.py,sha256=imjo5mSxwkn7uGrwJzGDtAB9aH9M6DdfXyBAZTUvknE,2332
+langchain_agentx/loop/context/types.py,sha256=HIiuNlOl47CmBlRr0yp-NCGaZ29omb3z2VRWq8mIsTI,3194
 langchain_agentx/loop/context/stages/__init__.py,sha256=wk9CFh8_Akw8qs3Dldnx14VE1MhyF5i9Cg3phTVChhg,892
-langchain_agentx/loop/context/stages/autocompact.py,sha256=P1XazrWL3YoH0gu8df5FMnRTb6d_XCJDpT9g8_H1bkM,7041
-langchain_agentx/loop/context/stages/base.py,sha256=iOWVR5NwmRcYq6fQAI6WEi-LMsuBeH5TfuOorN0luIg,982
+langchain_agentx/loop/context/stages/autocompact.py,sha256=En8K7dkqAnueZH0mQ4eY6r8-wwY8oXikTKaXcri_Mhs,11784
+langchain_agentx/loop/context/stages/base.py,sha256=LVfCp-DLySrTExy0J-M40tDJvzbOXxfZxXvi7XQayA8,1380
 langchain_agentx/loop/context/stages/collapse.py,sha256=yOf3nfWZr83rq2qnhUpuTCLFHcGvF7my8klMLmfZ7jc,2971
 langchain_agentx/loop/context/stages/microcompact.py,sha256=aTF3TjBkQ_fDx818Kfwr3d7hdx3dtAW8St3bAOiZTMg,2779
 langchain_agentx/loop/context/stages/noop.py,sha256=UKKPeKfyDoxd9NBzjIai6OGcr-9RrraKmx2E9Vpf3vc,1069
@@ -157,7 +157,7 @@ langchain_agentx/provider/env.py,sha256=bmELhixPGoJ3b0rtgEPCB512gJF2cVS00bRQfclk
 langchain_agentx/provider/model_profile.py,sha256=3m3iVtYYuBLMADRu-36L_JwODjH8vYe1BfkuEMNkKJc,6245
 langchain_agentx/provider/openai.py,sha256=mNPRPhxtkKRhBVnXqJD8r1Vmo22HNM-hT-Di_VNL-ng,2996
 langchain_agentx/session/__init__.py,sha256=UO-bRS9oYSzdYoavow4FSXdY7qzw5O3VoUH9_FTzGTI,497
-langchain_agentx/session/agent_session.py,sha256=iAlB7w9GFxlBh_eZiNCW7YPqPibLaCr1QiPWHgHEIHQ,13791
+langchain_agentx/session/agent_session.py,sha256=jMc6vwsv8wNa0B_3HtTyXpJAH72xuR0D4rqQJwlPlRs,14352
 langchain_agentx/session/conversation_factory.py,sha256=Nhi_8iH0D8-NmfsJqgnKxIEa8Y32qfOFpjRNqWVksEQ,2992
 langchain_agentx/session/conversation_recovery.py,sha256=U0M3p4NKaSz6heEvNzlzehC8oTX9EB2Vz-QdYhhyk0U,5813
 langchain_agentx/session/conversation_session.py,sha256=phzXQZMfNCOzOa9dDlaA0zaPCOVuHiu6_EXmg3zpuok,8007
@@ -444,8 +444,8 @@ langchain_agentx/workspace/config.py,sha256=K2XaAvlkBr5aA2mgH5zNxfAZg-LGmwwDVNcE
 langchain_agentx/workspace/path_key_normalizer.py,sha256=ICk9uGiiNFH-zaXJG3_vx91uOpgWmgOPIjJoSYevKOc,1113
 langchain_agentx/workspace/resolver.py,sha256=9-wRLLIC7KJCqu9i8nAL-gJ9lIWsTPOpjnZnZEGLunk,6281
 langchain_agentx/workspace/validators.py,sha256=tQt-6TOcL8Fw7Ig5ebA9S7vGWh1rby920eFW6x8Tk9E,1439
-langchain_agentx_python-0.3.2.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-langchain_agentx_python-0.3.2.dist-info/METADATA,sha256=TVN9m4gC_J5zfoi0NF5H_UcBWpMPHls6q9Om8wJdzkU,20832
-langchain_agentx_python-0.3.2.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
-langchain_agentx_python-0.3.2.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
-langchain_agentx_python-0.3.2.dist-info/RECORD,,
+langchain_agentx_python-0.3.3.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+langchain_agentx_python-0.3.3.dist-info/METADATA,sha256=X1N_trdWuzlYm1XVrNWgIxTq1P2nsxiYjy-Bjdz91xo,20832
+langchain_agentx_python-0.3.3.dist-info/WHEEL,sha256=51RkbunBAw4BWsgaQWTpPhg4Diwp3c9P5iaLk67Hdtg,92
+langchain_agentx_python-0.3.3.dist-info/top_level.txt,sha256=Ge284pniNt8xea0OLk2o9o32GqVpDhOYk20fwE-0xxA,17
+langchain_agentx_python-0.3.3.dist-info/RECORD,,