Skip to content
Back to top
View this page

# mindroot.coreplugins.chat package

## Submodules

## mindroot.coreplugins.chat.commands module

async mindroot.coreplugins.chat.commands.converse_with_agent(agent_name: str, sub_log_id: str, first_message: str, contextual_info: str, exit_criteria: str, context=None)

  IMPORTANT: Wait for the system to return the sub_log_id from the initiate_agent_session() command before using this command. Have a conversation with an agent in an existing chat session. .. note:

      Do not use this command again to send more messages to the agent.
      Again, IMPORTANT: do NOT use this command from within a subconversation.
      You only issue this command ONCE, then the conversation occurs in another subcontext.

  Parameters: agent_name - String. The name of the agent to converse with. sub_log_id - String. The log_id of the existing chat session with a secondary agent.

  first_message - String. The first message to the agent. contextual_info - String. Relevant details that may come up. exit_criteria - String. The criteria for ending the conversation.

  Return: String. Contains a concise summary of relevant details of conversation.

async mindroot.coreplugins.chat.commands.delegate_task(instructions: str, agent_name, log_id=None, retries=3, context=None)

  Delegate a task to another agent.

  Example:

  { “delegate_task”: { “log_id”: “poem.moon.03_22_2024.4PM.1”, “instructions”: “Write a poem about the moon”, “agent_name”: “poet” } }

  Note: do not specify any other arguments than those in the example. In particular, ‘context’ is not a valid argument!

  log_id is optional, if you specify it you must use something unique.

  You can also let the system assign log_id automatically:

  Example:

  { “delegate_task”: { “instructions”: “Write a poem about the moon”, “agent_name”: “poet” } }

async mindroot.coreplugins.chat.commands.exit_conversation(output: str, context=None)

  Exit a chat session with another agent. Use this when exit criteria are met. Use this command when you are finished with an agent. You may not initiate another conversation whie in a chat session with an agent.

  Parameters: output - String :

  > ALL relevant details of the conversation. IMPORTANT: if the output of the conversation is a deliverable in the form of text, then depending on the wording of the user’s instructions, you may need to include the ALL the text of the deliverable here! If the user asked for only a summary, then provide a summary. If there was work output to a file, this must include the full filename. Etc.

  > This should be EVERY detail that is needed to continue, but none of any intermediary details of the conversation that aren’t relevant. Such as greetings, intermediary work steps, etc. But assume that you will not be able to refer back to this conversation other than the takeaways listed here. So err on the side of caution of including MORE information. But be concise without losing ANY potentially relevant detail.

  > Example: discussion was about a shopping list that was requested from the user. The output should be the full shopping list verbatim (but you can use abbreviations)

  > Example: discussion was about a long process ending in a file being created. The output should be the full filename and path.

  > Example: user requested to have an agent install some software. The output should be whether the software was successfully installed or not, and how to start and configure it. The output in this case should not include all of the steps involved or files installed.

async mindroot.coreplugins.chat.commands.initiate_agent_session(agent_name: str, context=None)

  Initiate a chat session with another agent. IMPORTANT NOTE: You may not use this command while already in conversation with another agent. You must exit the current conversation and then the parent context will continue.

  Parameters: agent_name - String. The name of the agent to start a session with.

  Important: wait for the system to return the log_id for the new chat session before using the converse_with_agent() command. Return: String. The log_id for the new chat session.

async mindroot.coreplugins.chat.commands.insert_image(image_url, context=None)

async mindroot.coreplugins.chat.commands.markdown_await_user(markdown='', context=None)

  Output some markdown text to the user or chat room and then wait for the user’s reply. Use this for any somewhat longer text that the user can read and and doesn’t necessarily need to be spoken out loud.

  You can write as much text/sentences etc. as you need.

  Use the special RAW format with START_RAW and END_RAW to output raw markdown.

  Parameters:

  markdown - String. Insert using RAW mode.

  Note that you can use Katex for math rendering in markdown, but remember to use ‘aligned’ instead of ‘align’. Always use ‘math’ code blocks for this. Be careful of limitations with KaTeX such as macros etc.

  Also, IMPORTANT: if you need to do other formatting in math sections such as a list of steps or a table, use the KaTeX formatting for this rather than trying to add LaTeX in the middle of markdown lists or tables etc.

  Also, you can use HTML in the typical way it is inserted into markdown, including, for example, embedding YouTube videos.

  # Basic Example

  > { “markdown_await_user”:

  >   { “markdown”: START_RAW

  ## Section 1

  - item 1

  - item 2

  END_RAW

    > }

    }

  NOTE: Do NOT start a new command list if there already is one!!

