regclock 0.0.1__py3-none-any.whl

regclock/__init__.py

@@ -0,0 +1,63 @@
+"""regclock: a calendar-correct runtime for regulatory obligation deadlines.
+
+This package represents a regulatory obligation as plain data (a small
+Pydantic schema) and computes its deadline lifecycle over real calendar
+time as a deterministic, auditable state machine. See the README for
+the *is / is not* scope and prior-art comparison.
+
+Sub-namespaces of interest:
+
+* :mod:`regclock.io` — importers (LegalRuleML) and reasoner adapters
+  (:class:`regclock.io.deontic.DeonticReasoner`).
+* :mod:`regclock.i18n` — language registry for display strings; English
+  is built-in, other languages register via
+  :func:`regclock.i18n.register_language`.
+"""
+
+from regclock import i18n
+from regclock.lifecycle.events import Event, EventLog
+from regclock.lifecycle.schedule import ScheduledInstance, build_schedule
+from regclock.lifecycle.state_machine import LifecycleStatus, resolve_state
+from regclock.model.amendment import Amendment, AmendmentLog
+from regclock.model.calendar import BusinessCalendar
+from regclock.model.obligation import (
+    Bearer,
+    DeadlineSpec,
+    EvidenceRequirement,
+    Obligation,
+    Penalty,
+    SourceCitation,
+)
+from regclock.schemas.types import (
+    DayBasis,
+    DeadlineKind,
+    EventKind,
+    RecurrenceFreq,
+    State,
+)
+
+__all__ = [
+    "Amendment",
+    "AmendmentLog",
+    "Bearer",
+    "BusinessCalendar",
+    "DayBasis",
+    "DeadlineKind",
+    "DeadlineSpec",
+    "Event",
+    "EventKind",
+    "EventLog",
+    "EvidenceRequirement",
+    "LifecycleStatus",
+    "Obligation",
+    "Penalty",
+    "RecurrenceFreq",
+    "ScheduledInstance",
+    "SourceCitation",
+    "State",
+    "build_schedule",
+    "i18n",
+    "resolve_state",
+]
+
+__version__ = "0.0.1"

regclock/cli.py

