clausal-decide

Calibrated decisions as relations, for Clausal Prolog.

A "System 1" decision model answers a set of typed questions about a text (pick a label, yes or no, a level on a scale) in one forward pass, with calibrated probabilities. This package runs such a model, either the open laya model or TypeSafe's hosted Jev, and makes its answers relations — neural predicates whose solutions carry probabilities, for symbolic logic to filter, rank and combine:

• choice/4,5 — pick a label; or enumerate every label with its probability
• noul/3 — the probability that a yes/no answer is yes
• score/4,5 — a level on a scale; or every level with its probability
• predict/3,4 — several questions in one forward pass
• predict_batch/3,4 — the same questions over many texts, sharing forward passes
• use_backend/1,2 — the open laya model in-process (default), a laya-serve server, or TypeSafe's hosted Jev model, which answers the same questions
• finetune/5, register_model/2 — fine-tune a checkpoint (on rows your program's own facts can label) and serve it by name

Install

pip install clausal-decide

laya (with torch and transformers) is pulled in as a dependency. Requires Python 3.13 or later. laya downloads its checkpoint from the Hugging Face Hub on first use. For the typesafe backend: pip install "clausal-decide[typesafe]" and set TYPESAFE_API_KEY.

Use

Import the predicates into a seam (.seam) module, as the package's own tests do. A Clausal Prolog (.clausal) module reaches Python only through the seam: put the imports in a .seam module and list it under [tool.clausal] python_bridges in your project's pyproject.toml (see Importing Prolog).

This example, from tests/fixtures/docs/decide_examples.seam, escalates a ticket when the model thinks the customer is leaving:

-import_from(py.decide, [noul])

escalate(TICKET) <- (
    noul(TICKET, "Does the user threaten to cancel or leave?", P),
    P > 0.5
)

test("a cancellation threat escalates") <- (
    escalate("Refund the duplicate charge today or we will cancel our plan.")
)

Documentation

• decide — calibrated decisions as relations

License

MIT