async mindroot.coreplugins.chat.commands.send_to_parent_chat(message: str, context=None)

  > Send a message to the parent chat session. This must only be used within a subconversation initiated by converse_with_agent(). It is useful for things like informing the user about task status or requesting that the user provide a file, etc.

  Parameters:

    - session. (message - String. The message to send to the parent chat)

    - Return – None

async mindroot.coreplugins.chat.commands.task_result(output: str, context=None)

  Return the result of a task to the user.

  This should be the final output of a task that the user requested.

  Note: if you have this command defined, you MUST use it at the end of a task. Be sure to include the full output of the task, unless they specified that they only want a brief or final answer.

  If you do not call this, the task will be repeated.

  Parameters:

  output - Array OR Object OR String. The output of the task, such as analysis, structured data, report, answer, etc.

  IMPORTANT: If the user requests JSON output or provides a schema, you must output ONLY the data in the format requested.

  Unless otherwise indicated for your model, use the special RAW format with START_RAW and END_RAW to output raw markdown.

  Example:

  User: Please output the addresses from the following document

    using this format (e.g.): [{ “address1”: “Main St.”, “state”: “CA”, “zip: “90210” }]

    (… document …)

  you would output something like this:

  { “task_result”: {
    “output”: [

      { “address1”: “First St.”, “state”: “TX”, “zip: “78573” }, { “address2”: “Second St.”, “state”: “TX”, “zip: “78001” }

    ] }

  }

  ___

  In the case that the user requested a formatted report:

  Example:

  User: What is the answer to the universe?

  you would output something like this:

  > { “task_result”:

  >   { “output”: START_RAW

  ## Answer

  The answer is 42.

  END_RAW

  > > }

  > }

async mindroot.coreplugins.chat.commands.tell_and_continue(text='', context=None)

  Say something to the user or chat room, then CONTINUE processing. One sentence per command. If you want to say multiple sentences, use multiple commands. This is for providing the user with a status update without stopping.

  Parameters: text - String. The text to say.

  Return: True

  ## Example 1

  [

    { “tell_and_continue”: { “text”: “Hello, user. I will make that directory for you and then continue with the task..” } }, { “mkdir”: { “absolute_path”: “/new/dir” } }

  ]

async mindroot.coreplugins.chat.commands.wait_for_user_reply(text='', context=None)

  > Say something to the user or chat room, then STOP processing and wait for them to reply. One sentence per command. If you want to say multiple sentences, use multiple commands.

  > Parameters: text - String. The text to say.

  > Return: No return value. After executing commands in the command list, the

  >   system will wait for the user to reply, UNLESS you include a command in your list that returns a value. Therefore, do not use this with other commands that return a value instead of waiting.

  > ## Example 1

  (in this example we issue multiple commands, but are finished with commands after that)

  > [

  >   { “wait_for_user_reply”: { “text”: “Hello, user. Here is some more info on that:” } }, { “markdown_await_user”: { “text”: “[A few paragraphs of info, using RAW encoding]” } }, { “task_complete”: {} }

  > ]

  > (The system waits for the user reply)

## mindroot.coreplugins.chat.format_result_msgs module

## mindroot.coreplugins.chat.mod module

async mindroot.coreplugins.chat.mod.startup(app, context)

## mindroot.coreplugins.chat.models module

class mindroot.coreplugins.chat.models.ImageMessagePart(*, type: Literal['image'], data: str)

  Bases: `BaseModel`

  data: str
  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

  type: Literal['image']

class mindroot.coreplugins.chat.models.TextMessagePart(*, type: Literal['text'], text: str)

  Bases: `BaseModel`

  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

  text: str
  type: Literal['text']

## mindroot.coreplugins.chat.router module

class mindroot.coreplugins.chat.router.CommandRequest(*, command: str, args: dict = {})

  Bases: `BaseModel`

  args: dict
  command: str
  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mindroot.coreplugins.chat.router.TaskRequest(*, instructions: str)

  Bases: `BaseModel`

  instructions: str
  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

async mindroot.coreplugins.chat.router.cancel_chat(request: Request, log_id: str, task_id: str)

async mindroot.coreplugins.chat.router.chat_events(log_id: str)

async mindroot.coreplugins.chat.router.chat_history(request: Request, agent_name: str, log_id: str)

async mindroot.coreplugins.chat.router.chat_session(request: Request, agent_name: str, log_id: str, embed: bool = Query(False))

