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

langchain_agentx/memory/instruction/loader.py

@@ -0,0 +1,325 @@
+"""instruction/loader.py — Layer 1 规则加载编排。
+
+职责：
+    负责规则文件加载、@path 展开、frontmatter 路径解析与条件规则筛选。
+
+链路位置：
+    Loop 初始化 -> load_rule_set(...) -> LoadedRuleSet -> sections 组装。
+
+当前裁剪范围：
+    仅处理 Layer 1 文本加载与匹配，不解析规则业务语义。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from wcmatch import glob as wcglob
+
+from langchain_agentx.utils.path_hierarchy import is_filesystem_root
+
+from .resolver import resolve_rules_file_name
+from .types import ConditionalRule, InstructionMemoryConfig, LoadedRuleSet, RuleFile, RuleLayer
+
+_AT_PATH_RE = re.compile(r"(?:^|\s)@((?:[^\s\\]|\\ )+)")
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+class ProjectRuleCollector:
+    """Project 规则文件收集器（workspace_root 向上遍历）。"""
+
+    def collect(self, *, workspace_root: Path, agent_home: str, rules_file: str) -> list[Path]:
+        found: list[Path] = []
+        current = workspace_root.resolve()
+        while True:
+            candidate = current / agent_home / rules_file
+            if candidate.exists():
+                found.append(candidate)
+            if is_filesystem_root(current):
+                break
+            current = current.parent
+        found.reverse()
+        return found
+
+
+class AtPathResolver:
+    """`@path` 路径解析器（支持 ~/、绝对路径、fragment、转义空格）。"""
+
+    def resolve(self, *, raw: str, current_file: Path) -> Path:
+        normalized = raw.replace(r"\ ", " ")
+        normalized = normalized.split("#")[0]
+        p = Path(normalized)
+        if p.is_absolute():
+            return p.resolve()
+        if normalized.startswith("~/"):
+            return (Path.home() / normalized[2:]).resolve()
+        return (current_file.parent / p).resolve()
+
+
+class AtPathProcessor:
+    """`@path` 行内展开器（代码块内跳过，循环/缺失文件保留原文）。"""
+
+    def __init__(self, *, depth_limit: int, resolver: AtPathResolver | None = None) -> None:
+        self._depth_limit = depth_limit
+        self._resolver = resolver or AtPathResolver()
+
+    def process(
+        self,
+        *,
+        current_path: Path,
+        content: str,
+        visited: frozenset[Path],
+        depth: int,
+    ) -> str:
+        if depth > self._depth_limit:
+            return content
+
+        lines: list[str] = []
+        in_code_block = False
+        for line in content.splitlines(keepends=True):
+            stripped = line.rstrip("\n\r")
+            if stripped.startswith("```") or stripped.startswith("~~~"):
+                in_code_block = not in_code_block
+                lines.append(line)
+                continue
+            if in_code_block:
+                lines.append(line)
+                continue
+            matches = _AT_PATH_RE.findall(stripped)
+            if not matches:
+                lines.append(line)
+                continue
+            result_line = line
+            for raw in matches:
+                resolved = self._resolver.resolve(raw=raw, current_file=current_path)
+                if resolved in visited:
+                    continue
+                if not resolved.exists():
+                    continue
+                included = resolved.read_text(encoding="utf-8")
+                expanded = self.process(
+                    current_path=resolved,
+                    content=included,
+                    visited=visited | {resolved},
+                    depth=depth + 1,
+                )
+                result_line = result_line.replace(f"@{raw}", expanded, 1)
+            lines.append(result_line)
+        return "".join(lines)
+
+
+def strip_html_comments(content: str) -> str:
+    return _HTML_COMMENT_RE.sub('', content)
+
+
+class FrontmatterPathsParser:
+    def parse(self, raw: str) -> tuple[str, list[str]]:
+        """解析 frontmatter，返回 (去除 frontmatter 的正文, paths 列表)。"""
+        lines = raw.splitlines(keepends=True)
+        if len(lines) < 3 or lines[0].strip() != "---":
+            return raw, []
+        end_idx = None
+        for i in range(1, len(lines)):
+            if lines[i].strip() == "---":
+                end_idx = i
+                break
+        if end_idx is None:
+            return raw, []
+
+        fm_block = "".join(lines[1:end_idx])
+        content = "".join(lines[end_idx + 1:])
+        patterns = self._parse_paths_block(fm_block)
+        return content, patterns
+
+    def parse_paths(self, raw: str) -> list[str]:
+        _, patterns = self.parse(raw)
+        return patterns
+
+    def _parse_paths_block(self, fm_block: str) -> list[str]:
+        fm_lines = fm_block.splitlines()
+        in_paths = False
+        patterns: list[str] = []
+        for line in fm_lines:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if stripped.startswith("paths:"):
+                direct = stripped[len("paths:"):].strip()
+                if direct:
+                    patterns.extend(self._split_inline_paths(direct))
+                in_paths = True
+                continue
+            if in_paths:
+                if stripped.startswith("- "):
+                    val = stripped[2:].strip().strip("'").strip('"')
+                    if val:
+                        patterns.append(val)
+                else:
+                    in_paths = False
+        return patterns
+
+    @staticmethod
+    def _split_inline_paths(raw: str) -> list[str]:
+        # 支持 paths: "a,b" 或 paths: a,b；逗号分隔时忽略空白项。
+        normalized = raw.strip().strip("'").strip('"')
+        if not normalized:
+            return []
+        return [part.strip() for part in normalized.split(",") if part.strip()]
+
+
+def _path_matches_pattern(file_path: str, pattern: str) -> bool:
+    return wcglob.globmatch(file_path, pattern, flags=wcglob.GLOBSTAR)
+
+
+def _parse_paths_from_frontmatter(raw: str) -> list[str]:
+    return FrontmatterPathsParser().parse_paths(raw)
+
+
+def get_active_conditional_rules(
+    conditional_rules: list[ConditionalRule],
+    active_files: list[str],
+) -> list[ConditionalRule]:
+    result: list[ConditionalRule] = []
+    for rule in conditional_rules:
+        if not rule.paths_patterns:
+            result.append(rule)
+            continue
+        if any(
+            _path_matches_pattern(f, pattern)
+            for f in active_files
+            for pattern in rule.paths_patterns
+        ):
+            result.append(rule)
+    return result
+
+
+class InstructionRuleLoader:
+    def __init__(
+        self,
+        *,
+        cfg: InstructionMemoryConfig,
+        frontmatter_parser: FrontmatterPathsParser | None = None,
+        project_collector: ProjectRuleCollector | None = None,
+        at_path_processor: AtPathProcessor | None = None,
+    ) -> None:
+        self._cfg = cfg
+        self._frontmatter_parser = frontmatter_parser or FrontmatterPathsParser()
+        self._project_collector = project_collector or ProjectRuleCollector()
+        self._at_path_processor = at_path_processor or AtPathProcessor(
+            depth_limit=cfg.include_depth_limit
+        )
+
+    def load(self) -> LoadedRuleSet:
+        ws = self._cfg.workspace_cfg
+        rules_file, local_file, rules_dir_name = resolve_rules_file_name(ws.agent_home)
+
+        user_rf: RuleFile | None = None
+        if self._cfg.load_user_layer:
+            user_path = Path.home() / ws.agent_home / rules_file
+            if user_path.exists():
+                user_rf = self._load_file(user_path, RuleLayer.USER)
+
+        project_paths = self._project_collector.collect(
+            workspace_root=ws.workspace_root,
+            agent_home=ws.agent_home,
+            rules_file=rules_file,
+        )
+        project_files = [
+            self._load_file(p, RuleLayer.PROJECT) for p in project_paths
+        ]
+
+        local_path = ws.agent_home_dir / local_file
+        local_rf = self._load_file(local_path, RuleLayer.LOCAL) if local_path.exists() else None
+
+        rules_dir = ws.agent_home_dir / rules_dir_name
+        conditional = self._load_conditional_rules(rules_dir)
+
+        return LoadedRuleSet(
+            managed=self._cfg.managed_rules,
+            user=user_rf,
+            project_files=project_files,
+            local=local_rf,
+            conditional_rules=conditional,
+        )
+
+    def _load_file(self, path: Path, layer: RuleLayer) -> RuleFile:
+        raw = path.read_text(encoding="utf-8")
+        content_wo_frontmatter, _ = self._frontmatter_parser.parse(raw)
+        content = self._at_path_processor.process(
+            current_path=path,
+            content=content_wo_frontmatter,
+            visited=frozenset([path.resolve()]),
+            depth=0,
+        )
+        return RuleFile(path=path, content=content, source_layer=layer)
+
+    def _load_conditional_rules(self, rules_dir: Path) -> list[ConditionalRule]:
+        if not rules_dir.exists() or not rules_dir.is_dir():
+            return []
+        result: list[ConditionalRule] = []
+        for file_path in sorted(rules_dir.glob("*.md"), key=lambda p: p.name):
+            raw = file_path.read_text(encoding="utf-8")
+            content_wo_frontmatter, patterns = self._frontmatter_parser.parse(raw)
+            content = self._at_path_processor.process(
+                current_path=file_path,
+                content=content_wo_frontmatter,
+                visited=frozenset([file_path.resolve()]),
+                depth=0,
+            )
+            result.append(ConditionalRule(path=file_path, content=content, paths_patterns=patterns))
+        return result
+
+
+def load_rule_set(cfg: InstructionMemoryConfig) -> LoadedRuleSet:
+    return InstructionRuleLoader(cfg=cfg).load()
+
+
+def load_conditional_rules(rules_dir: Path, depth_limit: int) -> list[ConditionalRule]:
+    if not rules_dir.exists() or not rules_dir.is_dir():
+        return []
+    parser = FrontmatterPathsParser()
+    processor = AtPathProcessor(depth_limit=depth_limit)
+    result: list[ConditionalRule] = []
+    for file_path in sorted(rules_dir.glob("*.md"), key=lambda p: p.name):
+        raw = file_path.read_text(encoding="utf-8")
+        content_wo_frontmatter, patterns = parser.parse(raw)
+        content = processor.process(
+            current_path=file_path,
+            content=content_wo_frontmatter,
+            visited=frozenset([file_path.resolve()]),
+            depth=0,
+        )
+        result.append(ConditionalRule(path=file_path, content=content, paths_patterns=patterns))
+    return result
+
+
+def collect_project_rule_files(
+    workspace_root: Path,
+    agent_home: str,
+    rules_file: str,
+) -> list[Path]:
+    return ProjectRuleCollector().collect(
+        workspace_root=workspace_root,
+        agent_home=agent_home,
+        rules_file=rules_file,
+    )
+
+
+def _resolve_at_path(raw: str, current_file: Path) -> Path:
+    return AtPathResolver().resolve(raw=raw, current_file=current_file)
+
+
+def process_at_paths(
+    current_path: Path,
+    content: str,
+    visited: frozenset[Path],
+    depth: int,
+    depth_limit: int,
+) -> str:
+    return AtPathProcessor(depth_limit=depth_limit).process(
+        current_path=current_path,
+        content=content,
+        visited=visited,
+        depth=depth,
+    )

langchain_agentx/memory/instruction/resolver.py

@@ -0,0 +1,24 @@
+"""instruction/resolver.py — Layer 1 规则文件名解析器。
+
+职责：
+    基于 agent_home 返回主规则文件、本地规则文件、rules 目录名映射。
+
+链路位置：
+    InstructionRuleLoader.load() -> resolve_rules_file_name(...)。
+
+当前裁剪范围：
+    仅做名称映射，不执行目录扫描与存在性回退。
+"""
+
+from __future__ import annotations
+
+_AGENT_HOME_MAP: dict[str, tuple[str, str, str]] = {
+    ".claude": ("CLAUDE.md", "CLAUDE.local.md", "rules"),
+    ".cursor": (".cursorrules", ".cursorrules.local", "rules"),
+}
+_DEFAULT = ("AGENT.md", "AGENT.local.md", "rules")
+
+
+def resolve_rules_file_name(agent_home: str) -> tuple[str, str, str]:
+    return _AGENT_HOME_MAP.get(agent_home, _DEFAULT)
+

langchain_agentx/memory/instruction/runtime.py

@@ -0,0 +1,83 @@
+"""instruction/runtime.py — Layer 1 在 loop 侧的接线协作者。
+
+职责：
+    封装 Instruction Memory 在运行时的配置解析与 section 构建，避免工厂内联拼装。
+
+链路位置：
+    LoopGraphBuilder.__init__ -> InstructionMemoryBootstrap.build_sections()。
+
+当前裁剪范围：
+    提供默认 active_files 提供器（空列表），具体会话采集策略由上层注入。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from langchain_agentx.loop.prompt import SystemPromptSection
+from langchain_agentx.workspace import resolve_agent_workspace_config
+
+from .loader import load_rule_set
+from .sections import make_instruction_sections
+from .types import InstructionMemoryConfig
+
+
+class InstructionMemoryBootstrap:
+    def __init__(
+        self,
+        *,
+        workspace_root: str | Path,
+        agent_home: str,
+        managed_rules: str | None,
+        include_depth_limit: int = 5,
+        active_files_provider: "ActiveFilesProvider | None" = None,
+    ) -> None:
+        self._workspace_root = workspace_root
+        self._agent_home = agent_home
+        self._managed_rules = managed_rules
+        self._include_depth_limit = include_depth_limit
+        self._active_files_provider = active_files_provider or NullActiveFilesProvider()
+
+    def build_sections(self) -> list[SystemPromptSection]:
+        workspace_cfg = resolve_agent_workspace_config(
+            workspace_root=self._workspace_root,
+            agent_home=self._agent_home,
+        )
+        loaded_rules = load_rule_set(
+            InstructionMemoryConfig(
+                workspace_cfg=workspace_cfg,
+                managed_rules=self._managed_rules,
+                load_user_layer=True,
+                include_depth_limit=self._include_depth_limit,
+            )
+        )
+        return make_instruction_sections(
+            loaded_rules,
+            active_files_getter=self._active_files_provider.get_active_files,
+        )
+
+
+class ActiveFilesProvider:
+    """active_files 提供器接口。"""
+
+    def get_active_files(self) -> list[str]:
+        raise NotImplementedError()
+
+
+class NullActiveFilesProvider(ActiveFilesProvider):
+    """默认 provider：无会话文件上下文时返回空列表。"""
+
+    def get_active_files(self) -> list[str]:
+        return []
+
+
+class CallbackActiveFilesProvider(ActiveFilesProvider):
+    """通过回调函数桥接外部会话上下文。"""
+
+    def __init__(self, getter: Callable[[], list[str]]) -> None:
+        self._getter = getter
+
+    def get_active_files(self) -> list[str]:
+        return list(self._getter() or [])
+

