langchain-agentx-python 0.9.9__tar.gz → 1.0.1__tar.gz

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.9.9
+Version: 1.0.1
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License
@@ -245,6 +245,34 @@ agent = create_loop_agent(...)
 
 具体的能力和使用方式可以参考源码中的 docstring 以及各模块下的 `README.md`。
 
+## 工具进度显示
+
+长耗时工具（如 `BashRuntimeTool`）可在执行期间通过 `ToolExecutionContext.emit_progress()` 向 CLI 实时报告进度。事件经 LangGraph `dispatch_custom_event("tool_progress", ...)` 发出，CLI 通过 `astream_events` 接收。
+
+```python
+# 工具 invoke 内（同步路径）
+ctx.emit_progress(
+    phase="running",
+    data={"output": chunk, "total_lines": line_count, "elapsed_time_seconds": elapsed},
+)
+
+# 异步工具
+await ctx.aemit_progress(phase="query_update", data={"query": query})
+```
+
+**向后兼容**：进度为可选能力。未发射 progress 或 CLI 未监听时，工具仍按 `ToolResultEnvelope` 正常返回。`emit_progress` 在无 LangGraph 上下文时静默失败，不中断工具主流程。
+
+**文档**：
+- 设计：[`docs/design-docs/tool-runtime/tool-progress-design.html`](docs/design-docs/tool-runtime/tool-progress-design.html)
+- 事件契约：[`docs/design-docs/tool-runtime/tool-progress-event-contract.html`](docs/design-docs/tool-runtime/tool-progress-event-contract.html)
+- 工具作者门禁：[`docs/guides/tool-implementation-checklist.html#section-4-2`](docs/guides/tool-implementation-checklist.html#section-4-2)
+
+**测试**：
+
+```bash
+pytest tests/regression/tool_progress/ tests/tool_runtime/progress/ langchain_agentx/tool_runtime/test_emit_progress.py -v
+```
+
 ## 发布新版本流程
 
 > **重要特性**：本项目的构建脚本会**自动排除所有测试文件**，生成纯净的生产包。当前有 140+ 个测试文件在构建时会被自动过滤，确保发布的包轻量、干净。
@@ -459,16 +487,62 @@ python -m twine upload dist/*
 
 ## 开发
 
+### 环境
+
+```bash
+# 推荐：项目 venv（Windows Git Bash 示例）
+export VENV_PYTHON="$HOME/langchain_agentx_venv/Scripts/python.exe"
+
+# 可编辑安装 + dev 依赖（首次或 pyproject.toml 变更后）
+"$VENV_PYTHON" -m pip install -e ".[dev]"
+```
+
+### 依赖方向门禁（import-linter，提交前自检）
+
+阶段 0 仓内 import 方向静态门禁（F1 / F3 / F4 / I1 / L1）。**本地 `git commit` 不会触发 CI**；GitHub Actions 在 **`push` 到 `main`** 或 **开/更新 PR** 时运行（且变更命中 `.importlinter`、`langchain_agentx/**` 等 paths 时）。
+
+**改 `langchain_agentx/` 前或 commit 前建议跑：**
+
+```bash
+# 1) import 方向扫描（与 CI lint-imports job 一致）
+bash scripts/lint-imports.sh
+
+# 2) pytest 回归（CI 同跑）
+python -m pytest langchain_agentx/test_import_direction_gate_regression.py -v
+
+# 3) trace 伴侣包单向依赖（正交互补，建议一并跑）
+python -m pytest langchain_agentx/test_trace_companion_import_guard.py -v
+```
+
+Windows 若不用脚本，可等价执行：
+
+```bash
+export PYTHONUTF8=1
+lint-imports --config .importlinter
+```
+
+**新增跨层 / 禁依赖 import 且无合法 ignore 登记** → 上述命令 exit 非 0；**已在 baseline 的老违规**（`.importlinter` 内 `ignore_imports`）→ 仍可通过。
+
+维护 baseline（须同步 `docs/design-docs/evolution/baseline-exit-plan.md`，单独 PR）：
+
+```bash
+python scripts/generate_importlinter_ignore.py
+```
+
+设计 / 实施文档：[`docs/design-docs/evolution/stage-0-dependency-direction-gate.md`](docs/design-docs/evolution/stage-0-dependency-direction-gate.md) · [`docs/exec-plan/evolution/stage-0-dependency-direction-gate-2026-06-10.html`](docs/exec-plan/evolution/stage-0-dependency-direction-gate-2026-06-10.html)
+
 ### 运行测试
 
 ```bash
 # 安装开发依赖
-pip install -e “.[dev]”
+pip install -e ".[dev]"
 
 # 运行测试
 pytest langchain_agentx/
 ```
 
+一键日常（不含 LLM）：`bash scripts/run-default-tests.sh`（详见 [`scripts/README.md`](scripts/README.md)）
+
 ### 代码规范
 
 所有代码遵循项目编码规范：`docs/guides/coding-style-guide.html`

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/README.md

@@ -25,6 +25,34 @@ agent = create_loop_agent(...)
 
 具体的能力和使用方式可以参考源码中的 docstring 以及各模块下的 `README.md`。
 
+## 工具进度显示
+
+长耗时工具（如 `BashRuntimeTool`）可在执行期间通过 `ToolExecutionContext.emit_progress()` 向 CLI 实时报告进度。事件经 LangGraph `dispatch_custom_event("tool_progress", ...)` 发出，CLI 通过 `astream_events` 接收。
+
+```python
+# 工具 invoke 内（同步路径）
+ctx.emit_progress(
+    phase="running",
+    data={"output": chunk, "total_lines": line_count, "elapsed_time_seconds": elapsed},
+)
+
+# 异步工具
+await ctx.aemit_progress(phase="query_update", data={"query": query})
+```
+
+**向后兼容**：进度为可选能力。未发射 progress 或 CLI 未监听时，工具仍按 `ToolResultEnvelope` 正常返回。`emit_progress` 在无 LangGraph 上下文时静默失败，不中断工具主流程。
+
+**文档**：
+- 设计：[`docs/design-docs/tool-runtime/tool-progress-design.html`](docs/design-docs/tool-runtime/tool-progress-design.html)
+- 事件契约：[`docs/design-docs/tool-runtime/tool-progress-event-contract.html`](docs/design-docs/tool-runtime/tool-progress-event-contract.html)
+- 工具作者门禁：[`docs/guides/tool-implementation-checklist.html#section-4-2`](docs/guides/tool-implementation-checklist.html#section-4-2)
+
+**测试**：
+
+```bash
+pytest tests/regression/tool_progress/ tests/tool_runtime/progress/ langchain_agentx/tool_runtime/test_emit_progress.py -v
+```
+
 ## 发布新版本流程
 
 > **重要特性**：本项目的构建脚本会**自动排除所有测试文件**，生成纯净的生产包。当前有 140+ 个测试文件在构建时会被自动过滤，确保发布的包轻量、干净。
@@ -239,16 +267,62 @@ python -m twine upload dist/*
 
 ## 开发
 
+### 环境
+
+```bash
+# 推荐：项目 venv（Windows Git Bash 示例）
+export VENV_PYTHON="$HOME/langchain_agentx_venv/Scripts/python.exe"
+
+# 可编辑安装 + dev 依赖（首次或 pyproject.toml 变更后）
+"$VENV_PYTHON" -m pip install -e ".[dev]"
+```
+
+### 依赖方向门禁（import-linter，提交前自检）
+
+阶段 0 仓内 import 方向静态门禁（F1 / F3 / F4 / I1 / L1）。**本地 `git commit` 不会触发 CI**；GitHub Actions 在 **`push` 到 `main`** 或 **开/更新 PR** 时运行（且变更命中 `.importlinter`、`langchain_agentx/**` 等 paths 时）。
+
+**改 `langchain_agentx/` 前或 commit 前建议跑：**
+
+```bash
+# 1) import 方向扫描（与 CI lint-imports job 一致）
+bash scripts/lint-imports.sh
+
+# 2) pytest 回归（CI 同跑）
+python -m pytest langchain_agentx/test_import_direction_gate_regression.py -v
+
+# 3) trace 伴侣包单向依赖（正交互补，建议一并跑）
+python -m pytest langchain_agentx/test_trace_companion_import_guard.py -v
+```
+
+Windows 若不用脚本，可等价执行：
+
+```bash
+export PYTHONUTF8=1
+lint-imports --config .importlinter
+```
+
+**新增跨层 / 禁依赖 import 且无合法 ignore 登记** → 上述命令 exit 非 0；**已在 baseline 的老违规**（`.importlinter` 内 `ignore_imports`）→ 仍可通过。
+
+维护 baseline（须同步 `docs/design-docs/evolution/baseline-exit-plan.md`，单独 PR）：
+
+```bash
+python scripts/generate_importlinter_ignore.py
+```
+
+设计 / 实施文档：[`docs/design-docs/evolution/stage-0-dependency-direction-gate.md`](docs/design-docs/evolution/stage-0-dependency-direction-gate.md) · [`docs/exec-plan/evolution/stage-0-dependency-direction-gate-2026-06-10.html`](docs/exec-plan/evolution/stage-0-dependency-direction-gate-2026-06-10.html)
+
 ### 运行测试
 
 ```bash
 # 安装开发依赖
-pip install -e “.[dev]”
+pip install -e ".[dev]"
 
 # 运行测试
 pytest langchain_agentx/
 ```
 
+一键日常（不含 LLM）：`bash scripts/run-default-tests.sh`（详见 [`scripts/README.md`](scripts/README.md)）
+
 ### 代码规范
 
 所有代码遵循项目编码规范：`docs/guides/coding-style-guide.html`

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "0.9.9"
+__version__ = "1.0.1"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/langchain_agentx/memory/memdir/agent_memory.py

@@ -42,6 +42,7 @@ logger = logging.getLogger(__name__)
 class _AgentMemoryWorkspaceView:
     memory_dir: Path
     memory_entrypoint: Path
+    transcripts_dir: Path
 
 
 @dataclass(frozen=True)
@@ -103,7 +104,11 @@ class AgentMemoryPromptService:
         memory_dir = self._cfg.agent_memory_dir(sanitized, scope)
         entrypoint = self._cfg.agent_memory_entrypoint(sanitized, scope)
         prompt = MemoryPromptLoader(
-            _AgentMemoryWorkspaceView(memory_dir=memory_dir, memory_entrypoint=entrypoint)  # type: ignore[arg-type]
+            _AgentMemoryWorkspaceView(
+                memory_dir=memory_dir,
+                memory_entrypoint=entrypoint,
+                transcripts_dir=self._cfg.transcripts_dir,
+            )  # type: ignore[arg-type]
         ).load_memory_prompt()
         if prompt is None:
             return None

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/langchain_agentx/memory/memdir/extractor.py

@@ -24,7 +24,14 @@ from langchain_agentx.workspace import ResolvedAgentStateConfig
 from .agent_memory import is_agent_memory_path
 from .paths import is_memory_enabled
 from .scan import format_memory_manifest, scan_memory_files
-from .types import HOW_TO_SAVE_SECTION, TYPES_SECTION_INDIVIDUAL, WHAT_NOT_TO_SAVE_SECTION
+from .types import (
+    HOW_TO_SAVE_SECTION,
+    TYPES_SECTION_INDIVIDUAL,
+    TRUSTING_RECALL_SECTION,
+    USER_VISIBLE_DELIVERABLE_SECTION,
+    WHAT_NOT_TO_SAVE_SECTION,
+    WHEN_TO_ACCESS_SECTION,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -289,12 +296,15 @@ def build_extract_prompt(
             "a duplicate."
         )
     body = (
-        "If the user explicitly asks you to remember something, save it immediately as\n"
-        "whichever type fits best. If they ask you to forget something, find and remove\n"
-        "the relevant entry.\n\n"
         f"{TYPES_SECTION_INDIVIDUAL}\n\n"
+        "If the user explicitly asks you to remember something, save only what fits the\n"
+        "memory types above and is not excluded under 'What NOT to save in memory'.\n"
+        "If they ask you to forget something, find and remove the relevant entry.\n\n"
         f"{WHAT_NOT_TO_SAVE_SECTION}\n\n"
-        f"{HOW_TO_SAVE_SECTION}"
+        f"{HOW_TO_SAVE_SECTION}\n\n"
+        f"{WHEN_TO_ACCESS_SECTION}\n\n"
+        f"{TRUSTING_RECALL_SECTION}\n\n"
+        f"{USER_VISIBLE_DELIVERABLE_SECTION}"
     )
     return opener + existing + "\n\n" + body
 

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/langchain_agentx/memory/memdir/loader.py

@@ -25,8 +25,10 @@ from .types import (
     MEMORY_AND_PERSISTENCE_SECTION,
     TRUSTING_RECALL_SECTION,
     TYPES_SECTION_INDIVIDUAL,
+    USER_VISIBLE_DELIVERABLE_SECTION,
     WHAT_NOT_TO_SAVE_SECTION,
     WHEN_TO_ACCESS_SECTION,
+    build_how_to_save_section,
 )
 
 MAX_ENTRYPOINT_LINES = 200
@@ -52,7 +54,12 @@ class MemoryPromptLoader:
         return _truncate_entrypoint_content(raw)
 
     def build_memory_lines(self, entrypoint_text: str) -> list[str]:
-        return _build_memory_lines(memory_dir=self._cfg.memory_dir, entrypoint_text=entrypoint_text)
+        transcripts_dir = getattr(self._cfg, "transcripts_dir", None)
+        return _build_memory_lines(
+            memory_dir=self._cfg.memory_dir,
+            entrypoint_text=entrypoint_text,
+            transcripts_dir=transcripts_dir,
+        )
 
     def load_memory_prompt(self) -> str | None:
         self._ensure_memory_dir()
@@ -125,7 +132,42 @@ def _truncate_entrypoint_content(raw: str) -> EntrypointTruncation:
     )
 
 
-def _build_memory_lines(*, memory_dir: Path, entrypoint_text: str) -> list[str]:
+def build_searching_past_context_section(
+    *,
+    memory_dir: Path,
+    transcripts_dir: Path,
+) -> list[str]:
+    """CC memdir.ts buildSearchingPastContextSection() — always enabled in SDK."""
+    mem_dir = memory_dir.as_posix()
+    transcripts = transcripts_dir.as_posix()
+    mem_search = f'grep with pattern="<search term>" path="{mem_dir}" glob="*.md"'
+    transcript_search = (
+        f'grep with pattern="<search term>" path="{transcripts}/" glob="*.jsonl"'
+    )
+    return [
+        "## Searching past context",
+        "",
+        "When looking for past context:",
+        "1. Search topic files in your memory directory:",
+        "```",
+        mem_search,
+        "```",
+        "2. Session transcript logs (last resort — large files, slow):",
+        "```",
+        transcript_search,
+        "```",
+        "Use narrow search terms (error messages, file paths, function names) rather than broad keywords.",
+        "",
+    ]
+
+
+def _build_memory_lines(
+    *,
+    memory_dir: Path,
+    entrypoint_text: str,
+    transcripts_dir: Path | None = None,
+) -> list[str]:
+    how_to_save = build_how_to_save_section(max_entrypoint_lines=MAX_ENTRYPOINT_LINES)
     header = [
         "# auto memory",
         "",
@@ -137,15 +179,15 @@ def _build_memory_lines(*, memory_dir: Path, entrypoint_text: str) -> list[str]:
         "with you, what behaviors to avoid or repeat, and the context behind the work",
         "the user gives you.",
         "",
-        "If the user explicitly asks you to remember something, save it immediately as",
-        "whichever type fits best. If they ask you to forget something, find and remove",
-        "the relevant entry.",
-        "",
         TYPES_SECTION_INDIVIDUAL,
         "",
+        "If the user explicitly asks you to remember something, save only what fits the",
+        "memory types above and is not excluded under 'What NOT to save in memory'.",
+        "If they ask you to forget something, find and remove the relevant entry.",
+        "",
         WHAT_NOT_TO_SAVE_SECTION,
         "",
-        HOW_TO_SAVE_SECTION,
+        how_to_save,
         "",
         WHEN_TO_ACCESS_SECTION,
         "",
@@ -153,9 +195,22 @@ def _build_memory_lines(*, memory_dir: Path, entrypoint_text: str) -> list[str]:
         "",
         MEMORY_AND_PERSISTENCE_SECTION,
         "",
-        "## MEMORY.md",
+        USER_VISIBLE_DELIVERABLE_SECTION,
         "",
     ]
+    if transcripts_dir is not None:
+        header.extend(
+            build_searching_past_context_section(
+                memory_dir=memory_dir,
+                transcripts_dir=transcripts_dir,
+            )
+        )
+    header.extend(
+        [
+            "## MEMORY.md",
+            "",
+        ]
+    )
     body = (
         entrypoint_text.strip()
         if entrypoint_text.strip()
@@ -182,6 +237,7 @@ __all__ = [
     "MAX_ENTRYPOINT_LINES",
     "MemoryPromptLoader",
     "build_memory_lines",
+    "build_searching_past_context_section",
     "load_memory_prompt",
     "truncate_entrypoint_content",
 ]

{langchain-agentx-python-0.9.9 → langchain-agentx-python-1.0.1}/langchain_agentx/memory/memdir/scan.py

@@ -88,13 +88,25 @@ class MemoryScanner:
                 break
         if end_index is None:
             raise FrontmatterParseError("missing closing ---")
+
+        in_metadata = False
         for raw in lines[1:end_index]:
-            line = raw.strip()
-            if not line:
+            stripped = raw.strip()
+            if not stripped:
+                continue
+            if stripped == "metadata:" or stripped.startswith("metadata:"):
+                in_metadata = True
                 continue
-            if ":" not in line:
-                raise FrontmatterParseError(f"invalid frontmatter line: {line}")
-            key, value = line.split(":", 1)
+            if in_metadata:
+                if stripped.startswith("type:"):
+                    value = stripped.split(":", 1)[1].strip().strip('"').strip("'")
+                    parsed = parse_memory_type(value)
+                    return parsed.value if parsed else None
+                if not raw[:1].isspace():
+                    in_metadata = False
+            if ":" not in stripped:
+                raise FrontmatterParseError(f"invalid frontmatter line: {stripped}")
+            key, value = stripped.split(":", 1)
             if key.strip() != "type":
                 continue
             normalized = value.strip().strip('"').strip("'")