Scopes - Modus Docs

ScopesResource

class ScopesResource(http: HttpClient, config: ModusConfig, ops: ManagementScopesOperations = ManagementScopesOperations(list='ScopesController_list', get='ScopesController_get', create='ScopesController_create', update='ScopesController_update', deploy='ScopesController_deploy', delete='ScopesController_delete', restore='ScopesController_restore', request_ownership_transfer='ScopesController_requestOwnershipTransfer', cancel_ownership_transfer='ScopesController_cancelOwnershipTransfer', accept_ownership_transfer='ScopesController_acceptOwnershipTransfer', patch_mcp_config='ScopesController_patchMcpConfig', get_variation='ScopesController_getVariation', conversations=ScopeConversationsOperations(list='ScopeConversationsController_list', get='ScopeConversationsController_get'), memories=ScopeMemoriesOperations(list='ScopeMemoriesController_list', search='ScopeMemoriesController_search', update='ScopeMemoriesController_update', delete='ScopeMemoriesController_delete'), evaluations=ScopeEvaluationsOperations(get_config='EvaluationsController_getConfig', update_config='EvaluationsController_updateConfig', trigger_run='EvaluationsController_triggerRun', list_runs='EvaluationsController_listRuns', get_run='EvaluationsController_getRun')))

Bases: object Full CRUD access to Modus scopes. mgmt.scopes.list() → page of scopes mgmt.scopes.get(scope_id) → scope (with variation fields) mgmt.scopes.create(name, ...) → scope mgmt.scopes.update(scope_id, ...) → scope mgmt.scopes.deploy(scope_id) → scope mgmt.scopes.delete(scope_id) → None mgmt.scopes.conversations(scope_id).list() → page of conversations mgmt.scopes.conversations(scope_id).get(tid) → conversation

conversations()

conversations(scope_id: int | str) → ScopeConversationsResource

Return the conversations sub-resource scoped to scope_id.

memories()

memories(scope_id: int | str) → ScopeMemoriesResource

Return the memories sub-resource scoped to scope_id.

evaluations()

evaluations(scope_id: int | str) → ScopeEvaluationsResource

Return the evaluations sub-resource scoped to scope_id.

supervision()

supervision(scope_id: int | str) → ScopeSupervisionResource

Return the supervision sub-resource scoped to scope_id.

list()

list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, view: Literal['active', 'draft'] | None = None, manager_id: int | None = None) → Page[ScopeDto]

List all Modus scopes in the organisation.

Parameters:
- page_size – Maximum number of items to return (default 25).
- page_token – Token from a previous page’s next_page_token; omit for the first page.
- search – Case-insensitive substring filter on the scope name.
- view – Variation view — "active" (deployed) or "draft".
- manager_id – Return only scopes supervised by this manager scope id.

get()

get(scope_id: int | str, *, view: Literal['active', 'draft'] | None = None) → ScopeDto

Retrieve a Modus scope with full configuration (instructions, model, and related fields).

create()

create(name: str, *, description: str | None = None, expected_output: str | None = None, instructions: List[str] | None = None, toolset: Toolset | None = None, model: str | None = None, connection_set: List[JsonObject] | List[Dict[str, Any]] | None = None, context_selections: List[JsonObject] | List[Dict[str, Any]] | None = None, interfaces: List[JsonObject] | List[Dict[str, Any]] | None = None, guardrails: List[str] | None = None) → ScopeDto

Create a new Modus scope in the organisation.

Parameters: guardrails – Runtime guardrail labels (for example "no-pii"). When set, the scope is created with these labels under the organisation default sharing rules. Omit (None) to create with no guardrails. ACL fields cannot be set from the SDK.

update()

update(scope_id: int | str, *, name: str | None = None, description: str | None = None, expected_output: str | None = None, instructions: List[str] | None = None, toolset: Toolset | None = None, model: str | None = None, connection_set: List[JsonObject] | List[Dict[str, Any]] | None = None, context_selections: List[JsonObject] | List[Dict[str, Any]] | None = None, interfaces: List[JsonObject] | List[Dict[str, Any]] | None = None, guardrails: List[str] | None = None, manager_id: str | None = None, evaluations: List[JsonObject] | List[Dict[str, Any]] | None = None, supervision_subordinate_descriptions: Dict[str, str] | None = None, update_mask: str | None = None) → ScopeDto

