PyPI - expdeploy - Versions diffs - 0.1.0__py3-none-any.whl - Mend

expdeploy 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (37) hide show

expdeploy/__init__.py +3 -0
expdeploy/__main__.py +6 -0
expdeploy/app.py +256 -0
expdeploy/battery/__init__.py +0 -0
expdeploy/battery/counterbalance.py +86 -0
expdeploy/battery/orchestrator.py +48 -0
expdeploy/cli.py +580 -0
expdeploy/importmap.py +76 -0
expdeploy/jspsych_assets/8.2.3/jspsych.css +524 -0
expdeploy/jspsych_assets/8.2.3/jspsych.js +5535 -0
expdeploy/jspsych_assets/8.2.3/manifest.json +53 -0
expdeploy/jspsych_assets/8.2.3/plugins/call-function.js +69 -0
expdeploy/jspsych_assets/8.2.3/plugins/fullscreen.js +164 -0
expdeploy/jspsych_assets/8.2.3/plugins/html-button-response.js +223 -0
expdeploy/jspsych_assets/8.2.3/plugins/html-keyboard-response.js +183 -0
expdeploy/jspsych_assets/8.2.3/plugins/image-button-response.js +326 -0
expdeploy/jspsych_assets/8.2.3/plugins/image-keyboard-response.js +270 -0
expdeploy/jspsych_assets/8.2.3/plugins/instructions.js +341 -0
expdeploy/jspsych_assets/8.2.3/plugins/preload.js +384 -0
expdeploy/jspsych_assets/8.2.3/plugins/survey-text.js +244 -0
expdeploy/jspsych_assets/__init__.py +1 -0
expdeploy/loader.py +44 -0
expdeploy/manifest.py +127 -0
expdeploy/renderer.py +37 -0
expdeploy/session.py +96 -0
expdeploy/storage/__init__.py +1 -0
expdeploy/storage/base.py +57 -0
expdeploy/storage/fs.py +193 -0
expdeploy/storage/sqlite.py +171 -0
expdeploy/storage/supabase.py +104 -0
expdeploy/storage/supabase_schema.sql +26 -0
expdeploy/templates/deploy.html.j2 +46 -0
expdeploy-0.1.0.dist-info/METADATA +65 -0
expdeploy-0.1.0.dist-info/RECORD +37 -0
expdeploy-0.1.0.dist-info/WHEEL +4 -0
expdeploy-0.1.0.dist-info/entry_points.txt +2 -0
expdeploy-0.1.0.dist-info/licenses/LICENSE +21 -0

expdeploy/__init__.py ADDED Viewed

@@ -0,0 +1,3 @@
+"""expdeploy — modern Python deploy tool for jsPsych v8 experiments."""
+__version__ = "0.1.0"

expdeploy/__main__.py ADDED Viewed

@@ -0,0 +1,6 @@
+"""Entry point for `python -m expdeploy`."""
+from expdeploy.cli import app
+if __name__ == "__main__":
+    app()

expdeploy/app.py ADDED Viewed

