> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmodus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes

> Create, update, deploy, and configure scopes (mgmt.scopes).

### ScopesResource

```python
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()

```python
conversations(scope_id: int | str) → ScopeConversationsResource
```

Return the conversations sub-resource scoped to `scope_id`.

#### memories()

```python
memories(scope_id: int | str) → ScopeMemoriesResource
```

Return the memories sub-resource scoped to `scope_id`.

#### evaluations()

```python
evaluations(scope_id: int | str) → ScopeEvaluationsResource
```

Return the evaluations sub-resource scoped to `scope_id`.

#### supervision()

```python
supervision(scope_id: int | str) → ScopeSupervisionResource
```

Return the supervision sub-resource scoped to `scope_id`.

#### list()

```python
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()

```python
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()

```python
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()

```python
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()

```python
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()

```python
delete(scope_id: int | str) → None
```

Delete a Modus scope.

* Parameters:

  **scope\_id** – Scope to remove.

#### request\_ownership\_transfer()

```python
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()

```python
cancel_ownership_transfer(scope_id: int | str) → ScopeDto
```

Cancel a pending scope ownership transfer.

#### accept\_ownership\_transfer()

```python
accept_ownership_transfer(scope_id: int | str) → ScopeDto
```

Accept a pending scope ownership transfer.

#### restore()

```python
restore(scope_id: int | str) → ScopeDto
```

Restore a deleted scope.

#### patch\_mcp\_config()

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

Update MCP server configuration for a scope.

#### get\_variation()

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

Retrieve a historic version snapshot of a scope.

### AsyncScopesResource

```python
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()

```python
conversations(scope_id: int | str) → AsyncScopeConversationsResource
```

Return the conversations sub-resource scoped to `scope_id`.

#### memories()

```python
memories(scope_id: int | str) → AsyncScopeMemoriesResource
```

Return the memories sub-resource scoped to `scope_id`.

#### supervision()

```python
supervision(scope_id: int | str) → AsyncScopeSupervisionResource
```

Return the supervision sub-resource scoped to `scope_id`.

#### list()

```python
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()

```python
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()

```python
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()

```python
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
```

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()

```python
async deploy(scope_id: int | str) → ScopeDto
```

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

#### delete()

```python
async delete(scope_id: int | str) → None
```

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

#### request\_ownership\_transfer()

```python
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()

```python
async cancel_ownership_transfer(scope_id: int | str) → ScopeDto
```

Cancel a pending scope ownership transfer.

#### accept\_ownership\_transfer()

```python
async accept_ownership_transfer(scope_id: int | str) → ScopeDto
```

Accept a pending scope ownership transfer.

#### restore()

```python
async restore(scope_id: int | str) → ScopeDto
```

Restore a deleted scope.

#### patch\_mcp\_config()

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

Update MCP server configuration for a scope.

#### get\_variation()

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

Retrieve a historic version snapshot of a scope.

### ScopeConversationsResource

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

Bases: `object`

#### list()

```python
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()

```python
get(thread_id: str) → ConversationDto
```

Retrieve a conversation thread with its full message history.

* Parameters:

  **thread\_id** – Conversation thread ID.

### ScopeMemoriesResource

```python
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()

```python
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()

```python
search(request: MemorySearchRequest) → MemorySearchResult
```

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

* Parameters:

  **request** – Query text and optional `user_id` / `limit`.

#### update()

```python
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()

```python
delete(memory_id: str) → None
```

Delete one memory (idempotent 204).

### ScopeEvaluationsResource

```python
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()

```python
get_config() → EvaluationConfigDto
```

Return the evaluation configuration for this scope.

#### update\_config()

```python
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()

```python
trigger_run() → TriggerEvaluationRunResponseDto
```

Start an on-demand evaluation run for this scope.

* Returns:

  Response with the new run id.

#### list\_runs()

```python
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()

```python
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

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

Bases: `object`

#### get()

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

Get this scope’s supervision configuration.

#### set()

```python
set(supervision: SetSupervisionRequestDto) → SupervisionDto
```

Replace this scope’s subordinate scopes.

#### set\_active()

```python
set_active(supervision: SetSupervisionRequestDto) → SupervisionDto
```

Replace subordinate scopes on the active scope version.