mcs-core 0.1.0__tar.gz

mcs_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcs_core-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: mcs-core
+Version: 0.1.0
+Summary: MCS (Maximum-Context Subgraph) — LLM-native knowledge graph engine
+Author: MCS Team
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai<2.0,>=1.0
+Requires-Dist: jieba>=0.42
+Requires-Dist: ujson>=5.0
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: claude
+Requires-Dist: anthropic<1.0,>=0.40; extra == "claude"
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == "yaml"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Requires-Dist: pyyaml>=6; extra == "mcp"
+Provides-Extra: agent
+Requires-Dist: fastapi>=0.110; extra == "agent"
+Requires-Dist: uvicorn>=0.27; extra == "agent"
+Requires-Dist: apscheduler>=3.10; extra == "agent"
+Dynamic: license-file
+
+# MCS - Maximum-Context Subgraph
+
+一个**完整的通用记忆引擎**——由大模型语义驱动，把零散文本组织成图结构的语义记忆，并维持一条硬不变量，使任意节点的活跃视图永远放得进一个 LLM 上下文窗口。不依赖 embedding / 向量检索，靠大模型直接阅读"装得下的局部子图"完成关系发现、聚类与召回。
+
+MCS 默认返回相关节点集合（`List[Node]`），不是自然语言答案。它专注于"记忆本身"，把合成答案、多轮对话、追问加深等留给上层（RAG / Agent / Chatbot）。
+
+## 核心定位
+
+MCS 不假设外部知识天然就近——它靠**核心不变量 + 守门 + 聚类裂变主动维持语义局部性**：无论图如何增长，任意节点的活跃双向视图（关系边 + 层级邻居）都被收敛到语义内聚、且渲染 token ≤ 一个上下文窗口 T。因此沿关联边的语义游走总能在有界视野内到达相关知识，大模型可以一次"读完"局部视野再做判断。导航、归纳、查询都建立在这之上。
+
+## 快速开始
+
+### 安装
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS / Linux
+pip install -e ".[dev]"
+```
+
+### 基本用法
+
+```python
+from mcs.presets import create_mcs
+
+# 知识图谱模式（默认配置含 Phase 1 插件）
+mcs = create_mcs(llm="deepseek", db_path="mcs.db")
+# 需先设置环境变量 DEEPSEEK_API_KEY 或传入 plugin_configs
+
+# 摄入文本 → 自动抽概念、定位、入图
+mcs.ingest("深度学习是机器学习的一个子领域，它使用多层神经网络来学习数据的表示。")
+mcs.ingest("卷积神经网络是一种专门处理网格状数据的深度学习模型。")
+
+# 查询 → 默认返回相关节点集合
+nodes = mcs.query("什么是深度学习？")
+for n in nodes:
+    print(n.name, "—", n.content[:80])
+```
+
+或使用 Builder 完整自定义：
+
+```python
+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"] = "your-api-key"
+
+builder = Phase1Builder(config)
+mcs = builder.build()  # 返回即用的 MCS 实例
+```
+
+### 配置文件（YAML）
+
+也支持从 **YAML 文件**配置（preset 铺底 + 字段叠加 + `${VAR}` 环境变量插值 + import-path 第三方插件）：
+
+```bash
+pip install -e ".[yaml]"   # 可选依赖 PyYAML
+```
+
+```yaml
+# mcs.yaml
+preset: knowledge_graph          # 复用默认 Phase1 插件集，只覆盖要改的字段
+write_llm: deepseek
+plugin_configs:
+  deepseek_llm:
+    api_key: ${DEEPSEEK_API_KEY}  # 秘密走环境、不进文件
+  sqlite_storage:
+    path: mcs.db
+shared_plugins:
+  - my_pkg.exts:MyEdgeExtension   # import-path 第三方插件
+```
+
+```python
+from mcs.entities.config import MCSConfig
+from mcs.presets import Phase1Builder
+
+config = MCSConfig.from_file("mcs.yaml")
+mcs = Phase1Builder(config).build()
+```
+
+> ⚠️ 配置文件是**受信输入**：YAML 经 import-path 可加载任意代码，**勿接受陌生来源**。
+> 自定义 LLM 必须走**无 preset** 路径（`knowledge_graph()` 只认 deepseek/claude/ollama）。
+> 详见 [配置文件文档](docs/configuration.md)。
+
+### 切换后端
+
+<details>
+<summary>Claude / Anthropic 后端</summary>
+
+```python
+mcs = create_mcs(
+    llm="claude",
+    db_path="mcs.db",
+    plugin_configs={
+        "claude_llm": {
+            "auth_token": "your-anthropic-token",
+            "model": "claude-3-5-sonnet-latest",
+            "base_url": "https://api.anthropic.com",
+        }
+    }
+)
+```
+
+需先安装：`pip install -e ".[claude]"`
+
+</details>
+
+<details>
+<summary>Ollama 本地后端（零 token 成本）</summary>
+
+```python
+mcs = create_mcs(
+    llm="ollama",
+    db_path="mcs.db",
+    plugin_configs={
+        "ollama_llm": {
+            "base_url": "http://localhost:11434/v1",
+            "model": "qwen3.5:9b",
+        }
+    }
+)
+```
+
+前置条件：安装 Ollama → `ollama serve` → `ollama pull qwen3.5:9b`
+
+适用场景：大量实验迭代、离线/隐私场景。小模型结构化 JSON 可靠性弱于云端，但 lenient parser 已缓解。
+
+</details>
+
+<details>
+<summary>不带 API key 跑通</summary>
+
+`examples/basic_usage.py` 和 `examples/wiki_example.py` 默认走 mock 模式（不需要 API key、不联网）。
+
+```bash
+python examples/basic_usage.py
+# 或加真实 LLM:
+# MCS_LLM_MODE=real DEEPSEEK_API_KEY=sk-... python examples/basic_usage.py
+```
+
+</details>
+
+## 作为 MCP Server
+
+MCS 可作为 **MCP（stdio）server** 暴露 `query` / `ingest` 工具，供 Claude Desktop 等客户端把知识图谱当工具用：
+
+```bash
+pip install -e ".[mcp]"          # 可选依赖 mcp + pyyaml
+export MCS_CONFIG=/path/to/mcs.yaml   # YAML 配置（见「配置文件」）
+mcs-mcp                          # 或 python -m mcs_mcp
+```
+
+```json
+// Claude Desktop: claude_desktop_config.json
+{
+  "mcpServers": {
+    "mcs": { "command": "mcs-mcp", "args": ["--config", "/abs/path/mcs.yaml"],
+             "env": { "DEEPSEEK_API_KEY": "sk-..." } }
+  }
+}
+```
+
+> `query` 经 agent 多步探索（多轮 LLM、耗时较长）、调用经 `MemoryStore` 单 worker 串行保证 SQLite 线程亲和。详见 [MCP Server 文档](docs/mcp-server.md)。
+
+## 文档
+
+| 文档 | 说明 |
+|------|------|
+| [文档索引](docs/INDEX.md) | 所有文档的统一导航入口 |
+| [上手指南](docs/getting-started.md) | 5 分钟跑通：安装 → 写入 → 查询 → MCP → Agent |
+| [架构总览](docs/architecture.md) | 系统定位、双层结构、核心不变量、插件体系 |
+| [图模型设计](docs/graph-model-design.md) | 完整、权威的图模型与核心算法设计 |
+| [常见问题](docs/faq.md) | FAQ |
+
+## 评测
+
+MCS 使用 MultiHop-RAG 做文档级多跳检索评测，指标为 Hit@k / MAP@k / MRR@k。
+
+**最新结果**（609 篇 whole-doc 建图、200 query、DeepSeek 后端，`T=16K`）：**hit@10 ≈ 0.70 / recall@10 ≈ 0.39**（分类型 inference 0.74 / temporal 0.69 / comparison 0.67）。
+
+> ⚠️ 当前 hit@10 的最大制约是**跨语言**：建图摘要由 LLM 生成为中文，而 query 为英文，词法交集近零。反事实对照（body 换英文原文、零 LLM）可达 ~0.84——说明瓶颈在语言对齐与下游重排，而非图模型 / 召回链路本身（全节点 gold 召回 0.89+）。详见 [评测报告](bench/multihop_rag/REPORT.md)。
+
+下方命令为 200 篇子集的**快速上手**（配置与上述权威数字不同，不直接对应该数字）：
+
+```bash
+# 200 篇子集，DeepSeek 后端（相关性重排默认开）
+python -m bench.multihop_rag --llm deepseek --corpus-subset 200 --output ./mh_out
+```
+
+详见 [bench/README.md](bench/README.md)。
+
+## 贡献
+
+欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建、开发流程和提交规范。
+
+## 许可证
+
+本项目基于 [MIT 许可证](LICENSE) 开源。

mcs_core-0.1.0/README.md

@@ -0,0 +1,200 @@
+# MCS - Maximum-Context Subgraph
+
+一个**完整的通用记忆引擎**——由大模型语义驱动，把零散文本组织成图结构的语义记忆，并维持一条硬不变量，使任意节点的活跃视图永远放得进一个 LLM 上下文窗口。不依赖 embedding / 向量检索，靠大模型直接阅读"装得下的局部子图"完成关系发现、聚类与召回。
+
+MCS 默认返回相关节点集合（`List[Node]`），不是自然语言答案。它专注于"记忆本身"，把合成答案、多轮对话、追问加深等留给上层（RAG / Agent / Chatbot）。
+
+## 核心定位
+
+MCS 不假设外部知识天然就近——它靠**核心不变量 + 守门 + 聚类裂变主动维持语义局部性**：无论图如何增长，任意节点的活跃双向视图（关系边 + 层级邻居）都被收敛到语义内聚、且渲染 token ≤ 一个上下文窗口 T。因此沿关联边的语义游走总能在有界视野内到达相关知识，大模型可以一次"读完"局部视野再做判断。导航、归纳、查询都建立在这之上。
+
+## 快速开始
+
+### 安装
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate          # Windows
+# source .venv/bin/activate     # macOS / Linux
+pip install -e ".[dev]"
+```
+
+### 基本用法
+
+```python
+from mcs.presets import create_mcs
+
+# 知识图谱模式（默认配置含 Phase 1 插件）
+mcs = create_mcs(llm="deepseek", db_path="mcs.db")
+# 需先设置环境变量 DEEPSEEK_API_KEY 或传入 plugin_configs
+
+# 摄入文本 → 自动抽概念、定位、入图
+mcs.ingest("深度学习是机器学习的一个子领域，它使用多层神经网络来学习数据的表示。")
+mcs.ingest("卷积神经网络是一种专门处理网格状数据的深度学习模型。")
+
+# 查询 → 默认返回相关节点集合
+nodes = mcs.query("什么是深度学习？")
+for n in nodes:
+    print(n.name, "—", n.content[:80])
+```
+
+或使用 Builder 完整自定义：
+
+```python
+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"] = "your-api-key"
+
+builder = Phase1Builder(config)
+mcs = builder.build()  # 返回即用的 MCS 实例
+```
+
+### 配置文件（YAML）
+
+也支持从 **YAML 文件**配置（preset 铺底 + 字段叠加 + `${VAR}` 环境变量插值 + import-path 第三方插件）：
+
+```bash
+pip install -e ".[yaml]"   # 可选依赖 PyYAML
+```
+
+```yaml
+# mcs.yaml
+preset: knowledge_graph          # 复用默认 Phase1 插件集，只覆盖要改的字段
+write_llm: deepseek
+plugin_configs:
+  deepseek_llm:
+    api_key: ${DEEPSEEK_API_KEY}  # 秘密走环境、不进文件
+  sqlite_storage:
+    path: mcs.db
+shared_plugins:
+  - my_pkg.exts:MyEdgeExtension   # import-path 第三方插件
+```
+
+```python
+from mcs.entities.config import MCSConfig
+from mcs.presets import Phase1Builder
+
+config = MCSConfig.from_file("mcs.yaml")
+mcs = Phase1Builder(config).build()
+```
+
+> ⚠️ 配置文件是**受信输入**：YAML 经 import-path 可加载任意代码，**勿接受陌生来源**。
+> 自定义 LLM 必须走**无 preset** 路径（`knowledge_graph()` 只认 deepseek/claude/ollama）。
+> 详见 [配置文件文档](docs/configuration.md)。
+
+### 切换后端
+
+<details>
+<summary>Claude / Anthropic 后端</summary>
+
+```python
+mcs = create_mcs(
+    llm="claude",
+    db_path="mcs.db",
+    plugin_configs={
+        "claude_llm": {
+            "auth_token": "your-anthropic-token",
+            "model": "claude-3-5-sonnet-latest",
+            "base_url": "https://api.anthropic.com",
+        }
+    }
+)
+```
+
+需先安装：`pip install -e ".[claude]"`
+
+</details>
+
+<details>
+<summary>Ollama 本地后端（零 token 成本）</summary>
+
+```python
+mcs = create_mcs(
+    llm="ollama",
+    db_path="mcs.db",
+    plugin_configs={
+        "ollama_llm": {
+            "base_url": "http://localhost:11434/v1",
+            "model": "qwen3.5:9b",
+        }
+    }
+)
+```
+
+前置条件：安装 Ollama → `ollama serve` → `ollama pull qwen3.5:9b`
+
+适用场景：大量实验迭代、离线/隐私场景。小模型结构化 JSON 可靠性弱于云端，但 lenient parser 已缓解。
+
+</details>
+
+<details>
+<summary>不带 API key 跑通</summary>
+
+`examples/basic_usage.py` 和 `examples/wiki_example.py` 默认走 mock 模式（不需要 API key、不联网）。
+
+```bash
+python examples/basic_usage.py
+# 或加真实 LLM:
+# MCS_LLM_MODE=real DEEPSEEK_API_KEY=sk-... python examples/basic_usage.py
+```
+
+</details>
+
+## 作为 MCP Server
+
+MCS 可作为 **MCP（stdio）server** 暴露 `query` / `ingest` 工具，供 Claude Desktop 等客户端把知识图谱当工具用：
+
+```bash
+pip install -e ".[mcp]"          # 可选依赖 mcp + pyyaml
+export MCS_CONFIG=/path/to/mcs.yaml   # YAML 配置（见「配置文件」）
+mcs-mcp                          # 或 python -m mcs_mcp
+```
+
+```json
+// Claude Desktop: claude_desktop_config.json
+{
+  "mcpServers": {
+    "mcs": { "command": "mcs-mcp", "args": ["--config", "/abs/path/mcs.yaml"],
+             "env": { "DEEPSEEK_API_KEY": "sk-..." } }
+  }
+}
+```
+
+> `query` 经 agent 多步探索（多轮 LLM、耗时较长）、调用经 `MemoryStore` 单 worker 串行保证 SQLite 线程亲和。详见 [MCP Server 文档](docs/mcp-server.md)。
+
+## 文档
+
+| 文档 | 说明 |
+|------|------|
+| [文档索引](docs/INDEX.md) | 所有文档的统一导航入口 |
+| [上手指南](docs/getting-started.md) | 5 分钟跑通：安装 → 写入 → 查询 → MCP → Agent |
+| [架构总览](docs/architecture.md) | 系统定位、双层结构、核心不变量、插件体系 |
+| [图模型设计](docs/graph-model-design.md) | 完整、权威的图模型与核心算法设计 |
+| [常见问题](docs/faq.md) | FAQ |
+
+## 评测
+
+MCS 使用 MultiHop-RAG 做文档级多跳检索评测，指标为 Hit@k / MAP@k / MRR@k。
+
+**最新结果**（609 篇 whole-doc 建图、200 query、DeepSeek 后端，`T=16K`）：**hit@10 ≈ 0.70 / recall@10 ≈ 0.39**（分类型 inference 0.74 / temporal 0.69 / comparison 0.67）。
+
+> ⚠️ 当前 hit@10 的最大制约是**跨语言**：建图摘要由 LLM 生成为中文，而 query 为英文，词法交集近零。反事实对照（body 换英文原文、零 LLM）可达 ~0.84——说明瓶颈在语言对齐与下游重排，而非图模型 / 召回链路本身（全节点 gold 召回 0.89+）。详见 [评测报告](bench/multihop_rag/REPORT.md)。
+
+下方命令为 200 篇子集的**快速上手**（配置与上述权威数字不同，不直接对应该数字）：
+
+```bash
+# 200 篇子集，DeepSeek 后端（相关性重排默认开）
+python -m bench.multihop_rag --llm deepseek --corpus-subset 200 --output ./mh_out
+```
+
+详见 [bench/README.md](bench/README.md)。
+
+## 贡献
+
+欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解环境搭建、开发流程和提交规范。
+
+## 许可证
+
+本项目基于 [MIT 许可证](LICENSE) 开源。

mcs_core-0.1.0/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-0.1.0/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.
+"""