@@ -0,0 +1,256 @@
+"""FastAPI app factory and route handlers."""
+from __future__ import annotations
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from expdeploy import __version__
+from expdeploy.battery.counterbalance import CounterbalanceStrategy
+from expdeploy.battery.orchestrator import BatteryOrchestrator
+from expdeploy.importmap import ImportMapBuilder
+from expdeploy.loader import LoadedExperiment
+from expdeploy.manifest import BatteryManifest
+from expdeploy.renderer import render_experiment_html
+from expdeploy.session import RunSession
+from expdeploy.storage.base import RunRecord, StorageAdapter
+COMPLETE_HTML = """<!DOCTYPE html>
+<html><body style="text-align:center;margin-top:4em;font-family:system-ui,sans-serif;">
+<h1>Battery complete</h1>
+<p>All experiments finished. You may close this tab.</p>
+</body></html>
+"""
+@dataclass(frozen=True, slots=True)
+class AppConfig:
+    """A single-experiment OR battery deployment config.
+    Exactly one of `experiment` or `(battery_manifest, experiments_by_id)` is set.
+    """
+    vendored_root: Path
+    storage: StorageAdapter  # primary always-on (FSAdapter)
+    catalog: StorageAdapter | None  # SQLiteCatalog or None
+    state_dir: Path  # for RunSession
+    subject_id: str
+    session_num: str | None
+    run_num: str | None
+    # Single-experiment mode
+    experiment: LoadedExperiment | None = None
+    # Battery mode
+    battery_manifest: BatteryManifest | None = None
+    experiments_by_id: dict[str, LoadedExperiment] | None = None
+    counterbalance_strategy: CounterbalanceStrategy | None = None
+    # Remote adapters (mirrors; best-effort)
+    remotes: tuple[StorageAdapter, ...] = ()
+    def is_battery(self) -> bool:
+        return self.battery_manifest is not None
+def create_app(config: AppConfig) -> FastAPI:
+    app = FastAPI(title="expdeploy", version=__version__)
+    builder = ImportMapBuilder(vendored_root=config.vendored_root)
+    # Mount vendored jsPsych once (single version for now).
+    if config.is_battery():
+        assert config.experiments_by_id is not None
+        any_exp = next(iter(config.experiments_by_id.values()))
+    else:
+        assert config.experiment is not None
+        any_exp = config.experiment
+    jspsych_version = any_exp.manifest.jspsych.version
+    jspsych_dir = config.vendored_root / jspsych_version
+    if not jspsych_dir.is_dir():
+        msg = f"jsPsych version {jspsych_version} not vendored"
+        raise LookupError(msg)
+    app.mount(
+        f"/static/jspsych/{jspsych_version}",
+        StaticFiles(directory=str(jspsych_dir)),
+        name="static-jspsych",
+    )
+    # Mount each experiment dir.
+    if config.is_battery():
+        assert config.experiments_by_id is not None
+        for exp_id, loaded in config.experiments_by_id.items():
+            app.mount(
+                f"/static/exp/{exp_id}",
+                StaticFiles(directory=str(loaded.path)),
+                name=f"static-experiment-{exp_id}",
+            )
+    else:
+        assert config.experiment is not None
+        exp_id_single = config.experiment.manifest.experiment.exp_id
+        app.mount(
+            f"/static/exp/{exp_id_single}",
+            StaticFiles(directory=str(config.experiment.path)),
+            name="static-experiment",
+        )
+    # Orchestrator (battery mode only)
+    orchestrator: BatteryOrchestrator | None = None
+    if config.is_battery():
+        assert config.battery_manifest is not None and config.counterbalance_strategy is not None
+        session = RunSession(state_dir=config.state_dir, subject_id=config.subject_id)
+        orchestrator = BatteryOrchestrator(
+            manifest=config.battery_manifest,
+            strategy=config.counterbalance_strategy,
+            session=session,
+        )
+        orchestrator.start()
+    def _render_for(loaded: LoadedExperiment) -> str:
+        exp_id = loaded.manifest.experiment.exp_id
+        import_map = builder.build(
+            loaded,
+            jspsych_url_prefix=f"/static/jspsych/{jspsych_version}",
+            experiment_url_prefix=f"/static/exp/{exp_id}",
+        )
+        style_url = (
+            f"/static/exp/{exp_id}/{loaded.manifest.experiment.style}"
+            if loaded.manifest.experiment.style
+            else None
+        )
+        return render_experiment_html(
+            exp_id=exp_id,
+            experiment_entry_url=f"/static/exp/{exp_id}/{loaded.manifest.experiment.entry}",
+            style_url=style_url,
+            jspsych_css_url=f"/static/jspsych/{jspsych_version}/jspsych.css",
+            import_map=import_map,
+            runtime_globals={
+                "expId": exp_id,
+                "subjectId": config.subject_id,
+                "sessionNum": config.session_num,
+                "runNum": config.run_num,
+                "deployVersion": __version__,
+            },
+            post_url="/api/data",
+        )
+    @app.get("/", response_class=HTMLResponse)
+    def serve_root() -> HTMLResponse:
+        if orchestrator is not None:
+            ref = orchestrator.next_experiment()
+            if ref is None:
+                return HTMLResponse(content=COMPLETE_HTML)
+            assert config.experiments_by_id is not None
+            loaded = config.experiments_by_id[ref.exp_id]
+            return HTMLResponse(content=_render_for(loaded))
+        assert config.experiment is not None
+        return HTMLResponse(content=_render_for(config.experiment))
+    @app.get("/healthz")
+    def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+    @app.get("/readyz")
+    def readyz() -> dict[str, str]:
+        return {"status": "ready"}
+    @app.get("/api/state")
+    def get_state() -> JSONResponse:
+        if orchestrator is None:
+            assert config.experiment is not None
+            exp_id = config.experiment.manifest.experiment.exp_id
+            return JSONResponse({"current": exp_id, "completed": [], "order": [exp_id]})
+        session = orchestrator.session
+        return JSONResponse(
+            {
+                "current": session.current(),
+                "completed": session.completed(),
+                "order": [e.exp_id for e in orchestrator.manifest.experiments],
+                "battery_id": orchestrator.battery_id,
+            }
+        )
+    @app.post("/api/state")
+    def update_state(action: dict[str, Any]) -> JSONResponse:
+        if orchestrator is None:
+            raise HTTPException(status_code=400, detail="not a battery deployment")
+        op = action.get("op")
+        if op == "reset":
+            orchestrator.session.reset()
+            orchestrator.start()
+        elif op == "skip":
+            orchestrator.advance()
+        else:
+            raise HTTPException(status_code=400, detail=f"unknown op {op!r}")
+        return JSONResponse({"current": orchestrator.session.current()})
+    @app.post("/api/data")
+    def post_data(payload: dict[str, Any]) -> JSONResponse:
+        try:
+            record = RunRecord(
+                exp_id=payload.get("exp_id", ""),
+                subject_id=payload.get("subject_id") or config.subject_id,
+                session_num=payload.get("session_num") or config.session_num,
+                run_num=payload.get("run_num") or config.run_num,
+                battery_id=(orchestrator.battery_id if orchestrator else None),
+                started_at=payload["started_at"],
+                ended_at=payload["ended_at"],
+                status=payload.get("status", "finished"),
+                trials=payload.get("trials", []),
+                interaction_data=payload.get("interaction_data", []),
+                jspsych_version=payload.get("jspsych_version"),
+                deploy_version=payload.get("deploy_version"),
+                client_user_agent=payload.get("client_user_agent"),
+                raw_payload=payload,
+            )
+        except Exception as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        result = config.storage.save(record)
+        if not result.ok:
+            raise HTTPException(status_code=500, detail=result.error or "save failed")
+        # SQLite catalog write (best-effort but synchronous)
+        if config.catalog is not None:
+            config.catalog.save(record)
+        # Remote adapter writes (best-effort mirrors)
+        for remote in config.remotes:
+            rresult = remote.save(record)
+            if config.catalog is not None:
+                from expdeploy.storage.sqlite import SQLiteCatalog
+                if isinstance(config.catalog, SQLiteCatalog):
+                    config.catalog.record_remote_attempt(
+                        record.run_id,
+                        remote.name,
+                        "synced" if rresult.ok else "failed",
+                        remote_uri=rresult.path if rresult.ok else None,
+                        error=None if rresult.ok else rresult.error,
+                    )
+        # BIDS write if applicable
+        loaded = _find_loaded(config, record.exp_id)
+        if (
+            loaded is not None
+            and loaded.manifest.bids is not None
+            and hasattr(config.storage, "save_bids")
+        ):
+            config.storage.save_bids(record, loaded.manifest)
+        # Advance battery
+        if orchestrator is not None:
+            orchestrator.advance()
+        return JSONResponse({"ok": True, "path": result.path})
+    return app
+def _find_loaded(config: AppConfig, exp_id: str | None) -> LoadedExperiment | None:
+    if exp_id is None:
+        return None
+    if config.experiments_by_id is not None:
+        return config.experiments_by_id.get(exp_id)
+    if config.experiment is not None and config.experiment.manifest.experiment.exp_id == exp_id:
+        return config.experiment
+    return None

