Python API

The complete BasePersona API, generated from source and separated by contract level:

• Required — you MUST implement these (the class is abstract without them).

• Recommended — you SHOULD implement these; a default exists, but most personas override them.

• Optional — you MAY implement these; a safe default is used otherwise.

• Available to subclasses — provided by BasePersona for your persona to call; you may override them.

• Available to consumers — provided by BasePersona for consumers (the PersonaManager and other extensions) to call on a persona; you should generally not override them.

Each member’s level is declared in the code (via the @mark_required / @mark_recommended / @mark_optional / @mark_subclass_api / @mark_consumer_api documentation markers in jupyter_ai_persona_manager.doc_markers) and a CI check keeps every member marked, so this classification can’t drift from the code. Every entry shows its signature, type hints, a contract badge, and a [source] link to the exact lines on GitHub.

class jupyter_ai_persona_manager.BasePersona(*args: t.Any, **kwargs: t.Any)

Abstract base class that defines a persona when implemented.

Required

MUST be implemented — the class is abstract without these.

BasePersona.defaults

[Required] MUST be implemented by every persona.

Returns a PersonaDefaults data model that represents the default settings of this persona.

This is an abstract method that must be implemented by subclasses.

abstractmethod async BasePersona.process_message(message: Message) → None

[Required] MUST be implemented by every persona.

Processes a new message. This method exclusively defines how new messages are handled by a persona, and should be considered the “main entry point” to this persona. Reading chat history and streaming a reply can be done through method calls to self.ychat. See JupyternautPersona for a reference implementation on how to do so.

This is an abstract method that must be implemented by subclasses.

Recommended

SHOULD be implemented — a default exists, but most personas override these.

async BasePersona.cancel_response() → None

[Recommended] SHOULD be implemented; most personas override the default.

Stops this persona’s in-progress response, if any. Called when the user interrupts the persona from the chat UI.

This is the counterpart to process_message: it should halt whatever that method set in motion (a model stream, an agent turn, pending tool calls) so the persona stops writing to the chat promptly. stream_message already clears the is_writing awareness flag when it unwinds, so a subclass typically just needs to interrupt its own backend here.

Optional: the default implementation is a no-op, for personas that have nothing cancellable or complete their responses synchronously. A persona that streams or runs a long-lived turn (e.g. an ACP agent) overrides this to actually interrupt it.

Only invoked for a persona that’s currently processing — the cancel handler gates on that — so an override can assume a response is in flight. This matters because some backends treat a cancel with no active response as an error (e.g. ACP defines session/cancel only for an ongoing prompt turn).

async BasePersona.shutdown() → None

[Recommended] SHOULD be implemented; most personas override the default.

Shuts the persona down. This method should:

• Halt all background tasks started by this instance.

• Remove the persona from the chat awareness

This method will be called when /refresh-personas is run, and may be called when the server is shutting down or when a chat session is closed.

Subclasses may need to override this method to add custom shutdown logic. The override should generally call super().shutdown() first before running custom shutdown logic.

Optional

MAY be implemented — a safe default covers personas that don’t need these.

async BasePersona.handle_uncaught_exception(exc: Exception) → None

[Optional] MAY be implemented; a safe default is used otherwise.

Called by PersonaManager when process_message() raises an unhandled exception. Override this method to customize error reporting.

The default implementation sends a message to the chat with the error type and message visible in the summary, and the full traceback hidden under a collapsible <details> element.

async BasePersona.update_model(model_id: str) → None

[Optional] MAY be implemented; a safe default is used otherwise.

Switch this persona to the model identified by model_id.

async BasePersona.update_model_settings(settings: dict[str, str | None]) → None

[Optional] MAY be implemented; a safe default is used otherwise.

Apply the given model settings (e.g. context size), keyed by ID.

async BasePersona.update_settings(settings: dict[str, str | None]) → None

[Optional] MAY be implemented; a safe default is used otherwise.

Apply the given general settings (e.g. mode, effort level), keyed by ID. Separate from model settings.

Available to subclasses

Provided by the base class for a persona to call from inside itself; may be overridden.

BasePersona.system_prompt

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the system prompt used by this persona. Provided by BasePersona.

NOTE/TODO: This currently just returns the value set in self.defaults. This is set here because we may require this field to be configurable for all personas in the future.

