sqllocks-shape-behavior 0.9.1__tar.gz

sqllocks_shape_behavior-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 SQLLocks (Jonathan Stewart)
+
+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.

sqllocks_shape_behavior-0.9.1/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: sqllocks-shape-behavior
+Version: 0.9.1
+Summary: Shape plugin: behavior models (state machines on a virtual clock)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sqllocks/shape
+Project-URL: Repository, https://github.com/sqllocks/shape
+Project-URL: Issues, https://github.com/sqllocks/shape/issues
+Project-URL: Documentation, https://github.com/sqllocks/shape/tree/main/plugins/shape-behavior
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqllocks-shape==0.9.1
+Dynamic: license-file
+
+# sqllocks-shape-behavior
+
+Shape plugin: **behavior models**. Declarative state-machine modules (states with delays, guards,
+weighted and conditional transitions, attributes, clinical-style events and an extension point for
+domain events) run for a population on a virtual clock, deterministic per seed and resumable, and
+return an Arrow table of timestamped events that a domain pack turns into tables. It also imports
+Generic Module Framework JSON modules that you download yourself.
+
+```bash
+pip install sqllocks-shape-behavior
+shape behave run subscription --population 10000 --years 3 --seed 7 -o out/
+```
+
+```python
+from shape_behavior import Population, Simulator, load_module
+
+sim = Simulator([load_module("subscription")], Population(size=10_000, start="2024-01-01"))
+events = sim.run_until("2027-01-01")  # a pyarrow.Table
+```
+
+Behavior modules are plugins of the entry-point group `shape.behaviors`: `shape plugins list`
+shows them, and `python -m shape.plugins.kit sqllocks-shape-behavior` checks them.
+
+Full reference: `docs/plugins/behavior.md` in the repository. Its version always equals core's
+(`sqllocks-shape`) and it is released together with core. It depends only on numpy and pyarrow.

sqllocks_shape_behavior-0.9.1/README.md

@@ -0,0 +1,25 @@
+# sqllocks-shape-behavior
+
+Shape plugin: **behavior models**. Declarative state-machine modules (states with delays, guards,
+weighted and conditional transitions, attributes, clinical-style events and an extension point for
+domain events) run for a population on a virtual clock, deterministic per seed and resumable, and
+return an Arrow table of timestamped events that a domain pack turns into tables. It also imports
+Generic Module Framework JSON modules that you download yourself.
+
+```bash
+pip install sqllocks-shape-behavior
+shape behave run subscription --population 10000 --years 3 --seed 7 -o out/
+```
+
+```python
+from shape_behavior import Population, Simulator, load_module
+
+sim = Simulator([load_module("subscription")], Population(size=10_000, start="2024-01-01"))
+events = sim.run_until("2027-01-01")  # a pyarrow.Table
+```
+
+Behavior modules are plugins of the entry-point group `shape.behaviors`: `shape plugins list`
+shows them, and `python -m shape.plugins.kit sqllocks-shape-behavior` checks them.
+
+Full reference: `docs/plugins/behavior.md` in the repository. Its version always equals core's
+(`sqllocks-shape`) and it is released together with core. It depends only on numpy and pyarrow.

sqllocks_shape_behavior-0.9.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqllocks-shape-behavior"
+# Lockstep with core (T-09): scripts/check_plugin_skeletons.py fails when this drifts.
+version = "0.9.1"
+description = "Shape plugin: behavior models (state machines on a virtual clock)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Database",
+]
+dependencies = ["sqllocks-shape==0.9.1"]
+
+# Entry points (shape.* groups, plugin API v1); see docs/plugins/authoring.md.
+[project.urls]
+Homepage = "https://github.com/sqllocks/shape"
+Repository = "https://github.com/sqllocks/shape"
+Issues = "https://github.com/sqllocks/shape/issues"
+Documentation = "https://github.com/sqllocks/shape/tree/main/plugins/shape-behavior"
+
+[project.entry-points."shape.commands"]
+behave = "shape_behavior.cli:BehaveCommand"
+
+[project.entry-points."shape.behaviors"]
+subscription = "shape_behavior.behaviors:Subscription"
+equipment_maintenance = "shape_behavior.behaviors:EquipmentMaintenance"
+healthcare_screening = "shape_behavior.behaviors:HealthcareScreening"
+event_sequence = "shape_behavior.behaviors:EventSequence"
+telemetry_series = "shape_behavior.behaviors:TelemetrySeries"
+transaction_stream = "shape_behavior.behaviors:TransactionStream"
+file_arrival = "shape_behavior.behaviors:FileArrival"
+entity_lifecycle = "shape_behavior.behaviors:EntityLifecycle"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+shape_behavior = ["examples/*.json"]

