mcs-core 0.1.0__py3-none-any.whl

mcs/__init__.py

@@ -0,0 +1,52 @@
+"""MCS - Maximum-Context Subgraph：可扩展的知识图谱与检索引擎。
+
+顶层 ``MCS`` 类将图存储、LLM 后端、插件链、读写管线组装在一起。
+推荐使用 Builder 构建 MCS 实例：
+
+    # 快捷方式（推荐）
+    from mcs.presets import create_mcs
+    mcs = create_mcs(llm="deepseek", db_path="mcs.db")
+
+    # 或完整自定义
+    from mcs.presets import Phase1Builder
+    from mcs.entities.config import MCSConfig
+
+    config = MCSConfig.knowledge_graph(write_llm="deepseek", read_llm="deepseek")
+    config.plugin_configs["deepseek_llm"]["api_key"] = "..."
+    builder = Phase1Builder(config)
+    mcs = builder.build()  # 返回即用的 MCS 实例
+
+    # 使用
+    mcs.ingest("深度学习是机器学习的一个子领域...")
+    nodes = mcs.query("什么是深度学习？")
+    mcs.shutdown()
+
+MCS 实例由 Builder 一次性构建完成，无需调用 initialize()。
+
+参见 ``openspec/specs/`` 获取各能力的契约定义。
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from mcs.core.builder import MCSBuilder
+from mcs.core.mcs import MCS
+from mcs.core.plugin import Plugin, PluginType
+from mcs.core.store import StoreInterface
+from mcs.entities.config import MCSConfig
+from mcs.presets import Phase1Builder, create_mcs, get_phase1_plugin_registry
+from mcs.stores.in_memory import InMemoryStore
+from mcs.stores.sqlite_store import SQLiteStore
+
+__all__ = [
+    "MCS",
+    "MCSConfig",
+    "MCSBuilder",
+    "Phase1Builder",
+    "StoreInterface",
+    "InMemoryStore",
+    "SQLiteStore",
+    "create_mcs",
+    "get_phase1_plugin_registry",
+]

mcs/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core engine - stable graph operations and pipeline state machines.
+
+Contains:
+  - ``mcs``: MCS top-level orchestrator with dual PluginManager architecture
+  - ``builder``: MCSBuilder abstract base class for building MCS instances
+  - ``errors``: Exception hierarchy
+  - ``plugin``: Plugin base class and PluginType enum
+  - ``plugin_manager``: PluginManager and PluginContext
+  - ``query_engine``: QueryEngine for read pipeline
+  - ``store``: StoreInterface ABC
+  - ``token_budget``: TokenBudget
+  - ``write_pipeline``: WritePipeline for ingest pipeline
+  - ``context_renderer``: ContextRenderer for LLM input rendering
+
+纯数据模型（Node/Edge/Subgraph、Decision 系列、MCSConfig）已迁至 ``mcs.entities``。
+
+See architecture.md §2.
+"""

mcs/core/builder.py

