Model builder
The model builder is the P2 map-to-instance prototype. It points at an AOI, shows public and missing sources, previews the fetch plan, records approvals, runs a dry run, streams the stage progress, and shows the review and handoff.
It is not the P10 planning studio, the P11 public demo portal, or a production authentication system. It is a synthetic-data prototype over the P2 catalogue, fetch plan, coverage, gap, and capability contracts.
Run the prototype
python -m pip install -e ".[web]"
uvicorn brushline.web.model_builder:app --reload
Open http://127.0.0.1:8000. The service loads
notes/reference/data-catalogue.v1.json and the synthetic corridor fixture by default. Tests inject
a store with a temporary runtime root so they never write beside the repository artifacts.
Flow
AOI. Select the synthetic corridor or drag a rectangle on the map. A drawn AOI is honest about the prototype gap: every source is missing because there is no spatial coverage query.
Availability. The source list shows the provider, licence, access status, and coverage state. Private connectors are listed separately.
Plan. The plan preview is built before any network call. It shows the source, query, licence, estimate, access, and materialization pointer.
Approvals. Public sources, bulk scope, and private connectors have separate controls. A bulk plan without a bulk approval fails the plan validator. A private connector without an explicit approval stays blocked.
Build. The dry run validates the AOI, plan, corridor, and review, and skips materialization, compilation, state seeding, scenario validation, and demo export. It writes the plan and review metadata, not a dataset payload.
Progress. The stage stream names the stage, the validator, the status, and the evidence.
Review. Segment count, initial state distribution, model cards, coverage counts, gaps, open questions, licences, and provenance.
Handoff. The prototype writes a handoff record and creates a linked instance directory. It does not publish or promote the instance.
A synthetic local build is also available: it compiles the synthetic fixture, seeds the fixture state, validates the template scenario, and copies the demo manifest. It still makes no network call. A custom AOI is blocked after the validation stage because the prototype has no real segmenter or provider pipeline.
API
Route |
Purpose |
|---|---|
|
Static model-builder shell. |
|
Browser assets. |
|
Selectable AOIs, asset types, and standards. |
|
Agent-safe source and connector metadata. |
|
Create a plan-only session. |
|
Read a session. |
|
Record public, bulk, and private-connector approvals. |
|
Run the dry run or the synthetic local build. |
|
Server-sent stage events. |
|
Review summary. |
|
Write the linked instance record. |
Session contract
brushline.model-builder-session.v1 carries the AOI, asset type, management standard, horizon,
currency, selected sources and connectors, approvals, plan, availability, coverage, gap report, status,
stages, review, and handoff.
The status is planned, approved, blocked, or complete. A blocked session keeps the failed
stage, the validator, and the evidence so the reviewer can see why it stopped.
Dry-run outputs
A dry run writes, under the runtime root:
fetch_plan.json: the plan metadata;review.json: the review metadata.
It does not write a dataset, a state artifact, a demo, or a private row. The handoff writes
handoff.json and creates an empty linked instance directory. The synthetic local build adds the
compiled dataset, state, scenario validation report, and demo copy.
Safety and limits
The catalogue endpoint uses the P2 agent-safe view; it never returns an authentication reference.
A private connector is selected only through the explicit approval endpoint.
The dry-run default is
True.The browser surface has no external map library, CDN, telemetry, or live model provider.
There is no production authentication. Run it locally only.
The synthetic coverage is fixture evidence, not a real spatial query.
The review requires a gap panel and open questions.
A custom AOI remains blocked rather than borrowing synthetic coverage.
Tests
tests/test_model_builder.py covers the static shell, catalogue safety, AOI list, plan preview,
public/bulk/private approvals, blocked builds, dry-run outputs, progress streaming, review, handoff,
custom AOI gaps, the synthetic local build, missing routes, and malformed AOIs. It uses FastAPI’s
in-process test client; it does not start a network server.