mainsequence 3.19.2__tar.gz → 3.19.5__tar.gz

{mainsequence-3.19.2 → mainsequence-3.19.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 3.19.2
+Version: 3.19.5
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement
@@ -89,7 +89,7 @@ Requires-Dist: playwright; extra == "workspace-snapshots"
 Dynamic: license-file
 
 <p align="center">
-  <img src="https://main-sequence.app/static/media/logos/MS_logo_long_black.png" alt="Main Sequence Logo" width="500"/>
+  <img src="https://www.main-sequence.io/images/logos/MS_logo_long_black.png" alt="Main Sequence Logo" width="500"/>
 </p>
 
 # Main Sequence Python SDK
@@ -154,6 +154,7 @@ Recommended entry points:
   - [Working With Simple Tables](docs/tutorial/working_with_simple_tables.md)
   - [Create Your First API](docs/tutorial/create_your_first_api.md)
   - [Role-Based Access Control](docs/tutorial/role_based_access_control.md)
+  - [Turn Your Project Into an Agent](docs/tutorial/project_to_agent.md)
 - Knowledge:
   - [Data Nodes](docs/knowledge/data_nodes.md)
   - [Command Center](docs/knowledge/command_center/index.md)
@@ -209,6 +210,7 @@ From there, the normal learning path is:
 4. understand sharing and RBAC
 5. schedule jobs
 6. build dashboards or downstream consumers
+7. package the project as an agent-facing surface when the repository is ready
 
 ## Installation for development
 

{mainsequence-3.19.2 → mainsequence-3.19.5}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://main-sequence.app/static/media/logos/MS_logo_long_black.png" alt="Main Sequence Logo" width="500"/>
+  <img src="https://www.main-sequence.io/images/logos/MS_logo_long_black.png" alt="Main Sequence Logo" width="500"/>
 </p>
 
 # Main Sequence Python SDK
@@ -64,6 +64,7 @@ Recommended entry points:
   - [Working With Simple Tables](docs/tutorial/working_with_simple_tables.md)
   - [Create Your First API](docs/tutorial/create_your_first_api.md)
   - [Role-Based Access Control](docs/tutorial/role_based_access_control.md)
+  - [Turn Your Project Into an Agent](docs/tutorial/project_to_agent.md)
 - Knowledge:
   - [Data Nodes](docs/knowledge/data_nodes.md)
   - [Command Center](docs/knowledge/command_center/index.md)
@@ -119,6 +120,7 @@ From there, the normal learning path is:
 4. understand sharing and RBAC
 5. schedule jobs
 6. build dashboards or downstream consumers
+7. package the project as an agent-facing surface when the repository is ready
 
 ## Installation for development
 

{mainsequence-3.19.2 → mainsequence-3.19.5}/agent_scaffold/AGENTS.md

@@ -18,9 +18,9 @@ uses them to update only the Main Sequence section below.
 ## Main Sequence Instructions
 
 Before any non-trivial Main Sequence work, verify that this Main Sequence section matches the
-latest installed `agent_scaffold/AGENTS.md` template and that
+latest installed `AGENTS.md` template and that
 `.agents/skills/mainsequence/project_builder/SKILL.md` matches the latest installed
-`agent_scaffold/skills/project_builder/SKILL.md`; if either local file does not match, update it
+`.agents/skills/project_builder/SKILL.md`; if either local file does not match, update it
 before proceeding.
 
 Canonical Main Sequence documentation root:

{mainsequence-3.19.2 → mainsequence-3.19.5}/agent_scaffold/skills/command_center/workspace_builder/SKILL.md

@@ -69,25 +69,32 @@ This skill must not claim ownership of:
 
 0. If widget selection, layout narrative, or visualization strategy is not already decided, use:
    - `.agents/skills/mainsequence/command_center/workspace_design/SKILL.md`
-1. Verify the widget catalog through the CLI:
+1. If the workspace may use connection-backed source widgets, inspect the available connections through the CLI first:
+   - `mainsequence cc connection list --json`
+   - identify the target connection instance `uid`
+   - `mainsequence cc connection detail <CONNECTION_UID> --json`
+   - `mainsequence cc connection_type list --json`
+   - identify the target connection `type_id`
+   - `mainsequence cc connection_type detail <TYPE_ID> --json`
+2. Verify the widget catalog through the CLI:
    - `mainsequence cc registered_widget_type list --json`
    - identify the target `widget_id`
    - `mainsequence cc registered_widget_type detail <WIDGET_ID> --json`
-2. The SDK client models in `mainsequence/client/command_center/`:
+3. The SDK client models in `mainsequence/client/command_center/`:
    - `workspace.py`
    - `connections.py` when source widgets depend on backend-owned connections
    - `data_models.py`
    - `app_component.py` when the workspace contains AppComponent widgets or editable form payloads
-3. `docs/knowledge/command_center/workspaces.md`
-4. the local Main Sequence docs/models/examples in this repository that define the widget payloads being mounted
-5. the current CLI docs if the task uses CLI workflow
+4. `docs/knowledge/command_center/workspaces.md`
+5. the local Main Sequence docs/models/examples in this repository that define the widget payloads being mounted
+6. the current CLI docs if the task uses CLI workflow
 
 If the workspace contains AppComponent widgets, also read:
 
-6. `docs/knowledge/command_center/forms.md`
-7. `docs/knowledge/command_center/widget_data_contracts.md`
-8. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md` when mounted widgets depend on project APIs that must be usable from Command Center
-9. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md` when the workspace should validate an AppComponent/API contract in `mock-json` mode before deployment
+7. `docs/knowledge/command_center/forms.md`
+8. `docs/knowledge/command_center/widget_data_contracts.md`
+9. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md` when mounted widgets depend on project APIs that must be usable from Command Center
+10. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md` when the workspace should validate an AppComponent/API contract in `mock-json` mode before deployment
 
 ## Command Center Mental Model
 
@@ -104,6 +111,92 @@ Think in terms of these objects:
 - saved widget or saved group:
   import-layer snapshot/template, not a live linked widget instance inside the workspace
 
+## Workspace JSON Model
+
+Workspace JSON is the durable workspace definition. It is not a raw frontend state dump and it is
+not a loaded runtime snapshot.
+
+Portable export artifacts may use a wrapper:
+
+```json
+{
+  "schema": "mainsequence.workspace",
+  "version": 1,
+  "exportedAt": "2026-05-07T00:00:00.000Z",
+  "workspace": {
+    "id": "workspace-example",
+    "title": "Example Workspace",
+    "description": "User-scoped workspace managed in Command Center.",
+    "type": "workspace",
+    "labels": [],
+    "category": "Custom",
+    "source": "user",
+    "layoutKind": "custom",
+    "grid": { "columns": 48, "rowHeight": 15, "gap": 8 },
+    "controls": {
+      "enabled": true,
+      "timeRange": {
+        "enabled": true,
+        "defaultRange": "24h",
+        "options": ["15m", "1h", "6h", "24h", "7d", "30d", "90d"]
+      },
+      "refresh": {
+        "enabled": true,
+        "defaultIntervalMs": 300000,
+        "intervals": [null, 30000, 60000, 300000, 600000, 3600000]
+      },
+      "actions": { "enabled": true, "share": false, "view": true }
+    },
+    "widgets": []
+  }
+}
+```
+
+Use the wrapper for portable artifacts. For direct workspace update commands, pass the writable
+workspace payload shape expected by that command, not an arbitrary wrapper, unless the command
+explicitly documents wrapper support.
+
+Durable workspace JSON owns:
+
+- workspace metadata, labels, category, source, layout kind, grid, and shared controls
+- mounted widget instances and ordering
+- widget `props`, `layout`, `position`, `bindings`, `managedBy`, `presentation`, and `row.children`
+- connection/query configuration on source widgets when the source widget contract requires it
+
+Durable workspace JSON does not own:
+
+- current user-selected control values when the platform separates user state
+- runtime/view state when the platform separates user state
+- credentials, provider URLs, native socket details, or backend route fragments
+- compiled or public runtime metadata generated by the platform
+
+## Widget Instance Shape
+
+Each mounted widget instance should resolve to this shape:
+
+```json
+{
+  "id": "unique-instance-id",
+  "widgetId": "registered-widget-type-id",
+  "title": "Optional title",
+  "props": {},
+  "bindings": {},
+  "layout": { "cols": 12, "rows": 8 },
+  "position": { "x": 0, "y": 0 }
+}
+```
+
+Important fields:
+
+- `id`: unique mounted instance id inside the workspace
+- `widgetId`: registered widget type id, not a saved-widget id and not a mounted instance id
+- `props`: durable widget configuration
+- `runtimeState`: optional current runtime/view state, not durable source configuration
+- `bindings`: target-owned graph edges from this widget's input ports to upstream output ports
+- `managedBy`: marks hidden managed source widgets
+- `presentation`: placement, rail visibility, chrome, and exposed field behavior
+- `row.children`: nested widgets inside a row/container widget
+
 ## Inputs This Skill Needs
 
 Before writing or mutating a workspace, collect or infer:
@@ -286,27 +379,133 @@ If the payload shape is not defined by those sources and cannot be verified, sto
 
 ### 3.1 Resolve connection-backed data before mounting consumers
 
-Before mounting table, chart, statistic, curve, or similar data consumers:
+Connections are backend-owned data resources. Workspace consumers should not store connection
+details directly unless their registered widget contract explicitly supports embedded managed source
+props.
 
-1. identify the source Connection Query widget
-2. verify the selected connection instance exists and is usable
-3. verify the connection type and `queryModelId`
-4. verify the typed query payload
-5. verify the published output contract
-6. add a Tabular Transform widget if analytical reshaping is required
-7. bind consumers to the source or transform `dataset` output
+Prefer explicit source widgets:
 
-Do not store endpoint URLs, credentials, backend route fragments, provider ids, or mutable
-connection display labels as authoritative widget props.
+- `connection-query` for request/response datasets
+- `connection-stream-query` for streaming or incremental paths
+- `tabular-transform` when analytical reshaping is needed before presentation
 
-Generic tabular consumers must receive `core.tabular_frame@v1`. If the upstream API or connection
-returns raw arrays, paginated JSON, nested provider payloads, or other ad hoc records, normalize
-through an Adapter from API connection first, then use an explicit transform when analytical
-reshaping is still required.
+One source widget can feed several consumers. Reuse one source when the same query drives several
+tables, charts, statistics, curves, or agent contexts.
 
-When a project API or AppComponent legitimately returns a full canonical frame, ground the contract
-against `mainsequence.client.command_center.data_models.TabularFrameResponse`. Source-specific
-runtime details belong in `source.context`, not top-level widget payload fields.
+Before mounting table, chart, statistic, curve, or similar data consumers:
+
+1. identify the source widget
+2. verify the selected connection instance exists and is usable
+3. verify `connectionRef.id` is real and backend-owned
+4. verify `connectionRef.typeId` matches the connection type
+5. verify `queryModelId` matches `query.kind`
+6. verify the typed query payload matches the selected connection type and query model
+7. verify the published output contract
+8. add a Tabular Transform widget if analytical reshaping is required
+9. bind consumers to the source or transform output through target-owned `bindings`
+
+Do not store credentials, provider URLs, native route fragments, backend route fragments, provider
+ids, or mutable connection display labels as authoritative widget props.
+
+Request/response source props:
+
+```json
+{
+  "connectionRef": { "id": 123, "typeId": "mainsequence.simple-table" },
+  "queryModelId": "simple-table-sql",
+  "query": {
+    "kind": "simple-table-sql",
+    "sql": "select * from {{simple_table}} limit 500"
+  },
+  "timeRangeMode": "dashboard",
+  "variables": {},
+  "maxRows": 500
+}
+```
+
+Incremental request/response props:
+
+```json
+{
+  "incrementalRefreshMode": "incremental",
+  "incrementalTimeField": "timestamp",
+  "incrementalMergeKeyFields": ["symbol", "timestamp"],
+  "incrementalOverlapMs": 60000,
+  "incrementalRetentionMs": 86400000,
+  "incrementalDedupePolicy": "latest"
+}
+```
+
+Stream source props:
+
+```json
+{
+  "connectionRef": { "id": 123, "typeId": "binance.market-data" },
+  "queryModelId": "ticker-stream",
+  "query": {
+    "kind": "ticker-stream",
+    "symbols": ["BTCUSDT", "ETHUSDT"]
+  },
+  "timeRangeMode": "none",
+  "mergeKeyFields": ["symbol"],
+  "retentionMaxRows": 1000
+}
+```
+
+Connection source rules:
+
+- use stream widgets only when the query model advertises stream support
+- configure retention and merge keys explicitly when the consumer expects bounded live state
+- incremental refresh requires a time-range-aware query model and stable time and identity columns
+- `incrementalTimeField` must exist in the returned frame
+- `incrementalMergeKeyFields` must identify stable rows
+- generic tabular consumers must receive `core.tabular_frame@v1`
+- if the upstream connection returns raw arrays, paginated JSON, nested provider payloads, or other
+  ad hoc records, normalize through an Adapter from API connection first, then use an explicit
+  transform when analytical reshaping is still required
+- when a project API or AppComponent legitimately returns a full canonical frame, ground the
+  contract against `mainsequence.client.command_center.data_models.TabularFrameResponse`
+- source-specific runtime details belong in `source.context`, not top-level widget payload fields
+
+### 3.2 Historical and incremental lanes
+
+Modern tabular consumers use explicit role inputs:
+
+- `seedData`: retained baseline or historical dataset
+- `liveUpdates`: incremental publication lane
+
+Source outputs:
+
+- `connection-query.dataset`: retained `core.tabular_frame@v1` frame for historical consumers
+- `connection-query.updates`: incremental output when incremental refresh is active
+- `connection-stream-query.dataset`: retained compatibility frame
+- `connection-stream-query.updates`: seed/update publication stream
+
+Canonical binding shape:
+
+```json
+"bindings": {
+  "seedData": {
+    "sourceWidgetId": "historical-source",
+    "sourceOutputId": "dataset"
+  },
+  "liveUpdates": {
+    "sourceWidgetId": "stream-source",
+    "sourceOutputId": "updates"
+  }
+}
+```
+
+Rules:
+
+- historical/request-response data uses `dataset -> seedData`
+- live or incremental data uses `updates -> liveUpdates`
+- `sourceData` is legacy or compatibility input; use it only when the widget contract requires it
+- do not send stream `dataset` to `liveUpdates`
+- do not send request/response `dataset` to `liveUpdates`
+- generic tabular consumers must receive `core.tabular_frame@v1`
+- raw arrays, paginated JSON, or nested provider payloads must be normalized before reaching generic
+  consumers
 
 ### 4. Shared workspace state and current-user state are different
 
@@ -389,26 +588,51 @@ Prefer:
 Bindings are canonical instance-level graph edges. They live on the target widget instance in
 `bindings`, not in `props`, and not in widget-type metadata.
 
-One binding is always defined as:
+One binding is always:
 
-- target widget instance + target input id
-- source widget instance + source output id
-- optional ordered transform steps
+```text
+source widget output port -> target widget input port
+```
 
 Persisted shape:
 
 - `bindings[inputId] = WidgetPortBinding`
 - `bindings[inputId] = WidgetPortBinding[]` when the target input declares `cardinality: "many"`
 
-A `WidgetPortBinding` minimally contains:
+Minimal `WidgetPortBinding`:
 
-- `sourceWidgetId`
-- `sourceOutputId`
-- optional `transformSteps`
+```json
+{
+  "sourceWidgetId": "prices-source",
+  "sourceOutputId": "dataset"
+}
+```
 
-Treat `transformSteps` as canonical. Legacy `transformId`, `transformPath`, and
+Binding with transform steps:
+
+```json
+{
+  "sourceWidgetId": "source-widget",
+  "sourceOutputId": "agent-context",
+  "transformSteps": [
+    { "id": "extract-path", "path": ["summary"], "contractId": "core.value.string@v1" }
+  ]
+}
+```
+
+Treat ordered `transformSteps` as canonical. Legacy `transformId`, `transformPath`, and
 `transformContractId` may still appear only as backward-compatible mirrors for older persisted
-workspaces.
+workspaces. Do not author those legacy fields in new workspace JSON.
+
+Supported lightweight transform steps:
+
+- `select-array-item`
+- `extract-path`
+
+Binding transforms are only for selecting one array item or extracting a nested field before
+compatibility is evaluated. Do not use binding transforms for analytical reshaping. Use a
+`tabular-transform` widget for projection, aggregate, pivot, unpivot, filtering, joining, or other
+visible data operations.
 
 Do not describe bindings loosely as “widget A uses widget B”. In this platform, bindings are always
 port-to-port:
@@ -424,17 +648,16 @@ Resolve bindings from the target widget outward:
 2. For each target input, record:
    - `inputId`
    - accepted contracts
+   - `acceptedOutputIds`
    - `required`
    - `cardinality`
    - `effects`
 3. Choose a source widget instance that actually publishes the required output id.
-4. If the source output is structured JSON or an array, resolve binding transforms before contract
+4. Validate the source output id against `acceptedOutputIds` when the target input declares it.
+5. If the source output is structured JSON or an array, resolve binding transforms before contract
    validation.
-   - supported transform steps:
-     - `select-array-item`
-     - `extract-path`
-5. Validate the transformed contract against the target input `accepts`.
-6. Treat the binding as usable only when the resolved status is `valid`.
+6. Validate the transformed contract against the target input `accepts`.
+7. Treat the binding as usable only when the resolved status is `valid`.
 
 A binding can exist in workspace JSON and still be unusable at runtime. The runtime may resolve a
 binding as:
@@ -461,6 +684,10 @@ Runtime and persistence rules:
 - binding changes clear that target widget's `runtimeState`
 - the widget settings `Bindings` tab and the workspace graph editor edit the same canonical binding model
 - for `cardinality: "many"` inputs, preserve order and store an array of bindings for that input id
+- for `cardinality: "one"` inputs, store a single binding object, not an array
+- do not bind a widget to itself
+- graph/editor interactions may be dragged in either visual direction, but persisted JSON is always
+  normalized back to target-owned bindings
 
 Dynamic-IO rule:
 
@@ -471,6 +698,10 @@ Dynamic-IO rule:
 Concrete examples:
 
 - a Connection Query widget publishes `dataset`; a Tabular Transform widget can consume and republish `dataset`
+- modern tabular consumers use explicit role inputs:
+  - historical/request-response data binds `dataset -> seedData`
+  - live or incremental data binds `updates -> liveUpdates`
+  - legacy `sourceData` should appear only when the widget contract still requires it
 - `main-sequence-ai-agent-terminal` accepts one input with `cardinality: "many"`, so several
   upstream widget contexts can feed one terminal
 - widgets that implement `buildAgentSnapshot(...)` may also publish a synthetic `agent-context`
@@ -483,16 +714,85 @@ Review rule:
   - target input id
   - source widget instance id
   - source output id
+  - accepted output id constraint, if any
   - transform steps, if any
   - final resolved contract
   - final resolved status
 
+## Managed Connection Sources
+
+Some consumers support embedded connection authoring. Treat this as UI convenience, not a shortcut
+around the source-widget model.
+
+The persisted model still has:
+
+- a visible owner widget, for example `graph`
+- a hidden source widget, either `connection-query` or `connection-stream-query`
+- `managedBy: { "ownerInstanceId": "<owner-id>", "role": "embedded-connection-source" }` on the hidden source widget
+- a normal binding from the owner input to the hidden source output
+
+Owner widget:
+
+```json
+{
+  "id": "graph-1",
+  "widgetId": "graph",
+  "props": {
+    "graphSourceMode": "connection",
+    "embeddedConnectionQuery": {
+      "connectionRef": { "id": 123, "typeId": "mainsequence.simple-table" },
+      "queryModelId": "simple-table-sql",
+      "query": { "kind": "simple-table-sql", "sql": "select * from {{simple_table}}" }
+    }
+  },
+  "bindings": {
+    "seedData": {
+      "sourceWidgetId": "graph-1-source",
+      "sourceOutputId": "dataset"
+    }
+  }
+}
+```
+
+Hidden source widget:
+
+```json
+{
+  "id": "graph-1-source",
+  "widgetId": "connection-query",
+  "title": "Graph Source",
+  "props": {
+    "connectionRef": { "id": 123, "typeId": "mainsequence.simple-table" },
+    "queryModelId": "simple-table-sql",
+    "query": { "kind": "simple-table-sql", "sql": "select * from {{simple_table}}" }
+  },
+  "managedBy": {
+    "ownerInstanceId": "graph-1",
+    "role": "embedded-connection-source"
+  },
+  "presentation": {
+    "placementMode": "sidebar",
+    "railVisibility": "hidden"
+  }
+}
+```
+
+Managed stream sources bind hidden source `updates` to owner `liveUpdates`.
+
+Rules:
+
+- keep owner props, hidden source props, `managedBy`, and bindings aligned
+- do not leave orphan hidden source widgets
+- do not point `managedBy.ownerInstanceId` at a missing owner
+- prefer explicit visible source widgets when they make the workspace easier to inspect or reuse
+
 
 ## Review Rules
 
 When reviewing a workspace task, look for:
 
 - guessed widget payloads
+- guessed input ids or output ids
 - widget work that skipped CLI registry verification
 - widget work that skipped SDK client model review when one exists
 - unknown or unverified `widgetId` values
@@ -500,12 +800,21 @@ When reviewing a workspace task, look for:
 - workspace mutation attempted without first exporting the current workspace JSON
 - widget payloads changed without saving versioned JSON drafts under `workspaces/widgets/`
 - workspace-wide rewrites for one-widget changes
-- shared state mixed incorrectly with current-user runtime state
+- current-user runtime state mixed into durable workspace JSON accidentally
 - runtime ownership violations such as consumer widgets inventing canonical fetch paths
 - unresolved external resource ids
-- connection-backed consumers missing a source or transform `dataset` binding
+- connection-backed consumers missing a source widget or required transform widget
 - generic tabular consumers bound to raw JSON instead of `core.tabular_frame@v1`
 - full canonical tabular payloads that drift from `TabularFrameResponse`
+- bindings authored in `props` instead of `widget.bindings`
+- bindings placed on the source widget instead of the target widget
+- bindings that ignore `acceptedOutputIds`
+- `dataset -> liveUpdates`
+- stream `dataset` used for live data instead of stream `updates`
+- stream or incremental outputs wired to the wrong role input
+- binding transforms used for analytical reshaping instead of a transform widget
+- hidden managed source widgets missing their owner widget
+- stale `managedBy.ownerInstanceId` values
 - widget trees using structures not supported by the Main Sequence repository source models
 
 ## Validation Checklist
@@ -523,13 +832,25 @@ Do not claim success until you have checked:
 - versioned workspace/widget JSON files were preserved pending user acceptance
 - widget detail was reviewed for `widgetVersion`, configuration, runtime, IO, capabilities, agent hints, and examples
 - the relevant SDK client model was reviewed when one exists
-- connection-backed source widgets have verified connection instance, connection type, query model, typed query payload, and output contract
+- every source widget has a valid connection ref, query model id, typed query payload, and output contract
+- every `query.kind` matches `queryModelId`
 - generic tabular consumers receive `core.tabular_frame@v1`
+- every binding references an existing source widget and output id
+- every binding targets an existing input id
+- every binding matches the target input contract
+- every binding respects `acceptedOutputIds` when declared
+- `cardinality: "many"` bindings preserve order as arrays
+- `cardinality: "one"` bindings are single binding objects
+- historical/request-response data uses `dataset -> seedData` when the widget exposes role inputs
+- live or incremental data uses `updates -> liveUpdates` when the widget exposes role inputs
 - full canonical tabular frames match `TabularFrameResponse`
 - widget ids and widget instance ids are correct
 - any mounted widget that depends on a project API points to a FastAPI project resource that already exists
 - any mounted widget that depends on a project API points to a FastAPI `ResourceRelease` that already exists
 - local payload shape was reconciled against the verified widget id, widget-detail contract, and SDK model
+- managed sources have valid `managedBy.ownerInstanceId` values
+- owner widgets and hidden managed source widgets agree on connection/query props
+- no credentials, native URLs, or backend route fragments are embedded in workspace JSON
 - the chosen mutation mode is correct:
   - full workspace update
   - widget-scoped mutation