langchain_agentx/memory/instruction/sections.py

@@ -0,0 +1,83 @@
+"""instruction/sections.py — Layer 1 规则段装配器。
+
+职责：
+    将 LoadedRuleSet 按静态/动态规则拆分为可缓存的 prompt sections。
+
+链路位置：
+    load_rule_set(...) -> make_instruction_sections(...) -> build_effective_system_prompt(...)。
+
+当前裁剪范围：
+    仅负责文本组装，不负责文件加载与 active_files 维护。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from langchain_agentx.loop.prompt import SystemPromptSection, section, volatile_section
+
+from .loader import get_active_conditional_rules, strip_html_comments
+from .types import LoadedRuleSet
+
+
+class InstructionSectionBuilder:
+    def __init__(
+        self,
+        *,
+        rule_set: LoadedRuleSet,
+        active_files_getter: Callable[[], list[str]],
+    ) -> None:
+        self._rule_set = rule_set
+        self._active_files_getter = active_files_getter
+
+    def build_static_rules(self) -> str | None:
+        parts: list[str] = []
+        if self._rule_set.managed:
+            parts.append(strip_html_comments(self._rule_set.managed))
+        if self._rule_set.user:
+            parts.append(strip_html_comments(self._rule_set.user.content))
+        for rf in self._rule_set.project_files:
+            parts.append(strip_html_comments(rf.content))
+        if self._rule_set.local:
+            parts.append(strip_html_comments(self._rule_set.local.content))
+        for rule in self._rule_set.conditional_rules:
+            if not rule.paths_patterns:
+                parts.append(strip_html_comments(rule.content))
+        return "".join(parts) if parts else None
+
+    def build_conditional_rules(self) -> str | None:
+        dynamic_rules = [
+            r
+            for r in get_active_conditional_rules(
+                self._rule_set.conditional_rules,
+                self._active_files_getter(),
+            )
+            if r.paths_patterns
+        ]
+        if not dynamic_rules:
+            return None
+        return "".join(strip_html_comments(r.content) for r in dynamic_rules)
+
+    def build_sections(self) -> list[SystemPromptSection]:
+        return [
+            section(
+                name="agent_rules_static",
+                compute=self.build_static_rules,
+            ),
+            volatile_section(
+                name="agent_rules_conditional",
+                compute=self.build_conditional_rules,
+                reason="active_files changes as session progresses; paths matching must re-evaluate each turn",
+            ),
+        ]
+
+
+def make_instruction_sections(
+    rule_set: LoadedRuleSet,
+    active_files_getter: Callable[[], list[str]],
+) -> list[SystemPromptSection]:
+    return InstructionSectionBuilder(
+        rule_set=rule_set,
+        active_files_getter=active_files_getter,
+    ).build_sections()
+

langchain_agentx/memory/instruction/types.py

@@ -0,0 +1,59 @@
+"""instruction/types.py — Layer 1 指令规则核心数据模型。
+
+职责：
+    定义规则来源层、单文件结果、条件规则、完整加载结果与配置入口。
+
+链路位置：
+    resolver/loader/sections 之间共享的契约层。
+
+当前裁剪范围：
+    仅数据建模，不包含任何 IO 或匹配逻辑。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+from langchain_agentx.workspace import AgentWorkspaceConfig
+
+
+class RuleLayer(str, Enum):
+    MANAGED = "managed"
+    USER = "user"
+    PROJECT = "project"
+    RULES = "rules"
+    LOCAL = "local"
+
+
+@dataclass(frozen=True)
+class RuleFile:
+    path: Path | None
+    content: str
+    source_layer: RuleLayer
+
+
+@dataclass(frozen=True)
+class ConditionalRule:
+    path: Path
+    content: str
+    paths_patterns: list[str]
+
+
+@dataclass(frozen=True)
+class LoadedRuleSet:
+    managed: str | None
+    user: RuleFile | None
+    project_files: list[RuleFile]  # root → workspace_root order; workspace_root has highest priority
+    local: RuleFile | None
+    conditional_rules: list[ConditionalRule]
+
+
+@dataclass(frozen=True)
+class InstructionMemoryConfig:
+    workspace_cfg: AgentWorkspaceConfig
+    managed_rules: str | None = None
+    load_user_layer: bool = True
+    include_depth_limit: int = 5
+