@@ -0,0 +1,232 @@
+"""Command-line interface for regclock.
+
+Subcommands:
+
+* ``regclock schedule`` — expand a YAML obligation file into a
+  concrete due-date schedule for a horizon.
+* ``regclock status`` — replay an event log and print the lifecycle
+  state of every obligation as of a reference date.
+* ``regclock pack`` — assemble a regulator-ready evidence pack for a
+  reporting period.
+
+The CLI keeps all heavy logic inside the library; this file is a thin
+shell around it so that the package is usable from both Python and a
+terminal.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import click
+import yaml
+
+from regclock import i18n
+from regclock.emit.ics import to_ics
+from regclock.emit.report import render_report
+from regclock.evidence.pack import build_pack
+from regclock.lifecycle.events import Event, EventLog
+from regclock.lifecycle.schedule import build_schedule
+from regclock.lifecycle.state_machine import resolve_state
+from regclock.model.calendar import BusinessCalendar
+from regclock.model.obligation import Obligation
+from regclock.schemas.types import EventKind
+
+
+def _default_lang_from_env() -> str:
+    """Resolve the default CLI language from environment variables.
+
+    Honours ``REGCLOCK_LANG`` first (explicit override), then ``LANG``
+    (POSIX), falling back to English. Only the language part of a POSIX
+    locale (e.g. ``"es_ES.UTF-8"`` → ``"es"``) is used.
+    """
+    raw = os.environ.get("REGCLOCK_LANG") or os.environ.get("LANG") or "en"
+    return raw.split(".", 1)[0].split("_", 1)[0].lower() or "en"
+
+
+@click.group()
+@click.option(
+    "--lang",
+    default=None,
+    help="Display language for human-readable output. "
+    "Defaults to REGCLOCK_LANG, then LANG, then 'en'.",
+)
+@click.version_option(package_name="regclock")
+def cli(lang: str | None) -> None:
+    """A calendar-correct runtime for regulatory obligation deadlines."""
+    i18n.set_default_language(lang or _default_lang_from_env())
+
+
+@cli.command("schedule")
+@click.argument("obligations_path", type=click.Path(exists=True, path_type=Path))
+@click.option("--from", "horizon_start", required=True, type=click.DateTime(["%Y-%m-%d"]))
+@click.option("--to", "horizon_end", required=True, type=click.DateTime(["%Y-%m-%d"]))
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "markdown", "ics"]),
+    default="markdown",
+)
+def schedule_cmd(
+    obligations_path: Path,
+    horizon_start: Any,
+    horizon_end: Any,
+    fmt: str,
+) -> None:
+    """Expand obligations into a concrete due-date schedule."""
+    obligations = _load_obligations(obligations_path)
+    calendars = _calendars_for(obligations)
+    schedule = build_schedule(
+        obligations,
+        horizon_start.date(),
+        horizon_end.date(),
+        calendars,
+    )
+    if fmt == "ics":
+        click.echo(to_ics(schedule), nl=False)
+        return
+    if fmt == "json":
+        rows = [
+            {
+                "obligation_id": s.obligation_id,
+                "title": s.title,
+                "jurisdiction": s.jurisdiction,
+                "due_on": s.due_on.isoformat(),
+                "kind": s.kind.value,
+                "trigger_on": s.trigger_on.isoformat() if s.trigger_on else None,
+            }
+            for s in schedule
+        ]
+        click.echo(json.dumps(rows, indent=2))
+        return
+    lines = ["| Obligation | Title | Due | Kind |", "|---|---|---|---|"]
+    for s in schedule:
+        lines.append(f"| {s.obligation_id} | {s.title} | {s.due_on} | {s.kind.value} |")
+    click.echo("\n".join(lines))
+
+
+@cli.command("status")
+@click.argument("obligations_path", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--events",
+    "events_path",
+    type=click.Path(exists=True, path_type=Path),
+    required=True,
+)
+@click.option("--asof", "as_of", required=True, type=click.DateTime(["%Y-%m-%d"]))
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["markdown", "html", "json"]),
+    default="markdown",
+)
+def status_cmd(obligations_path: Path, events_path: Path, as_of: Any, fmt: str) -> None:
+    """Replay the event log and print lifecycle states as of a date."""
+    obligations = _load_obligations(obligations_path)
+    events = _load_events(events_path)
+    calendars = _calendars_for(obligations)
+    schedule = build_schedule(
+        obligations,
+        as_of.date().replace(month=1, day=1),
+        as_of.date().replace(month=12, day=31),
+        calendars,
+        events=events,
+    )
+    obligations_by_id = {o.id: o for o in obligations}
+    statuses = []
+    for inst in schedule:
+        obligation = obligations_by_id[inst.obligation_id]
+        calendar = calendars[obligation.jurisdiction]
+        statuses.append(resolve_state(obligation, inst, events, calendar, as_of.date()))
+    click.echo(render_report(statuses, fmt=fmt))  # type: ignore[arg-type]
+
+
+@cli.command("pack")
+@click.argument("obligations_path", type=click.Path(exists=True, path_type=Path))
+@click.option(
+    "--events",
+    "events_path",
+    type=click.Path(exists=True, path_type=Path),
+    required=True,
+)
+@click.option("--period", required=True, help="e.g. 2026Q1 or 2026-01-01:2026-03-31")
+@click.option("--out", "out_path", type=click.Path(path_type=Path), default=None)
+def pack_cmd(obligations_path: Path, events_path: Path, period: str, out_path: Path | None) -> None:
+    """Assemble an evidence pack for a reporting period."""
+    start, end = _parse_period(period)
+    obligations = _load_obligations(obligations_path)
+    events = _load_events(events_path)
+    calendars = _calendars_for(obligations)
+    schedule = build_schedule(obligations, start, end, calendars, events=events)
+    pack = build_pack(
+        period_start=start,
+        period_end=end,
+        obligations=obligations,
+        schedule=schedule,
+        events=events,
+        calendars=calendars,
+    )
+    payload = pack.model_dump(mode="json")
+    text = json.dumps(payload, indent=2, default=str)
+    if out_path is None:
+        click.echo(text)
+    else:
+        out_path.write_text(text, encoding="utf-8")
+        click.echo(f"wrote {out_path} (digest={pack.digest[:12]}…)")
+
+
+def _load_obligations(path: Path) -> list[Obligation]:
+    """Load a list of obligations from YAML or JSON."""
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if isinstance(raw, dict) and "obligations" in raw:
+        raw = raw["obligations"]
+    if not isinstance(raw, list):
+        click.echo("Expected a list of obligations or {obligations: [...]}", err=True)
+        sys.exit(2)
+    return [Obligation.model_validate(item) for item in raw]
+
+
+def _load_events(path: Path) -> EventLog:
+    """Load an event log from JSONL."""
+    events: list[Event] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        payload = json.loads(line)
+        if "kind" in payload and isinstance(payload["kind"], str):
+            payload["kind"] = EventKind(payload["kind"])
+        events.append(Event.model_validate(payload))
+    return EventLog(events=events)
+
+
+def _calendars_for(obligations: list[Obligation]) -> dict[str, BusinessCalendar]:
+    """Build a default :class:`BusinessCalendar` per jurisdiction seen."""
+    jurisdictions = {o.jurisdiction for o in obligations}
+    return {j: BusinessCalendar(jurisdiction=j) for j in jurisdictions}
+
+
+def _parse_period(period: str) -> tuple[date, date]:
+    """Parse a ``YYYYQn`` or ``start:end`` period string."""
+    if ":" in period:
+        a, b = period.split(":", 1)
+        return date.fromisoformat(a), date.fromisoformat(b)
+    if "Q" in period.upper():
+        year_str, q_str = period.upper().split("Q", 1)
+        year = int(year_str)
+        q = int(q_str)
+        month_start = {1: 1, 2: 4, 3: 7, 4: 10}[q]
+        from calendar import monthrange
+
+        month_end = month_start + 2
+        return date(year, month_start, 1), date(year, month_end, monthrange(year, month_end)[1])
+    raise click.BadParameter(f"Unrecognised period: {period}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

regclock/emit/__init__.py

@@ -0,0 +1,12 @@
+"""Emit layer: documents, iCalendar exports, and status reports."""
+
+from regclock.emit.documents import render_reminder, render_stub
+from regclock.emit.ics import to_ics
+from regclock.emit.report import render_report
+
+__all__ = [
+    "render_reminder",
+    "render_report",
+    "render_stub",
+    "to_ics",
+]

regclock/emit/documents.py

@@ -0,0 +1,122 @@
+"""Render filing/document stubs and reminder payloads via Jinja2.
+
+Templates live under ``regclock/templates/{lang}/``. The English pack
+ships in-tree; additional language packs are registered at runtime via
+:func:`regclock.i18n.register_language`. When a language registers no
+template directory, the English templates are used with the registered
+labels substituted in via the ``ui`` namespace and the
+``state_label`` / ``event_kind_label`` Jinja globals.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from jinja2 import (
+    ChoiceLoader,
+    Environment,
+    FileSystemLoader,
+    StrictUndefined,
+    select_autoescape,
+)
+
+from regclock import i18n
+from regclock.lifecycle.state_machine import LifecycleStatus
+from regclock.model.obligation import Obligation
+
+
+def _env(lang: str | None = None) -> Environment:
+    """Build a Jinja2 environment configured for ``lang``.
+
+    The loader tries the language-specific template directory first
+    (if registered via :func:`regclock.i18n.register_language`) and
+    falls back to the in-tree English pack for any file the language
+    pack does not override. ``ui``, ``state_label``, and
+    ``event_kind_label`` are exposed as globals so templates do not
+    need to import anything.
+    """
+    resolved_lang = (lang or i18n.get_default_language()).lower()
+    en_dir = str(resources.files("regclock").joinpath("templates", "en"))
+    loaders = []
+    custom_dir = i18n.templates_dir_for(resolved_lang)
+    if custom_dir is not None:
+        loaders.append(FileSystemLoader(str(Path(custom_dir))))
+    loaders.append(FileSystemLoader(en_dir))
+    env = Environment(
+        loader=ChoiceLoader(loaders),
+        autoescape=select_autoescape(enabled_extensions=("html", "md")),
+        undefined=StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+    env.globals["ui"] = i18n.labels_for_jinja(resolved_lang)
+    env.globals["state_label"] = lambda state: i18n.label_for_state(state, resolved_lang)
+    env.globals["event_kind_label"] = lambda kind: i18n.label_for_event_kind(kind, resolved_lang)
+    return env
+
+
+def render_stub(
+    obligation: Obligation,
+    status: LifecycleStatus,
+    lang: str | None = None,
+) -> str:
+    """Render a Markdown filing/document stub for one obligation instance.
+
+    Args:
+        obligation: The obligation definition.
+        status: The computed lifecycle status (provides due date,
+            state, evidence references).
+        lang: Language code; defaults to
+            :func:`regclock.i18n.get_default_language`.
+
+    Returns:
+        A Markdown string ready to be saved to disk or attached to a
+        ticket. The content is descriptive only: the engine does not
+        sign or submit anything.
+
+    Example:
+        >>> render_stub(obl, status, lang="es")
+        '# Borrador de presentación: ...'
+
+    """
+    template = _env(lang).get_template("filing_stub.md.j2")
+    return template.render(obligation=obligation, status=status)
+
+
+def render_reminder(
+    obligation: Obligation,
+    status: LifecycleStatus,
+    lang: str | None = None,
+) -> dict[str, str]:
+    """Render a reminder payload for an upcoming or overdue instance.
+
+    Args:
+        obligation: The obligation definition.
+        status: The computed lifecycle status.
+        lang: Language code; defaults to
+            :func:`regclock.i18n.get_default_language`.
+
+    Returns:
+        A dict with ``subject``, ``summary``, and ``body`` keys. The
+        dict is intentionally minimal so it can be fed into email,
+        Slack, or ticket-system adapters without further work.
+
+    Example:
+        >>> render_reminder(obl, status)
+        {'subject': '...', 'summary': '...', 'body': '...'}
+
+    """
+    body_template = _env(lang).get_template("reminder_body.md.j2")
+    body = body_template.render(obligation=obligation, status=status)
+    subject = (
+        f"[{obligation.jurisdiction}] {obligation.title} — "
+        f"{i18n.t('ui.due_on', lang).lower()} {status.instance.due_on}"
+    )
+    summary = (
+        f"{i18n.t('report.col_state', lang)}: "
+        f"{i18n.label_for_state(status.state, lang)}; "
+        f"{i18n.t('ui.reminder_due_date', lang).lower()} "
+        f"({status.instance.due_on})."
+    )
+    return {"subject": subject, "summary": summary, "body": body}

regclock/emit/ics.py

@@ -0,0 +1,95 @@
+"""Export a schedule to iCalendar (RFC 5545).
+
+We hand-roll the ICS output instead of pulling in a third-party
+dependency, because the format we emit (VEVENT only, all-day) is small,
+stable, and easy to validate.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from datetime import date, datetime, timezone
+
+from regclock.lifecycle.schedule import ScheduledInstance
+
+_PRODID = "-//regclock//deadline-runtime//EN"
+
+
+def to_ics(instances: Iterable[ScheduledInstance], calendar_name: str = "Obligations") -> str:
+    """Render a list of scheduled instances as an iCalendar string.
+
+    Args:
+        instances: The scheduled instances to export.
+        calendar_name: Human-readable name shown by calendar clients.
+
+    Returns:
+        An iCalendar VCALENDAR/VEVENT string using all-day events
+        (``VALUE=DATE``).
+
+    Example:
+        >>> print(to_ics(schedule)[:64])
+        BEGIN:VCALENDAR
+        VERSION:2.0
+        PRODID:-//regclock//deadline-runtime//EN
+
+    """
+    now = _utc_now_stamp()
+    lines: list[str] = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        f"PRODID:{_PRODID}",
+        "CALSCALE:GREGORIAN",
+        f"X-WR-CALNAME:{_escape(calendar_name)}",
+    ]
+    for inst in instances:
+        uid = _uid_for(inst)
+        lines.extend(
+            [
+                "BEGIN:VEVENT",
+                f"UID:{uid}",
+                f"DTSTAMP:{now}",
+                f"DTSTART;VALUE=DATE:{_ical_date(inst.due_on)}",
+                f"DTEND;VALUE=DATE:{_ical_date(_next_day(inst.due_on))}",
+                f"SUMMARY:{_escape(inst.title)}",
+                f"DESCRIPTION:{_escape(f'Obligation {inst.obligation_id} ({inst.jurisdiction})')}",
+                "TRANSP:TRANSPARENT",
+                "END:VEVENT",
+            ]
+        )
+    lines.append("END:VCALENDAR")
+    return "\r\n".join(lines) + "\r\n"
+
+
+def _ical_date(d: date) -> str:
+    """Render a date as ``YYYYMMDD`` per RFC 5545 ``DATE`` value type."""
+    return d.strftime("%Y%m%d")
+
+
+def _next_day(d: date) -> date:
+    """Return the day after ``d``; used for the exclusive DTEND of all-day events."""
+    from datetime import timedelta
+
+    return d + timedelta(days=1)
+
+
+def _utc_now_stamp() -> str:
+    """Return the current UTC time as an RFC 5545 ``DTSTAMP`` string."""
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def _escape(text: str) -> str:
+    """Escape backslashes, commas, semicolons and newlines per RFC 5545."""
+    return (
+        text.replace("\\", "\\\\")
+        .replace(",", "\\,")
+        .replace(";", "\\;")
+        .replace("\n", "\\n")
+    )
+
+
+def _uid_for(inst: ScheduledInstance) -> str:
+    """Build a stable, deterministic UID for one scheduled instance."""
+    material = f"{inst.obligation_id}|{inst.due_on.isoformat()}|{inst.kind.value}"
+    digest = hashlib.sha1(material.encode("utf-8")).hexdigest()
+    return f"{digest}@regclock"

regclock/emit/report.py

@@ -0,0 +1,126 @@
+"""Status reports in Markdown, HTML, or JSON.
+
+JSON output keeps machine-readable English ``state.value`` strings so
+that serialised reports remain locale-agnostic and diffable. Markdown
+and HTML use the translated display strings registered via
+:mod:`regclock.i18n`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+from typing import Literal
+
+from regclock import i18n
+from regclock.lifecycle.state_machine import LifecycleStatus
+
+
+def render_report(
+    statuses: Iterable[LifecycleStatus],
+    fmt: Literal["markdown", "html", "json"] = "markdown",
+    lang: str | None = None,
+) -> str:
+    """Render a flat status report for a collection of lifecycle statuses.
+
+    Args:
+        statuses: The lifecycle statuses to include.
+        fmt: Output format: ``"markdown"`` (default), ``"html"``, or
+            ``"json"``.
+        lang: Language code for human-readable columns. JSON output is
+            always machine-readable (English ``state.value``);
+            ``lang`` only affects Markdown and HTML. Defaults to the
+            current default language.
+
+    Returns:
+        The rendered report as a single string.
+
+    Raises:
+        ValueError: If ``fmt`` is not a recognised format.
+
+    Example:
+        >>> print(render_report(statuses))
+        | Obligation | State | Due | ...
+
+    """
+    statuses_list = list(statuses)
+    rows = [_row(s) for s in statuses_list]
+    if fmt == "json":
+        return json.dumps(rows, indent=2, default=str)
+    resolved_lang = lang or i18n.get_default_language()
+    display_rows = [
+        {**row, "state_display": i18n.label_for_state(s.state, resolved_lang)}
+        for row, s in zip(rows, statuses_list)
+    ]
+    if fmt == "markdown":
+        return _markdown(display_rows, resolved_lang)
+    if fmt == "html":
+        return _html(display_rows, resolved_lang)
+    raise ValueError(f"Unknown format: {fmt}")
+
+
+def _row(status: LifecycleStatus) -> dict[str, object]:
+    """Flatten a :class:`LifecycleStatus` into a serialisable row dict.
+
+    ``state`` is always the machine-readable enum value (English) so
+    that JSON output is locale-independent.
+    """
+    return {
+        "obligation_id": status.instance.obligation_id,
+        "title": status.instance.title,
+        "jurisdiction": status.instance.jurisdiction,
+        "due_on": status.instance.due_on.isoformat(),
+        "state": status.state.value,
+        "days_to_due": status.days_to_due,
+        "evidence_on": status.evidence.occurred_on.isoformat() if status.evidence else None,
+    }
+
+
+def _headers(lang: str) -> dict[str, str]:
+    return {
+        "obligation": i18n.t("report.col_obligation", lang),
+        "title": i18n.t("report.col_title", lang),
+        "jurisdiction": i18n.t("report.col_jurisdiction", lang),
+        "due": i18n.t("report.col_due", lang),
+        "state": i18n.t("report.col_state", lang),
+        "days": i18n.t("report.col_days", lang),
+        "evidence": i18n.t("report.col_evidence", lang),
+    }
+
+
+def _markdown(rows: list[dict[str, object]], lang: str) -> str:
+    """Render rows as a GitHub-flavoured Markdown table."""
+    h = _headers(lang)
+    header = (
+        f"| {h['obligation']} | {h['title']} | {h['jurisdiction']} | "
+        f"{h['due']} | {h['state']} | {h['days']} | {h['evidence']} |\n"
+        "|---|---|---|---|---|---|---|\n"
+    )
+    body = "".join(
+        f"| {r['obligation_id']} | {r['title']} | {r['jurisdiction']} | "
+        f"{r['due_on']} | {r['state_display']} | {r['days_to_due']} | "
+        f"{r['evidence_on'] or '-'} |\n"
+        for r in rows
+    )
+    return header + body
+
+
+def _html(rows: list[dict[str, object]], lang: str) -> str:
+    """Render rows as a minimal HTML table."""
+    h = _headers(lang)
+    head = (
+        "<table><thead><tr>"
+        f"<th>{h['obligation']}</th><th>{h['title']}</th>"
+        f"<th>{h['jurisdiction']}</th><th>{h['due']}</th>"
+        f"<th>{h['state']}</th><th>{h['days']}</th>"
+        f"<th>{h['evidence']}</th>"
+        "</tr></thead><tbody>"
+    )
+    body = "".join(
+        f"<tr><td>{r['obligation_id']}</td><td>{r['title']}</td>"
+        f"<td>{r['jurisdiction']}</td><td>{r['due_on']}</td>"
+        f"<td>{r['state_display']}</td><td>{r['days_to_due']}</td>"
+        f"<td>{r['evidence_on'] or '-'}</td></tr>"
+        for r in rows
+    )
+    return head + body + "</tbody></table>"

regclock/evidence/__init__.py

@@ -0,0 +1,11 @@
+"""Evidence layer: reproducible satisfaction records and regulator-ready packs."""
+
+from regclock.evidence.pack import EvidencePack, build_pack
+from regclock.evidence.record import EvidenceRecord, make_record
+
+__all__ = [
+    "EvidencePack",
+    "EvidenceRecord",
+    "build_pack",
+    "make_record",
+]