Prolog Reasoner

prolog-reasoner

将 SWI-Prolog 作为大模型的“逻辑计算器”——可用作 MCP 服务和 Python 库。消除大模型逻辑推理中的黑箱。

大模型擅长自然语言，但在形式逻辑方面表现不佳。Prolog 擅长逻辑推理，但无法处理自然语言。prolog-reasoner 通过向大模型开放 SWI-Prolog 执行能力，弥合了这一差距。

它有帮助吗？

在内置的 30 道逻辑题基准测试中：

流程	准确率
仅使用大模型（claude-sonnet-4-6）	22/30（73.3%）
大模型 + prolog-reasoner	27/30（90.0%）

差距主要体现在约束满足和多步推理上——这些组合问题领域是大模型的弱项，却是 Prolog 的强项。下方查看完整分析。

为什么有效

大模型进行模式匹配；Prolog 则会实际搜索并求解。当大模型将问题写成 Prolog 代码时，会同时带来两项好处：

• Prolog 负责大模型不擅长的组合计算——约束满足、多步推理和穷举搜索。
• 推理过程以代码形式呈现，可供阅读、重新运行和调试。出现问题时，你可以看到出错的确切 Prolog 代码及其原因。

两种使用方式

• MCP 服务 — Claude（或任何 MCP 客户端）可在对话中将其用作逻辑求解器。借助规则库，大模型可以保存稳定的领域规则，并在每次调用时按名称引用。
• Python 库 — 提供带自我修正功能的完整 NL→Prolog 流程。需要 OpenAI 或 Anthropic。

功能特性

• MCP 工具：execute_prolog 用于执行任意 SWI-Prolog 代码；list_rule_bases / get_rule_base / save_rule_base / delete_rule_base 用于管理可复用的具名规则库（v14）
• 规则库：一次性保存稳定的 Prolog 规则（例如国际象棋走法规则、法律公理），并在 execute_prolog 中按名称引用，使大模型每次调用时只需编写与具体情境相关的事实
• 透明的中间表示：Prolog 代码就是审计记录——执行前可检查、修改或验证
• 支持 CLP(FD)：用于调度和优化的约束逻辑编程
• 失败即否定、递归及所有标准 SWI-Prolog 功能
• 库模式：带自我修正循环的 NL→Prolog 转换（OpenAI / Anthropic）

要求

• Python ≥ 3.10
• 已安装 SWI-Prolog，且位于 PATH 中（≥ 9.0）
• OpenAI 或 Anthropic 的 API 密钥——仅库模式需要，MCP 服务无需此密钥

安装

# MCP server only (no LLM dependencies)
pip install prolog-reasoner

# Library with OpenAI
pip install prolog-reasoner[openai]

# Library with Anthropic
pip install prolog-reasoner[anthropic]

# Both providers
pip install prolog-reasoner[all]

MCP 服务设置

MCP 服务提供五种工具——execute_prolog 用于运行已连接的大模型编写的 Prolog 代码，另外四种规则库工具用于管理具名且可复用的 Prolog 模块。它不会调用任何外部大模型 API，因此无需 API 密钥。

Claude Desktop / Claude Code

{
  "mcpServers": {
    "prolog-reasoner": {
      "command": "uvx",
      "args": ["prolog-reasoner"]
    }
  }
}

或者，如果直接安装了 prolog-reasoner：

{
  "mcpServers": {
    "prolog-reasoner": {
      "command": "prolog-reasoner"
    }
  }
}

Docker（内置 SWI-Prolog）

如果不想在本地安装 SWI-Prolog，可以使用 Docker：

docker build -f docker/Dockerfile -t prolog-reasoner .

{
  "mcpServers": {
    "prolog-reasoner": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "prolog-reasoner"]
    }
  }
}

工具参考

execute_prolog(prolog_code, query, rule_bases=None, max_results=100, trace=False)

• prolog_code — Prolog 事实和规则（字符串）
• query — 要运行的 Prolog 查询，例如 "mortal(X)"（字符串）
• rule_bases — 可选的已保存规则库名称列表，按顺序添加到 prolog_code 前。可用它在多次调用间复用稳定的领域规则，无需重复发送
• max_results — 返回的解的数量上限（默认值为 100）
• trace — 为 True 时，会在每个解的 metadata.proof_trace 中附加结构化证明树。此可选子功能会带来性能开销，且不支持 CLP(FD)、高阶谓词或 assert/retract。

返回包含 success、output、query、error 和 metadata 的 JSON 对象。

