magick_mind.resources.v1.persona

V1 persona resource implementation.

PersonaResourceV1

class PersonaResourceV1(BaseResource)

Persona resource client for V1 API.

Provides persona CRUD, blueprint-based creation, and version management.

Example:

Create a persona

persona = await client.v1.persona.create( name="Aria", role="assistant", )

Create from blueprint

result = await client.v1.persona.create_from_blueprint( blueprint_id="bp-123", name="Aria", role="assistant", ) print(result.persona.id, result.version.version)

Version management

version = await client.v1.persona.create_version( persona_id="p-123", version="1.1", ) active = await client.v1.persona.get_active_version("p-123")

PersonaResourceV1.create

async def create(name: str,
                 role: str,
                 artifact_id: Optional[str] = None,
                 traits: Optional[list[str]] = None,
                 tones: Optional[list[str]] = None,
                 background_story: str = "") -> Persona

Create a new persona.

Arguments:

• name - Persona name
• role - Persona role
• artifact_id - Optional associated artifact ID
• traits - Optional list of trait names
• tones - Optional list of tone names
• background_story - Optional background story

Returns:

Persona

PersonaResourceV1.get

async def get(persona_id: str) -> Persona

Get a persona by ID.

Arguments:

• persona_id - Persona ID

Returns:

Persona

PersonaResourceV1.update

async def update(persona_id: str,
                 name: str,
                 role: str,
                 artifact_id: Optional[str] = None,
                 traits: Optional[list[str]] = None,
                 tones: Optional[list[str]] = None,
                 background_story: str = "") -> Persona

Update a persona.

Arguments:

• persona_id - Persona ID
• name - Updated name
• role - Updated role
• artifact_id - Optional updated artifact ID
• traits - Updated traits list
• tones - Updated tones list
• background_story - Updated background story

Returns:

Persona

PersonaResourceV1.delete

async def delete(persona_id: str) -> None

Delete a persona.

Arguments:

• persona_id - Persona ID

PersonaResourceV1.prepare

async def prepare(persona_id: str,
                  *,
                  user_id: Optional[str] = None) -> PreparePersonaResponse

Prepare a persona's system prompt.

Resolves the persona's traits, active version constraints, and optional user-specific context into a ready-to-use system prompt string.

Arguments:

• persona_id - Persona ID
• user_id - Optional user ID for user-specific prompt context

Returns:

PreparePersonaResponse with the system_prompt string

PersonaResourceV1.create_from_blueprint

async def create_from_blueprint(
        blueprint_id: str,
        name: str,
        role: str,
        background_story: Optional[str] = None,
        artifact_id: Optional[str] = None,
        trait_overrides: Optional[list[TraitConstraint]] = None,
        additional_traits: Optional[list[TraitConstraint]] = None,
        remove_traits: Optional[list[str]] = None,
        growth_override: Optional[GrowthConfig] = None,
        dyadic_override: Optional[DyadicConfig] = None) -> PersonaWithVersion

Create a persona from a blueprint with optional overrides.

Arguments:

• blueprint_id - Source blueprint ID
• name - Persona name
• role - Persona role
• background_story - Optional background story
• artifact_id - Optional artifact ID
• trait_overrides - Optional trait constraint overrides
• additional_traits - Optional additional trait constraints
• remove_traits - Optional trait refs to remove
• growth_override - Optional growth config override
• dyadic_override - Optional dyadic config override

Returns:

PersonaWithVersion containing both the persona and its initial version

PersonaResourceV1.create_version

async def create_version(
        persona_id: str,
        version: str,
        constraints: Optional[list[TraitConstraint]] = None,
        growth: Optional[GrowthConfig] = None,
        dyadic: Optional[DyadicConfig] = None) -> PersonaVersion

Create a new version for a persona.

Arguments:

• persona_id - Persona ID
• version - Version string
• constraints - Optional trait constraints
• growth - Optional growth config
• dyadic - Optional dyadic config

Returns:

PersonaVersion

PersonaResourceV1.list_versions

async def list_versions(
        persona_id: str,
        cursor: Optional[str] = None,
        limit: Optional[int] = None) -> ListPersonaVersionsResponse

List all versions for a persona.

Arguments:

• persona_id - Persona ID
• cursor - Pagination cursor
• limit - Maximum number of results

Returns:

ListPersonaVersionsResponse with data and paging

PersonaResourceV1.get_version

async def get_version(persona_id: str, version: str) -> PersonaVersion

Get a specific version by version string.

Arguments:

• persona_id - Persona ID
• version - Version string

Returns:

PersonaVersion

PersonaResourceV1.get_active_version

async def get_active_version(persona_id: str) -> PersonaVersion

Get the currently active version.

Arguments:

• persona_id - Persona ID

Returns:

PersonaVersion (the active one)

PersonaResourceV1.set_active_version

async def set_active_version(persona_id: str, version: str) -> Persona

Set a version as active.

Arguments:

• persona_id - Persona ID
• version - Version ID to activate

Returns:

Persona with updated active_version