Expose Schemas

Generic response model for tool/agent outputs.

Structured response that includes a message and any resource references created or modified by the tool.

Successful layer creation result with copy parameters.

Enrichment value domain model.

Fired when one enrichment workflow reaches a terminal state.

Unlike CreditStateChangedEvent this is payload-rich. It carries:

• workflow_id — the client registry's key; routes the event to the cell/column it belongs to.
• project_id / enrichment_id / feature_id — the coordinates, so an event for a workflow the client didn't dispatch in this session (e.g. after a reload, before reconcile) can still build a registry entry from the event alone.
• value — on SUCCESS, the persisted EnrichRowResponse-shaped dict ({value, reasoning, citations, state}) built from the SAME db_value written to the sandbox, so the live cell is byte-identical to what a refresh re-reads. None on FAILURE (no value was written).

The terminal-status policy lives on the server (the workflow's own terminal state), not on the client — so the client can no longer drift a transient signal into a false terminal (the bug class this replaces).

Fired after a project view mutation commits (create / update / filter / delete / column change), over the same per-user channel.

Payload-rich + version-stamped, mirroring EnrichmentStatusChangedEvent: the FE applies the carried view(s) straight to its React Query cache without a refetch round-trip, and uses each view's version to discard stale or out-of-order events. Carries only the affected view(s) plus deletedViewIds (not the full list) so the FE merges rather than overwrites siblings.

Fields are camelCase so the SSE endpoint can forward model_dump_json verbatim and the FE reads the same keys it reads off /views.

Fired after a layer metadata mutation commits (create / delete / rename / restyle / recolor), over the same per-user channel — the layer sibling of ViewStateChangedEvent.

Payload-rich + version-stamped: the FE applies the carried layer(s) straight to its React Query cache without a refetch round-trip, and uses each layer's metadata_version to discard stale or out-of-order events. Carries only the affected layer(s) plus deletedLayerIds so the FE merges rather than overwrites siblings.

Unlike views, the nested layers serialize in their snake_case wire shape — LayerModel has no field aliases, and the FE reads the same snake_case keys off GET /projects/{id}/layers through layerMappers.fromApiModel. So no field_serializer is needed here; the default dump is already the wire shape.

Fired when a chat's background summarize_workflow finishes persisting.

Summarization runs as a fire-and-forget DBOS workflow after a turn crosses the context threshold; the turn's complete SSE frame (carrying summarization_task_id) is the enqueue moment, ~50s before the summary actually generates + persists. The original turn's direct stream has closed by then, so this advisory event over the per-user fanout is how the client learns the summary is genuinely done and renders the "summarized" divider.

Advisory only — the durable summary is the source of truth: on reload the FE reconstructs the divider from persisted history (detectSummarization), so a dropped publish degrades to "divider appears on next reload," never a stuck state.

Carries only projectId (camelCase wire shape, matching ViewStateChangedEvent / LayerStateChangedEvent): chats.project_id is UNIQUE (one chat per project), so the project anchors the chat and the FE needs no chat_id to route.

Settles the "what I did" summary a complete frame said was pending.

The summary is written after the turn's complete frame closes its stream, so it reaches the open chat over the per-user fanout. messageId is the user message that opened the turn; the FE writes the summary onto the assistant reply that follows it. summary is None when none was written, which tells the FE to stop waiting and keep the step sentences.

Advisory only — a written summary is stamped on the turn's last persisted response, so a dropped publish shows on the next reload.

Fired when a project's name changes server-side, over the per-user channel.

The trigger today is auto-title generation: a fire-and-forget task that generates a name several seconds into the turn, and can retry on a later message. By then the project is already ready and the FE's creating-project poller has stopped watching it, so without this event the new name only surfaces on the next projects refetch — a manual refresh in practice.

Carries the coordinates the FE needs to patch the projects-list cache in place: projectId to locate the row, name for the display, and titleSource so the cached row matches what a refetch would read. camelCase wire shape, matching ViewStateChangedEvent / LayerStateChangedEvent.

Advisory only — a dropped publish degrades to the FE's reconnect-resync.

Fired when the agent moves the map camera to a resolved feature, over the per-user channel — the reply to a "zoom to <address/place/parcel>" request.

Carries the envelope bbox ([minLng, minLat, maxLng, maxLat]) of a feature already in the project's data; the FE fitBounds to it. projectId gates the move to the active project (the per-user stream is not project-scoped). commandId lets current clients deduplicate this compatibility event against the ordered tool result. Older clients ignore that additional field. camelCase wire shape, matching the sibling events.

Fire-and-forget / advisory: current clients also receive the ordered tool result, so a dropped compatibility publish does not stop their camera move.

Schema for streaming chat content deltas.

Schema for streaming thinking/reasoning content deltas.

Schema for when a tool call begins.

Schema for when a tool call completes.

Schema for streaming chat completion event.

Schema for general streaming chat error event.

Schema for chat interruption event.

new_messages carries the persisted partial (surfaced) so the live client renders a stopped turn exactly as a reload would — routing any leaked <thinking> reasoning to the thinking display instead of leaving it as raw chat prose. Empty when no partial was persisted (a hard-cancel synthesis), so no partial turn is fabricated.

Schema for web search status updates from built-in tools.

The acting user's prompt, emitted as the FIRST durable stream event.

The live sender already rendered its own message optimistically, so it ignores this echo. A client that reconnects to an in-flight run (page refresh mid-stream) has no optimistic bubble — it replays the durable stream from offset 0 and renders the question from this event, then the deltas that follow. The user message is also persisted at run admission, so a client holding fetched history dedupes this echo against it by message_id.

What the agent's current tool call is actually touching on the map.

Emitted by tools themselves (not the run-event translator), keyed to the tool call so the client can replace that phase's typed preview with truth. Written to the durable chat stream, so it replays on resume like any other event. Multiple emissions per tool call are ordered by seq; a later seq supersedes an earlier one for the same call.

Person contact model parsed from PDL Person Search API.

This model represents a person with their contact information, current job, work history, and education.

Concise tenant / lease model optimized for REIT screens. Includes a small set of critical fields and computed helpers (lease duration, months remaining, rent delta). Use to_dict() to include derived values in output.

A resolved residential mailing address for a parcel's decision-making owner.

The full mortgage & liens profile for one matched property.

Result returned when a query cannot be processed — invalid input, system limitation, or execution blocker.

Lightweight real-time parse of a user query, used for live preview chips.

Model for a layer creation failure.

Terminal event for a run that ended awaiting tool approval (MAIA-2220).

The agent issued a requires_approval tool call (save_skill / update_skill) and the run ended as a pending DeferredToolRequests. The turn is persisted (including the pending call + its tool_approval_request metadata) before this frame is emitted, so the live client renders the approval card from new_messages exactly as a reload would. display: completion is the fail-safe: a consumer that doesn't know this discriminant still finalizes the turn's messages (per stream-terminal-events-carry-consumer-decision-state).

The pending approval-gated tool call, as persisted for card rendering.

What the user agrees to when MAIA asks before filling a column.

The same object travels both ways: dumped by alias into ApprovalRequired(metadata=...) for the card, and validated back off ctx.tool_call_metadata on the approved re-run. There is no second hand-kept key contract between the two halves.

The grant is an amount of work on a named column — config_fingerprint and rows, plus the authority and any credit cost the card quoted — not a named set of rows. fingerprint_for_enrichment covers what the column asks (tool, params, dtype), so an edit to the question re-quotes; the eligible-row ordering is deterministic but not arrival-stable, so a row created after the card was shown can sort inside the approved window. The guarantee that holds is the size and the cost, which is what the card states.

credit_cost and credits_remaining_after are None where the workspace does not charge credits: that path meters in dollars, which are never shown to a customer, and the run tool strips every mention of credits there.

The user's approve/decline for a pending tool call.

message is wire-forward-compat: no UI affordance sends it yet (the card is approve/decline only), but the denial seam already threads it into the synthesized ToolDenied as context for a future decline-reason input. Capped because it persists into chat history and rides every subsequent model call.

One trust-receipt entry.

Carried under two metadata keys with the same shape: attribution (the reply ran a skill / applied a saved preference) and knowledge_saved (the reply saved a new knowledge entry). The key distinguishes the semantic; for knowledge_saved kind is always "knowledge".

The catalog skill a user turn invoked, for the inline chip.

The receipt stamped onto a user turn's ModelRequest.metadata.

The focused feature reaches the agent as turn context and is not otherwise recorded, so once the parcel leaves context nothing can say what a past message was about. This receipt is that record, and the frontend renders its parcel chip from it alone.

label is the display string the client rendered for the feature at send, minted there rather than here: the title falls through several attribute candidates that are frontend display logic, and re-deriving it server-side would drift from what the user actually saw.

The receipt records what the turn was sent with, not what was on screen — an explicit row analysis stamps one while the compose chip is dismissed. A turn whose feature row had not reached the client yet has no title to carry, so no receipt is written and that turn never shows a chip; the ids still ride the request, so the agent is told about the feature either way.

sourceTable names the layer source the title was minted from, and titleSource names the attribute branch that produced it. Both exist because label is free text that no allowlist bounds. The source table alone cannot answer the release question: a feature's properties are the layer table's columns plus its enrichment sidecars, so a parcel-sourced row with no parcel number falls through to a name or address column and the title is that value verbatim. Nor can the string's shape answer it — a name reading literally Parcel Ridge is indistinguishable from a parcel number. Only the producer knows which branch ran, so it says so. Absent means unknown on either field, and unknown is not released.

The receipt stamped onto a user turn's ModelRequest.metadata.

Once the turn is persisted this is the only record that a document was ever attached: the bytes are dehydrated out of the message before the row is written, and the frontend renders its attachment pill from this alone.