Update a Modus scope’s configuration. Only the fields you pass are changed. To clear a field, name it in update_mask (a comma-separated list of field names) and leave its argument unset — the server sets each masked field to null and leaves fields not named in the mask untouched.

Parameters: guardrails – Runtime guardrail labels to set on the scope. Fetches the current scope first and merges these labels into its access configuration (an extra get request). Omit (None) to leave guardrails unchanged. Pass [] to clear all guardrails.

deploy()

deploy(scope_id: int | str) → ScopeDto

Publish the current draft of a Modus scope.

Parameters: scope_id – Scope to publish.
Returns: The scope with its newly published configuration.

delete()

delete(scope_id: int | str) → None

Delete a Modus scope.

Parameters: scope_id – Scope to remove.

request_ownership_transfer()

request_ownership_transfer(scope_id: int | str, *, new_owner_user_id: str) → ScopeDto

Start transferring ownership of a scope to another organisation member.

cancel_ownership_transfer()

cancel_ownership_transfer(scope_id: int | str) → ScopeDto

Cancel a pending scope ownership transfer.

accept_ownership_transfer()

accept_ownership_transfer(scope_id: int | str) → ScopeDto

Accept a pending scope ownership transfer.

restore()

restore(scope_id: int | str) → ScopeDto

Restore a deleted scope.

patch_mcp_config()

patch_mcp_config(scope_id: int | str, *, mcp_config: Dict[str, Any]) → None

Update MCP server configuration for a scope.

get_variation()

get_variation(scope_id: int | str, *, variation_uid: str) → ScopeDto

Retrieve a historic version snapshot of a scope.

AsyncScopesResource

class AsyncScopesResource(http: AsyncHttpClient, config: ModusConfig, ops: ManagementScopesOperations = ManagementScopesOperations(list='ScopesController_list', get='ScopesController_get', create='ScopesController_create', update='ScopesController_update', deploy='ScopesController_deploy', delete='ScopesController_delete', restore='ScopesController_restore', request_ownership_transfer='ScopesController_requestOwnershipTransfer', cancel_ownership_transfer='ScopesController_cancelOwnershipTransfer', accept_ownership_transfer='ScopesController_acceptOwnershipTransfer', patch_mcp_config='ScopesController_patchMcpConfig', get_variation='ScopesController_getVariation', conversations=ScopeConversationsOperations(list='ScopeConversationsController_list', get='ScopeConversationsController_get'), memories=ScopeMemoriesOperations(list='ScopeMemoriesController_list', search='ScopeMemoriesController_search', update='ScopeMemoriesController_update', delete='ScopeMemoriesController_delete'), evaluations=ScopeEvaluationsOperations(get_config='EvaluationsController_getConfig', update_config='EvaluationsController_updateConfig', trigger_run='EvaluationsController_triggerRun', list_runs='EvaluationsController_listRuns', get_run='EvaluationsController_getRun')))

Bases: object

conversations()

conversations(scope_id: int | str) → AsyncScopeConversationsResource

Return the conversations sub-resource scoped to scope_id.

memories()

memories(scope_id: int | str) → AsyncScopeMemoriesResource

Return the memories sub-resource scoped to scope_id.

supervision()

supervision(scope_id: int | str) → AsyncScopeSupervisionResource

Return the supervision sub-resource scoped to scope_id.

list()

async list(*, page_size: int = 25, page_token: str | None = None, search: str | None = None, view: Literal['active', 'draft'] | None = None, manager_id: int | None = None) → AsyncPage[ScopeDto]

List all Modus scopes in the organisation.

Parameters:
- page_size – Maximum number of items to return (default 25).
- page_token – Token from a previous page’s next_page_token; omit for the first page.
- search – Case-insensitive substring filter on the scope name.
- view – Variation view — "active" (deployed) or "draft".
- manager_id – Return only scopes supervised by this manager scope id.

get()

async get(scope_id: int | str, *, view: Literal['active', 'draft'] | None = None) → ScopeDto

Retrieve a Modus scope with full configuration (instructions, model, and related fields).

