sequentialist-core 0.1.0__py3-none-any.whl

sequentialist/core/storage/sqlite.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Storage in one SQLite database file (the sqlite3 module of the standard library).
+
+The state and the clearing of the journal are one transaction.  The
+database runs in WAL mode; `sync="fsync"` sets ``synchronous=FULL``
+(survives a power failure), ``"flush"`` sets ``NORMAL`` (survives a crash of
+the process).  Writers lock tasks with files next to the database
+(``<database>.locks/<task>.lock``); ``":memory:"`` locks within the process.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Any, Sequence
+
+from ..canonical import loads
+from ..errors import ConflictError, StorageError
+from ._lock import FileLock, Lock, MemoryLock
+from .base import Storage, check_document_name, check_task_id
+
+FORMAT = "sequentialist.sqlite/1"
+
+_SCHEMA = """
+create table if not exists meta (key text primary key, value text not null);
+create table if not exists tasks (task_id text primary key, version integer not null, state text not null);
+create table if not exists journal (task_id text not null, pos integer not null, entry text not null,
+                                    primary key (task_id, pos));
+create table if not exists audit (task_id text not null, n integer not null, entry text not null,
+                                  primary key (task_id, n));
+create table if not exists documents (task_id text not null, name text not null, document text not null,
+                                      primary key (task_id, name));
+"""
+
+
+def _dump(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, ensure_ascii=False)
+
+
+class SQLiteStorage(Storage):
+    def __init__(self, path: str | Path, *, sync: str = "fsync"):
+        if sync not in ("fsync", "flush"):
+            raise ValueError("sync must be 'fsync' or 'flush'")
+        self.path = str(path)
+        self._memory = self.path == ":memory:"
+        self._guard = threading.Lock()
+        self._held: set[str] = set()
+        self._db = sqlite3.connect(self.path, check_same_thread=False, isolation_level=None)
+        with self._guard:
+            if not self._memory:
+                self._db.execute("pragma journal_mode=wal")
+            self._db.execute(f"pragma synchronous={'full' if sync == 'fsync' else 'normal'}")
+            self._db.executescript(_SCHEMA)
+            row = self._db.execute("select value from meta where key = 'format'").fetchone()
+            if row is None:
+                self._db.execute("insert into meta values ('format', ?)", (FORMAT,))
+            elif row[0] != FORMAT:
+                raise StorageError(f"{self.path}: format {row[0]!r}, this version reads {FORMAT!r}")
+
+    def lock(self, task_id: str) -> Lock:
+        check_task_id(task_id)
+        if self._memory:
+            return MemoryLock(self._held, self._guard, task_id, f"task {task_id!r}")
+        locks = Path(self.path + ".locks")
+        locks.mkdir(exist_ok=True)
+        return FileLock(str(locks / f"{task_id}.lock"), f"task {task_id!r} in {self.path}")
+
+    def _query(self, sql: str, args: tuple[Any, ...] = ()) -> list[tuple[Any, ...]]:
+        with self._guard:
+            return self._db.execute(sql, args).fetchall()
+
+    def tasks(self) -> list[str]:
+        return [r[0] for r in self._query("select task_id from tasks order by task_id")]
+
+    def load(self, task_id: str) -> tuple[int, dict[str, Any]] | None:
+        rows = self._query("select version, state from tasks where task_id = ?", (check_task_id(task_id),))
+        return None if not rows else (rows[0][0], loads(rows[0][1]))
+
+    def save(self, task_id: str, state: dict[str, Any], *, expected: int, clear_journal: bool = False) -> int:
+        check_task_id(task_id)
+        with self._guard:
+            db = self._db
+            db.execute("begin immediate")
+            try:
+                row = db.execute("select version from tasks where task_id = ?", (task_id,)).fetchone()
+                current = 0 if row is None else row[0]
+                if current != expected:
+                    raise ConflictError(f"task {task_id!r}: stored version {current}, expected {expected}")
+                db.execute("insert or replace into tasks values (?, ?, ?)", (task_id, current + 1, _dump(state)))
+                if clear_journal:
+                    db.execute("delete from journal where task_id = ?", (task_id,))
+                db.execute("commit")
+            except BaseException:
+                db.execute("rollback")
+                raise
+        return current + 1
+
+    def _append(self, table: str, task_id: str, entries: Sequence[dict[str, Any]]) -> None:
+        column = "pos" if table == "journal" else "n"
+        with self._guard:
+            db = self._db
+            db.execute("begin immediate")
+            try:
+                row = db.execute(f"select max({column}) from {table} where task_id = ?", (task_id,)).fetchone()
+                start = 0 if row[0] is None else row[0] + 1
+                db.executemany(f"insert into {table} values (?, ?, ?)",
+                               [(task_id, start + i, _dump(e)) for i, e in enumerate(entries)])
+                db.execute("commit")
+            except BaseException:
+                db.execute("rollback")
+                raise
+
+    def journal_append(self, task_id: str, entries: Sequence[dict[str, Any]]) -> None:
+        if entries:
+            self._append("journal", check_task_id(task_id), entries)
+
+    def journal_read(self, task_id: str) -> list[dict[str, Any]]:
+        rows = self._query("select entry from journal where task_id = ? order by pos", (check_task_id(task_id),))
+        return [loads(r[0]) for r in rows]
+
+    def audit_append(self, task_id: str, entry: dict[str, Any]) -> None:
+        self._append("audit", check_task_id(task_id), [entry])
+
+    def audit_read(self, task_id: str) -> list[dict[str, Any]]:
+        rows = self._query("select entry from audit where task_id = ? order by n", (check_task_id(task_id),))
+        return [loads(r[0]) for r in rows]
+
+    def put_document(self, task_id: str, name: str, document: dict[str, Any]) -> None:
+        with self._guard:
+            self._db.execute("insert or replace into documents values (?, ?, ?)",
+                             (check_task_id(task_id), check_document_name(name), _dump(document)))
+
+    def get_document(self, task_id: str, name: str) -> dict[str, Any] | None:
+        rows = self._query("select document from documents where task_id = ? and name = ?",
+                           (check_task_id(task_id), check_document_name(name)))
+        if not rows:
+            return None
+        found: dict[str, Any] = loads(rows[0][0])
+        return found
+
+    def documents(self, task_id: str) -> list[str]:
+        return [r[0] for r in self._query("select name from documents where task_id = ? order by name",
+                                          (check_task_id(task_id),))]
+
+    def close(self) -> None:
+        with self._guard:
+            self._db.close()

