shadowbox 0.3.0__py3-none-any.whl

shadowbox/store.py

@@ -0,0 +1,85 @@
+"""SQLite persistence for models, simulations, and reports (M4a local server).
+
+Cloud deploy (M4b) swaps this module for a D1-backed store with the same
+function signatures; the API layer does not change.
+"""
+
+import json
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Any
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS models (
+  id TEXT PRIMARY KEY,
+  body TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS simulations (
+  id TEXT PRIMARY KEY,
+  model_id TEXT NOT NULL REFERENCES models(id),
+  scenario TEXT NOT NULL,
+  seed INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  report TEXT NOT NULL
+);
+"""
+
+
+def _connect(path: Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(path)
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.executescript(_SCHEMA)
+    return conn
+
+
+class Store:
+    """File-backed store; one connection per call keeps the API thread-safe."""
+
+    def __init__(self, path: Path) -> None:
+        self._path = path  # file created lazily on first use, never on import
+
+    def _new_id(self) -> str:
+        return uuid.uuid4().hex[:16]
+
+    def save_model(self, body: dict[str, Any]) -> str:
+        model_id = self._new_id()
+        with _connect(self._path) as conn:
+            conn.execute(
+                "INSERT INTO models (id, body) VALUES (?, ?)", (model_id, json.dumps(body))
+            )
+        return model_id
+
+    def get_model(self, model_id: str) -> dict[str, Any] | None:
+        with _connect(self._path) as conn:
+            row = conn.execute("SELECT body FROM models WHERE id = ?", (model_id,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+    def save_simulation(
+        self, model_id: str, scenario: dict[str, Any], seed: int, report: dict[str, Any]
+    ) -> str:
+        sim_id = self._new_id()
+        with _connect(self._path) as conn:
+            conn.execute(
+                "INSERT INTO simulations (id, model_id, scenario, seed, status, report)"
+                " VALUES (?, ?, ?, ?, 'completed', ?)",
+                (sim_id, model_id, json.dumps(scenario), seed, json.dumps(report)),
+            )
+        return sim_id
+
+    def get_simulation(self, sim_id: str) -> dict[str, Any] | None:
+        with _connect(self._path) as conn:
+            row = conn.execute(
+                "SELECT model_id, scenario, seed, status, report FROM simulations WHERE id = ?",
+                (sim_id,),
+            ).fetchone()
+        if row is None:
+            return None
+        return {
+            "id": sim_id,
+            "model_id": row[0],
+            "scenario": json.loads(row[1]),
+            "seed": row[2],
+            "status": row[3],
+            "report": json.loads(row[4]),
+        }

shadowbox-0.3.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: shadowbox
+Version: 0.3.0
+Summary: Executable architectural model for safe what-if experimentation (M0: contracts + validate)
+License: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# ShadowBox
+
+Executable architectural model for safe what-if experimentation. Model the system. Experiment safely.
+
+> Scope: headless CLI (validate, simulate, compare, report, import, init, serve) plus local API, static demo, and React Studio. Simulation output is always labeled with assumptions, confidence, and seed — never presented as production measurement.
+
+## Requirements
+
+- Python `>=3.13` (pinned via `.python-version`)
+- `uv` for env and runs (no Docker needed)
+
+## Install
+
+With a clone (development):
+
+```powershell
+uv python pin 3.13
+uv venv
+uv sync --group dev
+```
+
+Without a clone (use only):
+
+```powershell
+uvx --from "shadowbox @ git+https://github.com/Pa004/shadowBox.git@v0.2.0" shadowbox init --out demo
+```
+
+## Run in development
+
+```powershell
+uv run shadowbox init --out demo
+uv run shadowbox import --from demo/docker-compose.yaml --out demo/model2.yaml
+uv run shadowbox validate demo/model.yaml --scenario demo/scenarios/db-failure.yaml
+uv run shadowbox simulate demo/model.yaml --scenario demo/scenarios/db-failure.yaml --seed 42 --out report.json
+uv run shadowbox report report.json --format text
+uv run shadowbox compare --a base.json --b report.json
+```
+
+Exit codes: `0` valid/pass, `2` scenario regression (compare), `3` invalid input or existing files without `--force` (prints `E_*` code).
+
+Import notes: every performance field is an estimated default (see warnings). Calibrate before trusting output.
+
+Chaos cards ship in the package (`init` writes them to `cards/`): `db-down`, `cache-poison`, `latency-500ms`, `traffic-10x`, `zone-loss`, `slow-dependency`, `queue-overflow`.
+
+## API server (local)
+
+```powershell
+uv run uvicorn shadowbox.api:app --port 8000
+# or: uv run shadowbox serve --port 8000
+```
+
+Endpoints: `POST /api/v1/models`, `GET /api/v1/models/{id}`, `POST /api/v1/simulations?model_id=...`, `GET /api/v1/simulations/{id}[/events|/metrics|/report]`. Events are paginated (`limit` 1..1000, `cursor` offset over the stored 500-request sample). State lives in `shadowbox.db` (git-ignored, created on first use). The API has no authentication: bind to localhost (`serve` defaults to `127.0.0.1`) and never expose it directly to the internet.
+
+## Deploy (Cloudflare free tier, no card)
+
+Scaffold ready in `wrangler.jsonc` + `schema.sql` + `apps/api/worker.py` + `apps/web/` (static demo, no build step). Remaining steps need your Cloudflare account:
+
+```powershell
+!npm install -g wrangler
+!wrangler login
+!wrangler d1 create shadowbox  # paste database_id into wrangler.jsonc
+!wrangler d1 execute shadowbox --file schema.sql
+!uvx --from workers-py pywrangler dev   # local Worker emulation, no account needed
+!wrangler deploy
+```
+
+Production note: the Worker serves the same FastAPI app; swapping the SQLite file store for the D1 binding is a follow-up task verified against a real account (M4b-full). The static demo deploys to Pages as-is and talks to any API base URL.
+
+Open `apps/web/index.html` after `Run` to scrub virtual time: the SVG graph colors failed components red and shows active faults per second (first 500 sampled requests).
+
+## Studio (React + Cytoscape)
+
+Full UI in `apps/studio/` (Vite, strict TS). Needs Node deps (run yourself):
+
+```powershell
+cd apps/studio
+npm install
+npm run build   # tsc plus vite
+npm run dev     # /api proxies to 127.0.0.1:8000
+```
+
+Run any scenario vs baseline, inspect p99/error verdict, scrub the failure cascade on the Cytoscape graph.
+
+## Environment variables
+
+None required. Server mode reads no env vars yet; Cloudflare D1 bindings arrive with the production Worker swap.
+
+## Project structure
+
+```text
+src/shadowbox/         # model, dsl, cli, errors, engine, metrics, report, cards, api, store
+src/shadowbox/data/    # canonical example + chaos cards (shipped in the wheel)
+schemas/               # model-v1.json, scenario-v1.json
+tests/                 # unit, deterministic (golden seed 42), property, integration
+tests/fixtures/        # broken models (E_CYCLE, E_REF)
+apps/web/              # static demo with replay (no build)
+apps/studio/           # React + Cytoscape UI (Vite, strict TS)
+```
+
+## Run tests
+
+```powershell
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+Benchmarks (reference: i7-1255U, 16GB, Python 3.13; SLO: 50k events < 2s):
+
+- checkout db-failure (6k reqs, 85k events): ~0.05s
+- 60k reqs, 840k events: ~0.6s
+
+## Deploy notes
+
+Local-first: CLI and `serve` need nothing but Python. Demo deploy: Cloudflare Pages (web) + Python Worker (FastAPI via `workers.asgi`) + D1 — see `Deploy (Cloudflare...)` above. No paid service, no credit card at any tier. See `ShadowBox.md` (local spec, git-ignored) for the full contract.

shadowbox-0.3.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+shadowbox/__init__.py,sha256=o_QtY1_AvIUnqpsVyGITrFt4bdOlGJEo86lcTCcgOuQ,159
+shadowbox/api.py,sha256=g32KlSsMq6pU5uyviHt4gJwAkdbJEtaNbPoKYgm4Mjc,4858
+shadowbox/cards.py,sha256=Ds_T2Og1okx6InFbGumkpzpapVb5uZkrK8KA3fQSycA,2327
+shadowbox/cli.py,sha256=aRw6S0Ypx4peWbDw4Q6FSkPz779Qyic--tZIL6gI5JI,8414
+shadowbox/compare.py,sha256=8dnzO9cqJIIwi3f0-OIxi3Ztq1ZElltz86zi135OmSU,3563
+shadowbox/dsl.py,sha256=nTZSu1StPpudHBdjxDKnylfHPAo8Ym1OxQYvzCt9844,3114
+shadowbox/engine.py,sha256=AJfSJeG9XlzKw26T33B_ohf6ByelXK660U9jRWar1lI,7905
+shadowbox/errors.py,sha256=ZqfRuI2O9RsCJRZQVf9-Q-9XXu4GfY0TaTSk-JqNTfE,707
+shadowbox/metrics.py,sha256=Bb1aAL_kNyjusWfh5mPg_rc6wW89e-SqvUI66D4ti24,1828
+shadowbox/model.py,sha256=eoRNQ_k5hw2MkAxThoBjagQDEwYH217Bew3JCh3Y29o,1926
+shadowbox/report.py,sha256=NU47bqVbDl_FoHcQjVH6VF_X3Ka7YIugPrDtUj8TRJM,1538
+shadowbox/store.py,sha256=zNU6_b9gIPqRrZYKLpBbJLdaNEVIHlEH3wwxDkC-gfY,2684
+shadowbox/data/__init__.py,sha256=jUhnEvdba9MKVpBiy43hbNqZH-H0Vyspnl_23_XjSok,76
+shadowbox/data/cards/cache-poison.yaml,sha256=L7mS51H1Z_V3Jc2J77tJ1LUyyVQYk-LDnaVMOddwXzo,290
+shadowbox/data/cards/db-down.yaml,sha256=ndaEcepXSk4pqnrZSRO5XCd2lAKJv_xVSjON0LTq-HE,267
+shadowbox/data/cards/latency-500ms.yaml,sha256=KRtMmJLin6ztVrLgATIYALtupxcKGu6fMUsO3CWWCr4,356
+shadowbox/data/cards/queue-overflow.yaml,sha256=743eZqtrMjM1n-c9Sd-JyYlZvXh6OxbriCEAybND6wk,212
+shadowbox/data/cards/slow-dependency.yaml,sha256=E2YZDirycQWZabLGXqRv7H1ohWbj_uVes8VX1-D1vDg,323
+shadowbox/data/cards/traffic-10x.yaml,sha256=K2r4w-_u0IIPWZmGVen99TfURUlVwfMuQJr35lxXqY0,214
+shadowbox/data/cards/zone-loss.yaml,sha256=3Sq_f9i_WtPVvfko3Pg7TEkFpmm_HD_spixPyDn6pSo,355
+shadowbox/data/example/docker-compose.yaml,sha256=QtQ2NLVb41So98upHPd8xD7YUYs8TVY7lK-fdtOpBZA,264
+shadowbox/data/example/model.yaml,sha256=Z7rGZMtnc16kXAFBujKVWUbQb4gxhehBLevlbY-sGZg,648
+shadowbox/data/example/scenarios/db-failure.yaml,sha256=h9nXmjMAvG29OPp2W9SkTcx_RQA01IrAAeiE846LX28,270
+shadowbox/importers/__init__.py,sha256=hwFgnRof5uJCK9ea2j-gZqKrv9cHAjliyRQ9qJfwlt0,97
+shadowbox/importers/compose.py,sha256=pjNLtc_oJmjU7nrfiKZHYBsSBzkxGLYnXOU__xCw95k,3834
+shadowbox-0.3.0.dist-info/METADATA,sha256=gLj9g7tIW3m4-6NWjd067uqBG5qdAc7dfeEet6u5h_U,5097
+shadowbox-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shadowbox-0.3.0.dist-info/entry_points.txt,sha256=VYWQuwhvc9Aek2hm5AdJt8sPDC4OVtBk7ZYHFbL2068,48
+shadowbox-0.3.0.dist-info/RECORD,,

shadowbox-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shadowbox-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shadowbox = shadowbox.cli:app