cellmap_flow.schema

The spec of what the dashboard’s two backends share, and its generation for TypeScript.

The dashboard’s JavaScript speaks to one of two backends, the Flask routes in server mode and the TypeScript routes of web/src/backend in browser mode, and the two must answer alike. What they agree on is written once, in the pydantic request models and in this module, and TypeScript is generated from it, so a change on the Python side reaches the browser’s types by itself and an implementation that drifts fails a test:

python -m cellmap_flow.schema --out web/src/generated --docs docs/api.md (npm run gen in web/) writes cellmap-flow.schema.json, a JSON Schema (draft 2020-12), cellmap-flow.ts, its types by json-schema-to-typescript with the constants and the route table as values, and the route table as Markdown;
--check says whether the committed files are current, with a diff when not (tests/web/test_schema.py and CI’s web job run it).

The schema holds:

every request model of dashboard/requests.py, and the route files’ own (ResolveModel, AddModel, PipelineUpdate), under $defs; the root object maps each route to its body’s model (“POST /api/set-data”);
x-routes: every route of the dashboard and where it is answered (a Route). The method and path come from the Flask app’s url_map, the availability from AVAILABILITY below, and the two must agree: a route added without a declaration is an error naming it (routes());
x-constants: the numbers both modes share (portable/rank.py’s, UNDO_DEPTH, the AI annotation’s caps) and the Finetune tab’s defaults for a blank field, read from finetune/options.py’s TrainingOptions;
x-steps: each normalizer’s and postprocessor’s parameters and defaults (a StepSpec), from their registries.

Attributes

`SCHEMA_DRAFT`
`ROOT`
`GENERATED_DIR`
`DOCS_FILE`
`SCHEMA_NAME`
`TS_NAME`
`JSON2TS`
`REGENERATE`
`Availability`
`AVAILABILITY`
`REQUEST_MODELS`
`FINETUNE_FORM_FIELDS`
`CONSTANT_DOCS`
`BANNER`

Classes

`Route`	One route of the dashboard and where it is answered: "both", by the
`StepSpec`	A normalizer or postprocessor as the dashboard's forms list it: its

Functions

`request_models`() → dict[str, type[pydantic.BaseModel]]	Every request model by name: the public pydantic models
`flask_rules`() → list[tuple[str, str]]	(method, path) for every rule of the dashboard but Flask's own /static.
`routes`([rules]) → list[Route]	The route table: `rules` (by default the Flask app's) with their
`constants`() → dict
`steps`() → dict[str, list[dict]]
`schema`() → dict	The whole schema (see the module's docstring).
`dumps`([spec]) → str
`typescript`([spec, json2ts]) → str	`spec`'s types, by json-schema-to-typescript (web's devDependency), then
`markdown`([spec]) → str	The route table as a Markdown page (docs/api.md).
`outputs`(out_dir, docs) → dict[pathlib.Path, str]	{path: content} of what --out and --docs write.
`check`(files) → list[str]	A unified diff per file of `files` whose content on disk differs.
`main`([argv]) → int

Module Contents

cellmap_flow.schema.SCHEMA_DRAFT = 'https://json-schema.org/draft/2020-12/schema'

cellmap_flow.schema.ROOT

cellmap_flow.schema.GENERATED_DIR

cellmap_flow.schema.DOCS_FILE

cellmap_flow.schema.SCHEMA_NAME = 'cellmap-flow.schema.json'

cellmap_flow.schema.TS_NAME = 'cellmap-flow.ts'

cellmap_flow.schema.JSON2TS

cellmap_flow.schema.REGENERATE = 'python -m cellmap_flow.schema --out web/src/generated --docs docs/api.md (npm run gen in web/)'

cellmap_flow.schema.Availability

class cellmap_flow.schema.Route(/, **data: Any)

One route of the dashboard and where it is answered: “both”, by the Flask route and the browser’s; “stub”, the browser answers the server’s JSON shape with fixed or empty data; “server”, the browser answers unavailable; “browser”, only the page has it. request names the pydantic model its body is parsed with, where there is one.

method: Literal['GET', 'POST', 'PUT', 'DELETE']

path: str

availability: Availability

request: str | None = None

class cellmap_flow.schema.StepSpec(/, **data: Any)

A normalizer or postprocessor as the dashboard’s forms list it: its class, its name, and its constructor’s parameters with their defaults (”” for one without a default).

class_name: str

name: str

params: dict[str, str | int | float | bool | None]

cellmap_flow.schema.AVAILABILITY: dict[str, Availability]

cellmap_flow.schema.REQUEST_MODELS: dict[str, str]

cellmap_flow.schema.FINETUNE_FORM_FIELDS = ('lora_r', 'num_epochs', 'batch_size', 'learning_rate', 'learning_rate_schedule', 'loss_type',...

cellmap_flow.schema.CONSTANT_DOCS

cellmap_flow.schema.request_models() → dict[str, type[pydantic.BaseModel]]: Every request model by name: the public pydantic models dashboard/requests.py defines, and the route files’ own.

cellmap_flow.schema.flask_rules() → list[tuple[str, str]]: (method, path) for every rule of the dashboard but Flask’s own /static.

cellmap_flow.schema.routes(rules: list[tuple[str, str]] | None = None) → list[Route]: The route table: rules (by default the Flask app’s) with their availability, in AVAILABILITY’s order. A rule that AVAILABILITY does not declare, or a declaration (other than a browser-only route) the app no longer has, is a LookupError naming it.

cellmap_flow.schema.constants() → dict

cellmap_flow.schema.steps() → dict[str, list[dict]]

cellmap_flow.schema.schema() → dict: The whole schema (see the module’s docstring).

cellmap_flow.schema.dumps(spec: dict | None = None) → str

cellmap_flow.schema.BANNER = "/* Generated from cellmap-flow's JSON Schema (python -m cellmap_flow.schema, npm run gen). Do...

cellmap_flow.schema.typescript(spec: dict | None = None, json2ts: pathlib.Path = JSON2TS) → str: spec’s types, by json-schema-to-typescript (web’s devDependency), then its constants, route table and steps as values.

cellmap_flow.schema.markdown(spec: dict | None = None) → str: The route table as a Markdown page (docs/api.md).

cellmap_flow.schema.outputs(out_dir: pathlib.Path | None, docs: pathlib.Path | None) → dict[pathlib.Path, str]: {path: content} of what –out and –docs write.

cellmap_flow.schema.check(files: dict[pathlib.Path, str]) → list[str]: A unified diff per file of files whose content on disk differs.

cellmap_flow.schema.main(argv: list[str] | None = None) → int