async mindroot.coreplugins.chat.router.chat_session_redirect(request: Request, agent_name: str, log_id: str)

  Redirect to trailing slash version for proper relative URL resolution.

async mindroot.coreplugins.chat.router.context1(request: Request, log_id: str)

async mindroot.coreplugins.chat.router.delete_chat_session(request: Request, log_id: str, user=Depends(dependency=<function require_user>, use_cache=True, scope=None))

  Delete a chat session by log_id, including chat logs, context files, and all child sessions.

  Parameters: - log_id: The log ID of the session to delete

  Returns: - JSON with success status and message

async mindroot.coreplugins.chat.router.execute_command_get(request: Request, log_id: str, command: str = Query(PydanticUndefined), args: str = Query({}))

  Execute a command using GET request (useful for data-table retrieve-url).

  Parameters: - log_id: The session log_id to use for context - command: The command name to execute (query param) - args: JSON-encoded arguments (query param, default: {})

  Returns: - Direct command result (for use with data-table component)

async mindroot.coreplugins.chat.router.execute_command_session_get(request: Request, agent_name: str, log_id: str, command: str = Query(PydanticUndefined), args: str = Query({}))

  Execute a command using GET request from session URL (for relative URLs in components).

  Parameters: - agent_name: The agent name (from URL path) - log_id: The session log_id to use for context - command: The command name to execute (query param) - args: JSON-encoded arguments (query param, default: {})

  Returns: - Direct command result (for use with data-table component)

async mindroot.coreplugins.chat.router.execute_command_with_session(request: Request, log_id: str, cmd_request: CommandRequest)

  Execute a command using an existing session’s context.

  Parameters: - log_id: The session log_id to use for context - command: The command name to execute - args: Dictionary of arguments to pass to the command

  Returns: - JSON with command result or error

async mindroot.coreplugins.chat.router.get_chat_html(request: Request, agent_name: str, api_key: str = Query(None), embed: bool = Query(False))

async mindroot.coreplugins.chat.router.get_persona_avatar(persona_path: str)

async mindroot.coreplugins.chat.router.get_persona_faceref(persona_path: str)

async mindroot.coreplugins.chat.router.get_token_count(request: Request, log_id: str)

  Get token counts for a chat log identified by log_id, including any delegated tasks.

  Parameters: - log_id: The log ID to count tokens for

  Returns: - JSON with token counts or error message if log not found

async mindroot.coreplugins.chat.router.get_token_count_alt(request: Request, log_id: str)

  Alternative token count endpoint using token_counter module.

  Parameters: - log_id: The log ID to count tokens for

  Returns: - JSON with token counts or error message if log not found

async mindroot.coreplugins.chat.router.make_session(request: Request, agent_name: str)

  Create a new chat session for the specified agent. Returns a redirect to the chat session page.

async mindroot.coreplugins.chat.router.run_task_route(request: Request, agent_name: str, task_request: TaskRequest = None, api_key: str = Query(None))

  Run a task for an agent with the given instructions. This endpoint allows programmatic interaction with agents without a full chat session.

  Parameters: - agent_name: The name of the agent to run the task - instructions: The instructions/prompt to send to the agent

  Returns: - JSON with results and log_id for tracking

async mindroot.coreplugins.chat.router.send_message(request: Request, log_id: str, message_parts: List[TextMessagePart | ImageMessagePart])

async mindroot.coreplugins.chat.router.upload_file(request: Request, log_id: str, file: UploadFile = File(PydanticUndefined))

  Upload a file and store it in a user-specific directory. Returns the file path that can be used in messages.

## mindroot.coreplugins.chat.router_dedup_patch module

## mindroot.coreplugins.chat.services module

mindroot.coreplugins.chat.services.add_current_time(data: dict, context=None) → dict

async mindroot.coreplugins.chat.services.agent_output(event: str, data: dict, context=None)

async mindroot.coreplugins.chat.services.append_message(role: str, content, context=None)

async mindroot.coreplugins.chat.services.backend_assistant_message(message: str, context=None)

  Signal the frontend to display an assistant message.

async mindroot.coreplugins.chat.services.backend_user_message(message: str, context=None)

  Signal the frontend to display a user message.

async mindroot.coreplugins.chat.services.cancel_active_response(log_id: str, context=None)

  Cancel active AI response for eager end of turn processing. Sets the finished_conversation flag to stop the agent processing loop.

async mindroot.coreplugins.chat.services.cancel_and_wait(session_id: str, user: str, context=None)

async mindroot.coreplugins.chat.services.close_chat_session(session_id: str, context=None)

