deontic 0.1.0__tar.gz

deontic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikko Ahonen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deontic-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: deontic
+Version: 0.1.0
+Summary: A constraint language for obligation, permission and prohibition
+Author: Mikko Ahonen
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mikko-ahonen/deontic
+Project-URL: Source, https://github.com/mikko-ahonen/deontic
+Keywords: deontic,constraints,policy,obligation,permission
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Dynamic: license-file
+
+# deontic
+
+A constraint language for **obligation**, **permission** and **prohibition** —
+the things a system must do, may do, and must not do.
+
+> **Status: alpha.** The grammar is implemented and reproduces the whole
+> conformance corpus: `deontic.parse` gives the AST, `deontic.load` reads a
+> dictionary and `deontic.resolve` checks a sentence against it. There is no
+> evaluator in this package, by design; the corpus's `evaluate/` cases are
+> for implementations that add one.
+
+## Why a language rather than a library
+
+Deontic statements are usually buried in imperative checks, where the rule and
+the enforcement of the rule are the same code. Writing them down as data makes
+them reviewable by the people who own the policy rather than only by the people
+who own the codebase, and lets more than one evaluator agree on what a rule
+means.
+
+## Design
+
+[docs/design.md](docs/design.md) states what the language is meant to be:
+the closed-class vocabulary, the shapes, filters and paths, attestation,
+the storage form, the interpretation rules, the outcome model, and how it
+relates to Attempto Controlled English and to deontic logic.
+
+## Conformance
+
+`conformance/` is the normative test data: source text plus the result every
+implementation must agree on, kept as data rather than Python tests so that an
+implementation in another language can consume it too. An implementation is
+conformant when it reproduces the corpus. It has three parts — `parse/`
+(source to AST, no lexicon needed), `reject/` (source to error) and
+`evaluate/` (sentences, a world and a date to outcomes) — over one invented
+fixture lexicon, and its README records the language decisions the cases fix.
+
+## Use
+
+```python
+import deontic
+
+ast = deontic.parse("Every $exhibit$ tagged fragile must @be located in@ a $gallery$ tagged storage.")
+# {'shape': 'obligation', 'subject': {...}, 'predicate': {...}}
+
+lexicon = deontic.load("conformance/lexicon.json")
+deontic.resolve(ast, lexicon)   # raises a ResolutionError with the corpus's error code otherwise
+```
+
+Sentences are authored as English and stored with markers on the typed
+spans (`$Term$`, `@verb@`, `#90 days#`, `<parameter>`); editors write the
+markers, people do not. A verb's meaning is a `pattern` in the dictionary
+or, failing that, code under the contract in [docs/hooks.md](docs/hooks.md).
+
+## Install
+
+```bash
+pip install deontic
+```
+
+Stdlib only, no runtime dependencies — a grammar meant to be implemented by
+other people should not put a parser generator in everyone's dependency tree.
+
+## License
+
+MIT.

deontic-0.1.0/README.md

@@ -0,0 +1,65 @@
+# deontic
+
+A constraint language for **obligation**, **permission** and **prohibition** —
+the things a system must do, may do, and must not do.
+
+> **Status: alpha.** The grammar is implemented and reproduces the whole
+> conformance corpus: `deontic.parse` gives the AST, `deontic.load` reads a
+> dictionary and `deontic.resolve` checks a sentence against it. There is no
+> evaluator in this package, by design; the corpus's `evaluate/` cases are
+> for implementations that add one.
+
+## Why a language rather than a library
+
+Deontic statements are usually buried in imperative checks, where the rule and
+the enforcement of the rule are the same code. Writing them down as data makes
+them reviewable by the people who own the policy rather than only by the people
+who own the codebase, and lets more than one evaluator agree on what a rule
+means.
+
+## Design
+
+[docs/design.md](docs/design.md) states what the language is meant to be:
+the closed-class vocabulary, the shapes, filters and paths, attestation,
+the storage form, the interpretation rules, the outcome model, and how it
+relates to Attempto Controlled English and to deontic logic.
+
+## Conformance
+
+`conformance/` is the normative test data: source text plus the result every
+implementation must agree on, kept as data rather than Python tests so that an
+implementation in another language can consume it too. An implementation is
+conformant when it reproduces the corpus. It has three parts — `parse/`
+(source to AST, no lexicon needed), `reject/` (source to error) and
+`evaluate/` (sentences, a world and a date to outcomes) — over one invented
+fixture lexicon, and its README records the language decisions the cases fix.
+
+## Use
+
+```python
+import deontic
+
+ast = deontic.parse("Every $exhibit$ tagged fragile must @be located in@ a $gallery$ tagged storage.")
+# {'shape': 'obligation', 'subject': {...}, 'predicate': {...}}
+
+lexicon = deontic.load("conformance/lexicon.json")
+deontic.resolve(ast, lexicon)   # raises a ResolutionError with the corpus's error code otherwise
+```
+
+Sentences are authored as English and stored with markers on the typed
+spans (`$Term$`, `@verb@`, `#90 days#`, `<parameter>`); editors write the
+markers, people do not. A verb's meaning is a `pattern` in the dictionary
+or, failing that, code under the contract in [docs/hooks.md](docs/hooks.md).
+
+## Install
+
+```bash
+pip install deontic
+```
+
+Stdlib only, no runtime dependencies — a grammar meant to be implemented by
+other people should not put a parser generator in everyone's dependency tree.
+
+## License
+
+MIT.