sqllocks_shape_behavior-0.9.1/setup.cfg

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

sqllocks_shape_behavior-0.9.1/src/shape_behavior/__init__.py

@@ -0,0 +1,40 @@
+"""Shape plugin: behavior models (state machines on a virtual clock).
+
+The public names are importable from here, lazily: importing the package loads no module of
+this plugin beyond this file, and none of NumPy or Arrow. See ``docs/plugins/behavior.md``.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+SHAPE_API = "1.0"
+
+_EXPORTS = {
+    "Module": "shape_behavior.model",
+    "ModuleError": "shape_behavior.model",
+    "load_module": "shape_behavior.model",
+    "Population": "shape_behavior.population",
+    "SimConfig": "shape_behavior.simulator",
+    "Simulator": "shape_behavior.simulator",
+    "Checkpoint": "shape_behavior.simulator",
+    "EVENT_SCHEMA": "shape_behavior.events",
+    "import_gmf": "shape_behavior.gmf",
+    "ImportResult": "shape_behavior.gmf",
+    "Unsupported": "shape_behavior.gmf",
+    "UnsupportedGmfError": "shape_behavior.gmf",
+    "register_state_type": "shape_behavior.extension",
+    "StateHandler": "shape_behavior.extension",
+    "StateContext": "shape_behavior.extension",
+    "Emission": "shape_behavior.extension",
+}
+
+__all__ = sorted(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module 'shape_behavior' has no attribute {name!r}")
+    return getattr(importlib.import_module(module), name)

sqllocks_shape_behavior-0.9.1/src/shape_behavior/behaviors.py

@@ -0,0 +1,150 @@
+"""Behavior modules as ``shape.behaviors`` plugins (plugin API v1, ``Behavior`` protocol).
+
+A :class:`ModuleBehavior` wraps one :class:`~shape_behavior.model.Module` so the engine, the
+plugin host, ``shape plugins list`` and the conformance kit can all reach it by name::
+
+    from shape_behavior.behaviors import behavior
+
+    b = behavior({"format": "shape-behavior/1", "name": "my_process", "states": {...}})
+    events = b.simulate(population=1000, seed=7, years=3)   # a pyarrow.Table
+
+The built-in examples register under ``shape.behaviors`` through the classes at the bottom of
+this file; a third-party package registers its own module the same way
+(``docs/plugins/behavior.md``, section 10).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from shape_behavior.extension import get_handler
+from shape_behavior.model import EVENT_KINDS, Module, load_module
+
+SHAPE_API = "1.0"
+VERSION = "1.0"
+
+DEFAULT_POPULATION: dict[str, Any] = {
+    "age_at_start": {"kind": "uniform", "low": 0, "high": 90},
+    "attributes": {"gender": {"kind": "categorical", "values": {"F": 0.5, "M": 0.5}}},
+}
+
+
+def population_settings(modules: list[Module]) -> dict[str, Any]:
+    """The population settings the modules ask for (``population_defaults``; the first module
+    wins on a clash), or :data:`DEFAULT_POPULATION` when none asks."""
+    import copy
+
+    spec: dict[str, Any] = {}
+    for m in reversed(modules):
+        spec.update(m.doc.get("population_defaults", {}))
+    return spec or copy.deepcopy(DEFAULT_POPULATION)
+
+
+class ModuleBehavior:
+    """One module as a ``shape.behaviors`` plugin: name, version, states, attributes, events."""
+
+    def __init__(self, module: Module | dict[str, Any] | str, version: str = VERSION) -> None:
+        self.module = load_module(module)
+        self.name: str = self.module.name
+        self.version: str = str(self.module.doc.get("version", version))
+        self.states: list[str] = list(self.module.states)
+        self.attributes: list[str] = sorted(self.module.attribute_uses())
+        self.events: list[str] = _event_kinds(self.module)
+
+    def simulate(self, population: int, seed: int, years: float) -> Any:
+        """Events of ``population`` entities over ``years`` from 2020-01-01, deterministic per
+        ``seed`` (an Arrow table in :data:`shape_behavior.EVENT_SCHEMA`)."""
+        from shape_behavior.population import Population
+        from shape_behavior.simulator import SimConfig, Simulator
+        from shape_behavior.timeutil import add_years, to_us
+
+        start = "2020-01-01"
+        pop = Population.from_dict(population_settings([self.module]), size=population, start=start)
+        sim = Simulator([self.module], pop, SimConfig(seed=seed))
+        return sim.run_until(add_years(to_us(start), years))
+
+
+def behavior(module: Module | dict[str, Any] | str, version: str = VERSION) -> ModuleBehavior:
+    """A :class:`ModuleBehavior` for a module, a module document or a module file path."""
+    return ModuleBehavior(module, version)
+
+
+def _event_kinds(module: Module) -> list[str]:
+    kinds: set[str] = set()
+    for state in module.states.values():
+        kind = state["type"]
+        if kind == "event":
+            kinds.add(str(state["event"]))
+        elif kind in EVENT_KINDS:
+            kinds.add(EVENT_KINDS[kind])
+        else:  # a registered state type may declare the kinds it emits (optional `kinds`)
+            declared = getattr(get_handler(kind), "kinds", None)
+            if declared is not None:
+                kinds.update(declared(state))
+    return sorted(kinds)
+
+
+class Subscription(ModuleBehavior):
+    """Subscription lifecycle: free trial, conversion, monthly payments, pause and cancel."""
+
+    def __init__(self) -> None:
+        super().__init__("subscription")
+
+
+class EquipmentMaintenance(ModuleBehavior):
+    """Equipment maintenance: run, degrade, fail, repair, with scheduled inspections."""
+
+    def __init__(self) -> None:
+        super().__init__("equipment_maintenance")
+
+
+class HealthcareScreening(ModuleBehavior):
+    """A tiny healthcare example (screening, diagnosis, treatment), written from scratch."""
+
+    def __init__(self) -> None:
+        super().__init__("healthcare_screening")
+
+
+class EventSequence(ModuleBehavior):
+    """An ordered funnel of named events with a continue probability per step (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import event_sequence
+
+        super().__init__(event_sequence())
+
+
+class TelemetrySeries(ModuleBehavior):
+    """A regular reading per device with drift, noise, skipped and stuck readings (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import telemetry_series
+
+        super().__init__(telemetry_series())
+
+
+class TransactionStream(ModuleBehavior):
+    """Transactions as a Poisson process per entity, with refunds and reversals (defaults)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import transaction_stream
+
+        super().__init__(transaction_stream())
+
+
+class FileArrival(ModuleBehavior):
+    """A feed with an expected arrival per schedule slot: on time, late, missing, duplicated."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import file_arrival
+
+        super().__init__(file_arrival())
+
+
+class EntityLifecycle(ModuleBehavior):
+    """Create, update and delete events per entity (change-data-capture style)."""
+
+    def __init__(self) -> None:
+        from shape_behavior.primitives import entity_lifecycle
+
+        super().__init__(entity_lifecycle())

sqllocks_shape_behavior-0.9.1/src/shape_behavior/cli.py

@@ -0,0 +1,240 @@
+"""``shape behave``: run, check and import behavior modules.
+
+Reference: ``docs/plugins/behavior.md``, section 7.
+
+::
+
+    shape behave run subscription --population 10000 --years 3 --seed 7 -o out/
+    shape behave check my_module.json
+    shape behave import-gmf downloaded_module.json -o converted.json
+    shape behave examples -o modules/
+
+Nothing heavy loads at import time: NumPy, Arrow and the simulator load when a command runs.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from shape_behavior.params import (
+    PRIMITIVE_NAMES,
+    PrimitiveParamsError,
+    read_params,
+    unknown_primitive,
+)
+
+SHAPE_API = "1.0"
+
+
+class BehaveCommand:
+    """``shape behave COMMAND ...``."""
+
+    name = "behave"
+    help = "run state-machine behavior modules on a virtual clock (events as Parquet)"
+
+    def configure(self, parser: Any) -> None:
+        sub = parser.add_subparsers(dest="behave_cmd", required=True, metavar="COMMAND")
+        run = sub.add_parser("run", help="simulate a population and write the event stream")
+        run.add_argument(
+            "modules",
+            nargs="+",
+            metavar="MODULES",
+            help="module files (native or GMF JSON) or example names",
+        )
+        run.add_argument(
+            "--population", type=int, required=True, metavar="N", help="number of entities"
+        )
+        run.add_argument(
+            "--years", type=float, required=True, metavar="Y", help="years to simulate"
+        )
+        run.add_argument("--seed", type=int, default=0, help="random seed (default 0)")
+        run.add_argument("-o", "--out", required=True, metavar="OUT", help="output directory")
+        run.add_argument(
+            "--start", default="2020-01-01", help="virtual clock start (default 2020-01-01)"
+        )
+        run.add_argument(
+            "--population-spec",
+            metavar="FILE",
+            help="JSON population settings (attributes, age_at_start, arrival, lifetime)",
+        )
+        run.add_argument(
+            "--window-years", type=float, default=1.0, help="years per output file (default 1)"
+        )
+        run.add_argument(
+            "--poll", default="7 days", help="guard polling interval (default '7 days')"
+        )
+        run.add_argument("--strict", action="store_true", help="fail on unsupported GMF elements")
+        run.add_argument(
+            "--params",
+            metavar="FILE.json",
+            help="parameters of a primitive named in MODULES "
+            '({"format": "shape-behavior-params", "version": 1, "primitive": NAME, "params": {}})',
+        )
+        run.set_defaults(fn=_run)
+        check = sub.add_parser("check", help="validate modules; exit 1 when one is invalid")
+        check.add_argument("modules", nargs="+", metavar="MODULES")
+        check.add_argument("--strict", action="store_true", help="fail on unsupported GMF elements")
+        check.set_defaults(fn=_check)
+        imp = sub.add_parser(
+            "import-gmf", help="convert a GMF module and report what is unsupported"
+        )
+        imp.add_argument("file", help="the GMF JSON file you downloaded")
+        imp.add_argument("-o", "--out", metavar="OUT.json", help="write the native module here")
+        imp.add_argument("--strict", action="store_true", help="fail on unsupported elements")
+        imp.set_defaults(fn=_import)
+        ex = sub.add_parser("examples", help="list the built-in example modules, or write them")
+        ex.add_argument("-o", "--out", metavar="DIR", help="write the examples into DIR")
+        ex.set_defaults(fn=_examples)
+
+    def run(self, args: Any) -> int:
+        try:
+            return int(args.fn(args))
+        except (FileNotFoundError, json.JSONDecodeError, PrimitiveParamsError) as exc:
+            print(f"shape behave: {exc}", file=sys.stderr)
+            return 2
+        except ValueError as exc:  # includes ModuleError, UnsupportedGmfError
+            print(f"shape behave: {exc}", file=sys.stderr)
+            return 1
+
+
+def _load(sources: list[str], strict: bool, params: str | None = None) -> list[Any]:
+    from shape_behavior.model import load_module
+
+    primitive, values = read_params(Path(params)) if params else ("", {})
+    if params and primitive not in sources:
+        if primitive not in PRIMITIVE_NAMES:
+            raise unknown_primitive(primitive)
+        raise PrimitiveParamsError(
+            f"--params is for primitive {primitive!r}, which is not among the modules to run "
+            f"({', '.join(sources)})",
+            "primitive",
+        )
+    if params:
+        from shape_behavior.primitives import build
+    modules = []
+    for src in sources:
+        module = (
+            build(primitive, values)
+            if params and src == primitive
+            else load_module(src, strict=strict)
+        )
+        report = module.import_report
+        if report is not None and (report.unsupported or report.warnings):
+            print(f"{src}:\n{report.report()}", file=sys.stderr)
+        modules.append(module)
+    return modules
+
+
+def _run(args: Any) -> int:
+    import pyarrow.parquet as pq  # type: ignore[import-untyped]
+
+    from shape_behavior.behaviors import population_settings
+    from shape_behavior.population import Population
+    from shape_behavior.simulator import SimConfig, Simulator
+    from shape_behavior.timeutil import add_years, to_us
+
+    if args.population < 0 or args.years <= 0 or args.window_years <= 0:
+        print(
+            "shape behave: --population must be >= 0 and --years and --window-years > 0",
+            file=sys.stderr,
+        )
+        return 2
+    modules = _load(args.modules, args.strict, args.params)
+    if args.population_spec:
+        spec = json.loads(Path(args.population_spec).read_text(encoding="utf-8"))
+    else:
+        spec = population_settings(modules)
+    population = Population.from_dict(spec, size=args.population, start=args.start)
+    sim = Simulator(modules, population, SimConfig(seed=args.seed, poll=args.poll))
+    out = Path(args.out)
+    (out / "events").mkdir(parents=True, exist_ok=True)
+    start = to_us(args.start)
+    end = add_years(start, args.years)
+    started = time.perf_counter()
+    windows: list[dict[str, Any]] = []
+    cursor, part = start, 0
+    while cursor < end:
+        nxt = min(add_years(start, args.window_years * (part + 1)), end)
+        events = sim.run_until(nxt)
+        pq.write_table(events, out / "events" / f"part-{part:04d}.parquet", compression="snappy")
+        windows.append(
+            {
+                "file": f"events/part-{part:04d}.parquet",
+                "until": str(sim.now),
+                "rows": events.num_rows,
+            }
+        )
+        cursor, part = nxt, part + 1
+    pq.write_table(sim.entities(), out / "entities.parquet", compression="snappy")
+    elapsed = time.perf_counter() - started
+    total = sum(w["rows"] for w in windows)
+    manifest = {
+        "seed": args.seed,
+        "years": args.years,
+        "start": args.start,
+        "population": population.to_dict(),
+        "modules": [_module_entry(m, s) for m, s in zip(modules, args.modules, strict=True)],
+        "events": total,
+        "windows": windows,
+        "seconds": round(elapsed, 3),
+        "unsupported": [
+            str(u) for m in modules if m.import_report for u in m.import_report.unsupported
+        ],
+    }
+    (out / "run.json").write_text(
+        json.dumps(manifest, indent=2) + "\n", encoding="utf-8", newline="\n"
+    )
+    print(f"{total:,} events for {args.population:,} entities in {elapsed:.1f}s -> {out}")
+    return 0
+
+
+def _module_entry(module: Any, source: str) -> dict[str, Any]:
+    entry: dict[str, Any] = {"name": module.name, "digest": module.digest(), "source": source}
+    if "primitive" in module.doc:  # a primitive: record the parameters it ran with
+        entry["primitive"] = module.doc["primitive"]
+        entry["parameters"] = module.doc["parameters"]
+    return entry
+
+
+def _check(args: Any) -> int:
+    modules = _load(args.modules, args.strict)
+    for m in modules:
+        print(f"ok  {m.name}  ({len(m.states)} states)")
+    return 0
+
+
+def _import(args: Any) -> int:
+    from shape_behavior.gmf import import_gmf
+
+    result = import_gmf(Path(args.file), strict=args.strict)
+    print(result.report())
+    if args.out:
+        Path(args.out).write_text(
+            json.dumps(result.module.to_dict(), indent=2) + "\n", encoding="utf-8", newline="\n"
+        )
+        print(f"wrote {args.out}")
+    return 0
+
+
+def _examples(args: Any) -> int:
+    import importlib.resources
+
+    from shape_behavior.model import examples
+
+    names = examples()
+    if not args.out:
+        print("\n".join(names))
+        return 0
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    for name in names:
+        text = (
+            importlib.resources.files("shape_behavior") / "examples" / f"{name}.json"
+        ).read_text(encoding="utf-8")
+        (out / f"{name}.json").write_text(text, encoding="utf-8", newline="\n")
+    print(f"wrote {len(names)} modules to {out}")
+    return 0