Logical English (LE) is a controlled natural language for legal and business logic. It allows experts to write executable rules that look like plain English, which are then automatically translated into formal logic (Prolog) for reasoning and explanation.
LE 2.0 is a modernized, high-performance implementation of the original Logical English project.
Logical English is designed to be readable by non-programmers while remaining mathematically precise.
- Template-based: Define your own natural language patterns (e.g.,
*a person* acquires British citizenship on *a date*). - Rule-oriented: Write logic using
if,and,or. - Explainable: Every answer comes with a justification tree in natural language.
- Typed: Built-in support for types, dates, and arithmetic.
Learn more about LE Syntax | Cheat sheet | View Examples
The LE 2.0 environment provides a powerful, web-based IDE for developing and testing logic:
- Real-time Feedback: Instant syntax highlighting and error reporting as you type.
- Integrated Debugger: Step through logic and visualize explanation trees.
- Scenario Testing: Define "Scenarios" (facts) and "Queries" within the same file to verify behavior.
- LSP Support: Modern editor features including autocompletion and hover information.
Editor Summary | Debugger Design
You can configure the deployment using the following environment variables:
NO_RESTRICTIONS: Set totrueto disable example path restrictions.ALLOWED_LE_EXPORTS: Comma-separated list of allowed /source web endpoint export paths.OPENAI_API_KEY: API key for OpenAI models.ANTHROPIC_API_KEY: API key for Anthropic models.GEMINI_API_KEY,GOOGLE_API_KEY,GOOGLE_GENERATIVE_AI_API_KEY: API key for Google Gemini models.GROQ_API_KEY: API key for Groq models.TOGETHER_API_KEY,TOGETHERAI_API_KEY: API key for Together AI models.
To run Logical English 2.0 on your local machine:
- Install SWI-Prolog: Download and install SWI-Prolog (version 9.0 or later recommended).
- Clone the Repository:
git clone https://github.com/mcalejo/LogicalEnglish2.git cd LogicalEnglish2 - Start the Server:
The editor will be available at
swipl -g "use_module(classic_web_api), start_api_server(3050)" classic_web_api.plhttp://localhost:3050/editor/.
The quickest way to run everything is the aggregate runner in testing/
(it always runs from the repo root, regardless of your current directory):
testing/run_tests.sh # run all suites and report a combined pass/fail
testing/run_tests.sh --no-e2e # skip the browser tests (fast: unit + LE examples)
testing/run_tests.sh unit # only the Prolog plunit suite
testing/run_tests.sh le # only the Logical English example tests (core)
testing/run_tests.sh e2e # only the Playwright browser tests
testing/run_tests.sh --with-extensions # LE examples incl. extension-dependent trees
testing/run_tests.sh le --with-extensions # ... just that suiteIt exits non-zero if any suite that ran failed. The Playwright suite is skipped
(not failed) when its prerequisites are missing, unless CI is set. Override the
interpreter with SWIPL=/path/to/swipl testing/run_tests.sh.
The Logical English example suite comes in two variants:
| suite | what it runs | when |
|---|---|---|
| core (default) | Every example that runs on this repository alone. | Gate CI on this. It is the suite a clean checkout can make green. |
all (--with-extensions) |
core, plus the example trees that need the proprietary le_extensions.pl — a symlink into a sibling repository. |
Only when those extensions are installed. |
The extension-dependent programs use constructs the core grammar does not
implement, so without le_extensions.pl they do not merely fail — they cannot be
parsed, and their failures say nothing about core LE. That is why they are not in
the default suite.
The exclusion is a hardwired table, extension_dependent_path_fragment/1 in
le_kbs.pl (currently the insureLE2/ and InsurLE2/ example trees). Add a row
there when a new extension-dependent tree appears; nothing else changes.
Each variant writes its own status snapshot, and neither run touches the other's:
| suite | status file | |
|---|---|---|
| core | testSuiteCoreStatus.txt |
reproducible from a clean checkout |
| all | testSuiteStatus.txt |
needs le_extensions.pl to mean anything |
Both are tracked here. A repository that does not have the extensions should
ignore testSuiteStatus.txt — it cannot reproduce it — and read
testSuiteCoreStatus.txt instead. Each file's header names the suite it ran, when,
and the sibling file, so opening the wrong one tells you where the other is. Both
are snapshots of a single run, not curated baselines: to gate CI, use the exit
status of testing/run_tests.sh.
- Prolog unit tests (plunit):
swipl -q -g run_tests -t halt testing/test_session_reaper.pl(coverstesting/test_*.pl). - Logical English example tests:
swipl -g "use_module(le_kbs), runTests, halt."runs the core suite;runAllTests(equivalentlyrunTests(all)) adds the extension-dependent trees. Each refreshes its own status file. Expectations live inside each scenario as<query> expects answers [...] and unknowns [...]; sibling.le.testsfiles are deprecated — still read if present, but none remain in the corpus and new examples must not add them. - E2E Tests (Playwright):
To run tests visibly, use
cd editor npm install npm run build npm run test:e2enpm run test:e2e -- --headedornpx playwright test --ui.
Logical English 2.0 is also available as a pre-configured Docker image.
docker run -p 3050:3050 logicalcontracts/le2The editor will be available at http://localhost:3050/editor/.
LE 2.0 is built on SWI-Prolog for the reasoning engine and TypeScript/Monaco for the frontend.
- Web API: A JSON-RPC and REST API for loading KBs and running queries.
- MCP Server: Built-in support for the Model Context Protocol, allowing LLMs (like Claude) to interact directly with your logic.
We are actively expanding LE 2.0. Under consideration:
- LLM assistant: Generate programs and scenario facts from free-form text or URLs.
- Inter-module Calling: Importing and calling logic across different LE files.
- Prolog Bridge: Calling arbitrary Prolog predicates with explanations.
- Time & Durations: Time expressions and intervals.
- Debug Adapter Protocol (DAP): Implement DAP for deeper integration with VS Code and other IDEs.
- Generators: Standalone Prolog and s(CASP) target generation.
- Globals: Support for global entities (e.g.,
*The TaxPayer*). - Proprietary Extensions: Allow additions to the LE grammar and reasoner.
All software in this repository is licensed under the Apache License 2.0 except where noted.
Copyright holders by country:
- LodgeIT (AU)
- AORA Law, Axiome (UK)
- AINexus (USA)
- Bob Kowalski (UK)
- Miguel Calejo (PT)
- Jacinto Dávila (VE)
Special thanks to: Andrew Noble, John Cummins, Chris and Bruce Mennell, Galileo Sartor and Faramarz Farhoodi.
For the legacy implementation and historical context, visit the original Logical English repository.