deontic-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+# The deontic constraint language — public grammar, AST and conformance corpus.
+#
+# This repository is maintained by hand rather than generated from a project
+# template, because it is public and the templates are not.
+#
+# Published to pypi.org from GitHub Actions via trusted publishing (OIDC), so
+# no API token exists at rest anywhere.
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deontic"
+version = "0.1.0"
+description = "A constraint language for obligation, permission and prohibition"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Mikko Ahonen" }]
+keywords = ["deontic", "constraints", "policy", "obligation", "permission"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+# Stdlib only. A grammar other people are meant to implement should not drag a
+# parser generator into every consumer's dependency tree.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "jsonschema"]
+
+[project.urls]
+Homepage = "https://github.com/mikko-ahonen/deontic"
+Source = "https://github.com/mikko-ahonen/deontic"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

deontic-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deontic-0.1.0/src/deontic/__init__.py

@@ -0,0 +1,32 @@
+"""The deontic constraint language.
+
+`parse` turns one sentence into the AST the conformance corpus fixes
+(conformance/ast.schema.json); `load` reads a dictionary; `resolve` checks a
+parsed sentence against it. `deontic.hooks` is the contract between a
+lexicon's code half and any implementation. No evaluator lives here.
+
+The version is read from installed metadata rather than written as a literal,
+so the value in a published wheel and the value this module reports cannot
+disagree.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("deontic")
+except PackageNotFoundError:  # running from a source tree, not installed
+    __version__ = "0.0.0+unknown"
+
+from .dictionary import Dictionary, DictionaryError, load  # noqa: E402
+from .errors import DeonticError, LexicalError, ResolutionError  # noqa: E402
+from .parser import parse  # noqa: E402
+from .resolve import Scope, resolve  # noqa: E402
+from .hooks import (  # noqa: E402
+    ENTRY_POINT_GROUP, Attestation, Context, Entity, Hook, Lexicon, Relation, Witness, World,
+)
+
+__all__ = [
+    "__version__", "parse", "resolve", "load", "Dictionary", "DictionaryError", "Scope",
+    "DeonticError", "LexicalError", "ResolutionError", "ENTRY_POINT_GROUP", "Attestation", "Context", "Entity", "Hook",
+    "Lexicon", "Relation", "Witness", "World",
+]

deontic-0.1.0/src/deontic/dictionary.py

@@ -0,0 +1,203 @@
+"""Loading a dictionary (conformance/dictionary.schema.json) into a form the
+resolver can query: every declared name with its role, field kinds, tag
+sets, relations by possessive word, verbs with their patterns.
+
+Loading checks what the JSON Schema cannot: that references point at
+declared types, that a pattern names real fields of the right kind, and
+that no name is declared in two roles.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+SCALARS = ("text", "number", "date", "boolean")
+
+
+class DictionaryError(ValueError):
+    pass
+
+
+def field_kind(f: Any) -> str:
+    return f if isinstance(f, str) else f["kind"]
+
+
+@dataclass
+class Dictionary:
+    data: dict
+    types: dict[str, dict] = field(default_factory=dict)
+    roles: dict[str, str] = field(default_factory=dict)       # name (lower) → type | plural | event | cadence | metric | attester | attester_plural | term | reference
+    canonical: dict[str, str] = field(default_factory=dict)   # name (lower) → declared spelling
+    plural_of: dict[str, str] = field(default_factory=dict)   # plural (lower) → singular type
+    verbs: dict[str, dict] = field(default_factory=dict)      # canonical verb → declaration
+    verb_of: dict[str, str] = field(default_factory=dict)     # any spelling → canonical
+    relations: dict[str, dict] = field(default_factory=dict)
+
+    @property
+    def name(self) -> str:
+        return self.data["name"]
+
+    @property
+    def strictness(self) -> str:
+        return self.data.get("strictness", "permissive")
+
+    # --- queries ---------------------------------------------------------------------
+
+    def role(self, name: str) -> str | None:
+        return self.roles.get(name.lower())
+
+    def type_of(self, name: str) -> str | None:
+        """The type a marked name denotes: itself, or the singular of a plural."""
+        r = self.role(name)
+        if r == "type":
+            return self.canonical[name.lower()]
+        if r == "plural":
+            return self.plural_of[name.lower()]
+        return None
+
+    def fields(self, type_name: str) -> dict:
+        return self.types[type_name].get("fields", {})
+
+    def tags(self, type_name: str) -> set[str]:
+        return {t if isinstance(t, str) else t["name"] for t in self.types[type_name].get("tags", [])}
+
+    def step(self, type_name: str, word: str) -> tuple[str | None, str | None]:
+        """Follow one possessive step. Returns (target type, error code or None)."""
+        f = self.fields(type_name).get(word)
+        if f is not None:
+            if field_kind(f) == "reference":
+                return f["to"], None
+            return None, "not_a_reference"
+        for r in self.relations.values():
+            if type_name in r["from"] and r.get("as", r["to"]) == word:
+                return r["to"], None
+        return None, "unknown_field"
+
+    def verb(self, spelling: str) -> dict | None:
+        c = self.verb_of.get(spelling.lower())
+        return self.verbs[c] if c else None
+
+    def verb_dated(self, decl: dict) -> bool:
+        if "pattern" in decl:
+            return "at" in decl["pattern"]
+        return bool(decl.get("dated", False))
+
+    def suggest(self, type_name: str, word: str) -> str | None:
+        import difflib
+        names = list(self.fields(type_name))
+        m = difflib.get_close_matches(word, names, n=1, cutoff=0.75)
+        return m[0] if m else None
+
+
+def _declare(d: Dictionary, name: str, role: str, canonical: str | None = None):
+    key = name.lower()
+    if key in d.roles and d.roles[key] != role:
+        raise DictionaryError(f"{name!r} declared as both {d.roles[key]} and {role}")
+    d.roles[key] = role
+    d.canonical[key] = canonical or name
+
+
+def load(source: dict | str | Path) -> Dictionary:
+    data = source if isinstance(source, dict) else json.loads(Path(source).read_text())
+    d = Dictionary(data=data)
+    d.types = data.get("types", {})
+    for name, t in d.types.items():
+        _declare(d, name, "type")
+        plural = t.get("plural", name + "s")
+        _declare(d, plural, "plural")
+        d.plural_of[plural.lower()] = name
+        for fname, f in t.get("fields", {}).items():
+            k = field_kind(f)
+            if k == "reference":
+                if f["to"] not in d.types:
+                    raise DictionaryError(f"{name}.{fname} refers to undeclared type {f['to']!r}")
+            elif k == "list":
+                if f["of"] not in SCALARS:
+                    raise DictionaryError(f"{name}.{fname}: list of {f['of']!r}")
+            elif k not in SCALARS:
+                raise DictionaryError(f"{name}.{fname}: unknown kind {k!r}")
+    for name, r in data.get("relations", {}).items():
+        for s in r["from"]:
+            if s not in d.types:
+                raise DictionaryError(f"relation {name}: undeclared subject type {s!r}")
+        if r["to"] not in d.types:
+            raise DictionaryError(f"relation {name}: undeclared object type {r['to']!r}")
+        d.relations[name] = r
+    for key, role in (("events", "event"), ("cadences", "cadence"), ("metrics", "metric"), ("attesters", "attester")):
+        for name, decl in data.get(key, {}).items():
+            _declare(d, name, role)
+            if role == "attester" and "plural" in decl:
+                _declare(d, decl["plural"], "attester_plural", canonical=name)
+            if role == "event":
+                if decl["type"] not in d.types or field_kind(d.fields(decl["type"]).get(decl["field"], "text")) != "date":
+                    raise DictionaryError(f"event {name}: not a date field of a declared type")
+            if role == "metric" and decl["of"] not in d.types:
+                raise DictionaryError(f"metric {name}: undeclared type {decl['of']!r}")
+    for name, v in data.get("verbs", {}).items():
+        d.verbs[name] = v
+        d.verb_of[name.lower()] = name
+        for syn in v.get("synonyms", []):
+            d.verb_of[syn.lower()] = name
+        _check_pattern(d, name, v)
+    for sentence in data.get("definitions", []):
+        from .lexer import fragments
+        first = next(f for f in fragments(sentence) if f.kind == "term")
+        _declare(d, first.text, "reference" if " refers to " in sentence else "term")
+    return d
+
+
+def _check_pattern(d: Dictionary, name: str, v: dict):
+    p = v.get("pattern")
+    if p is None:
+        if "dated" not in v:
+            raise DictionaryError(f"verb {name}: a hook verb must declare dated")
+        return
+    if "dated" in v:
+        raise DictionaryError(f"verb {name}: a verb is data or code, never both")
+    subj, obj = v.get("subject"), v.get("object", "entity")
+
+    def ref(type_name, fname, to):
+        f = d.fields(type_name).get(fname)
+        if f is None or field_kind(f) != "reference" or (to and f["to"] != to):
+            raise DictionaryError(f"verb {name}: {type_name}.{fname} is not a reference to {to}")
+
+    def date(type_name, fname):
+        f = d.fields(type_name).get(fname)
+        if f is None or field_kind(f) != "date":
+            raise DictionaryError(f"verb {name}: {type_name}.{fname} is not a date")
+
+    if p["kind"] == "field":
+        if subj is None:
+            raise DictionaryError(f"verb {name}: a field pattern needs a subject type")
+        if "object" in p:
+            ref(subj, p["object"], obj)
+        if "at" in p:
+            date(subj, p["at"])
+    elif p["kind"] == "record":
+        if p["via"] not in d.types:
+            raise DictionaryError(f"verb {name}: via type {p['via']!r} undeclared")
+        ref(p["via"], p["subject"], subj)
+        if p.get("object") == "self":
+            if obj != p["via"]:
+                raise DictionaryError(f"verb {name}: object self means the object type is {p['via']}")
+        elif "object" in p:
+            ref(p["via"], p["object"], obj if obj not in ("entity", "none") else None)
+        if "at" in p:
+            date(p["via"], p["at"])
+    elif p["kind"] == "relation":
+        r = d.relations.get(p["name"])
+        if r is None:
+            raise DictionaryError(f"verb {name}: relation {p['name']!r} undeclared")
+        if subj and subj not in r["from"]:
+            raise DictionaryError(f"verb {name}: subject {subj} is not a subject of {p['name']}")
+        if obj not in ("entity", "none") and obj != r["to"]:
+            raise DictionaryError(f"verb {name}: object {obj} is not the object of {p['name']}")
+    elif p["kind"] == "reference":
+        if obj != "entity":
+            raise DictionaryError(f"verb {name}: a reference pattern takes any entity")
+
+
+__all__ = ["Dictionary", "DictionaryError", "load", "field_kind"]

deontic-0.1.0/src/deontic/errors.py

@@ -0,0 +1,96 @@
+"""Errors, named by the codes the conformance corpus uses."""
+
+from __future__ import annotations
+
+
+class DeonticError(Exception):
+    code = "error"
+
+    def __init__(self, message: str = "", **details):
+        super().__init__(message or self.code)
+        self.message = message or self.code
+        self.details = details
+
+    def as_dict(self) -> dict:
+        return {"code": self.code, **{k: v for k, v in self.details.items() if v is not None}}
+
+
+class LexicalError(DeonticError):
+    """A sentence that cannot be read at all, in either strictness setting."""
+
+
+class UnmatchedMarker(LexicalError):
+    code = "unmatched_marker"
+
+
+class EmptyMarker(LexicalError):
+    code = "empty_marker"
+
+
+class SigilInsideMarker(LexicalError):
+    code = "sigil_inside_marker"
+
+
+class UnterminatedString(LexicalError):
+    code = "unterminated_string"
+
+
+class UnbalancedParenthesis(LexicalError):
+    code = "unbalanced_parenthesis"
+
+
+class MissingPeriod(LexicalError):
+    code = "missing_period"
+
+
+class NoShape(DeonticError):
+    """Strict only: marked text matching no shape."""
+    code = "no_shape"
+
+
+class UnresolvedAnaphora(DeonticError):
+    code = "unresolved_anaphora"
+
+
+class ResolutionError(DeonticError):
+    """An error found against a dictionary."""
+
+
+class UnknownTerm(ResolutionError):
+    code = "unknown_term"
+
+
+class UnknownField(ResolutionError):
+    code = "unknown_field"
+
+
+class NotAReference(ResolutionError):
+    code = "not_a_reference"
+
+
+class UnknownTag(ResolutionError):
+    code = "unknown_tag"
+
+
+class TypeMismatch(ResolutionError):
+    code = "type_mismatch"
+
+
+class UnknownVerb(ResolutionError):
+    code = "unknown_verb"
+
+
+class ObjectKindMismatch(ResolutionError):
+    code = "object_kind_mismatch"
+
+
+class UnknownRubric(ResolutionError):
+    code = "unknown_rubric"
+
+
+class ConfidenceRequiresSystem(ResolutionError):
+    code = "confidence_requires_system"
+
+
+class UndatedVerb(ResolutionError):
+    code = "undated_verb"

deontic-0.1.0/src/deontic/hooks.py

@@ -0,0 +1,100 @@
+"""The Python form of a lexicon's code half (docs/hooks.md §4).
+
+A verb the dictionary declares without a `pattern` is a hook verb. A lexicon
+may ship a callable for it; an implementation that can run the callable
+evaluates the verb, one that cannot skips constraints using it. This module
+is the whole contract: the witness record, the read-only world and context
+a hook receives, and the entry-point group lexicons register under.
+
+Stdlib only, and no evaluator lives here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any, Callable, Iterable, Mapping, Protocol, Sequence
+
+ENTRY_POINT_GROUP = "deontic.lexicons"
+"""Python lexicons register here, named after their dictionary. The entry
+point resolves to an object with a `hooks` mapping from verb name to Hook."""
+
+
+@dataclass(frozen=True)
+class Entity:
+    id: str
+    type: str
+    tags: frozenset[str] = frozenset()
+    fields: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Relation:
+    name: str
+    subject: str
+    object: str
+
+
+@dataclass(frozen=True)
+class Attestation:
+    subject: str
+    attester: str
+    claim: str
+    date: date
+    confidence: float | None = None
+    system: str | None = None
+    attester_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Witness:
+    """One piece of evidence that a verb holds of a subject.
+
+    `object` is the entity the verb relates the subject to, if the verb takes
+    one; `at` is when, if the verb is dated; `via` is the record that carries
+    the evidence when it is neither the subject nor the object.
+    """
+    object: str | None = None
+    at: date | None = None
+    via: str | None = None
+
+
+class World(Protocol):
+    """Read access to the closed world, and nothing outside it."""
+
+    def entity(self, id: str) -> Entity | None: ...
+    def entities(self, type: str) -> Iterable[Entity]: ...
+    def relations(self, name: str) -> Iterable[Relation]: ...
+    def attestations(self, subject: str) -> Iterable[Attestation]: ...
+
+
+@dataclass(frozen=True)
+class Context:
+    as_of: date
+    parameters: Mapping[str, Any]
+    verb: Mapping[str, Any]
+    """The verb's declaration from the dictionary, as loaded."""
+
+
+Hook = Callable[[Entity, World, Context], Iterable[Witness]]
+"""A hook is pure: the same subject, world and context give the same
+witnesses. It sees no sentence, filter or time expression."""
+
+
+class Lexicon(Protocol):
+    """What an entry point in ENTRY_POINT_GROUP resolves to."""
+
+    hooks: Mapping[str, Hook]
+
+
+def dated(hook: Hook) -> bool:
+    """Whether a hook's witnesses carry a date, per its `dated` attribute; a
+    hook without one is undated, so a time expression on its verb is an
+    `undated_verb` error rather than a silent pass."""
+    return bool(getattr(hook, "dated", False))
+
+
+__all__ = [
+    "ENTRY_POINT_GROUP", "Entity", "Relation", "Attestation", "Witness",
+    "World", "Context", "Hook", "Lexicon", "dated",
+]