Skip to main content

phocinae-rulepack

Read a ledger, apply one version of a rule pack, and emit only the differences for a human to review. Zero model calls. Zero third-party runtime dependencies.

python deps model calls License

中文


Why this exists, in one measurement

The same decision model, asked the same question two ways, scored like this on 53 labelled commands:

how the question was asked recall on destructive commands
"Should this be blocked?" (boolean) 0.00 — it passed all 31
allow / ask / deny (three-way) 0.74
harmless / risky / destructive (scale) 0.97

And on a policy-check battery of 14 claims, the rule kernel scored 14/14 with zero model calls, while the same model, asked to approve or reject the claims directly, rejected all 8 compliant ones.

The conclusion this package is built on: "the rule kernel is worth shipping as a deterministic plugin that uses no model at all." This is that kernel.

If you want the measurement harness rather than the kernel, see phocinae-formulate.

Install

pip install phocinae-rulepack==0.1.0

Python 3.9 or newer. No dependencies. Nothing in this package opens a socket.

Use

# validate a pack: schema, citation text, corpus hashes
phocinae-rulepack validate expense-policy

# run one document (JSON or YAML; '-' reads stdin)
phocinae-rulepack check expense-policy claim.json

# run a ledger and get one envelope
phocinae-rulepack check expense-policy ledger.json --format json

# what ships in the box
phocinae-rulepack list --packs-dir ./packs

Exit codes are the contract:

code meaning
0 every result is pass
1 at least one fail
2 no fail, but at least one review (grey zone → a human decides)
3 usage or configuration error, or an empty scan

Priority is fixed and total: 3 > 1 > 2 > 0.

The three-state result

{"rulepack":"expense-policy","verdict":"fail","model_calls":0,
 "reasons":[{"rule":"r2_meal_cap","verdict":"fail","reason_code":"OVER_CATEGORY_CAP",
             "cite":["c2","c4"],"evidence":"matched:r2_meal_cap"}],
 "unmatched_paths":["id"]}
  • review means a human decides. It is not "look again later".
  • pass requires a rule that says pass. A document no rule matched is review (NO_RULE_MATCHED) — nothing falls through to a silent allow.
  • A missing field or a wrongly-typed field never becomes pass. Missing fields are review; they are never treated as compliance.
  • A real violation outranks a missing field. If one rule finds a breach and another cannot be evaluated, the verdict is fail and both are reported.
  • model_calls is a real counter, and it is always 0.

The evidence model is the point

A rule is only as good as the text behind it, so a citation must say where its text came from and whether anyone has actually read the instrument:

evidence_level meaning can it fail something?
verbatim the quote appears character-for-character in the corpus yes
derived an authority's restatement, not the instrument's own words yes, with a warning
unavailable the instrument text was not obtained no — the verdict is capped to review

That cap is the difference between an honest tool and a fake gate. A rule whose basis nobody has read must not be able to reject a customer's paperwork. The cap is verified in both directions by the test suite: flip the citation to derived and the same input must move from review to fail.

validate resolves every quote against the corpus and recomputes every sha256. A one-character change to a quote, or a wrong hash, fails validation. --strict additionally rejects sample corpus and unavailable citations.

Writing a pack

schema: phocinae-rulepack/v1
id: my-check
title: What this checks
version: 0.1.0
missing_field_policy: review        # only 'review' is accepted in v1
corpus:
  - path: sources/spec.txt
    role: authority                  # authority | production | sample
    sha256: <64 uppercase hex>
citations:
  - id: c1
    source: Where the text is from
    locator: clause 4.2
    quote: "the exact words, character for character"
    document: sources/spec.txt
    evidence_level: verbatim
rules:
  - id: r1_limit
    when:
      all_of:
        - {field: amount, op: ">", value: 500}
        - {field: receipt, op: "==", value: false}
    then: {verdict: fail, reason_code: OVER_LIMIT, cite: [c1]}
    require_fields: [amount, receipt]

The expression language is deliberately small: field OP value combined with all_of / any_of / not, and a value may be {"ref": "other.field"} to compare two fields. Operators: == != < <= > >= in not_in matches exists missing.

There is no arithmetic, no custom function, no loop, and no network access. If you need a computed value, compute it in the adapter that builds the input document — that keeps the judgement criterion in the pack, where it can be cited and tested.

The two YAML traps worth knowing

Both of these parse into something plausible and wrong, which is why the loader raises instead of guessing:

op: >            # WRONG: a folded block scalar. It swallows the lines below.
op: ">"          # right: quote operators

note: text with a ": " colon inside    # WRONG: YAML wants a new key there
note: "text with a \": \" colon inside"  # right: quote it, or use a block scalar

What ships

pack scenario rules
expense-policy S15 (the expense pre-approval demo) 8

Naming note: "S15" here is the gallery's S15 expense demo. In the 182-scenario inventory S15 is something else (multilingual low-resource expansion).

Testing

python tests/run_all.py

No network, no model, no third-party packages. The suite exits non-zero when zero assertions ran — "a check with nothing to check must not report success" is the same rule the engine applies to an empty scan.

Tests never use tempfile: scratch goes to $PHOCINAE_RULEPACK_TMP, or to a directory beside the repository.

What this is not

It is not a compliance, legal, medical or financial conclusion. It reports differences for a human to review. It is not a model, and it does not call one.

License

Apache-2.0.

Metadata

Release files for phocinae-rulepack 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phocinae-rulepack 0.1.0
File Size Uploaded Provenance Actions
phocinae_rulepack-0.1.0.tar.gz 46.3 kB Without provenance Details for phocinae_rulepack-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phocinae-rulepack 0.1.0
File Interpreter ABI Platform Actions
phocinae_rulepack-0.1.0-py3-none-any.whl Python 3 none any Details for phocinae_rulepack-0.1.0-py3-none-any.whl

Total release size: 85.3 kB

Release files / phocinae_rulepack-0.1.0.tar.gz

Download URL phocinae_rulepack-0.1.0.tar.gz
Size 46.3 kB
Tags Source
SHA-256 checksum
How to use checksums
62a5a056698fef18f2b8284397ae4a45a8a1df2cc6886793ceb12817d66016af
BLAKE2b-256 checksum
How to use checksums
5a424a6e6e0bd9553201d4860b11a248f6ba72f0f5d512ccdfa86cbb0271af1b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / phocinae_rulepack-0.1.0-py3-none-any.whl

Download URL phocinae_rulepack-0.1.0-py3-none-any.whl
Size 39.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62eeaa8c0c162fb4fd3257ad12d15e18faa929456e2e65aed831e305484f279f
BLAKE2b-256 checksum
How to use checksums
cef2ed4a7fa20b7538a561ac70cabd5ba6f9e770f873d43aa3eb7fcf228dbea9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for phocinae-rulepack 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page