create()

async create(name: str, *, description: str | None = None, expected_output: str | None = None, instructions: List[str] | None = None, toolset: Toolset | None = None, model: str | None = None, connection_set: List[JsonObject] | List[Dict[str, Any]] | None = None, context_selections: List[JsonObject] | List[Dict[str, Any]] | None = None, interfaces: List[JsonObject] | List[Dict[str, Any]] | None = None, guardrails: List[str] | None = None) → ScopeDto

Create a new Modus scope in the organisation.

Parameters: guardrails – Runtime guardrail labels (for example "no-pii"). When set, the scope is created with these labels under the organisation default sharing rules. Omit (None) to create with no guardrails. ACL fields cannot be set from the SDK.

update()

async update(scope_id: int | str, *, name: str | None = None, description: str | None = None, expected_output: str | None = None, instructions: List[str] | None = None, toolset: Toolset | None = None, model: str | None = None, connection_set: List[JsonObject] | List[Dict[str, Any]] | None = None, context_selections: List[JsonObject] | List[Dict[str, Any]] | None = None, interfaces: List[JsonObject] | List[Dict[str, Any]] | None = None, guardrails: List[str] | None = None, manager_id: str | None = None, evaluations: List[JsonObject] | List[Dict[str, Any]] | None = None, supervision_subordinate_descriptions: Dict[str, str] | None = None, update_mask: str | None = None) → ScopeDto

Parameters: guardrails – Runtime guardrail labels to set on the scope. Fetches the current scope first and merges these labels into its access configuration (an extra get request). Omit (None) to leave guardrails unchanged. Pass [] to clear all guardrails.

deploy()

async deploy(scope_id: int | str) → ScopeDto

Publish the current draft of a Modus scope. See the sync deploy for argument details.

delete()

async delete(scope_id: int | str) → None

Delete a Modus scope. See the sync delete for argument details.

request_ownership_transfer()

async request_ownership_transfer(scope_id: int | str, *, new_owner_user_id: str) → ScopeDto

Start transferring ownership of a scope to another organisation member.

cancel_ownership_transfer()

async cancel_ownership_transfer(scope_id: int | str) → ScopeDto

Cancel a pending scope ownership transfer.

accept_ownership_transfer()

async accept_ownership_transfer(scope_id: int | str) → ScopeDto

Accept a pending scope ownership transfer.

restore()

async restore(scope_id: int | str) → ScopeDto

Restore a deleted scope.

patch_mcp_config()

async patch_mcp_config(scope_id: int | str, *, mcp_config: Dict[str, Any]) → None

Update MCP server configuration for a scope.

get_variation()

async get_variation(scope_id: int | str, *, variation_uid: str) → ScopeDto

Retrieve a historic version snapshot of a scope.

ScopeConversationsResource

class ScopeConversationsResource(http: HttpClient, config: ModusConfig, scope_id: int | str, ops: ScopeConversationsOperations = ScopeConversationsOperations(list='ScopeConversationsController_list', get='ScopeConversationsController_get'))

Bases: object

list()

list(*, page_size: int = 25, page_token: str | None = None) → Page[ConversationListItemDto]

List conversation threads for this scope, newest first.

Parameters:
- page_size – Maximum number of items to return (default 25).
- page_token – Token from a previous page’s next_page_token; omit for the first page.

get()

get(thread_id: str) → ConversationDto

Retrieve a conversation thread with its full message history.

Parameters: thread_id – Conversation thread ID.

ScopeMemoriesResource

class ScopeMemoriesResource(http: HttpClient, config: ModusConfig, scope_id: int | str, ops: ScopeMemoriesOperations = ScopeMemoriesOperations(list='ScopeMemoriesController_list', search='ScopeMemoriesController_search', update='ScopeMemoriesController_update', delete='ScopeMemoriesController_delete'))

Bases: object

list()

list(*, page_size: int = 25, page_token: str | None = None, user_id: str | None = None) → Page[Memory]

List memories stored for this scope.

Parameters:
- page_size – Items per page (default 25).
- page_token – Token from a previous page’s next_page_token.
- user_id – Optional end-user scope when memories are scoped per user.

search()

