magick_mind.resources.v1.mindspace

V1 mindspace resource implementation.

MindspaceResourceV1

class MindspaceResourceV1(BaseResource)

Mindspace resource client for V1 API.

Provides typed interface for managing mindspaces (organizational containers for chat conversations, corpus, and users).

Example:

Create a private mindspace

mindspace = await client.v1.magickspaces.create( name="My Workspace", type="private", description="Personal workspace", corpus_ids=["corp-123"] )

List all mindspaces

mindspaces = await client.v1.magickspaces.list(user_id="user-456")

Get messages from mindspace

messages = await client.v1.magickspaces.get_messages("mind-123", limit=50)

MindspaceResourceV1.create

async def create(name: str,
                 type: MindSpaceType,
                 description: Optional[str] = None,
                 project_id: Optional[str] = None,
                 corpus_ids: Optional[list[str]] = None,
                 participant_ids: Optional[list[str]] = None) -> MindSpace

Create a new mindspace.

Arguments:

• name - Mindspace name (max 100 characters)
• type - Mindspace type - either "PRIVATE" or "GROUP"
• description - Optional description (max 256 characters)
• project_id - Optional associated project ID
• corpus_ids - Optional list of corpus IDs to attach
• participant_ids - Optional list of participant IDs to grant access

Returns:

MindSpace

Raises:

• HTTPError - If the API request fails
• ValidationError - If parameters are invalid

Example:

Create a group mindspace

mindspace = await client.v1.magickspaces.create( name="Engineering Team", type="GROUP", description="Team collaboration space", corpus_ids=["corp-1", "corp-2"], participant_ids=["user-1", "user-2"] ) print(f"Created mindspace: {mindspace.id}")

MindspaceResourceV1.get

async def get(mindspace_id: str) -> MindSpace

Get a mindspace by ID.

Arguments:

• mindspace_id - Mindspace ID to retrieve

Returns:

MindSpace

Raises:

• HTTPError - If the API request fails or mindspace not found

Example:

mindspace = await client.v1.magickspaces.get("mind-123")

• print(f"Mindspace - {mindspace.name}")
• print(f"Type - {mindspace.type}")
• print(f"Corpus - {mindspace.corpus_ids}")

MindspaceResourceV1.list

async def list(participant_id: Optional[str] = None,
               project_id: Optional[str] = None,
               type: Optional[MindSpaceType] = None,
               name: Optional[str] = None,
               cursor: Optional[str] = None,
               limit: Optional[int] = None,
               order: Optional[str] = None) -> GetMindSpaceListResponse

List mindspaces, optionally filtered by various parameters.

Arguments:

• participant_id - Optional participant ID to filter mindspaces
• project_id - Optional project ID to filter mindspaces
• type - Optional mindspace type filter ("PRIVATE" or "GROUP")
• name - Optional name filter
• cursor - Optional pagination cursor
• limit - Optional maximum number of results to return
• order - Optional sort order

Returns:

GetMindSpaceListResponse with list of mindspaces

Raises:

• HTTPError - If the API request fails

Example:

List all mindspaces for a participant

response = await client.v1.magickspaces.list(participant_id="user-456") for ms in response.mindspaces: print(f"- {ms.name} ({ms.type})")

MindspaceResourceV1.update

async def update(mindspace_id: str,
                 name: str,
                 description: Optional[str] = None,
                 project_id: Optional[str] = None,
                 corpus_ids: Optional[list[str]] = None,
                 participant_ids: Optional[list[str]] = None) -> MindSpace

Update an existing mindspace.

Arguments:

• mindspace_id - Mindspace ID to update
• name - Updated mindspace name (max 100 characters)
• description - Updated description (max 256 characters)
• project_id - Updated associated project ID
• corpus_ids - Updated list of corpus IDs
• participant_ids - Updated list of participant IDs

Returns:

MindSpace

Raises:

• HTTPError - If the API request fails or mindspace not found
• ValidationError - If parameters are invalid

Example:

Update mindspace to add more corpus

mindspace = await client.v1.magickspaces.update( mindspace_id="mind-123", name="Engineering Team", corpus_ids=["corp-1", "corp-2", "corp-3"] )

• print(f"Updated - {mindspace.corpus_ids}")

MindspaceResourceV1.delete

async def delete(mindspace_id: str) -> None

Delete a mindspace.

Arguments:

• mindspace_id - Mindspace ID to delete

Raises:

• HTTPError - If the API request fails or mindspace not found

Example:

await client.v1.magickspaces.delete("mind-123") print("Mindspace deleted successfully")

MindspaceResourceV1.get_messages