expdeploy/battery/__init__.py ADDED Viewed

File without changes

expdeploy/battery/counterbalance.py ADDED Viewed

@@ -0,0 +1,86 @@
+"""Counterbalance strategies — 4 implementations of CounterbalanceStrategy."""
+from __future__ import annotations
+import csv
+import random
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+@runtime_checkable
+class CounterbalanceStrategy(Protocol):
+    name: str
+    def order_for(self, subject_id: str, experiments: list[str]) -> list[str]: ...
+class FixedStrategy:
+    name = "fixed"
+    def order_for(self, subject_id: str, experiments: list[str]) -> list[str]:
+        return list(experiments)
+class LatinSquareStrategy:
+    """Balanced KxK Latin square; subject row = int(subject_id) mod K."""
+    name = "latin_square"
+    def order_for(self, subject_id: str, experiments: list[str]) -> list[str]:
+        try:
+            n = int(subject_id)
+        except ValueError as exc:
+            msg = f"latin_square requires integer-parseable subject_id; got {subject_id!r}"
+            raise ValueError(msg) from exc
+        k = len(experiments)
+        row = n % k
+        # Williams-style Latin square: position j of row i = (i + j) mod K
+        return [experiments[(row + j) % k] for j in range(k)]
+class SeededRandomStrategy:
+    """Per-subject deterministic shuffle. Seed derived from subject_id."""
+    name = "seeded_random"
+    def order_for(self, subject_id: str, experiments: list[str]) -> list[str]:
+        rng = random.Random(subject_id)
+        out = list(experiments)
+        rng.shuffle(out)
+        return out
+class UserSuppliedStrategy:
+    """Reads order_csv; rows are subject_id, pos_1, pos_2, ..."""
+    name = "user_supplied"
+    def __init__(self, order_csv: Path) -> None:
+        self.order_csv = Path(order_csv)
+        self._cache: dict[str, list[str]] | None = None
+    def _load(self) -> dict[str, list[str]]:
+        if self._cache is not None:
+            return self._cache
+        out: dict[str, list[str]] = {}
+        with self.order_csv.open() as f:
+            reader = csv.reader(f)
+            header = next(reader, None)
+            if header is None or len(header) < 2:
+                msg = f"order_csv {self.order_csv} missing header / columns"
+                raise ValueError(msg)
+            for row in reader:
+                if not row:
+                    continue
+                subject = row[0]
+                out[subject] = [c for c in row[1:] if c]
+        self._cache = out
+        return out
+    def order_for(self, subject_id: str, experiments: list[str]) -> list[str]:
+        loaded = self._load()
+        if subject_id not in loaded:
+            msg = f"subject_id {subject_id!r} not in {self.order_csv}"
+            raise KeyError(msg)
+        return loaded[subject_id]

