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: ClassVar[ConfigDict] = {}

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: ClassVar[ConfigDict] = {}

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.TaskRequest(*, instructions: str)

Bases: BaseModel

instructions: str

model_config: ClassVar[ConfigDict] = {}

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.context1(request: Request, log_id: str)

async mindroot.coreplugins.chat.router.delete_chat_session(request: Request, log_id: str, user=Depends(require_user))

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

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.close_chat_session(session_id: str, context=None)

async mindroot.coreplugins.chat.services.command_result(command: str, result, 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, 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, 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)

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: ClassVar[ConfigDict] = {}

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: ClassVar[ConfigDict] = {}

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