async mindroot.coreplugins.chat.services.command_result(command: str, result, cmd_id=None, context=None)

async mindroot.coreplugins.chat.services.finished_chat(context=None)

async mindroot.coreplugins.chat.services.get_chat_history(agent_name: str, session_id: str, user: str)

async mindroot.coreplugins.chat.services.init_chat_session(user: str, agent_name: str, log_id: str, context=None)

async mindroot.coreplugins.chat.services.partial_command(command: str, chunk: str, params, cmd_id=None, context=None)

mindroot.coreplugins.chat.services.process_result(result, formatted_results)

async mindroot.coreplugins.chat.services.prompt(model: str, instructions: str, temperature=0, max_tokens=400, json=False, context=None)

async mindroot.coreplugins.chat.services.quit(context=None)

mindroot.coreplugins.chat.services.results_output(results)

mindroot.coreplugins.chat.services.results_text(results)

mindroot.coreplugins.chat.services.results_text_output(results)

async mindroot.coreplugins.chat.services.run_task(instructions: str, agent_name: str = None, user: str = None, log_id=None, parent_log_id=None, llm=None, retries=3, context=None)

  Run a task with the given instructions IMPORTANT NOTE: agent must have the task_result() command enabled.

async mindroot.coreplugins.chat.services.running_command(command: str, args, cmd_id=None, context=None)

async mindroot.coreplugins.chat.services.send_message_to_agent(session_id: str, message: str | List[TextMessagePart | ImageMessagePart], max_iterations=35, context=None, user=None, assume_wait_for_task_result=False)

async mindroot.coreplugins.chat.services.subscribe_to_agent_messages(session_id: str, context=None)

## mindroot.coreplugins.chat.utils module

## mindroot.coreplugins.chat.widget_manager module

class mindroot.coreplugins.chat.widget_manager.WidgetManager(widgets_dir: str = 'data/widgets')

  Bases: `object`

  Manages secure widget tokens for chat embedding.

  create_widget_token(api_key: str, agent_name: str, base_url: str, created_by: str, description: str = '', styling: Dict | None = None) → str

    Create a new widget token and store its configuration.

    Parameters:

      - api_key – The API key to use for authentication

      - agent_name – The agent to use for chat sessions

      - base_url – The base URL for the MindRoot instance

      - created_by – Username of the creator

      - description – Optional description for the widget

      - styling – Optional styling configuration

    Returns:

      The generated widget token

  delete_widget_token(token: str) → bool

    Delete a widget token and its configuration.

    Parameters:

      token – The widget token to delete

    Returns:

      True if deleted successfully, False if not found

  get_widget_config(token: str) → Dict | None

    Retrieve widget configuration by token.

    Parameters:

      token – The widget token

    Returns:

      Widget configuration dict if found, None otherwise

  list_widget_tokens(created_by: str | None = None) → List[Dict]

    List all widget tokens, optionally filtered by creator.

    Parameters:

      created_by – Optional username to filter by

    Returns:

      List of widget configurations (with API keys hidden)

  validate_token(token: str) → bool

    Check if a widget token is valid.

    Parameters:

      token – The widget token to validate

    Returns:

      True if valid, False otherwise

## mindroot.coreplugins.chat.widget_routes module

class mindroot.coreplugins.chat.widget_routes.WidgetTokenCreate(*, api_key: str, agent_name: str, base_url: str, description: str | None = '', styling: dict | None = None)

  Bases: `BaseModel`

  agent_name: str
  api_key: str
  base_url: str
  description: str | None
  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

  styling: dict | None

class mindroot.coreplugins.chat.widget_routes.WidgetTokenResponse(*, token: str, agent_name: str, base_url: str, description: str, created_at: str, created_by: str, styling: dict)

  Bases: `BaseModel`

  agent_name: str
  base_url: str
  created_at: str
  created_by: str
  description: str
  model_config = {}

    Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

  styling: dict
  token: str

async mindroot.coreplugins.chat.widget_routes.create_widget_session(token: str)

  Create a secure chat session for a widget token.

async mindroot.coreplugins.chat.widget_routes.create_widget_token(request: Request, widget_request: WidgetTokenCreate)

  Create a new widget token.

async mindroot.coreplugins.chat.widget_routes.delete_widget_token(request: Request, token: str)

  Delete a widget token.

async mindroot.coreplugins.chat.widget_routes.get_embed_script(token: str)

  Generate the secure embed script for a widget token.

async mindroot.coreplugins.chat.widget_routes.list_widget_tokens(request: Request)

  List widget tokens for the current user.

## Module contents