prolog-reasoner

SWI-Prolog as a "logic calculator" for LLMs — available as an MCP server and a Python library. Eliminate the black box from LLM logical reasoning.

LLMs excel at natural language but struggle with formal logic. Prolog excels at logical reasoning but can't process natural language.prolog-reasonerbridges this gap by exposing SWI-Prolog execution to LLMs.

On the built-in 30-problem logic benchmark:

The gap concentrates in constraint satisfaction and multi-step reasoning — the combinatorial territory LLMs are weak on and Prolog is strong on.Full breakdown below.

- Python ≥ 3.10
- SWI-Prologinstalled and on PATH (≥ 9.0)
- API key for OpenAI or Anthropic —only for library mode, not for the MCP server

# 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]

The MCP server exposes five tools —execute_prologruns Prolog code written by the connected LLM, and four rule-base tools manage named, reusable Prolog modules. It doesnotcall any external LLM API, so no API key is required.

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

Or, ifprolog-reasoneris installed directly:

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

Use Docker if you don't want to install SWI-Prolog locally:

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 facts and rules (string)
- query— Prolog query to run, e.g."mortal(X)"(string)
- rule_bases— optional list of saved rule base names to prepend toprolog_code(in order). Use this to reuse stable domain rules across calls without re-sending them
- max_results— cap the number of solutions returned (default 100)
- trace— whenTrue, attach a structured proof tree per solution tometadata.proof_trace. Opt-in sub-feature; has performance overhead and does not support CLP(FD), higher-order predicates, or assert/retract.

Returns a JSON object withsuccess,output,query,error, andmetadata.

On success,metadataincludesexecution_time_ms,result_count,truncated, andrule_bases_used. When rule bases were requested,rule_base_load_msis also attached (disk I/O timing). On failure,metadataalso includeserror_category(one ofsyntax_error,undefined_predicate,unbound_variable,type_error,domain_error,evaluation_error,permission_error,timeout,trace_mechanism_error,unknown) anderror_explanation— a natural-language hint for the connected LLM (or human) to decide how to fix the Prolog code.

Rule base tools— manage named, reusable Prolog modules underPROLOG_REASONER_RULES_DIR(defaults to~/.prolog-reasoner/rules/). 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 the write; failures surface asRULEBASE_003. Returns{"success": true, "name": ..., "created": bool}wherecreatedistrueon first write,falseon overwrite. Files overmax_rule_sizeare rejected withRULEBASE_005.
- list_rule_bases()— return all saved rule bases withname,description, andtags. Metadata is extracted from leading% description:/% tags:comments in each file.
- get_rule_base(name)— return the raw Prolog source of a saved rule base.
- delete_rule_base(name)— remove a saved rule base.

For name/size/existence errors, the tools return{"success": false, "error": "...", "error_code": "RULEBASE_001"|"RULEBASE_002"|"RULEBASE_003"|"RULEBASE_005"}rather than raising. I/O failures (RULEBASE_004) are propagated as infrastructure errors.

Rule base conventions— start each rule base file with leading comments that double aslist_rule_basesmetadata:

% description: Chess piece movement rules % tags: chess, games piece_move(knight, (X1,Y1), (X2,Y2)) :- ...

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

Rule bases also serve as the foundation for domain-specialized forks: ship a curated set (legal axioms, game rules, tax scenarios, etc.) bundled viaBUNDLED_RULES_DIRas a ready-to-use reasoning package.

The library exposesPrologExecutor(Prolog-only, no LLM) andPrologReasoner(NL→Prolog pipeline, needs an LLM API key).

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())

Full NL→Prolog pipeline (requires LLM API key)

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())

All settings via environment variables (prefixPROLOG_REASONER_):

benchmarks/contains 30 logic problems across 5 categories (deduction, transitive, constraint, contradiction, multi-step) to compare LLM-only reasoning vs LLM+Prolog reasoning. The benchmark exercises thelibrarypath (translator + executor), since it requires the NL→Prolog step.

Measured onanthropic/claude-sonnet-4-6, single run over 30 problems:

The gap is concentrated inconstraint(SEND+MORE, 6-queens, knapsack, K4 coloring, Einstein-lite) andmulti-step(Nim game theory, 3-person knights-and-knaves, TSP-4, zebra puzzle) — exactly the combinatorial/search-heavy territory where symbolic solvers outperform pattern completion. On purely deductive or transitive questions the LLM is already strong and Prolog adds latency without accuracy gains.

All 3 LLM+Prolog failures were Prolog execution errors from malformed LLM-generated code (missing predicate definitions, unbound CLP(FD) variables) rather than reasoning errors — addressable via prompt tuning. Notably, every failure is inspectable: you can see the exact Prolog that failed and why, rather than a wrong natural-language answer with no explanation.

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

Results are saved tobenchmarks/results.json.

Several Prolog MCP servers exist, each with different design choices.prolog-reasoneris intentionally stateless and spot-use — Prolog is a calculator you call when logic matters, not the backbone of your agent's memory.

This is also why accuracy benchmarks are published here and not elsewhere: statelessness is what makes a side-by-side comparison possible.

If you need persistent agent memory, hallucination-safeguarded fact storage, or a full neuro-symbolic substrate, other projects may fit better:

- adamrybinski/prolog-mcp— Trealla WASM with save/load sessions
- umuro/prolog-mcp— layered KB with file-backed persistence
- vpursuit/model-context-lab— SWI-Prolog with security sandboxing
- dr3d/prolog-reasoning— neuro-symbolic memory with write-path safety

# 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

Rewrites coding prompts for optimal results with AI IDEs like Cursor AI, powered by Claude by Anthropic.