rikarazome/prolog-reasoner

Added

Rule bases

Named, reusable Prolog modules stored as .pl files under PROLOG_REASONER_RULES_DIR (default ~/.prolog-reasoner/rules/). Four new MCP tools — save_rule_base, list_rule_bases, get_rule_base, delete_rule_base — manage them, and execute_prolog accepts a rule_bases: list[str] parameter that prepends the named modules (in order, deduped) to the user-supplied Prolog code.

Library equivalents: ExecutionRequest.rule_bases and TranslationRequest.rule_bases; the translator exposes the saved bodies to the LLM via an "Available rule bases" prompt section so it can reuse existing predicate names. Metadata exposes rule_bases_used on every execution and rule_base_load_ms when disk I/O occurred.

Rules are name-validated ([a-zA-Z0-9_-]{1,64}), syntax-validated on save via a parse-only read_term loop (with CLP(FD) operator prelude), size-capped at PROLOG_REASONER_MAX_RULE_SIZE (default 1 MiB), and written atomically via mkstemp + os.replace. Bundled rule bases shipped by a fork via PROLOG_REASONER_BUNDLED_RULES_DIR are copied into RULES_DIR once on startup (copy-on-first-use; user edits preserved). Prompt injection is capped separately at PROLOG_REASONER_MAX_RULE_PROMPT_BYTES (default 64 KiB).

New error taxonomy: RuleBaseError with codes RULEBASE_001 (not found, includes difflib suggestion) / RULEBASE_002 (invalid name) / RULEBASE_003 (syntax error on save) / RULEBASE_004 (I/O failure, propagated as infrastructure error) / RULEBASE_005 (oversize); ConfigurationError code CONFIG_002 for bundled-sync failures at server startup. Leading % description: / % tags: comments in rule-base files surface as metadata from list_rule_bases.

Structured error classification

ExecutionResult.metadata now exposes error_category (syntax_error / undefined_predicate / unbound_variable / type_error / domain_error / evaluation_error / permission_error / timeout / unknown) and error_explanation (natural-language hint). The raw error field is preserved for callers that need the original SWI-Prolog output.

Opt-in proof trace

trace: bool = False parameter on execute_prolog (MCP) and PrologExecutor.execute() (library). When enabled, metadata.proof_trace returns a list of structured Prolog term strings — one per solution — built by a meta-interpreter ('$pr_prove'/2) that introspects rule application via clause/2. Constructors: proof(Goal, Body), builtin(Goal), negation_as_failure(Goal), opaque(Goal), conjunction tuples. Includes a new trace_mechanism_error category for self-detected meta-interpreter bugs. Default behavior (trace=False) unchanged. Known limitation: CLP(FD)-bearing code is not supported with trace=True.

PyPI: https://pypi.org/project/prolog-reasoner/0.2.0/