expdeploy/battery/orchestrator.py ADDED Viewed

@@ -0,0 +1,48 @@
+"""BatteryOrchestrator — ties manifest + strategy + session."""
+from __future__ import annotations
+import hashlib
+import json
+from expdeploy.battery.counterbalance import CounterbalanceStrategy
+from expdeploy.manifest import BatteryExperimentRef, BatteryManifest
+from expdeploy.session import RunSession
+class BatteryOrchestrator:
+    def __init__(
+        self,
+        *,
+        manifest: BatteryManifest,
+        strategy: CounterbalanceStrategy,
+        session: RunSession,
+    ) -> None:
+        self.manifest = manifest
+        self.strategy = strategy
+        self.session = session
+    @property
+    def battery_id(self) -> str:
+        """Stable id derived from the manifest. Subject-independent."""
+        payload = self.manifest.model_dump(mode="json")
+        digest = hashlib.sha256(json.dumps(payload, sort_keys=True).encode("utf-8")).hexdigest()
+        return digest[:16]
+    def start(self) -> None:
+        experiments_by_id = {e.exp_id: e for e in self.manifest.experiments}
+        order = self.strategy.order_for(self.session.subject_id, list(experiments_by_id.keys()))
+        self.session.initialize(battery_id=self.battery_id, order=order)
+    def next_experiment(self) -> BatteryExperimentRef | None:
+        current_id = self.session.current()
+        if current_id is None:
+            return None
+        for e in self.manifest.experiments:
+            if e.exp_id == current_id:
+                return e
+        msg = f"current experiment {current_id!r} not in manifest"
+        raise LookupError(msg)
+    def advance(self) -> None:
+        self.session.advance()