prolog-reasoner

Purpose

prolog-reasoner exposes SWI-Prolog to large language models (LLMs) as a "logic calculator" to eliminate the black-box problem in LLM logical reasoning. LLMs are good at natural language but struggle with formal logic, while Prolog is good at logical reasoning but cannot handle natural language. This tool bridges that gap by having the LLM write and execute Prolog code.

Main Capabilities

• MCP server: Claude or any MCP client can call it as a logic solver during a conversation. Rule bases let the LLM save stable domain rules once and reference them by name on each call.
• Python library: Provides a complete natural language to Prolog pipeline with a self-correction loop, requiring an OpenAI or Anthropic API key.
• MCP tools:execute_prolog for executing arbitrary SWI-Prolog code;list_rule_bases、get_rule_base、save_rule_base、delete_rule_base for managing reusable named rule bases.
• Rule bases: Save stable Prolog rules once (for example chess move rules, legal axioms) and reference them by name from execute_prolog , so the LLM only needs to write facts relevant to the specific situation on each call.
• Transparent intermediate representation: The Prolog code itself is the audit trail and can be inspected, modified, or verified before execution.
• CLP(FD) support: Constraint logic programming for scheduling and optimization.
• Negation as failure, recursion, and all standard SWI-Prolog features.
• Library mode: Natural language to Prolog translation with a self-correction loop (OpenAI / Anthropic).

Usage

Requirements

• SWI-Prolog installed and on the PATH (version ≥ 9.0).
• An OpenAI or Anthropic API key — required only for library mode, not for the MCP server.

MCP server setup

The MCP server exposes five tools:execute_prolog runs Prolog code written by the connected LLM, and four rule base tools manage named reusable Prolog modules. It does not call any external LLM API, so no API key is needed.

Claude Desktop / Claude Code is supported, and it can also be used after installing prolog-reasoner directly. If you do not want to install SWI-Prolog locally, you can use Docker (SWI-Prolog is already bundled).

execute_prolog parameters

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

• prolog_code — Prolog facts and rules (string).
• query — The Prolog query to run, for example "mortal(X)"(string).
• rule_bases — Optional, a list of saved rule base names to prepend to prolog_code (in order). Used to reuse stable domain rules across calls without resending them.
• max_results — Maximum number of solutions to return (default 100).
• trace — When True, append a structured proof tree in metadata.proof_trace for each solution. This is an optional subfeature, has a performance overhead, and does not support CLP(FD), higher-order predicates, or assert/retract.

Returns a JSON object containing success、output、query、error and metadata . On success,metadata contains execution_time_ms、result_count、truncated and rule_bases_used; when a rule base is requested, rule_base_load_msis also appended (disk I/O timing). On failure,metadata also contains error_category(one of syntax_error, undefined_predicate, unbound_variable, type_error, domain_error, evaluation_error, permission_error, timeout, trace_mechanism_error, unknown) and error_explanation— a natural language hint for the connected LLM or human to decide how to fix the Prolog code.

Rule base tools

In PROLOG_REASONER_RULES_DIR(Default ~/.prolog-reasoner/rules/) manages named reusable Prolog modules. Names are restricted to [a-z0-9_-], length 1–64.

• save_rule_base(name, content) — Write or overwrite a rule base. Content is syntax-validated (parse only) before writing; failure is presented as RULEBASE_003 . Returns {"success": true, "name": ..., "created": bool}, with created true on first write and false on overwrite. Files exceeding max_rule_size are rejected with RULEBASE_005 .
• list_rule_bases() — Returns all saved rule bases along with their name、description and tags. Metadata is extracted from the % description: / % tags: comment at the beginning of each file.
• get_rule_base(name) — Returns the raw Prolog source of a saved rule base.
• delete_rule_base(name) — Deletes a saved rule base.

For name/size/existence errors, the tool returns {"success": false, "error": "...", "error_code": "RULEBASE_001"|"RULEBASE_002"|"RULEBASE_003"|"RULEBASE_005"} rather than throwing an exception. I/O failures (RULEBASE_004) propagate as infrastructure errors.

Rule base conventions: each rule base file uses a leading comment as metadata for list_rule_bases , then is referenced from execute_prolog . Rule bases can also serve as the basis for domain-specific branches: bundle a curated set of rules (legal axioms, game rules, tax scenarios, etc.) via BUNDLED_RULES_DIR as a ready-to-use reasoning package.

Python Library

The library exposes PrologExecutor(Prolog only, no LLM) and PrologReasoner(natural language to Prolog pipeline, requires an LLM API key).

• Direct Prolog execution (no LLM).
• Full natural language to Prolog pipeline (requires an LLM API key).

All settings are via environment variables (prefix PROLOG_REASONER_).

Use Cases

• Constraint satisfaction problems (e.g., SEND+MORE, 6 queens, knapsack, K4 coloring, simplified Einstein puzzle).
• Multi-step reasoning (e.g., Nim game theory, three knights and knaves, TSP-4, zebra puzzle).
• Logic tasks requiring an auditable, debuggable reasoning process.
• As an ad-hoc logic solver for LLMs, rather than the backbone of agent memory.

Limitations

• Requires SWI-Prolog ≥ 9.0 and it must be in PATH.
• Library mode requires an OpenAI or Anthropic API key; the MCP server does not.
• The trace feature has performance overhead and does not support CLP(FD), higher-order predicates, or assert/retract.
• On purely deductive or transitive problems, the LLM itself is already strong, and Prolog adds latency without improving accuracy.
• In benchmarks, all LLM+Prolog failures come from Prolog execution errors in LLM-generated code (missing predicate definitions, unbound CLP(FD) variables), not reasoning errors, and can be resolved through prompt tuning.
• The project is intentionally designed to be stateless and ad-hoc; if you need persistent agent memory, hallucination-proof fact storage, or a full neuro-symbolic substrate, other projects may be more suitable.

Benchmarks

benchmarks/ contains 30 logic problems divided into 5 categories (deduction, transitivity, constraints, contradiction, multi-step), used to compare pure LLM reasoning with LLM+Prolog reasoning. The benchmark uses the library path (translator + executor) because it requires the natural language to Prolog step. Measurements from a single run of 30 problems on anthropic/claude-sonnet-4-6 show that the gap is concentrated in the constraints and multi-step categories—precisely the combination/search-intensive domains where symbolic solvers outperform pattern completion. Results are saved to benchmarks/results.json。