langchain_agentx/memory/memdir/__init__.py

@@ -0,0 +1,77 @@
+"""memdir — Layer 2 跨会话事实记忆能力入口。"""
+
+from .age import memory_age_days, memory_freshness_text
+from .agent_memory import (
+    AgentMemoryExtractionContext,
+    AgentMemoryExtractionCoordinator,
+    AgentMemoryPromptBootstrap,
+    AgentMemoryPromptService,
+    AgentMemoryPathPolicy,
+    drain_pending_agent_memory_extraction,
+    get_default_agent_memory_extraction_coordinator,
+    is_agent_memory_path,
+    is_agent_memory_path_for_type,
+    load_agent_memory_prompt,
+    sanitize_agent_type,
+)
+from .extractor import (
+    MemoryExtractionContext,
+    MemoryExtractionCoordinator,
+    build_extract_prompt,
+    create_auto_mem_can_use_tool,
+    drain_pending_extraction,
+    execute_extract_memories,
+)
+from .loader import (
+    EntrypointTruncation,
+    MemoryPromptLoader,
+    build_memory_lines,
+    load_memory_prompt,
+    truncate_entrypoint_content,
+)
+from .paths import get_memory_dir, is_memory_enabled, is_memory_path
+from .runtime import MemoryPromptBootstrap
+from .scan import MAX_SCAN_FILES, MemoryFileHeader, MemoryScanner, format_memory_manifest, scan_memory_files
+from .recall import find_relevant_memories, select_relevant_memories
+from .types import MEMORY_TYPES, MemoryType, parse_memory_type
+
+__all__ = [
+    "EntrypointTruncation",
+    "AgentMemoryPathPolicy",
+    "AgentMemoryExtractionContext",
+    "AgentMemoryExtractionCoordinator",
+    "AgentMemoryPromptBootstrap",
+    "AgentMemoryPromptService",
+    "get_default_agent_memory_extraction_coordinator",
+    "MEMORY_TYPES",
+    "MAX_SCAN_FILES",
+    "MemoryExtractionContext",
+    "MemoryExtractionCoordinator",
+    "MemoryFileHeader",
+    "build_extract_prompt",
+    "create_auto_mem_can_use_tool",
+    "drain_pending_extraction",
+    "execute_extract_memories",
+    "MemoryScanner",
+    "MemoryType",
+    "MemoryPromptBootstrap",
+    "MemoryPromptLoader",
+    "build_memory_lines",
+    "format_memory_manifest",
+    "get_memory_dir",
+    "is_memory_enabled",
+    "is_memory_path",
+    "is_agent_memory_path",
+    "is_agent_memory_path_for_type",
+    "load_agent_memory_prompt",
+    "drain_pending_agent_memory_extraction",
+    "load_memory_prompt",
+    "memory_age_days",
+    "memory_freshness_text",
+    "parse_memory_type",
+    "sanitize_agent_type",
+    "find_relevant_memories",
+    "scan_memory_files",
+    "select_relevant_memories",
+    "truncate_entrypoint_content",
+]

langchain_agentx/memory/memdir/age.py

@@ -0,0 +1,36 @@
+"""
+memory/memdir/age.py — Layer 2 记忆新鲜度文本。
+
+职责：
+    基于文件更新时间计算 age 文本，为 memory manifest 提供可读提示。
+
+链路位置：
+    scan/build_memory_lines 在组装输出时读取本模块结果。
+
+当前裁剪范围：
+    仅基于 mtime，不引入时区数据库或复杂本地化。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+
+def memory_age_days(path: Path, now: datetime | None = None) -> int:
+    snapshot = now or datetime.now()
+    mtime = datetime.fromtimestamp(path.stat().st_mtime)
+    delta = snapshot - mtime
+    return max(0, delta.days)
+
+
+def memory_freshness_text(path: Path, now: datetime | None = None) -> str:
+    days = memory_age_days(path, now=now)
+    if days <= 0:
+        return "updated today"
+    if days == 1:
+        return "updated yesterday"
+    return f"updated {days} days ago"
+
+
+__all__ = ["memory_age_days", "memory_freshness_text"]