deontic 0.1.0__py3-none-any.whl

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/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/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/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",
+]

deontic/lexer.py

@@ -0,0 +1,194 @@
+"""Marker lexing and word tokenising (design §10, corpus README).
+
+Two passes. The first splits the source into typed fragments: `$Term$`,
+`$$Terms$$`, `@verb@`, `#90 days#`, `<parameter>` and the prose between
+them. Only editors write markers, so any unmatched or empty marker is an
+error. The second turns the prose into words, numbers, dates, strings and
+punctuation, giving the parser one flat token stream.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import (
+    EmptyMarker, MissingPeriod, SigilInsideMarker, UnbalancedParenthesis,
+    UnmatchedMarker, UnterminatedString,
+)
+
+SIGILS = "$@#<>"
+UNITS = {
+    "hour": "hour", "hours": "hour", "day": "day", "days": "day", "week": "week", "weeks": "week",
+    "month": "month", "months": "month", "quarter": "quarter", "quarters": "quarter",
+    "year": "year", "years": "year", "percent": "percent",
+}
+CALENDAR_UNITS = {"calendar week": "calendar week", "calendar weeks": "calendar week",
+                  "calendar month": "calendar month", "calendar months": "calendar month",
+                  "calendar year": "calendar year", "calendar years": "calendar year"}
+NUMBER_WORDS = {"one": 1, "two": 2, "three": 3, "four": 4, "five": 5, "six": 6, "seven": 7,
+                "eight": 8, "nine": 9, "ten": 10}
+
+
+@dataclass(frozen=True)
+class Fragment:
+    kind: str            # prose | term | verb | quantity | parameter
+    text: str
+    pos: int
+    plural: bool = False
+
+
+@dataclass(frozen=True)
+class Token:
+    kind: str            # word | punct | string | number | date | term | verb | quantity | parameter
+    value: Any
+    pos: int
+    plural: bool = False
+    raw: str = ""
+
+
+def normalise(text: str) -> str:
+    return " ".join(text.split())
+
+
+def quantity(text: str) -> dict:
+    """`90 days` → {value: 90, unit: day}; `7` → {value: 7}; `year` → {value: 1, unit: year}."""
+    words = normalise(text).lower().split()
+    if not words:
+        raise ValueError("empty quantity")
+    value = None
+    if re.fullmatch(r"\d+(\.\d+)?", words[0]):
+        value = float(words[0]) if "." in words[0] else int(words[0])
+        words = words[1:]
+    elif words[0] in NUMBER_WORDS:
+        value = NUMBER_WORDS[words[0]]
+        words = words[1:]
+    unit = " ".join(words)
+    if unit in CALENDAR_UNITS:
+        unit = CALENDAR_UNITS[unit]
+    elif unit in UNITS:
+        unit = UNITS[unit]
+    elif unit:
+        raise ValueError(f"unknown unit {unit!r}")
+    if value is None:
+        if not unit:
+            raise ValueError("quantity without a value")
+        value = 1
+    out: dict = {"value": value}
+    if unit:
+        out["unit"] = unit
+    return out
+
+
+def fragments(source: str) -> list[Fragment]:
+    out: list[Fragment] = []
+    i, n, prose_start = 0, len(source), 0
+    while i < n:
+        c = source[i]
+        if c not in "$@#<":
+            i += 1
+            continue
+        if prose_start < i:
+            out.append(Fragment("prose", source[prose_start:i], prose_start))
+        if c == "$" and source.startswith("$$", i):
+            open_m, close_m, kind, plural = "$$", "$$", "term", True
+        else:
+            open_m = c
+            close_m = {"$": "$", "@": "@", "#": "#", "<": ">"}[c]
+            kind = {"$": "term", "@": "verb", "#": "quantity", "<": "parameter"}[c]
+            plural = False
+        start = i + len(open_m)
+        end = source.find(close_m, start)
+        if end < 0:
+            raise UnmatchedMarker(f"unmatched {open_m!r}", position=i)
+        content = source[start:end]
+        if any(s in content for s in SIGILS):
+            raise SigilInsideMarker("markers do not nest", position=i)
+        content = normalise(content)
+        if not content:
+            raise EmptyMarker("empty marker", position=i)
+        out.append(Fragment(kind, content, i, plural))
+        i = end + len(close_m)
+        prose_start = i
+    if prose_start < n:
+        out.append(Fragment("prose", source[prose_start:], prose_start))
+    # A stray closing sigil in prose
+    for f in out:
+        if f.kind == "prose" and ">" in f.text:
+            raise UnmatchedMarker("unmatched '>'", position=f.pos + f.text.index(">"))
+    return out
+
+
+_WORD_RE = re.compile(r"""
+    (?P<date>\d{4}-\d{2}-\d{2})(?![\w-])
+  | (?P<number>\d+(?:\.\d+)?)(?![\w-])(?!\.\d)
+  | (?P<poss>'s)(?![\w-])
+  | (?P<word>[^\s"()',.]+?)(?=[\s"()',.]|$|'s\b)
+  | (?P<punct>[(),.])
+  | (?P<space>\s+)
+""", re.VERBOSE)
+
+
+def _prose_tokens(text: str, base: int) -> list[Token]:
+    out: list[Token] = []
+    i = 0
+    while i < len(text):
+        c = text[i]
+        if c == '"':
+            end = text.find('"', i + 1)
+            if end < 0:
+                raise UnterminatedString("unterminated string", position=base + i)
+            out.append(Token("string", text[i + 1:end], base + i))
+            i = end + 1
+            continue
+        m = _WORD_RE.match(text, i)
+        if not m:
+            raise UnmatchedMarker("unreadable text", position=base + i)
+        kind = m.lastgroup
+        if kind == "space":
+            pass
+        elif kind == "date":
+            out.append(Token("date", m.group(), base + i))
+        elif kind == "number":
+            s = m.group()
+            out.append(Token("number", float(s) if "." in s else int(s), base + i, raw=s))
+        elif kind == "poss":
+            out.append(Token("punct", "'s", base + i))
+        elif kind == "punct":
+            out.append(Token("punct", m.group(), base + i))
+        else:
+            out.append(Token("word", m.group().lower(), base + i, raw=m.group()))
+        i = m.end()
+    return out
+
+
+def tokens(source: str) -> tuple[list[Fragment], list[Token]]:
+    frags = fragments(source)
+    out: list[Token] = []
+    for f in frags:
+        if f.kind == "prose":
+            out.extend(_prose_tokens(f.text, f.pos))
+        elif f.kind == "quantity":
+            try:
+                out.append(Token("quantity", quantity(f.text), f.pos, raw=f.text))
+            except ValueError:
+                out.append(Token("quantity", None, f.pos, raw=f.text))
+        else:
+            out.append(Token(f.kind, f.text, f.pos, plural=f.plural))
+    depth = 0
+    first_open = None
+    for t in out:
+        if t.kind == "punct" and t.value == "(":
+            depth += 1
+            if first_open is None:
+                first_open = t.pos
+        elif t.kind == "punct" and t.value == ")":
+            depth -= 1
+            if depth < 0:
+                raise UnbalancedParenthesis("unbalanced parenthesis", position=t.pos)
+    if depth > 0:
+        raise UnbalancedParenthesis("unbalanced parenthesis", position=first_open)
+    if not out or not (out[-1].kind == "punct" and out[-1].value == "."):
+        raise MissingPeriod("a sentence ends with a period")
+    return frags, out