BasePersona.event_loop

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

The asyncio event loop running this process.

async BasePersona.stream_message(reply_stream: AsyncIterator) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Takes an async iterator, dubbed the ‘reply stream’, and streams it to a new message by this persona in the YChat. The async iterator may yield either strings or litellm.ModelResponseStream objects. Details:

• Creates a new message upon receiving the first chunk from the reply stream, then continuously updates it until the stream is closed.

• Automatically manages its awareness state to show writing status.

• Triggers mention detection after streaming completes, allowing personas to mention each other in their responses.

BasePersona.send_message(body: str) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Sends a new message to the chat from this persona.

BasePersona.get_chat_path(relative: bool = False) → str

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the absolute path of the chat file assigned to this persona.

To get a path relative to the ContentsManager root directory, call this method with relative=True.

BasePersona.get_chat_dir() → str

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the absolute path to the parent directory of the chat file assigned to this persona.

BasePersona.get_dotjupyter_dir() → str | None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the path to the .jupyter directory for the current chat.

BasePersona.get_workspace_dir() → str

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the path to the workspace directory for the current chat.

BasePersona.get_mcp_settings() → McpSettings | None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Returns the MCP config for the current chat.

BasePersona.get_model_configuration() → ModelConfiguration

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the current model, model settings, and all options for both.

BasePersona.get_setting_configurations() → list[SettingConfiguration]

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the current value and all options for each general setting.

BasePersona.get_model() → str | None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the current model ID, or None if using the default.

BasePersona.get_model_settings() → dict[str, str | None]

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the current model settings, keyed by setting ID.

BasePersona.get_settings() → dict[str, str | None]

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the current general settings, keyed by setting ID. This is separate from the model settings returned by get_model_settings().

BasePersona.get_usage() → Usage

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the usage currently reported by this persona.

BasePersona.get_slash_commands() → list[CommandOption]

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Return the slash commands currently advertised by this persona.

BasePersona.report_model_configuration(model: ModelConfiguration) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Publish the persona’s model configuration (current model, model options, and model settings). A persona calls this once it knows its models (e.g. an ACP persona on session create/load).

BasePersona.report_settings_configuration(settings: list[SettingConfiguration]) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Publish the persona’s general (non-model) settings configuration.

BasePersona.report_usage(usage: Usage, *, append: bool = False) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Merge usage into the reported usage and rebroadcast. Only the fields set on usage are touched, so a source that reports context and tokens in separate calls composes into one Usage.

append=False (default): each provided field replaces the stored value. Use for sources that already report totals — ACP reports cumulative counts and a live context snapshot, so replace is correct, and it’s what we prioritize.

append=True: each provided field is added to the stored value, for sources that emit per-turn deltas. Snapshot fields (context_*) should not be sent this way — you don’t sum window sizes.

BasePersona.report_slash_commands(commands: list[CommandOption]) → None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Publish the advertised slash commands.

BasePersona.process_attachments(message: Message) → str | None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Process file attachments in the message and return their content as a string.

BasePersona.resolve_attachment_to_path(attachment_id: str) → str | None

[Available to subclasses] Provided by BasePersona for a persona to call; may be overridden.

Resolve an attachment ID to its file path using multiple strategies.

Available to consumers

Provided by the base class for consumers (e.g. the PersonaManager) to call on a persona; generally not overridden.

BasePersona.processing

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Whether this persona is currently processing at least one message — i.e. a process_message() call is in flight. Use this to avoid interrupting a persona that has no response to cancel (see cancel_response).

BasePersona.track_processing()

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Context manager that marks this persona as processing for its duration, so processing reflects an in-flight response. PersonaManager wraps each process_message() call in this; the count is restored even if the call raises. A count (not a bool) because a persona may process several messages concurrently.

BasePersona.id

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Returns a static & unique ID for this persona. This sets the username field in the data model returned by self.as_user().

The ID is guaranteed to follow the format jupyter-ai-personas::<package-name>::<persona-class-name>. The prefix allows consumers to easily distinguish AI personas from human users.

If a package provides multiple personas, their class names must be different to ensure that their IDs are unique.

BasePersona.name

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Returns the name shown on messages from this persona in the chat. This sets the name and display_name fields in the data model returned by self.as_user(). Provided by BasePersona.

