Skip to content

Install

There are two ways to install this library: as a dependency of your own service, which is what most readers want, or as a development checkout of this repository, for running the examples and changing the code. This page covers both, and a three-line check that the install works.

You need Python 3.12 or newer. The package is called grounded-decision; in Python you import grounded_decision.

Add it to your project

The package is not published to any package index. You install it from a checkout of this repository, or from the wheel that make build writes locally.

uv add /path/to/grounded_decision

uv records the path under [tool.uv.sources] in your pyproject.toml, so teammates need the checkout at the same path.

In a checkout of this repository, build the wheel:

make build

That writes dist/python/grounded_decision-0.1.0-py3-none-any.whl (and a source archive). Copy the wheel wherever your project can reach it, then, in your project's virtual environment:

pip install grounded_decision-0.1.0-py3-none-any.whl

The library brings in two packages: lark (reads the policy text) and numpy (numerical helpers). Nothing else is installed.

Check that it works

Save this as check.py in your project and run it (uv run python check.py, or python check.py in an activated environment):

from grounded_decision import Event, Module, __version__, parse
from grounded_decision.examples.common import well_corroborated_evidence

module = Module.from_expr("smoke", parse("test(ok) ; act(go)"))
record = module.decide(Event("ok"), well_corroborated_evidence())
print(__version__, record.verdict.value, record.action)

0.1.0 act go

The version, then act go: the policy proposed go and every check passed on the ready-made strong evidence. The command-line tool is installed too; grounded-decision --version prints 0.1.0, and grounded-decision examples lists the worked examples you can run (Command line).

What it does not need

  • No proof assistant, papers or model server. Some checks rely on machine-checked proofs or published theorems; those are recorded as text in the package. Nothing is downloaded or run at decision time.
  • No database, web framework or queue. The library is a function call. You keep state, logs and review queues in your own systems; Build a decision service shows one way.
  • No network access. A decision is a local computation on the numbers you pass in.

Set up a development checkout

To run the demos and examples, or to change the library, clone the repository and use uv. From the repository root (the directory containing pyproject.toml):

make setup
make test
make demo

The repository's .python-version file pins Python 3.12, so uv creates the environment with 3.12 even when your default python is newer. make setup creates .venv with the library and both tool groups: dev (pytest, pyright, ruff) and docs (MkDocs and its plugins). make test runs the test suite. make demo prints the clinical-triage walkthrough: three patients, one of them held for a clinician.

Other commands you will use early:

Command What it does
make help List every command with a one-line description
make examples List every example id
make examples-all Run every example and print its report
make service Run the reference HTTP decision service on port 8080
make docs-serve Serve this documentation at http://127.0.0.1:8000
make check Everything CI runs: format, lint, types, tests, docs, build

Each target is a thin wrapper around a uv command, shown in the Makefile. Development and automation covers adding dependencies, the test layout and releasing.

If something goes wrong

Symptom Cause and fix
requires-python error, or a syntax error on import Python older than 3.12. Check python -V (or uv run python -V) and use 3.12 or newer.
ModuleNotFoundError: grounded_decision Installed into a different environment. Run with uv run, or activate the environment you installed into.
make: uv: No such file or directory uv is not installed or not on PATH. Install it from the uv documentation.
mkdocs: command not found in a checkout The docs group is missing. Run make setup (or uv sync --group docs).
make fails with "No rule to make target" You are not in the repository root. cd to the directory containing pyproject.toml.

Next