@@ -0,0 +1,433 @@
+"""MCSBuilder 抽象基类 — 全量组装契约。
+
+Builder 接管从配置到完成态 MCS 的完整构建流程，包括：
+- Store 初始化
+- 插件实例化与注册
+- PluginContext 构建与插件初始化
+- QueryEngine 和 WritePipeline 构建
+- Load-on-startup
+
+MCS 构造后即处于 ready 状态，无需调用 initialize()。
+
+参见 openspec/specs/mcs-builder/spec.md "MCSBuilder 抽象基类定义构建契约"。
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcs.core.plugin import Plugin
+    from mcs.entities.config import MCSConfig
+
+logger = logging.getLogger(__name__)
+
+
+class MCSBuilder(ABC):
+    """抽象构建器 — 全量组装 MCS。
+
+    子类需实现 ``get_plugin_class()`` 方法，根据插件名称返回插件类。
+    ``build()`` 方法封装从配置到初始化完成的整个构建流程。
+    """
+
+    def __init__(self, config: "MCSConfig"):
+        """初始化构建器。
+
+        Args:
+            config: MCS 配置对象
+        """
+        self.config = config
+
+    @abstractmethod
+    def get_plugin_class(self, name: str) -> type["Plugin"] | None:
+        """根据插件名称返回插件类。
+
+        Args:
+            name: 插件名称（如 "sqlite_storage", "deepseek_llm"）
+
+        Returns:
+            插件类，若未找到则返回 None
+        """
+        ...
+
+    def build(self) -> "MCS":
+        """构建并返回即用的 MCS 实例。
+
+        执行完整的 14 步初始化流程。
+
+        Returns:
+            已完成初始化、可直接使用的 MCS 实例
+        """
+        from mcs.core.context_renderer import ContextRenderer
+        from mcs.core.mcs import MCS
+        from mcs.core.plugin_manager import PluginContext, PluginManager
+        from mcs.core.query_engine import QueryEngine
+        from mcs.core.token_budget import TokenBudget
+        from mcs.core.write_pipeline import WritePipeline
+        from mcs.interfaces.priority_scorer import DefaultPriorityScorer
+        from mcs.stores.in_memory import InMemoryStore
+        from mcs.stores.sqlite_store import SQLiteStore
+
+        # 1. 实例化 Store
+        store = self._init_store()
+
+        # 2. 实例化双 PluginManager
+        write_manager = PluginManager()
+        read_manager = PluginManager()
+
+        # 3. 按配置实例化并注册插件（获取 write_llm / read_llm）
+        write_llm, read_llm = self._register_plugins(write_manager, read_manager)
+
+        # 4. 用 write_llm.count_tokens 构造 TokenBudget
+        #    write_llm 必非 None：_register_llm_plugins 在 write_llm 缺失时直接 raise
+        token_budget = TokenBudget(
+            self.config.token_budget,
+            counter=write_llm.count_tokens,
+        )
+
+        # 5. 初始化 SQLiteStore（若使用）
+        if isinstance(store, SQLiteStore) and store.conn is None:
+            from mcs.core.plugin import PluginType
+            schema_exts = write_manager.get_all(PluginType.STORAGE_SCHEMA_EXT)
+            node_exts = {
+                p.get_name(): p
+                for p in write_manager.get_all(PluginType.NODE_EXTENSION)
+            }
+            edge_exts = {
+                p.get_name(): p
+                for p in write_manager.get_all(PluginType.EDGE_EXTENSION)
+            }
+            store.initialize(
+                schema_extensions=schema_exts,
+                node_extensions=node_exts,
+                edge_extensions=edge_exts,
+                priority_scorer=DefaultPriorityScorer(),
+            )
+
+        # 6. 创建 ContextRenderer（传入 read_manager）
+        context_renderer = ContextRenderer(read_manager)
+
+        # 7. 构建 PluginContext 并初始化所有插件
+        self._init_plugin_context(
+            store, token_budget, context_renderer, write_manager, read_manager
+        )
+
+        # 8. 应用 prompt_overrides 到 LLM
+        self._apply_prompt_overrides(write_llm, read_llm)
+
+        # 9. 构建 QueryEngine（read_manager + read_llm）
+        query_engine = QueryEngine(
+            store=store,
+            llm=read_llm,
+            plugin_manager=read_manager,
+            token_budget=token_budget,
+            max_rounds=self.config.max_rounds,
+            max_accumulated_nodes=self.config.max_accumulated_nodes,
+        )
+
+        # 10. 构建 WritePipeline（write_manager + write_llm + query_engine）
+        write_pipeline = WritePipeline(
+            store=store,
+            llm=write_llm,
+            query_engine=query_engine,
+            plugin_manager=write_manager,
+            token_budget=token_budget,
+            config=self.config,
+        )
+
+        # 11. 构建 MCS
+        mcs = MCS(
+            write_pipeline=write_pipeline,
+            query_engine=query_engine,
+            store=store,
+            write_manager=write_manager,
+            read_manager=read_manager,
+        )
+
+        # 12. 执行 load-on-startup
+        self._load_on_startup(store, read_manager)
+
+        return mcs
+
+    def _init_store(self) -> "StoreInterface":
+        """根据配置实例化 Store。
+
+        Returns:
+            Store 实例
+        """
+        from mcs.stores.in_memory import InMemoryStore
+        from mcs.stores.sqlite_store import SQLiteStore
+
+        sqlite_config = self.config.plugin_configs.get("sqlite_storage", {})
+        db_path = sqlite_config.get("path", "")
+
+        if db_path and db_path != ":memory:":
+            return SQLiteStore(sqlite_config)
+        return InMemoryStore()
+
+    def _register_plugins(
+        self,
+        write_manager: "PluginManager",
+        read_manager: "PluginManager",
+    ) -> tuple["Plugin", "Plugin"]:
+        """按 shared/write/read 分类实例化并注册插件到双 manager。
+
+        Args:
+            write_manager: 写入侧插件管理器
+            read_manager: 读取侧插件管理器
+
+        Returns:
+            (write_llm, read_llm) 插件实例元组
+        """
+        # 1. 共享插件：同一实例注册到两个 manager
+        for plugin_name in self.config.shared_plugins:
+            plugin = self._instantiate_plugin(plugin_name)
+            if plugin is None:
+                continue
+            write_manager.register(plugin)
+            read_manager.register(plugin)
+
+        # 2. 写入专用：只注册到 write_manager
+        for plugin_name in self.config.write_plugins:
+            plugin = self._instantiate_plugin(plugin_name)
+            if plugin is None:
+                continue
+            write_manager.register(plugin)
+
+        # 3. 读取专用：只注册到 read_manager
+        for plugin_name in self.config.read_plugins:
+            plugin = self._instantiate_plugin(plugin_name)
+            if plugin is None:
+                continue
+            read_manager.register(plugin)
+
+        # 4. 处理 LLM 分离
+        return self._register_llm_plugins(write_manager, read_manager)
+
+    def _instantiate_plugin(self, plugin_name: str) -> "Plugin | None":
+        """从注册表实例化插件。
+
+        Args:
+            plugin_name: 插件名称
+
+        Returns:
+            插件实例，若未找到则返回 None
+        """
+        cls = self.get_plugin_class(plugin_name)
+        if cls is None:
+            return None
+        plugin_config = self.config.plugin_configs.get(plugin_name, {})
+        try:
+            return cls(plugin_config)
+        except TypeError:
+            return cls()
+
+    def _register_llm_plugins(
+        self,
+        write_manager: "PluginManager",
+        read_manager: "PluginManager",
+    ) -> tuple["Plugin", "Plugin"]:
+        """处理 LLM 分离：write_llm / read_llm 从对应 manager 查找；相同时共享实例。
+
+        Args:
+            write_manager: 写入侧插件管理器
+            read_manager: 读取侧插件管理器
+
+        Returns:
+            (write_llm, read_llm) 插件实例元组
+        """
+        write_llm_name = self.config.write_llm
+        read_llm_name = self.config.read_llm
+
+        if not write_llm_name:
+            raise RuntimeError(
+                "未指定 write_llm。请在 MCSConfig 中设置 write_llm。"
+            )
+        if not read_llm_name:
+            raise RuntimeError(
+                "未指定 read_llm。请在 MCSConfig 中设置 read_llm。"
+            )
+
+        if write_llm_name == read_llm_name:
+            # 同一 LLM：共享实例
+            # 先检查是否已通过 register_plugin 注册
+            existing = write_manager.get_by_name(write_llm_name) or \
+                       read_manager.get_by_name(read_llm_name)
+            if existing is not None:
+                # 已注册，只需确保两个 manager 都有
+                if write_manager.get_by_name(write_llm_name) is None:
+                    write_manager.register(existing)
+                if read_manager.get_by_name(read_llm_name) is None:
+                    read_manager.register(existing)
+            else:
+                # 从 registry 实例化
+                plugin = self._instantiate_plugin(write_llm_name)
+                if plugin is None:
+                    raise RuntimeError(
+                        f"未找到 LLM 插件: {write_llm_name!r}。"
+                        "请确保插件注册表中包含该插件。"
+                    )
+                write_manager.register(plugin)
+                read_manager.register(plugin)
+        else:
+            # 不同 LLM：各自独立
+            write_plugin = write_manager.get_by_name(write_llm_name) or \
+                           read_manager.get_by_name(write_llm_name)
+            if write_plugin is None:
+                write_plugin = self._instantiate_plugin(write_llm_name)
+            if write_plugin is None:
+                raise RuntimeError(
+                    f"未找到写入 LLM 插件: {write_llm_name!r}。"
+                    "请确保插件注册表中包含该插件。"
+                )
+            if write_manager.get_by_name(write_llm_name) is None:
+                write_manager.register(write_plugin)
+
+            read_plugin = read_manager.get_by_name(read_llm_name) or \
+                          write_manager.get_by_name(read_llm_name)
+            if read_plugin is None:
+                read_plugin = self._instantiate_plugin(read_llm_name)
+            if read_plugin is None:
+                raise RuntimeError(
+                    f"未找到读取 LLM 插件: {read_llm_name!r}。"
+                    "请确保插件注册表中包含该插件。"
+                )
+            if read_manager.get_by_name(read_llm_name) is None:
+                read_manager.register(read_plugin)
+
+        # 解析 LLM 引用
+        write_llm = write_manager.get_by_name(write_llm_name)
+        read_llm = read_manager.get_by_name(read_llm_name)
+
+        return write_llm, read_llm
+
+    def _init_plugin_context(
+        self,
+        store: "StoreInterface",
+        token_budget: "TokenBudget",
+        context_renderer: "ContextRenderer",
+        write_manager: "PluginManager",
+        read_manager: "PluginManager",
+    ) -> None:
+        """创建 PluginContext 并初始化所有插件。
+
+        Args:
+            store: 存储实例
+            token_budget: Token 预算
+            context_renderer: 上下文渲染器
+            write_manager: 写入侧插件管理器
+            read_manager: 读取侧插件管理器
+        """
+        from mcs.core.plugin_manager import PluginContext
+
+        # 写入侧插件初始化
+        write_ctx = PluginContext(
+            store=store,
+            config=self.config,
+            token_budget=token_budget,
+            context_renderer=context_renderer,
+            plugin_manager=write_manager,
+        )
+        write_manager.initialize_all(write_ctx)
+
+        # 读取侧插件初始化
+        read_ctx = PluginContext(
+            store=store,
+            config=self.config,
+            token_budget=token_budget,
+            context_renderer=context_renderer,
+            plugin_manager=read_manager,
+        )
+        read_manager.initialize_all(read_ctx)
+
+    def _apply_prompt_overrides(
+        self,
+        write_llm: "Plugin",
+        read_llm: "Plugin",
+    ) -> None:
+        """将用户 prompt 覆盖应用到 LLM。
+
+        Args:
+            write_llm: 写入 LLM 插件
+            read_llm: 读取 LLM 插件
+        """
+        for purpose, overrides in (self.config.prompt_overrides or {}).items():
+            write_llm.register_prompt(
+                purpose,
+                system=overrides.get("system"),
+                template=overrides.get("template"),
+                parser=overrides.get("parser"),
+            )
+            # 如果 read_llm 与 write_llm 不同，也应用覆盖
+            if read_llm is not write_llm:
+                read_llm.register_prompt(
+                    purpose,
+                    system=overrides.get("system"),
+                    template=overrides.get("template"),
+                    parser=overrides.get("parser"),
+                )
+
+    def _load_on_startup(
+        self,
+        store: "StoreInterface",
+        read_manager: "PluginManager",
+    ) -> None:
+        """若 Store 为空且 SQLite 可用，加载已有数据并重建 Index。
+
+        Args:
+            store: 存储实例
+            read_manager: 读取侧插件管理器（用于获取 Index 插件）
+        """
+        from mcs.core.plugin import PluginType
+        from mcs.stores.sqlite_store import SQLiteStore
+
+        if store.get_all_nodes():
+            return
+        if not isinstance(store, SQLiteStore):
+            return
+        try:
+            store.load()
+            # reload 后重建所有 IndexInterface 索引
+            for index in read_manager.get_all(PluginType.INDEX):
+                try:
+                    index.build(store)
+                except NotImplementedError:
+                    continue
+        except Exception:
+            logger.warning("Load-on-startup failed", exc_info=True)
+
+    def _collect_registry(self) -> dict[str, type["Plugin"]]:
+        """从 shared + write + read + LLM 收集插件注册表。
+
+        Returns:
+            插件名称 → 插件类的映射
+        """
+        all_names: list[str] = []
+
+        # 收集所有插件名称（去重）
+        seen: set[str] = set()
+        for name in (
+            self.config.shared_plugins +
+            self.config.write_plugins +
+            self.config.read_plugins
+        ):
+            if name not in seen:
+                all_names.append(name)
+                seen.add(name)
+
+        # LLM 也加入（即使不在 plugins 列表中）
+        for llm in [self.config.write_llm, self.config.read_llm]:
+            if llm and llm not in seen:
+                all_names.append(llm)
+                seen.add(llm)
+
+        # 查找插件类
+        registry: dict[str, type["Plugin"]] = {}
+        for name in all_names:
+            cls = self.get_plugin_class(name)
+            if cls is not None:
+                registry[name] = cls
+
+        return registry

mcs/core/calibrated_estimator.py

@@ -0,0 +1,61 @@
+"""校准经验式 token 估算器——精确方案的兜底。
+
+当 LLM 插件的精确计数（API / tiktoken）不可用时，使用按模型族调整系数的
+经验式替代当前硬编码的 CJK 1:1 + 非CJK 4:1。
+
+设计原则：宁可高估（过早触发裂变）也不低估（破坏核心不变量）。
+unknown 模型采用 claude/gpt 系数（最保守）。
+
+系数来源：下表系数为文献/经验值（CJK 系数取各模型族中文 token/字 的保守上界）。
+``bench/calibration/calibrate_token_estimator.py`` 提供校准工具（对照精确计数拟合
+系数），尚未跑实测定标；定标后更新 ``COEFFICIENTS``。
+"""
+
+from __future__ import annotations
+
+
+class CalibratedEstimator:
+    """按模型族调整系数的经验式 token 估算器。
+
+    每个模型族有独立的 CJK 系数和非 CJK 除数：
+
+        estimate(text) = cjk_count * cjk_coeff + non_cjk_count // non_cjk_divisor
+
+    系数表为文献/经验值（详见 design.md §校准方法论），待 bench/calibration 实测定标。
+    """
+
+    # 模型族 → (CJK 系数, 非CJK 字符/token 除数)。文献/经验值，待实测定标
+    COEFFICIENTS: dict[str, tuple[float, int]] = {
+        "claude": (1.7, 3),
+        "gpt": (1.7, 3),
+        "deepseek": (1.3, 4),
+        "ollama": (1.3, 4),
+        "unknown": (1.7, 3),  # 保守——与 claude/gpt 相同
+    }
+
+    def __init__(self, model_family: str = "unknown") -> None:
+        self._model_family = model_family
+        cjk_coeff, non_cjk_divisor = self.COEFFICIENTS.get(
+            model_family, self.COEFFICIENTS["unknown"]
+        )
+        self._cjk_coeff = cjk_coeff
+        self._non_cjk_divisor = non_cjk_divisor
+
+    @property
+    def model_family(self) -> str:
+        """返回构造时指定的模型族名称。"""
+        return self._model_family
+
+    def estimate(self, text: str | None) -> int:
+        """估算 ``text`` 的 token 数量。
+
+        - CJK 字符按 ``cjk_coeff`` 计（如 claude ×1.7）
+        - 非 CJK 字符按 ``non_cjk_divisor`` 除（如 claude ÷3）
+        - 空值/None 返回 0
+        - 非空文本至少返回 1
+        """
+        if not text:
+            return 0
+        cjk = sum(1 for ch in text if "一" <= ch <= "鿿")
+        non_cjk = len(text) - cjk
+        return max(1, int(cjk * self._cjk_coeff + non_cjk // self._non_cjk_divisor))

mcs/core/content_merge.py

@@ -0,0 +1,81 @@
+"""公共 content 合并 helper。
+
+统一 3 条字面合并路径的 content 处理（write path / query read-repair / 后台 dedup），
+落实 unified-graph-schema「图质量最终收敛」content 合并守则：不机械换行追加。
+
+行为：
+- 子串关系（target ⊇ incoming → 跳过；incoming ⊇ target → 替换）→ 零成本，所有路径共用。
+- 非子串 + merge_llm 传入 → LLM 语义合并成一个稳定定义（守时间归属）。
+- 非子串 + merge_llm=None → 返回 target（不碰；调用方决定挂起 / 保留 dup）。
+
+``substring_relation`` 抽出子串包含判定，供 ``merge_content`` 与后台 dedup 共用——
+单点定义，防两处分支口径漂移。
+
+调用方分流（按 LLM 可用性）：
+- write path `_dispatch_merge` 传 merge_llm（每次 ingest 同名对齐，本就 LLM）。
+- query read-repair `_try_read_repair` 不传（读路径零 LLM；被并方节点保留）。
+- 后台 dedup 不传（子串才合删 dup，非子串保留 dup；彻底合并靠 write path）。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def substring_relation(target: str, incoming: str) -> Optional[str]:
+    """两段 content 的子串包含关系（``merge_content`` 与 dedup 共用，防口径漂移）。
+
+    返回：
+    - ``"target"``：incoming 为空，或 incoming ⊆ target（target 更全 / 相等）。
+    - ``"incoming"``：target 为空，或 target ⊆ incoming（incoming 更全）。
+    - ``None``：两方都非空且互不包含（非子串）。
+
+    调用方据此区分「可零成本合并」（返回非 None）与「需 LLM / 保留 dup」（None）。
+    """
+    t = target or ""
+    i = incoming or ""
+    if not i.strip():
+        return "target"
+    if not t.strip():
+        return "incoming"
+    if i in t:
+        return "target"
+    if t in i:
+        return "incoming"
+    return None
+
+
+def merge_content(
+    target: str,
+    incoming: str,
+    merge_llm: Optional[Callable[[str, str], str]] = None,
+) -> str:
+    """合并两段 content 成一个稳定定义（不机械换行追加）。
+
+    - 子串关系零成本（经 ``substring_relation``：incoming ⊆ target → target；
+      target ⊆ incoming → incoming；含一方空）。
+    - 非子串 + merge_llm：LLM 语义合并；异常 / 空返回 → 降级保留 target + warning。
+    - 非子串 + merge_llm=None：返回 target（不碰）。
+    """
+    rel = substring_relation(target, incoming)
+    if rel == "target":
+        return target
+    if rel == "incoming":
+        return incoming
+
+    # 非子串（两方都非空、互不包含）
+    if merge_llm is None:
+        return target
+
+    try:
+        merged = merge_llm(target, incoming)
+    except Exception:
+        logger.warning("merge_content: LLM 合并失败，保留 target content", exc_info=True)
+        return target
+    if not merged or not merged.strip():
+        logger.warning("merge_content: LLM 返回空，保留 target content")
+        return target
+    return merged.strip()