NOTE/TODO: This currently just returns the value set in self.defaults. This is set here because we may require this field to be configurable for all personas in the future.

BasePersona.avatar_path

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Returns the API URL route that serves the avatar for this persona.

The avatar is served at {base_url}api/ai/avatars/{id} where the ID is the unique persona identifier. This ensures that each persona has a unique avatar URL without exposing filesystem paths.

The base_url is obtained from the PersonaManager and ensures the URL works correctly in both JupyterLab standalone and JupyterHub environments.

The actual avatar file path is specified in defaults.avatar_path as an absolute filesystem path to an image file (SVG, PNG, or JPG) within the persona’s package or module.

This sets the avatar_url field in the data model returned by self.as_user(). Provided by BasePersona.

BasePersona.as_user() → User

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Returns the jupyterlab_chat.models:User model that represents this persona in the chat. This model also includes all attributes from jupyter_server.auth:JupyterUser, the user model returned by the IdentityProvider in Jupyter Server.

This method is provided by BasePersona.

BasePersona.as_user_dict() → dict[str, Any]

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Returns self.as_user() as a Python dictionary. This method is provided by BasePersona.

async BasePersona.apply_model_spec(spec: ModelSpec) → None

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Apply a user’s specified model and model settings, then record the new current values on the awareness slot (which rebroadcasts).

A None model ID or a None setting value means “use the persona’s current value”, so it is skipped. The persona’s backend is only asked to switch (and the change only broadcast) when a specified value actually differs from the current one.

async BasePersona.apply_settings_spec(spec: dict[str, str | None]) → None

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Apply a user’s specified general settings, then record the new current values on the awareness slot (which rebroadcasts).

A None value for a setting means “use the persona’s current value”, so it is skipped. The persona’s backend is only asked to switch (and the change only broadcast) when a specified value actually differs from the current one.

async BasePersona.apply_specs_in_message(message: Message) → None

[Available to consumers] Provided by BasePersona for consumers to call; should not be overridden.

Apply the model and settings specification carried on a message’s metadata before the message is processed. Called by the PersonaManager for every routed message, so a persona picks up per-message selections without each process_message() implementation having to do so itself.

A message with no relevant metadata is a no-op.

Data models

The Pydantic models a persona works with, rendered from source with their fields, types, defaults, and constraints:

pydantic model jupyter_ai_persona_manager.PersonaDefaults

Data structure that represents the default settings of a persona. Each persona must define some basic default settings, like its name.

Each of these settings can be overwritten through the settings UI.

Show JSON schema

{
   "title": "PersonaDefaults",
   "description": "Data structure that represents the default settings of a persona. Each persona\nmust define some basic default settings, like its name.\n\nEach of these settings can be overwritten through the settings UI.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "title": "Description",
         "type": "string"
      },
      "avatar_path": {
         "title": "Avatar Path",
         "type": "string"
      },
      "system_prompt": {
         "title": "System Prompt",
         "type": "string"
      },
      "slash_commands": {
         "default": [
            "*"
         ],
         "items": {
            "type": "string"
         },
         "title": "Slash Commands",
         "type": "array",
         "uniqueItems": true
      },
      "model_uid": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Model Uid"
      }
   },
   "required": [
      "name",
      "description",
      "avatar_path",
      "system_prompt"
   ]
}

Fields:

• avatar_path (str)

• description (str)

• model_uid (str | None)

• name (str)

• slash_commands (set[str])

• system_prompt (str)

field avatar_path: str [Required]

field description: str [Required]

field model_uid: str | None = None

field name: str [Required]

field slash_commands: set[str] = {'*'}

field system_prompt: str [Required]

pydantic model jupyter_ai_persona_manager.ModelConfiguration

The persona’s current model, its options, and its model settings.

Show JSON schema