sequentialist/core/version.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+__version__ = "0.1.0"

sequentialist_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: sequentialist-core
+Version: 0.1.0
+Summary: Common layer of the sequentialist libraries: specs, a checkpointed engine over sequential-analysis runs, storage, audit log, reports
+Author: Andrej Novikov
+Maintainer-email: Novikov Laboratories LLC <andrei@hobukob.ru>
+License-Expression: AGPL-3.0-only OR LicenseRef-Commercial
+Project-URL: Source, https://github.com/andre-a-no/sequentialist-core
+Project-URL: Issues, https://github.com/andre-a-no/sequentialist-core/issues
+Project-URL: Commercial license, https://github.com/andre-a-no/sequentialist-core/blob/main/COMMERCIAL.md
+Keywords: sequential analysis,anytime-valid inference,audit log,checkpoint,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: COMMERCIAL.md
+Requires-Dist: sequential-analysis<0.5,>=0.4
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=5.1; extra == "yaml"
+Dynamic: license-file
+
+# sequentialist-core
+
+The common layer of the sequentialist libraries: applications of sequential
+statistics built on
+[sequential-analysis](https://github.com/andre-a-no/sequential-analysis).
+The statistics live in sequential-analysis; this package turns its
+procedures into applications that run for months, survive crashes and can
+be audited, and every conclusion they report names its guarantee
+(`exact`, `asymptotic`, `model`, `approximate` or `none`), as the procedure
+behind it states it.
+
+| Library | Repository | Status |
+|---|---|---|
+| `sequentialist-core` | this one | 0.1.2: specs, the checkpointed engine, storage, audit log, reports, simulations |
+| `sequentialist-ab`, `@sequentialist/ab-client` (npm) | [sequentialist-ab](https://github.com/andre-a-no/sequentialist-ab) | 0.1.0: the engine of an A/B testing platform |
+| `sequentialist-quality` | [sequentialist-quality](https://github.com/andre-a-no/sequentialist-quality) | 0.1.0: sequential acceptance sampling of lots |
+| `sequentialist-monitor` | [sequentialist-monitor](https://github.com/andre-a-no/sequentialist-monitor) | planned: equipment, processes and energy |
+| `sequentialist-markets` | [sequentialist-markets](https://github.com/andre-a-no/sequentialist-markets) | planned: risk, backtests, strategy decay |
+| `sequentialist-clinical` | [sequentialist-clinical](https://github.com/andre-a-no/sequentialist-clinical) | planned: trials, drug safety, quality of care |
+| `sequentialist-release`, `sequentialist-mlops` | | planned: canary releases, models in production |
+
+The libraries are installed separately and share the `sequentialist`
+namespace. None is on PyPI yet.
+
+```
+pip install sequentialist-core            # Python 3.8+, depends only on sequential-analysis
+pip install "sequentialist-core[yaml]"    # specs in YAML as well as JSON
+```
+
+| Module | What it does |
+|---|---|
+| `spec` | Specs with declarative schemas: every error reported at once with its JSON pointer; a normal form (durations in seconds, timestamps in epoch seconds) and a spec id (SHA-256 of its canonical JSON); JSON Schema for other tools |
+| `engine` | Tasks of several streams, each a `Run` of sequential-analysis: idempotent intake by (source, seq), a journal written before processing, checkpoints, replay after a crash, segments (a new run after an alarm or a window), commands of people, one writer per task, shards |
+| `storage` | `MemoryStorage`, `FileStorage` (a directory of JSON files), `SQLiteStorage`; `open_storage("files:...")` |
+| `audit` | The hash-chained log of decisions and actions, with the evidence behind each: procedure, guarantee, step, history digest; `verify_audit` |
+| `report` | Reports in JSON and Markdown; a `Finding` cannot be made without its guarantee |
+| `simulate` | Error rates of a whole pipeline by simulation, with Monte Carlo intervals |
+| `replay` | Recorded data through the live code, on the data's own clock: the same audit log every time |
+| `sinks` | Notifications of decisions: log, JSON lines, webhooks with retries |
+| `privacy` | Pseudonyms for identifiers of people (HMAC-SHA-256 under the data owner's key) |
+
+A library implements a `Handler`: it declares its streams and processes
+records, the passing of time and commands. The engine does the rest:
+
+```python
+from sequentialist.core import Engine, Handler, Record, SQLiteStorage, Stream
+from sequential_analysis.procedures import MeanEDetector
+
+class Watch(Handler):
+    def __init__(self, spec):
+        self.spec = spec
+
+    def streams(self):
+        return {"mean": Stream(MeanEDetector(m=self.spec["m"], arl=10000, direction="increase"))}
+
+    def on_record(self, record, ctx):
+        event = ctx.step("mean", {"x": record.data["x"]})
+        if event is not None and event.terminal:
+            ctx.record("decision", "alarm", basis={"t": event.t}, evidence=["mean"])
+            ctx.restart("mean", "alarm")
+
+engine = Engine(SQLiteStorage("tasks.db"))
+task = engine.create("line-3", "example.watch/1", {"m": 0.2}, Watch({"m": 0.2}))
+task.ingest([Record("sensor-7", 0, {"x": 0.18}, time=1793491200.0)])
+task.close()
+task = engine.open("line-3", Watch)       # restores the checkpoint, replays the journal
+```
+
+`sequentialist tasks STORAGE` lists stored tasks; `sequentialist audit
+STORAGE TASK` verifies and prints a task's audit log. Installed libraries
+add their own subcommands.
+
+**Limits of this version.** The whole state of a task is written at every
+checkpoint, so its size (and the cost of a checkpoint) grows with what the
+handler keeps; the A/B handler keeps one entry per unit. Locks protect a
+task within one host; across hosts the storage must be shared and locked
+by other means (Postgres storage is planned).
+
+## What the engine guarantees
+
+* **Idempotent intake**: a record is identified by its source and sequence
+  number; sending it again changes nothing.
+* **Nothing accepted is lost**: records are journaled before they are
+  processed; after a crash the task is restored from its checkpoint and the
+  journal is replayed, and the result is the uninterrupted run bit for bit
+  (tested on every storage, with crashes at every point that matters).
+* **An audit log of every decision**, chained by SHA-256, with the
+  procedure, its guarantee, the step and the history digest of
+  sequential-analysis that each decision rests on (`sequentialist audit`
+  verifies it).
+* **One writer per task**, enforced by locks and version checks.
+
+## License
+
+GNU AGPL v3 or a commercial license ([COMMERCIAL.md](COMMERCIAL.md)).
+Contributions need the [Contributor License Agreement](CLA.md); see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+Contact: andrei@hobukob.ru, a.hobukob@gmail.com.

sequentialist_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+sequentialist/core/__init__.py,sha256=A3CD2zwo9pMsOv9qtTK9leGhPuMRbHbU-_x0Ao_7OtY,2483
+sequentialist/core/audit.py,sha256=38_KnPApnamLQNowgPPpy9vgvFWbJIXVIFmvpcUFJeo,5931
+sequentialist/core/canonical.py,sha256=8GAf8PeoNKZeMV8vxaPmkN5BMaNccbFwtybz6j7uNho,1601
+sequentialist/core/cli.py,sha256=BKrQE_6uPgGX09gpJ39FPpkrGZPh_N2yAV4IleRjzUU,3758
+sequentialist/core/engine.py,sha256=ApGeS5iEu8q19ia69K-yilYi7PjUBo_P5SjOjnboNE4,27189
+sequentialist/core/errors.py,sha256=lsz2K3hcL7SkUv5thlXdXIZ7UxxSNN-XYWkrrlaKRZ4,1487
+sequentialist/core/privacy.py,sha256=aOI9eMKLzCPlq4YCSjIxVQ9AUmWq1Y-8byFnHuMfOK0,1404
+sequentialist/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sequentialist/core/replay.py,sha256=njeREhx2aU9UyFBevlEHO9mKppCp2vyGzFnfKJKD824,1641
+sequentialist/core/report.py,sha256=jKuI7Z9Qbq2ihgbpGy039kQJUSExMG739rmollcGQIk,5318
+sequentialist/core/schema.py,sha256=2kDz8xcI_Ri5yEedgCCFkvJUPLZaz_gvAuRVyH7dgJI,17277
+sequentialist/core/simulate.py,sha256=MMY3EybPbUciB08Hrgm4AQkg5owM9x_Uqnpm_xUl2hA,2243
+sequentialist/core/sinks.py,sha256=Ns9QNf2_ZJTxaKJcCLM9V_rO3hkO4Cn4wEHVeNDtpko,3872
+sequentialist/core/spec.py,sha256=7gHsKzKSMX8vhmWYCeAY_dFpAc7hB2heSqtejFNWd7g,4472
+sequentialist/core/version.py,sha256=CsfruV3uKgWYX83KIO66KnP0vrJNWBI15uYWd-5cGEw,175
+sequentialist/core/storage/__init__.py,sha256=0Jn2OfLg2TVq40jZtD0KUJ63bDvaNJ6Ar7gu-_skuhE,1081
+sequentialist/core/storage/_lock.py,sha256=Yk2Md-DBnLLtIxL2KHTEp2-cMViAkkJnZr__l2EtiV0,2577
+sequentialist/core/storage/base.py,sha256=30BEXjMR9xHmMA919sScyKFQwqYt2FU5ylu3RMVo5hE,4050
+sequentialist/core/storage/files.py,sha256=-mI8zpUqcjxPW27ja_CupRPdFGwiRPGcq_Zk-ma1VCw,7118
+sequentialist/core/storage/memory.py,sha256=NfHr9QFwvkqo-tggmwEShBGDdIrRd478GaQwkonKWQE,2966
+sequentialist/core/storage/sqlite.py,sha256=o0Jz9A4SaoaG3hiXQaGGsxZhYbyCi46SXl5GrKvHjh8,7118
+sequentialist_core-0.1.0.dist-info/licenses/COMMERCIAL.md,sha256=4cW3QcGfbCjxNYZq5bNHdsWCh8wwJjHKWk4dXJNa7O4,5819
+sequentialist_core-0.1.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+sequentialist_core-0.1.0.dist-info/METADATA,sha256=Y5oz1XC3MeE-0Zm__QbUm10iQydgfbj_sZK-qzX6f4s,7090
+sequentialist_core-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sequentialist_core-0.1.0.dist-info/entry_points.txt,sha256=kvVM3CuWVivOcJm37VxT8fATBftSaOxs11x5j46OQDU,178
+sequentialist_core-0.1.0.dist-info/top_level.txt,sha256=xPS1PnoauDjS39ioTd_o3S_P227_qgXDCp-ND0IIaSs,14
+sequentialist_core-0.1.0.dist-info/RECORD,,

sequentialist_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sequentialist_core-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+sequentialist = sequentialist.core.cli:main
+
+[sequentialist.commands]
+audit = sequentialist.core.cli:audit_command
+tasks = sequentialist.core.cli:tasks_command

sequentialist_core-0.1.0.dist-info/licenses/COMMERCIAL.md

@@ -0,0 +1,89 @@
+# Licensing
+
+The sequentialist libraries are dual-licensed: open source under the GNU
+AGPL v3, and under a commercial license for products whose source code
+stays closed. They are built on
+[sequential-analysis](https://github.com/andre-a-no/sequential-analysis),
+which is licensed the same way.
+
+
+## Do I need a commercial license?
+
+| Your use | License |
+|---|---|
+| Research, teaching, study, personal projects | AGPL v3 — free |
+| An open-source project released under the AGPL v3 (or the GPL v3, which can be combined with it) | AGPL v3 — free |
+| Internal use in an organisation, with no copies given to others and no access over a network for people outside it | AGPL v3 — free |
+| A product or service you distribute or offer over a network, with its complete source code published under the AGPL v3 | AGPL v3 — free |
+| A closed-source product that includes a sequentialist library (application, library, device, firmware) | **commercial license** |
+| A network service (SaaS, API, web application, an experimentation platform) built with a sequentialist library whose source code you do not publish | **commercial license** |
+| Your organisation's policy does not allow AGPL software, or you need warranty, support or indemnification | **commercial license** |
+
+Every sequentialist library depends on sequential-analysis. A commercial
+license for a sequentialist library therefore covers sequential-analysis as
+used by it; both are licensed by the same company.
+
+## Open source: GNU AGPL v3
+
+The code is available under the [GNU Affero General Public License,
+version 3](LICENSE) (`AGPL-3.0-only`). You may use, study, modify and
+redistribute it free of charge, provided that you comply with the AGPL. In
+short: if you distribute software that includes a sequentialist library, or
+let users interact with it over a network, you must make the complete
+corresponding source code of that software available under the AGPL as
+well. This text is a summary; the license itself decides.
+
+## Commercial license
+
+A commercial license releases the licensed product from the obligations of
+the AGPL: you may keep its source code closed. Terms (per product, per
+organisation, with or without support) are agreed individually.
+
+Copyright holder and licensor: **Novikov Laboratories LLC**
+(ООО «Лаборатории Новиковых»; OGRN 1231600027548, INN 1685011563).
+
+- Email: andrei@hobukob.ru, a.hobukob@gmail.com
+
+Please describe your product and how you intend to use the libraries.
+
+## Contributions
+
+Contributions are accepted under a [Contributor License Agreement](CLA.md),
+so that the project can continue to be offered under both licenses. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+# Лицензирование
+
+Библиотеки sequentialist распространяются по двойной лицензии: как открытое
+ПО по GNU AGPL v3 и по коммерческой лицензии для продуктов с закрытым
+исходным кодом. Они построены на
+[sequential-analysis](https://github.com/andre-a-no/sequential-analysis),
+которая лицензируется так же.
+
+
+## Нужна ли вам коммерческая лицензия?
+
+| Как вы используете | Лицензия |
+|---|---|
+| Исследования, преподавание, обучение, личные проекты | AGPL v3 — бесплатно |
+| Открытый проект под AGPL v3 (или GPL v3, совместимой с ней) | AGPL v3 — бесплатно |
+| Внутреннее использование в организации без передачи копий и без сетевого доступа для посторонних | AGPL v3 — бесплатно |
+| Продукт или сервис, который вы распространяете или предоставляете по сети, с полным исходным кодом, открытым по AGPL v3 | AGPL v3 — бесплатно |
+| Закрытый продукт, включающий библиотеку sequentialist (приложение, библиотека, устройство, прошивка) | **коммерческая лицензия** |
+| Сетевой сервис (SaaS, API, веб-приложение, платформа экспериментов) на основе библиотеки sequentialist, исходный код которого вы не публикуете | **коммерческая лицензия** |
+| Политика вашей организации не допускает ПО под AGPL, или вам нужны гарантии, поддержка, защита от претензий | **коммерческая лицензия** |
+
+Каждая библиотека sequentialist зависит от sequential-analysis.
+Коммерческая лицензия на библиотеку sequentialist поэтому покрывает и
+sequential-analysis в том объёме, в каком библиотека её использует;
+правообладатель у обеих один.
+
+Правообладатель и лицензиар — ООО «Лаборатории Новиковых» (Novikov
+Laboratories LLC; ОГРН 1231600027548, ИНН 1685011563).
+Контакты: andrei@hobukob.ru, a.hobukob@gmail.com. Опишите, пожалуйста, ваш
+продукт и то, как вы собираетесь использовать библиотеки.
+
+Вклад в проект принимается по [лицензионному соглашению участника](CLA.md).
+Краткое изложение выше не заменяет текст лицензии AGPL v3.