async def get_messages(
        mindspace_id: str,
        *,
        cursor: Optional[str] = None,
        limit: Optional[int] = None,
        order: Optional[str] = None) -> MindspaceMessagesResponse

Fetch chat messages from a mindspace with cursor-based pagination.

Arguments:

• mindspace_id - Mindspace to fetch messages from
• cursor - Pagination cursor (from paging.cursors.after or .before)
• limit - Maximum number of messages to return
• order - Sort order — "asc" or "desc" (default: asc)

Returns:

MindspaceMessagesResponse with messages and pagination cursors

Raises:

• HTTPError - If the API request fails

Example:

Get latest messages

messages = await client.v1.magickspaces.get_messages("mind-123") for msg in messages.chat_histories:

• print(f"{msg.sent_by_user_id} - {msg.content}")

  Next page

  if messages.has_more: page2 = await client.v1.magickspaces.get_messages( "mind-123", cursor=messages.next_after_id, )

MindspaceResourceV1.send_message

async def send_message(mindspace_id: str,
                       *,
                       content: str,
                       sender_id: str,
                       reply_to_message_id: Optional[str] = None,
                       artifact_ids: Optional[list[str]] = None,
                       message_type: str = "TEXT",
                       broadcast: bool = True) -> ChatHistoryItem

Send a message to a mindspace.

Arguments:

• mindspace_id - Mindspace ID to send message to
• content - Message content text
• sender_id - ID of the user sending the message
• reply_to_message_id - Optional ID of message being replied to
• artifact_ids - Optional list of artifact IDs to attach
• message_type - Message type (default: "TEXT")
• broadcast - Whether to broadcast via Centrifugo (default: True)

Returns:

ChatHistoryItem for the created message

Raises:

• ProblemDetailsException - If the request fails

Example:

msg = await client.v1.magickspaces.send_message( "mind-123", content="Hello, world!", sender_id="user-456", ) print(f"Sent message {msg.id}")

MindspaceResourceV1.add_participants

async def add_participants(mindspace_id: str,
                           participant_ids: list[str]) -> MindSpace

Add participants to an existing mindspace.

Arguments:

• mindspace_id - Mindspace ID to add participants to
• participant_ids - List of participant IDs to add to the mindspace

Returns:

MindSpace with updated participant list

Raises:

• HTTPError - If the API request fails or mindspace not found
• ValidationError - If parameters are invalid

Example:

Add participants to a group mindspace

mindspace = await client.v1.magickspaces.add_participants( mindspace_id="mind-123", participant_ids=["user-3", "user-4"] ) print(f"Updated participants: {mindspace.participant_ids}")

MindspaceResourceV1.add_users

async def add_users(mindspace_id: str, user_ids: list[str]) -> MindSpace

Add users to an existing mindspace.

.. deprecated:: Use :meth:add_participants instead. This method will be removed in a future version.

Arguments:

• mindspace_id - Mindspace ID to add users to
• user_ids - List of user IDs to add to the mindspace

Returns:

MindSpace with updated participant list

MindspaceResourceV1.prepare_context

async def prepare_context(
        mindspace_id: str,
        participant_id: str,
        chat_history: Optional[ChatHistoryParams] = None,
        corpus: Optional[CorpusParams] = None,
        pelican: Optional[FetcherParams] = None,
        api_key: Optional[str] = None) -> ContextPrepareResponse

Retrieve multiple memory sources for a mindspace in a single call.

Sources are queried in parallel on the server and bundled into one response.

Arguments:

• mindspace_id - Mindspace ID
• participant_id - Participant ID (required)
• chat_history - Chat history params (limit)
• corpus - Corpus search params (query)
• pelican - Pelican episodic memory params (query). Requires api_key.
• api_key - API key required when using pelican fetcher (sent as x-api-key header)

Returns:

ContextPrepareResponse

MindspaceResourceV1.get_livekit_token

async def get_livekit_token(mindspace_id: str,
                            participant_id: str) -> LivekitTokenResponse

Get a LiveKit access token for joining the mindspace room.

Arguments:

• mindspace_id - Mindspace ID (used as room name)
• participant_id - Participant identity for the token

Returns:

LivekitTokenResponse with token and URL

MindspaceResourceV1.livekit_join

async def livekit_join(mindspace_id: str,
                       participant_ids: list[str]) -> LivekitJoinResponse

Signal agents to join the LiveKit room for this mindspace.

Arguments:

• mindspace_id - Mindspace ID
• participant_ids - List of participant IDs to signal

Returns:

LivekitJoinResponse with list of signaled participants