{
   "title": "ModelConfiguration",
   "description": "The persona's current model, its options, and its model settings.",
   "type": "object",
   "properties": {
      "current": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Current"
      },
      "options": {
         "items": {
            "$ref": "#/$defs/ModelOption"
         },
         "title": "Options",
         "type": "array"
      },
      "settings": {
         "items": {
            "$ref": "#/$defs/SettingConfiguration"
         },
         "title": "Settings",
         "type": "array"
      }
   },
   "$defs": {
      "ModelOption": {
         "description": "One selectable model.",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Name"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            }
         },
         "required": [
            "id"
         ],
         "title": "ModelOption",
         "type": "object"
      },
      "SettingConfiguration": {
         "description": "A single setting: its current value and all available options.\n\nUsed both for model settings (rendered next to the model picker) and for\ngeneral settings (rendered separately). The list order controls UI order.",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "current": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Current"
            },
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Name"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            },
            "options": {
               "items": {
                  "$ref": "#/$defs/SettingOption"
               },
               "title": "Options",
               "type": "array"
            }
         },
         "required": [
            "id"
         ],
         "title": "SettingConfiguration",
         "type": "object"
      },
      "SettingOption": {
         "description": "One selectable value for a setting.",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Name"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            }
         },
         "required": [
            "id"
         ],
         "title": "SettingOption",
         "type": "object"
      }
   }
}

Fields:

• current (str | None)

• options (list[jupyter_ai_persona_manager.awareness_models.ModelOption])

• settings (list[jupyter_ai_persona_manager.awareness_models.SettingConfiguration])

field current: str | None = None

The current model ID, or None to indicate the persona’s default.

field options: list[ModelOption] [Optional]

The models the persona offers, in display order.

field settings: list[SettingConfiguration] [Optional]

Settings that should render near the model picker (ACP model_config).

pydantic model jupyter_ai_persona_manager.ModelOption

One selectable model.

Show JSON schema

{
   "title": "ModelOption",
   "description": "One selectable model.",
   "type": "object",
   "properties": {
      "id": {
         "title": "Id",
         "type": "string"
      },
      "name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Name"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Description"
      }
   },
   "required": [
      "id"
   ]
}

Fields:

• description (str | None)

• id (str)

• name (str | None)

field description: str | None = None

Optional longer description shown alongside the model in the picker.

field id: str [Required]

The model’s unique identifier, used when selecting it (e.g. via ModelSpec).

field name: str | None = None

Human-readable label for the model; falls back to id when None.

pydantic model jupyter_ai_persona_manager.SettingConfiguration

A single setting: its current value and all available options.

Used both for model settings (rendered next to the model picker) and for general settings (rendered separately). The list order controls UI order.

Show JSON schema

{
   "title": "SettingConfiguration",
   "description": "A single setting: its current value and all available options.\n\nUsed both for model settings (rendered next to the model picker) and for\ngeneral settings (rendered separately). The list order controls UI order.",
   "type": "object",
   "properties": {
      "id": {
         "title": "Id",
         "type": "string"
      },
      "current": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Current"
      },
      "name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Name"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Description"
      },
      "options": {
         "items": {
            "$ref": "#/$defs/SettingOption"
         },
         "title": "Options",
         "type": "array"
      }
   },
   "$defs": {
      "SettingOption": {
         "description": "One selectable value for a setting.",
         "properties": {
            "id": {
               "title": "Id",
               "type": "string"
            },
            "name": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Name"
            },
            "description": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "title": "Description"
            }
         },
         "required": [
            "id"
         ],
         "title": "SettingOption",
         "type": "object"
      }
   },
   "required": [
      "id"
   ]
}

Fields:

• current (str | None)

• description (str | None)

• id (str)

• name (str | None)

• options (list[jupyter_ai_persona_manager.awareness_models.SettingOption])

field current: str | None = None

The current value, or None to indicate the persona’s default.

field description: str | None = None

Optional longer description explaining what the setting controls.

field id: str [Required]

ID of the setting, e.g. “agent_mode”.

field name: str | None = None

Human-readable label for the setting; falls back to id when None.

field options: list[SettingOption] [Optional]

The selectable values for this setting, in display order.

pydantic model jupyter_ai_persona_manager.SettingOption

One selectable value for a setting.

Show JSON schema

{
   "title": "SettingOption",
   "description": "One selectable value for a setting.",
   "type": "object",
   "properties": {
      "id": {
         "title": "Id",
         "type": "string"
      },
      "name": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Name"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Description"
      }
   },
   "required": [
      "id"
   ]
}

Fields:

• description (str | None)

• id (str)

• name (str | None)

field description: str | None = None

Optional longer description shown alongside the option in the picker.

