Metadata-Version: 2.4
Name: clausal-decide
Version: 0.1.0
Summary: Calibrated decisions as relations for Clausal: choice, yes/no and score answers about a text, from laya or TypeSafe's Jev
Author-email: Mike Amy <mikeamycoder@gmail.com>
License: MIT
Project-URL: Homepage, https://clausal.pl
Project-URL: Documentation, https://github.com/neurosymbolica/clausal-prolog/blob/main/packages/clausal-decide/README.md
Project-URL: Repository, https://gitlab.com/MikeAmy/clausal
Project-URL: GitHub, https://github.com/neurosymbolica/clausal-prolog/tree/main/packages/clausal-decide
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: clausal>=1.0
Requires-Dist: laya>=0.3.28
Provides-Extra: typesafe
Requires-Dist: typesafe-sdk>=0.7; extra == "typesafe"

# clausal-decide

Calibrated decisions as relations, for [Clausal Prolog](https://github.com/neurosymbolica/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](https://pypi.org/project/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](https://github.com/neurosymbolica/clausal-prolog/blob/main/docs/importing_prolog.md)).

This example, from [`tests/fixtures/docs/decide_examples.seam`](https://github.com/neurosymbolica/clausal-prolog/blob/main/packages/clausal-decide/tests/fixtures/docs/decide_examples.seam),
escalates a ticket when the model thinks the customer is leaving:

```seam
-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](https://github.com/neurosymbolica/clausal-prolog/blob/main/packages/clausal-decide/docs/decide.md)

## License

MIT
