This release is a pre-release and may not be stable for production use.
MOI Product Python SDK
Python SDK for UI-visible MOI product APIs.
The existing MemoryService / ConsumerMemoryHandle target the legacy Consumer Memory/Profile API. Current MOI does not expose those routes; these entries are not a current capability. See Legacy API availability.
Typed product result objects are generated from ../proto/product/*.proto.
Runner and sandbox services are available through client.runners(workspace_id)
and client.sandboxes(workspace_id). SandboxEgressEndpoint, SandboxQuotaStatus
and SandboxQuota are exported from moi_product_sdk alongside the existing
request/result types. Quota request fields preserve explicit zero versus omission.
See Runner and sandbox HTTP alignment.
Error.details preserves nested dictionaries, lists and scalar JSON values,
including exact integer IDs. Owner code/message, HTTP status, transport request
ID and repair data remain available. See Structured error details.
File imports may omit name and volume_id; MOI supplies an absent name. ImportTaskCreateSpec and FileImportTaskSpec accept an optional task_id, which is sent unchanged. ImportTaskUpdateSpec edits the name, load mode, file filter and URIs; choose the target volume at creation. Export tasks require a name and accept the optional creator label.
KnowledgeService.create_with_sources accepts with_semantic_model_with_sources_target_catalog_id to choose the destination Catalog and with_semantic_model_with_sources_source_selections to select existing Catalog files or tables. The CLI exposes --target-catalog-id and --source-selections-file; use moi-cli schema semantic-model create-with-sources --argument source-selections-file for the file structure.
KnowledgeService.append_sources(..., selections=...) also accepts Catalog selections; the CLI exposes semantic-model append-sources --source-selections-file. Knowledge creation exposes descriptions and the image-index setting, while semantic-model update accepts --description, --tables-file and --files-file to pass the corresponding SDK options.
Catalog tree navigation supports pagination, search, resource types and exact resource IDs. CatalogService.tree(include_table_leaves=False) excludes table leaves while omission keeps the server default. An empty resource_types list omits the filter, matching Go's wire encoding. The CLI exposes navigation through catalog tree, system-tree and database-table-leaves; catalog search-data-dashboard-tables exposes permission-scoped table search across databases.
Compute creation and updates accept with_compute_kind / with_compute_update_kind and with_compute_py_requirements_txt / with_compute_update_py_requirements_txt. Both spec operations accept with_compute_spec_node_placement. See Compute configuration for CLI flags, clearing behavior and dependency observations.
Knowledge creation accepts knowledge.create_with_spec with SemanticModelCreateSpec for embedding preservation and drawing settings. Keep description, tables and files in the existing options. See Knowledge creation controls for omission, explicit false and CLI usage.
Workflow template creation and updates expose key, description, input-form and builtin options in the CLI. MOWL templates have a dedicated update method and handle operation. Template response IDs use the handler’s 64-bit range. See Workflow template controls.
Current IAM capabilities
The existing IAM service accepts optional capability IDs:
capabilities = workspace.iam().current_principal_capabilities("action.role.create", "navigation.roles")
Omit IDs to retrieve the full projection. The server evaluates only supported requested IDs and returns the existing metadata, denial reasons and resource scopes in capability ID order. Unknown IDs, including empty values, are reported in capabilities.unsupported_capability_ids with HTTP 200. If all IDs are unsupported, items is empty; duplicate IDs are returned once. The SDK sends IDs unchanged. See the API contract.
A2A message/send semantics
The server answers message/send at task admission (A2A 0.3 non-blocking default): a still-running task returns its persisted non-terminal projection (kind=task, status.state of submitted or working, with metadata.eventCursor), while a task settled inside the admission window keeps its terminal or acknowledgement answer unchanged. configuration.blocking: true is explicitly rejected with HTTP 400, JSON-RPC -32602, and error.data.reason = BLOCKING_UNSUPPORTED; other configuration keys are ignored.
AgentService.a2a() and AgentHandle.send_text() keep their signatures: when a send result is a non-terminal task, the SDK internally follows it to a terminal state before returning — first through tasks/resubscribe resuming at the persisted eventCursor (bounded reconnects with backoff), degrading to tasks/get polling every 2 seconds when the stream cannot be held. Message-kind results (feedback ack, run-control ack, provider interaction) and already-terminal tasks pass through unchanged. The terminal set is completed/failed/canceled/rejected plus the interrupted input-required/auth-required states, which are handed back to the caller for handling.
For explicit protocol control that returns the admission result immediately, pass no_wait=True on A2ARequest to agent.a2a(...) or AgentService.a2a(...). This matches Go's A2ARequest.NoWait and moi-cli agent a2a --no-wait. It only skips the client's task follow; the flag is never sent to the server. Keep the returned task ID to query, resume or cancel the task later.
with_a2a_wait_timeout(seconds) bounds the whole follow (default 600) and is independent of the per-request with_timeout. When the budget is exhausted the call raises Error("ErrTimeout", ...) whose details carry task_id, so the caller can resume the persisted task explicitly instead of treating it as lost.
For task-to-entry-point guidance, start with the AI Decision Ladder, then use the User Story Matrix, AI Task Selection Guide, AI Intent Disambiguation Matrix, and User Context Entry Matrix before dropping to route-aligned services directly. Use the Capability Area Promotion Map, Route-Aligned Service Promotion Map, and Backend API Promotion Checklist when adding or changing product APIs. When a handle needs an existing id, use the Handle ID Source Matrix before writing the constructor call.
AI usage contract:
AI decision ladder:
- Classify the requested product outcome first; use Cross-Domain User Journeys before task rows when the request spans multiple product areas.
- Resolve ambiguous wording with the AI Intent Disambiguation Matrix; ask for explicit user choice when the source or outcome remains unclear.
- Choose the SDK starting object from the User Context Entry Matrix using only supplied context, typed SDK results, UI state, or documented discovery/create calls.
- Select the promoted User Story Matrix row and minimal handle/spec path from the User Story Ergonomic Usage Tiers.
- Verify every existing id with the Handle ID Source Matrix before binding handles.
- Check the detailed safety matrices needed by the selected lifecycle step before polling, retrying, deleting, sharing, displaying, or automating SDK calls.
- Use route-aligned services only when no promoted user-story facade covers the requested outcome or explicit route-level control is required; keep that choice out of friendly SDK examples.
- Match the user request to the Task quick start table, AI Task Selection Guide, or User Story Matrix before choosing an SDK method.
- Use the AI Intent Disambiguation Matrix when a request could match multiple promoted tasks or a route-aligned escape hatch; ask for explicit user choice if the source or outcome remains ambiguous.
- Use the User Context Entry Matrix to choose the SDK starting object from the context already available; if required context is missing, ask for explicit user input or use the documented discover/create path before binding handles.
- Check the User Story Ergonomic Usage Tiers before writing code; start with the minimal path, add advanced control only when the user asks or interaction mode requires it, and use escape boundaries only for uncovered route-level behavior.
- Check the User Story Operation Intent Coverage before assuming a task supports a lifecycle action; each task must state its read/discover, create/configure, update/action, delete/cancel, and observe/result behavior or say the action is not promoted.
- Check the User Story Capability Availability Coverage before choosing method names; the matched task must state availability probe, unavailable signal, required dependency/configuration, forbidden availability workaround, and AI-safe unavailable behavior.
- Check the User Story Abstraction Fitness before choosing method names; each task must state the user mental model, friendly handle/spec shape, hidden route/scope details, caller-owned boundary, and forbidden low-level shortcut.
- If the request spans multiple product areas, choose the Cross-Domain User Journeys outcome first, then follow the User Story Flow Recipes for each matched task before writing code; they define the ordered start point, next calls, produced handles/results, and source rules.
- Check the User Story State Handoff Coverage before passing values between SDK calls; the matched task must state carried typed state, public accessor/result source, next-call binding, forbidden handoff shortcut, and AI-safe handoff behavior.
- Check the Cross-Domain Journey Example Anchors before copying README example lines for a multi-area outcome.
- Check the Cross-Domain Journey Risk Coverage before composing retries, cancellations, reruns, permission-sensitive operations, or external dependency calls across product areas.
- Check the User Story Discovery and Selection Coverage before constructing handles from ids; it identifies the promoted discover/create path and when route-aligned fallback is not a promoted discovery path.
- Check the User Story Selection Disambiguation Coverage before selecting one resource from list, search, name, or paginated results; the matched task must state selection input, uniqueness rule, pagination/search boundary, ambiguous/missing selection handling, and forbidden selection shortcut.
- Check the User Story Ordering and Recency Coverage before honoring latest, recent, oldest, first, top, sorted, priority, or time-window wording; the matched task must state ordering intent, authoritative order source, recency/time-window source, forbidden ordering shortcut, and AI-safe ordering behavior.
- Check the User Story Outcome Contracts before treating a task as complete; confirm the user-visible outcome, continuation handle/spec, and caller-owned inputs or decisions.
- Check the User Story Interaction Mode Coverage before writing code that polls, streams, paginates, batches, deletes, cancels, forces, or asks for approval.
- Check the User Story Execution Budget Coverage before polling, streaming, paginating, retrying, or waiting on long-running work; the matched task must state timeout/deadline source, polling/stream stop condition, page/batch limit, retry budget, and approval/escalation boundary.
- Check the User Story Pagination and Partial Result Coverage before treating first pages, previews, streams, batches, or capped reads as complete; the matched task must state paginated/partial surfaces, continuation token/source, complete-result proof, forbidden partial-result shortcut, and AI-safe pagination behavior.
- Check the User Story Error Recovery Coverage before adding retries, reruns, prompts, or fallback behavior; the matched task must state retryable failures, user-correctable failures, forbidden recovery, and the AI-safe next action.
- Check the User Story Permission and Scope Coverage before issuing permission-sensitive calls; the matched task must state product scope, permission-sensitive operations, caller-owned authorization boundary, forbidden scope/RBAC behavior, and AI-safe permission handling.
- Check the User Story Ownership and Collaboration Coverage before modifying, exposing, deleting, sharing, or continuing work on resources in a shared workspace; the matched task must state ownership evidence, collaborator/shared scope, caller-owned decision boundary, forbidden cross-user shortcut, and AI-safe collaboration behavior.
- Check the User Story Input Construction Coverage before constructing specs, options, enum values, secrets, or payloads; the matched task must state required caller inputs, derived typed-result inputs, option/enum/secret rules, forbidden construction behavior, and AI-safe construction.
- Check the User Story Value Format and Units Coverage before serializing identifiers, timestamps, durations, byte sizes, limits, enum values, URLs, SQL, cron, or payload fields; the matched task must state value/format contract, unit/timezone authority, enum/identifier format, forbidden format shortcut, and AI-safe value behavior.
- Check the User Story Default and Omission Coverage before relying on omitted fields, empty values, zero values, or backend defaults; the matched task must state optional omissions, invalid empty/zero values, backend/default authority, forbidden defaulting behavior, and AI-safe omission behavior.
- Check the User Story Completion Verification Coverage before treating a write, async start, delete, cancel, or error-only method as complete; the matched task must state completion signal, verification call, async/delete/cancel handling, forbidden completion shortcut, and AI-safe stop condition.
- Check the User Story Result Accessor Coverage before reading returned values; the matched task must state public result/accessor source, user-readable fields, continuation fields, forbidden extraction shortcut, and AI-safe accessor behavior.
- Check the User Story Output Consumption Coverage before displaying or reusing returned values; the matched task must state user-facing output, continuation output, sensitive/internal output boundary, forbidden output consumption, and AI-safe consumption behavior.
- Check the User Story Sensitive Data Handling Coverage before logging, persisting, showing examples, or passing SDK inputs/outputs into AI context; the matched task must state sensitive inputs, sensitive outputs, logging/example boundary, persistence/AI-context boundary, and AI-safe handling.
- Check the User Story Automation Safety Coverage before repeating or automating SDK calls; the matched task must state repeat-safe behavior, idempotency key or lookup, external/cost side-effect boundary, forbidden automation shortcut, and AI-safe automation behavior.
- Check the User Story Concurrent Submission Coverage before allowing parallel SDK calls, UI double-clicks, background polls, async retries, or multiple AI workers to act on the same task; the matched task must state operation identity, parallel-safe reads, serialized mutation boundary, forbidden duplicate submission, and AI-safe in-flight behavior.
- Check the User Story Impact Assessment Coverage before asking for confirmation or executing high-impact SDK operations; the matched task must state impact source, affected scope, cost/external side effects, uncertainty boundary, and AI-safe impact summary.
- Check the User Story Confirmation and Preview Coverage before destructive, cost-incurring, external, data-moving, permission-changing, or irreversible SDK operations; the matched task must state confirmation trigger, preview/preflight source, user-visible confirmation summary, forbidden implicit approval, and AI-safe confirmation behavior.
- Check the User Story Abort and Cleanup Coverage before abandoning, canceling, compensating, or cleaning up partial SDK work; the matched task must state abort trigger, cleanup/compensation target, state proof before cleanup, forbidden rollback shortcut, and AI-safe abort behavior.
- Check the User Story Progress Visibility Coverage before waiting on, streaming, paginating, batching, deleting, canceling, or otherwise monitoring SDK work; the matched task must state progress signal, status/read call, user-visible update, forbidden silent wait, and AI-safe progress reporting.
- Check the User Story Diagnostic Handoff Coverage before asking a user, support engineer, or later AI step to debug a failed, stuck, or ambiguous task; the matched task must state safe diagnostic context, correlation/status handle, sensitive diagnostic boundary, forbidden diagnostic shortcut, and AI-safe diagnostic handoff.
- Check the User Story Freshness and Conflict Coverage before updating, deleting, canceling, rerunning, publishing, or otherwise acting on previously read state; the matched task must state fresh-state source, conflict/stale signal, destructive/update conflict boundary, forbidden stale-state shortcut, and AI-safe conflict handling.
- Check the User Story Stability Evidence before writing code; the matched task must list Go/Python facade tests, stable proof, and failure boundary.
- Check the User Story Representative Method Coverage before writing examples; the matched task must have visible Go/Python calls that mirror the language README examples.
- Check the User Story Example Scenario Coverage before adapting examples; the matched task must state user scenario, copyable example anchor, inputs to replace, expected user-visible output, and AI adaptation boundary.
- Bootstrap through the product endpoint, then use
ensure_workspacefor name-based find/create orworkspaceonly for an already sourced workspace id before continuing withWorkspaceHandlefor workspace-scoped tasks. - Prefer the listed handle/spec entry points whenever they exist; do not start from
client.<domain>(workspace_id)for a promoted user task. - Use route-aligned services only as an explicit escape hatch for domains without a promoted user-story facade or when route-level control is required.
- Do not expose the Apps backend domain through the Python Product SDK, including
/apps,/apps/:app_code, or app-specific workflows. - When a handle requires an existing id, obtain that id from a typed SDK create/list/get result, a UI-selected resource, or explicit user input; handle constructors only bind existing resources and do not create or discover them; do not invent ids or infer them from
ProductData. - Treat error-only write methods as success/failure checks only; they do not return product data, ids, or handles and must not be used as the source for the next SDK call.
Task quick start:
Use the Cross-Domain User Journeys first when the request spans multiple product areas. Then use the AI Task Selection Guide for intent signals and avoid rules before applying this table. Use the AI Intent Disambiguation Matrix when wording could match multiple tasks or a route-aligned escape hatch. Use the User Context Entry Matrix to choose the SDK starting object from the context already available. Check the User Story Ergonomic Usage Tiers so examples start with the minimal path and add advanced control only when needed. Check the User Story Operation Intent Coverage before adding lifecycle actions such as create/configure, update/action, delete/cancel, or observe/result. Check the User Story Capability Availability Coverage before choosing method names. Check the User Story Abstraction Fitness before picking handles or specs so the code follows the user mental model instead of route-group translation. After choosing a row, follow its User Story Flow Recipe before writing code. Check the User Story State Handoff Coverage before passing values between SDK calls. Check the Cross-Domain Journey Risk Coverage before composing retries, cancellations, reruns, permission-sensitive operations, or external dependency calls. Check the User Story Discovery and Selection Coverage before constructing handles from ids. Check the User Story Selection Disambiguation Coverage before selecting one resource from list, search, name, or paginated results. Then check the User Story Outcome Contract so generated code stops at a user-visible result and keeps caller-owned inputs explicit.
| User task | Prefer |
|---|---|
| Bootstrap a UI workspace and inspect identity | Client.ensure_workspace, Client.workspace, WorkspaceHandle |
| Manage workspace members | WorkspaceMemberHandle |
| Browse catalog resources and operate tables | CatalogHandle, DatabaseHandle, TableHandle, TableColumn |
| Manage volumes, folders, and files | VolumeHandle, FolderHandle, FileHandle, UploadedFilePreview, ConnectorFileHandle |
| Deploy, run, inspect, rerun, and cancel workflows | WorkflowHandle, WorkflowRunHandle, WorkflowRunNodeHandle, WorkflowRunRerunHandle |
| Design workflow custom operators and templates | CustomOperatorHandle, CustomOperatorSpec, CustomOperatorTestInput, WorkflowTemplateHandle |
| Publish and invoke WorkItem API services | WorkitemAPIServiceHandle, WorkitemAPIServicePublishSpec, WorkitemAPIServiceInvokeSpec |
| Review lineage artifacts and rerun from nodes/blocks | ArtifactHandle, ArtifactBlockHandle, ArtifactNodeHandle, ArtifactNodeBlockHandle, LineageRevisionSwitch |
| Ask Explore questions with selected sources | ExploreSessionHandle, ExploreMessageHandle, ExploreDataSources |
| Browse Explore source tables and columns | ExploreDataHandle, ExploreDatabaseHandle, ExploreTableHandle |
| Manage semantic models and entries | SemanticModelHandle, SemanticEntryHandle, SemanticEntryInput |
| Manage connectors plus import/export tasks | ConnectorHandle, FileImportTaskSpec, ImportTaskUpdateSpec, ExportTaskSpec, ExportTaskConfig, ExportTaskFile, ImportTaskHandle, ExportTaskHandle |
| Use product agents through A2A | AgentHandle, AgentTextMessage, AgentTaskRequest, AgentInputSubmission |
| Configure model providers and routers | ModelProviderHandle, ProviderBackendHandle, ProviderRouterHandle |
| Manage compute resources | ComputeResourceHandle |
| Publish and subscribe data shares | DataSharePublishHandle, DataShareSubscriptionHandle |
| Work in the SQL editor and query history | SQLMetadataHandle, SQLDatabaseMetadataHandle, SQLTableMetadataHandle, SQLWorkbookHandle, SQLWorkbookVersionHandle, SQLQueryHandle, SQLStatementHandle |
Endpoint rule:
- Product Python SDK clients use the same product API gateway and RBAC layer used by the MOI UI.
- Local SDK development and integration tests may use
moi-backenddirectly when no product gateway is running. moi-backendmust support user-scoped API key authentication for SDK calls, not only UI token/session authentication.- Product Python SDK clients must not use
moi-core/catalogas their default endpoint. - Direct catalog access belongs to core SDKs, backend internals, or test diagnostics, not to Product SDK actions.
Gate meaning:
- Route alignment proves required backend product routes are reachable from Go and Python SDK services.
- Route alignment uses the runtime Gin route manifest from
moi-backend/cmd/sdk-route-manifestand fails when a required backend product route has no Go and Python SDK route mapping. - Capability maturity proves known SDK methods do not regress into raw request/response shapes without an explicit design exemption.
- User-story facade alignment proves promoted task-level handle/spec APIs are present in both Go and Python SDKs, remain cross-language compatible, and do not regress into route-only or raw request/response shapes.
- It checks Go/Python promoted handle methods and direct
Clientuser-story entries for compatible parameter names, parameter shapes, and return shapes so user-facing snippets transfer across languages. - It checks promoted builder objects such as
ExploreDataSourcesfor cross-language method, parameter, and return-shape parity. - It also checks option helpers used by promoted handle option families for Go/Python counterparts, compatible parameter names and shapes, and Python package-root exports.
- It checks option helpers remain modifiers of already selected
Clientor handle calls, not user-story SDK entry points, AI task-selection sources, or standalone copy anchors. - It checks A2A protocol constants and low-level request types remain explicit protocol-control values, not user-story SDK entry points, AI task-selection sources, or standalone copy anchors.
- It checks SDK error types, helpers, and sentinel values remain diagnostic/error-branch values, not user-story SDK entry points, AI task-selection sources, recovery-strategy sources, input-construction sources, or standalone copy anchors.
- It checks local file path upload helpers remain caller-supplied file input conveniences, not AI file-discovery, local-filesystem probing, filename-inference, default upload entry points, or standalone copy anchors.
- It also checks Go/Python promoted spec, input, message, request, submission, and config fields for parity so examples and AI-written code do not drift at the object-construction boundary.
- It checks User Story Gap Register rows keep non-promoted route-aligned gaps out of every user-friendly SDK section.
- It checks route-aligned
sdk_methodentries stay route coverage facts, not AI copy anchors, until user-story handle/spec evidence promotes the outcome. - Route mapping metadata is for alignment gates and diagnostics only; it is not a user-story SDK entry point, AI task-selection source, or example anchor.
- Passing route alignment alone does not prove a new backend API has a high-level user-story SDK. New user-facing tasks need Go/Python facade entries with compatible parameter names, parameter shapes, return shapes, and promoted input fields before they are considered promoted.
- The gate does not parse README snippets or Example task index Replace/Result/source columns to prove documentation variable completeness.
Minimal Python bootstrap:
product_endpoint must include the environment's product API base path, for
example https://example.com/newmoi or another environment-specific prefix.
The SDK appends product-relative paths to that address and does not add
/newmoi itself.
`python import moi_product_sdk as sdk
def run(product_endpoint: str, api_key: str, workspace_name: str): client = sdk.Client(product_endpoint, sdk.with_api_key(api_key)) workspace = client.ensure_workspace(workspace_name) return workspace.db_connection() `
Example task index:
Use this index before copying from the reference catalog. It keeps each copied snippet anchored to one user task, identifies caller-owned variables, and shows the handle/result that proves the task can continue. After choosing an anchor, follow the selected Flow Recipe in recipe order; do not treat the anchor as a complete workflow by itself. Check before run entries summarize task-specific Error Recovery, Permission and Scope, Confirmation and Preview, and Progress Visibility Coverage.
| User task | Copy anchor | Replace | Result | Continue with | Check before run |
|---|---|---|---|---|---|
| Bootstrap a UI workspace and inspect identity | client.ensure_workspace( |
product_endpoint, api_key, workspace_name. |
workspace result. |
WorkspaceHandle descendants from the selected Flow Recipe. |
Check auth error handling, workspace permission scope, duplicate-name confirmation, and progress visibility. |
| Manage workspace members | workspace.invite_member( |
user_display_name, explicit default_role_id, user_email or user_mobile_number, canonical assigned_role_ids containing that Default Role, a member ID for lifecycle operations, and iam_user_id from member detail for role bindings. |
invitation result, then accepted member detail with iam_user_id. |
Bind WorkspaceMemberHandle with the member ID for lifecycle calls; pass iam_user_id to IAM role-binding calls. |
Check IAM error handling, role-assignment scope, confirmation, and audit/progress visibility. |
| Browse catalog resources and operate tables | workspace.prepare_catalog( |
catalog_name, database_name, table_name, table_columns, table_data_url, table_page_size. |
catalog, database, table, and rows results. |
DatabaseHandle or TableHandle from the selected Flow Recipe. |
Check catalog error handling, workspace permission scope, destructive table confirmation, and page/progress visibility. |
| Manage volumes, folders, and files | database.prepare_volume( |
volume_name, folder_name, file_name, local_file_path, csv_bytes, download_as_zip. |
volume, file, and download results. |
VolumeHandle, FolderHandle, or FileHandle from the selected Flow Recipe. |
Check file error handling, workspace permission scope, delete/clean confirmation, and upload/download progress visibility. |
| Deploy, run, inspect, rerun, and cancel workflows | workspace.deploy_workflow( |
workflow_name, workflow_id, dsl_yaml, workflow_run_input, execution_id, node_id, node_execution_id, workflow_rerun_mode. |
workflow, run_data, run, and created_rerun results. |
WorkflowHandle, WorkflowRunHandle, or WorkflowRunNodeHandle from the selected Flow Recipe. |
Check workflow error handling, workspace permission scope, rerun/cancel confirmation, and run progress visibility. |
| Design workflow custom operators and templates | workspace.create_custom_operator_from_spec( |
operator_name, operator_test_input, workflow_template_name, dsl_yaml. |
operator, tested_operator, and workflow_template results. |
CustomOperatorHandle or WorkflowTemplateHandle from the selected Flow Recipe. |
Check validation error handling, workspace permission scope, enable/delete confirmation, and test progress visibility. |
| Publish and invoke WorkItem API services | service.publish( |
node_id, service_version, compute_resource_id, service_name, service_type, service_payload, service_timeout_seconds, service_max_concurrency, service_rate_limit_per_min. |
service, published_service, and invoked_service results. |
WorkitemAPIServiceHandle from the selected Flow Recipe. |
Check publish/invoke error handling, service permission scope, enable/disable confirmation, and invocation progress visibility. |
| Review lineage artifacts and rerun from nodes/blocks | file.lineage_overview() |
artifact_id. |
file_lineage, artifact, and artifact_blocks results. |
ArtifactHandle, ArtifactBlockHandle, or ArtifactNodeHandle from the selected Flow Recipe. |
Check lineage error handling, artifact permission scope, rerun/revision confirmation, and rerun progress visibility. |
| Ask Explore questions with selected sources | session.query_with_sources( |
explore_question, catalog_id, database_id, table_id, semantic_model_id, explore_database_name, explore_table_name. |
sources, session, and answer results. |
ExploreSessionHandle or ExploreMessageHandle from the selected Flow Recipe. |
Check query error handling, source permission scope, stream/feedback confirmation, and answer progress visibility. |
| Browse Explore source tables and columns | workspace.explore_data() |
database_id, table_id, explore_database_name, explore_table_name, table_page_size. |
explore_data, explore_database, explore_table, and columns results. |
ExploreDataHandle, ExploreDatabaseHandle, or ExploreTableHandle from the selected Flow Recipe. |
Check browse error handling, source permission scope, broad-scan confirmation, and page progress visibility. |
| Manage semantic models and entries | workspace.create_semantic_model( |
semantic_model_name, semantic_entry_kind, semantic_entry_key, semantic_entry_spec, table_name. |
semantic_model, semantic_entry, and validated_model results. |
SemanticModelHandle or SemanticEntryHandle from the selected Flow Recipe. |
Check semantic error handling, model permission scope, import/delete confirmation, and validation progress visibility. |
| Manage connectors plus import/export tasks | connector.create_file_import_task( |
connector_name, import_task_uris, config_type, import_task_name, import_task_updated_name, volume_id, file_id, load_mode_config, file_filter_config, updated_import_task_uris, export_task_name, export_type, s3_config, export_file_path. |
connector, import_task, and export_task results. |
ConnectorHandle, ImportTaskHandle, or ExportTaskHandle from the selected Flow Recipe. |
Check connector error handling, external permission scope, import/export confirmation, and transfer progress visibility. |
| Use product agents through A2A | agent.send_text( |
agent_code, agent_prompt, request_id, status_request_id, agent_message_id. |
agent, agent_task, agent_task_id, and agent_task_status results. |
AgentHandle and A2A task calls from the selected Flow Recipe. |
Check A2A error handling, agent permission scope, cancel/input confirmation, and stream/task progress visibility. |
| Configure model providers and routers | llm.create_backend( |
provider_backend_name, provider_model_names, model_endpoint, router_strategy, embedding_model_names. |
llm, llm_backend, and router results. |
ModelProviderHandle, ProviderBackendHandle, or ProviderRouterHandle from the selected Flow Recipe. |
Check provider error handling, secret permission scope, router/delete confirmation, and probe progress visibility. |
| Manage compute resources | workspace.create_compute_resource( |
spec_id, worker_image, compute_cpu, compute_memory_gb, compute_min_replicas, compute_max_replicas. |
compute and suspended results. |
ComputeResourceHandle from the selected Flow Recipe. |
Check compute error handling, resource permission scope, action/delete confirmation, and action progress visibility. |
| Publish and subscribe data shares | workspace.create_data_share_publish( |
publish_name, source_database_id, table_scope, source_table_ids, target_workspace_id, subscription_id, subscription_name, data_share_remark. |
publish, subscription, and subscribed results. |
DataSharePublishHandle or DataShareSubscriptionHandle from the selected Flow Recipe. |
Check share error handling, cross-workspace permission scope, subscribe/delete confirmation, and share progress visibility. |
| Work in the SQL editor and query history | workspace.execute_sql( |
sql_text, sql_workbook_name, statement_id, target_database_name, sql_result_limit. |
sql_metadata, workbook, query, statement, and rows results. |
SQLMetadataHandle, SQLWorkbookHandle, SQLQueryHandle, or SQLStatementHandle from the selected Flow Recipe. |
Check SQL error handling, database permission scope, cancel/drop confirmation, and query progress visibility. |
Example selection rule: the representative Python snippets below are a reference catalog, not one complete runnable workflow. For a user request, first choose the Cross-Domain User Journey or User Story Matrix task, then copy only the minimal ordered lines required by that task's User Story Flow Recipe. Do not combine unrelated lines from the catalog into one generated workflow.
`python import moi_product_sdk as sdk
client = sdk.Client(product_endpoint, sdk.with_api_key(api_key)) workspace = client.ensure_workspace(workspace_name) profile = workspace.db_connection() db = workspace.db_connection() invitation = workspace.invite_member(user_display_name, role_id, sdk.with_user_email(user_email), sdk.with_user_role_ids(role_id)) user = workspace.member(active_member_user_id) member = user.info() canonical_iam_user_id = member.iam_user_id bindings = workspace.iam().user_role_bindings(canonical_iam_user_id) expected_binding_version = sdk.iam_binding_version_number(bindings) updated_bindings = workspace.iam().put_user_role_bindings( canonical_iam_user_id, sdk.IAMUserRoleBindingsRequest( assigned_role_ids=assigned_role_ids, default_role_id=default_role_id, expected_binding_version=expected_binding_version, expected_default_role_version=bindings.default_role_version, request_id=request_id, ), ) catalog = workspace.prepare_catalog(catalog_name) database = catalog.prepare_database(database_name) catalogs, catalog_list = workspace.catalogs() databases, database_list = catalog.databases() children = database.children() volumes, volume_children = database.volumes() tables, table_children = database.tables() table, created_table = database.create_table_from_columns(table_name, table_columns, sdk.with_table_data_file_url(table_data_url)) rows = table.data(sdk.with_table_data_page_size(table_page_size)) preview_rows = table.preview(sdk.with_table_preview_lines(table_preview_lines)) volume = database.prepare_volume(volume_name) volume = workspace.prepare_data_volume(catalog_name, database_name, volume_name) uploaded = volume.upload_bytes(file_name, csv_bytes) file = volume.upload_bytes_handle(file_name, csv_bytes) local_file = volume.upload_file_handle(local_file_path) volume_preview = volume.upload_bytes_preview(file_name, csv_bytes) local_volume_preview = volume.upload_file_preview(local_file_path) file = workspace.upload_bytes_to_data_volume(catalog_name, database_name, volume_name, file_name, csv_bytes) local_file = workspace.upload_file_to_data_volume(catalog_name, database_name, volume_name, local_file_path) previewed = workspace.upload_bytes_preview_to_data_volume(catalog_name, database_name, volume_name, file_name, csv_bytes) local_previewed = workspace.upload_file_preview_to_data_volume(catalog_name, database_name, volume_name, local_file_path) volume = workspace.attach_data_volume_workflow(catalog_name, database_name, volume_name, workflow_id) volume = workspace.detach_data_volume_workflow(catalog_name, database_name, volume_name, workflow_id) path = volume.full_path() refs = volume.refs() files = volume.files(sdk.with_file_list_page_size(file_list_page_size)) processed_files = volume.processed_files(sdk.with_processed_volume_files_limit(processed_files_limit)) path = workspace.data_volume_full_path(catalog_name, database_name, volume_name) refs = workspace.data_volume_refs(catalog_name, database_name, volume_name) folder, created_folder = volume.create_folder(folder_name, sdk.with_folder_description(folder_description)) folder = folder.rename(renamed_folder_name, sdk.with_updated_folder_description(updated_folder_description)) folder_refs = folder.refs() folder.clean() folder.delete() info = file.info() file = file.rename(renamed_file_name) download = file.download(sdk.with_file_as_zip(download_as_zip)) download.close() preview_stream = file.preview() preview_stream.close() excel_preview = file.preview_excel(sdk.with_excel_sheet_name(excel_sheet_name)) data_asset = file.data_asset() file_artifact = file.artifact()
First deployment: let the server allocate the ID. Pass an existing ID to publish a new version.
workflow, deployed = workspace.deploy_workflow(workflow_name, dsl_yaml) workflow_id = workflow.id workflow = workspace.workflow(workflow_id) run_data = workflow.run(sdk.with_workflow_run_input(workflow_run_input)) file_lineage = file.lineage_overview() artifact = workspace.artifact(artifact_id) artifact_blocks = artifact.output_blocks() artifact_node = artifact.node(node_id) node_rerun = artifact_node.rerun(sdk.with_lineage_rerun_mode(lineage_rerun_mode)) run = workflow.run_handle(execution_id) run_node = run.node_handle(node_key) rerun_plan = run_node.rerun_plan(sdk.with_source_node_execution_id(node_execution_id)).plan created_rerun = run_node.create_rerun(workflow_rerun_mode, node_execution_id, sdk.with_expected_workflow_rerun_contract_hash(rerun_plan.rerun_contract_hash)) rerun = run.rerun(rerun_id) rerun_info = rerun.info() result = run.result() cancelled = run.cancel(sdk.with_workflow_cancel_reason(workflow_cancel_reason)) operator_spec = sdk.CustomOperatorSpec(operator_name, operator_identifier, operator_description, input_schema, output_schema) operator, created_operator = workspace.create_custom_operator_from_spec(operator_spec) tested_operator = operator.test_with_input(sdk.CustomOperatorTestInput(operator_test_input)) workflow_template, created_template = workspace.create_workflow_template(workflow_template_name, dsl_yaml) workflow_template_info = workflow_template.info() service = workspace.workitem_api_service(node_id, service_version) published_service = service.publish(sdk.WorkitemAPIServicePublishSpec(service_version, compute_resource_id=compute_resource_id, timeout_seconds=service_timeout_seconds, max_concurrency=service_max_concurrency, rate_limit_per_min=service_rate_limit_per_min)) invoked_service = service.invoke(sdk.WorkitemAPIServiceInvokeSpec(service_name, service_type, service_version, service_payload)) session, created = workspace.create_explore_session(explore_session_title) session = workspace.explore_session(explore_session_id) explore_data = workspace.explore_data() overview = explore_data.overview() explore_database = explore_data.database(database_id, explore_database_name) explore_tables = explore_database.tables() explore_table = explore_database.table(table_id, explore_table_name) columns = explore_table.columns() sources = sdk.ExploreDataSources().with_table(explore_database_name, [explore_table_name], catalog_id).with_semantic_models(semantic_model_id) answer = session.query_with_sources(explore_question, sources) messages = session.messages(sdk.with_explore_message_limit(explore_message_limit)) latest = session.latest_message_id() message = session.message(message_id) liked = message.like() semantic_model, created_model = workspace.create_semantic_model(semantic_model_name, sdk.with_semantic_model_tables([table_name])) semantic_entry, created_entry = semantic_model.create_entry(sdk.SemanticEntryInput(semantic_entry_kind, semantic_entry_key, semantic_entry_spec, [table_name])) validated_model = semantic_model.validate() exported_model = semantic_model.export() connector, created_connector = workspace.create_connector(connector_name, source_type, usage_type) connector = workspace.connector(connector_id) source_databases = connector.source_databases() source_schemas = connector.source_schemas(source_schema_name) source_tables = connector.source_tables(source_schema_name) source_schema = connector.source_schema(source_schema_name, table_name) target_databases = connector.mo_databases() target_tables = connector.mo_database_tables(target_database_name) target_table_exists = connector.check_mo_table_name(target_database_name, table_name) column_mapping = connector.mo_column_mapping(target_database_name, table_name, column_mapping_input) connector_file = connector.file(connector_file_id) preview = connector_file.preview(sdk.with_connector_preview_row_start(connector_preview_row_start)) download_url = connector_file.download() stream = connector_file.stream() stream.close() connector_file.delete() import_task, imported = connector.create_file_import_task(sdk.FileImportTaskSpec(config_type, import_task_uris, load_mode_config, file_filter_config, name=import_task_name, volume_id=volume_id)) import_task.update_config(sdk.ImportTaskUpdateSpec(load_mode_config, name=import_task_updated_name, file_filter_config=file_filter_config, uris=updated_import_task_uris)) import_runs = import_task.runs() import_task.retry_files(file_id) export_task, exported = connector.create_export_task_from_spec(sdk.ExportTaskSpec(export_task_name, connector_name, export_type, sdk.ExportTaskConfig(s3_config=s3_config), [sdk.ExportTaskFile(file_id, export_file_path)])) export_state = export_task.state() export_task.retry(file_id) agent = workspace.agent_by_code(agent_code) agent_task = agent.send_text(sdk.AgentTextMessage(agent_prompt, agent_message_id, request_id=request_id)) agent_task_id = sdk.agent_a2a_task_id(agent_task) agent_task_status = agent.get_task(sdk.AgentTaskRequest(agent_task_id, request_id=status_request_id)) agent_turn_id = sdk.agent_a2a_turn_id(agent_task) agent_input = agent.submit_input(sdk.AgentInputSubmission(agent_task_id, agent_turn_id, agent_input_answers, request_id=input_request_id)) llm = workspace.llm_provider() llm_backend, created_llm = llm.create_backend(provider_backend_name, sdk.with_provider_backend_address(model_endpoint), sdk.with_provider_backend_models(*provider_model_names)) models = llm_backend.probe_models(sdk.with_provider_backend_api_key(api_key)) endpoints = llm_backend.endpoints() router = llm.router().update(sdk.with_router_strategy(router_strategy)) embedding = workspace.embedding_provider() embedding_backend, created_embedding = embedding.create_backend(embedding_backend_name, sdk.with_provider_backend_models(*embedding_model_names)) embedding_models = embedding_backend.probe_models() parser = workspace.parser_provider() parser_backend, created_parser = parser.create_backend(parser_backend_name, sdk.with_provider_backend_supported_mime_types(*supported_mime_types)) group = workspace.alert_group(alert_group_id) workspace.create_alert_receiver(group.id, receiver_name, notify_type, receiver_status, sdk.with_receiver_email(receiver_email)) receiver = workspace.alert_receiver(receiver_id) workspace.create_alert_rule(expression_id, alert_level, alert_category, sdk.with_alert_rule_receivers(receiver.id)) rule = workspace.alert_rule(alert_rule_id) history = group.history(sdk.with_alerting_page(alerting_page), sdk.with_alerting_size(alerting_size)) group.mark_read() rule.update(sdk.with_alert_rule_update_level(updated_alert_level)) receiver.update(sdk.with_receiver_update_status(receiver_update_status)) compute, created_compute = workspace.create_compute_resource(worker_image, spec_id, compute_cpu, compute_memory_gb, sdk.with_compute_min_replicas(compute_min_replicas), sdk.with_compute_max_replicas(compute_max_replicas)) preflight = compute.preflight_delete() suspended = compute.suspend() resumed = compute.resume() compute.delete(sdk.with_force(compute_force_delete)) table_scope = sdk.DataShareScope(mode="selected", object_ids=source_table_ids) publish, created_publish = workspace.create_data_share_publish(publish_name, source_database_id, table_scope, [target_workspace_id], sdk.with_data_share_remark(data_share_remark)) summary = workspace.data_share_summary() publish = workspace.data_share_publish(publish_id) updated_publish = publish.update(sdk.with_data_share_update_table_scope(table_scope)) subscription = workspace.data_share_subscription(subscription_id) subscribed = subscription.subscribe(subscription_name) subscription.unsubscribe() publish.delete() sql_metadata = workspace.sql_metadata() sql_databases = sql_metadata.databases() sql_tree = sql_metadata.tree() sql_database = sql_metadata.database(target_database_name) sql_tables = sql_database.tables() sql_table = sql_database.table(table_name) sql_columns = sql_table.columns() sql_ddl = sql_table.ddl() workbook, created_workbook = workspace.create_sql_workbook(sql_workbook_name) version, created_version = workbook.create_version(sql_text) version.save() query, started_query = workspace.execute_sql(sql_text, sdk.with_sql_query_db_name(target_database_name)) query_state = query.describe() statement = workspace.sql_statement(statement_id) rows = statement.result(sdk.with_sql_result_limit(sql_result_limit)) profile = statement.profile() catalog = catalog.rename(renamed_catalog_name) database = database.rename(renamed_database_name) table_path = table.full_path() table_refs = table.refs() table.truncate() table.delete() volume = volume.rename(renamed_volume_name) catalog_info = catalog.info() database_info = database.info() volume_info = volume.info() catalog_refs = catalog.refs() database_refs = database.refs() file.delete_ref() file.delete() volume.delete() database.delete() catalog.delete() failures = workspace.recent_failed_audit_logs(recent_audit_limit) `
SQL result download API contract after PR #14017
The Python Product SDK does not currently expose a helper for SQL result downloads. Consumers that call the backend directly must use:
POST /newmoi/query/result/download
{"statement_id":"<owned saved-result statement ID>"}
Use the normal Product API authentication and workspace context. Get
statement_id from SQL execution or query history. A missing ID is rejected,
and the server does not re-execute SQL text or accept query / db_name as a
compatibility fallback.
The route returns a streamed CSV response. The calling Python HTTP client owns the response stream and must consume and close it. This repository change does not add a Python SDK method, modify SDK version metadata, or publish a package.
Metadata
Release files for moi-product-sdk 0.1.0.dev20261119093303
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| moi_product_sdk-0.1.0.dev20261119093303.tar.gz | 385.6 kB | Without provenance | Details for moi_product_sdk-0.1.0.dev20261119093303.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| moi_product_sdk-0.1.0.dev20261119093303-py3-none-any.whl | Python 3 | none | any | Details for moi_product_sdk-0.1.0.dev20261119093303-py3-none-any.whl |
Total release size: 610.5 kB
Release files / moi_product_sdk-0.1.0.dev20261119093303.tar.gz
| Download URL | moi_product_sdk-0.1.0.dev20261119093303.tar.gz |
|---|---|
| Size | 385.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9218d94564e01b206e680be802aff2fb7e6770950092bca0c24bbbe49d15d72f
|
|
BLAKE2b-256 checksum How to use checksums |
d7d27443b334fda2eed5749b12030f371ebc2a69e1529e9a3713dcd7d171dcec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Release files / moi_product_sdk-0.1.0.dev20261119093303-py3-none-any.whl
| Download URL | moi_product_sdk-0.1.0.dev20261119093303-py3-none-any.whl |
|---|---|
| Size | 224.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
310046d6842bc68d7c4467a76daec4476462a88a047c1b166ee590475f74045f
|
|
BLAKE2b-256 checksum How to use checksums |
de4d5dd3ee87781082a6a010ddf13b99049e92d823fb64394bf949a0bb28de59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.6
|
Security for moi-product-sdk 0.1.0.dev20261119093303
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.