field id: str [Required]

The option’s unique identifier, used as the selected value for its setting.

field name: str | None = None

Human-readable label for the option; falls back to id when None.

pydantic model jupyter_ai_persona_manager.Usage

Token and cost usage reported by a persona for the current session.

Show JSON schema

{
   "title": "Usage",
   "description": "Token and cost usage reported by a persona for the current session.",
   "type": "object",
   "properties": {
      "context_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Context Tokens"
      },
      "context_size": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Context Size"
      },
      "context_percent": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Context Percent"
      },
      "input_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Input Tokens"
      },
      "output_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Output Tokens"
      },
      "cached_read_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Cached Read Tokens"
      },
      "cached_write_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Cached Write Tokens"
      },
      "thought_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Thought Tokens"
      },
      "total_tokens": {
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Total Tokens"
      },
      "cost_amount": {
         "anyOf": [
            {
               "type": "number"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Cost Amount"
      },
      "cost_currency": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Cost Currency"
      }
   }
}

Fields:

• cached_read_tokens (int | None)

• cached_write_tokens (int | None)

• context_percent (float | None)

• context_size (int | None)

• context_tokens (int | None)

• cost_amount (float | None)

• cost_currency (str | None)

• input_tokens (int | None)

• output_tokens (int | None)

• thought_tokens (int | None)

• total_tokens (int | None)

field cached_read_tokens: int | None = None

Cumulative count of tokens read from the prompt cache this session.

field cached_write_tokens: int | None = None

Cumulative count of tokens written to the prompt cache this session.

field context_percent: float | None = None

Context fill as a bare percentage (0-100), the fallback for agents that report only a percentage with no token counts (e.g. kiro-cli). Precedence contract for consumers: when context_tokens/context_size are present, derive the percentage from them and ignore this field; read this field only when they are absent.

field context_size: int | None = None

Total context-window size. See context_tokens.

field context_tokens: int | None = None

Tokens currently in the context window. Part of the live context-window snapshot: unlike the cumulative counters below, context_tokens and context_size can decrease during a session (e.g. after the agent compacts context).

field cost_amount: float | None = None

Cumulative session cost, expressed in cost_currency.

field cost_currency: str | None = None

The currency of cost_amount: an ISO 4217 code (e.g. “USD”) or, for agents that meter in their own unit, that unit’s plural name (e.g. “credits”).

field input_tokens: int | None = None

Cumulative count of input tokens for the session.

field output_tokens: int | None = None

Cumulative count of output tokens for the session.

field thought_tokens: int | None = None

Cumulative count of reasoning (“thinking”) tokens for the session.

field total_tokens: int | None = None

Cumulative count of all tokens for the session.

pydantic model jupyter_ai_persona_manager.CommandOption

One slash command advertised by a persona.

Show JSON schema

{
   "title": "CommandOption",
   "description": "One slash command advertised by a persona.",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "description": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Description"
      }
   },
   "required": [
      "name"
   ]
}

Fields:

• description (str | None)

• name (str)

field description: str | None = None

Optional short description of what the command does, shown in the UI.

field name: str [Required]

The command name, including the leading “/”, e.g. “/compact”.

pydantic model jupyter_ai_persona_manager.ModelSpec

A user’s model selection, carried on outgoing message metadata.

id is the selected model ID, or None to keep the persona’s current model. settings maps model-setting IDs to a selected option ID, or None to keep the current value for that setting.

Show JSON schema

{
   "title": "ModelSpec",
   "description": "A user's model selection, carried on outgoing message metadata.\n\n`id` is the selected model ID, or None to keep the persona's current model.\n`settings` maps model-setting IDs to a selected option ID, or None to keep\nthe current value for that setting.",
   "type": "object",
   "properties": {
      "id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "title": "Id"
      },
      "settings": {
         "additionalProperties": {
            "anyOf": [
               {
                  "type": "string"
               },
               {
                  "type": "null"
               }
            ]
         },
         "title": "Settings",
         "type": "object"
      }
   }
}

Fields:

• id (str | None)

• settings (dict[str, str | None])

field id: str | None = None

The selected model ID, or None to keep the persona’s current model.

field settings: dict[str, str | None] [Optional]

Maps each model-setting ID to its selected option ID, or to None to keep that setting’s current value.