成功时，metadata 包含 execution_time_ms、result_count、truncated 和 rule_bases_used。如果请求了规则库，还会附加 rule_base_load_ms（磁盘 I/O 耗时）。失败时，metadata 还包含 error_category（取值之一：syntax_error、undefined_predicate、unbound_variable、type_error、domain_error、evaluation_error、permission_error、timeout、trace_mechanism_error、unknown）和 error_explanation——为连接的 LLM（或人类）提供自然语言提示，以便决定如何修复 Prolog 代码。

规则库工具 — 管理 PROLOG_REASONER_RULES_DIR 下具名、可复用的 Prolog 模块（默认路径为 ~/.prolog-reasoner/rules/）。名称仅限 [a-z0-9_-]，长度为 1–64。

• save_rule_base(name, content) — 写入或覆盖规则库。写入前会验证内容的语法（仅解析）；验证失败会返回 RULEBASE_003。返回 {"success": true, "name": ..., "created": bool}，其中首次写入时 created 为 true，覆盖时为 false。超过 max_rule_size 的文件会被拒绝，并返回 RULEBASE_005。
• list_rule_bases() — 返回所有已保存规则库及其 name、description 和 tags。元数据从每个文件开头的 % description: / % tags: 注释中提取。
• get_rule_base(name) — 返回已保存规则库的原始 Prolog 源码。
• delete_rule_base(name) — 删除已保存的规则库。

对于名称、大小或存在性错误，工具会返回 {"success": false, "error": "...", "error_code": "RULEBASE_001"|"RULEBASE_002"|"RULEBASE_003"|"RULEBASE_005"}，而不是抛出异常。I/O 故障（RULEBASE_004）会作为基础设施错误传播。

规则库约定 — 每个规则库文件都应以开头注释起始，这些注释也用作 list_rule_bases 的元数据：

% description: Chess piece movement rules
% tags: chess, games

piece_move(knight, (X1,Y1), (X2,Y2)) :- ...

然后在 execute_prolog 中引用：

{
  "rule_bases": ["chess_moves"],
  "prolog_code": "position(knight, (4,4)).",
  "query": "piece_move(knight, (4,4), Target)"
}

规则库还是构建领域专用分支的基础：通过 BUNDLED_RULES_DIR 打包精选规则集（法律公理、游戏规则、税务场景等），将其作为开箱即用的推理包。

库的使用

该库提供 PrologExecutor（仅 Prolog，不使用 LLM）和 PrologReasoner（NL→Prolog 流程，需要 LLM API 密钥）。

直接执行 Prolog（不使用 LLM）

import asyncio
from prolog_reasoner.config import Settings
from prolog_reasoner.executor import PrologExecutor

async def main():
    settings = Settings()  # no API key needed
    executor = PrologExecutor(settings)
    result = await executor.execute(
        prolog_code="human(socrates). mortal(X) :- human(X).",
        query="mortal(X)",
    )
    print(result.output)  # mortal(socrates)

asyncio.run(main())

完整的 NL→Prolog 流程（需要 LLM API 密钥）

import asyncio
from prolog_reasoner import PrologReasoner, TranslationRequest, ExecutionRequest
from prolog_reasoner.config import Settings
from prolog_reasoner.executor import PrologExecutor
from prolog_reasoner.translator import PrologTranslator
from prolog_reasoner.llm_client import LLMClient

async def main():
    settings = Settings(llm_api_key="sk-...")  # from env or explicit
    llm = LLMClient(
        provider=settings.llm_provider,
        api_key=settings.llm_api_key,
        model=settings.llm_model,
        timeout_seconds=settings.llm_timeout_seconds,
    )
    reasoner = PrologReasoner(
        translator=PrologTranslator(llm, settings),
        executor=PrologExecutor(settings),
    )
    translation = await reasoner.translate(
        TranslationRequest(query="Socrates is human. All humans are mortal. Is Socrates mortal?")
    )
    print(translation.prolog_code)
    result = await reasoner.execute(
        ExecutionRequest(prolog_code=translation.prolog_code, query=translation.suggested_query)
    )
    print(result.output)

asyncio.run(main())

配置

所有设置均通过环境变量配置（前缀为 PROLOG_REASONER_）：

