prolog-reasoner

PyPI version Python versions License: MIT

SWI-Prolog 作为 LLM 的“逻辑计算器”——提供 MCP 服务器和 Python 库两种形式。

LLM 擅长自然语言，但在形式逻辑方面表现欠佳。Prolog 擅长逻辑推理，但无法处理自然语言。prolog-reasoner 通过两种互补的方式将 SWI-Prolog 执行能力暴露给 LLM，从而弥补了这一差距：

MCP 服务器 — 连接的 LLM（例如 Claude）编写 Prolog 代码并通过服务器执行。服务器端无需 LLM API 密钥。
Python 库 — 一个完整的 NL→Prolog 流水线，具备自我修正功能，适用于不涉及 LLM 循环的程序。需要 OpenAI 或 Anthropic API 密钥。

两种方式共享同一个 Prolog 执行器；库在此基础上增加了一个基于 LLM 的翻译器。

特性

MCP 工具 (execute_prolog)：运行带有查询的任意 SWI-Prolog 代码
CLP(FD) 支持：用于调度和优化的约束逻辑编程
失败即否定 (Negation-as-failure)、递归、所有标准 SWI-Prolog 特性
透明的中间表示：在执行前检查/修改 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 的工具，用于运行由连接的 LLM 编写的 Prolog 代码。它不调用任何外部 LLM 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, max_results=100)

prolog_code — Prolog 事实和规则（字符串）
query — 要运行的 Prolog 查询，例如 "mortal(X)"（字符串）
max_results — 限制返回的解决方案数量（默认 100）

返回一个包含 success、output、query、error 和 metadata（执行时间、结果计数、截断标志）的 JSON 对象。

库使用方法

该库提供了 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`	两者
`LOG_LEVEL`	`INFO`	两者

基准测试

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

结果

在 anthropic/claude-sonnet-4-6 上测量，对 30 个问题进行单次运行：

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

各类别细分：

类别	仅 LLM	LLM + Prolog
演绎	6/6	6/6
传递	6/6	5/6
约束	3/7	6/7
矛盾	4/4	3/4
多步	3/7	7/7

差距主要集中在约束（SEND+MORE、6皇后、背包问题、K4着色、爱因斯坦谜题简化版）和多步（Nim 游戏理论、3人骑士与无赖、TSP-4、斑马谜题）——这正是符号求解器优于模式补全的组合/搜索密集型领域。在纯演绎或传递性问题上，LLM 本身就很强，Prolog 反而增加了延迟且没有准确率提升。

所有 3 个 LLM+Prolog 的失败案例都是由于 LLM 生成的代码格式错误（缺少谓词定义、未绑定的 CLP(FD) 变量）导致的 Prolog 执行错误，而非推理错误——可以通过提示词优化来解决。

自行运行

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

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

开发

# 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

prolog-reasoner

prolog-reasoner

特性

要求

安装

MCP 服务器设置

Claude Desktop / Claude Code

Docker (捆绑 SWI-Prolog)

工具参考

库使用方法

直接执行 Prolog（无 LLM）

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

配置

基准测试

结果

自行运行

开发

许可证

Resources

Tools

Latest Blog Posts

MCP directory API