search(request: MemorySearchRequest) → MemorySearchResult

Search this scope’s memories by natural-language query.

Parameters: request – Query text and optional user_id / limit.

update()

update(memory_id: str, update: MemoryUpdate, *, update_mask: str | None = None) → Memory

Update one memory. Requires manage permission on the scope.

Parameters:
- memory_id – Id from list or search.
- update – Fields to change (memory and/or metadata).
- update_mask – Optional comma-separated field names to update.

delete()

delete(memory_id: str) → None

Delete one memory (idempotent 204).

ScopeEvaluationsResource

class ScopeEvaluationsResource(http: HttpClient, config: ModusConfig, scope_id: int | str, ops: ScopeEvaluationsOperations = ScopeEvaluationsOperations(get_config='EvaluationsController_getConfig', update_config='EvaluationsController_updateConfig', trigger_run='EvaluationsController_triggerRun', list_runs='EvaluationsController_listRuns', get_run='EvaluationsController_getRun'))

Bases: object

get_config()

get_config() → EvaluationConfigDto

Return the evaluation configuration for this scope.

update_config()

update_config(update: UpdateEvaluationConfigDto) → EvaluationConfigDto

Update evaluation settings for this scope.

Parameters: update – Fields to change (schedule, test cases, etc.).
Returns: The updated evaluation configuration.

trigger_run()

trigger_run() → TriggerEvaluationRunResponseDto

Start an on-demand evaluation run for this scope.

Returns: Response with the new run id.

list_runs()

list_runs(*, page_size: int = 25, page_token: str | None = None) → Page[EvaluationRunDto]

List evaluation runs for this scope.

Parameters:
- page_size – Items per page (default 25).
- page_token – Token from a previous page’s next_page_token.
Returns: Page of evaluation runs.

get_run()

get_run(run_id: str) → EvaluationRunWithResultsDto

Retrieve one evaluation run with full results.

Parameters: run_id – Id from list_runs or trigger_run.
Returns: Run metadata and per-test-case results.

ScopeSupervisionResource

class ScopeSupervisionResource(http: HttpClient, config: ModusConfig, scope_id: int | str)

Bases: object

get()

get(*, view: Literal['active', 'draft'] | None = None) → SupervisionDto

Get this scope’s supervision configuration.

set()

set(supervision: SetSupervisionRequestDto) → SupervisionDto

Replace this scope’s subordinate scopes.

set_active()

set_active(supervision: SetSupervisionRequestDto) → SupervisionDto

Replace subordinate scopes on the active scope version.

​ScopesResource

​conversations()

​memories()

​evaluations()

​supervision()

​list()

​get()

​create()

​update()

​deploy()

​delete()

​request_ownership_transfer()

​cancel_ownership_transfer()

​accept_ownership_transfer()

​restore()

​patch_mcp_config()

​get_variation()

​AsyncScopesResource

​conversations()

​memories()

​supervision()

​list()

​get()

​create()

​update()

​deploy()

​delete()

​request_ownership_transfer()

​cancel_ownership_transfer()

​accept_ownership_transfer()

​restore()

​patch_mcp_config()

​get_variation()

​ScopeConversationsResource

​list()

​get()

​ScopeMemoriesResource

​list()

​search()

​update()

​delete()

​ScopeEvaluationsResource

​get_config()

​update_config()

​trigger_run()

​list_runs()

​get_run()

​ScopeSupervisionResource

​get()

​set()

​set_active()

ScopesResource

conversations()

memories()

evaluations()

supervision()

list()

get()

create()

update()

deploy()

delete()

request_ownership_transfer()

cancel_ownership_transfer()

accept_ownership_transfer()

restore()

patch_mcp_config()

get_variation()

AsyncScopesResource

conversations()

memories()

supervision()

list()

get()

create()

update()

deploy()

delete()

request_ownership_transfer()

cancel_ownership_transfer()

accept_ownership_transfer()

restore()

patch_mcp_config()

get_variation()

ScopeConversationsResource

list()

get()

ScopeMemoriesResource

list()

search()

update()

delete()

ScopeEvaluationsResource

get_config()

update_config()

trigger_run()

list_runs()

get_run()

ScopeSupervisionResource

get()

set()

set_active()