变量	默认值	适用于
LLM_PROVIDER	openai	库（openai 或 anthropic）
LLM_API_KEY	""	仅限库 — MCP 无需设置
LLM_MODEL	gpt-5.4-mini	库
LLM_TEMPERATURE	0.0	库
LLM_TIMEOUT_SECONDS	30.0	库
SWIPL_PATH	swipl	两者
EXECUTION_TIMEOUT_SECONDS	10.0	两者
RULES_DIR	~/.prolog-reasoner/rules	两者（用户保存的规则库所在位置）
BUNDLED_RULES_DIR	未设置	两者（可选 — 首次启动时同步到 RULES_DIR，以便在分支项目中附带默认规则）
MAX_RULE_SIZE	1048576 (1 MiB)	两者（单个文件的保存上限；save_rule_base 会拒绝超出上限的内容，并返回 RULEBASE_005）
MAX_RULE_PROMPT_BYTES	65536 (64 KiB)	仅限库（“Available rule bases”提示词部分的总字节数上限；超出时会截断并添加标记）
LOG_LEVEL	INFO	两者

基准测试

benchmarks/ 包含 5 个类别（演绎、传递性、约束、矛盾、多步）中的 30 道逻辑题，用于比较仅使用 LLM 推理与使用 LLM+Prolog 推理的效果。基准测试采用库路径（翻译器 + 执行器），因为它需要执行 NL→Prolog 步骤。

结果

在 anthropic/claude-sonnet-4-6 上对 30 道题进行单次测试：

流程	准确率	平均延迟
仅 LLM	22/30 (73.3%)	1.7s
LLM + Prolog	27/30 (90.0%)	3.8s

各类别明细：

类别	仅 LLM	LLM + Prolog
deduction	6/6	6/6
transitive	6/6	5/6
constraint	3/7	6/7
contradiction	4/4	3/4
multi-step	3/7	7/7

差距主要集中在约束（SEND+MORE、6 皇后、背包问题、K4 着色、Einstein-lite）和多步（Nim 博弈论、3 人骑士与无赖、TSP-4、斑马谜题）领域——这些正是组合搜索密集型问题，也是符号求解器优于模式补全的领域。对于纯演绎或传递性问题，LLM 本身已经表现出色，而 Prolog 只会增加延迟，准确率却没有提升。

LLM+Prolog 的 3 次失败都是由格式错误的 LLM 生成代码导致的 Prolog 执行错误（缺少谓词定义、CLP(FD) 变量未绑定），而非推理错误——可通过调整提示词来解决。值得注意的是，每次失败都可以检查：你可以看到执行失败的确切 Prolog 代码及其原因，而不是一个没有解释的错误自然语言答案。

亲自运行

docker run --rm -e PROLOG_REASONER_LLM_API_KEY=sk-... \
    prolog-reasoner-dev python benchmarks/run_benchmark.py

结果会保存到 benchmarks/results.json。

与其他 Prolog MCP 的比较

现有多个 Prolog MCP 服务，各自采用了不同的设计方案。prolog-reasoner 有意设计为无状态、按需使用——Prolog 是在需要逻辑推理时调用的计算器，而不是 Agent 记忆的底层支柱。

	prolog-reasoner	有状态的 Prolog MCP
Prolog 的作用	按次调用的推理工具	项目级知识库
状态	无状态执行（每次调用互相独立）；可选用命名的规则库复用静态规则，不保留调用间的会话记忆	持久会话／分层知识库
可复现性	相同输入（包括相同规则库）→ 始终得到相同输出	取决于累积的状态
集成成本	在需要逻辑推理时使用，不需要时跳过	需要在架构上作出承诺
可与仅使用 LLM 的方案进行 A/B 测试	可以（每次调用都是受控实验）	在结构上无法比较

这也是准确率基准测试只在这里发布的原因：无状态设计使并排比较成为可能。

如果你需要持久的 Agent 记忆、带防幻觉机制的事实存储，或完整的神经符号底层架构，其他项目可能更适合：

• adamrybinski/prolog-mcp — Trealla WASM，支持保存／加载会话
• umuro/prolog-mcp — 分层知识库，支持基于文件的持久化
• vpursuit/model-context-lab — SWI-Prolog，带安全沙箱
• dr3d/prolog-reasoning — 神经符号记忆，带写入路径安全机制

我们是按需使用的选择。

开发

# Build dev image
docker build -f docker/Dockerfile -t prolog-reasoner-dev .

# Run tests (no API key needed — LLM calls are mocked)
docker run --rm prolog-reasoner-dev

# With coverage
docker run --rm prolog-reasoner-dev pytest tests/ -v --cov=prolog_reasoner

# Or via docker compose
docker compose -f docker/docker-compose.yml run --rm test

许可证

MIT