dataspring-cli 0.3.0__py3-none-any.whl

cli/contract.py

@@ -0,0 +1,1138 @@
+"""The dispatch contract: every ``params_model`` and action union, and nothing else.
+
+This is the ``dataspring_contract`` of decision D19
+(``docs/2026-09-17-one-registry-three-surfaces.md``): the pydantic models
+that describe what each registry operation takes. ``services/dispatch.py``
+imports them and pairs each with its handler; ``GET /api/dispatch``
+publishes their JSON schemas; the MCP tools are generated from them; and
+``cli/generated.py`` is generated from them, so the CLI validates a body
+against the same class the server will.
+
+It lives in ``cli/`` for the reason ``cli/skilltree.py`` does: the
+``dataspring-cli`` wheel ships exactly this package, and the server imports
+from it, so both ends read one definition. It imports pydantic and the
+standard library only. ``tests/test_cli_thin_client.py`` and
+``tests/test_cli_wheel_imports.py`` keep it that way.
+
+``extra="forbid"`` on the base is the contract every surface relies on: a
+field the server does not know is refused at the boundary instead of
+silently dropped. Field descriptions are the parameter docs every surface
+shows, verbatim; a model's docstring is its description.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DispatchParams(BaseModel):
+    """Base of every model on the dispatch boundary: each registry entry's
+    ``params_model`` and every member of the ``<domain>_edit`` action unions
+    (decision D19).
+
+    ``extra="forbid"`` is the contract every surface relies on: a field the
+    server does not know is refused at the boundary (HTTP 400, an MCP
+    validation error) instead of silently dropped, so a client can never
+    believe it sent something the handler never saw.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# ---------------------------------------------------------------------------
+# Dashboard action types
+# ---------------------------------------------------------------------------
+
+
+class CreateDashboardAction(DispatchParams):
+    """Create a new dashboard."""
+
+    action: Literal["create"]
+    title: str = Field(description="Dashboard title")
+    description: str | None = Field(default=None, description="Optional description")
+    visibility: Literal["private", "org"] = Field(
+        default="private",
+        description='"private" (only you) or "org" (shared with organization)',
+    )
+
+
+class UpdateDashboardAction(DispatchParams):
+    """Update an existing dashboard's metadata (title/description/visibility)."""
+
+    action: Literal["update"]
+    id: str = Field(description="Dashboard ID")
+    title: str | None = None
+    description: str | None = None
+    visibility: Literal["private", "org"] | None = None
+    expected_version: int | None = Field(
+        default=None,
+        description="Optimistic lock — if provided, update fails on mismatch. "
+        "Use the version from get_dashboard to prevent overwriting concurrent changes.",
+    )
+
+
+class DeleteDashboardAction(DispatchParams):
+    """Delete a dashboard. Cannot be undone."""
+
+    action: Literal["delete"]
+    id: str = Field(description="Dashboard ID")
+
+
+class DuplicateDashboardAction(DispatchParams):
+    """Duplicate a dashboard with all pages, sections, and widgets (new IDs)."""
+
+    action: Literal["duplicate"]
+    id: str = Field(description="Source dashboard ID")
+    new_title: str | None = Field(
+        default=None, description='Title for the copy (default: "Copy of {original}")'
+    )
+
+
+class ShareDashboardAction(DispatchParams):
+    """Toggle dashboard visibility between private and shared (org)."""
+
+    action: Literal["share"]
+    id: str = Field(description="Dashboard ID")
+    visibility: Literal["private", "org"]
+
+
+class SetDashboardControlsAction(DispatchParams):
+    """Update a dashboard's date-range, grain, and comparison controls."""
+
+    action: Literal["set_controls"]
+    id: str = Field(description="Dashboard ID")
+    date_range: dict | None = Field(
+        default=None,
+        description=(
+            'Date range config. Relative: {"mode": "relative", "preset": "last_30_days"}. '
+            'Absolute: {"mode": "absolute", "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD"}.'
+        ),
+    )
+    grain: Literal["day", "week", "month", "quarter", "year"] | None = None
+    comparison: Literal["none", "previous_period", "same_period_last_year"] | None = None
+
+
+DashboardAction = Annotated[
+    CreateDashboardAction
+    | UpdateDashboardAction
+    | DeleteDashboardAction
+    | DuplicateDashboardAction
+    | ShareDashboardAction
+    | SetDashboardControlsAction,
+    Field(discriminator="action"),
+]
+
+
+class DashboardEditParams(DispatchParams):
+    """The ``dashboard_edit`` call: one ``action`` from the family's union."""
+
+    action: DashboardAction
+
+
+# ---------------------------------------------------------------------------
+# Widget action types
+# ---------------------------------------------------------------------------
+
+
+class AddWidgetAction(DispatchParams):
+    """Add a widget to a dashboard section."""
+
+    action: Literal["add"]
+    dashboard_id: str
+    widget: dict = Field(
+        description=(
+            "Widget definition. Required: type (kpi|area_chart|bar_chart|line_chart|"
+            "table|donut|heatmap), title, query. Optional: format, width (1-10), "
+            "time_scope (range|latest|latest_complete), pivot (for table widgets)."
+        )
+    )
+    page_index: int = 0
+    section_index: int = 0
+    expected_version: int | None = None
+
+
+class UpdateWidgetAction(DispatchParams):
+    """Update a widget's fields (title, type, query, format, width, time_scope, pivot)."""
+
+    action: Literal["update"]
+    dashboard_id: str
+    page_index: int
+    section_index: int
+    widget_index: int
+    updates: dict = Field(description="Fields to patch — only provided keys are changed")
+    expected_version: int | None = None
+
+
+class RemoveWidgetAction(DispatchParams):
+    """Remove a widget from a dashboard section (irreversible)."""
+
+    action: Literal["remove"]
+    dashboard_id: str
+    page_index: int
+    section_index: int
+    widget_index: int
+    expected_version: int | None = None
+
+
+class ReorderWidgetsAction(DispatchParams):
+    """Reorder widgets within a section. All widget IDs in the section must be listed."""
+
+    action: Literal["reorder"]
+    dashboard_id: str
+    page_index: int
+    section_index: int
+    widget_ids: list[str] = Field(description="Full list of widget IDs in desired order")
+    expected_version: int | None = None
+
+
+class MoveWidgetAction(DispatchParams):
+    """Move a widget to a different page/section (keeps the same ID)."""
+
+    action: Literal["move"]
+    dashboard_id: str
+    widget_id: str
+    target_page_id: str
+    target_section_index: int
+    position: int | None = Field(
+        default=None, description="Position within target section (None = append)"
+    )
+
+
+class CopyWidgetAction(DispatchParams):
+    """Copy a widget with a new ID."""
+
+    action: Literal["copy"]
+    dashboard_id: str
+    widget_id: str
+    target_page_id: str
+    target_section_index: int
+    new_title: str | None = None
+
+
+class SwapWidgetsAction(DispatchParams):
+    """Swap the positions of two widgets (may be in different sections)."""
+
+    action: Literal["swap"]
+    dashboard_id: str
+    widget_id_1: str
+    widget_id_2: str
+
+
+WidgetAction = Annotated[
+    AddWidgetAction
+    | UpdateWidgetAction
+    | RemoveWidgetAction
+    | ReorderWidgetsAction
+    | MoveWidgetAction
+    | CopyWidgetAction
+    | SwapWidgetsAction,
+    Field(discriminator="action"),
+]
+
+
+class WidgetEditParams(DispatchParams):
+    """The ``widget_edit`` call: one ``action`` from the family's union."""
+
+    action: WidgetAction
+
+
+# ---------------------------------------------------------------------------
+# Page action types
+# ---------------------------------------------------------------------------
+
+
+class CreatePageAction(DispatchParams):
+    action: Literal["create"]
+    dashboard_id: str
+    title: str
+    position: int | None = Field(default=None, description="Insert position (None = append)")
+
+
+class DeletePageAction(DispatchParams):
+    action: Literal["delete"]
+    dashboard_id: str
+    page_id: str
+    cascade: bool = Field(default=False, description="Delete even if page has widgets")
+
+
+class RenamePageAction(DispatchParams):
+    action: Literal["rename"]
+    dashboard_id: str
+    page_id: str
+    title: str
+
+
+class ReorderPagesAction(DispatchParams):
+    action: Literal["reorder"]
+    dashboard_id: str
+    page_ids: list[str] = Field(description="Full list of page IDs in desired order")
+
+
+PageAction = Annotated[
+    CreatePageAction | DeletePageAction | RenamePageAction | ReorderPagesAction,
+    Field(discriminator="action"),
+]
+
+
+class PageEditParams(DispatchParams):
+    """The ``page_edit`` call: one ``action`` from the family's union."""
+
+    action: PageAction
+
+
+# ---------------------------------------------------------------------------
+# Section action types
+# ---------------------------------------------------------------------------
+
+
+class CreateSectionAction(DispatchParams):
+    action: Literal["create"]
+    dashboard_id: str
+    page_id: str
+    title: str | None = None
+    position: int | None = None
+
+
+class DeleteSectionAction(DispatchParams):
+    action: Literal["delete"]
+    dashboard_id: str
+    page_id: str
+    section_index: int
+    cascade: bool = False
+
+
+class RenameSectionAction(DispatchParams):
+    action: Literal["rename"]
+    dashboard_id: str
+    page_id: str
+    section_index: int
+    title: str | None = Field(description="New title (None to clear)")
+
+
+class MoveSectionAction(DispatchParams):
+    action: Literal["move"]
+    dashboard_id: str
+    source_page_id: str
+    section_index: int
+    target_page_id: str
+    target_position: int | None = None
+
+
+SectionAction = Annotated[
+    CreateSectionAction | DeleteSectionAction | RenameSectionAction | MoveSectionAction,
+    Field(discriminator="action"),
+]
+
+
+class SectionEditParams(DispatchParams):
+    """The ``section_edit`` call: one ``action`` from the family's union."""
+
+    action: SectionAction
+
+
+# ---------------------------------------------------------------------------
+# Semantic-model action types (admin/owner only)
+# ---------------------------------------------------------------------------
+
+
+_EXPECT_VERSION_DOC = (
+    "Managed tenants only: the datacore version (draft snapshot id) this edit "
+    "was written against, from the previous edit's `version` or "
+    "dataspring://datacore/files; refused with the current one when stale"
+)
+
+
+class CreateSemanticModelAction(DispatchParams):
+    action: Literal["create"]
+    model_data: dict = Field(
+        description="Full semantic-model definition (name, measures, dimensions, entities)"
+    )
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class UpdateSemanticModelAction(DispatchParams):
+    action: Literal["update"]
+    name: str
+    updates: dict
+    confirmed: bool = Field(
+        default=False,
+        description=(
+            "set true only after the user confirmed a redefinition of a "
+            "NATIVE entity whose impact you showed them; has no effect on "
+            "imported entities"
+        ),
+    )
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class DeleteSemanticModelAction(DispatchParams):
+    action: Literal["delete"]
+    name: str
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class PreviewSemanticModelAction(DispatchParams):
+    """Validate a semantic model without writing it or touching the warehouse."""
+
+    action: Literal["preview"]
+    model_data: dict = Field(
+        description="Full semantic-model definition to validate (name, "
+        "measures, dimensions, entities)"
+    )
+
+
+SemanticModelAction = Annotated[
+    CreateSemanticModelAction
+    | UpdateSemanticModelAction
+    | DeleteSemanticModelAction
+    | PreviewSemanticModelAction,
+    Field(discriminator="action"),
+]
+
+
+class SemanticModelEditParams(DispatchParams):
+    """The ``semantic_model_edit`` call: one ``action`` from the family's union."""
+
+    action: SemanticModelAction
+
+
+# ---------------------------------------------------------------------------
+# Metric action types (admin/owner only for writes, preview is open)
+# ---------------------------------------------------------------------------
+
+
+class CreateMetricAction(DispatchParams):
+    action: Literal["create"]
+    metric_data: dict = Field(description="Metric definition (name, type, type_params)")
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class UpdateMetricAction(DispatchParams):
+    action: Literal["update"]
+    name: str
+    updates: dict
+    confirmed: bool = Field(
+        default=False,
+        description=(
+            "set true only after the user confirmed a redefinition of a "
+            "NATIVE entity whose impact you showed them; has no effect on "
+            "imported entities"
+        ),
+    )
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class DeleteMetricAction(DispatchParams):
+    action: Literal["delete"]
+    name: str
+    expect_version: str | None = Field(default=None, description=_EXPECT_VERSION_DOC)
+
+
+class PreviewMetricAction(DispatchParams):
+    action: Literal["preview"]
+    metric_data: dict = Field(description="Metric definition to preview")
+    sample_query: dict | None = Field(
+        default=None,
+        description="Optional query params (start_date, end_date, grain, limit)",
+    )
+
+
+class ImpactMetricAction(DispatchParams):
+    """What applying ``updates`` to this metric would touch, without writing."""
+
+    action: Literal["impact"]
+    name: str
+    updates: dict = Field(description="The updates whose impact to assess")
+
+
+MetricAction = Annotated[
+    CreateMetricAction
+    | UpdateMetricAction
+    | DeleteMetricAction
+    | PreviewMetricAction
+    | ImpactMetricAction,
+    Field(discriminator="action"),
+]
+
+
+class MetricEditParams(DispatchParams):
+    """The ``metric_edit`` call: one ``action`` from the family's union."""
+
+    action: MetricAction
+
+
+# ---------------------------------------------------------------------------
+# Quick-metric action types
+# ---------------------------------------------------------------------------
+
+
+class CreateQuickMetricAction(DispatchParams):
+    action: Literal["create"]
+    name: str = Field(description='Metric name (e.g., "revenue_per_order")')
+    expression: str = Field(
+        description='Arithmetic expression over existing metrics (e.g., "total_revenue / order_count")'
+    )
+    description: str | None = None
+
+
+class UpdateQuickMetricAction(DispatchParams):
+    action: Literal["update"]
+    metric_id: str
+    name: str | None = None
+    expression: str | None = None
+    description: str | None = None
+
+
+class DeleteQuickMetricAction(DispatchParams):
+    action: Literal["delete"]
+    metric_id: str
+
+
+QuickMetricAction = Annotated[
+    CreateQuickMetricAction | UpdateQuickMetricAction | DeleteQuickMetricAction,
+    Field(discriminator="action"),
+]
+
+
+class QuickMetricEditParams(DispatchParams):
+    """The ``quick_metric_edit`` call: one ``action`` from the family's union."""
+
+    action: QuickMetricAction
+
+
+# ---------------------------------------------------------------------------
+# Scheduled-report action types
+# ---------------------------------------------------------------------------
+
+
+_Frequency = Literal["daily", "weekly", "monthly"]
+
+
+class CreateReportAction(DispatchParams):
+    action: Literal["create"]
+    name: str
+    frequency_type: _Frequency
+    time: str = Field(description="HH:MM in UTC, 24-hour")
+    recipients: list[str]
+    dashboard_id: str | None = Field(
+        default=None, description="For dashboard reports (PDF/PNG)"
+    )
+    metrics: list[str] | None = Field(
+        default=None, description="For query reports (CSV/JSON)"
+    )
+    dimensions: list[str] | None = None
+    format: str = Field(
+        default="pdf",
+        description='"pdf"|"png" for dashboards, "csv"|"json" for queries',
+    )
+    day_of_week: int | None = Field(default=None, description="0=Mon … 6=Sun (weekly)")
+    day_of_month: int | None = Field(default=None, description="1-28 (monthly)")
+
+
+class UpdateReportAction(DispatchParams):
+    action: Literal["update"]
+    schedule_id: str
+    name: str | None = None
+    enabled: bool | None = Field(
+        default=None, description="Set False to pause without deleting"
+    )
+    frequency_type: _Frequency | None = None
+    time: str | None = None
+    day_of_week: int | None = None
+    day_of_month: int | None = None
+    recipients: list[str] | None = None
+
+
+class DeleteReportAction(DispatchParams):
+    action: Literal["delete"]
+    schedule_id: str
+
+
+ReportAction = Annotated[
+    CreateReportAction | UpdateReportAction | DeleteReportAction,
+    Field(discriminator="action"),
+]
+
+
+class ReportEditParams(DispatchParams):
+    """The ``report_edit`` call: one ``action`` from the family's union."""
+
+    action: ReportAction
+
+
+# ---------------------------------------------------------------------------
+# business_context action types
+# ---------------------------------------------------------------------------
+
+
+class GetBusinessContextAction(DispatchParams):
+    """Read the current org business_context document."""
+
+    action: Literal["get"]
+
+
+class ShowSizeBusinessContextAction(DispatchParams):
+    """Report current size and remaining room within the 2000-byte UTF-8 cap."""
+
+    action: Literal["show_size"]
+
+
+class SetBusinessContextAction(DispatchParams):
+    """Replace the org's business_context with ``content`` (admin/owner)."""
+
+    action: Literal["set"]
+    content: str = Field(description="Full document content to save")
+
+
+class AppendBusinessContextAction(DispatchParams):
+    """Append ``content`` to the existing business_context (admin/owner).
+
+    Reads the current value, concatenates, and writes the combined text.
+    Useful for incremental edits where the agent doesn't already have
+    the prior content in scope.
+    """
+
+    action: Literal["append"]
+    content: str = Field(description="Text to append to the current document")
+
+
+BusinessContextAction = Annotated[
+    GetBusinessContextAction
+    | ShowSizeBusinessContextAction
+    | SetBusinessContextAction
+    | AppendBusinessContextAction,
+    Field(discriminator="action"),
+]
+
+
+class BusinessContextEditParams(DispatchParams):
+    """The ``business_context_edit`` call: one ``action`` from the family's union."""
+
+    action: BusinessContextAction
+
+
+# ---------------------------------------------------------------------------
+# Learned-trail action types
+# ---------------------------------------------------------------------------
+
+
+class ListLearnedAction(DispatchParams):
+    """List what DataSpring learned for this org (plus your personal entries)."""
+
+    action: Literal["list"]
+    limit: int = 20
+    include_reverted: bool = False
+
+
+class UndoLearnedAction(DispatchParams):
+    """Revert one learning (or, with no id, your most recent reversible one)."""
+
+    action: Literal["undo"]
+    learning_id: str | None = Field(
+        default=None,
+        description="Learning to revert; omit for your most recent reversible entry",
+    )
+
+
+LearnedAction = Annotated[
+    ListLearnedAction | UndoLearnedAction,
+    Field(discriminator="action"),
+]
+
+
+class LearnedEditParams(DispatchParams):
+    """The ``learned_edit`` call: one ``action`` from the family's union."""
+
+    action: LearnedAction
+
+
+# ---------------------------------------------------------------------------
+# Verified-query action types
+# ---------------------------------------------------------------------------
+
+
+class ListVerifiedQueriesAction(DispatchParams):
+    """The org's verified queries plus your own personal ones."""
+
+    action: Literal["list"]
+    limit: int = 20
+
+
+class RecordVerifiedQueryAction(DispatchParams):
+    """Record one confirmed (question, query) pair."""
+
+    action: Literal["record"]
+    question: str = Field(description="The user's question, verbatim")
+    params: dict = Field(
+        description=(
+            "The query that answers it, in the query_metrics wire shape: "
+            "metrics, dimensions, grain, start_date, end_date, where, "
+            "order_by, limit"
+        )
+    )
+    note: str | None = Field(
+        default=None,
+        description="One line on WHY this is the right query for that question",
+    )
+    scope: Literal["org", "user"] = Field(
+        default="user",
+        description=(
+            "'user' (the default) records it in this user's personal set; "
+            "'org' curates it for everyone and requires admin/owner"
+        ),
+    )
+
+
+class DeleteVerifiedQueryAction(DispatchParams):
+    """Remove one verified query by id."""
+
+    action: Literal["delete"]
+    id: str
+
+
+VerifiedQueryAction = Annotated[
+    ListVerifiedQueriesAction | RecordVerifiedQueryAction | DeleteVerifiedQueryAction,
+    Field(discriminator="action"),
+]
+
+
+class VerifiedQueryEditParams(DispatchParams):
+    """The ``verified_query_edit`` call: one ``action`` from the family's union."""
+
+    action: VerifiedQueryAction
+
+
+# ---------------------------------------------------------------------------
+# Warehouse action types (docs/2026-09-17-datacore-chunk2-plan.md)
+# ---------------------------------------------------------------------------
+
+
+class ActivateWarehouseAction(DispatchParams):
+    """Make one warehouse the org's default: every query that names no
+    ``warehouse`` runs against it."""
+
+    action: Literal["activate"]
+    id: str = Field(description="Warehouse id, e.g. 'managed' or 'external'")
+
+
+class AddExternalWarehouseAction(DispatchParams):
+    """Register a customer-owned BigQuery project as an external warehouse.
+
+    The customer's key is NOT an argument: it lives in Secret Manager in the
+    data project and is only named here (``key_secret``)."""
+
+    action: Literal["add_external"]
+    label: str = Field(description="Display name, e.g. \"Noon's BigQuery\"")
+    project: str = Field(description="The customer's GCP project id")
+    dataset: str = Field(description="The dataset the semantic manifest points at")
+    location: str = Field(description="BigQuery location of that dataset, e.g. 'europe-north2'")
+    key_secret: str = Field(
+        description=(
+            "NAME of the Secret Manager secret holding the customer's "
+            "service-account key (t-<org>-external-bigquery-key). Never the key itself."
+        )
+    )
+    id: str = Field(default="external", description="Warehouse id to create (default 'external')")
+
+
+class RemoveWarehouseAction(DispatchParams):
+    """Delete a warehouse and its manifest. Refused for the active warehouse
+    and for the managed one."""
+
+    action: Literal["remove"]
+    id: str = Field(description="Warehouse id to remove")
+
+
+WarehouseAction = Annotated[
+    ActivateWarehouseAction | AddExternalWarehouseAction | RemoveWarehouseAction,
+    Field(discriminator="action"),
+]
+
+
+class WarehouseEditParams(DispatchParams):
+    """The ``warehouse_edit`` call: one ``action`` from the family's union."""
+
+    action: WarehouseAction
+
+
+# ---------------------------------------------------------------------------
+# Datacore action types (chunk 3): the workspace files, and the loop
+# ---------------------------------------------------------------------------
+
+_DATACORE_VERSION_DOC = (
+    "The datacore version this edit was written against: the `version` the "
+    "previous edit returned, or dataspring://datacore/files. An edit against "
+    "a stale version is refused with the current one. Omit to skip the check."
+)
+
+
+_DATACORE_NAME_DOC = (
+    "For kind connection or pipeline: the name, i.e. the file name without .yaml "
+    "(connections/<name>.yaml, pipelines/<name>.yaml). For kind model: the path "
+    "under models/, the dbt project (models/models/marts/orders.sql, "
+    "models/models/staging/schema.yml, models/seeds/x.csv, models/dbt_project.yml); "
+    "no traversal, .sql .yml .yaml .csv .md .txt .json, never target/ or dbt_packages/"
+)
+
+
+DatacoreKind = Literal["connection", "pipeline", "model"]
+
+
+class ApplyDatacoreFileAction(DispatchParams):
+    """Write one workspace file whole (create or replace): a connection or
+    pipeline as a ``document`` (validated against its schema and the
+    catalog), a dbt project file as ``content``."""
+
+    action: Literal["apply"]
+    kind: DatacoreKind = Field(description="connection (admin), pipeline (admin) or model (member)")
+    name: str = Field(description=_DATACORE_NAME_DOC)
+    document: dict | None = Field(
+        default=None,
+        description=(
+            "kind connection: the whole document (connection.schema.json: kind, base_url, "
+            "auth with secret NAMES). kind pipeline: the whole document (pipeline.schema.json: "
+            "a catalog `connector` with config, secrets, overrides; or a `connection` reference, "
+            "an inline `source` or named `sources`, with `resources`; schedule, checks, then). "
+            "Secrets are named, never valued; every name must exist"
+        ),
+    )
+    content: str | None = Field(default=None, description="kind model: the whole file content")
+    expect_version: str | None = Field(default=None, description=_DATACORE_VERSION_DOC)
+
+
+class PatchDatacoreFileAction(DispatchParams):
+    """Apply a JSON merge patch (RFC 7386: a key set to null is removed) to an
+    existing YAML file: a connection, a pipeline (a schedule, a window, a
+    check), or a YAML file under models/ (not SQL)."""
+
+    action: Literal["patch"]
+    kind: DatacoreKind = Field(description="connection (admin), pipeline (admin) or model (member)")
+    name: str = Field(description=_DATACORE_NAME_DOC)
+    patch: dict = Field(description="JSON merge patch over the current document")
+    expect_version: str | None = Field(default=None, description=_DATACORE_VERSION_DOC)
+
+
+class DeleteDatacoreFileAction(DispatchParams):
+    """Remove one workspace file."""
+
+    action: Literal["delete"]
+    kind: DatacoreKind = Field(description="connection (admin), pipeline (admin) or model (member)")
+    name: str = Field(description=_DATACORE_NAME_DOC)
+    expect_version: str | None = Field(default=None, description=_DATACORE_VERSION_DOC)
+
+
+DatacoreAction = Annotated[
+    ApplyDatacoreFileAction | PatchDatacoreFileAction | DeleteDatacoreFileAction,
+    Field(discriminator="action"),
+]
+
+
+class DatacoreEditParams(DispatchParams):
+    """The ``datacore_edit`` call: one ``action`` from the family's union."""
+
+    action: DatacoreAction
+
+
+class CheckDatacoreAction(DispatchParams):
+    """Check the current draft; no arguments beyond an optional note."""
+
+    action: Literal["check"]
+    note: str | None = Field(default=None, description="Optional note, recorded on the check run")
+
+
+class DeployDatacoreAction(DispatchParams):
+    action: Literal["deploy"]
+    snapshot: str | None = Field(
+        default=None,
+        description=(
+            "Omit to promote the current draft (needs a green check bound to it). "
+            "A previously deployed snapshot id rolls back to it"
+        ),
+    )
+    note: str | None = Field(default=None, description="Why, recorded on the learned trail")
+
+
+class RunWindowParams(DispatchParams):
+    start: str = Field(description="First day, YYYY-MM-DD, inclusive")
+    end: str = Field(description="Last day, YYYY-MM-DD, inclusive")
+
+
+class RunCursorParams(DispatchParams):
+    start: Any = Field(
+        alias="from",
+        description="For a cursor-driven pipeline (Uniconta): re-pull from this cursor value",
+    )
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+
+class RunPipelineAction(DispatchParams):
+    action: Literal["run"]
+    pipeline: str = Field(description="Pipeline name (a deployed pipelines/<name>.yaml)")
+    window: RunWindowParams | None = Field(
+        default=None,
+        description="A date window to load instead of the pipeline's own; wider than backfill_chunk becomes a chunked backfill",
+    )
+    cursor: RunCursorParams | None = Field(default=None, description="{from: <value>}: a cursor to re-pull from")
+    backfill_chunk: str | None = Field(
+        default=None,
+        description="Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default)",
+    )
+
+
+class ResetPipelineAction(DispatchParams):
+    action: Literal["reset"]
+    pipeline: str = Field(description="The pipeline whose dlt state and raw tables to remove")
+    approve: bool = Field(
+        default=False,
+        description="Must be true: the reset is irreversible. Ask the user first",
+    )
+
+
+DatacoreRunAction = Annotated[
+    CheckDatacoreAction | DeployDatacoreAction | RunPipelineAction | ResetPipelineAction,
+    Field(discriminator="action"),
+]
+
+
+class DatacoreRunParams(DispatchParams):
+    """The ``datacore_run`` call: one ``action`` from the family's union."""
+
+    action: DatacoreRunAction
+
+
+class MCPQueryParams(DispatchParams):
+    """One metric query as every surface sends it: string dates, MetricFlow
+    ``where`` constraints, an optional warehouse. ``query_metrics`` and
+    ``explain_query`` both take it; ``services.queries.QueryParams`` is the
+    parsed form the query service runs.
+    """
+
+    metrics: list[str] = Field(description="List of metric names to query (e.g., ['total_revenue', 'order_count'])")
+    dimensions: list[str] | None = Field(default=None, description="Dimensions to group by. Use qualified names from dataspring://dimensions (e.g., ['customer__segment', 'order__region'])")
+    grain: str | None = Field(default=None, description="Time granularity: 'day', 'week', 'month', 'quarter', or 'year'")
+    start_date: str | None = Field(default=None, description="Start date in YYYY-MM-DD format")
+    end_date: str | None = Field(default=None, description="End date in YYYY-MM-DD format")
+    limit: int | None = Field(default=None, description="Maximum number of rows to return")
+    order_by: str | None = Field(default=None, description="Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc')")
+    where: list[str] | None = Field(
+        default=None,
+        description=(
+            "Row filters in MetricFlow's constraint syntax, one string each, "
+            "e.g. \"{{ Dimension('customer__segment') }} NOT IN ('Direct')\". "
+            "Use qualified names from dataspring://dimensions - an unresolvable "
+            "name comes back as an error whose suggestion names the qualified "
+            "form. `where` decides WHICH ROWS the numbers cover; `dimensions` "
+            "breaks the numbers OUT by a column; send both for a breakdown of "
+            "a filtered slice. A `where` on a dimension also overrides the "
+            "user's standing filter on that same dimension for this call."
+        ),
+    )
+    warehouse: str | None = Field(
+        default=None,
+        description=(
+            "Which of the org's warehouses to run against - an id from "
+            "dataspring://warehouses ('managed', 'external', ...). Omit for the "
+            "active one. During a migration ask both and compare."
+        ),
+    )
+
+
+class QueryMetricsParams(MCPQueryParams):
+    """``query_metrics``: the query, plus whether to suggest a chart for it
+    and the shape of the answer (rows, or a CSV document)."""
+
+    suggest_visualization: bool = Field(
+        default=False,
+        description="Also return a suggested visualization type for the result.",
+    )
+    format: Literal["json", "csv"] = Field(
+        default="json",
+        description=(
+            "'json' (default) answers rows in `data`; 'csv' answers the same "
+            "result as one CSV document in `content` (header row first) for a "
+            "file or a spreadsheet, with `columns` and `row_count` alongside."
+        ),
+    )
+
+
+class ExplainQueryParams(MCPQueryParams):
+    """``explain_query``: the same query ``query_metrics`` takes, compiled and
+    described instead of run."""
+
+
+class ExportDataParams(DispatchParams):
+    """``export_data``: a query to export, or a dashboard whose data to export."""
+
+    format: Literal["csv", "json"] = Field(default="csv", description="Output format: 'csv' or 'json'.")
+    metrics: list[str] | None = Field(default=None, description="Metric names to query (query export).")
+    dimensions: list[str] | None = Field(default=None, description="Dimensions to group by (query export).")
+    grain: str | None = Field(default=None, description="Time granularity: 'day', 'week', 'month', 'quarter' or 'year' (query export).")
+    start_date: str | None = Field(default=None, description="Start date, YYYY-MM-DD (query export).")
+    end_date: str | None = Field(default=None, description="End date, YYYY-MM-DD (query export).")
+    dashboard_id: str | None = Field(default=None, description="Dashboard id for a dashboard export; takes precedence over the query fields.")
+    output_path: str | None = Field(default=None, description="If given, save to this file path instead of returning the content.")
+    warehouse: str | None = Field(default=None, description="One of the org's warehouses (see dataspring://warehouses); omit for the active one (query export only).")
+
+
+class UpdateContextParams(DispatchParams):
+    """``update_context``: the preference fields to merge in."""
+
+    updates: dict[str, Any] = Field(
+        description=(
+            "Fields to update; only these change. Presentation: default_currency, "
+            "default_grain, decimal_places, preferred_chart_type. Lists and maps "
+            "REPLACE what is stored: favorite_metrics, standing_filters "
+            "([{dimension, operator: in|not_in|eq|neq, values}]), "
+            "metric_substitutions ({asked: preferred}), default_segment "
+            "({dimension, value} or null)."
+        ),
+    )
+
+
+class ImportManifestParams(DispatchParams):
+    """``import_manifest``: a semantic manifest and the warehouse it belongs to."""
+
+    manifest_data: dict[str, Any] = Field(
+        description="The semantic manifest to import (semantic models, metrics), as a JSON object."
+    )
+    warehouse: str | None = Field(
+        default=None,
+        description="Which of the org's warehouses the manifest belongs to (see dataspring://warehouses); omit for the active one.",
+    )
+
+
+class RenderDashboardParams(DispatchParams):
+    """``render_dashboard``: which dashboard, in which mode."""
+
+    dashboard_id: str = Field(description="ID of the dashboard to render.")
+    format: Literal["pdf", "png", "app"] = Field(
+        default="app",
+        description="'app' for an interactive iframe payload (default), 'pdf' or 'png' for a static export.",
+    )
+    page_id: str | None = Field(default=None, description="(pdf/png only) One page to render; default: all pages.")
+    width: int = Field(default=1200, description="(pdf/png only) Viewport width in pixels.")
+    height: int = Field(default=800, description="(pdf/png only) Viewport height in pixels.")
+    output_path: str | None = Field(default=None, description="(pdf/png only) Save to this file path instead of returning base64.")
+    warehouse: str | None = Field(
+        default=None,
+        description="One of the org's warehouses (see dataspring://warehouses) the widgets query; omit for the active one.",
+    )
+
+
+class RenderWidgetParams(DispatchParams):
+    """``render_widget``: which widget of which dashboard, in which mode."""
+
+    dashboard_id: str = Field(description="ID of the dashboard containing the widget.")
+    widget_id: str = Field(description="ID of the widget to render.")
+    format: Literal["png", "app"] = Field(
+        default="app",
+        description="'app' for an interactive iframe payload (default), 'png' for a static snapshot.",
+    )
+    width: int = Field(default=600, description="(png only) Viewport width in pixels.")
+    height: int = Field(default=400, description="(png only) Viewport height in pixels.")
+    output_path: str | None = Field(default=None, description="(png only) Save to this file path instead of returning base64.")
+    warehouse: str | None = Field(
+        default=None,
+        description="One of the org's warehouses (see dataspring://warehouses) the widget queries; omit for the active one.",
+    )
+
+
+class SwitchOrganizationParams(DispatchParams):
+    """``switch_organization``: the org to switch to."""
+
+    org_id: str = Field(description="The organization ID to switch to (see read(kind=\"organizations\")).")
+
+
+class SubmitErrorReportParams(DispatchParams):
+    """``submit_error_report``: what failed, and what was expected."""
+
+    command: str = Field(description="The tool, resource, or action that failed (e.g. 'query_metrics', 'dataspring://dashboards', 'dashboard_edit').")
+    error_message: str = Field(description="The exact error message received.")
+    expected: str | None = Field(default=None, description="What you expected to happen.")
+    context_info: str | None = Field(default=None, description="What you were trying to achieve.")
+    source: str = Field(default="mcp", description="Which surface sent the report: 'mcp', 'cli' or 'api'.")
+
+
+# ---------------------------------------------------------------------------
+# secret_edit: secrets in both directions (D17 and its 2026-09-18 amendment)
+# ---------------------------------------------------------------------------
+
+
+class SetSecretAction(DispatchParams):
+    """Get a one-time link where a PERSON pastes a credential. The value
+    never comes through here; the same name rotates a credential."""
+
+    action: Literal["set"]
+    name: str = Field(
+        description=(
+            "The secret to set or rotate: t-<org>-<connection>-<field> for your "
+            "organization, lower-case (t-acme-kanpla-api_key, "
+            "t-acme-external-bigquery-key). A connection file names it."
+        )
+    )
+
+
+class RevealSecretAction(DispatchParams):
+    """Get a one-time link that shows a credential DataSpring ISSUED to this
+    organization (the Airbyte destination key today), once."""
+
+    action: Literal["reveal"]
+    name: str | None = Field(
+        default=None,
+        description=(
+            "The issued credential, by secret name. Omit for the Airbyte "
+            "destination key (t-<org>-airbyte-key). Only issued credentials can "
+            "be revealed, never ones you gave DataSpring."
+        ),
+    )
+
+
+SecretAction = Annotated[
+    SetSecretAction | RevealSecretAction,
+    Field(discriminator="action"),
+]
+
+
+class SecretEditParams(DispatchParams):
+    """The ``secret_edit`` call: one ``action`` from the family's union."""
+
+    action: SecretAction
+
+
+#: Rows one ``run_sql`` call may return, and the ceiling ``max_rows`` may ask for.
+RUN_SQL_DEFAULT_ROWS = 1000
+RUN_SQL_MAX_ROWS = 10_000
+
+
+class RunSqlParams(DispatchParams):
+    """``run_sql``: one statement and how much of its result to return."""
+
+    sql: str = Field(
+        description=(
+            "One SQL statement (BigQuery Standard SQL on a managed warehouse). "
+            "Name tables as <org>_marts.<table>, <org>_core.<table> or "
+            "<org>_staging.<table>; the identity it runs as can read those and "
+            "nothing else, so a write or a reach outside them is refused by "
+            "the warehouse."
+        )
+    )
+    warehouse: str | None = Field(
+        default=None,
+        description="One of the org's warehouses (see dataspring://warehouses); omit for the active one.",
+    )
+    max_rows: int = Field(
+        default=RUN_SQL_DEFAULT_ROWS,
+        ge=1,
+        le=RUN_SQL_MAX_ROWS,
+        description=f"Rows to return at most (default {RUN_SQL_DEFAULT_ROWS}, cap {RUN_SQL_MAX_ROWS}). Aggregate in SQL rather than paging.",
+    )
+    format: Literal["json", "csv", "markdown"] = Field(
+        default="json",
+        description="'json' answers rows in `data`; 'csv' or 'markdown' answer one document in `content`.",
+    )
+    dry_run: bool = Field(
+        default=False,
+        description="Only estimate the bytes the statement would process (and check it parses); run nothing.",
+    )