h2ogpte package

Submodules

h2ogpte.h2ogpte module

class h2ogpte.h2ogpte.H2OGPTE(address: str, api_key: str | None = None, token_provider: TokenProvider | None = None, verify: bool | str = True, strict_version_check: bool = False, send_client_version: bool = True, azure_token: str | None = None)

Bases: H2OGPTESyncBase

Connect to and interact with an h2oGPTe server.

add_agent_key(agent_keys: List[dict]) → List[dict]

Create one or more agent keys for use with agent tools.

Processes a list of agent key configurations and creates each key. Continues processing remaining keys if individual key creation fails.

Args:

agent_keys: List of key configuration dictionaries.

Expected structure:

[
    {
        "name": str,
            # Display name for the key

        "value": str,
            # The actual key/token value

        "key_type": str,
            # Type of key ("private" or "shared")

        "description": str,
            # (Optional) Description of the key's purpose
    }
]

Returns:

List[dict]: List of created key results. Each successful creation: returns {“agent_key_id”: str}. Failed creations are logged but don’t appear in results.

add_builtin_mcp(mcp_id: str, keys: List[dict] | None = None, file_paths: List[str] | None = None) → str

Add a built-in MCP (Model Context Protocol server) to user’s tools.

This configures and enables a predefined MCP for the user, automatically adding it to the user’s tool preferences.

Args:

mcp_id: The ID of the built-in MCP to add (e.g., “playwright_builtin”, “slack_builtin”) keys: Optional list of agent key associations for the MCP.

Each dict should have: {“name”: “ENV_VAR_NAME”, “key_id”: “agent_key_id”}

file_paths: Optional list of file paths to upload for MCP configuration.: Files will be uploaded and attached to the MCP configuration.

Returns:

str: The ID of the added MCP tool

Raises:

InvalidArgumentError: If the MCP is an OAuth app type or file not found

Example:

```python # Add Slack MCP with API key tool_id = client.add_builtin_mcp(

mcp_id=”slack_builtin”, keys=[{“name”: “SLACK_MCP_XOXP_TOKEN”, “key_id”: “my_key_id”}]

)

# Add MCP with file paths (files will be uploaded automatically) tool_id = client.add_builtin_mcp(

mcp_id=”custom_mcp”, file_paths=[“/path/to/config.json”, “/path/to/schema.yaml”]

add_custom_agent(agent_type: str, agent_args: dict, agent_path: str, agent_name: str | None = None) → list

Adds a custom agent by uploading a zip file.

Args:: agent_type: Type of agent (langgraph, crewai, openai, claude) agent_args: Agent configuration arguments agent_path: Path to the agent zip file agent_name: Optional user-provided name for the agent. If provided and the

zip contains exactly one agent, this name will be used instead of the folder name inside the zip. If not provided (or empty), the agent name is derived from the folder name(s) inside the zip.
Returns:: List of agent IDs created from the upload

add_custom_agent_tool(tool_type: str, tool_args: dict, custom_tool_path: str | None = None, generate_system_prompt: bool = False, system_prompt_generation_timeout: float | None = None) → list

Adds a custom agent tool.

Args:

tool_type: The type of custom tool being added. Valid values:

‘local_mcp’: Model Context Protocol server running locally
‘remote_mcp’: Model Context Protocol server running remotely
‘browser_action’: Custom browser automation actions
‘general_code’: General purpose code execution tools

tool_args: Dictionary containing tool-specific arguments. Structure varies by tool_type:

For ‘remote_mcp’: {

“mcp_config_json”: “JSON string with MCP server configuration”, “enable_by_default”: True/False (optional, defaults to True)

}

For ‘local_mcp’, ‘browser_action’, and ‘general_code’: {

“tool_name”: “string (optional, defaults to filename without extension)”, “description”: “string (optional, tool description)”, “enable_by_default”: True/False (optional, defaults to True), “should_unzip”: True/False (optional, for general_code .zip files only), “tool_usage_mode”: [“runner”, “creator”] (optional list of strings, for remote_mcp)

}

custom_tool_path: Path to the tool file to upload (optional). Requirements vary by tool_type:

‘local_mcp’: .zip file containing MCP server code
‘remote_mcp’: Optional configuration file — any extension accepted
(common: .json, .yml, .yaml, .py, .zip, .toml, .ini, .conf, .config, .env, .txt)
‘browser_action’: .py file (must start with ‘browser_’) or .zip containing browser action scripts
‘general_code’: .py or .zip file with custom code

generate_system_prompt:

(Optional) If True and tool_type is “general_code”, generates a system prompt for the tool using LLM analysis and waits for completion. Default is False. Note: this is synchronous and the server holds the connection open until the job completes. Ensure your HTTP client and any intermediate proxies have sufficient timeout (nginx/ALB default to 60-120s, which may cause 504 errors). Use system_prompt_generation_timeout to set a server-side wait budget that returns 408 before the proxy times out.

system_prompt_generation_timeout:

(Optional) Server-side wait budget in seconds. Only used when generate_system_prompt=True. Set below your proxy/ingress read timeout so the API returns 408 instead of letting the proxy emit a 504. Defaults to the server-side cap of 600 seconds (10 minutes).

Returns:

list: List of created custom agent tool IDs

add_role_to_group(group_id: str, roles: List[str]) → List[UserRole]

add_role_to_user(user_id: str, roles: List[str]) → List[UserRole]

add_showcase_chat(shared_chat_id: str, title: str, description: str, category: str | None = None) → AddShowcaseChatResponse

Promote a shared chat to the showcase. Requires manage_showcase.

title and description are required by the server and must be non-empty after trimming; passing an empty string yields a 400.

category is a free-text label used to group tiles in the listing. Pass None (default) to leave the tile uncategorized.

add_skill(skill_path: str, enable_by_default: bool = False) → List[Skill]

Upload a .zip or .skill file to create one or more agent skills.

The zip must contain a SKILL.md file at the root or inside a single subdirectory, with YAML frontmatter containing name and description. A zip with multiple subfolders, each containing a SKILL.md, will create multiple skills.

Args:: skill_path: Path to a .zip or .skill file. enable_by_default: Whether to enable the skill(s) by default for

the user after creation.
Returns:: List[Skill]: The created skill objects.
Raises:: FileNotFoundError: skill_path does not exist. ValueError: skill_path has an unsupported extension or is too

large (>100 MiB).

Example:

skills = client.add_skill("my-skills.zip")
for skill in skills:
    print(skill.id, skill.skill_name)

add_user_document_permission(user_id: str, document_id: str) → [<class 'str'>, <class 'str'>]

Associates a user with a document they have permission on. Args:

user_id:
String The id of the user that has the permission.

document_id:
String The id of the document that the permission is for.

Returns:: [user_id, document_id]: A tuple containing the user_id and document_id.

admin_cleanup_chat_sessions(older_than_days: int, force: bool = False, timeout: float | None = None) → Job

Delete chat sessions older than a specified number of days.

Admin-only. Dispatches a cleanup job for chat sessions that haven’t been active for the specified number of days.

Args:

older_than_days:: Delete sessions inactive for this many days.
force:: If True, also delete keep_forever and exempt sessions.
timeout:: Timeout in seconds.

Returns:

The cleanup job.

Send a message and get a response from an LLM.

Note: This method is only recommended if you are passing a chat conversation or for low-volume testing. For general chat with an LLM, we recommend session.query() for higher throughput in multi-user environments. The following code sample shows the recommended method:
# Establish a chat session
chat_session_id = client.create_chat_session()
# Connect to the chat session
with client.connect(chat_session_id) as session:
    # Send a basic query and print the reply
    reply = session.query("Hello", timeout=60)
    print(reply.content)
Format of inputs content:
{text_context_list}
"""\n{chat_conversation}{question}
Args:

question:
Text query to send to the LLM.

text_context_list:
List of raw text strings to be included, will be converted to a string like this: “

“.join(text_context_list)

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default, or None for h2oGPTe default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks in text_context_list. Only used if text_context_list is provided.

prompt_query:

Text that is appended after the contextual document chunks in text_context_list. Only used if text_context_list is provided.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

# Core generation parameters temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. min_chars_per_yield (int) — Minimum number of characters to yield at a time during streaming reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort

# Output format parameters response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation json_preserve_system_prompt (bool) — Whether to preserve the system prompt when using JSON response format

# Vision and image parameters images_num_max (int) — Maximum number of images to process visible_vision_models (list) — List of vision models that can be used

# Agent parameters use_agent (bool, default: False) — Whether to enable agent functionality for advanced task processing with access to tools shared_agent (bool, default: False) — Whether to use shared agent instance across multiple requests for efficiency agent_type (str, default: “auto”) — Type of agent to use. Options: [“auto”, “agent_analysis”, “agent_chat_history_md”, “agent_code”, “agent_rag”] selected_tool_type (str, default: “auto”) — Type of tools to make available to the agent. Options: [“auto”, “all”, “any”] or specific tool names selected_agent_type (str, optional) — Agent framework type for agents_builder. Options: [“crewai”, “langgraph”, “openai”] agent_accuracy (str, default: “standard”) — Accuracy level for agent operations. Options:

“quick” - Fastest, less verification (max_turns=10, timeout=30s) “basic” - Best for simple tasks (max_turns=20, timeout=60s) “standard” - Good for most tasks (max_turns=40, timeout=120s) “maximum” - Highest accuracy, can take a long time (max_turns=80, timeout=240s)

agent_max_turns (Union[str, int], default: “auto”) — Maximum number of back-and-forth turns the agent can take. Either “auto” or an integer agent_original_files (list) — List of file paths for agent to process and analyze agent_timeout (int) — Timeout in seconds for each individual agent turn/operation agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent operations combined agent_min_time (int) — Minimum time in seconds to run the agent before allowing completion agent_tools (Union[str, list], default: “auto”) — List of specific tools available to the agent. Options: “auto”, “all”, “any”, or list of tool names user_persona (str) — User persona description for agent context to customize agent behavior agent_code_writer_system_message (str) — Custom system message for code writing agent to guide code generation agent_code_restrictions_level (int) — Level of code execution restrictions for agent (typically 0 for unrestricted) agent_num_executable_code_blocks_limit (int) — Maximum number of code blocks the agent can execute in a single session agent_system_site_packages (bool, default: False) — Whether agent can use system site packages when executing code agent_main_model (str) — Main model to use for agent operations (e.g., specific LLM name) agent_max_stream_length (int, default: -1) — Maximum length for agent streaming responses, -1 for unlimited agent_max_memory_usage (int) — Maximum memory usage in bytes for agent operations agent_main_reasoning_effort (int) — Level of reasoning effort for main agent model (higher values = more reasoning, e.g., 10000) agent_advanced_reasoning_effort (int) — Level of reasoning effort for advanced agent operations (e.g., 20000) agent_max_confidence_level (int) — Maximum confidence level for agent decisions (typically 0, 1, or 2) agent_planning_forced_mode (bool) — Whether to force planning mode for agent (True to always plan first) agent_too_soon_forced_mode (bool) — Whether to force handling of premature agent decisions agent_critique_forced_mode (int) — Whether to force critique mode for agent self-evaluation agent_query_understanding_parallel_calls (int) — Number of parallel calls for query understanding tool_building_mode (str) — Mode for tool building configuration agent_stream_files (bool, default: True) — Whether to stream files from agent operations for real-time updates

# Other parameters max_time (int) — Maximum time in seconds for the operation client_metadata (dict) — Metadata to include with the request

chat_conversation:

List of tuples for (human, bot) conversation that will be pre-appended to an (question, None) case for a query.

guardrails_settings:

Guardrails Settings.

timeout:

Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:: h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

archive_chat_session(chat_session_id: str) → str

Archive a chat session along with its associated data.

Admin-only. Sets the session status to ‘archived’, clears expiry settings, and marks keep_forever as false.

Args:

chat_session_id:: ID of the chat session to archive.

archive_collection(collection_id: str) → str

Archive a collection along with its associated data.

Args:

collection_id:: ID of the collection to archive.

assign_agent_key_for_tool(tool_dict_list: List[dict]) → List[Tuple] | None

Assign agent keys to tools by creating associations between them.

Args:

tool_dict_list: List of dictionaries containing tool association data.

Each dictionary should have a “tool_dict” key with the association configuration data for creating agent tool key associations.

Expected tool_dict structure:

{
    "tool": str,        # Name of the tool (for example, "test_tool").
    "keys": list[dict], # List of key definitions. Each item is a dictionary with:
                       #   - "name": str
                       #       Environment variable name (for example, "TEST_KEY").
                       #   - "key_id": Any
                       #       Identifier assigned to the key (for example, agent_key_id).
}

Returns:

Optional[List[Tuple]]: List of tuples containing association details.: Each tuple contains (associate_id, tool, key_name, key_id, user_id). Returns None if no associations were created.

assign_permissions_to_role(role_name: str, permission_names: Iterable[str]) → Result

build_collection_graph(collection_id: str, llm: str | int | None = None, force_rebuild: bool = False, timeout: float | None = None, callback: Callable[[Job], None] | None = None) → Job

Build a knowledge graph for a collection using LightRAG.

Triggers an asynchronous job that extracts entities and relationships from all document chunks in the collection to build a knowledge graph. The graph enables graph-augmented retrieval via the graph_rag RAG type.

Args:

collection_id:: String id of the collection to build the graph for.
llm:: LLM to use for entity extraction. Defaults to the system default.
force_rebuild:: If True, removes any existing graph and rebuilds from scratch.
timeout:: Amount of time in seconds to allow the job to run. The default is 86400 seconds.
callback:: Function for processing job status info during the build.

Returns:

The completed Job object.

bulk_delete_global_configurations(key_names: List[str]) → List[GlobalConfigItem]

bulk_delete_role_configurations(role_id: str, keys: List[str]) → List[ConfigItem]

Delete role configuration items for a given role. Args:

role_id:
The role id to delete configurations for.

keys:
List of configuration keys to delete.

Returns:: List[ConfigItem]: List of remaining role configurations.

bulk_delete_user_configurations_for_user(user_id: str, key_names: List[str]) → List[ConfigItem]

cancel_job(job_id: str) → Result

Stops a specific job from running on the server.

Args:

job_id:: String id of the job to cancel.

Returns:

Result: Status of canceling the job.

cancel_user_job(job_id: str, cancel_reason: str | None = None) → Result

As an admin, stops a specific user job from running on the server.

Args:

job_id:: String id of the job to cancel.
cancel_reason:: Optional reason for canceling the job.

Returns:

Result: Status of canceling the job.

confirm_current_user_deletion(delete_id: str, timeout: float | None = None) → None

Confirm deletion of the current user data.

Args:

delete_id:: The delete ID returned from request_current_user_deletion().
timeout:: Timeout in seconds. Default is 300 seconds.

connect_assistant_to_collection(assistant_id: str, collection_id: str, access_mode: str = 'read') → None

Connect an AI assistant to a document collection.

Once connected, the assistant can use RAG tools (query_collection, read_document, list_documents) against this collection.

Args:: assistant_id: The assistant’s UUID. collection_id: The collection’s UUID. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

Defaults to ‘read’.

connect_assistant_to_forum(assistant_id: str, forum_id: str, access_mode: str = 'read') → None

Connect an AI assistant to a forum.

Args:: assistant_id: The assistant’s UUID. forum_id: The forum’s UUID. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

Defaults to ‘read’ to follow principle of least privilege.

connect_assistant_to_schedule(assistant_id: str, scheduled_task_id: str) → None

Connect an AI assistant to a scheduled task as a wake trigger.

Args:: assistant_id: The assistant’s UUID. scheduled_task_id: The scheduled task’s UUID.

count_assets() → ObjectCount

Counts number of objects owned by the user.

Returns:: ObjectCount: The count of chat sessions, collections, and documents.

count_chat_sessions() → int

Counts number of chat sessions owned by the user.

Returns:: int: The count of chat sessions owned by the user.

count_chat_sessions_for_collection(collection_id: str) → int

Counts number of chat sessions in a specific collection.

Args:

collection_id:: String id of the collection to count chat sessions for.

Returns:

int: The count of chat sessions in that collection.

count_collections() → int

Counts number of collections owned by the user.

Returns:: int: The count of collections owned by the user.

count_documents(chat_session_id: str | None = None) → int

Counts number of documents accessed by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents so a filtered list can be paged against this total.

Returns:

int: The count of documents accessed by the user.

count_documents_in_collection(collection_id: str) → int

Counts the number of documents in a specific collection.

Args:

collection_id:: String id of the collection to count documents for.

Returns:

int: The number of documents in that collection.

count_documents_owned_by_me(chat_session_id: str | None = None) → int

Counts number of documents owned by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents.

Returns:

int: The count of documents owned by the user.

count_jobs_by_status(created_after: datetime | str | None = None) → JobHistoryStats

Count jobs by status over the last 7 days by default (admin only).

Args:

created_after:: Lower bound on created_at. Defaults to the last 7 days when omitted; how far back data exists is bounded by the server’s retention setting (at most 365 days).

Returns:

JobHistoryStats: per-status counts, including cleared (deleted) jobs.

count_prompt_templates() → int

Counts number of prompt templates

Returns:: int: The count of prompt templates

count_question_reply_feedback(collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → int

Fetch user’s questions and answers with feedback count.

Args:

collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only count feedbacks with no collection.

Returns:

int: the count of questions and replies that have a user feedback.

create_ai_assistant(name: str, llm: str, description: str = '', system_prompt: str = '', llm_args: Dict[str, Any] | None = None, custom_tool_definition: str | None = None, mcp_servers: List[Any] | None = None, credential_ids: List[str] | None = None, memory_block_id: str | None = None, notification_email: str | None = None, history_management: str = 'semantic_retrieval', history_max_chars: int | None = None, history_recent_chars: int | None = None, history_retrieval_chars: int | None = None, allowed_tool_actions: List[str] | None = None, allowed_trigger_types: List[str] | None = None, default_wake_period: int | None = None, tool_action_policies: Dict[str, str] | None = None, approval_user_id: str | None = None, custom_approval_text: str | None = None, auto_memory_block: bool = True) → str

Create a new AI assistant.

Args:

name: Name of the assistant (must be unique per user). description: Optional description. system_prompt: System prompt for the assistant’s LLM calls. llm: Model identifier to use. llm_args: Optional dict of additional LLM arguments. custom_tool_definition: Optional custom tool Python code (None = use default). mcp_servers: Optional list of MCP server configuration objects. credential_ids: Optional list of credential/secret UUIDs. memory_block_id: Optional UUID of a memory block for private state.

When None and auto_memory_block is True, an auto memory block is created. When None and auto_memory_block is False, no memory block is used.

notification_email: Optional email for wake cycle notifications. history_management: ‘truncation’, ‘compactification’, or ‘semantic_retrieval’. history_max_chars: Character threshold for history management. history_recent_chars: Characters of recent history to always include (semantic_retrieval mode). history_retrieval_chars: Characters of retrieved history to include (semantic_retrieval mode). allowed_tool_actions: List of allowed tool action names (None = all allowed). allowed_trigger_types: List of allowed trigger types (None = all allowed). default_wake_period: Periodic wake interval in seconds (None = no periodic wake). tool_action_policies: Dict mapping tool action names to policies (None = no policies). approval_user_id: Optional UUID of the designated approval user. custom_approval_text: Optional custom data protection instructions for the agent. auto_memory_block: When True (default) and memory_block_id is None, an auto

memory block is created for the assistant. Set to False to explicitly create an assistant without a memory block.

Returns:

str: The ID of the created assistant.

create_api_key_for_user(user_id: str, name: str | None = None, collection_id: str | None = None, expires_in: str | None = None, inactivity_interval: int | None = None) → str

Allows admins to create a new api key for a specific user and optionally make it specific to a collection. Args:

user_id:
String: The id of the user the API key is for.

name:
(Optional) String: The name of the API key.

collection_id:
(Optional) String: The id of the specific collection.

expires_in:
(Optional) String: The expiration for the API key as an interval. Ex. “30 days” or “30 minutes”

inactivity_interval:
(Optional) int: The number of days a key can be unused for (no activity) before it becomes invalid.

Returns:: String: The id of the API key.

create_assistant_webhook(assistant_id: str, name: str, description: str = '', rate_limit_per_minute: int = 10) → Dict[str, Any]

Create a webhook endpoint for an AI assistant.

External systems can wake the assistant by POSTing to the webhook URL. The token is returned only once — save it immediately.

Args:: assistant_id: ID of the assistant. name: Human-readable name for the webhook. description: Optional description. rate_limit_per_minute: Max invocations per minute (default 10).
Returns:: Dict with ‘id’, ‘token’ (shown only once), ‘name’, and webhook URL.

create_chat_session(collection_id: str | None = None, workspace: str | None = None) → str

Creates a new chat session for asking questions (of documents).

Args:

collection_id:: String id of the collection to chat with. If None, chat with LLM directly.
workspace:: String id of the workspace this chat will be associated with. If None, the user’s default workspace will be used.

Returns:

str: The ID of the newly created chat session.

create_chat_session_on_default_collection() → str

Creates a new chat session for asking questions of documents on the default collection.

Returns:: str: The ID of the newly created chat session.

Creates a new collection.

Args:

name:

Name of the collection.

description:

Description of the collection

embedding_model:

embedding model to use. call list_embedding_models() to list of options.

prompt_template_id:

ID of the prompt template to get the prompts from. None to fall back to system defaults.

collection_settings:

(Optional) Dictionary with key/value pairs to configure certain collection specific settings max_tokens_per_chunk: Approximate max. number of tokens per chunk for text-dominated document pages. For images, chunks can be larger. chunk_overlap_tokens: Approximate number of tokens that are overlapping between successive chunks. gen_doc_summaries: Whether to auto-generate document summaries (uses LLM) gen_doc_questions: Whether to auto-generate sample questions for each document (uses LLM) audio_input_language: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices. ocr_model: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models.

Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. auto - Automatic will auto-select the best OCR model for every page. off - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

tesseract_lang: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices. keep_tables_as_one_chunk: When tables are identified by the table parser the table tokens will be kept in a single chunk. chunk_by_page: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is true. handwriting_check: Check pages for handwriting. Will use specialized models if handwriting is found. follow_links: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document. max_depth: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings). max_documents: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit). root_dir: Root directory for document storage copy_document: Whether to copy the document when importing an existing document. guardrails_settings itself is a dictionary of the following keys.

column_redaction_config: list of list for redacting columns from CSV/TSV files (regex_pattern, fill_value) disallowed_regex_patterns: list of regular expressions that match custom PII presidio_labels_to_flag: list of entities to be flagged as PII by the built-in Presidio model. pii_labels_to_flag: list of entities to be flagged as PII by the built-in PII model. pii_detection_parse_action: what to do when PII is detected during parsing of documents. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content in the ingested documents with redaction bars. pii_detection_llm_input_action: what to do when PII is detected in the input to the LLM (document content and user prompts). One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. pii_detection_llm_output_action: what to do when PII is detected in the output of the LLM. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. prompt_guard_labels_to_flag: list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model. guardrails_labels_to_flag: list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided. guardrails_safe_category: (Optional) name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults. guardrails_entities: (Optional) dictionary of entities and their descriptions for the guardrails model to classify. The first entry is the “safe” class, the rest are “unsafe” classes. custom_pii_entities_to_flag: list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided. custom_pii_entities: (Optional) dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files. guardrails_llm: LLM to use for guardrails and PII detection. Use “auto” for automatic. Use H2OGPTE.get_llms() to see all available options.

Example:

Note: Call client.get_guardrails_settings() to see all options for guardrails_settings.

collection_settings=dict(

max_tokens_per_chunk=320, chunk_overlap_tokens=0, guardrails_settings=dict(

disallowed_regex_patterns=[“secret_disallowed_word”, r”(?!0{3})(?!6{3})[0-8]d{2}-(?!0{2})d{2}-(?!0{4})d{4}”], presidio_labels_to_flag=[“IBAN_CODE”, “US_SSN”], pii_labels_to_flag=[“IBAN”, “SSN”], pii_detection_parse_action=”redact”, pii_detection_llm_input_action=”redact”, pii_detection_llm_output_action=”allow”, prompt_guard_labels_to_flag=[“JAILBREAK”], guardrails_labels_to_flag=[

“Violent Crimes”, “Non-Violent Crimes”, “Intellectual Property”, “Code Interpreter Abuse”,

], guardrails_safe_category=”Safe”, # guardrails_entities is intentionally NOT shown here. # Omit it to inherit the server’s maintained default # category definitions and keep receiving improvements # to them. Supplying it REPLACES the defaults wholesale # (it is not merged), so a dict copied from an example # pins the collection to those exact definitions # forever – including wordings later found too weak to # classify reliably. Pass it only when you own the full # category set deliberately. custom_pii_entities_to_flag=[

“Mother’s Maiden Name”

], custom_pii_entities={

“Mother’s Maiden Name”: “Mother’s maiden name.”

}, guardrails_llm=”meta-llama/Llama-3.3-70B-Instruct”,

),

)

thumbnail:

(Optional) Path to the thumbnail image for the collection. Must include appropriate file extension.

chat_settings:

(Optional) Dictionary with key/value pairs to configure the default values for certain chat specific settings The following keys are supported, see the client.session() documentation for more details. llm: str — Default LLM to use for chat sessions in this collection llm_args: dict — Default LLM arguments (see answer_question method for full list of valid keys) self_reflection_config: dict — Configuration for self-reflection functionality rag_config: dict — Configuration for RAG (Retrieval-Augmented Generation) include_chat_history: bool — Whether to include chat history in context tags: list[str] — Tags to associate with the collection

workspace:

(Optional) The workspace id to be associated with this collection. None to use the default workspace.

vex_encryption:

(Optional) Per-collection vector encryption choice. One of:

“enabled” — store vectors encrypted (the server must have a vector encryption provider configured).
“disabled” — store vectors as plaintext, even if the server has encryption enabled by default.
None — fall back to the server-level default.

Honored at create time only and sticky once any data is written.

Returns:

str: The ID of the newly created collection.

create_custom_agent_key_association(agent_id: str, env_key_name: str, key_id: str) → dict

Creates a custom agent key association (env var -> agent key).

Args:

agent_id: Custom agent UUID env_key_name: Env var name (from envs.json or user-added) key_id: Agent key UUID to associate

Returns:

dict: Created association with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

create_custom_agent_tool_association(agent_id: str, mcp_server_name: str, tool_name: str | None = None) → dict

Creates a custom agent tool association.

Args:: agent_id: Agent UUID mcp_server_name: MCP server name tool_name: Optional tool name to associate (None for unresolved)
Returns:: dict: Created association object

create_event_type(name: str, description: str = '', payload_schema: Dict[str, Any] | None = None) → AiAssistantEventType

Create a custom event type that assistants can subscribe to and emit.

Args:: name: Name of the event type (max 200 chars, must not collide with built-in types). description: Optional description (max 5000 chars). payload_schema: Optional JSON schema for event payloads.
Returns:: AiAssistantEventType: The created event type.

create_extractor(name: str, llm: str, extractor_schema: Dict[str, Any], description: str = '', prompt: str = '', pre_prompt_summary: str = '', keep_intermediate_results: bool = False, system_prompt: str = '', max_num_chunks: int = 100, vision: str = 'auto', vision_llm: str = 'auto', image_batch_image_prompt: str = '', image_batch_final_prompt: str = '', guardrails_settings: Dict | None = None) → Extractor

Creates a new extractor.

Args:: name: Name of the extractor. llm: LLM to use for extraction. extractor_schema: JSON schema defining the extraction structure. If not empty, extractor will return data as JSON object. description: Optional description of the extractor. prompt: Optional prompt text for the extractor. If combined with extractor_schema, prompt can modify the output, but not its format as it’s set to be JSON object. pre_prompt_summary: Optional pre-prompt summary text for the extractor. keep_intermediate_results: Optional flag indicating whether to keep intermediate results during extraction. system_prompt: Optional system prompt text for the extractor. max_num_chunks: Optional maximum number of chunks to process. vision: Optional vision mode setting. vision_llm: Optional vision LLM model identifier. image_batch_image_prompt: Optional image batch processing prompt. image_batch_final_prompt: Optional final prompt for image batch processing. guardrails_settings: Optional guardrails settings configuration as a dictionary.
Returns:: Extractor: Details of the newly created extractor.
Raises:: InvalidArgumentError: If extractor_schema is neither a dict nor None.

create_forum(name: str, description: str = '') → str

Create a new forum.

Args:: name: Name of the forum (must be unique per user). description: Optional description.
Returns:: str: The ID of the created forum.

create_forum_post(forum_id: str, content: str, parent_post_id: str | None = None, assistant_id: str | None = None, file_ids: List[str] | None = None, metadata: Dict[str, Any] | None = None) → str

Create a post on a forum.

Creates the post via the REST API. Sleeping assistants connected to this forum are automatically woken via a push to the event queue.

Args:: forum_id: The forum’s UUID. content: The post content. parent_post_id: Optional parent post ID for threading (reply). assistant_id: Optional assistant ID if posting as an assistant. file_ids: Optional list of file UUIDs to attach. metadata: Optional metadata dict for custom key-value pairs.

Note: the ‘pinned’ key is stripped server-side; use pin_forum_post() instead.
Returns:: str: The ID of the created post.

Create a memory block: reusable content injected into LLM/agent chats.

Args:

name:: Display name of the memory block.
content:: Text content of the memory block.
system_prompt_amendment:: System prompt amendment used in agent mode.
injection_mode:: Where memory content is injected: ‘system_prompt’, ‘user_instruction’, ‘agent_file’, or ‘agent_tool’.
access_mode:: Whether the LLM/agent can ‘read’, ‘write’, or ‘read_write’.
max_content_length:: Maximum number of characters allowed in memory content. 0 means unlimited.

Returns:

MemoryBlock: The newly created memory block.

create_prompt_template(name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Create a new prompt template

Args:

name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the newly created prompt template.

create_runtime_llm(config: Dict[str, Any]) → Dict[str, Any]: Create a runtime (UI/API) LLM from a full config object; the config is stored verbatim and the connection is probed before the model is saved (a failed probe rejects the create). display_name must be the name the model is served under whenever that name is a LiteLLM proxy routing key: the lite_llm_yaml block’s top-level model_name when the config has a block, else base_model when inference_server is "litellm". A different display_name is rejected, because the model is registered with the proxy under that name. A model reached directly at its provider (anthropic, google, a vLLM endpoint) with no block is registered under display_name itself, so its display_name is free. A block mux cannot read (hand-written YAML, or JSON declaring no top-level model_name) is rejected. Returns the new row (admin only).

create_scheduled_task(name: str | None = None, schedule_type: str = '', schedule_expression: str = '', task_type: str = '', task_config: Dict[str, Any] | None = None, description: str = '', max_executions: int | None = None, expires_at: str | None = None, notification_email: str = '', message: str | None = None, system_prompt: str | None = None, collection_id: str | None = None, timezone: str | None = None, llm: str | None = None, llm_args: Dict[str, Any] | None = None) → ScheduledTask

Create a scheduled task.

Args:

name: Unique (per user) task name. If omitted, a collision-safe name: is derived from the message (e.g. ‘summarize-yesterdays-sales-a3f2c1’).

schedule_type: ‘once’, ‘recurring’, or ‘interval’. schedule_expression: ISO-8601 datetime (‘once’), 5-field cron

(‘recurring’, e.g. ‘0 9 * * 1’), or ‘N minutes’/’N hours’ (‘interval’).

task_type: ‘chat_completion’ or ‘agent_task’. task_config: Task configuration. MUST contain a non-empty ‘message’

key (the question/prompt). May include ‘timezone’, ‘collection_id’, and ‘llm_args’.

description: Optional description. max_executions: Optional cap on executions. Not needed for ‘once’

tasks, which already run exactly once.

expires_at: Optional ISO-8601 expiry; must be in the future. notification_email: Optional email for run notifications. The literal

‘current_user’ resolves to the caller’s email server-side.

message: Builder mode: the question/prompt to run. Required if: task_config is omitted.

system_prompt: Builder mode: system prompt applied to every run. collection_id: Builder mode: binds each run’s chat session to this

collection.

timezone: Builder mode: IANA timezone for cron evaluation. llm: Builder mode: model override. llm_args: Builder mode: LLM arguments, e.g. {‘use_agent’: True} for

agent behavior.

Note:

task_config and the builder kwargs are mutually exclusive.

Returns:

ScheduledTask: the created task.

Example:

task = client.create_scheduled_task(
    name="sales-summary-daily",
    schedule_type="recurring",
    schedule_expression="0 9 * * *",
    task_type="chat_completion",
    task_config={
        "message": "Summarize yesterday's sales",
        "system_prompt": "You are a sales analyst.",
        "collection_id": "<collection-uuid>",   # binds the runs to a collection
        "timezone": "America/New_York",         # cron evaluated in this tz
        "llm_args": {"use_agent": True},        # agent behavior
    },
)

create_scheduled_task_for_assistant(assistant_id: str, name: str, message: str, schedule_type: str = 'once', schedule_expression: str = '', run_at: str | None = None, cron_expression: str | None = None, max_executions: int | None = None, notification_email: str = '') → str

Create a scheduled task and connect it to an AI assistant.

This is a convenience method that: 1. Creates a scheduled task via create_scheduled_task RPC. 2. Connects the task to the assistant via connect_assistant_to_schedule.

Args:

assistant_id: The assistant’s UUID. name: Task name. message: The message/prompt for the task. schedule_type: ‘once’, ‘recurring’, or ‘interval’. schedule_expression: Cron expression (for recurring) or interval (for interval).

Ignored if run_at is provided.

run_at: ISO 8601 timestamp for one-shot tasks. Sets schedule_type=’once’. cron_expression: Alias for schedule_expression with schedule_type=’recurring’. max_executions: Maximum number of executions (null = unlimited). notification_email: Email for notifications.

Returns:

str: The created scheduled task UUID.

create_secret(secret: Dict[str, Any]) → str | None

Create a new secret in the SecureStore.

Args:

secret: A dictionary containing the secret data to be stored.: Must include secret_id and secret_value; secret_type is optional.

Returns:

The ID of the newly created secret.

create_slack_integration(name: str, workspace_id: str, bot_token: str, signing_secret: str) → Dict[str, Any]

Create a Slack integration for connecting Slack channels as forums.

Args:: name: Display name for the integration. workspace_id: Slack workspace/team ID (e.g., T01234567). bot_token: Slack bot token (xoxb-…). signing_secret: Slack signing secret for webhook verification.
Returns:: Dict with integration details.

create_tag(tag_name: str) → str

Creates a new tag.

Args:

tag_name:: String representing the tag to create.

Returns:

String: The id of the created tag.

create_user_builtin_mcp(mcp_config: dict, logo_path: str | None = None) → dict

Create a new user-specific builtin MCP configuration.

Publishes an MCP to the shared library so it appears in the builtin MCPs list for all users. Requires the ManageLibrary permission (admins hold it by default).

Args:

mcp_config: Dictionary containing the MCP configuration matching built_in_mcps.json structure.: Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

logo_path: Optional path to a logo image file to upload

Returns:

dict: Dictionary with the created MCP details including id, mcp_id, config, user_id, created_at, updated_at

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission InvalidArgumentError: If the MCP config is invalid or MCP ID already exists

Example:

```python mcp_config = {

“name”: “My Custom MCP”, “description”: “Custom MCP for internal use”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = client.create_user_builtin_mcp(mcp_config, logo_path=”/path/to/logo.png”) ```

create_user_group(name: str, description: str) → UserGroup

create_user_role(name: str, description: str) → UserRole

deactivate_api_key(api_key_id: str) → Result

Allows admins to deactivate an API key.

Note: You cannot undo this action.

Args:

api_key_id:: String: The id of the API key.

Returns:

Result: Status of the deactivate request.

delete_agent_directories(chat_session_id: str) → bool: Delete agent directories for a chat session.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

delete_agent_keys(key_ids: List[str]) → None

delete_agent_server_files(chat_session_id: str) → bool

delete_agent_tool_association(associate_ids: List[str]) → int

delete_agent_tool_preference() → None

delete_ai_assistant(assistant_id: str) → None

Delete an AI assistant.

Uses the REST API endpoint which both deletes from the DB and cleans up Redis wake/dedup keys, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

delete_api_keys(api_key_ids: List[str]) → Result

Allows admins to delete API keys.

Args:

api_key_ids:: List[str]: The API keys to delete.

Returns:

Result: Status of the delete request.

delete_assistant_webhook(assistant_id: str, webhook_id: str) → None

Delete a webhook endpoint.

Args:: assistant_id: ID of the assistant. webhook_id: ID of the webhook to delete.

delete_chat_messages(chat_message_ids: Iterable[str]) → Result

Deletes specific chat messages.

Args:

chat_message_ids:: List of string ids of chat messages to delete from the system.

Returns:

Result: Status of the delete job.

delete_chat_sessions(chat_session_ids: Iterable[str], timeout: float | None = None) → Job

Deletes chat sessions and related messages.

Args:

chat_session_ids:: List of string ids of chat sessions to delete from the system.
timeout:: Timeout in seconds.

Returns:

Result: The delete job.

delete_collections(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections from the environment.

Documents in the collection that are owned by other users will not be deleted.

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

delete_collections_as_admin(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections and their associated data from the environment (needs appropriate permission).

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

delete_custom_agent(agent_ids: List[str]) → int

Deletes custom agents.

Args:: agent_ids: List of agent IDs to delete
Returns:: Count of deleted agents

delete_custom_agent_key_associations(association_ids: List[str]) → int

Deletes custom agent key associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

delete_custom_agent_tool(tool_ids: List[str]) → int

delete_custom_agent_tool_associations(association_ids: List[str]) → int

Deletes custom agent tool associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

delete_document_summaries(summaries_ids: Iterable[str]) → Result

Deletes document summaries.

Args:

summaries_ids:: List of string ids of a document summary to delete from the system.

Returns:

Result: Status of the delete job.

delete_documents(document_ids: Iterable[str], timeout: float | None = None) → Job

Deletes documents from the system.

Args:

document_ids:: List of string ids to delete from the system and all collections.
timeout:: Timeout in seconds.

delete_documents_from_collection(collection_id: str, document_ids: Iterable[str], timeout: float | None = None) → Job

Removes documents from a collection.

See Also: H2OGPTE.delete_documents for completely removing the document from the environment.

Args:

collection_id:: String of the collection to remove documents from.
document_ids:: List of string ids to remove from the collection.
timeout:: Timeout in seconds.

delete_event_type(event_type_id: str) → None

Delete a custom event type. Only the creator can delete.

Cascades to all subscriptions.

Args:: event_type_id: The event type’s UUID.

delete_extractor(extractor_id: str)

Deletes an extractor by its ID.

Args:: extractor_id: The ID of the extractor to delete.

delete_forum(forum_id: str) → None

Delete a forum.

Args:: forum_id: The forum’s UUID.

delete_forum_post(post_id: str) → None

Delete a forum post.

Args:: post_id: The post’s UUID.

delete_library_skill(skill_id: str) → None

Remove a published skill from the library (requires ManageLibrary).

Args:: skill_id: Library id of the published skill.

Example:

client.delete_library_skill("my-skill_library")

delete_memory_block(memory_block_id: str) → None

Delete a memory block.

Args:

memory_block_id:: ID of the memory block to delete.

delete_multiple_agent_directories(chat_session_ids: List[str], dir_types: List[str]) → bool: Delete agent directories for multiple chat sessions.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

delete_prompt_templates(ids: Iterable[str]) → Result

Deletes prompt templates

Args:

ids:: List of string ids of prompte templates to delete from the system.

Returns:

Result: Status of the delete job.

delete_runtime_llm(model_id: str) → None: Hard-delete a runtime LLM by registry UUID (the row is removed, not soft-deleted). Operates only on UI/API runtime rows; a static/env/override or unknown UUID is rejected (admin only).

delete_scheduled_task(task_id: str) → Dict[str, Any] | None: Delete a single scheduled task. Returns {‘status’: ‘deleted’} (or None on a 204).

delete_scheduled_tasks(task_ids: List[str]) → Dict[str, Any] | None: Delete multiple scheduled tasks. Returns {‘status’: ‘deleted’, ‘count’: N} (or None on a 204).

delete_scheduled_tasks_by_admin(task_ids: List[str]) → Dict[str, Any] | None: Delete multiple scheduled tasks for any user (admin only). Returns None on a 204.

delete_secret(secret_id: str) → None

Delete a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to delete.
Returns:: None

delete_shared_chats(shared_chat_ids: List[str]) → None

Delete shared chats by their IDs.

Only shared chats owned by the current user can be deleted.

Args:

shared_chat_ids:: List of shared chat IDs to delete.

delete_showcase_thumbnail(showcase_id: str) → None: Drop the thumbnail object from storage and clear the showcase row.

delete_skills(skill_ids: List[str]) → int

Delete agent skills by their IDs.

Delete is all-or-nothing: if any ID does not belong to the current user, the request fails with an authorization error and no skill is deleted. This avoids the partial-success ambiguity where a caller could not tell which IDs were rejected.

Args:

skill_ids: List of skill UUIDs to delete. Must all belong to the: authenticated user.

Returns:

int: Number of distinct skills deleted. Duplicate IDs are de-duplicated server-side, so this equals the number of unique IDs in skill_ids (which may be less than len(skill_ids) if the list contains repeats).

Raises:

H2OGPTEError: HTTP 403 — one or more IDs do not belong to the user; no skills are deleted.

Example:

count = client.delete_skills(["id1", "id2"])
print(f"Deleted {count} skills")

delete_slack_integration(integration_id: str) → None

Delete a Slack integration and all linked channels.

Args:: integration_id: ID of the Slack integration.

delete_tag(tag_name: str) → str

Deletes a tag from the system.

Only the tag creator can delete it. All document-tag associations are automatically removed.

Args:

tag_name:: String representing the tag to delete.

Returns:

String: The id of the deleted tag.

delete_upload(upload_id: str) → str

Delete a file previously uploaded with the “upload” method.

See Also:

upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection.

Args:

upload_id:: ID of a file to remove

Returns:

upload_id: The upload id of the removed.

Raises:

Exception: The delete upload request was unsuccessful.

delete_user_builtin_mcp(mcp_id: str) → dict

Delete a user builtin MCP by ID.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may remove any entry.

Args:: mcp_id: The ID of the MCP to delete (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with success message
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = client.delete_user_builtin_mcp("my_custom_builtin") print(result["message"]) # "MCP deleted successfully" `

delete_user_groups_by_ids(groups_ids: Iterable[str]) → Result

delete_user_groups_by_names(groups_names: Iterable[str]) → Result

delete_user_roles_by_ids(roles_ids: Iterable[str]) → Result

delete_user_roles_by_names(roles_names: Iterable[str]) → Result

disconnect_assistant_from_collection(assistant_id: str, collection_id: str) → None

Disconnect an AI assistant from a collection.

Args:: assistant_id: The assistant’s UUID. collection_id: The collection’s UUID.

disconnect_assistant_from_forum(assistant_id: str, forum_id: str) → None

Disconnect an AI assistant from a forum.

Args:: assistant_id: The assistant’s UUID. forum_id: The forum’s UUID.

disconnect_assistant_from_schedule(assistant_id: str, scheduled_task_id: str) → None

Disconnect an AI assistant from a scheduled task.

Args:: assistant_id: The assistant’s UUID. scheduled_task_id: The scheduled task’s UUID.

download_agent_tool_file(tool_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the file associated with a custom agent tool.

Args:: tool_id: The ID of the custom agent tool whose file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves the original filename from the tool metadata, falling back to "tool_file".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

download_ai_assistant_file(assistant_id: str, file_id: str, destination_directory: str | Path, destination_file_name: str) → Path

Downloads a file stored by an AI assistant to a local directory.

Args:: assistant_id: The assistant’s UUID. file_id: The file’s UUID. destination_directory: Destination directory to save the file into. destination_file_name: Destination file name.
Returns:: Path: Path of the downloaded file.

download_custom_agent_file(agent_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the zip file associated with a custom agent.

Args:: agent_id: The ID of the custom agent whose zip file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves to "<agent_name>.zip" from the agent metadata, falling back to "agent.zip".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

download_document(destination_directory: str | Path, destination_file_name: str, document_id: str) → Path

Downloads a document to a local system directory.

Args:

destination_directory:: Destination directory to save file into.
destination_file_name:: Destination file name.
document_id:: Document ID.

Returns:

Path: Path of downloaded document

download_library_skill(skill_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Download a library skill’s zip archive (requires ManageSkill).

Args:: skill_id: Library id of the skill. destination_directory: Directory to save the downloaded archive into. destination_file_name: Optional filename. Defaults to <skill_id>.zip.
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: destination_directory does not exist. FileExistsError: A file with the resolved name already exists.

Example:

path = client.download_library_skill("tabh2o-predict", ".")

download_reference_highlighting(message_id: str, destination_directory: str, output_type: str = 'combined', limit: int | None = None) → list

Get PDFs with reference highlighting

Args:

message_id:: ID of the message to get references from
destination_directory:: Destination directory to save files into.
output_type: str one of: "combined" Generates a PDF file for each source document, with all relevant chunks highlighted in each respective file. This option consolidates all highlights for each source document into a single PDF, making it easy to view all highlights related to that document at once. "split" Generates a separate PDF file for each chunk, with only the relevant chunk highlighted in each file. This option is useful for focusing on individual sections without interference from other parts of the text. The output files names will be in the format “{document_id}_{chunk_id}.pdf”
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list[Path]: List of paths of downloaded documents with highlighting

emit_event(assistant_id: str, event_type_name: str, payload: Dict[str, Any] | None = None, target_assistant_ids: List[str] | None = None) → Dict[str, Any]

Emit a custom event that wakes subscribed sleeping assistants.

This goes through the REST API which handles Redis wake event dispatch.

Args:: assistant_id: The emitting assistant’s UUID. event_type_name: Name of the event type to emit. payload: Optional event payload data. target_assistant_ids: Optional list of specific assistant IDs to target.
Returns:: dict: Response with ‘status’ and ‘woken_count’ keys.

encode_for_retrieval(chunks: Iterable[str], embedding_model: str | None = None) → List[List[float]]

Encode texts for semantic searching.

See Also: H2OGPTE.match for getting a list of chunks that semantically match each encoded text.

Args:

chunks:: List of strings of texts to be encoded.
embedding_model:: embedding model to use. call list_embedding_models() to list of options.

Returns:

List of list of floats: Each list in the list is the encoded original text.

export_feedback_csv(destination_directory: str | Path, destination_file_name: str = 'feedback_export.csv', collection_id: str | None = None, interval: str | None = None, no_collection: bool = False, filter: str | None = None, timeout: float | None = None) → Path

Export feedback data as CSV via job and save to disk.

Submits an export job, waits for completion, then downloads the CSV file to the specified directory.

Args:

destination_directory:: Destination directory to save the CSV file into.
destination_file_name:: Destination file name. Defaults to "feedback_export.csv".
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only export feedbacks with no collection.
filter:: Optional text to match against the question or response content.
timeout:: Timeout in seconds for the export job.

Returns:

Path: Path of the downloaded CSV file.

Extract information from one or more contexts using an LLM.

pre_prompt_extract and prompt_extract variables must be used together. If these variables are not set, the inputs texts will be summarized into bullet points.

Format of extract content:
"{pre_prompt_extract}"""
{text_context_list}
"""\n{prompt_extract}"
Examples:
extract = h2ogpte.extract_data(
    text_context_list=chunks,
    pre_prompt_extract="Pay attention and look at all people. Your job is to collect their names.\n",
    prompt_extract="List all people's names as JSON.",
)
Args:

text_context_list:
List of raw text strings to extract data from.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_extract:
Text that is prepended before the list of texts. If not set, the inputs will be summarized.

prompt_extract:
Text that is appended after the list of texts. If not set, the inputs will be summarized.

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: ExtractionAnswer: The list of text responses and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

finish_chat(question_id: str) → Result

Signal the LLM to complete its current thought and finish naturally.

Unlike stop_chat which immediately halts response generation, finish_chat allows the LLM to complete its current thought naturally, providing a more coherent ending.

Args:: question_id: The ID of the chat message/question to finish gracefully.
Returns:: Result: Status of the finish operation.
Raises:: Exception: If the user is not authorized to finish this chat or if the operation fails.

fork_chat_session(chat_session_id: str, message_id: str | None = None) → str

Fork a chat session, creating an independent copy with all messages, references, metadata, and document associations preserved.

When message_id is provided, only messages up to and including that message are copied (branch from a specific point in the conversation).

Args:: chat_session_id: The ID of the chat session to fork. message_id: Optional message ID to branch from.
Returns:: The ID of the newly created (forked) chat session.

generate_assistant_spec(prompt: str, llm: str | None = None, count: int | None = None) → Dict[str, Any]

Generate AI assistant configurations from a natural language prompt.

Uses an LLM with guided JSON mode to produce structured assistant specifications that map to every field in the create-assistant API.

Args:

prompt: Natural language description of the desired assistant(s).: For example: “Create an assistant that monitors sales data and sends daily email reports.”
llm: Optional LLM model override for generation. If not provided,: the system default model is used.
count: Optional number of assistant configurations to generate.: Defaults to the number implied by the prompt.

Returns:

A dictionary with keys:

assistants: list of spec dicts, each with keys name, description, system_prompt, llm, history_management, history_max_chars, history_recent_chars, history_retrieval_chars, notification_email, allowed_tool_actions, allowed_trigger_types, default_wake_period, auto_memory_block, auto_start.
passed: True only if the user’s prompt minimally described what the assistant should do; False if essential info was missing. Callers MUST NOT create any assistants when passed is False.
dialog: confirmation strategy — one of "none" (create directly), "text" (confirm in chat with a yes/no reply), or "ui" (open the full create-assistant form pre-filled from the spec). Always "text" when passed=False.
response: human-language message — a clarification ask if passed=False, otherwise keyed to dialog. May contain the literal tokens {artifact_url} and {artifact_name} which callers substitute post-creation.
llm_used: the model name that was actually used for generation.

The auto_start field is True only when the user explicitly asked the assistant to be started/run/launched.

Example:

result = client.generate_assistant_spec(
    "Create and start a sales monitoring assistant that wakes daily"
)
if not result["passed"]:
    print(result["response"])  # Show clarification ask
    return
for spec in result["assistants"]:
    aid = client.create_ai_assistant(
        name=spec["name"],
        llm=spec.get("llm", ""),
        description=spec.get("description", ""),
        system_prompt=spec.get("system_prompt", ""),
        history_management=spec.get("history_management", "truncation"),
        allowed_tool_actions=spec.get("allowed_tool_actions"),
        allowed_trigger_types=spec.get("allowed_trigger_types"),
    )
    if spec.get("auto_start"):
        client.start_ai_assistant(aid)

generate_scheduled_task_spec(prompt: str, llm: str | None = None, timezone: str | None = None, use_agent: bool | None = None) → Dict[str, Any]

Generate a scheduled task configuration from a natural language prompt.

Uses an LLM with guided JSON mode to produce a structured scheduled task spec that can be passed directly to the create_scheduled_task RPC.

Args:

prompt: Natural language description of the desired scheduled task.: For example: “Summarize the top AI news every weekday at 9am Eastern and send a digest to my email.”
llm: Optional LLM model override for generation. If not provided,: the system default model is used.
timezone: Optional IANA timezone string (e.g. "America/New_York"): used to compute today’s local date for relative expressions like “tomorrow” or “next Monday”. Defaults to UTC if not provided.
use_agent: When true, tells the generator that the user has agent: mode enabled in their chat. The LLM will then prefer task_type="agent_task" unless the prompt clearly describes a plain chat-completion task. Does not force the generated task_type.

Returns:

A dictionary with keys:

task: the generated spec dict with keys name, description, message, schedule_type, schedule_expression, task_type, timezone, max_executions, notification_email.
passed: True only if the user’s prompt minimally described the task to run; False if essential info was missing. Callers MUST NOT create the task when passed is False.
dialog: confirmation strategy — one of "none" (create directly), "text" (confirm in chat with a yes/no reply), or "ui" (open the full schedule-task form pre-filled from the spec). Always "text" when passed=False.
response: human-language message — a clarification ask if passed=False, otherwise keyed to dialog. May contain the literal tokens {artifact_url} and {artifact_name} which callers substitute post-creation.
llm_used: the model name that was actually used for generation.

schedule_type is one of "once", "recurring", "interval". schedule_expression is an ISO datetime for once, 5-field cron for recurring (e.g. "0 9 * * 1"), or "N minutes"/"N hours" for interval. task_type is "agent_task" for multi-step/tool-use work or "chat_completion" for straightforward LLM tasks. timezone is an IANA timezone string (e.g. "America/New_York"). max_executions is an integer or None for unlimited.

Example:

result = client.generate_scheduled_task_spec(
    "Every Monday at 9am Eastern, summarize last week's sales data "
    "from the sales-data collection and email the report to reports@example.com",
    timezone="America/New_York",
)
if not result["passed"]:
    print(result["response"])  # Show clarification ask
    return
spec = result["task"]
task_id = client.create_scheduled_task_for_assistant(
    assistant_id=my_assistant_id,
    name=spec["name"],
    message=spec["message"],
    schedule_type=spec["schedule_type"],
    schedule_expression=spec["schedule_expression"],
    max_executions=spec.get("max_executions"),
    notification_email=spec.get("notification_email", ""),
)

get_agent_key_tool_associations() → List[dict]

get_agent_keys() → List[dict]

get_agent_server_files(chat_session_id: str) → List[dict]

get_agent_suggestions(agent_id: str) → List[dict]

Gets MCP tool suggestions for a custom agent.

Returns suggested MCP tool configurations for a custom agent based on its metadata. Helps users identify and configure required tools.

Args:

agent_id: The unique identifier of the custom agent.

Returns:

List[dict]: A list of suggestion objects, each containing:

mcp_servers: List of MCP server suggestions with tool_name and tool_args

get_agent_tool_preference() → List[str]

get_agent_tools_dict() → dict

get_ai_assistant(assistant_id: str) → AiAssistant

Get details of an AI assistant.

Args:: assistant_id: The assistant’s UUID.
Returns:: AiAssistant: The assistant details.

get_ai_assistant_chat_history(assistant_id: str, offset: int = 0, limit: int = 10000) → str

Get the assistant’s full chat history as formatted text.

Returns the complete conversation history across all wake cycles as a plain-text string with question/reply pairs in chronological order.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset (default 0). limit: Maximum number of chat turns to return (default 10000).
Returns:: str: The full chat history as formatted text.

get_ai_assistant_event_history(assistant_id: str, offset: int = 0, limit: int = 100) → str

Get the assistant’s event history as formatted text.

Returns event/activity log entries with timestamps, event types, trigger details, and wake cycle numbers.

Pagination is newest-first. The underlying RPC orders events created_at DESC and caps each page at 100. Within a single returned page the entries are rendered oldest-first for readability, but walking via offset += limit traverses BACKWARD in time (each successive page is older than the last). To assemble a complete chronological log, fetch all pages and reverse the page order before concatenating.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset (default 0). limit: Maximum events per page; capped at 100 server-side

(default 100). Values above 100 are clamped silently.
Returns:: str: A page of the event history as formatted text.

get_all_agents() → List[dict]

Gets all agents (both built-in and custom) for the current user.

Returns:

List[dict]: A list of all agents with unified structure.: Each agent contains: id, value, label, enabled, type, owner, description, api_keys (grouped by optional/required/custom), and mcp_servers (for custom agents)

get_all_directory_stats(chat_session_id: str, detail_level: int = 0) → dict

get_audio_timestamps(document_id: str) → List[AudioSegment]

Get exact per-segment speaker timestamps for an audio/video transcript document.

Returns the speaker-segment timing captured from diarization at ingest — the authoritative source for time-indexed transcript workflows. Each segment carries its exact start/end times (seconds), speaker label, and text.

Args:

document_id:: String id of the audio/video document.

Returns:

List[AudioSegment]: One entry per speaker segment, in transcript order. Empty for non-transcript documents and documents ingested before timestamps were captured.

get_chat_session_guardrails(chat_session_id: str) → str

Get guardrails settings for a specific chat session.

Args:

chat_session_id:: ID of the chat session

Returns:

str: JSON string containing guardrails settings or “null” if not set

get_chat_session_prompt_template(chat_session_id: str) → PromptTemplate | None

Get the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session

Returns:

str: ID of the prompt template.

get_chat_session_questions(chat_session_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

chat_session_id:: A chat session ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

get_chat_session_workspace(chat_session_id: str) → str

Get the workspace associated with the chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

str: The identifier of the workspace

get_chunks(collection_id: str, chunk_ids: Iterable[int]) → List[Chunk]

Get the text of specific chunks in a collection.

Args:

collection_id:: String id of the collection to search in.
chunk_ids:: List of ints for the chunks to return. Chunks are indexed starting at 1.

Returns:

Chunk: The text of the chunk.

Raises:

Exception: One or more chunks could not be found.

get_collection(collection_id: str) → Collection

Get metadata about a collection.

Args:

collection_id:: String id of the collection to search for.

Returns:

Collection: Metadata about the collection.

Raises:

KeyError: The collection was not found.

get_collection_for_chat_session(chat_session_id: str) → Collection

Get metadata about the collection of a chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

Collection: Metadata about the collection.

get_collection_graph_status(collection_id: str) → GraphStatus

Get the knowledge graph build status for a collection.

Args:

collection_id:: String id of the collection.

Returns:

GraphStatus object with status (‘none’, ‘building’, ‘ready’, ‘failed’) and built_at timestamp if the graph has been built.

get_collection_prompt_template(collection_id: str) → PromptTemplate | None

Get the prompt template for a collection

Args:

collection_id:: ID of the collection

Returns:

str: ID of the prompt template.

get_collection_questions(collection_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

collection_id:: A collection ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

get_connector_status() → ConnectorStatus

Return connector availability and the caller’s existing links.

Returns:: ConnectorStatus: available lists the connector types the server is configured for; connected lists the caller’s current links.

get_custom_agent(agent_id: str) → dict

Gets a single custom agent by ID for the current user.

Args:

agent_id: The unique identifier of the agent to retrieve.

Returns:

dict: A custom agent with details including: id, agent_name, agent_type,: agent_args, owner_email, mcp_servers, api_keys

Raises:

NotFoundError: If the agent is not found or not owned by the user

get_custom_agent_tool(tool_id: str) → dict

Gets a single custom agent tool by ID for the current user.

Args:

tool_id: The unique identifier of the tool to retrieve.

Returns:

dict: A custom agent tool with details including: id, tool_name,: tool_type, tool_args, owner_email, file_name

Raises:

NotFoundError: If the tool is not found or not owned by the user

get_custom_agent_tools() → List[dict]

Gets all custom agent tools for the current user.

Returns:

List[dict]: A list of custom agent tools with their details.: Each tool contains: id, tool_name, tool_type, tool_args, owner_email

get_custom_agents() → List[dict]

Gets all custom agents for the current user.

Returns:

List[dict]: A list of custom agents with their details.: Each agent contains: id, agent_name, agent_type, agent_args, owner_email, resolved_tool_mapping

get_default_collection() → CollectionInfo

Get the default collection, to be used for collection API-keys.

Returns:: CollectionInfo: Default collection info.

get_default_memory_blocks() → dict

Get the current user’s default memory blocks.

Returns a dict with key 'defaults' containing a dict with keys 'llm' and 'agent', each either a memory block dict or None.

The two scopes are independent — LLM default applies to non-agent chats, agent default applies to agent chats. No cascade between them.

Example:

result = client.get_default_memory_blocks()
# result['defaults']['llm']    -> MemoryBlock dict or None
# result['defaults']['agent']  -> MemoryBlock dict or None

get_directory_stats(directory_name: str, chat_session_id: str, detail_level: int = 0) → dict

get_document(document_id: str, include_layout: bool = False) → Document

Fetches information about a specific document.

Args:

document_id:: String id of the document.
include_layout:: Include the layout prediction results.

Returns:

Document: Metadata about the Document.

Raises:

KeyError: The document was not found.

get_document_content(file_name: str, document_id: str) → bytes

Downloads a document and return its content as a byte array.

Args:

file_name:: File name.
document_id:: Document ID.

Returns:

Path: File content

get_effective_guardrails(chat_session_id: str | None = None, collection_id: str | None = None) → str

Get the effective guardrails settings based on the hierarchy.

Args:

chat_session_id:: Optional chat session ID to check for chat-level settings
collection_id:: Optional collection ID to check for collection-level settings

Returns:

str: JSON string containing effective guardrails settings

get_event_type(event_type_id: str) → AiAssistantEventType

Get a custom event type by ID.

Args:: event_type_id: The event type’s UUID.
Returns:: AiAssistantEventType: The event type.

get_extractor(extractor_id: str) → Extractor

Fetches an extractor by its ID.

Args:: extractor_id: The ID of the extractor to retrieve.
Returns:: Extractor: Details of the extractor.
Raises:: UnauthorizedError: If the extractor does not exist or is not visible to the caller. InvalidArgumentError: If extractor_id is not a uuid.

get_forum(forum_id: str) → Forum

Get details of a forum.

Args:: forum_id: The forum’s UUID.
Returns:: Forum: The forum details.

get_forum_post(post_id: str) → ForumPost

Get a single forum post.

Args:: post_id: The post’s UUID.
Returns:: ForumPost: The post details.

get_global_configurations() → List[GlobalConfigItem]

get_global_configurations_by_admin() → List[GlobalConfigItem]

get_guardrails_settings(action: str = 'redact', sensitive: bool = True, non_sensitive: bool = True, all_guardrails: bool = True, guardrails_settings: dict | None = None) → Dict[str, str | List[str]]: Helper to get reasonable (easy to use) defaults for Guardrails/PII settings. To be further customized. :param action: what to do when detecting PII, either “redact” or “fail” (“allow” would keep PII intact). Guardrails models always fail upon detecting safety violations. :param sensitive: whether to include the most sensitive PII entities like SSN, bank account info :param non_sensitive: whether to include all non-sensitive PII entities, such as IP addresses, locations, names, e-mail addresses etc. :param all_guardrails: whether to include all possible entities for prompt guard and guardrails models, or just system defaults :param guardrails_settings: existing guardrails settings (e.g., from collection settings) to obtain guardrails entities, guardrails_entities_to_flag, column redaction custom_pii_entities, column_redaction_pii_to_flag from instead of system defaults :return: dictionary to pass to collection creation or process_document method

get_h2ogpt_system_stats() → dict

get_job(job_id: str) → Job

Fetches information about a specific job.

Args:

job_id:: String id of the job.

Returns:

Job: Metadata about the Job.

get_llm_and_auto_reasoning_llm_names() → Dict[str, str]

Get mapping of llm to its reasoning_model when [“auto”] is passed as visible_reasoning_models

Returns:: dictionary {‘llm1’: ‘llm1_reasoning_llm’, etc.}

get_llm_and_auto_vision_llm_names() → Dict[str, str]

Get mapping of llm to its vision_model when [“auto”] is passed as visible_vision_models

Returns:: dictionary {‘llm1’: ‘llm1_vision_llm’, etc.}

get_llm_name_for_rest(llm: str | int | None)

get_llm_names() → List[str]

Lists names of available LLMs in the environment.

Returns:: list of string: Name of each available model.

get_llm_performance_by_llm(interval: str) → List[LLMPerformance]

get_llm_usage_24h() → float

get_llm_usage_24h_by_llm() → List[LLMUsage]

get_llm_usage_24h_with_limits() → LLMUsageLimit

get_llm_usage_6h() → float

get_llm_usage_6h_by_llm() → List[LLMUsage]

get_llm_usage_by_llm(interval: str) → List[LLMUsage]

get_llm_usage_by_llm_and_user(interval: str) → List[LLMWithUserUsage]

get_llm_usage_by_user(interval: str) → List[UserWithLLMUsage]

get_llm_usage_with_limits(interval: str) → LLMUsageLimit

get_llms() → List[Dict[str, Any]]

Lists metadata information about available LLMs in the environment.

Returns:: list of dict (string, ANY): Name and details about each available model.

get_mcp_sdk_options() → dict

Get the schema of available Claude SDK options for MCP tool runners.

Returns:

dict: Schema with keys:

sdk_options_schema: Full ClaudeSdkAdvancedOptions JSON schema
permission_modes: List of valid permission mode strings
effort_levels: List of valid effort level strings
available_betas: List of available beta feature flags
hook_actions: List of valid hook action strings
hook_events: List of valid hook event strings
limitations: Dict of partially implemented features

Example:

`python schema = client.get_mcp_sdk_options() print("Permission modes:", schema.get("permission_modes")) print("Effort levels:", schema.get("effort_levels")) `

get_memory_block(memory_block_id: str) → MemoryBlock

Fetch a single memory block by id.

Args:

memory_block_id:: ID of the memory block to fetch.

Returns:

MemoryBlock: The requested memory block.

get_meta() → Meta

Returns information about the environment and the user.

Returns:: Meta: Details about the version and license of the environment and the user’s name and email.

get_prompt_template(id: str | None = None) → PromptTemplate

Get a prompt template

Args:

id:: String id of the prompt template to retrieve or None for default

Returns:

PromptTemplate: prompts

Raises:

KeyError: The prompt template was not found.

get_reasoning_capable_llm_names() → List[str]

Lists names of available reasoning-capable (that can natively reason) in the environment.

Returns:: list of string: Name of each available model.

get_role_llm_access(role_id: str) → List[Dict[str, Any]]: Return a role’s LLM access grants as [{“display_name”, “granted”}] (requires manage-roles).

get_scheduled_task(task_id: str) → ScheduledTask: Get a scheduled task by id.

get_scheduled_task_execution_stats(interval: str = '7 days') → ScheduledTaskExecutionStats: Execution stats over a PostgreSQL interval (admin only).

get_scheduled_task_summary() → ScheduledTaskSummary: Aggregate stats for the current user’s scheduled tasks.

get_scheduled_task_summary_by_admin() → ScheduledTaskAdminSummary: System-wide scheduled task summary (admin only).

get_scheduler_stats() → SchedulerStats

Count the number of global, pending jobs on the server.

Returns:: SchedulerStats: The queue length for number of jobs.

get_secret(secret_id: str) → Dict[str, Any] | None

Get a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret object corresponding to the provided ID.

get_secret_value(secret_id: str) → Dict[str, Any] | None

Get the value of a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret value (a dictionary of credentials and configuration) corresponding to the provided ID, or None if it is empty.

get_shared_chat(shared_chat_id: str) → SharedChatDetail

Get a shared chat by its ID.

Args:

shared_chat_id:: ID of the shared chat to retrieve.

Returns:

SharedChatDetail: Shared chat data including messages and metadata.

get_skill_associations() → List[SkillAssociations]

List the current user’s skill env-var→key and target-tool associations.

Returns:: List[SkillAssociations]: One entry per skill that has any association, with its env-var→key bindings and the tools that receive its env vars.

get_skills(offset: int = 0, limit: int = 100, query: str = None) → List[Skill]

List agent skills for the current user.

Args:: offset: How many skills to skip before returning. Default is 0. limit: How many skills to return. Default is 100. query: Optional case-insensitive substring filter on the skill

name. When provided, only skills whose name contains the substring are returned (and the total count reflects the filtered set).
Returns:: List[Skill]: List of skill objects.

Example:

skills = client.get_skills(query="summar")
for s in skills:
    print(s.skill_name, s.description)

get_tag(tag_name: str) → Tag

Returns an existing tag.

Args:

tag_name:: String The name of the tag to retrieve.

Returns:

Tag: The requested tag.

Raises:

KeyError: The tag was not found.

get_user_all_agent_directories(offset: int, limit: int, filter_text: str | None) → List[dict]

get_user_approval_config(user_id: str) → UserApprovalConfig

Get approval governance config for a user. Admin-only.

Args:: user_id: The target user’s UUID.
Returns:: UserApprovalConfig: The approval governance configuration.

get_user_configurations() → List[ConfigItem]

Gets the user configurations for the current user.

Returns:: List[ConfigItem]: List of user configurations.

get_user_configurations_for_user(user_id: str) → List[ConfigItem]

Gets the user configurations for a specific user (to be used by admins only).

Args:

user_id:: The unique identifier of the user.

Returns:

List[ConfigItem]: List of user configurations.

get_vision_capable_llm_names() → List[str]

Lists names of available vision-capable multi-modal LLMs (that can natively handle images as input) in the environment.

Returns:: list of string: Name of each available model.

Import all documents from a collection into an existing collection

Args:

collection_id:: Collection ID to add documents to.
src_collection_id:: Collection ID to import documents from.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_document_status:: Whether to preserve each document’s original ingest mode (agent_only vs standard) when importing. When True, documents with agent_only status remain agent_only in the target collection. When False, all documents use the ingest_mode parameter uniformly.
preserve_metadata:: Whether to preserve the documents’ existing metadata when importing.
migrate_scheduled_connectors:: Whether to move scheduled connectors from source collection to target collection after documents are imported. The source collection will have no scheduled connectors after this operation. Only the owner of both collections can use this flag.
copy_lifecycle_settings:: Whether to copy lifecycle settings (expiry_date, inactivity_interval, size_limit) from the source collection to the target collection.
skip_reparse:: Whether to skip re-parsing documents and only re-embed existing chunks with the target collection’s embedding model. Much faster than full import since it skips file fetch, PDF conversion, OCR, and chunking. Only re-embeds the text chunks. Cannot be combined with copy_document=True.

Import an already stored document to an existing collection

Args:

collection_id:: Collection ID to add documents to.
document_id:: Document ID to add.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_metadata:: Whether to preserve the document’s existing metadata when importing.

ingest_agent_only_to_standard(collection_id: str, document_id: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, timeout: float | None = None)

For files uploaded in “agent_only” ingest mode, convert to PDF and parse

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:: String id of the collection to add the ingested documents into.
document_id:: ID of document to be parsed.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
restricted:: Whether the document should be restricted only to certain users.
permissions:: List of permissions. Each permission is a SharePermission object.
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.

Add files from the Azure Blob Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
container:: Name of the Azure Blob Storage container.
path:: Path or list of paths to files or directories within an Azure Blob Storage container. Examples: file1, dir1/file2, dir3/dir4/
account_name:: Name of a storage account
credentials:: The object with Azure credentials. If the object is not provided, only a public container will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Metadata to be associated with the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Ingests confluence pages into collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
base_url:: Url of confluence instance. Example: https://h2oai.atlassian.net/wiki
page_id:: The page id or ids of pages to be ingested.
credentials:: The object with Confluence credentials.
include_attachments:: A flag indicating whether to also ingest attachments with the page.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the local system into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
root_dir:: String path of where to look for files.
glob:: String of the glob pattern used to match files in the root directory.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the Google Cloud Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of GCS files or directories. Examples: gs://bucket/file, gs://bucket/../dir/
credentials:: The object holding a path to a JSON key of Google Cloud service account. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

ingest_from_plain_text(collection_id: str, plain_text: str, file_name: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None)

Add plain text to a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
plain_text:: String of the plain text to ingest.
file_name:: String of the file name to use for the document.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds

Add files from the AWS S3 storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of S3 files or directories. Examples: s3://bucket/file, s3://bucket/../dir/
region:: The name of the region used for interaction with AWS services.
credentials:: The object with S3 credentials. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

ingest_from_sharepoint_online(collection_id: str, entries: Sequence[SharepointOnlineEntry], credentials: SharepointOnlineAppCredentials | SharepointOnlineUserCredentials, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None)

Add files from SharePoint Online into a collection.

Supports both site/drive/folder/file entries and the drive_by_id entry type for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites — see issue #10695), mixed freely in a single call.

Args:

collection_id: String id of the collection to add the: ingested documents into.
entries: Sequence of SharepointOnlineEntry to ingest.: See the class docstring for entry-type semantics — including "drive_by_id" for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites).
credentials: Either SharepointOnlineAppCredentials: (application permissions) or SharepointOnlineUserCredentials (OAuth delegated).

gen_doc_summaries: Whether to auto-generate document summaries. gen_doc_questions: Whether to auto-generate sample questions. audio_input_language: Spoken-language hint for audio files. ocr_model: OCR model for image text extraction. tesseract_lang: Tesseract language for ocr_model='tesseract'. keep_tables_as_one_chunk: Keep parsed table tokens in a single

chunk.

chunk_by_page: Make each page its own chunk. handwriting_check: Use specialized models when handwriting is

detected.

metadata: Metadata to associate with the document. timeout: Timeout in seconds. ingest_mode: Ingest mode ("standard", "lite",

"agent_only").

ingest_uploads(collection_id: str, upload_ids: Iterable[str], gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None, encrypt_document: bool | None = None, callback: Callable[[Job], None] | None = None) → Job

Add uploaded documents into a specific collection.

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:

String id of the collection to add the ingested documents into.

upload_ids:

List of string ids of each uploaded document to add to the collection.

gen_doc_summaries:

Whether to auto-generate document summaries (uses LLM)

gen_doc_questions:

Whether to auto-generate sample questions for each document (uses LLM)

audio_input_language:

Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.

ocr_model:

Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

restricted:

Whether the document should be restricted only to certain users.

permissions:

List of permissions. Each permission is a SharePermission object.

tesseract_lang:

Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.

keep_tables_as_one_chunk:

When tables are identified by the table parser the table tokens will be kept in a single chunk.

chunk_by_page:

Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.

handwriting_check:

Check pages for handwriting. Will use specialized models if handwriting is found.

metadata:

Dictionary mapping upload_ids to their metadata. Each key must be an upload_id from the upload_ids list, and each value is a dictionary of metadata key-value pairs to associate with that document.

Example:

# Single document
metadata = {upload_id: {"category": "reports", "year": "2024"}}

# Multiple documents
metadata = {
    upload_id_1: {"category": "reports"},
    upload_id_2: {"category": "invoices"}
}

timeout:

Timeout in seconds.

ingest_mode:

Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

encrypt_document:

Whether to encrypt the document files at rest in object storage.

callback:

Function for processing job status info during the upload.

Crawl and ingest a URL into a collection.

The web page or document linked from this URL will be imported.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: String of the url to crawl.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
follow_links:: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document.
max_depth:: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings).
max_documents:: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit).
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

insert_command_synth_pair(chat_session_id: str, user_prompt: str, ai_response: str, command_name: str) → Dict[str, Any]

Persist a synthetic user prompt + AI response pair into a chat session.

Args:

chat_session_id: The ID of the chat session to attach the pair to.: The caller must own the session.

user_prompt: The user-authored prompt that triggered the command. ai_response: The LLM-generated response (e.g. from generate_spec). command_name: Slash-command identifier, e.g. "schedule" or

"create-assistant". Stored in chat_message_meta with message_type="command_synth" so UIs can distinguish these turns from regular LLM turns.

Returns:

A dictionary with keys:

question_id: UUID of the inserted question turn.
reply_id: UUID of the inserted reply turn.

Raises:

ObjectNotFoundError: when the chat session does not exist or is: not owned by the caller (mapped from the RPC’s 30404 errcode).

Example:

ids = client.insert_command_synth_pair(
    chat_session_id=session_id,
    user_prompt="schedule a daily 9pm report",
    ai_response="Scheduled a daily report at 21:00 UTC.",
    command_name="schedule",
)
print(ids["question_id"], ids["reply_id"])

inspect_mcp_tool(tool_id: str | None = None, servers: dict | None = None, file_path: str | None = None, model: str | None = None) → dict

Unified MCP tool inspection.

Supports three modes (provide exactly one): 1. tool_id — inspect an existing local or remote MCP tool by its ID. 2. servers — inspect one or more remote MCP server configs (pre-add). 3. file_path — inspect an uploaded MCP package file (pre-add).

Args:

tool_id: ID of an existing MCP tool to inspect. servers: Dict mapping server names to config dicts for pre-add inspection. file_path: Path to an MCP package file (.py, .zip, .tar.gz) for pre-add inspection. model: Optional LLM model for security inspection.

Returns:

dict: Unified result with keys:

status: ‘success’ or ‘error’
servers: List of per-server inspection result dicts
error: Top-level error message if status is ‘error’

Example:

```python # Inspect an existing tool result = client.inspect_mcp_tool(tool_id=”abc-123”) for srv in result[“servers”]:

print(f”{srv[‘server_name’]}: {srv[‘tool_count’]} tools”)

# Inspect a remote config before adding result = client.inspect_mcp_tool(

servers={“playwright”: {“command”: “npx”, “args”: [“@playwright/mcp@latest”]}}

install_library_skill(skill_id: str, enable_by_default: bool = False) → str

Install a library skill into the caller’s own skills.

Args:: skill_id: Library id of the skill (LibrarySkill.id). enable_by_default: Whether to enable the skill right away.
Returns:: str: The created agent_skill id (use with delete_skills).
Raises:: H2OGPTEError: The install returned no skill id.

Example:

user_skill_id = client.install_library_skill("tabh2o-predict")
client.delete_skills([user_skill_id])  # uninstall

is_collection_permission_granted(collection_id: str, permission: str) → bool

is_permission_granted(permission: str) → bool

launch_custom_agent_tool(tool_id: str) → dict

Launch a custom agent tool via CodeAPI.

Args:: tool_id: The ID of the tool to launch.
Returns:: Dict with codeapi_job_id and codeapi_url.

link_slack_channel(integration_id: str, channel_id: str, channel_name: str = '', forum_name: str = '', sync_direction: str = 'bidirectional', sync_threads: bool = True) → Dict[str, Any]

Link a Slack channel to a forum.

Creates a new forum backed by the Slack channel. Messages in Slack appear as forum posts, and assistant posts appear in Slack.

Args:: integration_id: ID of the Slack integration. channel_id: Slack channel ID (e.g., C01234567). channel_name: Display name of the channel. forum_name: Name for the h2ogpte forum (defaults to channel name). sync_direction: ‘bidirectional’, ‘slack_to_h2ogpte’, or ‘h2ogpte_to_slack’. sync_threads: Whether to sync Slack threads as forum post threads.
Returns:: Dict with channel-forum mapping details.

list_ai_assistant_files(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantFile]

List files stored by an AI assistant.

Args:

assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).

Returns:

List[AiAssistantFile]: List of file metadata objects with: file_id, created_at, and source fields.

list_ai_assistant_permissions(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantPermission]

List sharing permissions for an AI assistant.

Args:

assistant_id: The assistant’s UUID. offset: Number of records to skip (default 0). limit: Maximum number of records to return (default 100, max 100).

Returns:

List[AiAssistantPermission]: List of permission objects with: username, can_read, can_edit fields.

list_ai_assistants(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None) → List[AiAssistant]

List AI assistants accessible to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results. name_filter: Optional name filter (substring match). status_filter: Optional status filter (‘stopped’, ‘running’, ‘sleeping’, ‘error’).
Returns:: List[AiAssistant]: List of assistants.

list_all_api_keys(offset: int, limit: int, key_filter: str = '') → List[APIKey]

Allows admins to list all the API keys that exist.

Args:

offset:: Int: How many keys to skip before returning.
limit:: Int: How many keys to return.
key_filter:: String: Only returns keys for usernames matching this filter.

Returns:

List[APIKey]: List of APIKeys with metadata about each key.

list_all_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[CollectionInfo]

Fetch all users’ collection metadata sorted by last update time.

This is for admin use only and includes private, public, and shared collections in the result.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return collections matching by name, id, or username.

Returns:

list of CollectionInfo: Metadata about each collection.

list_all_jobs() → List[UserJobs]

List all jobs (to be used by admins only).

Returns:: list of UserJobs

list_all_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

list_all_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

list_all_tags(linked_only: bool = False, user_scope: bool = False) → List[Tag]

Lists all existing tags.

Args:

linked_only:: When True, returns only tags associated with at least one document. Default is False, which returns all tags.
user_scope:: When True, scopes results to the current user: tags from the user’s accessible documents, plus tags the user created. Combined with linked_only=True, excludes the user’s unlinked tags. Default is False.

Returns:

List of Tags: List of existing tags.

list_all_user_scheduled_task_executions(offset: int = 0, limit: int = 100, status_filter: str | None = None, name_filter: str | None = None, time_interval: str | None = None, trigger_filter: str | None = None) → ScheduledTaskExecutionList

List executions across all of the current user’s tasks (paginated).

Optionally filter by execution status, task-name substring, a relative time window (e.g. ‘1 day’, ‘7 days’, ‘1 month’), and trigger source (‘scheduled’ or ‘manual’).

list_approvals_routed_to_me(offset: int = 0, limit: int = 50) → List[ApprovalRequestWithAssistant]

List pending approval requests routed to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List of approval requests routed to the current user.

list_archived_chat_sessions(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[ChatSessionInfo]

List archived chat sessions.

Admin-only. Returns chat sessions that have been archived by the expiry sweep or manually by an admin.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
sort_column:: Sort column. One of: name, updated_at, archived_at, username, collection_name.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return sessions matching by name, id, collection name, or username.

Returns:

list of ChatSessionInfo: Metadata about each archived chat session.

list_assistant_collections(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantCollectionLink]

List collections connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantCollectionLink]: List of collection connections.

list_assistant_event_subscriptions(assistant_id: str) → List[AiAssistantEventSubscription]

List an assistant’s event type subscriptions.

Args:: assistant_id: The assistant’s UUID.
Returns:: List[AiAssistantEventSubscription]: List of subscriptions.

list_assistant_events(assistant_id: str, offset: int = 0, limit: int = 50, event_type: str | None = None, since: datetime | None = None) → List[AiAssistantEvent]

List wake/sleep events for an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results. event_type: Optional event type filter (‘wake’, ‘sleep’, ‘error’, ‘start’, ‘stop’, ‘compactify’, ‘memory_index’). since: Optional cutoff timestamp — only return events created

after this time. Defaults to 2 years on the server side.
Returns:: List[AiAssistantEvent]: List of events.

list_assistant_forums(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantForumLink]

List forums connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantForumLink]: List of forum connections.

list_assistant_messages(assistant_id: str, offset: int = 0, limit: int = 50, since: datetime | None = None) → List[AiAssistantMessage]

List direct messages for an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results. since: Optional cutoff timestamp — only return messages created

after this time. Defaults to 2 years on the server side.
Returns:: List[AiAssistantMessage]: List of messages.

list_assistant_schedules(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantScheduleLink]

List scheduled tasks connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantScheduleLink]: List of schedule connections.

list_assistant_webhooks(assistant_id: str) → List[Dict[str, Any]]

List webhooks for an AI assistant (tokens are masked).

Args:: assistant_id: ID of the assistant.
Returns:: List of webhook dicts with masked tokens.

list_builtin_mcps() → dict

List built-in MCPs (Model Context Protocol servers) available for use.

Returns a dictionary with two lists: - oauth_apps: List of OAuth-based MCP applications - api_key_apps: List of API key-based MCP applications

Each MCP includes information about whether it’s already added as a tool and whether the related OAuth connector is connected.

Returns:: dict: Dictionary containing ‘oauth_apps’ and ‘api_key_apps’ lists

list_chat_message_meta_part(message_id: str, info_type: str) → ChatMessageMeta

Fetch one chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.
info_type:: Metadata type to fetch. Valid choices are: “self_reflection”, “usage_stats”, “prompt_raw”, “llm_only”, “hyde1”, “py_client_code”

Returns:

ChatMessageMeta: Metadata information about the chat message.

list_chat_message_references(message_id: str, limit: int | None = None) → List[ChatMessageReference]

Fetch metadata for references of a chat message.

References are only available for messages sent from an LLM, an empty list will be returned for messages sent by the user.

Args:

message_id:: String id of the message to get references for.
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list of ChatMessageReference: Metadata including the document name, polygon information, and score.

list_chat_messages(chat_session_id: str, offset: int, limit: int) → List[ChatMessage]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessage: Text and metadata for chat messages.

list_chat_messages_full(chat_session_id: str, offset: int, limit: int) → List[ChatMessageFull]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessageFull: Text and metadata for chat messages.

list_chat_sessions_for_collection(collection_id: str, offset: int, limit: int, username: str | None = None) → List[ChatSessionForCollection]

Fetch chat session metadata for chat sessions in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
username:: Optional username to filter chat sessions by owner.

Returns:

list of ChatSessionForCollection: Metadata about each chat session including the latest message.

list_chat_sessions_for_document(document_id: str, offset: int, limit: int) → List[ChatSessionForDocument]

Fetch chat session metadata for chat session that produced a specific document (typically through agents).

Args:

document_id:: String id of the document to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionForDocument: Metadata about each chat session including the latest message.

list_collection_group_permissions(collection_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given collection.

The returned list of group permissions denoting which groups have access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given collection.

list_collection_permissions(collection_id: str) → List[SharePermission]

Returns a list of access permissions for a given collection.

The returned list of permissions denotes who has access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given collection.

list_collection_public_permissions(collection_id: str) → List[str]

Returns the public permissions for a given collection.

The returned list contains the permission strings that apply to public access of the collection.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of str: Public permissions list for the given collection.

list_collections_for_document(document_id: str, offset: int, limit: int) → List[CollectionInfo]

Fetch metadata about each collection the document is a part of.

At this time, each document will only be available in a single collection.

Args:

document_id:: String id of the document to search for.
offset:: How many collections to skip before returning.
limit:: How many collections to return.

Returns:

list of CollectionInfo: Metadata about each collection.

list_connectors(connector_type: str | None = None) → List[UserConnector]

List the caller’s linked connectors.

Args:

connector_type:: Optional filter, e.g. "github", "confluence", "sharepoint", or "snowflake". When None (default), all of the caller’s connectors are returned.

Returns:

List[UserConnector]: The caller’s connectors.

list_custom_agent_key_associations(agent_id: str | None = None) → List[dict]

Lists custom agent key associations, optionally filtered by agent_id.

Args:

agent_id: Optional agent UUID to filter by

Returns:

List[dict]: Association objects with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

list_custom_agent_tool_associations(agent_id: str | None = None, agent_name: str | None = None) → List[dict]

Lists custom agent tool associations, optionally filtered by agent_id or agent_name.

Args:: agent_id: Optional agent UUID to filter by agent_name: Optional agent name to filter by
Returns:: List[dict]: A list of association objects with agent_id, agent_name, tool_id, tool_name, mcp_server_name, etc.

list_document_chunks(document_id: str, collection_id: str | None = None) → List[SearchResult]

Returns all chunks for a specific document.

Args:

document_id:: ID of the document.
collection_id:: ID of the collection the document belongs to. If not specified, an arbitrary collections containing the document is chosen.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

list_documents_from_tags(collection_id: str, tags: List[str]) → List[Document]

Lists documents that have the specified set of tags within a collection. Args:

collection_id:
String The id of the collection to find documents in.

tags:
List of Strings representing the tags to retrieve documents for.

Returns:: List of Documents: All the documents with the specified tags.

list_documents_in_collection(collection_id: str, offset: int, limit: int, metadata_filter: dict = {}) → List[DocumentInfo]

Fetch document metadata for documents in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.

Returns:

list of DocumentInfo: Metadata about each document.

list_embedding_models() → List[str]

list_event_types(assistant_id: str | None = None, offset: int = 0, limit: int = 100) → List[AiAssistantEventType]

List custom event types.

Args:: assistant_id: Optional assistant ID to include subscription status for. offset: Pagination offset. limit: Maximum number of results.
Returns:: List[AiAssistantEventType]: List of event types.

list_extractor_group_permissions(extractor_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given extractor.

The returned list of group permissions denoting which groups have access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given extractor.

list_extractor_permissions(extractor_id: str) → List[SharePermission]

Returns a list of access permissions for a given extractor.

The returned list of permissions denotes who has access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given extractor.

list_extractor_results(extractor_id: str, job_id: str | None = None, offset: int | None = None, limit: int | None = None) → List[DocumentExtractionResult]

Retrieve extraction results produced by this extractor.

If job_id is specified, returns results for that specific extraction run. If job_id is omitted, returns all results produced by this extractor across all runs.

Args:

extractor_id:: String ID of the extractor.
job_id:: Optional job ID to retrieve results for a specific extraction run. If omitted, returns all results for this extractor.
offset:: Optional number of extraction results to skip before returning. Defaults to 0 if not specified.
limit:: Optional maximum number of extraction results to return. If not specified, returns all results.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ObjectNotFoundError: If the extractor is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor.

list_extractors(offset: int | None = None, limit: int | None = None, name_filter: str | None = None) → List[Extractor]

Lists available extractors.

Args:: offset: Number of extractors to skip. Defaults to server-side default (0). limit: Maximum number of extractors to return. Defaults to server-side default. name_filter: Filter extractors by name.
Returns:: List[Extractor]: A list of available extractors.

list_forum_permissions(forum_id: str, offset: int = 0, limit: int = 100) → List[ForumPermission]

List sharing permissions for a forum.

Args:

forum_id: The forum’s UUID. offset: Number of records to skip (default 0). limit: Maximum number of records to return (default 100, max 100).

Returns:

List[ForumPermission]: List of permission objects with: username, can_read, can_edit fields.

list_forum_posts(forum_id: str, offset: int = 0, limit: int = 50, sort_by: str = 'newest', parent_post_id: str | None = None, since: datetime | None = None) → List[ForumPost]

List posts in a forum.

Args:: forum_id: The forum’s UUID. offset: Pagination offset. limit: Maximum number of results. sort_by: Sort order (‘top’, ‘newest’, or ‘oldest’). parent_post_id: Filter to replies of a specific post. since: Optional cutoff timestamp — only return posts created

after this time.
Returns:: List[ForumPost]: List of posts.

list_forums(offset: int = 0, limit: int = 100, name_filter: str | None = None) → List[Forum]

List forums accessible to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results. name_filter: Optional name filter (substring match).
Returns:: List[Forum]: List of forums.

list_group_permissions(group_id: str) → List[UserPermission]

list_group_permissions_by_name(group_names: List[str]) → List[UserPermission]

list_group_roles(group_id: str) → List[UserRole]

list_jobs() → List[Job]

List the user’s jobs.

Returns:: list of Job:

List job history (admin only), newest first, keyset-paginated.

Args:

cursor_created_at, cursor_id:: The next_cursor_* values from a previous page. Omit for the first page.
limit:: Max rows per page (default 50, hard-capped at 200 server-side).
status:: Optional list of statuses to filter by (queued, running, completed, failed, canceled, timeout, stale, unknown).
kind:: Optional exact job-kind filter.
user_id:: Optional owning-user filter.
collection_id:: Optional filter by the collection the job operated on.
created_after:: Lower bound on created_at. Defaults to the last 7 days when omitted; how far back data exists is bounded by the server’s retention setting (at most 365 days).

Returns:

JobHistoryPage: the page of rows plus the next-page cursor.

list_library_skills() → List[LibrarySkill]

List the skill library catalog (predefined + admin-published).

Visible to all users. Entries carry the caller’s install state (is_skill_added, user_skill_id) and popularity counters (install_count, star_count, is_starred_by_me).

Returns:: List[LibrarySkill]: The library catalog entries.

Example:

skills = client.list_library_skills()
for s in skills:
    print(s.id, s.skill_name, s.star_count)

list_list_chat_message_meta(message_id: str) → List[ChatMessageMeta]

Fetch chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.

Returns:

list of ChatMessageMeta: Metadata about the chat message.

list_llm_registry_admin_models() → List[Dict[str, Any]]: List the admin registry view: effective winners with their shadow candidates and the full raw_config (which MAY include secrets), matching the legacy admin-only runtime_llms setting. Admin only.

list_mcp_tools(config_type: str = 'runner', server_names: List[str] | None = None, mcp_dir: str | None = None, include_remote: bool = True) → dict

List tools from configured MCP servers.

Args:

config_type: Type of config (‘runner’ or ‘creator’). server_names: Optional list of server names to filter. mcp_dir: Optional override directory for MCP configs. include_remote: Whether to include remote MCP servers (default True).

Returns:

dict: Result with keys:

status: ‘success’ or ‘error’
servers: Dict mapping server names to tool lists
total_servers: Number of servers found
total_tools: Total number of tools across all servers
error: Error message if status is ‘error’

Example:

```python result = client.list_mcp_tools(config_type=”runner”) for server, info in result.get(“servers”, {}).items():

print(f”{server}: {info[‘tool_count’]} tools”)

```

list_memory_block_group_permissions(memory_block_id: str) → List[GroupSharePermission]

Returns the group access permissions for a given memory block.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of GroupSharePermission: Which groups have access and at what level.

list_memory_block_permissions(memory_block_id: str) → List[SharePermission]

Returns the user access permissions for a given memory block.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of SharePermission: Who has access and at what level.

list_memory_blocks(offset: int = 0, limit: int = 100, name_filter: str | None = None, updated_after: datetime | None = None) → List[MemoryBlock]

List memory blocks accessible to the current user.

Args:

offset:: How many memory blocks to skip.
limit:: How many memory blocks to return.
name_filter:: Filter by name (case-insensitive substring match).
updated_after:: Only return memory blocks updated at or after this timestamp.

Returns:

list of MemoryBlock: The page of accessible memory blocks.

list_prompt_group_permissions(prompt_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given prompt template.

The returned list of group permissions denoting which groups have access to the prompt template.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given prompt template.

list_prompt_permissions(prompt_id: str) → List[SharePermission]

Returns a list of access permissions for a given prompt template.

The returned list of permissions denotes who has access to the prompt template and their access level.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given prompt template.

list_public_memory_block_permissions(memory_block_id: str) → List[str]

Returns the public permissions for a given memory block.

Returns an empty list both when the memory block is not public and when it is public with read-only access (read is implicit for public blocks); use get_memory_block(...).is_public to distinguish. Matches list_collection_public_permissions.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of str: Permission strings that apply to public access.

list_question_reply_feedback_data(offset: int, limit: int, collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → List[QuestionReplyData]

Fetch user’s questions and answers that have a feedback.

Questions and answers with metadata and feedback information.

Args:

offset:: How many conversations to skip before returning.
limit:: How many conversations to return.
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only return feedbacks with no collection.

Returns:

list of QuestionReplyData: Metadata about questions and answers.

list_recent_chat_sessions(offset: int, limit: int) → List[ChatSessionInfo]

Fetch user’s chat session metadata sorted by last update time.

Chats across all collections will be accessed.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionInfo: Metadata about each chat session including the latest message.

list_recent_collections(offset: int, limit: int, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_filter(offset: int, limit: int, current_user_only: bool = False, name_filter: str = '') → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with filter options.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
name_filter:: Only returns collections with names matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_metadata_filter(offset: int, limit: int, current_user_only: bool, metadata_filter: dict) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with a filter on metadata.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
metadata_filter:: Only returns collections with metadata matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_document_summaries(document_id: str, offset: int, limit: int) → List[ProcessedDocument]

Fetches recent document summaries/extractions/transformations

Args:

document_id:: document ID for which to return summaries
offset:: How many summaries to skip before returning summaries.
limit:: How many summaries to return.

list_recent_documents(offset: int, limit: int, metadata_filter: dict = {}, username: str = '', status: str = '', source: str = '', chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfo]

Fetch user’s document metadata sorted by last update time.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.
username:: Filter documents by the username of the uploader (exact match).
status:: Filter documents by ingestion status (exact match). Values: unknown, scheduled, queued, running, completed, failed, canceled, agent_only.
source:: Filter documents by connector source (case-insensitive match, e.g. SharePoint, url, upload, Agent).
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfo: Metadata about each document.

list_recent_documents_with_summaries(offset: int, limit: int, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

list_recent_documents_with_summaries_sort(offset: int, limit: int, sort_column: str, ascending: bool, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

list_recent_documents_with_summaries_sort_filter_by_type(offset: int, limit: int, sort_column: str = 'updated_at', ascending: bool = False, filter: str = '', interval: str = '36500 days', origin: str = '', use_age: bool = False, document_type: str = 'current_user', chat_session_id: str | None = None, group_by_source_chat: bool = False) → DocumentInfoSummaryListing

Fetch a filtered, sorted page of the user’s documents with summaries.

Unlike list_recent_documents_with_summaries_sort, this performs the text search, origin filtering, and age windowing server-side and returns the total match count alongside the page so the caller can paginate without a separate count query.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return. Pass 0 (or a negative value) for no limit (all matches from offset onward).
sort_column:: Column to sort by. One of name, username, type, size, page_count, connector, uri, original_type, original_mtime, status, updated_at.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Case-insensitive substring matched against the document’s name, type, connector, uri, original_type, id, and username. Empty string matches everything.
interval:: A PostgreSQL interval string (e.g. "7 days") bounding how far back to look. Defaults to "36500 days" (effectively no bound).
origin:: Restrict by document origin. One of "Generated" (agent output), "Indexed" (completed non-agent docs), "Importable" (completed docs), "Canceled", "Agent Only", or "" for no origin filter.
use_age:: When True, the interval window is measured against each document’s original_mtime instead of its updated_at.
document_type:: Visibility scope. "current_user" returns only the calling user’s documents; "public" returns all documents.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; sort_column then orders rows within each group. Documents with no source chat come last.

Returns:

DocumentInfoSummaryListing: The requested page in documents and the total number of matching documents in total. Each document carries chat_session_id and chat_session_name when it was generated by an agent, and chat_session_visible says whether the caller can open that session (a visible session may still have no name).

list_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

list_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

list_role_configurations(role_id: str) → List[ConfigItem]

Lists role configurations for a given role. Args:

role_id:
The role id to get configurations for.

Returns:: List[ConfigItem]: List of role configurations.

list_scheduled_connectors_for_collection(collection_id: str) → List[ScheduledConnectorDetails]

List scheduled connectors associated with a collection.

Args:

collection_id:: String id of the collection to list scheduled connectors for.

Returns:

List[ScheduledConnectorDetails]: Metadata about each scheduled connector.

list_scheduled_task_executions(task_id: str, offset: int = 0, limit: int = 100) → ScheduledTaskExecutionList: List executions for one scheduled task (paginated).

list_scheduled_task_executions_by_admin(task_id: str | None = None, offset: int = 0, limit: int = 100) → ScheduledTaskExecutionList: List executions across all users; optionally filter by task_id (admin only).

list_scheduled_tasks(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None, collection_id: str | None = None, has_collection: bool | None = None) → ScheduledTaskList

List the current user’s scheduled tasks (paginated).

Args:

offset: Pagination offset. limit: Page size. name_filter: Case-insensitive substring match on the task name. status_filter: One of ‘active’, ‘paused’, ‘completed’, ‘expired’. collection_id: Only tasks bound to this collection (UUID).

Mutually exclusive with has_collection.

has_collection: True = only collection-bound tasks; False = only: tasks without a collection. Mutually exclusive with collection_id.

list_scheduled_tasks_by_admin(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None, user_filter: str | None = None) → ScheduledTaskList: List all scheduled tasks across users (admin only).

list_secret_ids(connector_type: str | None = None) → List[str]

List available secret IDs from the SecureStore for cloud storage connectors.

Args:

connector_type: Type of connector (‘s3’, ‘gcs’, ‘azure_key’, ‘azure_sas’): If None, returns secrets for all connector types.

Returns:

List of secret IDs available for the specified connector type

list_shared_chats(offset: int = 0, limit: int = 100, filter_text: str = '', filter_type: str = 'all', showcase_filter: str = 'all') → List[SharedChatInfo]

List shared chats created by the current user.

Args:

offset:: Number of items to skip for pagination.
limit:: Maximum number of items to return.
filter_text:: Optional text to filter shared chats by name.
filter_type:: Type filter. One of ‘all’, ‘frozen’, ‘active’, ‘private’, ‘public’.
showcase_filter:: Showcase membership filter. One of ‘all’, ‘featured’, ‘not_featured’.

Returns:

list of SharedChatInfo: List of shared chat metadata.

list_showcase_categories() → List[str]: Distinct, alphabetically-sorted category labels currently in use across showcase tiles. Requires manage_showcase.

list_showcase_chats(offset: int = 0, limit: int | None = None) → List[ShowcaseChat]: List admin-curated showcase shared chats. Public visibility is gated server-side by the showcase_page_mode global setting.

list_slack_integrations() → List[Dict[str, Any]]

List all Slack integrations for the current user.

Returns:: List of Slack integration dicts.

list_system_groups() → List[UserGroup]

list_system_permissions() → List[UserPermission]

list_system_roles() → List[UserRole]

list_upload() → List[str]

List pending file uploads to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:: upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file
Returns:: List[str]: The pending upload ids to be used in ingest jobs.
Raises:: Exception: The upload list request was unsuccessful.

list_user_permissions(user_id: str | None = None) → List[UserPermission]

list_user_role_permissions(roles: List[str]) → List[UserPermission]

list_user_roles(user_id: str | None = None) → List[UserRole]

list_users(offset: int, limit: int) → List[User]

List system users.

Returns a list of all registered users fo the system, a registered user, is a users that has logged in at least once.

Args:

offset:: How many users to skip before returning.
limit:: How many users to return.

Returns:

list of User: Metadata about each user.

make_collection_private(collection_id: str)

Make a collection private

Once a collection is private, other users will no longer be able to access chat history or documents related to the collection.

Args:

collection_id:: ID of the collection to make private.

make_collection_public(collection_id: str, permissions: List[str] | None = None)

Make a collection public

Once a collection is public, it will be accessible to all authenticated users of the system.

Args:

collection_id:: ID of the collection to make public.
permissions:: Optional: Collection specific permissions. If not provided, all permissions will default to true.

make_extractor_private(extractor_id: str)

Make an extractor private

Once a extractor is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

extractore_id:: ID of the extractor to make private.

make_extractor_public(extractor_id: str)

Make an extractor public

Once an extractor is public, it can be seen and used by all users.

Args:

extractor_id:: ID of the extractor to make public.

make_memory_block_private(memory_block_id: str) → None

Make a memory block private.

Once private, other users no longer have public access. Individual and group shares are preserved.

Args:

memory_block_id:: ID of the memory block.

make_memory_block_public(memory_block_id: str, permissions: List[str] | None = None) → None

Make a memory block public.

Once public, all users can read the memory block. permissions controls additional public access (e.g. edit). Omitting it (None) grants edit by default; pass an explicit empty list ([]) for read-only public access.

Args:

memory_block_id:: ID of the memory block.
permissions:: Public permission strings to grant beyond read (e.g. ['h2ogpte/memory_block/edit']). None grants edit by default; [] makes the block public read-only.

make_prompt_template_private(prompt_template_id: str)

Make a prompt template private

Once a prompt template is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

prompt_template_id:: ID of the prompt template to make private.

make_prompt_template_public(prompt_template_id: str)

Make a prompt template public

Once a prompt template is public, it can be seen and used by all users.

Args:

prompt_template_id:: ID of the prompt template to make public.

match_chunks(collection_id: str, vectors: List[List[float]], topics: List[str], offset: int, limit: int, cut_off: float = 0, width: int = 0) → List[SearchResult]

Find chunks related to a message using semantic search.

Chunks are sorted by relevance and similarity score to the message.

See Also: H2OGPTE.encode_for_retrieval to create vectors from messages.

Args:

collection_id:: ID of the collection to search within.
vectors:: A list of vectorized message for running semantic search.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.
cut_off:: Exclude matches with distances higher than this cut off.
width:: How many chunks before and after a match to return - not implemented.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

migrate_chat_sessions_to_collection(source_collection_id: str, target_collection_id: str, timeout: float | None = None) → Job

Migrate chat sessions from one collection to another.

This method creates a job to migrate chat sessions between collections. Only the collection owner can perform this operation.

Args:

source_collection_id:: String ID of the source collection containing the chat sessions.
target_collection_id:: String ID of the target collection to migrate chat sessions to.
timeout:: Timeout in seconds.

migrate_scheduled_connectors_to_collection(collection_id: str, src_collection_id: str, timeout: float | None = None) → Job

Move all scheduled connectors from a source collection to a target collection.

Connectors are moved, meaning the source collection will have no scheduled connectors after this operation. Both collections must be owned by the same user.

Args:

collection_id:: Target collection ID where scheduled connectors will be moved to.
src_collection_id:: Source collection ID to move scheduled connectors from.
timeout:: Timeout in seconds.

pause_chat(question_id: str) → Result

Pause a streaming chat response.

Args:: question_id: The ID of the chat message/question to pause.
Returns:: Result: Status of the pause operation.
Raises:: Exception: If the user is not authorized to pause this chat or if the operation fails.

pin_forum_post(post_id: str, is_pinned: bool) → None

Pin or unpin a forum post (forum owner only).

Args:: post_id: The post’s UUID. is_pinned: True to pin, False to unpin.

Processes a document to either create a global or piecewise summary/extraction/transformation of a document.

Effective prompt created (excluding the system prompt):

"{pre_prompt_summary}
"""
{text from document}
"""
{prompt_summary}"

Args:

document_id:

String id of the document to create a summary from.

system_prompt:

System Prompt

pre_prompt_summary:

Prompt that goes before each large piece of text to summarize

prompt_summary:

Prompt that goes after each large piece of text to summarize

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

llm:

LLM to use

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:: temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation enable_vision (str, default: “auto”) — Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”] visible_vision_models (List[str], default: [“auto”]) — Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic

max_num_chunks:

Max limit of chunks to send to the summarizer

sampling_strategy:

How to sample if the document has more chunks than max_num_chunks. Options are “auto”, “uniform”, “first”, “first+last”, default is “auto” (a hybrid of them all).

pages:

List of specific pages (of the ingested document in PDF form) to use from the document. 1-based indexing.

schema:

Optional JSON schema to use for guided json generation.

keep_intermediate_results:

Whether to keep intermediate results. Default: disabled. If disabled, further LLM calls are applied to the intermediate results until one global summary is obtained: map+reduce (i.e., summary). If enabled, the results’ content will be a list of strings (the results of applying the LLM to different pieces of document context): map (i.e., extract).

guardrails_settings:

Guardrails Settings.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context given to the LLM. Only used if enable_vision is disabled. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

timeout:

Amount of time in seconds to allow the request to run. The default is 86400 seconds.

Returns:

ProcessedDocument: Processed document. The content is either a string (keep_intermediate_results=False) or a list of strings (keep_intermediate_results=True).

Raises:

TimeoutError: The request did not complete in time. SessionError: No summary or extraction created. Document wasn’t part of a collection, or LLM timed out, etc.

publish_library_skill(skill_path: str) → List[PublishedLibrarySkill]

Publish a skill zip to the shared library (requires ManageLibrary).

A multi-skill zip creates one library entry per SKILL.md found. The catalog is global: re-publishing an existing skill name replaces that entry in place regardless of who published it.

Args:: skill_path: Path to a .zip or .skill file (max 100 MiB).
Returns:: List[PublishedLibrarySkill]: The created/updated library rows.
Raises:: FileNotFoundError: skill_path does not exist. ValueError: skill_path has an unsupported extension or is too

large (>100 MiB).

Example:

rows = client.publish_library_skill("my-skill.zip")
for row in rows:
    print(row.skill_id, row.inserted)

regenerate_assistant_webhook_token(assistant_id: str, webhook_id: str) → Dict[str, Any]

Regenerate the token for a webhook (invalidates the old token).

Args:: assistant_id: ID of the assistant. webhook_id: ID of the webhook.
Returns:: Dict with the new ‘token’ (shown only once).

remove_admin_mcp_logo(mcp_id: str) → dict

Remove the logo from an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = client.remove_admin_mcp_logo("my_custom_builtin") print(result["message"]) # "Logo removed successfully" `

remove_chat_session_expiry_date(chat_session_id: str) → str

Remove the expiry date from a chat session.

Args:

chat_session_id:: ID of the chat session to update.

remove_collection_expiry_date(collection_id: str) → str

Remove an expiry date from a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_inactivity_interval(collection_id: str) → str

Remove an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_size_limit(collection_id: str) → str

Remove a size limit for a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_thumbnail(collection_id: str, timeout: float | None = None)

Remove a thumbnail from a collection.

Args:

collection_id:: Collection you want to remove the thumbnail from.
timeout:: Amount of time in seconds to allow the request to run. The default is 86400 seconds.

remove_custom_agent_tool_from_codeapi(tool_id: str) → bool

Remove a custom agent tool from CodeAPI, terminating its job.

Args:: tool_id: The ID of the tool to remove from CodeAPI.
Returns:: True on success.

remove_permissions_from_role(role_id: str, permission_name: str) → Result

remove_role_from_group(group_id: str, roles: List[str]) → List[UserRole]

remove_role_from_user(user_id: str, roles: List[str]) → List[UserRole]

remove_showcase_chat(showcase_id: str) → None: Remove a showcase tile. The underlying shared chat is untouched.

rename_chat_session(chat_session_id: str, name: str)

Update a chat session name

Args:

chat_session_id:: String id of the document to search for.
name:: The new chat session name.

reorder_showcase_chats(orders: List[ReorderShowcaseChatEntry]) → None: Atomically reassign sort_order for the given showcase entries.

reply_to_forum_post(forum_id: str, post_id: str, content: str, assistant_id: str | None = None, file_ids: List[str] | None = None, metadata: Dict[str, Any] | None = None) → str

Reply to a specific post in a forum.

Creates a reply via the REST API endpoint, which also triggers wake events for sleeping assistants connected to the forum.

Args:: forum_id: The forum’s UUID. post_id: The parent post’s UUID to reply to. content: The reply content. assistant_id: Optional AI assistant UUID to post as. file_ids: Optional list of file UUIDs to attach. metadata: Optional metadata dict.
Returns:: str: The ID of the created reply post.

request_current_user_deletion() → str

Request deletion of the current user account.

This creates a deletion request and returns a delete ID that must be used to confirm the deletion within 5 minutes.

Returns:: str: Delete ID that must be used to confirm deletion.

reset_ai_assistant_tool(assistant_id: str) → None

Reset an AI assistant’s custom tool definition to NULL.

Uses the __CLEAR__ sentinel value recognized by the update_ai_assistant DB function to set custom_tool_definition to NULL.

Args:: assistant_id: The assistant’s UUID.

reset_all_collection_expirations(): Reset any expiry dates and inactivity intervals that have been set for all collections (admin only). This will also reset any archived collections back to active.

reset_and_share_extractor(extractor_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to an extractor (except for the owner) and share it with the provided list of new users.

Args:

extractor_id:: ID of the extractor to un-share.
new_usernames:: The list of usernames belonging to the users this extractor will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_extractor_with_groups(extractor_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to an extractor and share it with the provided list of new group ids.

Args:

extractor_id:: ID of the extractor to un-share.
new_groups:: The list of group ids this extractor will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_prompt_template(prompt_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to a prompt template (except for the owner) and share it with the provided list of new users.

Args:

prompt_id:: ID of the prompt template to un-share.
new_usernames:: The list of usernames belonging to the users this prompt template will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_prompt_template_with_groups(prompt_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to a prompt template and share it with the provided list of new group ids.

Args:

prompt_id:: ID of the prompt template to un-share.
new_groups:: The list of group ids this prompt template will be shared with.

ShareResponseStatus: Status of share request.

reset_collection_prompt_settings(collection_id: str) → str

Reset the prompt settings for a given collection.

Args:

collection_id:: ID of the collection to update.

Returns:

str: ID of the updated collection.

reset_roles_for_group(group_id: str, roles: List[str]) → List[UserRole]

reset_roles_for_user(user_id: str, roles: List[str]) → List[UserRole]

reset_user_configurations_for_user(key_name: str, user_id: str) → List[ConfigItem]

Reset a user configuration for a specific user (to be used by admins only).

Returns:: List[ConfigItem]: List of user configurations.

resume_chat(question_id: str) → Result

Resume a paused chat response.

Args:: question_id: The ID of the chat message/question to resume.
Returns:: Result: Status of the resume operation.
Raises:: Exception: If the user is not authorized to resume this chat or if the operation fails.

revoke_connector(connector_id: str) → None

Revoke and delete a linked connector.

Revokes the token at the provider (when the provider supports it) and removes the stored connector.

Args:

connector_id:: The id of the connector to revoke (see list_connectors()).

run_extractor(extractor_id: str, collection_id: str | None = None, document_id: str | None = None, files: List[Tuple[str, bytes]] | None = None, timeout: int | None = None) → List[DocumentExtractionResult]

Run an extractor on a collection, single document, or uploaded files and wait for completion.

This method creates a job to execute the specified extractor and blocks until the job finishes. Exactly one of collection_id, document_id, or files must be provided. Mixing files with collection_id or document_id is not allowed.

Args:

extractor_id:: String ID of the extractor to run.
collection_id:: String ID of the collection to run the extractor on.
document_id:: String ID of a single document to run the extractor on.
files:: List of (filename, bytes) tuples to run the extractor on directly, without requiring a collection. The files are uploaded temporarily and deleted after extraction completes.
timeout:: Optional timeout in seconds.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ValueError: If files is provided together with collection_id or document_id. ObjectNotFoundError: If the extractor or collection is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor or collection.

Example:

# Run extraction on a collection and wait for results
results = client.run_extractor(
    extractor_id="extractor-123",
    collection_id="collection-456"
)

# Run extraction on a single document and wait for results
results = client.run_extractor(
    extractor_id="extractor-123",
    document_id="document-789"
)

# Run extraction on uploaded files directly
with open("report.pdf", "rb") as f:
    results = client.run_extractor(
        extractor_id="extractor-123",
        files=[("report.pdf", f.read())]
    )

for result in results:
    print(f"Document: {result.document_name}")
    print(f"Extracted content: {result.content}")

run_selftest(llm: str, mode: str) → dict

Run a self-test for a given LLM Args:

llm:
Name of LLM

mode:
one of [“quick”, “rag”, “full”, “agent”]

Returns:: Dictionary with performance stats. If “error” is filled, the test failed.

search_chunks(collection_id: str, query: str, topics: List[str], offset: int, limit: int) → List[SearchResult]

Find chunks related to a message using lexical search.

Chunks are sorted by relevance and similarity score to the message.

Args:

collection_id:: ID of the collection to search within.
query:: Question or imperative from the end user to search a collection for.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

search_forum_posts(assistant_id: str, query: str, forum_id: str | None = None, author_username: str | None = None, author_assistant_name: str | None = None, since: datetime | None = None, min_vote_score: int | None = None, sort_by: str = 'relevance', limit: int = 20, offset: int = 0) → Dict[str, Any]

Search forum posts by keyword across all accessible forums.

Uses PostgreSQL full-text search. Supports natural language queries, phrases, boolean operators (& |), negation (!), and prefix matching (*).

Args:: assistant_id: The assistant’s UUID (used for access scoping). query: Search keywords or full-text search expression. forum_id: Optional forum UUID to restrict search to. author_username: Optional filter by human author username. author_assistant_name: Optional filter by assistant author name. since: Optional cutoff — only posts created after this time. min_vote_score: Optional minimum vote score filter. sort_by: Sort order: ‘relevance’ (default), ‘newest’, ‘oldest’, ‘top’. limit: Max results (1–100, default 20). offset: Pagination offset.
Returns:: Dict with ‘posts’ (list of matching posts with highlighted snippets), ‘total’ (total matches), ‘query’, ‘offset’, ‘limit’.

send_hitl_message(question_id: str, message: str) → Result

Send a course correction message to a running agent.

Sends a human-in-the-loop message to a running agent. The agent will incorporate this guidance before its next LLM call.

Args:: question_id: The ID of the active streaming chat question. message: The course correction message to send to the agent.
Returns:: Result: Status of the send operation.
Raises:: Exception: If the user is not authorized or if the operation fails.

send_inter_assistant_message(assistant_id: str, recipient_assistant_id: str, content: str, metadata: Dict[str, Any] | None = None) → str

Send a direct message from one assistant to another.

Triggers a wake event on the recipient assistant. This goes through the REST API which handles Redis wake event dispatch.

Args:: assistant_id: The sender assistant’s UUID. recipient_assistant_id: The recipient assistant’s UUID. content: Message content (max 100000 chars). metadata: Optional metadata dict.
Returns:: str: The created message UUID.

send_message_to_assistant(assistant_id: str, content: str) → str

Send a direct message to an AI assistant.

Creates the message in the database and automatically pushes a wake event if the assistant is in sleeping state. There is no need to call wake_ai_assistant() separately.

Args:: assistant_id: The assistant’s UUID. content: The message text.
Returns:: str: The ID of the created message.

set_agent_skill_preference(skill_ids: List[str], enabled: bool) → None

Enable or disable the given agent skills for the user.

Sets the enabled flag for the listed skill IDs. Only the named skills are changed; any skill not in skill_ids is left untouched.

Args:: skill_ids: IDs of the skills to update. enabled: True to enable the listed skills, False to disable them.

Example:

skills = client.get_skills()
client.set_agent_skill_preference([skills[0].id], True)

set_api_key_expiration(api_key_id: str, expires_in: str | None = None) → Result

Allows admins to set an expiration on an API key.

Args:

api_key_id:: String: The id of the API key.
expires_in:: (Optional) String: The expiration for the API key as an interval or None (to remove an expiration that was previously set). Ex. “30 days” or “30 minutes”

Returns:

Result: Status of the expiration request.

set_api_key_inactivity_interval(api_key_id: str, inactivity_interval: int | None = None) → Result

Allows admins to set an inactivity interval for an API key. This is how many days a key can be unused for (no activity) before it becomes invalid.

Args:

api_key_id:: String: The id of the API key.
inactivity_interval:: (Optional) int: The inactivity interval for the API key as an integer of days or None (to remove an inactivity interval that was previously set).

Returns:

Result: Status of the request.

set_chat_message_votes(chat_message_id: str, votes: int) → Result

Change the vote value of a chat message.

Set the exact value of a vote for a chat message. Any message type can be updated, but only LLM response votes will be visible in the UI. The expectation is 0: unvoted, -1: dislike, 1 like. Values outside of this will not be viewable in the UI.

Args:

chat_message_id:: ID of a chat message, any message can be used but only LLM responses will be visible in the UI.
votes:: Integer value for the message. Only -1 and 1 will be visible in the UI as dislike and like respectively.

Returns:

Result: The status of the update.

Raises:

Exception: The upload request was unsuccessful.

set_chat_session_collection(chat_session_id: str, collection_id: str | None) → str

Set the collection for a chat_session

Args:

chat_session_id:: ID of the chat session
collection_id:: ID of the collection, or None to chat with the LLM only.

Returns:

str: ID of the updated chat session

set_chat_session_expiry_date(chat_session_id: str, expiry_date: str, timezone: str | None = None) → str

Set an expiry date for a chat session.

When the expiry date is reached, the chat session will be automatically archived and eventually deleted after the configured grace period.

Args:

chat_session_id:: ID of the chat session to update.
expiry_date:: The expiry date as a string in ‘YYYY-MM-DD’ format.
timezone:: Optional timezone to associate with expiry date (with IANA timezone support).

set_chat_session_keep_forever(chat_session_id: str, keep_forever: bool) → str

Set whether a chat session should be preserved from auto-archival.

When keep_forever is True, the chat session will not be subject to inactivity-based or date-based expiry, and its expiry date is cleared permanently. When set to False, the global inactivity interval is re-applied and the inactivity timer is restarted, so the chat gets a full retention period before it is considered for archival again.

Args:

chat_session_id:: ID of the chat session to update.
keep_forever:: Whether to preserve the chat session from expiry.

set_chat_session_prompt_template(chat_session_id: str, prompt_template_id: str | None) → str

Set the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.

Returns:

str: ID of the updated chat session

set_collection_exempt_from_chat_expiry(collection_id: str, exempt: bool) → str

Set whether a collection’s chat sessions are exempt from expiry.

When exempt is True, all chat sessions in the collection will be excluded from automatic expiry regardless of their individual settings.

Args:

collection_id:: ID of the collection to update.
exempt:: Whether to exempt chat sessions from expiry.

set_collection_expiry_date(collection_id: str, expiry_date: str | date | datetime, timezone: str | None = None) → str

Set an expiry date for a collection.

Args:

collection_id:: ID of the collection to update.
expiry_date:: Expiry as a "YYYY-MM-DD" date string, a full ISO 8601 datetime string with optional timezone offset (e.g. "2026-09-30T17:00:00-05:00"), or a datetime.date / datetime.datetime object. A date-only value resolves to midnight (00:00:00) of that day in timezone.
timezone:: Optional timezone to associate with a date-only / offset-less expiry (with IANA timezone support). Ignored for parsing when expiry_date already carries an offset, but always stored as the collection’s expiry_timezone so the expiry is displayed in this zone. Defaults to the local machine’s zone.

set_collection_inactivity_interval(collection_id: str, inactivity_interval: int) → str

Set an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.
inactivity_interval:: The inactivity interval as an integer number of days.

set_collection_prompt_template(collection_id: str, prompt_template_id: str | None, strict_check: bool = False) → str

Set the prompt template for a collection

Args:

collection_id:: ID of the collection to update.
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.
strict_check:: whether to check that the collection’s embedding model and the prompt template are optimally compatible

Returns:

str: ID of the updated collection.

set_collection_size_limit(collection_id: str, limit: int | str) → str

Set a maximum limit on the total size of documents (sum) added to a collection. The limit is measured in bytes.

Args:

collection_id:: ID of the collection to update.
limit:: The bytes limit, possible values follow the format: 12345, “1GB”, or “1GiB”.

set_collection_thumbnail(collection_id: str, file_path: Path, timeout: float | None = None)

Upload an image file to be set as a collection’s thumbnail.

The image file will not be considered as a collection document. Acceptable image file types include: .png, .jpg, .jpeg, .svg

Args:

collection_id:: Collection you want to add the thumbnail to.
file_path:: Path to the image file. Must include appropriate file extension.
timeout:: Amount of time in seconds to allow the request to run.

Raises:

ValueError: The file is invalid. Exception: The upload request was unsuccessful.

set_default_memory_block(scope: str, memory_block_id: str | None = None) → dict

Set or clear a default memory block for a given scope.

Args:: scope: Which scope to set. Must be 'llm' or 'agent'. memory_block_id: UUID of the memory block to set as default,

or None to clear the default for this scope.
Returns:: A dict with 'scope' and 'memory_block' (the set block or None if cleared).
Raises:: ValueError: If scope is not ‘llm’ or ‘agent’.

Example:

# Set default for LLM (non-agent) chats
client.set_default_memory_block('llm', '<block-id>')

# Set default for agent chats
client.set_default_memory_block('agent', '<block-id>')

# Clear the agent default
client.set_default_memory_block('agent', None)

set_default_prompt_template_visibility(prompt_id: str, is_visible: bool)

Updates a flag specifying whether a default prompt template is visible or hidden to users.

Once you hide a default prompt template, users will no longer be able to use this prompt template. This will also affect collections and chats that have this as a default prompt template. Once you show a default prompt template, all users will be able to see and use this prompt template.

Args:

prompt_id:: ID of the default prompt template you would like to change the visibility of.
is_visible:: Whether the default prompt template should be visible.

set_global_configuration(key_name: str, string_value: str, can_overwrite: bool, is_public: bool, value_type: str = None) → List[GlobalConfigItem]

Set a global configuration.

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the global config.
can_overwrite:: Whether user settings can override this global setting.
is_public:: Whether users can see the value for this global setting.
value_type:: The type of the value to be set for the global config.

Returns:

List[GlobalConfigItem]: List of global configurations.

set_role_configuration(key_name: str, role_id: str, string_value: str, value_type: str = None) → List[ConfigItem]

Set a role configuration, overrides the global configuration. Args:

role_id:
The role id you want to apply the config for.

key_name:
The name of the global config key.

string_value:
The value to be set for the config.

value_type:
The type of the value to be set for the config.

Returns:: List[ConfigItem]: List of role configurations.

set_role_llm_access(role_id: str, names: List[str]) → None: Replace a role’s LLM access grants with names; protected roles rejected (manage-roles).

set_role_priority(role_id: str, priority: int) → UserRole

Sets the priority for a role. Args:

role_id:
String: The id of the role to set the priority for.

priority:
Int: The priority value to set for the role. ex: 100, 200, 300…etc. The lower the number, the higher the priority.

Returns:: UserRole: The updated user role with the new priority.

set_skill_associations(skill_id: str, keys: List[dict] | None = None, tools: List[str] | None = None) → dict

Set a skill’s env-var→key associations and which tools receive them.

Args:

skill_id: The skill to configure (must belong to the caller). keys: List of {"name": <env var>, "key_id": <agent key id or None>}.

Only env vars declared in the skill’s envs.json are accepted; key_id None/”” clears the binding.

tools: Tools that receive the skill’s env vars when it is selected.: Empty/omitted defaults to ["python", "shell"].

Returns:

dict: {"count": <associations upserted>, "tools": [<resulting tools>]}.

Example:

skills = client.get_skills()
keys = client.get_agent_keys()
client.set_skill_associations(
    skills[0].id,
    keys=[{"name": "OPENAI_API_KEY", "key_id": keys[0].id}],
    tools=["python", "shell"],
)

set_user_approval_config(user_id: str, approval_user_id: str | None = None, allow_custom_approval_text: bool = False, allow_policy_override: bool = True, allow_approval_user_change: bool = False) → Dict[str, Any]

Set approval governance config for a user. Admin-only.

Args:: user_id: The target user’s UUID. approval_user_id: UUID of the designated approval user (None = clear). allow_custom_approval_text: Allow user to set custom approval text. allow_policy_override: Allow user to change tool action policies. allow_approval_user_change: Allow user to change their approval user.
Returns:: Dict with ‘id’ and ‘status’.

set_user_configuration_for_user(key_name: str, string_value: str, user_id: str, value_type: str = None) → List[ConfigItem]

Set a user configuration for a specific user (overrides the global configuration and to be used by admins only).

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the config.
user_id:: The user id you want to apply the config for.
value_type:: The type of the value to be set for the config.

Returns:

List[ConfigItem]: List of user configurations.

share_ai_assistant(assistant_id: str, username: str, access_mode: str = 'read') → None

Share an AI assistant with another user.

Args:: assistant_id: The assistant’s UUID. username: The username to share with. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

share_chat_session(chat_session_id: str, is_private: bool = False, is_frozen: bool = True, includes_artifacts: bool = False) → ChatShareUrl

Share a chat session and get a publicly accessible URL.

Args:

chat_session_id:: String id of the chat session to share.
is_private:: If True, only authenticated users can view the shared chat. If False (default), the shared chat is publicly accessible.
is_frozen:: If True (default), a snapshot of the chat is created at share time. If False, the shared chat shows live updates from the source chat.
includes_artifacts:: If True, file artifacts referenced in messages are included. If False (default), artifacts are excluded.

Returns:

ChatShareUrl: Object containing the shareable URL and relative path.

share_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Share a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_collection_with_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a collection to a group.

The permission attribute defines the level of access, and which group can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level and group.

Returns:

ShareResponseStatus: Status of share request.

share_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Share an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_extractor_with_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share an extractor to a group.

The permission attribute defines which group can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the group for sharing with.

Returns:

ShareResponseStatus: Status of share request.

share_forum(forum_id: str, username: str, access_mode: str = 'read') → None

Share a forum with another user.

Args:: forum_id: The forum’s UUID. username: The username to share with. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

share_memory_block(memory_block_id: str, permission: SharePermission) → ShareResponseStatus

Share a memory block to a user.

Args:

memory_block_id:: ID of the memory block to share.
permission:: Defines the user to share with and the permission level. permission.permissions may be None or empty for read-only access.

Returns:

ShareResponseStatus: Status of the share request.

share_memory_block_with_group(memory_block_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a memory block to a group.

Args:

memory_block_id:: ID of the memory block to share.
permission:: Defines the group to share with and the permission level. permission.permissions may be None or empty for read-only access.

Returns:

ShareResponseStatus: Status of the share request.

share_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Share a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_prompt_with_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a prompt to a group.

Args:

prompt_id:: ID of the prompt to share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

star_library_item(item_kind: Literal['skill', 'mcp'], item_id: str) → LibraryStarStatus

Star a library item. Requires the caller to have it installed.

Args:: item_kind: "skill" or "mcp". item_id: Library id of the item.
Returns:: LibraryStarStatus: The new aggregate star state.

Example:

status = client.star_library_item("skill", "tabh2o-predict")
print(status.star_count, status.is_starred_by_me)

start_ai_assistant(assistant_id: str) → None

Start an AI assistant (sets status to ‘sleeping’ and records a start event).

Uses the REST API endpoint which both updates the DB status and records the start event, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

start_connector_link(connector_type: str) → str

Begin the OAuth flow for a connector and return the authorization URL.

The caller must open the returned URL in a browser (logged into the h2oGPTe server as the same user) and approve access at the provider. The link is complete once the provider redirects back to the server’s callback; observe it via list_connectors().

Args:

connector_type:: One of "github", "confluence", "sharepoint", or "snowflake". Must be a type the server is configured for (see get_connector_status()).

Returns:

str: The provider authorization URL to open in a browser.

stop_ai_assistant(assistant_id: str) → None

Stop an AI assistant (sets status to ‘stopped’ and records a stop event).

Uses the REST API endpoint which both updates the DB status and records the stop event, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

stop_chat(question_id: str) → Result

Immediately stop/cancel a streaming chat response.

This will immediately halt response generation, which may result in an incomplete sentence or thought. For a more graceful termination, use finish_chat instead.

Args:: question_id: The ID of the chat message/question to stop immediately.
Returns:: Result: Status of the cancel operation.
Raises:: Exception: If the user is not authorized to cancel this chat or if the operation fails.

subscribe_assistant_to_event_type(assistant_id: str, event_type_id: str) → AiAssistantEventSubscription

Subscribe an assistant to a custom event type.

Idempotent — re-subscribing returns the existing subscription.

Args:: assistant_id: The assistant’s UUID. event_type_id: The event type’s UUID.
Returns:: AiAssistantEventSubscription: The subscription record.

Summarize one or more contexts using an LLM.

Effective prompt created (excluding the system prompt):
"{pre_prompt_summary}
"""
{text_context_list}
"""
{prompt_summary}"
Args:

text_context_list:
List of raw text strings to be summarized.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default or None for h2oGPTe defaults. Defaults to ‘’ for no system prompt.

pre_prompt_summary:
Text that is prepended before the list of texts. The default can be customized per environment, but the standard default is "In order to write a concise single-paragraph or bulleted list summary, pay attention to the following text:\n"

prompt_summary:
Text that is appended after the list of texts. The default can be customized per environment, but the standard default is "Using only the text above, write a condensed and concise summary of key results (preferably as bullet points):\n"

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

summarize_document(*args, **kwargs) → DocumentSummary

tag_document(document_id: str, tag_name: str) → str

Adds a tag to a document.

Args:

document_id:: String id of the document to attach the tag to.
tag_name:: String representing the tag to attach.

Returns:

String: The id of the newly created tag.

test_runtime_llm(config: Dict[str, Any]) → Dict[str, Any]: Probe a runtime LLM config without persisting it (a non-caching, non-persisting metadata round-trip); returns {“ok”, “meta”|”error”}. Applies the same display_name rule as create_runtime_llm(), so a config the create path would refuse never tests green (admin only).

trigger_scheduled_task(task_id: str) → ScheduledTaskTriggerResult: Manually trigger a scheduled task immediately (a test run).

unarchive_chat_session(chat_session_id: str) → str

Restore an archived chat session to an active state.

Admin-only. Resets the session status from ‘archived’ to ‘active’, clears archived_at, and restores the inactivity interval from the current global configuration.

Args:

chat_session_id:: ID of the chat session to restore.

unarchive_collection(collection_id: str) → str

Restore an archived collection to an active status.

Args:

collection_id:: ID of the collection to restore.

unshare_ai_assistant(assistant_id: str, username: str) → None

Remove sharing for an AI assistant.

Args:: assistant_id: The assistant’s UUID. username: The username to unshare from.

unshare_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

unshare_collection_for_all(collection_id: str) → ShareResponseStatus

Remove sharing of a collection to all other users but the original owner.

Args:

collection_id:: ID of the collection to un-share.

ShareResponseStatus: Status of share request.

unshare_collection_from_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of a collection from a group.

The permission attribute defines which group to remove access from, the collection_id attribute denotes the collection to be unshared. In case of un-sharing, the GroupSharePermission’s group_id is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the group for which collection access is revoked.

Returns:

ShareResponseStatus: Status of share request.

unshare_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the user for which extractor access is revoked.

ShareResponseStatus: Status of share request.

unshare_extractor_for_all(extractor_id: str) → ShareResponseStatus

Remove sharing of an extractor to all other users but the original owner.

Args:

extractor_id:: ID of the extractor to un-share.

ShareResponseStatus: Status of share request.

unshare_extractor_from_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of an extractor from a group.

The permission attribute defines which group to remove access from, the extractor_id attribute denotes the extractor to be unshared.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the group for which extractor access is revoked.

Returns:

ShareResponseStatus: Status of share request.

unshare_forum(forum_id: str, username: str) → None

Remove sharing for a forum.

Args:: forum_id: The forum’s UUID. username: The username to unshare from.

unshare_memory_block(memory_block_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a memory block from a user.

Args:

memory_block_id:: ID of the memory block.
permission:: Defines the user whose access is revoked (permission.username).

Returns:

ShareResponseStatus: Status of the unshare request.

unshare_memory_block_from_group(memory_block_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of a memory block from a group.

Args:

memory_block_id:: ID of the memory block.
permission:: Defines the group whose access is revoked (permission.group_id).

Returns:

ShareResponseStatus: Status of the unshare request.

unshare_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

unshare_prompt_for_all(prompt_id: str) → ShareResponseStatus

Remove sharing of a prompt template to all other users but the original owner (owner action only).

Args:

prompt_id:: ID of the prompt template to un-share.

ShareResponseStatus: Status of share request.

unshare_prompt_from_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Unshare a prompt from a group.

Args:

prompt_id:: ID of the prompt to un-share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

unstar_library_item(item_kind: Literal['skill', 'mcp'], item_id: str) → LibraryStarStatus

Remove the caller’s star on a library item. Idempotent.

Args:: item_kind: "skill" or "mcp". item_id: Library id of the item.
Returns:: LibraryStarStatus: The new aggregate star state.

Example:

status = client.unstar_library_item("skill", "tabh2o-predict")
print(status.star_count)

unsubscribe_assistant_from_event_type(assistant_id: str, event_type_id: str) → None

Unsubscribe an assistant from a custom event type.

Args:: assistant_id: The assistant’s UUID. event_type_id: The event type’s UUID.

untag_document(document_id: str, tag_name: str) → str

Removes an existing tag from a document.

Args:

document_id:: String id of the document to remove the tag from.
tag_name:: String representing the tag to remove.

Returns:

String: The id of the removed tag.

update_admin_mcp_logo(mcp_id: str, logo_path: str) → dict

Update the logo for an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) logo_path: Path to the logo image file to upload
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the logo file is invalid or not found
Example:: `python result = client.update_admin_mcp_logo("my_custom_builtin", "/path/to/logo.png") print(result["logo"]) # "/file?id=...&name=logo.png" `

update_agent_key(key_id: str, name: str | None = None, value: str | None = None, key_type: str | None = None, description: str | None = None) → dict | None

update_agent_tool_preference(reference_value: List[str]) → None

Update an AI assistant’s configuration.

Args:: assistant_id: The assistant’s UUID. name: New name (optional). description: New description (optional). system_prompt: New system prompt (optional). llm: New model identifier (optional). llm_args: New LLM args dict (optional). custom_tool_definition: New custom tool Python code (optional). mcp_servers: New MCP server config list (optional). credential_ids: New credential UUID list (optional). memory_block_id: New memory block UUID (optional). notification_email: New notification email (optional). notification_smtp: New SMTP config dict for outbound notifications (optional). history_management: New history mode (optional). history_max_chars: New char threshold (optional). history_recent_chars: Characters of recent history to always include (optional). history_retrieval_chars: Characters of retrieved history to include (optional). allowed_tool_actions: List of allowed tool action names (optional). allowed_trigger_types: List of allowed trigger types (optional). tool_action_policies: Dict mapping tool action names to policies (optional). approval_user_id: UUID of the designated approval user (optional). custom_approval_text: Custom data protection instructions (optional). policies_locked: Lock tool action policies (admin-only) (optional). custom_approval_locked: Lock custom approval text (admin-only) (optional).

update_ai_assistant_tool(assistant_id: str, custom_tool_definition: str) → None

Update the custom tool definition for an AI assistant.

Args:: assistant_id: The assistant’s UUID. custom_tool_definition: The Python code for the custom tool.

update_collection(collection_id: str, name: str, description: str) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:: ID of the collection to update.
name:: New name of the collection, this is required.
description:: New description of the collection, this is required.

Returns:

str: ID of the updated collection.

update_collection_metadata(collection_id: str, collection_metadata: dict) → str

Set the new collection metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_metadata:: Dictionary containing the new collection metadata.

Returns:

str: ID of the updated collection.

update_collection_rag_type(collection_id: str, name: str, description: str, rag_type) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:

ID of the collection to update.

name:

New name of the collection, this is required.

description:

New description of the collection, this is required.

rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.: Requires 1 Agent call.
"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.: Requires 1 Agent call with RAG tool execution.
"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code: execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.
"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts: to answer the query. Requires 1 LLM or Agent call.
"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).: Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.
"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant: contexts from a collection for generating a response. Requires 3 LLM calls.
"rag+" Summary RAG - Like RAG, but uses more context and recursive: summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.
"all_data" All Data RAG - Like Summary RAG, but includes all document: chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

Returns:

str: ID of the updated collection.

update_collection_settings(collection_id: str, collection_settings: dict) → str

Set the new collection settings, must be complete. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_settings:: Dictionary containing the new collection settings.

Returns:

str: ID of the updated collection.

update_collection_workspace(collection_id: str, workspace: str) → str

Update the workspace associated with a collection.

Args:

collection_id:: ID of the collection to update.
workspace:: The workspace associated with the collection.

update_custom_agent(agent_id: str, agent_args: dict, mcp_servers_mapping: dict | None = None) → str

Updates a custom agent’s arguments.

Args:: agent_id: The ID of the agent to update agent_args: New agent arguments mcp_servers_mapping: Optional dict mapping MCP server names to tool names (or None)

Example: {“powerpoint_server”: “powerpoint_mcp_tool”, “web_search”: None}
Returns:: The updated agent ID

update_custom_agent_tool(tool_id: str, tool_args: dict, custom_tool_path: str | None = None) → str

Updates a custom agent tool’s arguments.

When custom_tool_path is provided, this will: 1. Upload the new file to object storage 2. Delete the old file from object storage 3. Update the tool’s configuration with the new file reference

Behavior change (v1.7.5): updates are per-tool. For remote_mcp tools, a mcp_config_json payload must describe exactly one server; a payload with multiple servers now raises an error instead of silently keeping the first server and dropping the rest. Use add_custom_agent_tool to create additional tools. Updating unsupported tool_type values (e.g. api_app/oauth_app) also raises a clear error.

Args:

tool_id: The ID of the tool to update tool_args: New tool arguments custom_tool_path: Optional path to a new file to replace the existing tool file

Returns:

The updated tool ID

Raises:

HTTPError: If the remote_mcp mcp_config_json contains more than: one server, or if the tool’s tool_type does not support updates.

update_document_metadata(document_id: str, document_metadata: dict) → str

Set the new document metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

document_id:: ID of the document to update.
document_metadata:: Dictionary containing the new document metadata.

Returns:

str: ID of the updated document.

update_document_name(document_id: str, name: str) → str

Update the name metadata for a given document.

Args:

document_id:: ID of the document to update.
name:: New name of the document, must include file extension.

Returns:

str: ID of the updated document.

update_document_uri(document_id: str, uri: str) → str

Update the URI metadata for a given document.

Args:

document_id:: ID of the document to update.
uri:: New URI of the document, this is required.

Returns:

str: ID of the updated document.

Updates an existing extractor.

Only the arguments that are passed are changed; every argument left as None keeps the extractor’s current value.

An empty string is a value rather than an absence: it writes an empty string, which for extractor_schema and prompt is the meaningful “use the default” setting. An empty llm or vision_llm is rejected, since a model cannot be cleared.

guardrails_settings replaces the whole object rather than merging into it, so a dict carrying one key drops every other guardrail setting the extractor had. Pass the complete settings to change one of its fields.

Args:

extractor_id: The ID of the extractor to update. name: New name of the extractor. llm: New LLM to use for extraction. extractor_schema: New JSON schema defining the extraction structure. If not empty, extractor will return data as JSON object. description: New description of the extractor. prompt: New prompt text for the extractor. If combined with extractor_schema, prompt can modify the output, but not its format as it’s set to be JSON object. pre_prompt_summary: New pre-prompt summary text for the extractor. keep_intermediate_results: New flag indicating whether to keep intermediate results during extraction. system_prompt: New system prompt text for the extractor. max_num_chunks: New maximum number of chunks to process. vision: New vision mode setting. One of ‘on’, ‘off’ or ‘auto’. vision_llm: New vision LLM model identifier. image_batch_image_prompt: New image batch processing prompt. image_batch_final_prompt: New final prompt for image batch processing. guardrails_settings: New guardrails settings configuration as a dictionary.

Returns:

Extractor: Details of the updated extractor.

Raises:

UnauthorizedError: If the extractor does not exist or is not visible to the caller. InvalidArgumentError: If no field was supplied, if extractor_id is not a uuid, if

llm or vision_llm is empty, if vision is not ‘on’/’off’/’auto’, or if max_num_chunks is below 1.

ObjectNotFoundError: If llm or vision_llm names a model the caller is not: granted.

update_forum(forum_id: str, name: str | None = None, description: str | None = None) → None

Update a forum’s configuration.

Args:: forum_id: The forum’s UUID. name: New name (optional). description: New description (optional).

update_forum_post(post_id: str, content: str) → None

Update a forum post (author only).

Args:: post_id: The post’s UUID. content: New content.

Update fields of a memory block. None leaves a field untouched.

Args:

memory_block_id:: ID of the memory block to update.
name:: New display name.
content:: New text content.
system_prompt_amendment:: New system prompt amendment.
injection_mode:: New injection mode.
access_mode:: New access mode.
max_content_length:: New maximum content length.

update_prompt_template(id: str, name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Update a prompt template

Args:

id:: String ID of the prompt template to update
name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the updated prompt template.

update_question_reply_feedback(reply_id: str, expected_answer: str, user_comment: str)

Update feedback for a specific answer to a question.

Args:

reply_id:: UUID of the reply.
expected_answer:: Expected answer.
user_comment:: User comment.

Returns:

None

update_runtime_llm(model_id: str, config: Dict[str, Any]) → Dict[str, Any]: NOT SUPPORTED – a runtime LLM can only be created and deleted; this call is rejected by the server. display_name is the routing key at the serving proxy, so an in-place edit can leave a saved, successfully probed model whose every request fails there. To change a configuration, delete_runtime_llm() it and create_runtime_llm() it again (admin only).

Partially update a scheduled task. Omitted args are left unchanged.

To pause/resume, pass status=’paused’/’active’. To CLEAR a nullable field, use the sentinels: max_executions=-1 clears it; expires_at=’1970-01-01T00:00:00Z’ clears it.

To change individual task_config fields without resending the whole dict, pass task_config_patch: top-level keys are merged server-side; a key set to None is REMOVED (e.g. task_config_patch={“collection_id”: None} unbinds the collection). Nested objects are replaced whole. Mutually exclusive with task_config. The merged result must keep a non-empty ‘message’. Example: task_config_patch={“message”: “new prompt”}.

Args:

message: Convenience for task_config_patch={‘message’: …}: changes: just this config field, server-side merge, no other fields touched. None = no change.
timezone: Convenience for task_config_patch={‘timezone’: …}: changes: just this config field, server-side merge, no other fields touched. None = no change. To CLEAR the timezone, use task_config_patch={‘timezone’: None} (a kwarg None cannot express removal).
collection_id: Convenience for task_config_patch={‘collection_id’: …}:: changes just this config field, server-side merge, no other fields touched. None = no change. To UNBIND the collection, use task_config_patch={‘collection_id’: None} (a kwarg None cannot express removal).

Returns:

ScheduledTask: the updated task (refetched).

Update any user’s scheduled task — status and metadata only (admin only).

Note: max_executions and expires_at cannot be changed through this admin method (matches the UI). Returns {‘status’: ‘updated’}.

update_secret(secret_id: str, secret: Dict[str, Any]) → None

Update an existing secret in the SecureStore.

Args:: secret_id: The ID of the secret to update. secret: A dictionary containing the updated secret data

(the payload stored under secret_value).
Returns:: None

update_shared_chat(shared_chat_id: str, is_private: bool | None = None, includes_artifacts: bool | None = None) → None

Update a shared chat’s settings.

Only shared chats owned by the current user can be updated.

Args:

shared_chat_id:: ID of the shared chat to update.
is_private:: If provided, update the privacy setting.
includes_artifacts:: If provided, update the artifacts inclusion setting.

update_showcase_chat(showcase_id: str, title: str | None = None, description: str | None = None, category: str | None = None) → None

Update tile metadata on a showcase entry. Requires manage_showcase. The thumbnail is managed exclusively via upload_showcase_thumbnail / delete_showcase_thumbnail.

None (default) leaves a field untouched on the server.

title and description cannot be cleared — passing an empty string yields a 400 from the server. Only category accepts an empty string, which clears it back to NULL and moves the tile into the Uncategorized group.

update_tag(tag_name: str, description: str, format: str) → str

Updates a tag.

Args:

tag_name:: String representing the tag to update.
description:: String describing the tag.
format:: String representing the format of the tag.

Returns:

String: The id of the updated tag.

update_user_builtin_mcp(mcp_id: str, mcp_config: dict) → dict

Update an existing user builtin MCP configuration.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may edit any entry.

Args:

mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) mcp_config: Dictionary containing the updated MCP configuration.

Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

Returns:

dict: Dictionary with the updated MCP details

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the MCP config is invalid

Example:

```python mcp_config = {

“name”: “My Updated MCP”, “description”: “Updated description”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = client.update_user_builtin_mcp(“my_custom_builtin”, mcp_config) ```

upload(file_name: str, file: Any, uri: str | None = None) → str

Upload a file to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:

ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file

Args:

file_name:: What to name the file on the server, must include file extension.
file:: File object to upload, often an opened file from with open(…) as f.
uri:: Optional - URI you would like to associate with the file.

Returns:

str: The upload id to be used in ingest jobs.

Raises:

Exception: The upload request was unsuccessful.

upload_showcase_thumbnail(showcase_id: str, file_path: str | Path) → UploadShowcaseThumbnailResponse: Upload an image file as the thumbnail for a showcase tile.

vote_on_forum_post(post_id: str, vote: int, assistant_id: str | None = None) → None

Vote on a forum post.

Args:: post_id: The post’s UUID. vote: +1 for upvote, -1 for downvote, 0 to clear vote. assistant_id: Optional assistant ID if voting as an assistant.

wake_ai_assistant(assistant_id: str) → None

Manually trigger a wake cycle for an AI assistant.

The assistant must be in ‘sleeping’ status. This calls the REST API endpoint which pushes a wake event to Redis for the event loop to process.

Uses the REST API endpoint which pushes the wake event via Redis, unlike calling the RPC directly which would only update the DB status.

Args:: assistant_id: The assistant’s UUID.

h2ogpte.session module

class h2ogpte.session.Session(address: str, chat_session_id: str, client: H2OGPTE = None, prompt_template_id: str | None = None, open_timeout: int = 10, close_timeout: int = 10, max_connect_retries: int = 10, connect_retry_delay: int = 0.5, connect_retry_max_delay: int = 60)

Bases: object

Create and participate in a chat session.

This is a live connection to the h2oGPTe server contained to a specific chat session on top of a single collection of documents. Users will find all questions and responses in this session in a single chat history in the UI.

See Also:

H2OGPTE.connect: To initialize a session on an existing connection.

Args:

address:: Full URL of the h2oGPTe server to connect to.
chat_session_id:: The ID of the chat session the queries should be sent to.
client:: Set to the value of H2OGPTE client object used to perform other calls to the system.

Examples:

# Example 1: Best practice, create a session using the H2OGPTE module
with h2ogpte.connect(chat_session_id) as session:
    answer1 = session.query('How many paper clips were shipped to Scranton?', timeout=10)
    answer2 = session.query('Did David Brent co-sign the contract with Initech?', timeout=10)

# Example 2: Connect and disconnect manually
session = Session(
    address=address,
    client=client,
    chat_session_id=chat_session_id
)
session.connect()
answer = session.query("Are there any dogs in the documents?")
session.disconnect()

connect()

Connect to an h2oGPTe server.

This is primarily an internal function used when users create a session using with from the H2OGPTE.connection() function.

property connection: ClientConnection

disconnect()

Disconnect from an h2oGPTe server.

This is primarily an internal function used when users create a session using with from the H2OGPTE.connection() function.

Retrieval-augmented generation for a query on a collection.

Finds a collection of chunks relevant to the query using similarity scores. Sends these and any additional instructions to an LLM.

Format of questions or imperatives:

"{pre_prompt_query}
"""
{similar_context_chunks}
"""                {prompt_query}{message}"

Args:

message:

Query or instruction from the end user to the LLM.

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks. The default can be customized per environment, but the standard default is "Pay attention and remember the information below, which will help to answer the question or imperative after the context ends.\n"

prompt_query:

Text that is appended to the beginning of the user’s message. The default can be customized per environment, but the standard default is “According to only the information in the document sources provided within the context above, “

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

pre_prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Use None or “auto” for automatic model routing, set cost_controls for detailed control over automatic routing.

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering. top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation. seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed. repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty. max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction. min_max_new_tokens (int, default: 512) — minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”]. guided_json (dict, default: None) — If specified, the output will follow the JSON schema. guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_choice (Optional[List[str]], default: None — If specified, the output will be exactly one of the choices. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. enable_vision (str, default: “auto”) - Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”]. visible_vision_models (List[str], default: [“auto”]) - Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic. images_num_max (int, default: None) — Maximum number of images to process. json_preserve_system_prompt (bool, default: None) — Whether to preserve system prompt in JSON response. client_metadata (str, default: None) — Additional metadata to send with the request. min_chars_per_yield (int, default: 1) — Minimum characters to yield in streaming response. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort. cost_controls: Optional dictionary

max_cost (float) - Sets the maximum allowed cost in USD per LLM call when doing Automatic model routing. If the estimated cost based on input and output token counts is higher than this limit, the request will fail as early as possible. max_cost_per_million_tokens (float) - Only consider models that cost less than this value in USD per million tokens when doing automatic routing. Using the max of input and output cost. model (List[str] or None) - Optional subset of models to consider when doing automatic routing. None means consider all models. willingness_to_pay (float) - Controls the willingness to pay extra for a more accurate model for every LLM call when doing automatic routing, in units of USD per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated cost divided by the increase in estimated accuracy is no more than this value divided by 10%, up to the upper limit specified above. Lower values will try to keep the cost as low as possible, higher values will approach the cost limit to increase accuracy. 0 means unlimited. willingness_to_wait (float) - Controls the willingness to wait longer for a more accurate model for every LLM call when doing automatic routing, in units of seconds per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated time divided by the increase in estimated accuracy is no more than this value divided by 10%. Lower values will try to keep the time as low as possible, higher values will take longer to increase accuracy. 0 means unlimited.

use_agent (bool, default: False) - If True, use the AI agent (with access to tools) to generate the response. agent_accuracy (str, default: “standard”) - Effort level by the agent. Only if use_agent=True. One of [“quick”, “basic”, “standard”, “maximum”]. agent_max_turns (Optional[Union[str, int]], default: “auto”) - Optional max. number of back-and-forth turns with the agent. Only if use_agent=True. Either “auto” or an integer. agent_tools (Optional[Union[str, List[str]]], default: “auto”) - Either “auto”, “all”, “any” to enable all available tools, or a specific list of tools to use. Only if use_agent=True. Get full list by calling await self._lang(“get_agent_tools_options”). agent_type (str, default: “auto”) — Type of agent to use for task processing. agent_original_files (List[str], default: None) — List of file paths for agent to process. agent_timeout (int, default: None) — Timeout in seconds for each agent turn. agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent processing. agent_min_time (int, default: 0) — Minimum time in seconds for all agent processing. final_answer_guidelines_mode (str, default: “auto”) — Mode for formatting agent final answers. Options:

auto: chooses “detailed” for now, but may later adapt

detailed: full deep_research like final answer guidelines

detailed_no_file_links: Like detailed, but without files provided to LLM for final answer so LLM doesn’t over-emphasize showing file links except what it auto-decides from chat history

detailed_no_image_links: Like detailed, but without images provided to LLM for final answer so LLM doesn’t over-emphasize showing image links except what it auto-decides from chat history

detailed_no_links: Like detailed, but without files or images provided to LLM for final answer so LLM doesn’t over-emphasize showing file or image links except what it auto-decides from chat history

file_template: Use file final_answer_guidelines_template.txt (in agent_files or original_agent_files) that has optional f-strings: agent_accuracy, new_image_files, new_non_image_files, formatted_references

raw_LLM: Bypasses final answer guidelines and just stops after own final LLM response that has no executable code.

agent_code_writer_system_message (str, default: None) — System message for agent code writer. agent_num_executable_code_blocks_limit (int, default: 1) — Maximum number of executable code blocks. agent_system_site_packages (bool, default: True) — Whether agent has access to system site packages. agent_main_model (Optional[str], default: None) — Main model to use for agent. agent_max_stream_length (Optional[int], default: None) — Maximum stream length for agent response. agent_max_memory_usage (int, default: 16*1024**3) — Maximum memory usage for agent in bytes (16GB default). agent_main_reasoning_effort (Optional[int], default: None) — Effort level for main reasoning. agent_advanced_reasoning_effort (Optional[int], default: None) — Effort level for advanced reasoning. agent_max_confidence_level (Optional[int], default: None) — Maximum confidence level for agent responses. agent_planning_forced_mode (Optional[bool], default: None) — Whether to force planning mode for agent. agent_too_soon_forced_mode (Optional[bool], default: None) — Whether to force “too soon” mode for agent. agent_critique_forced_mode (Optional[int], default: None) — Whether to force critique mode for agent. agent_query_understanding_parallel_calls (Optional[int], default: None) — Number of parallel calls for query understanding. tool_building_mode (Optional[str], default: None) — Mode for tool building configuration. agent_stream_files (bool, default: True) — Whether to stream files from agent.

self_reflection_config:

Dictionary of arguments for self-reflection, can contain the following string:string mappings:

llm_reflection: str
"gpt-4-0613" or "" to disable reflection

prompt_reflection: str
‘Here’s the prompt and the response: """Prompt:\n%s\n"""\n\n""" Response:\n%s\n"""\n\nWhat is the quality of the response for the given prompt? Respond with a score ranging from Score: 0/10 (worst) to Score: 10/10 (best), and give a brief explanation why.'

system_prompt_reflection: str
""

llm_args_reflection: str
"{}"

rag_config:

Dictionary of arguments to control RAG (retrieval-augmented-generation) types. Can contain the following key/value pairs: rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.
Requires 1 Agent call.

"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.
Requires 1 Agent call with RAG tool execution.

"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code
execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.

"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts
to answer the query. Requires 1 LLM or Agent call.

"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.

"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant
contexts from a collection for generating a response. Requires 3 LLM calls.

"rag+" Summary RAG - Like RAG, but uses more context and recursive
summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.

"all_data" All Data RAG - Like Summary RAG, but includes all document
chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

hyde_no_rag_llm_prompt_extension: str

Add this prompt to every user’s prompt, when generating answers to be used for subsequent retrieval during HyDE. Only used when rag_type is “hyde1” or “hyde2”. example: '\nKeep the answer brief, and list the 5 most relevant key words at the end.'

num_neighbor_chunks_to_include: int

Number of neighboring chunks to include for every retrieved relevant chunk. Helps to keep surrounding context together. Only enabled for rag_type “rag+”. Defaults to 1.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context for a chat with a collection. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

rag_max_chunks:

Maximum number of document chunks to retrieve for RAG. If not specified (default: -1), actual number depends on rag_type and admin configuration. Set to >0 values to enable. Can be combined with rag_min_chunk_score.

rag_min_chunk_score:

Minimum score of document chunks to retrieve for RAG. If not specified (default: 0.0), will not filter chunks by score. Set to >0 values to enable. Can be combined with rag_max_chunks.

include_chat_history:

Whether to include chat history. Includes previous questions and answers for the current chat session for each new chat request. Disable if require deterministic answers for a given question. Choices are: [“on”,”off”,”auto”,True,False]

tags:

Filter documents by tags for RAG. Can be: - List format: [“red”, “blue”] includes documents with these tags - TagFilter object: TagFilter(include=[“red”], exclude=[“blue”])

metadata_filter:

A dictionary to filter documents by metadata, from which to pull the context for RAG.

timeout:

Amount of time in seconds to allow the request to run. The default is 1000 seconds.

retries:

Amount of retries to allow the request to run when hits a network issue. The default is 3.

callback:

Function for processing partial messages, used for streaming responses to an end user.

Returns:

ChatMessage: The response text and details about the response from the LLM. For example:

ChatMessage(
    id='XXX',
    content='The information provided in the context...',
    reply_to='YYY',
    votes=0,
    created_at=datetime.datetime(2023, 10, 24, 20, 12, 34, 875026)
    type_list=[],
)

Raises:

TimeoutError: The request did not complete in time.

h2ogpte.session.deserialize(response: str) → ChatResponse | ChatAcknowledgement | None

h2ogpte.session.serialize(request: ChatRequest) → str

h2ogpte.types module

class h2ogpte.types.APIKey(*, id: str, username: str, name: str, hint: str, created_at: datetime, expires_at: datetime | None = None, is_active: bool, collection_name: str | None = None, collection_id: str | None = None, is_global_key: bool, last_used_at: datetime | None = None, total_calls: int, inactivity_interval: int | None = None)

Bases: BaseModel

collection_id: str | None

collection_name: str | None

created_at: datetime

expires_at: datetime | None

hint: str

id: str

inactivity_interval: int | None

is_active: bool

is_global_key: bool

last_used_at: datetime | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

total_calls: int

username: str

class h2ogpte.types.Answer(*, content: str, error: str, prompt_raw: str = '', llm: str, input_tokens: int = 0, output_tokens: int = 0, origin: str = 'N/A')

Bases: BaseModel

content: str

error: str

input_tokens: int

llm: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

origin: str

output_tokens: int

prompt_raw: str

class h2ogpte.types.ChatAcknowledgement(t: str, session_id: str, correlation_id: str, message_id: str, username: str, body: str, use_agent: bool | None = None)

Bases: object

body: str

correlation_id: str

message_id: str

session_id: str

t: str

use_agent: bool | None = None

username: str

class h2ogpte.types.ChatMessage(*, id: str, content: str, reply_to: str | None = None, votes: int, created_at: datetime, type_list: List[str] | None = None, error: str | None = None)

Bases: BaseModel

content: str

created_at: datetime

error: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reply_to: str | None

type_list: List[str] | None

votes: int

class h2ogpte.types.ChatMessageFull(*, id: str, username: str | None = None, content: str, reply_to: str | None = None, votes: int, created_at: datetime, type_list: List[ChatMessageMeta] | None = [], has_references: bool, total_references: int, collection_id: str | None = None, collection_name: str | None = None, error: str | None = None, llm_args: str | None = None)

Bases: BaseModel

collection_id: str | None

collection_name: str | None

content: str

created_at: datetime

error: str | None

has_references: bool

id: str

llm_args: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reply_to: str | None

total_references: int

type_list: List[ChatMessageMeta] | None

username: str | None

votes: int

class h2ogpte.types.ChatMessageMeta(*, message_type: str, content: str)

Bases: BaseModel

content: str

message_type: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.ChatMessageReference(*, document_id: str, document_name: str, chunk_id: int, pages: str, score: float, content: str, collection_id: str, were_references_deleted: bool, uri: str | None = None)

Bases: BaseModel

chunk_id: int

collection_id: str

content: str

document_id: str

document_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pages: str

score: float

uri: str | None

were_references_deleted: bool

Bases: object

body: str

correlation_id: str

image_batch_final_prompt: str | None = None

image_batch_image_prompt: str | None = None

include_chat_history: bool | str | None = False

llm: str | int | None

llm_args: str | None

metadata_filter: str | None = None

mode: str

pre_prompt_query: str | None

pre_prompt_summary: str | None

prompt_query: str | None

prompt_summary: str | None

rag_config: str | None

self_reflection_config: str | None

session_id: str

system_prompt: str | None

t: str

tags: List[str] | TagFilter | None = None

class h2ogpte.types.ChatResponse(t: str, session_id: str, message_id: str, reply_to_id: str, body: str, error: str, meta: List[Any] = <factory>, error_type: Optional[str] = None, retry_after: Optional[int] = None, correlation_id: Optional[str] = None)

Bases: object

body: str

correlation_id: str | None = None

error: str

error_type: str | None = None

message_id: str

meta: List[Any]

reply_to_id: str

retry_after: int | None = None

session_id: str

t: str

class h2ogpte.types.ChatSessionCount(*, chat_session_count: int)

Bases: BaseModel

chat_session_count: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.ChatSessionForCollection(*, id: str, latest_message_content: str | None = None, updated_at: datetime, name: str | None = None, username: str | None = None, source: str | None = None)

Bases: BaseModel

id: str

latest_message_content: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None

source: str | None

updated_at: datetime

username: str | None

class h2ogpte.types.ChatSessionForDocument(*, id: str, latest_message_content: str | None = None, updated_at: datetime, source: str | None = None)

Bases: BaseModel

id: str

latest_message_content: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

source: str | None

updated_at: datetime

Bases: BaseModel

archived_at: datetime | None

collection_id: str | None

collection_name: str | None

expiry_date: datetime | None

id: str

inactivity_interval: int | None

keep_forever: bool | None

latest_message_content: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | None

prompt_template_id: str | None

source: str | None

status: str | None

updated_at: datetime

username: str | None

workspace: str | None

class h2ogpte.types.ChatShareUrl(url: str, relative_path: str)

Bases: object

relative_path: str

url: str

class h2ogpte.types.Chunk(*, text: str, id: int, name: str, size: int, pages: str, start_time: float | None = None, end_time: float | None = None)

Bases: BaseModel

end_time: float | None

id: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

pages: str

size: int

start_time: float | None

text: str

class h2ogpte.types.Collection(*, id: str, name: str, description: str, document_count: int, document_size: int, created_at: datetime, updated_at: datetime, username: str, rag_type: str | None = None, embedding_model: str | None = None, prompt_template_id: str | None = None, collection_settings: dict | None = None, is_public: bool, thumbnail: str | None = None, metadata_dict: dict | None = None, chat_settings: dict | None = None, status: str, expiry_date: datetime | None = None, inactivity_interval: int | None = None, size_limit: int | None = None, workspace: str | None = None, has_default_guardrails: bool | None = None, vex_encryption: str | None = None, exempt_from_chat_expiry: bool | None = None, description_auto_generated: bool | None = None, description_generated_at: datetime | None = None, description_dirty_at: datetime | None = None, description_generation_started_at: datetime | None = None)

Bases: BaseModel

chat_settings: dict | None

collection_settings: dict | None

created_at: datetime

description: str

description_auto_generated: bool | None

description_dirty_at: datetime | None

description_generated_at: datetime | None

description_generation_started_at: datetime | None

document_count: int

document_size: int

embedding_model: str | None

exempt_from_chat_expiry: bool | None

expiry_date: datetime | None

has_default_guardrails: bool | None

id: str

inactivity_interval: int | None

is_public: bool

metadata_dict: dict | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

prompt_template_id: str | None

rag_type: str | None

size_limit: int | None

status: str

thumbnail: str | None

updated_at: datetime

username: str

vex_encryption: str | None

workspace: str | None

class h2ogpte.types.CollectionCount(*, collection_count: int)

Bases: BaseModel

collection_count: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.CollectionInfo(*, id: str, name: str, description: str, embedding_model: str, document_count: int, document_size: int, updated_at: datetime, created_at: datetime, user_count: int, is_public: bool, username: str, sessions_count: int, status: str, expiry_date: datetime | None = None, inactivity_interval: int | None = None, archived_at: datetime | None = None, size_limit: int | None = None, metadata_dict: dict | None = None, workspace: str | None = None, exempt_from_chat_expiry: bool | None = None)

Bases: BaseModel

archived_at: datetime | None

created_at: datetime

description: str

document_count: int

document_size: int

embedding_model: str

exempt_from_chat_expiry: bool | None

expiry_date: datetime | None

id: str

inactivity_interval: int | None

is_public: bool

metadata_dict: dict | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

sessions_count: int

size_limit: int | None

status: str

updated_at: datetime

user_count: int

username: str

workspace: str | None

class h2ogpte.types.ConfigItem(*, key_name: str, string_value: str, value_type: str)

Bases: BaseModel

key_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

string_value: str

value_type: str

class h2ogpte.types.Document(*, id: str, name: str, type: str, size: int, page_count: int, guardrails_settings: dict | None = None, connector: str | None = None, uri: str | None = None, original_type: str | None = None, original_mtime: datetime | None = None, meta_data_dict: dict | None = None, status: Status, created_at: datetime, updated_at: datetime, user_source_file: dict | None = None, page_ocr_model_dict: dict | None = None, page_layout_dict: dict | None = None, metadata_dict: dict | None = None, is_encrypted: bool = False, encrypted_dek: bytes | None = None)

Bases: BaseModel

connector: str | None

created_at: datetime

encrypted_dek: bytes | None

guardrails_settings: dict | None

id: str

is_encrypted: bool

meta_data_dict: dict | None

metadata_dict: dict | None

model_config: ClassVar[ConfigDict] = {'use_enum_values': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

original_mtime: datetime | None

original_type: str | None

page_count: int

page_layout_dict: dict | None

page_ocr_model_dict: dict | None

size: int

status: Status

type: str

updated_at: datetime

uri: str | None

user_source_file: dict | None

class h2ogpte.types.DocumentCount(*, document_count: int)

Bases: BaseModel

document_count: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.DocumentExtractionResult(*, id: str, document_id: str | None = None, document_name: str, content: Dict[str, Any] | str, error: str | None = None)

Bases: BaseModel

content: Dict[str, Any] | str

document_id: str | None

document_name: str

error: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.DocumentInfo(*, id: str, username: str, name: str, type: str, size: int, page_count: int, guardrails_settings: dict | None = None, connector: str | None = None, uri: str | None = None, original_type: str | None = None, meta_data_dict: dict | None = None, status: Status, updated_at: datetime, user_source_file: dict | None = None, page_ocr_model_dict: dict | None = None, page_layout_dict: dict | None = None, metadata_dict: dict | None = None, is_encrypted: bool = False, chat_session_id: str | None = None, chat_session_name: str | None = None, chat_session_visible: bool = False)

Bases: BaseModel

chat_session_id: str | None: Chat session that generated the document, set by the list_recent_documents methods; None for user-uploaded documents.

chat_session_name: str | None: None when the document is not agent-generated, or the session is not visible. A visible session can also simply be unnamed, so check chat_session_visible to tell those apart.

chat_session_visible: bool: Whether the caller can open the source chat session.

connector: str | None

guardrails_settings: dict | None

id: str

is_encrypted: bool

meta_data_dict: dict | None

metadata_dict: dict | None

model_config: ClassVar[ConfigDict] = {'use_enum_values': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

original_type: str | None

page_count: int

page_layout_dict: dict | None

page_ocr_model_dict: dict | None

size: int

status: Status

type: str

updated_at: datetime

uri: str | None

user_source_file: dict | None

username: str

class h2ogpte.types.DocumentInfoSummary(*, id: str, username: str, name: str, type: str, size: int, page_count: int, guardrails_settings: dict | None = None, connector: str | None = None, uri: str | None = None, original_type: str | None = None, meta_data_dict: dict | None = None, status: Status, updated_at: datetime, user_source_file: dict | None = None, usage_stats: str | None = None, summary: str | None = None, summary_parameters: str | None = None, page_ocr_model_dict: dict | None = None, page_layout_dict: dict | None = None, metadata_dict: dict | None = None, is_encrypted: bool = False, chat_session_id: str | None = None, chat_session_name: str | None = None, chat_session_visible: bool = False)

Bases: BaseModel

chat_session_id: str | None: Chat session that generated the document, set by the list_recent_documents methods; None for user-uploaded documents.

chat_session_name: str | None: None when the document is not agent-generated, or the session is not visible. A visible session can also simply be unnamed, so check chat_session_visible to tell those apart.

chat_session_visible: bool: Whether the caller can open the source chat session.

connector: str | None

guardrails_settings: dict | None

id: str

is_encrypted: bool

meta_data_dict: dict | None

metadata_dict: dict | None

model_config: ClassVar[ConfigDict] = {'use_enum_values': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

original_type: str | None

page_count: int

page_layout_dict: dict | None

page_ocr_model_dict: dict | None

size: int

status: Status

summary: str | None

summary_parameters: str | None

type: str

updated_at: datetime

uri: str | None

usage_stats: str | None

user_source_file: dict | None

username: str

class h2ogpte.types.DocumentInfoSummaryListing(*, documents: List[DocumentInfoSummary], total: int)

Bases: BaseModel

A page of documents (with summaries) plus the total match count.

Returned by list_recent_documents_with_summaries_sort_filter_by_type. total is the number of documents matching the filter across all pages — not just the number returned in documents — so callers can drive pagination without a separate count query.

documents: List[DocumentInfoSummary]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total: int

class h2ogpte.types.DocumentSummary(*, id: str, content: str, error: str, document_id: str, kwargs: str, created_at: datetime, usage_stats: str | None = None)

Bases: ProcessedDocument

content: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.ExtractionAnswer(*, content: List[str], error: str, llm: str, input_tokens: int = 0, output_tokens: int = 0)

Bases: BaseModel

content: List[str]

error: str

input_tokens: int

llm: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_tokens: int

class h2ogpte.types.Extractor(*, id: str, created_at: datetime, name: str, description: str | None = None, llm: str | None = None, extractor_schema: Dict[str, Any] | None = None, prompt: str | None = None, pre_prompt_summary: str | None = None, keep_intermediate_results: bool | None = None, system_prompt: str | None = None, max_num_chunks: int | None = None, vision: str | None = None, vision_llm: str | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None, guardrails_settings: Dict[str, Any] | None = None, is_public: bool)

Bases: BaseModel

created_at: datetime

description: str | None

extractor_schema: Dict[str, Any] | None

guardrails_settings: Dict[str, Any] | None

id: str

image_batch_final_prompt: str | None

image_batch_image_prompt: str | None

is_public: bool

keep_intermediate_results: bool | None

llm: str | None

max_num_chunks: int | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

pre_prompt_summary: str | None

prompt: str | None

system_prompt: str | None

vision: str | None

vision_llm: str | None

class h2ogpte.types.GlobalConfigItem(*, key_name: str, string_value: str, value_type: str, can_overwrite: bool, upper_bound: int | float | None = None, is_public: bool)

Bases: BaseModel

can_overwrite: bool

is_public: bool

key_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

string_value: str

upper_bound: int | float | None

value_type: str

class h2ogpte.types.GraphStatus(*, status: str, built_at: datetime | None = None, outdated: bool = False)

Bases: BaseModel

Status of a collection’s knowledge graph.

built_at: datetime | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

outdated: bool

status: str

class h2ogpte.types.GroupSharePermission(*, group_id: str, permissions: List[str] | None = None)

Bases: BaseModel

group_id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

permissions: List[str] | None

class h2ogpte.types.Identifier(*, id: str, error: str | None = None)

Bases: BaseModel

error: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.Job(*, id: str, name: str, passed: float, failed: float, progress: float, completed: bool, canceled: bool, date: datetime, kind: JobKind, statuses: List[JobStatus], errors: List[str], last_update_date: datetime, duration: str, duration_seconds: float, start_time: float | None = None, canceled_by: str | None = None, cancel_reason: str | None = None, timeout: float | None = None, files_total: int | None = None, files_failed: int | None = None)

Bases: BaseModel

cancel_reason: str | None

canceled: bool

canceled_by: str | None

completed: bool

date: datetime

duration: str

duration_seconds: float

errors: List[str]

failed: float

files_failed: int | None

files_total: int | None

id: str

kind: JobKind

last_update_date: datetime

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

passed: float

progress: float

start_time: float | None

statuses: List[JobStatus]

timeout: float | None

class h2ogpte.types.JobKind(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

BuildCollectionGraphJob = 'BuildCollectionGraphJob'

BuildSystemPromptJob = 'BuildSystemPromptJob'

CreateTopicModelJob = 'CreateTopicModelJob'

DeleteArchivedChatSessionsJob = 'DeleteArchivedChatSessionsJob'

DeleteChatSessionsAsAdminJob = 'DeleteChatSessionsAsAdminJob'

DeleteChatSessionsJob = 'DeleteChatSessionsJob'

DeleteCollectionThumbnailJob = 'DeleteCollectionThumbnailJob'

DeleteCollectionsAsAdminJob = 'DeleteCollectionsAsAdminJob'

DeleteCollectionsJob = 'DeleteCollectionsJob'

DeleteDocumentsFromCollectionJob = 'DeleteDocumentsFromCollectionJob'

DeleteDocumentsJob = 'DeleteDocumentsJob'

DeleteUserJob = 'DeleteUserJob'

DocumentSummaryJob = 'DocumentProcessJob'

EvalCollectionJob = 'EvalCollectionJob'

EvalMessageJob = 'EvalMessageJob'

ExportFeedbackCSVJob = 'ExportFeedbackCSVJob'

ImportCollectionIntoCollectionJob = 'ImportCollectionIntoCollectionJob'

ImportDocumentIntoCollectionJob = 'ImportDocumentIntoCollectionJob'

IndexFilesJob = 'IndexFilesJob'

IngestAgentOnlyToStandardJob = 'IngestAgentOnlyToStandardJob'

IngestFromCloudStorageJob = 'IngestFromCloudStorageJob'

IngestFromFileSystemJob = 'IngestFromFileSystemJob'

IngestPlainTextJob = 'IngestPlainTextJob'

IngestUploadsJob = 'IngestUploadsJob'

IngestWebsiteJob = 'IngestWebsiteJob'

IngestWithScheduledConnectorJob = 'IngestWithScheduledConnectorJob'

MigrateCollectionChatSessionsJob = 'MigrateCollectionChatSessionsJob'

MigrateScheduledConnectorsToCollectionJob = 'MigrateScheduledConnectorsToCollectionJob'

NoOpJob = 'NoOpJob'

RegenerateCollectionDescriptionJob = 'RegenerateCollectionDescriptionJob'

RunExtractorJob = 'RunExtractorJob'

RunExtractorOnUploadsJob = 'RunExtractorOnUploadsJob'

ScheduledTaskExecutionJob = 'ScheduledTaskExecutionJob'

UpdateCollectionStatsJob = 'UpdateCollectionStatsJob'

UpdateCollectionThumbnailJob = 'UpdateCollectionThumbnailJob'

class h2ogpte.types.JobStatus(*, id: str, status: str)

Bases: BaseModel

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: str

class h2ogpte.types.LLMPerformance(*, llm_name: str, call_count: int, input_tokens: int, output_tokens: int, tokens_per_second: float, time_to_first_token: float)

Bases: BaseModel

call_count: int

input_tokens: int

llm_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_tokens: int

time_to_first_token: float

tokens_per_second: float

class h2ogpte.types.LLMUsage(*, llm_name: str, llm_cost: float, call_count: int, input_tokens: int, output_tokens: int)

Bases: BaseModel

call_count: int

input_tokens: int

llm_cost: float

llm_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_tokens: int

class h2ogpte.types.LLMUsageLimit(*, current: float, max_allowed_24h: float, cost_unit: str, interval: str)

Bases: BaseModel

cost_unit: str

current: float

interval: str

max_allowed_24h: float

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.LLMWithUserUsage(*, llm_name: str, total_cost: float, total_calls: int, total_input_tokens: int, total_output_tokens: int, user_usage: List[UserUsage])

Bases: BaseModel

llm_name: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

total_calls: int

total_cost: float

total_input_tokens: int

total_output_tokens: int

user_usage: List[UserUsage]

class h2ogpte.types.Meta(*, version: str, build: str, username: str, user_id: str, subject: str, email: str, is_guest: bool, license_expired: bool, license_expiry_date: str, global_configs: List[GlobalConfigItem], user_configs: List[ConfigItem], picture: str | None, groups: List[str] | None, workspaces: List[str] | None, permissions: List[str], ui_config: MetaUIConfig)

Bases: BaseModel

build: str

email: str

global_configs: List[GlobalConfigItem]

groups: List[str] | None

is_guest: bool

license_expired: bool

license_expiry_date: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

permissions: List[str]

picture: str | None

subject: str

ui_config: MetaUIConfig

user_configs: List[ConfigItem]

user_id: str

username: str

version: str

workspaces: List[str] | None

class h2ogpte.types.MetaUIConfig(*, logo: str, chat_logo: str, primary_color: str, chat_name: str, greeting: str, show_private_button: bool, show_workers_status: bool, show_live_logs: bool, show_eval: bool, show_extractors: bool, public_mode: bool)

Bases: BaseModel

chat_logo: str

chat_name: str

greeting: str

logo: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

primary_color: str

public_mode: bool

show_eval: bool

show_extractors: bool

show_live_logs: bool

show_private_button: bool

show_workers_status: bool

class h2ogpte.types.ObjectCount(*, chat_session_count: int, collection_count: int, document_count: int)

Bases: BaseModel

chat_session_count: int

collection_count: int

document_count: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class h2ogpte.types.PartialChatMessage(*, id: str, content: str, reply_to: str | None = None, meta: List[Any] | None = None)

Bases: BaseModel

content: str

id: str

meta: List[Any] | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

reply_to: str | None

class h2ogpte.types.PostProcessor(*, id: str, name: str, description: str, llm_prompt: str, user_id: str, created_at: datetime, updated_at: datetime)

Bases: BaseModel

created_at: datetime

description: str

id: str

llm_prompt: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

updated_at: datetime

user_id: str

class h2ogpte.types.ProcessedDocument(*, id: str, content: str | List[str], error: str, document_id: str, kwargs: str, created_at: datetime, usage_stats: str | None = None)

Bases: BaseModel

content: str | List[str]

created_at: datetime

document_id: str

error: str

id: str

kwargs: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

usage_stats: str | None

class h2ogpte.types.PromptTemplate(*, is_default: bool, id: str | None, name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, created_at: datetime | None = None, user_id: str | None = '', username: str | None = '', user_count: int | None = -1, group_count: int | None = -1, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None, is_public: bool, visible: bool | None = None, is_system_default: bool)

Bases: BaseModel

auto_gen_description_prompt: str | None

auto_gen_document_sample_questions_prompt: str | None

auto_gen_document_summary_pre_prompt_summary: str | None

auto_gen_document_summary_prompt_summary: str | None

created_at: datetime | None

default_sample_questions: List[str] | None

description: str | None

group_count: int | None

hyde_no_rag_llm_prompt_extension: str | None

id: str | None

image_batch_final_prompt: str | None

image_batch_image_prompt: str | None

is_default: bool

is_public: bool

is_system_default: bool

lang: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

pre_prompt_query: str | None

pre_prompt_reflection: str | None

pre_prompt_summary: str | None

prompt_query: str | None

prompt_reflection: str | None

prompt_summary: str | None

system_prompt: str | None

system_prompt_reflection: str | None

user_count: int | None

user_id: str | None

username: str | None

visible: bool | None

class h2ogpte.types.PromptTemplateCount(*, prompt_template_count: int)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prompt_template_count: int

Bases: BaseModel

chat_session_id: str | None

collection_documents: List[str] | None

collection_id: str | None

collection_name: str | None

expected_answer: str | None

include_chat_history: bool | str | None

llm: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pre_prompt_query: str | None

pre_prompt_summary: str | None

prompt_query: str | None

prompt_summary: str | None

prompt_template_id: str | None

question_content: str

question_id: str

rag_config: str | None

reply_content: str

reply_id: str

response_created_at_time: str

system_prompt: str | None

user_comment: str | None

voted_user_id: str | None

voted_username: str | None

votes: int

class h2ogpte.types.QuestionReplyDataCount(*, question_reply_data_count: int)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

question_reply_data_count: int

class h2ogpte.types.QueueInfo(*, name: str, length: int)

Bases: BaseModel

length: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

exception h2ogpte.types.RateLimitError(message: str, retry_after: int = 0)

Bases: SessionError

Raised when a request is rejected due to rate limiting.

class h2ogpte.types.Result(*, status: Status)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {'use_enum_values': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: Status

class h2ogpte.types.ScheduledConnectorDetails(*, id: str, user_id: str, user_name: str | None = None, user_email: str | None = None, collection_id: str, collection_name: str | None = None, type: str, config: Dict[str, Any] | None = None, schedule: int, last_sync_status: str | None = None, last_sync_job_id: str | None = None, last_sync_at: datetime | None = None, last_sync_error: str | None = None, created_at: datetime)

Bases: BaseModel

collection_id: str

collection_name: str | None

config: Dict[str, Any] | None

created_at: datetime

id: str

last_sync_at: datetime | None

last_sync_error: str | None

last_sync_job_id: str | None

last_sync_status: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schedule: int

type: str

user_email: str | None

user_id: str

user_name: str | None

class h2ogpte.types.SchedulerStats(*, queue_length: int, queue_infos: List[QueueInfo])

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

queue_infos: List[QueueInfo]

queue_length: int

class h2ogpte.types.SearchResult(*, id: int, topic: str, name: str, text: str, size: int, pages: str, score: float)

Bases: BaseModel

id: int

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

pages: str

score: float

size: int

text: str

topic: str

class h2ogpte.types.SearchResults(*, result: List[SearchResult])

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

result: List[SearchResult]

exception h2ogpte.types.SessionError: Bases: Exception

class h2ogpte.types.SharePermission(*, username: str, permissions: List[str] | None = None)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

permissions: List[str] | None

username: str

class h2ogpte.types.ShareResponseStatus(*, status: str)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

status: str

class h2ogpte.types.SharedChatDetail(name: str | None, shared_at: str | None, shared_by: str | None, is_frozen: bool, is_private: bool, includes_artifacts: bool, messages: List[Dict[str, Any]])

Bases: object

includes_artifacts: bool

is_frozen: bool

is_private: bool

messages: List[Dict[str, Any]]

name: str | None

shared_at: str | None

shared_by: str | None

class h2ogpte.types.SharedChatInfo(id: str, is_private: bool, is_frozen: bool, includes_artifacts: bool, created_at: str, name: str | None = None, chat_session_id: str | None = None, showcase_id: str | None = None)

Bases: object

chat_session_id: str | None = None

created_at: str

id: str

includes_artifacts: bool

is_frozen: bool

is_private: bool

name: str | None = None

showcase_id: str | None = None

class h2ogpte.types.Status(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

AgentOnly = 'agent_only'

Canceled = 'canceled'

Completed = 'completed'

Failed = 'failed'

Queued = 'queued'

Running = 'running'

Scheduled = 'scheduled'

Unknown = 'unknown'

class h2ogpte.types.SuggestedQuestion(*, question: str)

Bases: BaseModel

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

question: str

class h2ogpte.types.Tag(*, id: str, name: str, description: str | None = None, format: str | None = None)

Bases: BaseModel

description: str | None

format: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class h2ogpte.types.TagFilter(include: List[str] | None = None, exclude: List[str] | None = None, document_ids: List[str] | None = None)

Bases: object

Filter for document tags supporting inclusion, exclusion, and direct document IDs.

When document_ids is set, include and exclude filters are ignored — the document IDs take full precedence as an explicit document scope.

Examples:: TagFilter(include=[‘red’, ‘blue’]) TagFilter(exclude=[‘red’, ‘blue’]) TagFilter(include=[‘color’], exclude=[‘red’, ‘blue’]) TagFilter(document_ids=[‘doc-uuid-1’, ‘doc-uuid-2’])

document_ids: List[str] | None = None

exclude: List[str] | None = None

include: List[str] | None = None

class h2ogpte.types.User(*, id: str, email: str, username: str)

Bases: BaseModel

email: str

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

username: str

class h2ogpte.types.UserGroup(*, id: str, name: str, description: str | None = None)

Bases: BaseModel

description: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class h2ogpte.types.UserJobs(*, username: str, user_id: str, jobs: List[Job])

Bases: BaseModel

jobs: List[Job]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

user_id: str

username: str

class h2ogpte.types.UserPermission(*, id: str, name: str, description: str | None = None, category: str | None = None, dependencies: List[str] | None = None)

Bases: BaseModel

category: str | None

dependencies: List[str] | None

description: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

class h2ogpte.types.UserRole(*, id: str, name: str, description: str | None = None, priority: int | None = None)

Bases: BaseModel

description: str | None

id: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

priority: int | None

class h2ogpte.types.UserUsage(*, user_id: str, username: str, email: str, llm_cost: float, call_count: int, input_tokens: int, output_tokens: int)

Bases: BaseModel

call_count: int

email: str

input_tokens: int

llm_cost: float

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

output_tokens: int

user_id: str

username: str

class h2ogpte.types.UserWithLLMUsage(*, user_id: str, username: str, email: str, llm_usage: List[LLMUsage])

Bases: BaseModel

email: str

llm_usage: List[LLMUsage]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

user_id: str

username: str

Module contents

h2oGPTe - AI for documents and more

h2ogpte is the Python client library for H2O.ai’s Enterprise h2oGPTe, a RAG (Retrieval-Augmented Generation) based platform built on top of many open-source software components such as h2oGPT, hnswlib, Torch, Transformers, Golang, Python, k8s, Docker, PyMuPDF, DocTR, and many more.

h2oGPTe is designed to help organizations improve their business using generative AI. It focuses on scaling as your organization expands the number of use cases, users, and documents and has the goal of being your one stop for integrating any model or LLM functionality into your business.

Main Features

Contextualize chat with your own data using RAG (Retrieval-Augmented Generation)
Scalable backend and frontend, multi-user, high throughput
Fully containerized with Kubernetes
Multi-modal support for text, images, and audio
Highly customizable prompting for:
- talk to LLM
- talk to document
- talk to collection of documents
- talk to every page of a collection (Map/Reduce), summary, extraction
LLM agnostic, choose the model you need for your use case

class h2ogpte.H2OGPTE(address: str, api_key: str | None = None, token_provider: TokenProvider | None = None, verify: bool | str = True, strict_version_check: bool = False, send_client_version: bool = True, azure_token: str | None = None)

Bases: H2OGPTESyncBase

Connect to and interact with an h2oGPTe server.

add_agent_key(agent_keys: List[dict]) → List[dict]

Create one or more agent keys for use with agent tools.

Processes a list of agent key configurations and creates each key. Continues processing remaining keys if individual key creation fails.

Args:

agent_keys: List of key configuration dictionaries.

Expected structure:

[
    {
        "name": str,
            # Display name for the key

        "value": str,
            # The actual key/token value

        "key_type": str,
            # Type of key ("private" or "shared")

        "description": str,
            # (Optional) Description of the key's purpose
    }
]

Returns:

List[dict]: List of created key results. Each successful creation: returns {“agent_key_id”: str}. Failed creations are logged but don’t appear in results.

add_builtin_mcp(mcp_id: str, keys: List[dict] | None = None, file_paths: List[str] | None = None) → str

Add a built-in MCP (Model Context Protocol server) to user’s tools.

This configures and enables a predefined MCP for the user, automatically adding it to the user’s tool preferences.

Args:

mcp_id: The ID of the built-in MCP to add (e.g., “playwright_builtin”, “slack_builtin”) keys: Optional list of agent key associations for the MCP.

Each dict should have: {“name”: “ENV_VAR_NAME”, “key_id”: “agent_key_id”}

file_paths: Optional list of file paths to upload for MCP configuration.: Files will be uploaded and attached to the MCP configuration.

Returns:

str: The ID of the added MCP tool

Raises:

InvalidArgumentError: If the MCP is an OAuth app type or file not found

Example:

```python # Add Slack MCP with API key tool_id = client.add_builtin_mcp(

mcp_id=”slack_builtin”, keys=[{“name”: “SLACK_MCP_XOXP_TOKEN”, “key_id”: “my_key_id”}]

)

# Add MCP with file paths (files will be uploaded automatically) tool_id = client.add_builtin_mcp(

mcp_id=”custom_mcp”, file_paths=[“/path/to/config.json”, “/path/to/schema.yaml”]

add_custom_agent(agent_type: str, agent_args: dict, agent_path: str, agent_name: str | None = None) → list

Adds a custom agent by uploading a zip file.

Args:: agent_type: Type of agent (langgraph, crewai, openai, claude) agent_args: Agent configuration arguments agent_path: Path to the agent zip file agent_name: Optional user-provided name for the agent. If provided and the

zip contains exactly one agent, this name will be used instead of the folder name inside the zip. If not provided (or empty), the agent name is derived from the folder name(s) inside the zip.
Returns:: List of agent IDs created from the upload

add_custom_agent_tool(tool_type: str, tool_args: dict, custom_tool_path: str | None = None, generate_system_prompt: bool = False, system_prompt_generation_timeout: float | None = None) → list

Adds a custom agent tool.

Args:

tool_type: The type of custom tool being added. Valid values:

‘local_mcp’: Model Context Protocol server running locally
‘remote_mcp’: Model Context Protocol server running remotely
‘browser_action’: Custom browser automation actions
‘general_code’: General purpose code execution tools

tool_args: Dictionary containing tool-specific arguments. Structure varies by tool_type:

For ‘remote_mcp’: {

“mcp_config_json”: “JSON string with MCP server configuration”, “enable_by_default”: True/False (optional, defaults to True)

}

For ‘local_mcp’, ‘browser_action’, and ‘general_code’: {

“tool_name”: “string (optional, defaults to filename without extension)”, “description”: “string (optional, tool description)”, “enable_by_default”: True/False (optional, defaults to True), “should_unzip”: True/False (optional, for general_code .zip files only), “tool_usage_mode”: [“runner”, “creator”] (optional list of strings, for remote_mcp)

}

custom_tool_path: Path to the tool file to upload (optional). Requirements vary by tool_type:

‘local_mcp’: .zip file containing MCP server code
‘remote_mcp’: Optional configuration file — any extension accepted
(common: .json, .yml, .yaml, .py, .zip, .toml, .ini, .conf, .config, .env, .txt)
‘browser_action’: .py file (must start with ‘browser_’) or .zip containing browser action scripts
‘general_code’: .py or .zip file with custom code

generate_system_prompt:

(Optional) If True and tool_type is “general_code”, generates a system prompt for the tool using LLM analysis and waits for completion. Default is False. Note: this is synchronous and the server holds the connection open until the job completes. Ensure your HTTP client and any intermediate proxies have sufficient timeout (nginx/ALB default to 60-120s, which may cause 504 errors). Use system_prompt_generation_timeout to set a server-side wait budget that returns 408 before the proxy times out.

system_prompt_generation_timeout:

(Optional) Server-side wait budget in seconds. Only used when generate_system_prompt=True. Set below your proxy/ingress read timeout so the API returns 408 instead of letting the proxy emit a 504. Defaults to the server-side cap of 600 seconds (10 minutes).

Returns:

list: List of created custom agent tool IDs

add_role_to_group(group_id: str, roles: List[str]) → List[UserRole]

add_role_to_user(user_id: str, roles: List[str]) → List[UserRole]

add_showcase_chat(shared_chat_id: str, title: str, description: str, category: str | None = None) → AddShowcaseChatResponse

Promote a shared chat to the showcase. Requires manage_showcase.

title and description are required by the server and must be non-empty after trimming; passing an empty string yields a 400.

category is a free-text label used to group tiles in the listing. Pass None (default) to leave the tile uncategorized.

add_skill(skill_path: str, enable_by_default: bool = False) → List[Skill]

Upload a .zip or .skill file to create one or more agent skills.

The zip must contain a SKILL.md file at the root or inside a single subdirectory, with YAML frontmatter containing name and description. A zip with multiple subfolders, each containing a SKILL.md, will create multiple skills.

Args:: skill_path: Path to a .zip or .skill file. enable_by_default: Whether to enable the skill(s) by default for

the user after creation.
Returns:: List[Skill]: The created skill objects.
Raises:: FileNotFoundError: skill_path does not exist. ValueError: skill_path has an unsupported extension or is too

large (>100 MiB).

Example:

skills = client.add_skill("my-skills.zip")
for skill in skills:
    print(skill.id, skill.skill_name)

add_user_document_permission(user_id: str, document_id: str) → [<class 'str'>, <class 'str'>]

Associates a user with a document they have permission on. Args:

user_id:
String The id of the user that has the permission.

document_id:
String The id of the document that the permission is for.

Returns:: [user_id, document_id]: A tuple containing the user_id and document_id.

admin_cleanup_chat_sessions(older_than_days: int, force: bool = False, timeout: float | None = None) → Job

Delete chat sessions older than a specified number of days.

Admin-only. Dispatches a cleanup job for chat sessions that haven’t been active for the specified number of days.

Args:

older_than_days:: Delete sessions inactive for this many days.
force:: If True, also delete keep_forever and exempt sessions.
timeout:: Timeout in seconds.

Returns:

The cleanup job.

Send a message and get a response from an LLM.

Note: This method is only recommended if you are passing a chat conversation or for low-volume testing. For general chat with an LLM, we recommend session.query() for higher throughput in multi-user environments. The following code sample shows the recommended method:
# Establish a chat session
chat_session_id = client.create_chat_session()
# Connect to the chat session
with client.connect(chat_session_id) as session:
    # Send a basic query and print the reply
    reply = session.query("Hello", timeout=60)
    print(reply.content)
Format of inputs content:
{text_context_list}
"""\n{chat_conversation}{question}
Args:

question:
Text query to send to the LLM.

text_context_list:
List of raw text strings to be included, will be converted to a string like this: “

“.join(text_context_list)

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default, or None for h2oGPTe default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks in text_context_list. Only used if text_context_list is provided.

prompt_query:

Text that is appended after the contextual document chunks in text_context_list. Only used if text_context_list is provided.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

# Core generation parameters temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. min_chars_per_yield (int) — Minimum number of characters to yield at a time during streaming reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort

# Output format parameters response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation json_preserve_system_prompt (bool) — Whether to preserve the system prompt when using JSON response format

# Vision and image parameters images_num_max (int) — Maximum number of images to process visible_vision_models (list) — List of vision models that can be used

# Agent parameters use_agent (bool, default: False) — Whether to enable agent functionality for advanced task processing with access to tools shared_agent (bool, default: False) — Whether to use shared agent instance across multiple requests for efficiency agent_type (str, default: “auto”) — Type of agent to use. Options: [“auto”, “agent_analysis”, “agent_chat_history_md”, “agent_code”, “agent_rag”] selected_tool_type (str, default: “auto”) — Type of tools to make available to the agent. Options: [“auto”, “all”, “any”] or specific tool names selected_agent_type (str, optional) — Agent framework type for agents_builder. Options: [“crewai”, “langgraph”, “openai”] agent_accuracy (str, default: “standard”) — Accuracy level for agent operations. Options:

“quick” - Fastest, less verification (max_turns=10, timeout=30s) “basic” - Best for simple tasks (max_turns=20, timeout=60s) “standard” - Good for most tasks (max_turns=40, timeout=120s) “maximum” - Highest accuracy, can take a long time (max_turns=80, timeout=240s)

agent_max_turns (Union[str, int], default: “auto”) — Maximum number of back-and-forth turns the agent can take. Either “auto” or an integer agent_original_files (list) — List of file paths for agent to process and analyze agent_timeout (int) — Timeout in seconds for each individual agent turn/operation agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent operations combined agent_min_time (int) — Minimum time in seconds to run the agent before allowing completion agent_tools (Union[str, list], default: “auto”) — List of specific tools available to the agent. Options: “auto”, “all”, “any”, or list of tool names user_persona (str) — User persona description for agent context to customize agent behavior agent_code_writer_system_message (str) — Custom system message for code writing agent to guide code generation agent_code_restrictions_level (int) — Level of code execution restrictions for agent (typically 0 for unrestricted) agent_num_executable_code_blocks_limit (int) — Maximum number of code blocks the agent can execute in a single session agent_system_site_packages (bool, default: False) — Whether agent can use system site packages when executing code agent_main_model (str) — Main model to use for agent operations (e.g., specific LLM name) agent_max_stream_length (int, default: -1) — Maximum length for agent streaming responses, -1 for unlimited agent_max_memory_usage (int) — Maximum memory usage in bytes for agent operations agent_main_reasoning_effort (int) — Level of reasoning effort for main agent model (higher values = more reasoning, e.g., 10000) agent_advanced_reasoning_effort (int) — Level of reasoning effort for advanced agent operations (e.g., 20000) agent_max_confidence_level (int) — Maximum confidence level for agent decisions (typically 0, 1, or 2) agent_planning_forced_mode (bool) — Whether to force planning mode for agent (True to always plan first) agent_too_soon_forced_mode (bool) — Whether to force handling of premature agent decisions agent_critique_forced_mode (int) — Whether to force critique mode for agent self-evaluation agent_query_understanding_parallel_calls (int) — Number of parallel calls for query understanding tool_building_mode (str) — Mode for tool building configuration agent_stream_files (bool, default: True) — Whether to stream files from agent operations for real-time updates

# Other parameters max_time (int) — Maximum time in seconds for the operation client_metadata (dict) — Metadata to include with the request

chat_conversation:

List of tuples for (human, bot) conversation that will be pre-appended to an (question, None) case for a query.

guardrails_settings:

Guardrails Settings.

timeout:

Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:: h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

archive_chat_session(chat_session_id: str) → str

Archive a chat session along with its associated data.

Admin-only. Sets the session status to ‘archived’, clears expiry settings, and marks keep_forever as false.

Args:

chat_session_id:: ID of the chat session to archive.

archive_collection(collection_id: str) → str

Archive a collection along with its associated data.

Args:

collection_id:: ID of the collection to archive.

assign_agent_key_for_tool(tool_dict_list: List[dict]) → List[Tuple] | None

Assign agent keys to tools by creating associations between them.

Args:

tool_dict_list: List of dictionaries containing tool association data.

Each dictionary should have a “tool_dict” key with the association configuration data for creating agent tool key associations.

Expected tool_dict structure:

{
    "tool": str,        # Name of the tool (for example, "test_tool").
    "keys": list[dict], # List of key definitions. Each item is a dictionary with:
                       #   - "name": str
                       #       Environment variable name (for example, "TEST_KEY").
                       #   - "key_id": Any
                       #       Identifier assigned to the key (for example, agent_key_id).
}

Returns:

Optional[List[Tuple]]: List of tuples containing association details.: Each tuple contains (associate_id, tool, key_name, key_id, user_id). Returns None if no associations were created.

assign_permissions_to_role(role_name: str, permission_names: Iterable[str]) → Result

build_collection_graph(collection_id: str, llm: str | int | None = None, force_rebuild: bool = False, timeout: float | None = None, callback: Callable[[Job], None] | None = None) → Job

Build a knowledge graph for a collection using LightRAG.

Triggers an asynchronous job that extracts entities and relationships from all document chunks in the collection to build a knowledge graph. The graph enables graph-augmented retrieval via the graph_rag RAG type.

Args:

collection_id:: String id of the collection to build the graph for.
llm:: LLM to use for entity extraction. Defaults to the system default.
force_rebuild:: If True, removes any existing graph and rebuilds from scratch.
timeout:: Amount of time in seconds to allow the job to run. The default is 86400 seconds.
callback:: Function for processing job status info during the build.

Returns:

The completed Job object.

bulk_delete_global_configurations(key_names: List[str]) → List[GlobalConfigItem]

bulk_delete_role_configurations(role_id: str, keys: List[str]) → List[ConfigItem]

Delete role configuration items for a given role. Args:

role_id:
The role id to delete configurations for.

keys:
List of configuration keys to delete.

Returns:: List[ConfigItem]: List of remaining role configurations.

bulk_delete_user_configurations_for_user(user_id: str, key_names: List[str]) → List[ConfigItem]

cancel_job(job_id: str) → Result

Stops a specific job from running on the server.

Args:

job_id:: String id of the job to cancel.

Returns:

Result: Status of canceling the job.

cancel_user_job(job_id: str, cancel_reason: str | None = None) → Result

As an admin, stops a specific user job from running on the server.

Args:

job_id:: String id of the job to cancel.
cancel_reason:: Optional reason for canceling the job.

Returns:

Result: Status of canceling the job.

confirm_current_user_deletion(delete_id: str, timeout: float | None = None) → None

Confirm deletion of the current user data.

Args:

delete_id:: The delete ID returned from request_current_user_deletion().
timeout:: Timeout in seconds. Default is 300 seconds.

connect_assistant_to_collection(assistant_id: str, collection_id: str, access_mode: str = 'read') → None

Connect an AI assistant to a document collection.

Once connected, the assistant can use RAG tools (query_collection, read_document, list_documents) against this collection.

Args:: assistant_id: The assistant’s UUID. collection_id: The collection’s UUID. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

Defaults to ‘read’.

connect_assistant_to_forum(assistant_id: str, forum_id: str, access_mode: str = 'read') → None

Connect an AI assistant to a forum.

Args:: assistant_id: The assistant’s UUID. forum_id: The forum’s UUID. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

Defaults to ‘read’ to follow principle of least privilege.

connect_assistant_to_schedule(assistant_id: str, scheduled_task_id: str) → None

Connect an AI assistant to a scheduled task as a wake trigger.

Args:: assistant_id: The assistant’s UUID. scheduled_task_id: The scheduled task’s UUID.

count_assets() → ObjectCount

Counts number of objects owned by the user.

Returns:: ObjectCount: The count of chat sessions, collections, and documents.

count_chat_sessions() → int

Counts number of chat sessions owned by the user.

Returns:: int: The count of chat sessions owned by the user.

count_chat_sessions_for_collection(collection_id: str) → int

Counts number of chat sessions in a specific collection.

Args:

collection_id:: String id of the collection to count chat sessions for.

Returns:

int: The count of chat sessions in that collection.

count_collections() → int

Counts number of collections owned by the user.

Returns:: int: The count of collections owned by the user.

count_documents(chat_session_id: str | None = None) → int

Counts number of documents accessed by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents so a filtered list can be paged against this total.

Returns:

int: The count of documents accessed by the user.

count_documents_in_collection(collection_id: str) → int

Counts the number of documents in a specific collection.

Args:

collection_id:: String id of the collection to count documents for.

Returns:

int: The number of documents in that collection.

count_documents_owned_by_me(chat_session_id: str | None = None) → int

Counts number of documents owned by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents.

Returns:

int: The count of documents owned by the user.

count_jobs_by_status(created_after: datetime | str | None = None) → JobHistoryStats

Count jobs by status over the last 7 days by default (admin only).

Args:

created_after:: Lower bound on created_at. Defaults to the last 7 days when omitted; how far back data exists is bounded by the server’s retention setting (at most 365 days).

Returns:

JobHistoryStats: per-status counts, including cleared (deleted) jobs.

count_prompt_templates() → int

Counts number of prompt templates

Returns:: int: The count of prompt templates

count_question_reply_feedback(collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → int

Fetch user’s questions and answers with feedback count.

Args:

collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only count feedbacks with no collection.

Returns:

int: the count of questions and replies that have a user feedback.

create_ai_assistant(name: str, llm: str, description: str = '', system_prompt: str = '', llm_args: Dict[str, Any] | None = None, custom_tool_definition: str | None = None, mcp_servers: List[Any] | None = None, credential_ids: List[str] | None = None, memory_block_id: str | None = None, notification_email: str | None = None, history_management: str = 'semantic_retrieval', history_max_chars: int | None = None, history_recent_chars: int | None = None, history_retrieval_chars: int | None = None, allowed_tool_actions: List[str] | None = None, allowed_trigger_types: List[str] | None = None, default_wake_period: int | None = None, tool_action_policies: Dict[str, str] | None = None, approval_user_id: str | None = None, custom_approval_text: str | None = None, auto_memory_block: bool = True) → str

Create a new AI assistant.

Args:

name: Name of the assistant (must be unique per user). description: Optional description. system_prompt: System prompt for the assistant’s LLM calls. llm: Model identifier to use. llm_args: Optional dict of additional LLM arguments. custom_tool_definition: Optional custom tool Python code (None = use default). mcp_servers: Optional list of MCP server configuration objects. credential_ids: Optional list of credential/secret UUIDs. memory_block_id: Optional UUID of a memory block for private state.

When None and auto_memory_block is True, an auto memory block is created. When None and auto_memory_block is False, no memory block is used.

notification_email: Optional email for wake cycle notifications. history_management: ‘truncation’, ‘compactification’, or ‘semantic_retrieval’. history_max_chars: Character threshold for history management. history_recent_chars: Characters of recent history to always include (semantic_retrieval mode). history_retrieval_chars: Characters of retrieved history to include (semantic_retrieval mode). allowed_tool_actions: List of allowed tool action names (None = all allowed). allowed_trigger_types: List of allowed trigger types (None = all allowed). default_wake_period: Periodic wake interval in seconds (None = no periodic wake). tool_action_policies: Dict mapping tool action names to policies (None = no policies). approval_user_id: Optional UUID of the designated approval user. custom_approval_text: Optional custom data protection instructions for the agent. auto_memory_block: When True (default) and memory_block_id is None, an auto

memory block is created for the assistant. Set to False to explicitly create an assistant without a memory block.

Returns:

str: The ID of the created assistant.

create_api_key_for_user(user_id: str, name: str | None = None, collection_id: str | None = None, expires_in: str | None = None, inactivity_interval: int | None = None) → str

Allows admins to create a new api key for a specific user and optionally make it specific to a collection. Args:

user_id:
String: The id of the user the API key is for.

name:
(Optional) String: The name of the API key.

collection_id:
(Optional) String: The id of the specific collection.

expires_in:
(Optional) String: The expiration for the API key as an interval. Ex. “30 days” or “30 minutes”

inactivity_interval:
(Optional) int: The number of days a key can be unused for (no activity) before it becomes invalid.

Returns:: String: The id of the API key.

create_assistant_webhook(assistant_id: str, name: str, description: str = '', rate_limit_per_minute: int = 10) → Dict[str, Any]

Create a webhook endpoint for an AI assistant.

External systems can wake the assistant by POSTing to the webhook URL. The token is returned only once — save it immediately.

Args:: assistant_id: ID of the assistant. name: Human-readable name for the webhook. description: Optional description. rate_limit_per_minute: Max invocations per minute (default 10).
Returns:: Dict with ‘id’, ‘token’ (shown only once), ‘name’, and webhook URL.

create_chat_session(collection_id: str | None = None, workspace: str | None = None) → str

Creates a new chat session for asking questions (of documents).

Args:

collection_id:: String id of the collection to chat with. If None, chat with LLM directly.
workspace:: String id of the workspace this chat will be associated with. If None, the user’s default workspace will be used.

Returns:

str: The ID of the newly created chat session.

create_chat_session_on_default_collection() → str

Creates a new chat session for asking questions of documents on the default collection.

Returns:: str: The ID of the newly created chat session.

Creates a new collection.

Args:

name:

Name of the collection.

description:

Description of the collection

embedding_model:

embedding model to use. call list_embedding_models() to list of options.

prompt_template_id:

ID of the prompt template to get the prompts from. None to fall back to system defaults.

collection_settings:

(Optional) Dictionary with key/value pairs to configure certain collection specific settings max_tokens_per_chunk: Approximate max. number of tokens per chunk for text-dominated document pages. For images, chunks can be larger. chunk_overlap_tokens: Approximate number of tokens that are overlapping between successive chunks. gen_doc_summaries: Whether to auto-generate document summaries (uses LLM) gen_doc_questions: Whether to auto-generate sample questions for each document (uses LLM) audio_input_language: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices. ocr_model: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models.

Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. auto - Automatic will auto-select the best OCR model for every page. off - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

tesseract_lang: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices. keep_tables_as_one_chunk: When tables are identified by the table parser the table tokens will be kept in a single chunk. chunk_by_page: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is true. handwriting_check: Check pages for handwriting. Will use specialized models if handwriting is found. follow_links: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document. max_depth: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings). max_documents: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit). root_dir: Root directory for document storage copy_document: Whether to copy the document when importing an existing document. guardrails_settings itself is a dictionary of the following keys.

column_redaction_config: list of list for redacting columns from CSV/TSV files (regex_pattern, fill_value) disallowed_regex_patterns: list of regular expressions that match custom PII presidio_labels_to_flag: list of entities to be flagged as PII by the built-in Presidio model. pii_labels_to_flag: list of entities to be flagged as PII by the built-in PII model. pii_detection_parse_action: what to do when PII is detected during parsing of documents. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content in the ingested documents with redaction bars. pii_detection_llm_input_action: what to do when PII is detected in the input to the LLM (document content and user prompts). One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. pii_detection_llm_output_action: what to do when PII is detected in the output of the LLM. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. prompt_guard_labels_to_flag: list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model. guardrails_labels_to_flag: list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided. guardrails_safe_category: (Optional) name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults. guardrails_entities: (Optional) dictionary of entities and their descriptions for the guardrails model to classify. The first entry is the “safe” class, the rest are “unsafe” classes. custom_pii_entities_to_flag: list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided. custom_pii_entities: (Optional) dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files. guardrails_llm: LLM to use for guardrails and PII detection. Use “auto” for automatic. Use H2OGPTE.get_llms() to see all available options.

Example:

Note: Call client.get_guardrails_settings() to see all options for guardrails_settings.

collection_settings=dict(

max_tokens_per_chunk=320, chunk_overlap_tokens=0, guardrails_settings=dict(

disallowed_regex_patterns=[“secret_disallowed_word”, r”(?!0{3})(?!6{3})[0-8]d{2}-(?!0{2})d{2}-(?!0{4})d{4}”], presidio_labels_to_flag=[“IBAN_CODE”, “US_SSN”], pii_labels_to_flag=[“IBAN”, “SSN”], pii_detection_parse_action=”redact”, pii_detection_llm_input_action=”redact”, pii_detection_llm_output_action=”allow”, prompt_guard_labels_to_flag=[“JAILBREAK”], guardrails_labels_to_flag=[

“Violent Crimes”, “Non-Violent Crimes”, “Intellectual Property”, “Code Interpreter Abuse”,

], guardrails_safe_category=”Safe”, # guardrails_entities is intentionally NOT shown here. # Omit it to inherit the server’s maintained default # category definitions and keep receiving improvements # to them. Supplying it REPLACES the defaults wholesale # (it is not merged), so a dict copied from an example # pins the collection to those exact definitions # forever – including wordings later found too weak to # classify reliably. Pass it only when you own the full # category set deliberately. custom_pii_entities_to_flag=[

“Mother’s Maiden Name”

], custom_pii_entities={

“Mother’s Maiden Name”: “Mother’s maiden name.”

}, guardrails_llm=”meta-llama/Llama-3.3-70B-Instruct”,

),

)

thumbnail:

(Optional) Path to the thumbnail image for the collection. Must include appropriate file extension.

chat_settings:

(Optional) Dictionary with key/value pairs to configure the default values for certain chat specific settings The following keys are supported, see the client.session() documentation for more details. llm: str — Default LLM to use for chat sessions in this collection llm_args: dict — Default LLM arguments (see answer_question method for full list of valid keys) self_reflection_config: dict — Configuration for self-reflection functionality rag_config: dict — Configuration for RAG (Retrieval-Augmented Generation) include_chat_history: bool — Whether to include chat history in context tags: list[str] — Tags to associate with the collection

workspace:

(Optional) The workspace id to be associated with this collection. None to use the default workspace.

vex_encryption:

(Optional) Per-collection vector encryption choice. One of:

“enabled” — store vectors encrypted (the server must have a vector encryption provider configured).
“disabled” — store vectors as plaintext, even if the server has encryption enabled by default.
None — fall back to the server-level default.

Honored at create time only and sticky once any data is written.

Returns:

str: The ID of the newly created collection.

create_custom_agent_key_association(agent_id: str, env_key_name: str, key_id: str) → dict

Creates a custom agent key association (env var -> agent key).

Args:

agent_id: Custom agent UUID env_key_name: Env var name (from envs.json or user-added) key_id: Agent key UUID to associate

Returns:

dict: Created association with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

create_custom_agent_tool_association(agent_id: str, mcp_server_name: str, tool_name: str | None = None) → dict

Creates a custom agent tool association.

Args:: agent_id: Agent UUID mcp_server_name: MCP server name tool_name: Optional tool name to associate (None for unresolved)
Returns:: dict: Created association object

create_event_type(name: str, description: str = '', payload_schema: Dict[str, Any] | None = None) → AiAssistantEventType

Create a custom event type that assistants can subscribe to and emit.

Args:: name: Name of the event type (max 200 chars, must not collide with built-in types). description: Optional description (max 5000 chars). payload_schema: Optional JSON schema for event payloads.
Returns:: AiAssistantEventType: The created event type.

create_extractor(name: str, llm: str, extractor_schema: Dict[str, Any], description: str = '', prompt: str = '', pre_prompt_summary: str = '', keep_intermediate_results: bool = False, system_prompt: str = '', max_num_chunks: int = 100, vision: str = 'auto', vision_llm: str = 'auto', image_batch_image_prompt: str = '', image_batch_final_prompt: str = '', guardrails_settings: Dict | None = None) → Extractor

Creates a new extractor.

Args:: name: Name of the extractor. llm: LLM to use for extraction. extractor_schema: JSON schema defining the extraction structure. If not empty, extractor will return data as JSON object. description: Optional description of the extractor. prompt: Optional prompt text for the extractor. If combined with extractor_schema, prompt can modify the output, but not its format as it’s set to be JSON object. pre_prompt_summary: Optional pre-prompt summary text for the extractor. keep_intermediate_results: Optional flag indicating whether to keep intermediate results during extraction. system_prompt: Optional system prompt text for the extractor. max_num_chunks: Optional maximum number of chunks to process. vision: Optional vision mode setting. vision_llm: Optional vision LLM model identifier. image_batch_image_prompt: Optional image batch processing prompt. image_batch_final_prompt: Optional final prompt for image batch processing. guardrails_settings: Optional guardrails settings configuration as a dictionary.
Returns:: Extractor: Details of the newly created extractor.
Raises:: InvalidArgumentError: If extractor_schema is neither a dict nor None.

create_forum(name: str, description: str = '') → str

Create a new forum.

Args:: name: Name of the forum (must be unique per user). description: Optional description.
Returns:: str: The ID of the created forum.

create_forum_post(forum_id: str, content: str, parent_post_id: str | None = None, assistant_id: str | None = None, file_ids: List[str] | None = None, metadata: Dict[str, Any] | None = None) → str

Create a post on a forum.

Creates the post via the REST API. Sleeping assistants connected to this forum are automatically woken via a push to the event queue.

Args:: forum_id: The forum’s UUID. content: The post content. parent_post_id: Optional parent post ID for threading (reply). assistant_id: Optional assistant ID if posting as an assistant. file_ids: Optional list of file UUIDs to attach. metadata: Optional metadata dict for custom key-value pairs.

Note: the ‘pinned’ key is stripped server-side; use pin_forum_post() instead.
Returns:: str: The ID of the created post.

Create a memory block: reusable content injected into LLM/agent chats.

Args:

name:: Display name of the memory block.
content:: Text content of the memory block.
system_prompt_amendment:: System prompt amendment used in agent mode.
injection_mode:: Where memory content is injected: ‘system_prompt’, ‘user_instruction’, ‘agent_file’, or ‘agent_tool’.
access_mode:: Whether the LLM/agent can ‘read’, ‘write’, or ‘read_write’.
max_content_length:: Maximum number of characters allowed in memory content. 0 means unlimited.

Returns:

MemoryBlock: The newly created memory block.

create_prompt_template(name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Create a new prompt template

Args:

name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the newly created prompt template.

create_runtime_llm(config: Dict[str, Any]) → Dict[str, Any]: Create a runtime (UI/API) LLM from a full config object; the config is stored verbatim and the connection is probed before the model is saved (a failed probe rejects the create). display_name must be the name the model is served under whenever that name is a LiteLLM proxy routing key: the lite_llm_yaml block’s top-level model_name when the config has a block, else base_model when inference_server is "litellm". A different display_name is rejected, because the model is registered with the proxy under that name. A model reached directly at its provider (anthropic, google, a vLLM endpoint) with no block is registered under display_name itself, so its display_name is free. A block mux cannot read (hand-written YAML, or JSON declaring no top-level model_name) is rejected. Returns the new row (admin only).

create_scheduled_task(name: str | None = None, schedule_type: str = '', schedule_expression: str = '', task_type: str = '', task_config: Dict[str, Any] | None = None, description: str = '', max_executions: int | None = None, expires_at: str | None = None, notification_email: str = '', message: str | None = None, system_prompt: str | None = None, collection_id: str | None = None, timezone: str | None = None, llm: str | None = None, llm_args: Dict[str, Any] | None = None) → ScheduledTask

Create a scheduled task.

Args:

name: Unique (per user) task name. If omitted, a collision-safe name: is derived from the message (e.g. ‘summarize-yesterdays-sales-a3f2c1’).

schedule_type: ‘once’, ‘recurring’, or ‘interval’. schedule_expression: ISO-8601 datetime (‘once’), 5-field cron

(‘recurring’, e.g. ‘0 9 * * 1’), or ‘N minutes’/’N hours’ (‘interval’).

task_type: ‘chat_completion’ or ‘agent_task’. task_config: Task configuration. MUST contain a non-empty ‘message’

key (the question/prompt). May include ‘timezone’, ‘collection_id’, and ‘llm_args’.

description: Optional description. max_executions: Optional cap on executions. Not needed for ‘once’

tasks, which already run exactly once.

expires_at: Optional ISO-8601 expiry; must be in the future. notification_email: Optional email for run notifications. The literal

‘current_user’ resolves to the caller’s email server-side.

message: Builder mode: the question/prompt to run. Required if: task_config is omitted.

system_prompt: Builder mode: system prompt applied to every run. collection_id: Builder mode: binds each run’s chat session to this

collection.

timezone: Builder mode: IANA timezone for cron evaluation. llm: Builder mode: model override. llm_args: Builder mode: LLM arguments, e.g. {‘use_agent’: True} for

agent behavior.

Note:

task_config and the builder kwargs are mutually exclusive.

Returns:

ScheduledTask: the created task.

Example:

task = client.create_scheduled_task(
    name="sales-summary-daily",
    schedule_type="recurring",
    schedule_expression="0 9 * * *",
    task_type="chat_completion",
    task_config={
        "message": "Summarize yesterday's sales",
        "system_prompt": "You are a sales analyst.",
        "collection_id": "<collection-uuid>",   # binds the runs to a collection
        "timezone": "America/New_York",         # cron evaluated in this tz
        "llm_args": {"use_agent": True},        # agent behavior
    },
)

create_scheduled_task_for_assistant(assistant_id: str, name: str, message: str, schedule_type: str = 'once', schedule_expression: str = '', run_at: str | None = None, cron_expression: str | None = None, max_executions: int | None = None, notification_email: str = '') → str

Create a scheduled task and connect it to an AI assistant.

This is a convenience method that: 1. Creates a scheduled task via create_scheduled_task RPC. 2. Connects the task to the assistant via connect_assistant_to_schedule.

Args:

assistant_id: The assistant’s UUID. name: Task name. message: The message/prompt for the task. schedule_type: ‘once’, ‘recurring’, or ‘interval’. schedule_expression: Cron expression (for recurring) or interval (for interval).

Ignored if run_at is provided.

run_at: ISO 8601 timestamp for one-shot tasks. Sets schedule_type=’once’. cron_expression: Alias for schedule_expression with schedule_type=’recurring’. max_executions: Maximum number of executions (null = unlimited). notification_email: Email for notifications.

Returns:

str: The created scheduled task UUID.

create_secret(secret: Dict[str, Any]) → str | None

Create a new secret in the SecureStore.

Args:

secret: A dictionary containing the secret data to be stored.: Must include secret_id and secret_value; secret_type is optional.

Returns:

The ID of the newly created secret.

create_slack_integration(name: str, workspace_id: str, bot_token: str, signing_secret: str) → Dict[str, Any]

Create a Slack integration for connecting Slack channels as forums.

Args:: name: Display name for the integration. workspace_id: Slack workspace/team ID (e.g., T01234567). bot_token: Slack bot token (xoxb-…). signing_secret: Slack signing secret for webhook verification.
Returns:: Dict with integration details.

create_tag(tag_name: str) → str

Creates a new tag.

Args:

tag_name:: String representing the tag to create.

Returns:

String: The id of the created tag.

create_user_builtin_mcp(mcp_config: dict, logo_path: str | None = None) → dict

Create a new user-specific builtin MCP configuration.

Publishes an MCP to the shared library so it appears in the builtin MCPs list for all users. Requires the ManageLibrary permission (admins hold it by default).

Args:

mcp_config: Dictionary containing the MCP configuration matching built_in_mcps.json structure.: Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

logo_path: Optional path to a logo image file to upload

Returns:

dict: Dictionary with the created MCP details including id, mcp_id, config, user_id, created_at, updated_at

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission InvalidArgumentError: If the MCP config is invalid or MCP ID already exists

Example:

```python mcp_config = {

“name”: “My Custom MCP”, “description”: “Custom MCP for internal use”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = client.create_user_builtin_mcp(mcp_config, logo_path=”/path/to/logo.png”) ```

create_user_group(name: str, description: str) → UserGroup

create_user_role(name: str, description: str) → UserRole

deactivate_api_key(api_key_id: str) → Result

Allows admins to deactivate an API key.

Note: You cannot undo this action.

Args:

api_key_id:: String: The id of the API key.

Returns:

Result: Status of the deactivate request.

delete_agent_directories(chat_session_id: str) → bool: Delete agent directories for a chat session.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

delete_agent_keys(key_ids: List[str]) → None

delete_agent_server_files(chat_session_id: str) → bool

delete_agent_tool_association(associate_ids: List[str]) → int

delete_agent_tool_preference() → None

delete_ai_assistant(assistant_id: str) → None

Delete an AI assistant.

Uses the REST API endpoint which both deletes from the DB and cleans up Redis wake/dedup keys, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

delete_api_keys(api_key_ids: List[str]) → Result

Allows admins to delete API keys.

Args:

api_key_ids:: List[str]: The API keys to delete.

Returns:

Result: Status of the delete request.

delete_assistant_webhook(assistant_id: str, webhook_id: str) → None

Delete a webhook endpoint.

Args:: assistant_id: ID of the assistant. webhook_id: ID of the webhook to delete.

delete_chat_messages(chat_message_ids: Iterable[str]) → Result

Deletes specific chat messages.

Args:

chat_message_ids:: List of string ids of chat messages to delete from the system.

Returns:

Result: Status of the delete job.

delete_chat_sessions(chat_session_ids: Iterable[str], timeout: float | None = None) → Job

Deletes chat sessions and related messages.

Args:

chat_session_ids:: List of string ids of chat sessions to delete from the system.
timeout:: Timeout in seconds.

Returns:

Result: The delete job.

delete_collections(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections from the environment.

Documents in the collection that are owned by other users will not be deleted.

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

delete_collections_as_admin(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections and their associated data from the environment (needs appropriate permission).

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

delete_custom_agent(agent_ids: List[str]) → int

Deletes custom agents.

Args:: agent_ids: List of agent IDs to delete
Returns:: Count of deleted agents

delete_custom_agent_key_associations(association_ids: List[str]) → int

Deletes custom agent key associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

delete_custom_agent_tool(tool_ids: List[str]) → int

delete_custom_agent_tool_associations(association_ids: List[str]) → int

Deletes custom agent tool associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

delete_document_summaries(summaries_ids: Iterable[str]) → Result

Deletes document summaries.

Args:

summaries_ids:: List of string ids of a document summary to delete from the system.

Returns:

Result: Status of the delete job.

delete_documents(document_ids: Iterable[str], timeout: float | None = None) → Job

Deletes documents from the system.

Args:

document_ids:: List of string ids to delete from the system and all collections.
timeout:: Timeout in seconds.

delete_documents_from_collection(collection_id: str, document_ids: Iterable[str], timeout: float | None = None) → Job

Removes documents from a collection.

See Also: H2OGPTE.delete_documents for completely removing the document from the environment.

Args:

collection_id:: String of the collection to remove documents from.
document_ids:: List of string ids to remove from the collection.
timeout:: Timeout in seconds.

delete_event_type(event_type_id: str) → None

Delete a custom event type. Only the creator can delete.

Cascades to all subscriptions.

Args:: event_type_id: The event type’s UUID.

delete_extractor(extractor_id: str)

Deletes an extractor by its ID.

Args:: extractor_id: The ID of the extractor to delete.

delete_forum(forum_id: str) → None

Delete a forum.

Args:: forum_id: The forum’s UUID.

delete_forum_post(post_id: str) → None

Delete a forum post.

Args:: post_id: The post’s UUID.

delete_library_skill(skill_id: str) → None

Remove a published skill from the library (requires ManageLibrary).

Args:: skill_id: Library id of the published skill.

Example:

client.delete_library_skill("my-skill_library")

delete_memory_block(memory_block_id: str) → None

Delete a memory block.

Args:

memory_block_id:: ID of the memory block to delete.

delete_multiple_agent_directories(chat_session_ids: List[str], dir_types: List[str]) → bool: Delete agent directories for multiple chat sessions.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

delete_prompt_templates(ids: Iterable[str]) → Result

Deletes prompt templates

Args:

ids:: List of string ids of prompte templates to delete from the system.

Returns:

Result: Status of the delete job.

delete_runtime_llm(model_id: str) → None: Hard-delete a runtime LLM by registry UUID (the row is removed, not soft-deleted). Operates only on UI/API runtime rows; a static/env/override or unknown UUID is rejected (admin only).

delete_scheduled_task(task_id: str) → Dict[str, Any] | None: Delete a single scheduled task. Returns {‘status’: ‘deleted’} (or None on a 204).

delete_scheduled_tasks(task_ids: List[str]) → Dict[str, Any] | None: Delete multiple scheduled tasks. Returns {‘status’: ‘deleted’, ‘count’: N} (or None on a 204).

delete_scheduled_tasks_by_admin(task_ids: List[str]) → Dict[str, Any] | None: Delete multiple scheduled tasks for any user (admin only). Returns None on a 204.

delete_secret(secret_id: str) → None

Delete a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to delete.
Returns:: None

delete_shared_chats(shared_chat_ids: List[str]) → None

Delete shared chats by their IDs.

Only shared chats owned by the current user can be deleted.

Args:

shared_chat_ids:: List of shared chat IDs to delete.

delete_showcase_thumbnail(showcase_id: str) → None: Drop the thumbnail object from storage and clear the showcase row.

delete_skills(skill_ids: List[str]) → int

Delete agent skills by their IDs.

Delete is all-or-nothing: if any ID does not belong to the current user, the request fails with an authorization error and no skill is deleted. This avoids the partial-success ambiguity where a caller could not tell which IDs were rejected.

Args:

skill_ids: List of skill UUIDs to delete. Must all belong to the: authenticated user.

Returns:

int: Number of distinct skills deleted. Duplicate IDs are de-duplicated server-side, so this equals the number of unique IDs in skill_ids (which may be less than len(skill_ids) if the list contains repeats).

Raises:

H2OGPTEError: HTTP 403 — one or more IDs do not belong to the user; no skills are deleted.

Example:

count = client.delete_skills(["id1", "id2"])
print(f"Deleted {count} skills")

delete_slack_integration(integration_id: str) → None

Delete a Slack integration and all linked channels.

Args:: integration_id: ID of the Slack integration.

delete_tag(tag_name: str) → str

Deletes a tag from the system.

Only the tag creator can delete it. All document-tag associations are automatically removed.

Args:

tag_name:: String representing the tag to delete.

Returns:

String: The id of the deleted tag.

delete_upload(upload_id: str) → str

Delete a file previously uploaded with the “upload” method.

See Also:

upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection.

Args:

upload_id:: ID of a file to remove

Returns:

upload_id: The upload id of the removed.

Raises:

Exception: The delete upload request was unsuccessful.

delete_user_builtin_mcp(mcp_id: str) → dict

Delete a user builtin MCP by ID.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may remove any entry.

Args:: mcp_id: The ID of the MCP to delete (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with success message
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = client.delete_user_builtin_mcp("my_custom_builtin") print(result["message"]) # "MCP deleted successfully" `

delete_user_groups_by_ids(groups_ids: Iterable[str]) → Result

delete_user_groups_by_names(groups_names: Iterable[str]) → Result

delete_user_roles_by_ids(roles_ids: Iterable[str]) → Result

delete_user_roles_by_names(roles_names: Iterable[str]) → Result

disconnect_assistant_from_collection(assistant_id: str, collection_id: str) → None

Disconnect an AI assistant from a collection.

Args:: assistant_id: The assistant’s UUID. collection_id: The collection’s UUID.

disconnect_assistant_from_forum(assistant_id: str, forum_id: str) → None

Disconnect an AI assistant from a forum.

Args:: assistant_id: The assistant’s UUID. forum_id: The forum’s UUID.

disconnect_assistant_from_schedule(assistant_id: str, scheduled_task_id: str) → None

Disconnect an AI assistant from a scheduled task.

Args:: assistant_id: The assistant’s UUID. scheduled_task_id: The scheduled task’s UUID.

download_agent_tool_file(tool_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the file associated with a custom agent tool.

Args:: tool_id: The ID of the custom agent tool whose file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves the original filename from the tool metadata, falling back to "tool_file".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

download_ai_assistant_file(assistant_id: str, file_id: str, destination_directory: str | Path, destination_file_name: str) → Path

Downloads a file stored by an AI assistant to a local directory.

Args:: assistant_id: The assistant’s UUID. file_id: The file’s UUID. destination_directory: Destination directory to save the file into. destination_file_name: Destination file name.
Returns:: Path: Path of the downloaded file.

download_custom_agent_file(agent_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the zip file associated with a custom agent.

Args:: agent_id: The ID of the custom agent whose zip file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves to "<agent_name>.zip" from the agent metadata, falling back to "agent.zip".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

download_document(destination_directory: str | Path, destination_file_name: str, document_id: str) → Path

Downloads a document to a local system directory.

Args:

destination_directory:: Destination directory to save file into.
destination_file_name:: Destination file name.
document_id:: Document ID.

Returns:

Path: Path of downloaded document

download_library_skill(skill_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Download a library skill’s zip archive (requires ManageSkill).

Args:: skill_id: Library id of the skill. destination_directory: Directory to save the downloaded archive into. destination_file_name: Optional filename. Defaults to <skill_id>.zip.
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: destination_directory does not exist. FileExistsError: A file with the resolved name already exists.

Example:

path = client.download_library_skill("tabh2o-predict", ".")

download_reference_highlighting(message_id: str, destination_directory: str, output_type: str = 'combined', limit: int | None = None) → list

Get PDFs with reference highlighting

Args:

message_id:: ID of the message to get references from
destination_directory:: Destination directory to save files into.
output_type: str one of: "combined" Generates a PDF file for each source document, with all relevant chunks highlighted in each respective file. This option consolidates all highlights for each source document into a single PDF, making it easy to view all highlights related to that document at once. "split" Generates a separate PDF file for each chunk, with only the relevant chunk highlighted in each file. This option is useful for focusing on individual sections without interference from other parts of the text. The output files names will be in the format “{document_id}_{chunk_id}.pdf”
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list[Path]: List of paths of downloaded documents with highlighting

emit_event(assistant_id: str, event_type_name: str, payload: Dict[str, Any] | None = None, target_assistant_ids: List[str] | None = None) → Dict[str, Any]

Emit a custom event that wakes subscribed sleeping assistants.

This goes through the REST API which handles Redis wake event dispatch.

Args:: assistant_id: The emitting assistant’s UUID. event_type_name: Name of the event type to emit. payload: Optional event payload data. target_assistant_ids: Optional list of specific assistant IDs to target.
Returns:: dict: Response with ‘status’ and ‘woken_count’ keys.

encode_for_retrieval(chunks: Iterable[str], embedding_model: str | None = None) → List[List[float]]

Encode texts for semantic searching.

See Also: H2OGPTE.match for getting a list of chunks that semantically match each encoded text.

Args:

chunks:: List of strings of texts to be encoded.
embedding_model:: embedding model to use. call list_embedding_models() to list of options.

Returns:

List of list of floats: Each list in the list is the encoded original text.

export_feedback_csv(destination_directory: str | Path, destination_file_name: str = 'feedback_export.csv', collection_id: str | None = None, interval: str | None = None, no_collection: bool = False, filter: str | None = None, timeout: float | None = None) → Path

Export feedback data as CSV via job and save to disk.

Submits an export job, waits for completion, then downloads the CSV file to the specified directory.

Args:

destination_directory:: Destination directory to save the CSV file into.
destination_file_name:: Destination file name. Defaults to "feedback_export.csv".
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only export feedbacks with no collection.
filter:: Optional text to match against the question or response content.
timeout:: Timeout in seconds for the export job.

Returns:

Path: Path of the downloaded CSV file.

Extract information from one or more contexts using an LLM.

pre_prompt_extract and prompt_extract variables must be used together. If these variables are not set, the inputs texts will be summarized into bullet points.

Format of extract content:
"{pre_prompt_extract}"""
{text_context_list}
"""\n{prompt_extract}"
Examples:
extract = h2ogpte.extract_data(
    text_context_list=chunks,
    pre_prompt_extract="Pay attention and look at all people. Your job is to collect their names.\n",
    prompt_extract="List all people's names as JSON.",
)
Args:

text_context_list:
List of raw text strings to extract data from.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_extract:
Text that is prepended before the list of texts. If not set, the inputs will be summarized.

prompt_extract:
Text that is appended after the list of texts. If not set, the inputs will be summarized.

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: ExtractionAnswer: The list of text responses and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

finish_chat(question_id: str) → Result

Signal the LLM to complete its current thought and finish naturally.

Unlike stop_chat which immediately halts response generation, finish_chat allows the LLM to complete its current thought naturally, providing a more coherent ending.

Args:: question_id: The ID of the chat message/question to finish gracefully.
Returns:: Result: Status of the finish operation.
Raises:: Exception: If the user is not authorized to finish this chat or if the operation fails.

fork_chat_session(chat_session_id: str, message_id: str | None = None) → str

Fork a chat session, creating an independent copy with all messages, references, metadata, and document associations preserved.

When message_id is provided, only messages up to and including that message are copied (branch from a specific point in the conversation).

Args:: chat_session_id: The ID of the chat session to fork. message_id: Optional message ID to branch from.
Returns:: The ID of the newly created (forked) chat session.

generate_assistant_spec(prompt: str, llm: str | None = None, count: int | None = None) → Dict[str, Any]

Generate AI assistant configurations from a natural language prompt.

Uses an LLM with guided JSON mode to produce structured assistant specifications that map to every field in the create-assistant API.

Args:

prompt: Natural language description of the desired assistant(s).: For example: “Create an assistant that monitors sales data and sends daily email reports.”
llm: Optional LLM model override for generation. If not provided,: the system default model is used.
count: Optional number of assistant configurations to generate.: Defaults to the number implied by the prompt.

Returns:

A dictionary with keys:

assistants: list of spec dicts, each with keys name, description, system_prompt, llm, history_management, history_max_chars, history_recent_chars, history_retrieval_chars, notification_email, allowed_tool_actions, allowed_trigger_types, default_wake_period, auto_memory_block, auto_start.
passed: True only if the user’s prompt minimally described what the assistant should do; False if essential info was missing. Callers MUST NOT create any assistants when passed is False.
dialog: confirmation strategy — one of "none" (create directly), "text" (confirm in chat with a yes/no reply), or "ui" (open the full create-assistant form pre-filled from the spec). Always "text" when passed=False.
response: human-language message — a clarification ask if passed=False, otherwise keyed to dialog. May contain the literal tokens {artifact_url} and {artifact_name} which callers substitute post-creation.
llm_used: the model name that was actually used for generation.

The auto_start field is True only when the user explicitly asked the assistant to be started/run/launched.

Example:

result = client.generate_assistant_spec(
    "Create and start a sales monitoring assistant that wakes daily"
)
if not result["passed"]:
    print(result["response"])  # Show clarification ask
    return
for spec in result["assistants"]:
    aid = client.create_ai_assistant(
        name=spec["name"],
        llm=spec.get("llm", ""),
        description=spec.get("description", ""),
        system_prompt=spec.get("system_prompt", ""),
        history_management=spec.get("history_management", "truncation"),
        allowed_tool_actions=spec.get("allowed_tool_actions"),
        allowed_trigger_types=spec.get("allowed_trigger_types"),
    )
    if spec.get("auto_start"):
        client.start_ai_assistant(aid)

generate_scheduled_task_spec(prompt: str, llm: str | None = None, timezone: str | None = None, use_agent: bool | None = None) → Dict[str, Any]

Generate a scheduled task configuration from a natural language prompt.

Uses an LLM with guided JSON mode to produce a structured scheduled task spec that can be passed directly to the create_scheduled_task RPC.

Args:

prompt: Natural language description of the desired scheduled task.: For example: “Summarize the top AI news every weekday at 9am Eastern and send a digest to my email.”
llm: Optional LLM model override for generation. If not provided,: the system default model is used.
timezone: Optional IANA timezone string (e.g. "America/New_York"): used to compute today’s local date for relative expressions like “tomorrow” or “next Monday”. Defaults to UTC if not provided.
use_agent: When true, tells the generator that the user has agent: mode enabled in their chat. The LLM will then prefer task_type="agent_task" unless the prompt clearly describes a plain chat-completion task. Does not force the generated task_type.

Returns:

A dictionary with keys:

task: the generated spec dict with keys name, description, message, schedule_type, schedule_expression, task_type, timezone, max_executions, notification_email.
passed: True only if the user’s prompt minimally described the task to run; False if essential info was missing. Callers MUST NOT create the task when passed is False.
dialog: confirmation strategy — one of "none" (create directly), "text" (confirm in chat with a yes/no reply), or "ui" (open the full schedule-task form pre-filled from the spec). Always "text" when passed=False.
response: human-language message — a clarification ask if passed=False, otherwise keyed to dialog. May contain the literal tokens {artifact_url} and {artifact_name} which callers substitute post-creation.
llm_used: the model name that was actually used for generation.

schedule_type is one of "once", "recurring", "interval". schedule_expression is an ISO datetime for once, 5-field cron for recurring (e.g. "0 9 * * 1"), or "N minutes"/"N hours" for interval. task_type is "agent_task" for multi-step/tool-use work or "chat_completion" for straightforward LLM tasks. timezone is an IANA timezone string (e.g. "America/New_York"). max_executions is an integer or None for unlimited.

Example:

result = client.generate_scheduled_task_spec(
    "Every Monday at 9am Eastern, summarize last week's sales data "
    "from the sales-data collection and email the report to reports@example.com",
    timezone="America/New_York",
)
if not result["passed"]:
    print(result["response"])  # Show clarification ask
    return
spec = result["task"]
task_id = client.create_scheduled_task_for_assistant(
    assistant_id=my_assistant_id,
    name=spec["name"],
    message=spec["message"],
    schedule_type=spec["schedule_type"],
    schedule_expression=spec["schedule_expression"],
    max_executions=spec.get("max_executions"),
    notification_email=spec.get("notification_email", ""),
)

get_agent_key_tool_associations() → List[dict]

get_agent_keys() → List[dict]

get_agent_server_files(chat_session_id: str) → List[dict]

get_agent_suggestions(agent_id: str) → List[dict]

Gets MCP tool suggestions for a custom agent.

Returns suggested MCP tool configurations for a custom agent based on its metadata. Helps users identify and configure required tools.

Args:

agent_id: The unique identifier of the custom agent.

Returns:

List[dict]: A list of suggestion objects, each containing:

mcp_servers: List of MCP server suggestions with tool_name and tool_args

get_agent_tool_preference() → List[str]

get_agent_tools_dict() → dict

get_ai_assistant(assistant_id: str) → AiAssistant

Get details of an AI assistant.

Args:: assistant_id: The assistant’s UUID.
Returns:: AiAssistant: The assistant details.

get_ai_assistant_chat_history(assistant_id: str, offset: int = 0, limit: int = 10000) → str

Get the assistant’s full chat history as formatted text.

Returns the complete conversation history across all wake cycles as a plain-text string with question/reply pairs in chronological order.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset (default 0). limit: Maximum number of chat turns to return (default 10000).
Returns:: str: The full chat history as formatted text.

get_ai_assistant_event_history(assistant_id: str, offset: int = 0, limit: int = 100) → str

Get the assistant’s event history as formatted text.

Returns event/activity log entries with timestamps, event types, trigger details, and wake cycle numbers.

Pagination is newest-first. The underlying RPC orders events created_at DESC and caps each page at 100. Within a single returned page the entries are rendered oldest-first for readability, but walking via offset += limit traverses BACKWARD in time (each successive page is older than the last). To assemble a complete chronological log, fetch all pages and reverse the page order before concatenating.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset (default 0). limit: Maximum events per page; capped at 100 server-side

(default 100). Values above 100 are clamped silently.
Returns:: str: A page of the event history as formatted text.

get_all_agents() → List[dict]

Gets all agents (both built-in and custom) for the current user.

Returns:

List[dict]: A list of all agents with unified structure.: Each agent contains: id, value, label, enabled, type, owner, description, api_keys (grouped by optional/required/custom), and mcp_servers (for custom agents)

get_all_directory_stats(chat_session_id: str, detail_level: int = 0) → dict

get_audio_timestamps(document_id: str) → List[AudioSegment]

Get exact per-segment speaker timestamps for an audio/video transcript document.

Returns the speaker-segment timing captured from diarization at ingest — the authoritative source for time-indexed transcript workflows. Each segment carries its exact start/end times (seconds), speaker label, and text.

Args:

document_id:: String id of the audio/video document.

Returns:

List[AudioSegment]: One entry per speaker segment, in transcript order. Empty for non-transcript documents and documents ingested before timestamps were captured.

get_chat_session_guardrails(chat_session_id: str) → str

Get guardrails settings for a specific chat session.

Args:

chat_session_id:: ID of the chat session

Returns:

str: JSON string containing guardrails settings or “null” if not set

get_chat_session_prompt_template(chat_session_id: str) → PromptTemplate | None

Get the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session

Returns:

str: ID of the prompt template.

get_chat_session_questions(chat_session_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

chat_session_id:: A chat session ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

get_chat_session_workspace(chat_session_id: str) → str

Get the workspace associated with the chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

str: The identifier of the workspace

get_chunks(collection_id: str, chunk_ids: Iterable[int]) → List[Chunk]

Get the text of specific chunks in a collection.

Args:

collection_id:: String id of the collection to search in.
chunk_ids:: List of ints for the chunks to return. Chunks are indexed starting at 1.

Returns:

Chunk: The text of the chunk.

Raises:

Exception: One or more chunks could not be found.

get_collection(collection_id: str) → Collection

Get metadata about a collection.

Args:

collection_id:: String id of the collection to search for.

Returns:

Collection: Metadata about the collection.

Raises:

KeyError: The collection was not found.

get_collection_for_chat_session(chat_session_id: str) → Collection

Get metadata about the collection of a chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

Collection: Metadata about the collection.

get_collection_graph_status(collection_id: str) → GraphStatus

Get the knowledge graph build status for a collection.

Args:

collection_id:: String id of the collection.

Returns:

GraphStatus object with status (‘none’, ‘building’, ‘ready’, ‘failed’) and built_at timestamp if the graph has been built.

get_collection_prompt_template(collection_id: str) → PromptTemplate | None

Get the prompt template for a collection

Args:

collection_id:: ID of the collection

Returns:

str: ID of the prompt template.

get_collection_questions(collection_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

collection_id:: A collection ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

get_connector_status() → ConnectorStatus

Return connector availability and the caller’s existing links.

Returns:: ConnectorStatus: available lists the connector types the server is configured for; connected lists the caller’s current links.

get_custom_agent(agent_id: str) → dict

Gets a single custom agent by ID for the current user.

Args:

agent_id: The unique identifier of the agent to retrieve.

Returns:

dict: A custom agent with details including: id, agent_name, agent_type,: agent_args, owner_email, mcp_servers, api_keys

Raises:

NotFoundError: If the agent is not found or not owned by the user

get_custom_agent_tool(tool_id: str) → dict

Gets a single custom agent tool by ID for the current user.

Args:

tool_id: The unique identifier of the tool to retrieve.

Returns:

dict: A custom agent tool with details including: id, tool_name,: tool_type, tool_args, owner_email, file_name

Raises:

NotFoundError: If the tool is not found or not owned by the user

get_custom_agent_tools() → List[dict]

Gets all custom agent tools for the current user.

Returns:

List[dict]: A list of custom agent tools with their details.: Each tool contains: id, tool_name, tool_type, tool_args, owner_email

get_custom_agents() → List[dict]

Gets all custom agents for the current user.

Returns:

List[dict]: A list of custom agents with their details.: Each agent contains: id, agent_name, agent_type, agent_args, owner_email, resolved_tool_mapping

get_default_collection() → CollectionInfo

Get the default collection, to be used for collection API-keys.

Returns:: CollectionInfo: Default collection info.

get_default_memory_blocks() → dict

Get the current user’s default memory blocks.

Returns a dict with key 'defaults' containing a dict with keys 'llm' and 'agent', each either a memory block dict or None.

The two scopes are independent — LLM default applies to non-agent chats, agent default applies to agent chats. No cascade between them.

Example:

result = client.get_default_memory_blocks()
# result['defaults']['llm']    -> MemoryBlock dict or None
# result['defaults']['agent']  -> MemoryBlock dict or None

get_directory_stats(directory_name: str, chat_session_id: str, detail_level: int = 0) → dict

get_document(document_id: str, include_layout: bool = False) → Document

Fetches information about a specific document.

Args:

document_id:: String id of the document.
include_layout:: Include the layout prediction results.

Returns:

Document: Metadata about the Document.

Raises:

KeyError: The document was not found.

get_document_content(file_name: str, document_id: str) → bytes

Downloads a document and return its content as a byte array.

Args:

file_name:: File name.
document_id:: Document ID.

Returns:

Path: File content

get_effective_guardrails(chat_session_id: str | None = None, collection_id: str | None = None) → str

Get the effective guardrails settings based on the hierarchy.

Args:

chat_session_id:: Optional chat session ID to check for chat-level settings
collection_id:: Optional collection ID to check for collection-level settings

Returns:

str: JSON string containing effective guardrails settings

get_event_type(event_type_id: str) → AiAssistantEventType

Get a custom event type by ID.

Args:: event_type_id: The event type’s UUID.
Returns:: AiAssistantEventType: The event type.

get_extractor(extractor_id: str) → Extractor

Fetches an extractor by its ID.

Args:: extractor_id: The ID of the extractor to retrieve.
Returns:: Extractor: Details of the extractor.
Raises:: UnauthorizedError: If the extractor does not exist or is not visible to the caller. InvalidArgumentError: If extractor_id is not a uuid.

get_forum(forum_id: str) → Forum

Get details of a forum.

Args:: forum_id: The forum’s UUID.
Returns:: Forum: The forum details.

get_forum_post(post_id: str) → ForumPost

Get a single forum post.

Args:: post_id: The post’s UUID.
Returns:: ForumPost: The post details.

get_global_configurations() → List[GlobalConfigItem]

get_global_configurations_by_admin() → List[GlobalConfigItem]

get_guardrails_settings(action: str = 'redact', sensitive: bool = True, non_sensitive: bool = True, all_guardrails: bool = True, guardrails_settings: dict | None = None) → Dict[str, str | List[str]]: Helper to get reasonable (easy to use) defaults for Guardrails/PII settings. To be further customized. :param action: what to do when detecting PII, either “redact” or “fail” (“allow” would keep PII intact). Guardrails models always fail upon detecting safety violations. :param sensitive: whether to include the most sensitive PII entities like SSN, bank account info :param non_sensitive: whether to include all non-sensitive PII entities, such as IP addresses, locations, names, e-mail addresses etc. :param all_guardrails: whether to include all possible entities for prompt guard and guardrails models, or just system defaults :param guardrails_settings: existing guardrails settings (e.g., from collection settings) to obtain guardrails entities, guardrails_entities_to_flag, column redaction custom_pii_entities, column_redaction_pii_to_flag from instead of system defaults :return: dictionary to pass to collection creation or process_document method

get_h2ogpt_system_stats() → dict

get_job(job_id: str) → Job

Fetches information about a specific job.

Args:

job_id:: String id of the job.

Returns:

Job: Metadata about the Job.

get_llm_and_auto_reasoning_llm_names() → Dict[str, str]

Get mapping of llm to its reasoning_model when [“auto”] is passed as visible_reasoning_models

Returns:: dictionary {‘llm1’: ‘llm1_reasoning_llm’, etc.}

get_llm_and_auto_vision_llm_names() → Dict[str, str]

Get mapping of llm to its vision_model when [“auto”] is passed as visible_vision_models

Returns:: dictionary {‘llm1’: ‘llm1_vision_llm’, etc.}

get_llm_name_for_rest(llm: str | int | None)

get_llm_names() → List[str]

Lists names of available LLMs in the environment.

Returns:: list of string: Name of each available model.

get_llm_performance_by_llm(interval: str) → List[LLMPerformance]

get_llm_usage_24h() → float

get_llm_usage_24h_by_llm() → List[LLMUsage]

get_llm_usage_24h_with_limits() → LLMUsageLimit

get_llm_usage_6h() → float

get_llm_usage_6h_by_llm() → List[LLMUsage]

get_llm_usage_by_llm(interval: str) → List[LLMUsage]

get_llm_usage_by_llm_and_user(interval: str) → List[LLMWithUserUsage]

get_llm_usage_by_user(interval: str) → List[UserWithLLMUsage]

get_llm_usage_with_limits(interval: str) → LLMUsageLimit

get_llms() → List[Dict[str, Any]]

Lists metadata information about available LLMs in the environment.

Returns:: list of dict (string, ANY): Name and details about each available model.

get_mcp_sdk_options() → dict

Get the schema of available Claude SDK options for MCP tool runners.

Returns:

dict: Schema with keys:

sdk_options_schema: Full ClaudeSdkAdvancedOptions JSON schema
permission_modes: List of valid permission mode strings
effort_levels: List of valid effort level strings
available_betas: List of available beta feature flags
hook_actions: List of valid hook action strings
hook_events: List of valid hook event strings
limitations: Dict of partially implemented features

Example:

`python schema = client.get_mcp_sdk_options() print("Permission modes:", schema.get("permission_modes")) print("Effort levels:", schema.get("effort_levels")) `

get_memory_block(memory_block_id: str) → MemoryBlock

Fetch a single memory block by id.

Args:

memory_block_id:: ID of the memory block to fetch.

Returns:

MemoryBlock: The requested memory block.

get_meta() → Meta

Returns information about the environment and the user.

Returns:: Meta: Details about the version and license of the environment and the user’s name and email.

get_prompt_template(id: str | None = None) → PromptTemplate

Get a prompt template

Args:

id:: String id of the prompt template to retrieve or None for default

Returns:

PromptTemplate: prompts

Raises:

KeyError: The prompt template was not found.

get_reasoning_capable_llm_names() → List[str]

Lists names of available reasoning-capable (that can natively reason) in the environment.

Returns:: list of string: Name of each available model.

get_role_llm_access(role_id: str) → List[Dict[str, Any]]: Return a role’s LLM access grants as [{“display_name”, “granted”}] (requires manage-roles).

get_scheduled_task(task_id: str) → ScheduledTask: Get a scheduled task by id.

get_scheduled_task_execution_stats(interval: str = '7 days') → ScheduledTaskExecutionStats: Execution stats over a PostgreSQL interval (admin only).

get_scheduled_task_summary() → ScheduledTaskSummary: Aggregate stats for the current user’s scheduled tasks.

get_scheduled_task_summary_by_admin() → ScheduledTaskAdminSummary: System-wide scheduled task summary (admin only).

get_scheduler_stats() → SchedulerStats

Count the number of global, pending jobs on the server.

Returns:: SchedulerStats: The queue length for number of jobs.

get_secret(secret_id: str) → Dict[str, Any] | None

Get a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret object corresponding to the provided ID.

get_secret_value(secret_id: str) → Dict[str, Any] | None

Get the value of a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret value (a dictionary of credentials and configuration) corresponding to the provided ID, or None if it is empty.

get_shared_chat(shared_chat_id: str) → SharedChatDetail

Get a shared chat by its ID.

Args:

shared_chat_id:: ID of the shared chat to retrieve.

Returns:

SharedChatDetail: Shared chat data including messages and metadata.

get_skill_associations() → List[SkillAssociations]

List the current user’s skill env-var→key and target-tool associations.

Returns:: List[SkillAssociations]: One entry per skill that has any association, with its env-var→key bindings and the tools that receive its env vars.

get_skills(offset: int = 0, limit: int = 100, query: str = None) → List[Skill]

List agent skills for the current user.

Args:: offset: How many skills to skip before returning. Default is 0. limit: How many skills to return. Default is 100. query: Optional case-insensitive substring filter on the skill

name. When provided, only skills whose name contains the substring are returned (and the total count reflects the filtered set).
Returns:: List[Skill]: List of skill objects.

Example:

skills = client.get_skills(query="summar")
for s in skills:
    print(s.skill_name, s.description)

get_tag(tag_name: str) → Tag

Returns an existing tag.

Args:

tag_name:: String The name of the tag to retrieve.

Returns:

Tag: The requested tag.

Raises:

KeyError: The tag was not found.

get_user_all_agent_directories(offset: int, limit: int, filter_text: str | None) → List[dict]

get_user_approval_config(user_id: str) → UserApprovalConfig

Get approval governance config for a user. Admin-only.

Args:: user_id: The target user’s UUID.
Returns:: UserApprovalConfig: The approval governance configuration.

get_user_configurations() → List[ConfigItem]

Gets the user configurations for the current user.

Returns:: List[ConfigItem]: List of user configurations.

get_user_configurations_for_user(user_id: str) → List[ConfigItem]

Gets the user configurations for a specific user (to be used by admins only).

Args:

user_id:: The unique identifier of the user.

Returns:

List[ConfigItem]: List of user configurations.

get_vision_capable_llm_names() → List[str]

Lists names of available vision-capable multi-modal LLMs (that can natively handle images as input) in the environment.

Returns:: list of string: Name of each available model.

Import all documents from a collection into an existing collection

Args:

collection_id:: Collection ID to add documents to.
src_collection_id:: Collection ID to import documents from.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_document_status:: Whether to preserve each document’s original ingest mode (agent_only vs standard) when importing. When True, documents with agent_only status remain agent_only in the target collection. When False, all documents use the ingest_mode parameter uniformly.
preserve_metadata:: Whether to preserve the documents’ existing metadata when importing.
migrate_scheduled_connectors:: Whether to move scheduled connectors from source collection to target collection after documents are imported. The source collection will have no scheduled connectors after this operation. Only the owner of both collections can use this flag.
copy_lifecycle_settings:: Whether to copy lifecycle settings (expiry_date, inactivity_interval, size_limit) from the source collection to the target collection.
skip_reparse:: Whether to skip re-parsing documents and only re-embed existing chunks with the target collection’s embedding model. Much faster than full import since it skips file fetch, PDF conversion, OCR, and chunking. Only re-embeds the text chunks. Cannot be combined with copy_document=True.

Import an already stored document to an existing collection

Args:

collection_id:: Collection ID to add documents to.
document_id:: Document ID to add.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_metadata:: Whether to preserve the document’s existing metadata when importing.

ingest_agent_only_to_standard(collection_id: str, document_id: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, timeout: float | None = None)

For files uploaded in “agent_only” ingest mode, convert to PDF and parse

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:: String id of the collection to add the ingested documents into.
document_id:: ID of document to be parsed.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
restricted:: Whether the document should be restricted only to certain users.
permissions:: List of permissions. Each permission is a SharePermission object.
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.

Add files from the Azure Blob Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
container:: Name of the Azure Blob Storage container.
path:: Path or list of paths to files or directories within an Azure Blob Storage container. Examples: file1, dir1/file2, dir3/dir4/
account_name:: Name of a storage account
credentials:: The object with Azure credentials. If the object is not provided, only a public container will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Metadata to be associated with the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Ingests confluence pages into collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
base_url:: Url of confluence instance. Example: https://h2oai.atlassian.net/wiki
page_id:: The page id or ids of pages to be ingested.
credentials:: The object with Confluence credentials.
include_attachments:: A flag indicating whether to also ingest attachments with the page.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the local system into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
root_dir:: String path of where to look for files.
glob:: String of the glob pattern used to match files in the root directory.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the Google Cloud Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of GCS files or directories. Examples: gs://bucket/file, gs://bucket/../dir/
credentials:: The object holding a path to a JSON key of Google Cloud service account. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

ingest_from_plain_text(collection_id: str, plain_text: str, file_name: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None)

Add plain text to a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
plain_text:: String of the plain text to ingest.
file_name:: String of the file name to use for the document.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds

Add files from the AWS S3 storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of S3 files or directories. Examples: s3://bucket/file, s3://bucket/../dir/
region:: The name of the region used for interaction with AWS services.
credentials:: The object with S3 credentials. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

ingest_from_sharepoint_online(collection_id: str, entries: Sequence[SharepointOnlineEntry], credentials: SharepointOnlineAppCredentials | SharepointOnlineUserCredentials, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None)

Add files from SharePoint Online into a collection.

Supports both site/drive/folder/file entries and the drive_by_id entry type for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites — see issue #10695), mixed freely in a single call.

Args:

collection_id: String id of the collection to add the: ingested documents into.
entries: Sequence of SharepointOnlineEntry to ingest.: See the class docstring for entry-type semantics — including "drive_by_id" for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites).
credentials: Either SharepointOnlineAppCredentials: (application permissions) or SharepointOnlineUserCredentials (OAuth delegated).

gen_doc_summaries: Whether to auto-generate document summaries. gen_doc_questions: Whether to auto-generate sample questions. audio_input_language: Spoken-language hint for audio files. ocr_model: OCR model for image text extraction. tesseract_lang: Tesseract language for ocr_model='tesseract'. keep_tables_as_one_chunk: Keep parsed table tokens in a single

chunk.

chunk_by_page: Make each page its own chunk. handwriting_check: Use specialized models when handwriting is

detected.

metadata: Metadata to associate with the document. timeout: Timeout in seconds. ingest_mode: Ingest mode ("standard", "lite",

"agent_only").

ingest_uploads(collection_id: str, upload_ids: Iterable[str], gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None, encrypt_document: bool | None = None, callback: Callable[[Job], None] | None = None) → Job

Add uploaded documents into a specific collection.

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:

String id of the collection to add the ingested documents into.

upload_ids:

List of string ids of each uploaded document to add to the collection.

gen_doc_summaries:

Whether to auto-generate document summaries (uses LLM)

gen_doc_questions:

Whether to auto-generate sample questions for each document (uses LLM)

audio_input_language:

Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.

ocr_model:

Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

restricted:

Whether the document should be restricted only to certain users.

permissions:

List of permissions. Each permission is a SharePermission object.

tesseract_lang:

Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.

keep_tables_as_one_chunk:

When tables are identified by the table parser the table tokens will be kept in a single chunk.

chunk_by_page:

Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.

handwriting_check:

Check pages for handwriting. Will use specialized models if handwriting is found.

metadata:

Dictionary mapping upload_ids to their metadata. Each key must be an upload_id from the upload_ids list, and each value is a dictionary of metadata key-value pairs to associate with that document.

Example:

# Single document
metadata = {upload_id: {"category": "reports", "year": "2024"}}

# Multiple documents
metadata = {
    upload_id_1: {"category": "reports"},
    upload_id_2: {"category": "invoices"}
}

timeout:

Timeout in seconds.

ingest_mode:

Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

encrypt_document:

Whether to encrypt the document files at rest in object storage.

callback:

Function for processing job status info during the upload.

Crawl and ingest a URL into a collection.

The web page or document linked from this URL will be imported.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: String of the url to crawl.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
follow_links:: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document.
max_depth:: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings).
max_documents:: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit).
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

insert_command_synth_pair(chat_session_id: str, user_prompt: str, ai_response: str, command_name: str) → Dict[str, Any]

Persist a synthetic user prompt + AI response pair into a chat session.

Args:

chat_session_id: The ID of the chat session to attach the pair to.: The caller must own the session.

user_prompt: The user-authored prompt that triggered the command. ai_response: The LLM-generated response (e.g. from generate_spec). command_name: Slash-command identifier, e.g. "schedule" or

"create-assistant". Stored in chat_message_meta with message_type="command_synth" so UIs can distinguish these turns from regular LLM turns.

Returns:

A dictionary with keys:

question_id: UUID of the inserted question turn.
reply_id: UUID of the inserted reply turn.

Raises:

ObjectNotFoundError: when the chat session does not exist or is: not owned by the caller (mapped from the RPC’s 30404 errcode).

Example:

ids = client.insert_command_synth_pair(
    chat_session_id=session_id,
    user_prompt="schedule a daily 9pm report",
    ai_response="Scheduled a daily report at 21:00 UTC.",
    command_name="schedule",
)
print(ids["question_id"], ids["reply_id"])

inspect_mcp_tool(tool_id: str | None = None, servers: dict | None = None, file_path: str | None = None, model: str | None = None) → dict

Unified MCP tool inspection.

Supports three modes (provide exactly one): 1. tool_id — inspect an existing local or remote MCP tool by its ID. 2. servers — inspect one or more remote MCP server configs (pre-add). 3. file_path — inspect an uploaded MCP package file (pre-add).

Args:

tool_id: ID of an existing MCP tool to inspect. servers: Dict mapping server names to config dicts for pre-add inspection. file_path: Path to an MCP package file (.py, .zip, .tar.gz) for pre-add inspection. model: Optional LLM model for security inspection.

Returns:

dict: Unified result with keys:

status: ‘success’ or ‘error’
servers: List of per-server inspection result dicts
error: Top-level error message if status is ‘error’

Example:

```python # Inspect an existing tool result = client.inspect_mcp_tool(tool_id=”abc-123”) for srv in result[“servers”]:

print(f”{srv[‘server_name’]}: {srv[‘tool_count’]} tools”)

# Inspect a remote config before adding result = client.inspect_mcp_tool(

servers={“playwright”: {“command”: “npx”, “args”: [“@playwright/mcp@latest”]}}

install_library_skill(skill_id: str, enable_by_default: bool = False) → str

Install a library skill into the caller’s own skills.

Args:: skill_id: Library id of the skill (LibrarySkill.id). enable_by_default: Whether to enable the skill right away.
Returns:: str: The created agent_skill id (use with delete_skills).
Raises:: H2OGPTEError: The install returned no skill id.

Example:

user_skill_id = client.install_library_skill("tabh2o-predict")
client.delete_skills([user_skill_id])  # uninstall

is_collection_permission_granted(collection_id: str, permission: str) → bool

is_permission_granted(permission: str) → bool

launch_custom_agent_tool(tool_id: str) → dict

Launch a custom agent tool via CodeAPI.

Args:: tool_id: The ID of the tool to launch.
Returns:: Dict with codeapi_job_id and codeapi_url.

link_slack_channel(integration_id: str, channel_id: str, channel_name: str = '', forum_name: str = '', sync_direction: str = 'bidirectional', sync_threads: bool = True) → Dict[str, Any]

Link a Slack channel to a forum.

Creates a new forum backed by the Slack channel. Messages in Slack appear as forum posts, and assistant posts appear in Slack.

Args:: integration_id: ID of the Slack integration. channel_id: Slack channel ID (e.g., C01234567). channel_name: Display name of the channel. forum_name: Name for the h2ogpte forum (defaults to channel name). sync_direction: ‘bidirectional’, ‘slack_to_h2ogpte’, or ‘h2ogpte_to_slack’. sync_threads: Whether to sync Slack threads as forum post threads.
Returns:: Dict with channel-forum mapping details.

list_ai_assistant_files(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantFile]

List files stored by an AI assistant.

Args:

assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).

Returns:

List[AiAssistantFile]: List of file metadata objects with: file_id, created_at, and source fields.

list_ai_assistant_permissions(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantPermission]

List sharing permissions for an AI assistant.

Args:

assistant_id: The assistant’s UUID. offset: Number of records to skip (default 0). limit: Maximum number of records to return (default 100, max 100).

Returns:

List[AiAssistantPermission]: List of permission objects with: username, can_read, can_edit fields.

list_ai_assistants(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None) → List[AiAssistant]

List AI assistants accessible to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results. name_filter: Optional name filter (substring match). status_filter: Optional status filter (‘stopped’, ‘running’, ‘sleeping’, ‘error’).
Returns:: List[AiAssistant]: List of assistants.

list_all_api_keys(offset: int, limit: int, key_filter: str = '') → List[APIKey]

Allows admins to list all the API keys that exist.

Args:

offset:: Int: How many keys to skip before returning.
limit:: Int: How many keys to return.
key_filter:: String: Only returns keys for usernames matching this filter.

Returns:

List[APIKey]: List of APIKeys with metadata about each key.

list_all_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[CollectionInfo]

Fetch all users’ collection metadata sorted by last update time.

This is for admin use only and includes private, public, and shared collections in the result.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return collections matching by name, id, or username.

Returns:

list of CollectionInfo: Metadata about each collection.

list_all_jobs() → List[UserJobs]

List all jobs (to be used by admins only).

Returns:: list of UserJobs

list_all_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

list_all_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

list_all_tags(linked_only: bool = False, user_scope: bool = False) → List[Tag]

Lists all existing tags.

Args:

linked_only:: When True, returns only tags associated with at least one document. Default is False, which returns all tags.
user_scope:: When True, scopes results to the current user: tags from the user’s accessible documents, plus tags the user created. Combined with linked_only=True, excludes the user’s unlinked tags. Default is False.

Returns:

List of Tags: List of existing tags.

list_all_user_scheduled_task_executions(offset: int = 0, limit: int = 100, status_filter: str | None = None, name_filter: str | None = None, time_interval: str | None = None, trigger_filter: str | None = None) → ScheduledTaskExecutionList

List executions across all of the current user’s tasks (paginated).

Optionally filter by execution status, task-name substring, a relative time window (e.g. ‘1 day’, ‘7 days’, ‘1 month’), and trigger source (‘scheduled’ or ‘manual’).

list_approvals_routed_to_me(offset: int = 0, limit: int = 50) → List[ApprovalRequestWithAssistant]

List pending approval requests routed to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List of approval requests routed to the current user.

list_archived_chat_sessions(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[ChatSessionInfo]

List archived chat sessions.

Admin-only. Returns chat sessions that have been archived by the expiry sweep or manually by an admin.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
sort_column:: Sort column. One of: name, updated_at, archived_at, username, collection_name.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return sessions matching by name, id, collection name, or username.

Returns:

list of ChatSessionInfo: Metadata about each archived chat session.

list_assistant_collections(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantCollectionLink]

List collections connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantCollectionLink]: List of collection connections.

list_assistant_event_subscriptions(assistant_id: str) → List[AiAssistantEventSubscription]

List an assistant’s event type subscriptions.

Args:: assistant_id: The assistant’s UUID.
Returns:: List[AiAssistantEventSubscription]: List of subscriptions.

list_assistant_events(assistant_id: str, offset: int = 0, limit: int = 50, event_type: str | None = None, since: datetime | None = None) → List[AiAssistantEvent]

List wake/sleep events for an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results. event_type: Optional event type filter (‘wake’, ‘sleep’, ‘error’, ‘start’, ‘stop’, ‘compactify’, ‘memory_index’). since: Optional cutoff timestamp — only return events created

after this time. Defaults to 2 years on the server side.
Returns:: List[AiAssistantEvent]: List of events.

list_assistant_forums(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantForumLink]

List forums connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantForumLink]: List of forum connections.

list_assistant_messages(assistant_id: str, offset: int = 0, limit: int = 50, since: datetime | None = None) → List[AiAssistantMessage]

List direct messages for an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results. since: Optional cutoff timestamp — only return messages created

after this time. Defaults to 2 years on the server side.
Returns:: List[AiAssistantMessage]: List of messages.

list_assistant_schedules(assistant_id: str, offset: int = 0, limit: int = 100) → List[AiAssistantScheduleLink]

List scheduled tasks connected to an AI assistant.

Args:: assistant_id: The assistant’s UUID. offset: Pagination offset. limit: Maximum number of results (max 100).
Returns:: List[AiAssistantScheduleLink]: List of schedule connections.

list_assistant_webhooks(assistant_id: str) → List[Dict[str, Any]]

List webhooks for an AI assistant (tokens are masked).

Args:: assistant_id: ID of the assistant.
Returns:: List of webhook dicts with masked tokens.

list_builtin_mcps() → dict

List built-in MCPs (Model Context Protocol servers) available for use.

Returns a dictionary with two lists: - oauth_apps: List of OAuth-based MCP applications - api_key_apps: List of API key-based MCP applications

Each MCP includes information about whether it’s already added as a tool and whether the related OAuth connector is connected.

Returns:: dict: Dictionary containing ‘oauth_apps’ and ‘api_key_apps’ lists

list_chat_message_meta_part(message_id: str, info_type: str) → ChatMessageMeta

Fetch one chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.
info_type:: Metadata type to fetch. Valid choices are: “self_reflection”, “usage_stats”, “prompt_raw”, “llm_only”, “hyde1”, “py_client_code”

Returns:

ChatMessageMeta: Metadata information about the chat message.

list_chat_message_references(message_id: str, limit: int | None = None) → List[ChatMessageReference]

Fetch metadata for references of a chat message.

References are only available for messages sent from an LLM, an empty list will be returned for messages sent by the user.

Args:

message_id:: String id of the message to get references for.
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list of ChatMessageReference: Metadata including the document name, polygon information, and score.

list_chat_messages(chat_session_id: str, offset: int, limit: int) → List[ChatMessage]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessage: Text and metadata for chat messages.

list_chat_messages_full(chat_session_id: str, offset: int, limit: int) → List[ChatMessageFull]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessageFull: Text and metadata for chat messages.

list_chat_sessions_for_collection(collection_id: str, offset: int, limit: int, username: str | None = None) → List[ChatSessionForCollection]

Fetch chat session metadata for chat sessions in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
username:: Optional username to filter chat sessions by owner.

Returns:

list of ChatSessionForCollection: Metadata about each chat session including the latest message.

list_chat_sessions_for_document(document_id: str, offset: int, limit: int) → List[ChatSessionForDocument]

Fetch chat session metadata for chat session that produced a specific document (typically through agents).

Args:

document_id:: String id of the document to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionForDocument: Metadata about each chat session including the latest message.

list_collection_group_permissions(collection_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given collection.

The returned list of group permissions denoting which groups have access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given collection.

list_collection_permissions(collection_id: str) → List[SharePermission]

Returns a list of access permissions for a given collection.

The returned list of permissions denotes who has access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given collection.

list_collection_public_permissions(collection_id: str) → List[str]

Returns the public permissions for a given collection.

The returned list contains the permission strings that apply to public access of the collection.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of str: Public permissions list for the given collection.

list_collections_for_document(document_id: str, offset: int, limit: int) → List[CollectionInfo]

Fetch metadata about each collection the document is a part of.

At this time, each document will only be available in a single collection.

Args:

document_id:: String id of the document to search for.
offset:: How many collections to skip before returning.
limit:: How many collections to return.

Returns:

list of CollectionInfo: Metadata about each collection.

list_connectors(connector_type: str | None = None) → List[UserConnector]

List the caller’s linked connectors.

Args:

connector_type:: Optional filter, e.g. "github", "confluence", "sharepoint", or "snowflake". When None (default), all of the caller’s connectors are returned.

Returns:

List[UserConnector]: The caller’s connectors.

list_custom_agent_key_associations(agent_id: str | None = None) → List[dict]

Lists custom agent key associations, optionally filtered by agent_id.

Args:

agent_id: Optional agent UUID to filter by

Returns:

List[dict]: Association objects with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

list_custom_agent_tool_associations(agent_id: str | None = None, agent_name: str | None = None) → List[dict]

Lists custom agent tool associations, optionally filtered by agent_id or agent_name.

Args:: agent_id: Optional agent UUID to filter by agent_name: Optional agent name to filter by
Returns:: List[dict]: A list of association objects with agent_id, agent_name, tool_id, tool_name, mcp_server_name, etc.

list_document_chunks(document_id: str, collection_id: str | None = None) → List[SearchResult]

Returns all chunks for a specific document.

Args:

document_id:: ID of the document.
collection_id:: ID of the collection the document belongs to. If not specified, an arbitrary collections containing the document is chosen.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

list_documents_from_tags(collection_id: str, tags: List[str]) → List[Document]

Lists documents that have the specified set of tags within a collection. Args:

collection_id:
String The id of the collection to find documents in.

tags:
List of Strings representing the tags to retrieve documents for.

Returns:: List of Documents: All the documents with the specified tags.

list_documents_in_collection(collection_id: str, offset: int, limit: int, metadata_filter: dict = {}) → List[DocumentInfo]

Fetch document metadata for documents in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.

Returns:

list of DocumentInfo: Metadata about each document.

list_embedding_models() → List[str]

list_event_types(assistant_id: str | None = None, offset: int = 0, limit: int = 100) → List[AiAssistantEventType]

List custom event types.

Args:: assistant_id: Optional assistant ID to include subscription status for. offset: Pagination offset. limit: Maximum number of results.
Returns:: List[AiAssistantEventType]: List of event types.

list_extractor_group_permissions(extractor_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given extractor.

The returned list of group permissions denoting which groups have access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given extractor.

list_extractor_permissions(extractor_id: str) → List[SharePermission]

Returns a list of access permissions for a given extractor.

The returned list of permissions denotes who has access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given extractor.

list_extractor_results(extractor_id: str, job_id: str | None = None, offset: int | None = None, limit: int | None = None) → List[DocumentExtractionResult]

Retrieve extraction results produced by this extractor.

If job_id is specified, returns results for that specific extraction run. If job_id is omitted, returns all results produced by this extractor across all runs.

Args:

extractor_id:: String ID of the extractor.
job_id:: Optional job ID to retrieve results for a specific extraction run. If omitted, returns all results for this extractor.
offset:: Optional number of extraction results to skip before returning. Defaults to 0 if not specified.
limit:: Optional maximum number of extraction results to return. If not specified, returns all results.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ObjectNotFoundError: If the extractor is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor.

list_extractors(offset: int | None = None, limit: int | None = None, name_filter: str | None = None) → List[Extractor]

Lists available extractors.

Args:: offset: Number of extractors to skip. Defaults to server-side default (0). limit: Maximum number of extractors to return. Defaults to server-side default. name_filter: Filter extractors by name.
Returns:: List[Extractor]: A list of available extractors.

list_forum_permissions(forum_id: str, offset: int = 0, limit: int = 100) → List[ForumPermission]

List sharing permissions for a forum.

Args:

forum_id: The forum’s UUID. offset: Number of records to skip (default 0). limit: Maximum number of records to return (default 100, max 100).

Returns:

List[ForumPermission]: List of permission objects with: username, can_read, can_edit fields.

list_forum_posts(forum_id: str, offset: int = 0, limit: int = 50, sort_by: str = 'newest', parent_post_id: str | None = None, since: datetime | None = None) → List[ForumPost]

List posts in a forum.

Args:: forum_id: The forum’s UUID. offset: Pagination offset. limit: Maximum number of results. sort_by: Sort order (‘top’, ‘newest’, or ‘oldest’). parent_post_id: Filter to replies of a specific post. since: Optional cutoff timestamp — only return posts created

after this time.
Returns:: List[ForumPost]: List of posts.

list_forums(offset: int = 0, limit: int = 100, name_filter: str | None = None) → List[Forum]

List forums accessible to the current user.

Args:: offset: Pagination offset. limit: Maximum number of results. name_filter: Optional name filter (substring match).
Returns:: List[Forum]: List of forums.

list_group_permissions(group_id: str) → List[UserPermission]

list_group_permissions_by_name(group_names: List[str]) → List[UserPermission]

list_group_roles(group_id: str) → List[UserRole]

list_jobs() → List[Job]

List the user’s jobs.

Returns:: list of Job:

List job history (admin only), newest first, keyset-paginated.

Args:

cursor_created_at, cursor_id:: The next_cursor_* values from a previous page. Omit for the first page.
limit:: Max rows per page (default 50, hard-capped at 200 server-side).
status:: Optional list of statuses to filter by (queued, running, completed, failed, canceled, timeout, stale, unknown).
kind:: Optional exact job-kind filter.
user_id:: Optional owning-user filter.
collection_id:: Optional filter by the collection the job operated on.
created_after:: Lower bound on created_at. Defaults to the last 7 days when omitted; how far back data exists is bounded by the server’s retention setting (at most 365 days).

Returns:

JobHistoryPage: the page of rows plus the next-page cursor.

list_library_skills() → List[LibrarySkill]

List the skill library catalog (predefined + admin-published).

Visible to all users. Entries carry the caller’s install state (is_skill_added, user_skill_id) and popularity counters (install_count, star_count, is_starred_by_me).

Returns:: List[LibrarySkill]: The library catalog entries.

Example:

skills = client.list_library_skills()
for s in skills:
    print(s.id, s.skill_name, s.star_count)

list_list_chat_message_meta(message_id: str) → List[ChatMessageMeta]

Fetch chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.

Returns:

list of ChatMessageMeta: Metadata about the chat message.

list_llm_registry_admin_models() → List[Dict[str, Any]]: List the admin registry view: effective winners with their shadow candidates and the full raw_config (which MAY include secrets), matching the legacy admin-only runtime_llms setting. Admin only.

list_mcp_tools(config_type: str = 'runner', server_names: List[str] | None = None, mcp_dir: str | None = None, include_remote: bool = True) → dict

List tools from configured MCP servers.

Args:

config_type: Type of config (‘runner’ or ‘creator’). server_names: Optional list of server names to filter. mcp_dir: Optional override directory for MCP configs. include_remote: Whether to include remote MCP servers (default True).

Returns:

dict: Result with keys:

status: ‘success’ or ‘error’
servers: Dict mapping server names to tool lists
total_servers: Number of servers found
total_tools: Total number of tools across all servers
error: Error message if status is ‘error’

Example:

```python result = client.list_mcp_tools(config_type=”runner”) for server, info in result.get(“servers”, {}).items():

print(f”{server}: {info[‘tool_count’]} tools”)

```

list_memory_block_group_permissions(memory_block_id: str) → List[GroupSharePermission]

Returns the group access permissions for a given memory block.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of GroupSharePermission: Which groups have access and at what level.

list_memory_block_permissions(memory_block_id: str) → List[SharePermission]

Returns the user access permissions for a given memory block.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of SharePermission: Who has access and at what level.

list_memory_blocks(offset: int = 0, limit: int = 100, name_filter: str | None = None, updated_after: datetime | None = None) → List[MemoryBlock]

List memory blocks accessible to the current user.

Args:

offset:: How many memory blocks to skip.
limit:: How many memory blocks to return.
name_filter:: Filter by name (case-insensitive substring match).
updated_after:: Only return memory blocks updated at or after this timestamp.

Returns:

list of MemoryBlock: The page of accessible memory blocks.

list_prompt_group_permissions(prompt_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given prompt template.

The returned list of group permissions denoting which groups have access to the prompt template.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given prompt template.

list_prompt_permissions(prompt_id: str) → List[SharePermission]

Returns a list of access permissions for a given prompt template.

The returned list of permissions denotes who has access to the prompt template and their access level.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given prompt template.

list_public_memory_block_permissions(memory_block_id: str) → List[str]

Returns the public permissions for a given memory block.

Returns an empty list both when the memory block is not public and when it is public with read-only access (read is implicit for public blocks); use get_memory_block(...).is_public to distinguish. Matches list_collection_public_permissions.

Args:

memory_block_id:: ID of the memory block to inspect.

Returns:

list of str: Permission strings that apply to public access.

list_question_reply_feedback_data(offset: int, limit: int, collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → List[QuestionReplyData]

Fetch user’s questions and answers that have a feedback.

Questions and answers with metadata and feedback information.

Args:

offset:: How many conversations to skip before returning.
limit:: How many conversations to return.
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only return feedbacks with no collection.

Returns:

list of QuestionReplyData: Metadata about questions and answers.

list_recent_chat_sessions(offset: int, limit: int) → List[ChatSessionInfo]

Fetch user’s chat session metadata sorted by last update time.

Chats across all collections will be accessed.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionInfo: Metadata about each chat session including the latest message.

list_recent_collections(offset: int, limit: int, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_filter(offset: int, limit: int, current_user_only: bool = False, name_filter: str = '') → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with filter options.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
name_filter:: Only returns collections with names matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_metadata_filter(offset: int, limit: int, current_user_only: bool, metadata_filter: dict) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with a filter on metadata.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
metadata_filter:: Only returns collections with metadata matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

list_recent_document_summaries(document_id: str, offset: int, limit: int) → List[ProcessedDocument]

Fetches recent document summaries/extractions/transformations

Args:

document_id:: document ID for which to return summaries
offset:: How many summaries to skip before returning summaries.
limit:: How many summaries to return.

list_recent_documents(offset: int, limit: int, metadata_filter: dict = {}, username: str = '', status: str = '', source: str = '', chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfo]

Fetch user’s document metadata sorted by last update time.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.
username:: Filter documents by the username of the uploader (exact match).
status:: Filter documents by ingestion status (exact match). Values: unknown, scheduled, queued, running, completed, failed, canceled, agent_only.
source:: Filter documents by connector source (case-insensitive match, e.g. SharePoint, url, upload, Agent).
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfo: Metadata about each document.

list_recent_documents_with_summaries(offset: int, limit: int, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

list_recent_documents_with_summaries_sort(offset: int, limit: int, sort_column: str, ascending: bool, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

list_recent_documents_with_summaries_sort_filter_by_type(offset: int, limit: int, sort_column: str = 'updated_at', ascending: bool = False, filter: str = '', interval: str = '36500 days', origin: str = '', use_age: bool = False, document_type: str = 'current_user', chat_session_id: str | None = None, group_by_source_chat: bool = False) → DocumentInfoSummaryListing

Fetch a filtered, sorted page of the user’s documents with summaries.

Unlike list_recent_documents_with_summaries_sort, this performs the text search, origin filtering, and age windowing server-side and returns the total match count alongside the page so the caller can paginate without a separate count query.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return. Pass 0 (or a negative value) for no limit (all matches from offset onward).
sort_column:: Column to sort by. One of name, username, type, size, page_count, connector, uri, original_type, original_mtime, status, updated_at.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Case-insensitive substring matched against the document’s name, type, connector, uri, original_type, id, and username. Empty string matches everything.
interval:: A PostgreSQL interval string (e.g. "7 days") bounding how far back to look. Defaults to "36500 days" (effectively no bound).
origin:: Restrict by document origin. One of "Generated" (agent output), "Indexed" (completed non-agent docs), "Importable" (completed docs), "Canceled", "Agent Only", or "" for no origin filter.
use_age:: When True, the interval window is measured against each document’s original_mtime instead of its updated_at.
document_type:: Visibility scope. "current_user" returns only the calling user’s documents; "public" returns all documents.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; sort_column then orders rows within each group. Documents with no source chat come last.

Returns:

DocumentInfoSummaryListing: The requested page in documents and the total number of matching documents in total. Each document carries chat_session_id and chat_session_name when it was generated by an agent, and chat_session_visible says whether the caller can open that session (a visible session may still have no name).

list_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

list_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

list_role_configurations(role_id: str) → List[ConfigItem]

Lists role configurations for a given role. Args:

role_id:
The role id to get configurations for.

Returns:: List[ConfigItem]: List of role configurations.

list_scheduled_connectors_for_collection(collection_id: str) → List[ScheduledConnectorDetails]

List scheduled connectors associated with a collection.

Args:

collection_id:: String id of the collection to list scheduled connectors for.

Returns:

List[ScheduledConnectorDetails]: Metadata about each scheduled connector.

list_scheduled_task_executions(task_id: str, offset: int = 0, limit: int = 100) → ScheduledTaskExecutionList: List executions for one scheduled task (paginated).

list_scheduled_task_executions_by_admin(task_id: str | None = None, offset: int = 0, limit: int = 100) → ScheduledTaskExecutionList: List executions across all users; optionally filter by task_id (admin only).

list_scheduled_tasks(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None, collection_id: str | None = None, has_collection: bool | None = None) → ScheduledTaskList

List the current user’s scheduled tasks (paginated).

Args:

offset: Pagination offset. limit: Page size. name_filter: Case-insensitive substring match on the task name. status_filter: One of ‘active’, ‘paused’, ‘completed’, ‘expired’. collection_id: Only tasks bound to this collection (UUID).

Mutually exclusive with has_collection.

has_collection: True = only collection-bound tasks; False = only: tasks without a collection. Mutually exclusive with collection_id.

list_scheduled_tasks_by_admin(offset: int = 0, limit: int = 100, name_filter: str | None = None, status_filter: str | None = None, user_filter: str | None = None) → ScheduledTaskList: List all scheduled tasks across users (admin only).

list_secret_ids(connector_type: str | None = None) → List[str]

List available secret IDs from the SecureStore for cloud storage connectors.

Args:

connector_type: Type of connector (‘s3’, ‘gcs’, ‘azure_key’, ‘azure_sas’): If None, returns secrets for all connector types.

Returns:

List of secret IDs available for the specified connector type

list_shared_chats(offset: int = 0, limit: int = 100, filter_text: str = '', filter_type: str = 'all', showcase_filter: str = 'all') → List[SharedChatInfo]

List shared chats created by the current user.

Args:

offset:: Number of items to skip for pagination.
limit:: Maximum number of items to return.
filter_text:: Optional text to filter shared chats by name.
filter_type:: Type filter. One of ‘all’, ‘frozen’, ‘active’, ‘private’, ‘public’.
showcase_filter:: Showcase membership filter. One of ‘all’, ‘featured’, ‘not_featured’.

Returns:

list of SharedChatInfo: List of shared chat metadata.

list_showcase_categories() → List[str]: Distinct, alphabetically-sorted category labels currently in use across showcase tiles. Requires manage_showcase.

list_showcase_chats(offset: int = 0, limit: int | None = None) → List[ShowcaseChat]: List admin-curated showcase shared chats. Public visibility is gated server-side by the showcase_page_mode global setting.

list_slack_integrations() → List[Dict[str, Any]]

List all Slack integrations for the current user.

Returns:: List of Slack integration dicts.

list_system_groups() → List[UserGroup]

list_system_permissions() → List[UserPermission]

list_system_roles() → List[UserRole]

list_upload() → List[str]

List pending file uploads to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:: upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file
Returns:: List[str]: The pending upload ids to be used in ingest jobs.
Raises:: Exception: The upload list request was unsuccessful.

list_user_permissions(user_id: str | None = None) → List[UserPermission]

list_user_role_permissions(roles: List[str]) → List[UserPermission]

list_user_roles(user_id: str | None = None) → List[UserRole]

list_users(offset: int, limit: int) → List[User]

List system users.

Returns a list of all registered users fo the system, a registered user, is a users that has logged in at least once.

Args:

offset:: How many users to skip before returning.
limit:: How many users to return.

Returns:

list of User: Metadata about each user.

make_collection_private(collection_id: str)

Make a collection private

Once a collection is private, other users will no longer be able to access chat history or documents related to the collection.

Args:

collection_id:: ID of the collection to make private.

make_collection_public(collection_id: str, permissions: List[str] | None = None)

Make a collection public

Once a collection is public, it will be accessible to all authenticated users of the system.

Args:

collection_id:: ID of the collection to make public.
permissions:: Optional: Collection specific permissions. If not provided, all permissions will default to true.

make_extractor_private(extractor_id: str)

Make an extractor private

Once a extractor is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

extractore_id:: ID of the extractor to make private.

make_extractor_public(extractor_id: str)

Make an extractor public

Once an extractor is public, it can be seen and used by all users.

Args:

extractor_id:: ID of the extractor to make public.

make_memory_block_private(memory_block_id: str) → None

Make a memory block private.

Once private, other users no longer have public access. Individual and group shares are preserved.

Args:

memory_block_id:: ID of the memory block.

make_memory_block_public(memory_block_id: str, permissions: List[str] | None = None) → None

Make a memory block public.

Once public, all users can read the memory block. permissions controls additional public access (e.g. edit). Omitting it (None) grants edit by default; pass an explicit empty list ([]) for read-only public access.

Args:

memory_block_id:: ID of the memory block.
permissions:: Public permission strings to grant beyond read (e.g. ['h2ogpte/memory_block/edit']). None grants edit by default; [] makes the block public read-only.

make_prompt_template_private(prompt_template_id: str)

Make a prompt template private

Once a prompt template is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

prompt_template_id:: ID of the prompt template to make private.

make_prompt_template_public(prompt_template_id: str)

Make a prompt template public

Once a prompt template is public, it can be seen and used by all users.

Args:

prompt_template_id:: ID of the prompt template to make public.

match_chunks(collection_id: str, vectors: List[List[float]], topics: List[str], offset: int, limit: int, cut_off: float = 0, width: int = 0) → List[SearchResult]

Find chunks related to a message using semantic search.

Chunks are sorted by relevance and similarity score to the message.

See Also: H2OGPTE.encode_for_retrieval to create vectors from messages.

Args:

collection_id:: ID of the collection to search within.
vectors:: A list of vectorized message for running semantic search.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.
cut_off:: Exclude matches with distances higher than this cut off.
width:: How many chunks before and after a match to return - not implemented.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

migrate_chat_sessions_to_collection(source_collection_id: str, target_collection_id: str, timeout: float | None = None) → Job

Migrate chat sessions from one collection to another.

This method creates a job to migrate chat sessions between collections. Only the collection owner can perform this operation.

Args:

source_collection_id:: String ID of the source collection containing the chat sessions.
target_collection_id:: String ID of the target collection to migrate chat sessions to.
timeout:: Timeout in seconds.

migrate_scheduled_connectors_to_collection(collection_id: str, src_collection_id: str, timeout: float | None = None) → Job

Move all scheduled connectors from a source collection to a target collection.

Connectors are moved, meaning the source collection will have no scheduled connectors after this operation. Both collections must be owned by the same user.

Args:

collection_id:: Target collection ID where scheduled connectors will be moved to.
src_collection_id:: Source collection ID to move scheduled connectors from.
timeout:: Timeout in seconds.

pause_chat(question_id: str) → Result

Pause a streaming chat response.

Args:: question_id: The ID of the chat message/question to pause.
Returns:: Result: Status of the pause operation.
Raises:: Exception: If the user is not authorized to pause this chat or if the operation fails.

pin_forum_post(post_id: str, is_pinned: bool) → None

Pin or unpin a forum post (forum owner only).

Args:: post_id: The post’s UUID. is_pinned: True to pin, False to unpin.

Processes a document to either create a global or piecewise summary/extraction/transformation of a document.

Effective prompt created (excluding the system prompt):

"{pre_prompt_summary}
"""
{text from document}
"""
{prompt_summary}"

Args:

document_id:

String id of the document to create a summary from.

system_prompt:

System Prompt

pre_prompt_summary:

Prompt that goes before each large piece of text to summarize

prompt_summary:

Prompt that goes after each large piece of text to summarize

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

llm:

LLM to use

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:: temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation enable_vision (str, default: “auto”) — Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”] visible_vision_models (List[str], default: [“auto”]) — Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic

max_num_chunks:

Max limit of chunks to send to the summarizer

sampling_strategy:

How to sample if the document has more chunks than max_num_chunks. Options are “auto”, “uniform”, “first”, “first+last”, default is “auto” (a hybrid of them all).

pages:

List of specific pages (of the ingested document in PDF form) to use from the document. 1-based indexing.

schema:

Optional JSON schema to use for guided json generation.

keep_intermediate_results:

Whether to keep intermediate results. Default: disabled. If disabled, further LLM calls are applied to the intermediate results until one global summary is obtained: map+reduce (i.e., summary). If enabled, the results’ content will be a list of strings (the results of applying the LLM to different pieces of document context): map (i.e., extract).

guardrails_settings:

Guardrails Settings.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context given to the LLM. Only used if enable_vision is disabled. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

timeout:

Amount of time in seconds to allow the request to run. The default is 86400 seconds.

Returns:

ProcessedDocument: Processed document. The content is either a string (keep_intermediate_results=False) or a list of strings (keep_intermediate_results=True).

Raises:

TimeoutError: The request did not complete in time. SessionError: No summary or extraction created. Document wasn’t part of a collection, or LLM timed out, etc.

publish_library_skill(skill_path: str) → List[PublishedLibrarySkill]

Publish a skill zip to the shared library (requires ManageLibrary).

A multi-skill zip creates one library entry per SKILL.md found. The catalog is global: re-publishing an existing skill name replaces that entry in place regardless of who published it.

Args:: skill_path: Path to a .zip or .skill file (max 100 MiB).
Returns:: List[PublishedLibrarySkill]: The created/updated library rows.
Raises:: FileNotFoundError: skill_path does not exist. ValueError: skill_path has an unsupported extension or is too

large (>100 MiB).

Example:

rows = client.publish_library_skill("my-skill.zip")
for row in rows:
    print(row.skill_id, row.inserted)

regenerate_assistant_webhook_token(assistant_id: str, webhook_id: str) → Dict[str, Any]

Regenerate the token for a webhook (invalidates the old token).

Args:: assistant_id: ID of the assistant. webhook_id: ID of the webhook.
Returns:: Dict with the new ‘token’ (shown only once).

remove_admin_mcp_logo(mcp_id: str) → dict

Remove the logo from an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = client.remove_admin_mcp_logo("my_custom_builtin") print(result["message"]) # "Logo removed successfully" `

remove_chat_session_expiry_date(chat_session_id: str) → str

Remove the expiry date from a chat session.

Args:

chat_session_id:: ID of the chat session to update.

remove_collection_expiry_date(collection_id: str) → str

Remove an expiry date from a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_inactivity_interval(collection_id: str) → str

Remove an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_size_limit(collection_id: str) → str

Remove a size limit for a collection.

Args:

collection_id:: ID of the collection to update.

remove_collection_thumbnail(collection_id: str, timeout: float | None = None)

Remove a thumbnail from a collection.

Args:

collection_id:: Collection you want to remove the thumbnail from.
timeout:: Amount of time in seconds to allow the request to run. The default is 86400 seconds.

remove_custom_agent_tool_from_codeapi(tool_id: str) → bool

Remove a custom agent tool from CodeAPI, terminating its job.

Args:: tool_id: The ID of the tool to remove from CodeAPI.
Returns:: True on success.

remove_permissions_from_role(role_id: str, permission_name: str) → Result

remove_role_from_group(group_id: str, roles: List[str]) → List[UserRole]

remove_role_from_user(user_id: str, roles: List[str]) → List[UserRole]

remove_showcase_chat(showcase_id: str) → None: Remove a showcase tile. The underlying shared chat is untouched.

rename_chat_session(chat_session_id: str, name: str)

Update a chat session name

Args:

chat_session_id:: String id of the document to search for.
name:: The new chat session name.

reorder_showcase_chats(orders: List[ReorderShowcaseChatEntry]) → None: Atomically reassign sort_order for the given showcase entries.

reply_to_forum_post(forum_id: str, post_id: str, content: str, assistant_id: str | None = None, file_ids: List[str] | None = None, metadata: Dict[str, Any] | None = None) → str

Reply to a specific post in a forum.

Creates a reply via the REST API endpoint, which also triggers wake events for sleeping assistants connected to the forum.

Args:: forum_id: The forum’s UUID. post_id: The parent post’s UUID to reply to. content: The reply content. assistant_id: Optional AI assistant UUID to post as. file_ids: Optional list of file UUIDs to attach. metadata: Optional metadata dict.
Returns:: str: The ID of the created reply post.

request_current_user_deletion() → str

Request deletion of the current user account.

This creates a deletion request and returns a delete ID that must be used to confirm the deletion within 5 minutes.

Returns:: str: Delete ID that must be used to confirm deletion.

reset_ai_assistant_tool(assistant_id: str) → None

Reset an AI assistant’s custom tool definition to NULL.

Uses the __CLEAR__ sentinel value recognized by the update_ai_assistant DB function to set custom_tool_definition to NULL.

Args:: assistant_id: The assistant’s UUID.

reset_all_collection_expirations(): Reset any expiry dates and inactivity intervals that have been set for all collections (admin only). This will also reset any archived collections back to active.

reset_and_share_extractor(extractor_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to an extractor (except for the owner) and share it with the provided list of new users.

Args:

extractor_id:: ID of the extractor to un-share.
new_usernames:: The list of usernames belonging to the users this extractor will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_extractor_with_groups(extractor_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to an extractor and share it with the provided list of new group ids.

Args:

extractor_id:: ID of the extractor to un-share.
new_groups:: The list of group ids this extractor will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_prompt_template(prompt_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to a prompt template (except for the owner) and share it with the provided list of new users.

Args:

prompt_id:: ID of the prompt template to un-share.
new_usernames:: The list of usernames belonging to the users this prompt template will be shared with.

ShareResponseStatus: Status of share request.

reset_and_share_prompt_template_with_groups(prompt_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to a prompt template and share it with the provided list of new group ids.

Args:

prompt_id:: ID of the prompt template to un-share.
new_groups:: The list of group ids this prompt template will be shared with.

ShareResponseStatus: Status of share request.

reset_collection_prompt_settings(collection_id: str) → str

Reset the prompt settings for a given collection.

Args:

collection_id:: ID of the collection to update.

Returns:

str: ID of the updated collection.

reset_roles_for_group(group_id: str, roles: List[str]) → List[UserRole]

reset_roles_for_user(user_id: str, roles: List[str]) → List[UserRole]

reset_user_configurations_for_user(key_name: str, user_id: str) → List[ConfigItem]

Reset a user configuration for a specific user (to be used by admins only).

Returns:: List[ConfigItem]: List of user configurations.

resume_chat(question_id: str) → Result

Resume a paused chat response.

Args:: question_id: The ID of the chat message/question to resume.
Returns:: Result: Status of the resume operation.
Raises:: Exception: If the user is not authorized to resume this chat or if the operation fails.

revoke_connector(connector_id: str) → None

Revoke and delete a linked connector.

Revokes the token at the provider (when the provider supports it) and removes the stored connector.

Args:

connector_id:: The id of the connector to revoke (see list_connectors()).

run_extractor(extractor_id: str, collection_id: str | None = None, document_id: str | None = None, files: List[Tuple[str, bytes]] | None = None, timeout: int | None = None) → List[DocumentExtractionResult]

Run an extractor on a collection, single document, or uploaded files and wait for completion.

This method creates a job to execute the specified extractor and blocks until the job finishes. Exactly one of collection_id, document_id, or files must be provided. Mixing files with collection_id or document_id is not allowed.

Args:

extractor_id:: String ID of the extractor to run.
collection_id:: String ID of the collection to run the extractor on.
document_id:: String ID of a single document to run the extractor on.
files:: List of (filename, bytes) tuples to run the extractor on directly, without requiring a collection. The files are uploaded temporarily and deleted after extraction completes.
timeout:: Optional timeout in seconds.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ValueError: If files is provided together with collection_id or document_id. ObjectNotFoundError: If the extractor or collection is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor or collection.

Example:

# Run extraction on a collection and wait for results
results = client.run_extractor(
    extractor_id="extractor-123",
    collection_id="collection-456"
)

# Run extraction on a single document and wait for results
results = client.run_extractor(
    extractor_id="extractor-123",
    document_id="document-789"
)

# Run extraction on uploaded files directly
with open("report.pdf", "rb") as f:
    results = client.run_extractor(
        extractor_id="extractor-123",
        files=[("report.pdf", f.read())]
    )

for result in results:
    print(f"Document: {result.document_name}")
    print(f"Extracted content: {result.content}")

run_selftest(llm: str, mode: str) → dict

Run a self-test for a given LLM Args:

llm:
Name of LLM

mode:
one of [“quick”, “rag”, “full”, “agent”]

Returns:: Dictionary with performance stats. If “error” is filled, the test failed.

search_chunks(collection_id: str, query: str, topics: List[str], offset: int, limit: int) → List[SearchResult]

Find chunks related to a message using lexical search.

Chunks are sorted by relevance and similarity score to the message.

Args:

collection_id:: ID of the collection to search within.
query:: Question or imperative from the end user to search a collection for.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

search_forum_posts(assistant_id: str, query: str, forum_id: str | None = None, author_username: str | None = None, author_assistant_name: str | None = None, since: datetime | None = None, min_vote_score: int | None = None, sort_by: str = 'relevance', limit: int = 20, offset: int = 0) → Dict[str, Any]

Search forum posts by keyword across all accessible forums.

Uses PostgreSQL full-text search. Supports natural language queries, phrases, boolean operators (& |), negation (!), and prefix matching (*).

Args:: assistant_id: The assistant’s UUID (used for access scoping). query: Search keywords or full-text search expression. forum_id: Optional forum UUID to restrict search to. author_username: Optional filter by human author username. author_assistant_name: Optional filter by assistant author name. since: Optional cutoff — only posts created after this time. min_vote_score: Optional minimum vote score filter. sort_by: Sort order: ‘relevance’ (default), ‘newest’, ‘oldest’, ‘top’. limit: Max results (1–100, default 20). offset: Pagination offset.
Returns:: Dict with ‘posts’ (list of matching posts with highlighted snippets), ‘total’ (total matches), ‘query’, ‘offset’, ‘limit’.

send_hitl_message(question_id: str, message: str) → Result

Send a course correction message to a running agent.

Sends a human-in-the-loop message to a running agent. The agent will incorporate this guidance before its next LLM call.

Args:: question_id: The ID of the active streaming chat question. message: The course correction message to send to the agent.
Returns:: Result: Status of the send operation.
Raises:: Exception: If the user is not authorized or if the operation fails.

send_inter_assistant_message(assistant_id: str, recipient_assistant_id: str, content: str, metadata: Dict[str, Any] | None = None) → str

Send a direct message from one assistant to another.

Triggers a wake event on the recipient assistant. This goes through the REST API which handles Redis wake event dispatch.

Args:: assistant_id: The sender assistant’s UUID. recipient_assistant_id: The recipient assistant’s UUID. content: Message content (max 100000 chars). metadata: Optional metadata dict.
Returns:: str: The created message UUID.

send_message_to_assistant(assistant_id: str, content: str) → str

Send a direct message to an AI assistant.

Creates the message in the database and automatically pushes a wake event if the assistant is in sleeping state. There is no need to call wake_ai_assistant() separately.

Args:: assistant_id: The assistant’s UUID. content: The message text.
Returns:: str: The ID of the created message.

set_agent_skill_preference(skill_ids: List[str], enabled: bool) → None

Enable or disable the given agent skills for the user.

Sets the enabled flag for the listed skill IDs. Only the named skills are changed; any skill not in skill_ids is left untouched.

Args:: skill_ids: IDs of the skills to update. enabled: True to enable the listed skills, False to disable them.

Example:

skills = client.get_skills()
client.set_agent_skill_preference([skills[0].id], True)

set_api_key_expiration(api_key_id: str, expires_in: str | None = None) → Result

Allows admins to set an expiration on an API key.

Args:

api_key_id:: String: The id of the API key.
expires_in:: (Optional) String: The expiration for the API key as an interval or None (to remove an expiration that was previously set). Ex. “30 days” or “30 minutes”

Returns:

Result: Status of the expiration request.

set_api_key_inactivity_interval(api_key_id: str, inactivity_interval: int | None = None) → Result

Allows admins to set an inactivity interval for an API key. This is how many days a key can be unused for (no activity) before it becomes invalid.

Args:

api_key_id:: String: The id of the API key.
inactivity_interval:: (Optional) int: The inactivity interval for the API key as an integer of days or None (to remove an inactivity interval that was previously set).

Returns:

Result: Status of the request.

set_chat_message_votes(chat_message_id: str, votes: int) → Result

Change the vote value of a chat message.

Set the exact value of a vote for a chat message. Any message type can be updated, but only LLM response votes will be visible in the UI. The expectation is 0: unvoted, -1: dislike, 1 like. Values outside of this will not be viewable in the UI.

Args:

chat_message_id:: ID of a chat message, any message can be used but only LLM responses will be visible in the UI.
votes:: Integer value for the message. Only -1 and 1 will be visible in the UI as dislike and like respectively.

Returns:

Result: The status of the update.

Raises:

Exception: The upload request was unsuccessful.

set_chat_session_collection(chat_session_id: str, collection_id: str | None) → str

Set the collection for a chat_session

Args:

chat_session_id:: ID of the chat session
collection_id:: ID of the collection, or None to chat with the LLM only.

Returns:

str: ID of the updated chat session

set_chat_session_expiry_date(chat_session_id: str, expiry_date: str, timezone: str | None = None) → str

Set an expiry date for a chat session.

When the expiry date is reached, the chat session will be automatically archived and eventually deleted after the configured grace period.

Args:

chat_session_id:: ID of the chat session to update.
expiry_date:: The expiry date as a string in ‘YYYY-MM-DD’ format.
timezone:: Optional timezone to associate with expiry date (with IANA timezone support).

set_chat_session_keep_forever(chat_session_id: str, keep_forever: bool) → str

Set whether a chat session should be preserved from auto-archival.

When keep_forever is True, the chat session will not be subject to inactivity-based or date-based expiry, and its expiry date is cleared permanently. When set to False, the global inactivity interval is re-applied and the inactivity timer is restarted, so the chat gets a full retention period before it is considered for archival again.

Args:

chat_session_id:: ID of the chat session to update.
keep_forever:: Whether to preserve the chat session from expiry.

set_chat_session_prompt_template(chat_session_id: str, prompt_template_id: str | None) → str

Set the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.

Returns:

str: ID of the updated chat session

set_collection_exempt_from_chat_expiry(collection_id: str, exempt: bool) → str

Set whether a collection’s chat sessions are exempt from expiry.

When exempt is True, all chat sessions in the collection will be excluded from automatic expiry regardless of their individual settings.

Args:

collection_id:: ID of the collection to update.
exempt:: Whether to exempt chat sessions from expiry.

set_collection_expiry_date(collection_id: str, expiry_date: str | date | datetime, timezone: str | None = None) → str

Set an expiry date for a collection.

Args:

collection_id:: ID of the collection to update.
expiry_date:: Expiry as a "YYYY-MM-DD" date string, a full ISO 8601 datetime string with optional timezone offset (e.g. "2026-09-30T17:00:00-05:00"), or a datetime.date / datetime.datetime object. A date-only value resolves to midnight (00:00:00) of that day in timezone.
timezone:: Optional timezone to associate with a date-only / offset-less expiry (with IANA timezone support). Ignored for parsing when expiry_date already carries an offset, but always stored as the collection’s expiry_timezone so the expiry is displayed in this zone. Defaults to the local machine’s zone.

set_collection_inactivity_interval(collection_id: str, inactivity_interval: int) → str

Set an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.
inactivity_interval:: The inactivity interval as an integer number of days.

set_collection_prompt_template(collection_id: str, prompt_template_id: str | None, strict_check: bool = False) → str

Set the prompt template for a collection

Args:

collection_id:: ID of the collection to update.
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.
strict_check:: whether to check that the collection’s embedding model and the prompt template are optimally compatible

Returns:

str: ID of the updated collection.

set_collection_size_limit(collection_id: str, limit: int | str) → str

Set a maximum limit on the total size of documents (sum) added to a collection. The limit is measured in bytes.

Args:

collection_id:: ID of the collection to update.
limit:: The bytes limit, possible values follow the format: 12345, “1GB”, or “1GiB”.

set_collection_thumbnail(collection_id: str, file_path: Path, timeout: float | None = None)

Upload an image file to be set as a collection’s thumbnail.

The image file will not be considered as a collection document. Acceptable image file types include: .png, .jpg, .jpeg, .svg

Args:

collection_id:: Collection you want to add the thumbnail to.
file_path:: Path to the image file. Must include appropriate file extension.
timeout:: Amount of time in seconds to allow the request to run.

Raises:

ValueError: The file is invalid. Exception: The upload request was unsuccessful.

set_default_memory_block(scope: str, memory_block_id: str | None = None) → dict

Set or clear a default memory block for a given scope.

Args:: scope: Which scope to set. Must be 'llm' or 'agent'. memory_block_id: UUID of the memory block to set as default,

or None to clear the default for this scope.
Returns:: A dict with 'scope' and 'memory_block' (the set block or None if cleared).
Raises:: ValueError: If scope is not ‘llm’ or ‘agent’.

Example:

# Set default for LLM (non-agent) chats
client.set_default_memory_block('llm', '<block-id>')

# Set default for agent chats
client.set_default_memory_block('agent', '<block-id>')

# Clear the agent default
client.set_default_memory_block('agent', None)

set_default_prompt_template_visibility(prompt_id: str, is_visible: bool)

Updates a flag specifying whether a default prompt template is visible or hidden to users.

Once you hide a default prompt template, users will no longer be able to use this prompt template. This will also affect collections and chats that have this as a default prompt template. Once you show a default prompt template, all users will be able to see and use this prompt template.

Args:

prompt_id:: ID of the default prompt template you would like to change the visibility of.
is_visible:: Whether the default prompt template should be visible.

set_global_configuration(key_name: str, string_value: str, can_overwrite: bool, is_public: bool, value_type: str = None) → List[GlobalConfigItem]

Set a global configuration.

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the global config.
can_overwrite:: Whether user settings can override this global setting.
is_public:: Whether users can see the value for this global setting.
value_type:: The type of the value to be set for the global config.

Returns:

List[GlobalConfigItem]: List of global configurations.

set_role_configuration(key_name: str, role_id: str, string_value: str, value_type: str = None) → List[ConfigItem]

Set a role configuration, overrides the global configuration. Args:

role_id:
The role id you want to apply the config for.

key_name:
The name of the global config key.

string_value:
The value to be set for the config.

value_type:
The type of the value to be set for the config.

Returns:: List[ConfigItem]: List of role configurations.

set_role_llm_access(role_id: str, names: List[str]) → None: Replace a role’s LLM access grants with names; protected roles rejected (manage-roles).

set_role_priority(role_id: str, priority: int) → UserRole

Sets the priority for a role. Args:

role_id:
String: The id of the role to set the priority for.

priority:
Int: The priority value to set for the role. ex: 100, 200, 300…etc. The lower the number, the higher the priority.

Returns:: UserRole: The updated user role with the new priority.

set_skill_associations(skill_id: str, keys: List[dict] | None = None, tools: List[str] | None = None) → dict

Set a skill’s env-var→key associations and which tools receive them.

Args:

skill_id: The skill to configure (must belong to the caller). keys: List of {"name": <env var>, "key_id": <agent key id or None>}.

Only env vars declared in the skill’s envs.json are accepted; key_id None/”” clears the binding.

tools: Tools that receive the skill’s env vars when it is selected.: Empty/omitted defaults to ["python", "shell"].

Returns:

dict: {"count": <associations upserted>, "tools": [<resulting tools>]}.

Example:

skills = client.get_skills()
keys = client.get_agent_keys()
client.set_skill_associations(
    skills[0].id,
    keys=[{"name": "OPENAI_API_KEY", "key_id": keys[0].id}],
    tools=["python", "shell"],
)

set_user_approval_config(user_id: str, approval_user_id: str | None = None, allow_custom_approval_text: bool = False, allow_policy_override: bool = True, allow_approval_user_change: bool = False) → Dict[str, Any]

Set approval governance config for a user. Admin-only.

Args:: user_id: The target user’s UUID. approval_user_id: UUID of the designated approval user (None = clear). allow_custom_approval_text: Allow user to set custom approval text. allow_policy_override: Allow user to change tool action policies. allow_approval_user_change: Allow user to change their approval user.
Returns:: Dict with ‘id’ and ‘status’.

set_user_configuration_for_user(key_name: str, string_value: str, user_id: str, value_type: str = None) → List[ConfigItem]

Set a user configuration for a specific user (overrides the global configuration and to be used by admins only).

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the config.
user_id:: The user id you want to apply the config for.
value_type:: The type of the value to be set for the config.

Returns:

List[ConfigItem]: List of user configurations.

share_ai_assistant(assistant_id: str, username: str, access_mode: str = 'read') → None

Share an AI assistant with another user.

Args:: assistant_id: The assistant’s UUID. username: The username to share with. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

share_chat_session(chat_session_id: str, is_private: bool = False, is_frozen: bool = True, includes_artifacts: bool = False) → ChatShareUrl

Share a chat session and get a publicly accessible URL.

Args:

chat_session_id:: String id of the chat session to share.
is_private:: If True, only authenticated users can view the shared chat. If False (default), the shared chat is publicly accessible.
is_frozen:: If True (default), a snapshot of the chat is created at share time. If False, the shared chat shows live updates from the source chat.
includes_artifacts:: If True, file artifacts referenced in messages are included. If False (default), artifacts are excluded.

Returns:

ChatShareUrl: Object containing the shareable URL and relative path.

share_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Share a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_collection_with_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a collection to a group.

The permission attribute defines the level of access, and which group can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level and group.

Returns:

ShareResponseStatus: Status of share request.

share_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Share an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_extractor_with_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share an extractor to a group.

The permission attribute defines which group can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the group for sharing with.

Returns:

ShareResponseStatus: Status of share request.

share_forum(forum_id: str, username: str, access_mode: str = 'read') → None

Share a forum with another user.

Args:: forum_id: The forum’s UUID. username: The username to share with. access_mode: Access level - ‘read’, ‘write’, or ‘read_write’.

share_memory_block(memory_block_id: str, permission: SharePermission) → ShareResponseStatus

Share a memory block to a user.

Args:

memory_block_id:: ID of the memory block to share.
permission:: Defines the user to share with and the permission level. permission.permissions may be None or empty for read-only access.

Returns:

ShareResponseStatus: Status of the share request.

share_memory_block_with_group(memory_block_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a memory block to a group.

Args:

memory_block_id:: ID of the memory block to share.
permission:: Defines the group to share with and the permission level. permission.permissions may be None or empty for read-only access.

Returns:

ShareResponseStatus: Status of the share request.

share_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Share a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

share_prompt_with_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a prompt to a group.

Args:

prompt_id:: ID of the prompt to share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

star_library_item(item_kind: Literal['skill', 'mcp'], item_id: str) → LibraryStarStatus

Star a library item. Requires the caller to have it installed.

Args:: item_kind: "skill" or "mcp". item_id: Library id of the item.
Returns:: LibraryStarStatus: The new aggregate star state.

Example:

status = client.star_library_item("skill", "tabh2o-predict")
print(status.star_count, status.is_starred_by_me)

start_ai_assistant(assistant_id: str) → None

Start an AI assistant (sets status to ‘sleeping’ and records a start event).

Uses the REST API endpoint which both updates the DB status and records the start event, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

start_connector_link(connector_type: str) → str

Begin the OAuth flow for a connector and return the authorization URL.

The caller must open the returned URL in a browser (logged into the h2oGPTe server as the same user) and approve access at the provider. The link is complete once the provider redirects back to the server’s callback; observe it via list_connectors().

Args:

connector_type:: One of "github", "confluence", "sharepoint", or "snowflake". Must be a type the server is configured for (see get_connector_status()).

Returns:

str: The provider authorization URL to open in a browser.

stop_ai_assistant(assistant_id: str) → None

Stop an AI assistant (sets status to ‘stopped’ and records a stop event).

Uses the REST API endpoint which both updates the DB status and records the stop event, unlike calling the RPC directly.

Args:: assistant_id: The assistant’s UUID.

stop_chat(question_id: str) → Result

Immediately stop/cancel a streaming chat response.

This will immediately halt response generation, which may result in an incomplete sentence or thought. For a more graceful termination, use finish_chat instead.

Args:: question_id: The ID of the chat message/question to stop immediately.
Returns:: Result: Status of the cancel operation.
Raises:: Exception: If the user is not authorized to cancel this chat or if the operation fails.

subscribe_assistant_to_event_type(assistant_id: str, event_type_id: str) → AiAssistantEventSubscription

Subscribe an assistant to a custom event type.

Idempotent — re-subscribing returns the existing subscription.

Args:: assistant_id: The assistant’s UUID. event_type_id: The event type’s UUID.
Returns:: AiAssistantEventSubscription: The subscription record.

Summarize one or more contexts using an LLM.

Effective prompt created (excluding the system prompt):
"{pre_prompt_summary}
"""
{text_context_list}
"""
{prompt_summary}"
Args:

text_context_list:
List of raw text strings to be summarized.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default or None for h2oGPTe defaults. Defaults to ‘’ for no system prompt.

pre_prompt_summary:
Text that is prepended before the list of texts. The default can be customized per environment, but the standard default is "In order to write a concise single-paragraph or bulleted list summary, pay attention to the following text:\n"

prompt_summary:
Text that is appended after the list of texts. The default can be customized per environment, but the standard default is "Using only the text above, write a condensed and concise summary of key results (preferably as bullet points):\n"

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

summarize_document(*args, **kwargs) → DocumentSummary

tag_document(document_id: str, tag_name: str) → str

Adds a tag to a document.

Args:

document_id:: String id of the document to attach the tag to.
tag_name:: String representing the tag to attach.

Returns:

String: The id of the newly created tag.

test_runtime_llm(config: Dict[str, Any]) → Dict[str, Any]: Probe a runtime LLM config without persisting it (a non-caching, non-persisting metadata round-trip); returns {“ok”, “meta”|”error”}. Applies the same display_name rule as create_runtime_llm(), so a config the create path would refuse never tests green (admin only).

trigger_scheduled_task(task_id: str) → ScheduledTaskTriggerResult: Manually trigger a scheduled task immediately (a test run).

unarchive_chat_session(chat_session_id: str) → str

Restore an archived chat session to an active state.

Admin-only. Resets the session status from ‘archived’ to ‘active’, clears archived_at, and restores the inactivity interval from the current global configuration.

Args:

chat_session_id:: ID of the chat session to restore.

unarchive_collection(collection_id: str) → str

Restore an archived collection to an active status.

Args:

collection_id:: ID of the collection to restore.

unshare_ai_assistant(assistant_id: str, username: str) → None

Remove sharing for an AI assistant.

Args:: assistant_id: The assistant’s UUID. username: The username to unshare from.

unshare_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

unshare_collection_for_all(collection_id: str) → ShareResponseStatus

Remove sharing of a collection to all other users but the original owner.

Args:

collection_id:: ID of the collection to un-share.

ShareResponseStatus: Status of share request.

unshare_collection_from_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of a collection from a group.

The permission attribute defines which group to remove access from, the collection_id attribute denotes the collection to be unshared. In case of un-sharing, the GroupSharePermission’s group_id is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the group for which collection access is revoked.

Returns:

ShareResponseStatus: Status of share request.

unshare_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the user for which extractor access is revoked.

ShareResponseStatus: Status of share request.

unshare_extractor_for_all(extractor_id: str) → ShareResponseStatus

Remove sharing of an extractor to all other users but the original owner.

Args:

extractor_id:: ID of the extractor to un-share.

ShareResponseStatus: Status of share request.

unshare_extractor_from_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of an extractor from a group.

The permission attribute defines which group to remove access from, the extractor_id attribute denotes the extractor to be unshared.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the group for which extractor access is revoked.

Returns:

ShareResponseStatus: Status of share request.

unshare_forum(forum_id: str, username: str) → None

Remove sharing for a forum.

Args:: forum_id: The forum’s UUID. username: The username to unshare from.

unshare_memory_block(memory_block_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a memory block from a user.

Args:

memory_block_id:: ID of the memory block.
permission:: Defines the user whose access is revoked (permission.username).

Returns:

ShareResponseStatus: Status of the unshare request.

unshare_memory_block_from_group(memory_block_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of a memory block from a group.

Args:

memory_block_id:: ID of the memory block.
permission:: Defines the group whose access is revoked (permission.group_id).

Returns:

ShareResponseStatus: Status of the unshare request.

unshare_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

unshare_prompt_for_all(prompt_id: str) → ShareResponseStatus

Remove sharing of a prompt template to all other users but the original owner (owner action only).

Args:

prompt_id:: ID of the prompt template to un-share.

ShareResponseStatus: Status of share request.

unshare_prompt_from_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Unshare a prompt from a group.

Args:

prompt_id:: ID of the prompt to un-share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

unstar_library_item(item_kind: Literal['skill', 'mcp'], item_id: str) → LibraryStarStatus

Remove the caller’s star on a library item. Idempotent.

Args:: item_kind: "skill" or "mcp". item_id: Library id of the item.
Returns:: LibraryStarStatus: The new aggregate star state.

Example:

status = client.unstar_library_item("skill", "tabh2o-predict")
print(status.star_count)

unsubscribe_assistant_from_event_type(assistant_id: str, event_type_id: str) → None

Unsubscribe an assistant from a custom event type.

Args:: assistant_id: The assistant’s UUID. event_type_id: The event type’s UUID.

untag_document(document_id: str, tag_name: str) → str

Removes an existing tag from a document.

Args:

document_id:: String id of the document to remove the tag from.
tag_name:: String representing the tag to remove.

Returns:

String: The id of the removed tag.

update_admin_mcp_logo(mcp_id: str, logo_path: str) → dict

Update the logo for an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) logo_path: Path to the logo image file to upload
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the logo file is invalid or not found
Example:: `python result = client.update_admin_mcp_logo("my_custom_builtin", "/path/to/logo.png") print(result["logo"]) # "/file?id=...&name=logo.png" `

update_agent_key(key_id: str, name: str | None = None, value: str | None = None, key_type: str | None = None, description: str | None = None) → dict | None

update_agent_tool_preference(reference_value: List[str]) → None

Update an AI assistant’s configuration.

Args:: assistant_id: The assistant’s UUID. name: New name (optional). description: New description (optional). system_prompt: New system prompt (optional). llm: New model identifier (optional). llm_args: New LLM args dict (optional). custom_tool_definition: New custom tool Python code (optional). mcp_servers: New MCP server config list (optional). credential_ids: New credential UUID list (optional). memory_block_id: New memory block UUID (optional). notification_email: New notification email (optional). notification_smtp: New SMTP config dict for outbound notifications (optional). history_management: New history mode (optional). history_max_chars: New char threshold (optional). history_recent_chars: Characters of recent history to always include (optional). history_retrieval_chars: Characters of retrieved history to include (optional). allowed_tool_actions: List of allowed tool action names (optional). allowed_trigger_types: List of allowed trigger types (optional). tool_action_policies: Dict mapping tool action names to policies (optional). approval_user_id: UUID of the designated approval user (optional). custom_approval_text: Custom data protection instructions (optional). policies_locked: Lock tool action policies (admin-only) (optional). custom_approval_locked: Lock custom approval text (admin-only) (optional).

update_ai_assistant_tool(assistant_id: str, custom_tool_definition: str) → None

Update the custom tool definition for an AI assistant.

Args:: assistant_id: The assistant’s UUID. custom_tool_definition: The Python code for the custom tool.

update_collection(collection_id: str, name: str, description: str) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:: ID of the collection to update.
name:: New name of the collection, this is required.
description:: New description of the collection, this is required.

Returns:

str: ID of the updated collection.

update_collection_metadata(collection_id: str, collection_metadata: dict) → str

Set the new collection metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_metadata:: Dictionary containing the new collection metadata.

Returns:

str: ID of the updated collection.

update_collection_rag_type(collection_id: str, name: str, description: str, rag_type) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:

ID of the collection to update.

name:

New name of the collection, this is required.

description:

New description of the collection, this is required.

rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.: Requires 1 Agent call.
"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.: Requires 1 Agent call with RAG tool execution.
"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code: execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.
"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts: to answer the query. Requires 1 LLM or Agent call.
"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).: Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.
"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant: contexts from a collection for generating a response. Requires 3 LLM calls.
"rag+" Summary RAG - Like RAG, but uses more context and recursive: summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.
"all_data" All Data RAG - Like Summary RAG, but includes all document: chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

Returns:

str: ID of the updated collection.

update_collection_settings(collection_id: str, collection_settings: dict) → str

Set the new collection settings, must be complete. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_settings:: Dictionary containing the new collection settings.

Returns:

str: ID of the updated collection.

update_collection_workspace(collection_id: str, workspace: str) → str

Update the workspace associated with a collection.

Args:

collection_id:: ID of the collection to update.
workspace:: The workspace associated with the collection.

update_custom_agent(agent_id: str, agent_args: dict, mcp_servers_mapping: dict | None = None) → str

Updates a custom agent’s arguments.

Args:: agent_id: The ID of the agent to update agent_args: New agent arguments mcp_servers_mapping: Optional dict mapping MCP server names to tool names (or None)

Example: {“powerpoint_server”: “powerpoint_mcp_tool”, “web_search”: None}
Returns:: The updated agent ID

update_custom_agent_tool(tool_id: str, tool_args: dict, custom_tool_path: str | None = None) → str

Updates a custom agent tool’s arguments.

When custom_tool_path is provided, this will: 1. Upload the new file to object storage 2. Delete the old file from object storage 3. Update the tool’s configuration with the new file reference

Behavior change (v1.7.5): updates are per-tool. For remote_mcp tools, a mcp_config_json payload must describe exactly one server; a payload with multiple servers now raises an error instead of silently keeping the first server and dropping the rest. Use add_custom_agent_tool to create additional tools. Updating unsupported tool_type values (e.g. api_app/oauth_app) also raises a clear error.

Args:

tool_id: The ID of the tool to update tool_args: New tool arguments custom_tool_path: Optional path to a new file to replace the existing tool file

Returns:

The updated tool ID

Raises:

HTTPError: If the remote_mcp mcp_config_json contains more than: one server, or if the tool’s tool_type does not support updates.

update_document_metadata(document_id: str, document_metadata: dict) → str

Set the new document metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

document_id:: ID of the document to update.
document_metadata:: Dictionary containing the new document metadata.

Returns:

str: ID of the updated document.

update_document_name(document_id: str, name: str) → str

Update the name metadata for a given document.

Args:

document_id:: ID of the document to update.
name:: New name of the document, must include file extension.

Returns:

str: ID of the updated document.

update_document_uri(document_id: str, uri: str) → str

Update the URI metadata for a given document.

Args:

document_id:: ID of the document to update.
uri:: New URI of the document, this is required.

Returns:

str: ID of the updated document.

Updates an existing extractor.

Only the arguments that are passed are changed; every argument left as None keeps the extractor’s current value.

An empty string is a value rather than an absence: it writes an empty string, which for extractor_schema and prompt is the meaningful “use the default” setting. An empty llm or vision_llm is rejected, since a model cannot be cleared.

guardrails_settings replaces the whole object rather than merging into it, so a dict carrying one key drops every other guardrail setting the extractor had. Pass the complete settings to change one of its fields.

Args:

extractor_id: The ID of the extractor to update. name: New name of the extractor. llm: New LLM to use for extraction. extractor_schema: New JSON schema defining the extraction structure. If not empty, extractor will return data as JSON object. description: New description of the extractor. prompt: New prompt text for the extractor. If combined with extractor_schema, prompt can modify the output, but not its format as it’s set to be JSON object. pre_prompt_summary: New pre-prompt summary text for the extractor. keep_intermediate_results: New flag indicating whether to keep intermediate results during extraction. system_prompt: New system prompt text for the extractor. max_num_chunks: New maximum number of chunks to process. vision: New vision mode setting. One of ‘on’, ‘off’ or ‘auto’. vision_llm: New vision LLM model identifier. image_batch_image_prompt: New image batch processing prompt. image_batch_final_prompt: New final prompt for image batch processing. guardrails_settings: New guardrails settings configuration as a dictionary.

Returns:

Extractor: Details of the updated extractor.

Raises:

UnauthorizedError: If the extractor does not exist or is not visible to the caller. InvalidArgumentError: If no field was supplied, if extractor_id is not a uuid, if

llm or vision_llm is empty, if vision is not ‘on’/’off’/’auto’, or if max_num_chunks is below 1.

ObjectNotFoundError: If llm or vision_llm names a model the caller is not: granted.

update_forum(forum_id: str, name: str | None = None, description: str | None = None) → None

Update a forum’s configuration.

Args:: forum_id: The forum’s UUID. name: New name (optional). description: New description (optional).

update_forum_post(post_id: str, content: str) → None

Update a forum post (author only).

Args:: post_id: The post’s UUID. content: New content.

Update fields of a memory block. None leaves a field untouched.

Args:

memory_block_id:: ID of the memory block to update.
name:: New display name.
content:: New text content.
system_prompt_amendment:: New system prompt amendment.
injection_mode:: New injection mode.
access_mode:: New access mode.
max_content_length:: New maximum content length.

update_prompt_template(id: str, name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Update a prompt template

Args:

id:: String ID of the prompt template to update
name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the updated prompt template.

update_question_reply_feedback(reply_id: str, expected_answer: str, user_comment: str)

Update feedback for a specific answer to a question.

Args:

reply_id:: UUID of the reply.
expected_answer:: Expected answer.
user_comment:: User comment.

Returns:

None

update_runtime_llm(model_id: str, config: Dict[str, Any]) → Dict[str, Any]: NOT SUPPORTED – a runtime LLM can only be created and deleted; this call is rejected by the server. display_name is the routing key at the serving proxy, so an in-place edit can leave a saved, successfully probed model whose every request fails there. To change a configuration, delete_runtime_llm() it and create_runtime_llm() it again (admin only).

Partially update a scheduled task. Omitted args are left unchanged.

To pause/resume, pass status=’paused’/’active’. To CLEAR a nullable field, use the sentinels: max_executions=-1 clears it; expires_at=’1970-01-01T00:00:00Z’ clears it.

To change individual task_config fields without resending the whole dict, pass task_config_patch: top-level keys are merged server-side; a key set to None is REMOVED (e.g. task_config_patch={“collection_id”: None} unbinds the collection). Nested objects are replaced whole. Mutually exclusive with task_config. The merged result must keep a non-empty ‘message’. Example: task_config_patch={“message”: “new prompt”}.

Args:

message: Convenience for task_config_patch={‘message’: …}: changes: just this config field, server-side merge, no other fields touched. None = no change.
timezone: Convenience for task_config_patch={‘timezone’: …}: changes: just this config field, server-side merge, no other fields touched. None = no change. To CLEAR the timezone, use task_config_patch={‘timezone’: None} (a kwarg None cannot express removal).
collection_id: Convenience for task_config_patch={‘collection_id’: …}:: changes just this config field, server-side merge, no other fields touched. None = no change. To UNBIND the collection, use task_config_patch={‘collection_id’: None} (a kwarg None cannot express removal).

Returns:

ScheduledTask: the updated task (refetched).

Update any user’s scheduled task — status and metadata only (admin only).

Note: max_executions and expires_at cannot be changed through this admin method (matches the UI). Returns {‘status’: ‘updated’}.

update_secret(secret_id: str, secret: Dict[str, Any]) → None

Update an existing secret in the SecureStore.

Args:: secret_id: The ID of the secret to update. secret: A dictionary containing the updated secret data

(the payload stored under secret_value).
Returns:: None

update_shared_chat(shared_chat_id: str, is_private: bool | None = None, includes_artifacts: bool | None = None) → None

Update a shared chat’s settings.

Only shared chats owned by the current user can be updated.

Args:

shared_chat_id:: ID of the shared chat to update.
is_private:: If provided, update the privacy setting.
includes_artifacts:: If provided, update the artifacts inclusion setting.

update_showcase_chat(showcase_id: str, title: str | None = None, description: str | None = None, category: str | None = None) → None

Update tile metadata on a showcase entry. Requires manage_showcase. The thumbnail is managed exclusively via upload_showcase_thumbnail / delete_showcase_thumbnail.

None (default) leaves a field untouched on the server.

title and description cannot be cleared — passing an empty string yields a 400 from the server. Only category accepts an empty string, which clears it back to NULL and moves the tile into the Uncategorized group.

update_tag(tag_name: str, description: str, format: str) → str

Updates a tag.

Args:

tag_name:: String representing the tag to update.
description:: String describing the tag.
format:: String representing the format of the tag.

Returns:

String: The id of the updated tag.

update_user_builtin_mcp(mcp_id: str, mcp_config: dict) → dict

Update an existing user builtin MCP configuration.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may edit any entry.

Args:

mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) mcp_config: Dictionary containing the updated MCP configuration.

Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

Returns:

dict: Dictionary with the updated MCP details

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the MCP config is invalid

Example:

```python mcp_config = {

“name”: “My Updated MCP”, “description”: “Updated description”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = client.update_user_builtin_mcp(“my_custom_builtin”, mcp_config) ```

upload(file_name: str, file: Any, uri: str | None = None) → str

Upload a file to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:

ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file

Args:

file_name:: What to name the file on the server, must include file extension.
file:: File object to upload, often an opened file from with open(…) as f.
uri:: Optional - URI you would like to associate with the file.

Returns:

str: The upload id to be used in ingest jobs.

Raises:

Exception: The upload request was unsuccessful.

upload_showcase_thumbnail(showcase_id: str, file_path: str | Path) → UploadShowcaseThumbnailResponse: Upload an image file as the thumbnail for a showcase tile.

vote_on_forum_post(post_id: str, vote: int, assistant_id: str | None = None) → None

Vote on a forum post.

Args:: post_id: The post’s UUID. vote: +1 for upvote, -1 for downvote, 0 to clear vote. assistant_id: Optional assistant ID if voting as an assistant.

wake_ai_assistant(assistant_id: str) → None

Manually trigger a wake cycle for an AI assistant.

The assistant must be in ‘sleeping’ status. This calls the REST API endpoint which pushes a wake event to Redis for the event loop to process.

Uses the REST API endpoint which pushes the wake event via Redis, unlike calling the RPC directly which would only update the DB status.

Args:: assistant_id: The assistant’s UUID.

class h2ogpte.H2OGPTEAsync(address: str, api_key: str | None = None, token_provider: AsyncTokenProvider | None = None, verify: bool | str = True, strict_version_check: bool = False, send_client_version: bool = True, azure_token: str | None = None)

Bases: _GraphRAGMixin, _GenerateAssistantMixin, _GenerateScheduledTaskMixin, _ScheduledTaskMixin, _InsertCommandSynthPairMixin, _AiAssistantMixin, _DefaultMemoryBlockMixin, _SkillsMixin, _ShowcaseMixin, _MemoryBlockMixin, _LLMRegistryMixin, _ConnectorsMixin, _AudioTimestampsMixin, _JobHistoryMixin, _ExtractorMixin

Connect to and interact with an h2oGPTe server, via an async interface.

INITIAL_WAIT_INTERVAL = 0.1

MAX_WAIT_INTERVAL = 1.0

TIMEOUT = 3600.0

WAIT_BACKOFF_FACTOR = 1.4

async add_agent_key(agent_keys: List[dict]) → List[dict]

Create one or more agent keys for use with agent tools.

Processes a list of agent key configurations and creates each key. Continues processing remaining keys if individual key creation fails.

Args:

agent_keys: List of key configuration dictionaries.

Expected structure:

[
    {
        "name": str,
            # Display name for the key

        "value": str,
            # The actual key/token value

        "key_type": str,
            # Type of key ("private" or "shared")

        "description": str,
            # (Optional) Description of the key's purpose
    }
]

Returns:

List[dict]: List of created key results. Each successful creation: returns {“agent_key_id”: str}. Failed creations are logged but don’t appear in results.

async add_builtin_mcp(mcp_id: str, keys: List[dict] | None = None, file_paths: List[str] | None = None) → str

Add a built-in MCP (Model Context Protocol server) to user’s tools.

This configures and enables a predefined MCP for the user, automatically adding it to the user’s tool preferences.

Args:

mcp_id: The ID of the built-in MCP to add (e.g., “playwright_builtin”, “slack_builtin”) keys: Optional list of agent key associations for the MCP.

Each dict should have: {“name”: “ENV_VAR_NAME”, “key_id”: “agent_key_id”}

file_paths: Optional list of file paths to upload for MCP configuration.: Files will be uploaded and attached to the MCP configuration.

Returns:

str: The ID of the added MCP tool

Raises:

InvalidArgumentError: If the MCP is an OAuth app type or file not found

Example:

```python # Add Slack MCP with API key tool_id = await client.add_builtin_mcp(

mcp_id=”slack_builtin”, keys=[{“name”: “SLACK_MCP_XOXP_TOKEN”, “key_id”: “my_key_id”}]

)

# Add MCP with file paths (files will be uploaded automatically) tool_id = await client.add_builtin_mcp(

mcp_id=”custom_mcp”, file_paths=[“/path/to/config.json”, “/path/to/schema.yaml”]

async add_custom_agent(agent_type: str, agent_args: dict, agent_path: str, agent_name: str | None = None) → list

Adds a custom agent by uploading a zip file.

Args:: agent_type: Type of agent (langgraph, crewai, openai, claude) agent_args: Agent configuration arguments agent_path: Path to the agent zip file agent_name: Optional user-provided name for the agent. If provided and the

zip contains exactly one agent, this name will be used instead of the folder name inside the zip. If not provided (or empty), the agent name is derived from the folder name(s) inside the zip.
Returns:: List of agent IDs created from the upload

async add_custom_agent_tool(tool_type: str, tool_args: dict, custom_tool_path: str | None = None, generate_system_prompt: bool = False, system_prompt_generation_timeout: float | None = None) → list

Adds a custom agent tool.

Args:

tool_type: The type of custom tool being added. Valid values:

‘local_mcp’: Model Context Protocol server running locally
‘remote_mcp’: Model Context Protocol server running remotely
‘browser_action’: Custom browser automation actions
‘general_code’: General purpose code execution tools

tool_args: Dictionary containing tool-specific arguments. Structure varies by tool_type:

For ‘remote_mcp’: {

“mcp_config_json”: “JSON string with MCP server configuration”, “enable_by_default”: True/False (optional, defaults to True)

}

For ‘local_mcp’, ‘browser_action’, and ‘general_code’: {

“tool_name”: “string (optional, defaults to filename without extension)”, “description”: “string (optional, tool description)”, “enable_by_default”: True/False (optional, defaults to True), “should_unzip”: True/False (optional, for general_code .zip files only), “tool_usage_mode”: [“runner”, “creator”] (optional list of strings, for remote_mcp)

}

custom_tool_path: Path to the tool file to upload (optional). Requirements vary by tool_type:

‘local_mcp’: .zip file containing MCP server code
‘remote_mcp’: Optional configuration file — any extension accepted
(common: .json, .yml, .yaml, .py, .zip, .toml, .ini, .conf, .config, .env, .txt)
‘browser_action’: .py file (must start with ‘browser_’) or .zip containing browser action scripts
‘general_code’: .py or .zip file with custom code

generate_system_prompt:

(Optional) If True and tool_type is “general_code”, generates a system prompt for the tool using LLM analysis and waits for completion. Default is False. Note: this is synchronous and the server holds the connection open until the job completes. Ensure your HTTP client and any intermediate proxies have sufficient timeout (nginx/ALB default to 60-120s, which may cause 504 errors). Use system_prompt_generation_timeout to set a server-side wait budget that returns 408 before the proxy times out.

system_prompt_generation_timeout:

(Optional) Server-side wait budget in seconds. Only used when generate_system_prompt=True. Set below your proxy/ingress read timeout so the API returns 408 instead of letting the proxy emit a 504. Defaults to the server-side cap of 600 seconds (10 minutes).

Returns:

list: List of created custom agent tool IDs

async add_role_to_group(group_id: str, roles: List[str]) → List[UserRole]

async add_role_to_user(user_id: str, roles: List[str]) → List[UserRole]

async add_user_document_permission(user_id: str, document_id: str) → [<class 'str'>, <class 'str'>]

Associates a user with a document they have permission on. Args:

user_id:
String The id of the user that has the permission.

document_id:
String The id of the document that the permission is for.

Returns:: [user_id, document_id]: A tuple containing the user_id and document_id.

async admin_cleanup_chat_sessions(older_than_days: int, force: bool = False, timeout: float | None = None) → Job

Delete chat sessions older than a specified number of days.

Admin-only. Dispatches a cleanup job for chat sessions that haven’t been active for the specified number of days.

Args:

older_than_days:: Delete sessions inactive for this many days.
force:: If True, also delete keep_forever and exempt sessions.
timeout:: Timeout in seconds.

Returns:

The cleanup job.

Send a message and get a response from an LLM.

Note: This method is only recommended if you are passing a chat conversation or for low-volume testing. For general chat with an LLM, we recommend session.query() for higher throughput in multi-user environments. The following code sample shows the recommended method:
# Establish a chat session
chat_session_id = client.create_chat_session()
# Connect to the chat session
with client.connect(chat_session_id) as session:
    # Send a basic query and print the reply
    reply = session.query("Hello", timeout=60)
    print(reply.content)
Format of inputs content:
{text_context_list}
"""\n{chat_conversation}{question}
Args:

question:
Text query to send to the LLM.

text_context_list:
List of raw text strings to be included, will be converted to a string like this: “

“.join(text_context_list)

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default, or None for h2oGPTe default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks in text_context_list. Only used if text_context_list is provided.

prompt_query:

Text that is appended after the contextual document chunks in text_context_list. Only used if text_context_list is provided.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

# Core generation parameters temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. min_chars_per_yield (int) — Minimum number of characters to yield at a time during streaming reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort

# Output format parameters response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation json_preserve_system_prompt (bool) — Whether to preserve the system prompt when using JSON response format

# Vision and image parameters images_num_max (int) — Maximum number of images to process visible_vision_models (list) — List of vision models that can be used

# Agent parameters use_agent (bool, default: False) — Whether to enable agent functionality for advanced task processing with access to tools shared_agent (bool, default: False) — Whether to use shared agent instance across multiple requests for efficiency agent_type (str, default: “auto”) — Type of agent to use. Options: [“auto”, “agent_analysis”, “agent_chat_history_md”, “agent_code”, “agent_rag”] selected_tool_type (str, default: “auto”) — Type of tools to make available to the agent. Options: [“auto”, “all”, “any”] or specific tool names selected_agent_type (str, optional) — Agent framework type for agents_builder. Options: [“crewai”, “langgraph”, “openai”] agent_accuracy (str, default: “standard”) — Accuracy level for agent operations. Options:

“quick” - Fastest, less verification (max_turns=10, timeout=30s) “basic” - Best for simple tasks (max_turns=20, timeout=60s) “standard” - Good for most tasks (max_turns=40, timeout=120s) “maximum” - Highest accuracy, can take a long time (max_turns=80, timeout=240s)

agent_max_turns (Union[str, int], default: “auto”) — Maximum number of back-and-forth turns the agent can take. Either “auto” or an integer agent_original_files (list) — List of file paths for agent to process and analyze agent_timeout (int) — Timeout in seconds for each individual agent turn/operation agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent operations combined agent_min_time (int) — Minimum time in seconds to run the agent before allowing completion agent_tools (Union[str, list], default: “auto”) — List of specific tools available to the agent. Options: “auto”, “all”, “any”, or list of tool names user_persona (str) — User persona description for agent context to customize agent behavior agent_code_writer_system_message (str) — Custom system message for code writing agent to guide code generation agent_code_restrictions_level (int) — Level of code execution restrictions for agent (typically 0 for unrestricted) agent_num_executable_code_blocks_limit (int) — Maximum number of code blocks the agent can execute in a single session agent_system_site_packages (bool, default: False) — Whether agent can use system site packages when executing code agent_main_model (str) — Main model to use for agent operations (e.g., specific LLM name) agent_max_stream_length (int, default: -1) — Maximum length for agent streaming responses, -1 for unlimited agent_max_memory_usage (int) — Maximum memory usage in bytes for agent operations agent_main_reasoning_effort (int) — Level of reasoning effort for main agent model (higher values = more reasoning, e.g., 10000) agent_advanced_reasoning_effort (int) — Level of reasoning effort for advanced agent operations (e.g., 20000) agent_max_confidence_level (int) — Maximum confidence level for agent decisions (typically 0, 1, or 2) agent_planning_forced_mode (bool) — Whether to force planning mode for agent (True to always plan first) agent_too_soon_forced_mode (bool) — Whether to force handling of premature agent decisions agent_critique_forced_mode (int) — Whether to force critique mode for agent self-evaluation agent_query_understanding_parallel_calls (int) — Number of parallel calls for query understanding tool_building_mode (str) — Mode for tool building configuration agent_stream_files (bool, default: True) — Whether to stream files from agent operations for real-time updates

# Other parameters max_time (int) — Maximum time in seconds for the operation client_metadata (dict) — Metadata to include with the request

chat_conversation:

List of tuples for (human, bot) conversation that will be pre-appended to an (question, None) case for a query.

guardrails_settings:

Guardrails Settings.

timeout:

Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:: h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

async archive_chat_session(chat_session_id: str) → str

Archive a chat session along with its associated data.

Admin-only. Sets the session status to ‘archived’, clears expiry settings, and marks keep_forever as false.

Args:

chat_session_id:: ID of the chat session to archive.

async archive_collection(collection_id: str) → str

Archive a collection along with its associated data.

Args:

collection_id:: ID of the collection to archive.

async assign_agent_key_for_tool(tool_dict_list: List[dict]) → List[Tuple] | None

Assign agent keys to tools by creating associations between them.

Args:

tool_dict_list: List of dictionaries containing tool association data.

Each dictionary should have a “tool_dict” key with the association configuration data for creating agent tool key associations.

Expected tool_dict structure:

{
    "tool": str,        # Name of the tool (for example, "test_tool").
    "keys": list[dict], # List of key definitions. Each item is a dictionary with:
                       #   - "name": str
                       #       Environment variable name (for example, "TEST_KEY").
                       #   - "key_id": Any
                       #       Identifier assigned to the key (for example, agent_key_id).
}

Returns:

Optional[List[Tuple]]: List of tuples containing association details.: Each tuple contains (associate_id, tool, key_name, key_id, user_id). Returns None if no associations were created.

async assign_permissions_to_role(role_name: str, permission_names: Iterable[str]) → Result

async bulk_delete_global_configurations(key_names: List[str]) → List[GlobalConfigItem]

async bulk_delete_role_configurations(role_id: str, keys: List[str]) → List[ConfigItem]

Delete role configuration items for a given role. Args:

role_id:
The role id to delete configurations for.

keys:
List of configuration keys to delete.

Returns:: List[ConfigItem]: List of remaining role configurations.

async bulk_delete_user_configurations_for_user(user_id: str, key_names: List[str]) → List[ConfigItem]

async cancel_job(job_id: str) → Result

Stops a specific job from running on the server.

Args:

job_id:: String id of the job to cancel.

Returns:

Result: Status of canceling the job.

async cancel_user_job(job_id: str, cancel_reason: str | None = None) → Result

As an admin, stops a specific user job from running on the server.

Args:

job_id:: String id of the job to cancel.
cancel_reason:: Optional reason for canceling the job.

Returns:

Result: Status of canceling the job.

async close()

async confirm_current_user_deletion(delete_id: str, timeout: float | None = None) → None

Confirm deletion of the current user data.

Args:

delete_id:: The delete ID returned from request_current_user_deletion().
timeout:: Timeout in seconds. Default is 300 seconds.

connect(chat_session_id: str, prompt_template_id: str | None = None, open_timeout: int = 10, close_timeout: int = 10, max_connect_retries: int = 10, connect_retry_delay: int = 0.5, connect_retry_max_delay: int = 60) → SessionAsync

Create and participate in a chat session. This is a live connection to the H2OGPTE server contained to a specific chat session on top of a single collection of documents. Users will find all questions and responses in this session in a single chat history in the UI.

Args:

chat_session_id:: ID of the chat session to connect to.
prompt_template_id:: ID of the prompt template to use.
open_timeout:: Timeout in seconds for opening the connection.
close_timeout:: Timeout in seconds for closing the connection.
max_connect_retries:: Maximum number of connection retry attempts.
connect_retry_delay:: Initial delay in seconds between connection retries.
connect_retry_max_delay:: Maximum delay in seconds between connection retries.

Returns:

Session: Live chat session connection with an LLM.

async count_assets() → ObjectCount

Counts number of objects owned by the user.

Returns:: ObjectCount: The count of chat sessions, collections, and documents.

async count_chat_sessions() → int

Counts number of chat sessions owned by the user.

Returns:: int: The count of chat sessions owned by the user.

async count_chat_sessions_for_collection(collection_id: str) → int

Counts number of chat sessions in a specific collection.

Args:

collection_id:: String id of the collection to count chat sessions for.

Returns:

int: The count of chat sessions in that collection.

async count_collections() → int

Counts number of collections owned by the user.

Returns:: int: The count of collections owned by the user.

async count_documents(chat_session_id: str | None = None) → int

Counts number of documents accessed by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents so a filtered list can be paged against this total.

Returns:

int: The count of documents accessed by the user.

async count_documents_in_collection(collection_id: str) → int

Counts the number of documents in a specific collection.

Args:

collection_id:: String id of the collection to count documents for.

Returns:

int: The number of documents in that collection.

async count_documents_owned_by_me(chat_session_id: str | None = None) → int

Counts number of documents owned by the user.

Args:

chat_session_id:: Count only the documents generated by this chat session, matching the filter of the same name on list_recent_documents.

Returns:

int: The count of documents owned by the user.

async count_prompt_templates() → int

Counts number of prompt templates

Returns:: int: The count of prompt templates

async count_question_reply_feedback(collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → int

Fetch user’s questions and answers with feedback count.

Args:

collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only count feedbacks with no collection.

Returns:

int: the count of questions and replies that have a user feedback.

async create_api_key_for_user(user_id: str, name: str | None = None, collection_id: str | None = None, expires_in: str | None = None, inactivity_interval: int | None = None) → str

Allows admins to create a new api key for a specific user and optionally make it specific to a collection. Args:

user_id:
String: The id of the user the API key is for.

name:
(Optional) String: The name of the API key.

collection_id:
(Optional) String: The id of the specific collection.

expires_in:
(Optional) String: The expiration for the API key as an interval. Ex. “30 days” or “30 minutes”

inactivity_interval:
(Optional) int: The number of days a key can be unused for (no activity) before it becomes invalid.

Returns:: String: The id of the API key.

async create_chat_session(collection_id: str | None = None, workspace: str | None = None) → str

Creates a new chat session for asking questions (of documents).

Args:

collection_id:: String id of the collection to chat with. If None, chat with LLM directly.
workspace:: String id of the workspace this chat will be associated with. If None, the user’s default workspace will be used.

Returns:

str: The ID of the newly created chat session.

async create_chat_session_on_default_collection() → str

Creates a new chat session for asking questions of documents on the default collection.

Returns:: str: The ID of the newly created chat session.

Creates a new collection.

Args:

name:

Name of the collection.

description:

Description of the collection

embedding_model:

embedding model to use. call list_embedding_models() to list of options.

prompt_template_id:

ID of the prompt template to get the prompts from. None to fall back to system defaults.

collection_settings:

(Optional) Dictionary with key/value pairs to configure certain collection specific settings max_tokens_per_chunk: Approximate max. number of tokens per chunk for text-dominated document pages. For images, chunks can be larger. chunk_overlap_tokens: Approximate number of tokens that are overlapping between successive chunks. gen_doc_summaries: Whether to auto-generate document summaries (uses LLM) gen_doc_questions: Whether to auto-generate sample questions for each document (uses LLM) audio_input_language: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices. ocr_model: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models.

Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. auto - Automatic will auto-select the best OCR model for every page. off - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

tesseract_lang: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices. keep_tables_as_one_chunk: When tables are identified by the table parser the table tokens will be kept in a single chunk. chunk_by_page: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is true. handwriting_check: Check pages for handwriting. Will use specialized models if handwriting is found. follow_links: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document. max_depth: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings). max_documents: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit). root_dir: Root directory for document storage copy_document: Whether to copy the document when importing an existing document. guardrails_settings itself is a dictionary of the following keys.

column_redaction_config: list of list for redacting columns from CSV/TSV files (regex_pattern, fill_value) disallowed_regex_patterns: list of regular expressions that match custom PII presidio_labels_to_flag: list of entities to be flagged as PII by the built-in Presidio model. pii_labels_to_flag: list of entities to be flagged as PII by the built-in PII model. pii_detection_parse_action: what to do when PII is detected during parsing of documents. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content in the ingested documents with redaction bars. pii_detection_llm_input_action: what to do when PII is detected in the input to the LLM (document content and user prompts). One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. pii_detection_llm_output_action: what to do when PII is detected in the output of the LLM. One of [“allow”, “redact”, “fail”]. Redact will replace disallowed content with placeholders. prompt_guard_labels_to_flag: list of entities to be flagged as safety violations in user prompts by the built-in prompt guard model. guardrails_labels_to_flag: list of entities to be flagged as safety violations in user prompts. Must be a subset of guardrails_entities, if provided. guardrails_safe_category: (Optional) name of the safe category for guardrails. Must be a key in guardrails_entities, if provided. Otherwise uses system defaults. guardrails_entities: (Optional) dictionary of entities and their descriptions for the guardrails model to classify. The first entry is the “safe” class, the rest are “unsafe” classes. custom_pii_entities_to_flag: list of entities to redact in tabular data files. Must be a subset of custom_pii_entities, if provided. custom_pii_entities: (Optional) dictionary of entities and a short description for the LLM to check for and redact columns containing PII in tabular data files. guardrails_llm: LLM to use for guardrails and PII detection. Use “auto” for automatic. Use H2OGPTE.get_llms() to see all available options.

Example:

Note: Call client.get_guardrails_settings() to see all options for guardrails_settings.

collection_settings=dict(

max_tokens_per_chunk=320, chunk_overlap_tokens=0, guardrails_settings=dict(

disallowed_regex_patterns=[“secret_disallowed_word”, r”(?!0{3})(?!6{3})[0-8]d{2}-(?!0{2})d{2}-(?!0{4})d{4}”], presidio_labels_to_flag=[“IBAN_CODE”, “US_SSN”], pii_labels_to_flag=[“IBAN”, “SSN”], pii_detection_parse_action=”redact”, pii_detection_llm_input_action=”redact”, pii_detection_llm_output_action=”allow”, prompt_guard_labels_to_flag=[“JAILBREAK”], guardrails_labels_to_flag=[

“Violent Crimes”, “Non-Violent Crimes”, “Intellectual Property”, “Code Interpreter Abuse”,

], guardrails_safe_category=”Safe”, # guardrails_entities is intentionally NOT shown here. # Omit it to inherit the server’s maintained default # category definitions and keep receiving improvements # to them. Supplying it REPLACES the defaults wholesale # (it is not merged), so a dict copied from an example # pins the collection to those exact definitions # forever – including wordings later found too weak to # classify reliably. Pass it only when you own the full # category set deliberately. custom_pii_entities_to_flag=[

“Mother’s Maiden Name”

], custom_pii_entities={

“Mother’s Maiden Name”: “Mother’s maiden name.”

}, guardrails_llm=”meta-llama/Llama-3.3-70B-Instruct”,

),

)

thumbnail:

(Optional) Path to the thumbnail image for the collection. Must include appropriate file extension.

chat_settings:

(Optional) Dictionary with key/value pairs to configure the default values for certain chat specific settings The following keys are supported, see the client.session() documentation for more details. llm: str — Default LLM to use for chat sessions in this collection llm_args: dict — Default LLM arguments (see answer_question method for full list of valid keys) self_reflection_config: dict — Configuration for self-reflection functionality rag_config: dict — Configuration for RAG (Retrieval-Augmented Generation) include_chat_history: bool — Whether to include chat history in context tags: list[str] — Tags to associate with the collection

workspace:

(Optional) The workspace id to be associated with this collection. None to use the default workspace.

vex_encryption:

(Optional) Per-collection vector encryption choice. One of:

“enabled” — store vectors encrypted (the server must have a vector encryption provider configured).
“disabled” — store vectors as plaintext, even if the server has encryption enabled by default.
None — fall back to the server-level default.

Honored at create time only and sticky once any data is written.

Returns:

str: The ID of the newly created collection.

async create_custom_agent_key_association(agent_id: str, env_key_name: str, key_id: str) → dict

Creates a custom agent key association (env var -> agent key).

Args:

agent_id: Custom agent UUID env_key_name: Env var name (from envs.json or user-added) key_id: Agent key UUID to associate

Returns:

dict: Created association with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

async create_custom_agent_tool_association(agent_id: str, mcp_server_name: str, tool_name: str | None = None) → dict

Creates a custom agent tool association.

Args:: agent_id: Agent UUID mcp_server_name: MCP server name tool_name: Optional tool name to associate (None for unresolved)
Returns:: dict: Created association object

async create_extractor(name: str, llm: str, extractor_schema: Dict[str, Any], description: str = '', prompt: str = '', pre_prompt_summary: str = '', keep_intermediate_results: bool = False, system_prompt: str = '', max_num_chunks: int = 100, vision: str = 'auto', vision_llm: str = 'auto', image_batch_image_prompt: str = '', image_batch_final_prompt: str = '', guardrails_settings: Dict | None = None) → Extractor

Creates a new extractor.

Args:: name: Name of the extractor. llm: LLM to use for extraction. extractor_schema: JSON schema defining the extraction structure. If not empty, extractor will return data as JSON object. description: Optional description of the extractor. prompt: Optional prompt text for the extractor. If combined with extractor_schema, prompt can modify the output, but not its format as it’s set to be JSON object. pre_prompt_summary: Optional pre-prompt summary text for the extractor. keep_intermediate_results: Optional flag indicating whether to keep intermediate results during extraction. system_prompt: Optional system prompt text for the extractor. max_num_chunks: Optional maximum number of chunks to process. vision: Optional vision mode setting. vision_llm: Optional vision LLM model identifier. image_batch_image_prompt: Optional image batch processing prompt. image_batch_final_prompt: Optional final prompt for image batch processing. guardrails_settings: Optional guardrails settings configuration as a dictionary.
Returns:: Extractor: Details of the newly created extractor.
Raises:: InvalidArgumentError: If extractor_schema is neither a dict nor None.

async create_prompt_template(name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Create a new prompt template

Args:

name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the newly created prompt template.

async create_secret(secret: Dict[str, Any]) → str | None

Create a new secret in the SecureStore.

Args:

secret: A dictionary containing the secret data to be stored.: Must include secret_id and secret_value; secret_type is optional.

Returns:

The ID of the newly created secret.

async create_tag(tag_name: str) → str

Creates a new tag.

Args:

tag_name:: String representing the tag to create.

Returns:

String: The id of the created tag.

async create_user_builtin_mcp(mcp_config: dict, logo_path: str | None = None) → dict

Create a new user-specific builtin MCP configuration.

Publishes an MCP to the shared library so it appears in the builtin MCPs list for all users. Requires the ManageLibrary permission (admins hold it by default).

Args:

mcp_config: Dictionary containing the MCP configuration matching built_in_mcps.json structure.: Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

logo_path: Optional path to a logo image file to upload

Returns:

dict: Dictionary with the created MCP details including id, mcp_id, config, user_id, created_at, updated_at

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission InvalidArgumentError: If the MCP config is invalid or MCP ID already exists

Example:

```python mcp_config = {

“name”: “My Custom MCP”, “description”: “Custom MCP for internal use”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = await client.create_user_builtin_mcp(mcp_config, logo_path=”/path/to/logo.png”) ```

async create_user_group(name: str, description: str) → UserGroup

async create_user_role(name: str, description: str) → UserRole

async deactivate_api_key(api_key_id: str) → Result

Allows admins to deactivate an API key.

Note: You cannot undo this action.

Args:

api_key_id:: String: The id of the API key.

Returns:

Result: Status of the deactivate request.

async delete_agent_directories(chat_session_id: str) → bool: Delete agent directories for a chat session.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

async delete_agent_keys(key_ids: List[str]) → None

async delete_agent_server_files(chat_session_id: str) → bool

async delete_agent_tool_association(associate_ids: List[str]) → int

async delete_agent_tool_preference() → None

async delete_api_keys(api_key_ids: List[str]) → Result

Allows admins to delete API keys.

Args:

api_key_ids:: List[str]: The API keys to delete.

Returns:

Result: Status of the delete request.

async delete_chat_messages(chat_message_ids: Iterable[str]) → Result

Deletes specific chat messages.

Args:

chat_message_ids:: List of string ids of chat messages to delete from the system.

Returns:

Result: Status of the delete job.

async delete_chat_sessions(chat_session_ids: Iterable[str], timeout: float | None = None) → Job

Deletes chat sessions and related messages.

Args:

chat_session_ids:: List of string ids of chat sessions to delete from the system.
timeout:: Timeout in seconds.

Returns:

Result: The delete job.

async delete_collections(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections from the environment.

Documents in the collection that are owned by other users will not be deleted.

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

async delete_collections_as_admin(collection_ids: Iterable[str], timeout: float | None = None) → Job

Deletes collections and their associated data from the environment (needs appropriate permission).

Args:

collection_ids:: List of string ids of collections to delete from the system.
timeout:: Timeout in seconds.

async delete_custom_agent(agent_ids: List[str]) → int

Deletes custom agents.

Args:: agent_ids: List of agent IDs to delete
Returns:: Count of deleted agents

async delete_custom_agent_key_associations(association_ids: List[str]) → int

Deletes custom agent key associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

async delete_custom_agent_tool(tool_ids: List[str]) → int

async delete_custom_agent_tool_associations(association_ids: List[str]) → int

Deletes custom agent tool associations by IDs.

Args:: association_ids: List of association UUIDs to delete
Returns:: int: Number of associations deleted

async delete_document_summaries(summaries_ids: Iterable[str]) → Result

Deletes document summaries.

Args:

summaries_ids:: List of string ids of a document summary to delete from the system.

Returns:

Result: Status of the delete job.

async delete_documents(document_ids: Iterable[str], timeout: float | None = None) → Job

Deletes documents from the system.

Args:

document_ids:: List of string ids to delete from the system and all collections.
timeout:: Timeout in seconds.

async delete_documents_from_collection(collection_id: str, document_ids: Iterable[str], timeout: float | None = None) → Job

Removes documents from a collection.

See Also: H2OGPTE.delete_documents for completely removing the document from the environment.

Args:

collection_id:: String of the collection to remove documents from.
document_ids:: List of string ids to remove from the collection.
timeout:: Timeout in seconds.

async delete_extractor(extractor_id: str)

Deletes an extractor by its ID.

Args:: extractor_id: The ID of the extractor to delete.

async delete_multiple_agent_directories(chat_session_ids: List[str], dir_types: List[str]) → bool: Delete agent directories for multiple chat sessions.

Deprecated since version Agent: directories are now cleaned up automatically as part of the chat-session delete cascade. Call delete_chat_sessions instead. Deleting agent files mid-conversation leaves the agent in an inconsistent state (see h2oai/h2ogpte#7302). This method is kept for one deprecation cycle and will be removed in a future release.

async delete_prompt_templates(ids: Iterable[str]) → Result

Deletes prompt templates

Args:

ids:: List of string ids of prompte templates to delete from the system.

Returns:

Result: Status of the delete job.

async delete_secret(secret_id: str) → None

Delete a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to delete.
Returns:: None

async delete_shared_chats(shared_chat_ids: List[str]) → None

Delete shared chats by their IDs.

Only shared chats owned by the current user can be deleted.

Args:

shared_chat_ids:: List of shared chat IDs to delete.

async delete_tag(tag_name: str) → str

Deletes a tag from the system.

Only the tag creator can delete it. All document-tag associations are automatically removed.

Args:

tag_name:: String representing the tag to delete.

Returns:

String: The id of the deleted tag.

async delete_upload(upload_id: str) → str

Delete a file previously uploaded with the “upload” method.

See Also:

upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection.

Args:

upload_id:: ID of a file to remove

Returns:

upload_id: The upload id of the removed.

Raises:

Exception: The delete upload request was unsuccessful.

async delete_user_builtin_mcp(mcp_id: str) → dict

Delete a user builtin MCP by ID.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may remove any entry.

Args:: mcp_id: The ID of the MCP to delete (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with success message
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = await client.delete_user_builtin_mcp("my_custom_builtin") print(result["message"]) # "MCP deleted successfully" `

async delete_user_groups_by_ids(groups_ids: Iterable[str]) → Result

async delete_user_groups_by_names(groups_names: Iterable[str]) → Result

async delete_user_roles_by_ids(roles_ids: Iterable[str]) → Result

async delete_user_roles_by_names(roles_names: Iterable[str]) → Result

async download_agent_tool_file(tool_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the file associated with a custom agent tool.

Args:: tool_id: The ID of the custom agent tool whose file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves the original filename from the tool metadata, falling back to "tool_file".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

async download_custom_agent_file(agent_id: str, destination_directory: str | Path, destination_file_name: str | None = None) → Path

Downloads the zip file associated with a custom agent.

Args:: agent_id: The ID of the custom agent whose zip file should be downloaded. destination_directory: Directory to save the downloaded file into. destination_file_name: Optional filename for the downloaded file.

If not provided, resolves to "<agent_name>.zip" from the agent metadata, falling back to "agent.zip".
Returns:: Path: Path of the downloaded file.
Raises:: FileNotFoundError: If destination_directory does not exist. FileExistsError: If a file with the resolved name already exists.

async download_document(destination_directory: str | Path, destination_file_name: str, document_id: str) → Path

Downloads a document to a local system directory.

Args:

destination_directory:: Destination directory to save file into.
destination_file_name:: Destination file name.
document_id:: Document ID.

Returns:

Path: Path of downloaded document

async download_reference_highlighting(message_id: str, destination_directory: str, output_type: str = 'combined', limit: int | None = None) → list

Get PDFs with reference highlighting

Args:

message_id:: ID of the message to get references from
destination_directory:: Destination directory to save files into.
output_type: str one of: "combined" Generates a PDF file for each source document, with all relevant chunks highlighted in each respective file. This option consolidates all highlights for each source document into a single PDF, making it easy to view all highlights related to that document at once. "split" Generates a separate PDF file for each chunk, with only the relevant chunk highlighted in each file. This option is useful for focusing on individual sections without interference from other parts of the text. The output files names will be in the format “{document_id}_{chunk_id}.pdf”
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list[Path]: List of paths of downloaded documents with highlighting

async encode_for_retrieval(chunks: Iterable[str], embedding_model: str | None = None) → List[List[float]]

Encode texts for semantic searching.

See Also: H2OGPTE.match for getting a list of chunks that semantically match each encoded text.

Args:

chunks:: List of strings of texts to be encoded.
embedding_model:: embedding model to use. call list_embedding_models() to list of options.

Returns:

List of list of floats: Each list in the list is the encoded original text.

async export_feedback_csv(destination_directory: str | Path, destination_file_name: str = 'feedback_export.csv', collection_id: str | None = None, interval: str | None = None, no_collection: bool = False, filter: str | None = None, timeout: float | None = None) → Path

Export feedback data as CSV via async job and save to disk.

Submits an export job, waits for completion, then downloads the CSV file to the specified directory.

Args:

destination_directory:: Destination directory to save the CSV file into.
destination_file_name:: Destination file name. Defaults to "feedback_export.csv".
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only export feedbacks with no collection.
filter:: Optional text to match against the question or response content.
timeout:: Timeout in seconds for the export job.

Returns:

Path: Path of the downloaded CSV file.

Extract information from one or more contexts using an LLM.

pre_prompt_extract and prompt_extract variables must be used together. If these variables are not set, the inputs texts will be summarized into bullet points.

Format of extract content:
"{pre_prompt_extract}"""
{text_context_list}
"""\n{prompt_extract}"
Examples:
extract = h2ogpte.extract_data(
    text_context_list=chunks,
    pre_prompt_extract="Pay attention and look at all people. Your job is to collect their names.\n",
    prompt_extract="List all people's names as JSON.",
)
Args:

text_context_list:
List of raw text strings to extract data from.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_extract:
Text that is prepended before the list of texts. If not set, the inputs will be summarized.

prompt_extract:
Text that is appended after the list of texts. If not set, the inputs will be summarized.

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: ExtractionAnswer: The list of text responses and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

async finish_chat(question_id: str) → Result

Signal the LLM to complete its current thought and finish naturally.

Unlike stop_chat which immediately halts response generation, finish_chat allows the LLM to complete its current thought naturally, providing a more coherent ending.

Args:: question_id: The ID of the chat message/question to finish gracefully.
Returns:: Result: Status of the finish operation.
Raises:: Exception: If the user is not authorized to finish this chat or if the operation fails.

async fork_chat_session(chat_session_id: str, message_id: str | None = None) → str

Fork a chat session, creating an independent copy with all messages, references, metadata, and document associations preserved.

When message_id is provided, only messages up to and including that message are copied (branch from a specific point in the conversation).

Args:: chat_session_id: The ID of the chat session to fork. message_id: Optional message ID to branch from.
Returns:: The ID of the newly created (forked) chat session.

async get_agent_key_tool_associations() → List[dict]

async get_agent_keys() → List[dict]

async get_agent_server_files(chat_session_id: str) → List[dict]

async get_agent_suggestions(agent_id: str) → List[dict]

Gets MCP tool suggestions for a custom agent.

Returns suggested MCP tool configurations for a custom agent based on its metadata. Helps users identify and configure required tools.

Args:

agent_id: The unique identifier of the custom agent.

Returns:

List[dict]: A list of suggestion objects, each containing:

mcp_servers: List of MCP server suggestions with tool_name and tool_args

async get_agent_tool_preference() → List[str]

async get_agent_tools_dict() → dict

async get_all_agents() → List[dict]

Gets all agents (both built-in and custom) for the current user.

Returns:

List[dict]: A list of all agents with unified structure.: Each agent contains: id, value, label, enabled, type, owner, description, api_keys (grouped by optional/required/custom), and mcp_servers (for custom agents)

async get_all_directory_stats(chat_session_id: str, detail_level: int = 0) → dict

async get_chat_session_guardrails(chat_session_id: str) → str

Get guardrails settings for a specific chat session.

Args:

chat_session_id:: ID of the chat session

Returns:

str: JSON string containing guardrails settings or “null” if not set

async get_chat_session_prompt_template(chat_session_id: str) → PromptTemplate | None

Get the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session

Returns:

str: ID of the prompt template.

async get_chat_session_questions(chat_session_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

chat_session_id:: A chat session ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

async get_chat_session_workspace(chat_session_id: str) → str

Get the workspace associated with the chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

str: The identifier of the workspace

async get_chunks(collection_id: str, chunk_ids: Iterable[int]) → List[Chunk]

Get the text of specific chunks in a collection.

Args:

collection_id:: String id of the collection to search in.
chunk_ids:: List of ints for the chunks to return. Chunks are indexed starting at 1.

Returns:

Chunk: The text of the chunk.

Raises:

Exception: One or more chunks could not be found.

async get_collection(collection_id: str) → Collection

Get metadata about a collection.

Args:

collection_id:: String id of the collection to search for.

Returns:

Collection: Metadata about the collection.

Raises:

KeyError: The collection was not found.

async get_collection_for_chat_session(chat_session_id: str) → Collection

Get metadata about the collection of a chat session.

Args:

chat_session_id:: String id of the chat session to search for.

Returns:

Collection: Metadata about the collection.

async get_collection_prompt_template(collection_id: str) → PromptTemplate | None

Get the prompt template for a collection

Args:

collection_id:: ID of the collection

Returns:

str: ID of the prompt template.

async get_collection_questions(collection_id: str, limit: int) → List[SuggestedQuestion]

List suggested questions

Args:

collection_id:: A collection ID of which to return the suggested questions
limit:: How many questions to return.

Returns:

List: A list of questions.

async get_custom_agent(agent_id: str) → dict

Gets a single custom agent by ID for the current user.

Args:

agent_id: The unique identifier of the agent to retrieve.

Returns:

dict: A custom agent with details including: id, agent_name, agent_type,: agent_args, owner_email, mcp_servers, api_keys

Raises:

NotFoundError: If the agent is not found or not owned by the user

async get_custom_agent_tool(tool_id: str) → dict

Gets a single custom agent tool by ID for the current user.

Args:

tool_id: The unique identifier of the tool to retrieve.

Returns:

dict: A custom agent tool with details including: id, tool_name,: tool_type, tool_args, owner_email, file_name

Raises:

NotFoundError: If the tool is not found or not owned by the user

async get_custom_agent_tools() → List[dict]

Gets all custom agent tools for the current user.

Returns:

List[dict]: A list of custom agent tools with their details.: Each tool contains: id, tool_name, tool_type, tool_args, owner_email

async get_custom_agents() → List[dict]

Gets all custom agents for the current user.

Returns:

List[dict]: A list of custom agents with their details.: Each agent contains: id, agent_name, agent_type, agent_args, owner_email, resolved_tool_mapping

async get_default_collection() → CollectionInfo

Get the default collection, to be used for collection API-keys.

Returns:: CollectionInfo: Default collection info.

async get_directory_stats(directory_name: str, chat_session_id: str, detail_level: int = 0) → dict

async get_document(document_id: str, include_layout: bool = False) → Document

Fetches information about a specific document.

Args:

document_id:: String id of the document.
include_layout:: Include the layout prediction results.

Returns:

Document: Metadata about the Document.

Raises:

KeyError: The document was not found.

async get_document_content(file_name: str, document_id: str) → bytes

Downloads a document and return its content as a byte array.

Args:

file_name:: File name.
document_id:: Document ID.

Returns:

Path: File content

async get_effective_guardrails(chat_session_id: str | None = None, collection_id: str | None = None) → str

Get the effective guardrails settings based on the hierarchy.

Args:

chat_session_id:: Optional chat session ID to check for chat-level settings
collection_id:: Optional collection ID to check for collection-level settings

Returns:

str: JSON string containing effective guardrails settings

async get_extractor(extractor_id: str) → Extractor

Fetches an extractor by its ID.

Args:: extractor_id: The ID of the extractor to retrieve.
Returns:: Extractor: Details of the extractor.
Raises:: UnauthorizedError: If the extractor does not exist or is not visible to the caller. InvalidArgumentError: If extractor_id is not a uuid.

async get_global_configurations() → List[GlobalConfigItem]

async get_global_configurations_by_admin() → List[GlobalConfigItem]

async get_guardrails_settings(action: str = 'redact', sensitive: bool = True, non_sensitive: bool = True, all_guardrails: bool = True, guardrails_settings: dict | None = None) → Dict[str, str | List[str]]: Helper to get reasonable (easy to use) defaults for Guardrails/PII settings. To be further customized. :param action: what to do when detecting PII, either “redact” or “fail” (“allow” would keep PII intact). Guardrails models always fail upon detecting safety violations. :param sensitive: whether to include the most sensitive PII entities like SSN, bank account info :param non_sensitive: whether to include all non-sensitive PII entities, such as IP addresses, locations, names, e-mail addresses etc. :param all_guardrails: whether to include all possible entities for prompt guard and guardrails models, or just system defaults :param guardrails_settings: existing guardrails settings (e.g., from collection settings) to obtain guardrails entities, guardrails_entities_to_flag, column redaction custom_pii_entities, column_redaction_pii_to_flag from instead of system defaults :return: dictionary to pass to collection creation or process_document method

async get_h2ogpt_system_stats() → dict

async get_job(job_id: str) → Job

Fetches information about a specific job.

Args:

job_id:: String id of the job.

Returns:

Job: Metadata about the Job.

async get_llm_and_auto_reasoning_llm_names() → Dict[str, str]

Get mapping of llm to its reasoning_model when [“auto”] is passed as visible_reasoning_models

Returns:: dictionary {‘llm1’: ‘llm1_reasoning_llm’, etc.}

async get_llm_and_auto_vision_llm_names() → Dict[str, str]

Get mapping of llm to its vision_model when [“auto”] is passed as visible_vision_models

Returns:: dictionary {‘llm1’: ‘llm1_vision_llm’, etc.}

async get_llm_name_for_rest(llm: str | int | None)

async get_llm_names() → List[str]

Lists names of available LLMs in the environment.

Returns:: list of string: Name of each available model.

async get_llm_performance_by_llm(interval: str) → List[LLMPerformance]

async get_llm_usage_24h() → float

async get_llm_usage_24h_by_llm() → List[LLMUsage]

async get_llm_usage_24h_with_limits() → LLMUsageLimit

async get_llm_usage_6h() → float

async get_llm_usage_6h_by_llm() → List[LLMUsage]

async get_llm_usage_by_llm(interval: str) → List[LLMUsage]

async get_llm_usage_by_llm_and_user(interval: str) → List[LLMWithUserUsage]

async get_llm_usage_by_user(interval: str) → List[UserWithLLMUsage]

async get_llm_usage_with_limits(interval: str) → LLMUsageLimit

async get_llms() → List[Dict[str, Any]]

Lists metadata information about available LLMs in the environment.

Returns:: list of dict (string, ANY): Name and details about each available model.

async get_mcp_sdk_options() → dict

Get the schema of available Claude SDK options for MCP tool runners.

Returns:

dict: Schema with keys:

sdk_options_schema: Full ClaudeSdkAdvancedOptions JSON schema
permission_modes: List of valid permission mode strings
effort_levels: List of valid effort level strings
available_betas: List of available beta feature flags
hook_actions: List of valid hook action strings
hook_events: List of valid hook event strings
limitations: Dict of partially implemented features

Example:

`python schema = await client.get_mcp_sdk_options() print("Permission modes:", schema.get("permission_modes")) print("Effort levels:", schema.get("effort_levels")) `

async get_meta() → Meta

Returns information about the environment and the user.

Returns:: Meta: Details about the version and license of the environment and the user’s name and email.

async get_prompt_template(id: str | None = None) → PromptTemplate

Get a prompt template

Args:

id:: String id of the prompt template to retrieve or None for default

Returns:

PromptTemplate: prompts

Raises:

KeyError: The prompt template was not found.

async get_reasoning_capable_llm_names() → List[str]

Lists names of available reasoning-capable (that can natively reason) in the environment.

Returns:: list of string: Name of each available model.

async get_scheduler_stats() → SchedulerStats

Count the number of global, pending jobs on the server.

Returns:: SchedulerStats: The queue length for number of jobs.

async get_secret(secret_id: str) → Dict[str, Any] | None

Get a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret object corresponding to the provided ID.

async get_secret_value(secret_id: str) → Dict[str, Any] | None

Get the value of a secret from the SecureStore by its ID.

Args:: secret_id: The ID of the secret to retrieve.
Returns:: The secret value (a dictionary of credentials and configuration) corresponding to the provided ID, or None if it is empty.

async get_shared_chat(shared_chat_id: str) → SharedChatDetail

Get a shared chat by its ID.

Args:

shared_chat_id:: ID of the shared chat to retrieve.

Returns:

SharedChatDetail: Shared chat data including messages and metadata.

async get_tag(tag_name: str) → Tag

Returns an existing tag.

Args:

tag_name:: String The name of the tag to retrieve.

Returns:

Tag: The requested tag.

Raises:

KeyError: The tag was not found.

async get_user_all_agent_directories(offset: int, limit: int, filter_text: str | None) → List[dict]

async get_user_configurations() → List[ConfigItem]

Gets the user configurations for the current user.

Returns:: List[ConfigItem]: List of user configurations.

async get_user_configurations_for_user(user_id: str) → List[ConfigItem]

Gets the user configurations for a specific user (to be used by admins only).

Args:

user_id:: The unique identifier of the user.

Returns:

List[ConfigItem]: List of user configurations.

async get_vision_capable_llm_names() → List[str]

Lists names of available vision-capable multi-modal LLMs (that can natively handle images as input) in the environment.

Returns:: list of string: Name of each available model.

Import all documents from a collection into an existing collection

Args:

collection_id:: Collection ID to add documents to.
src_collection_id:: Collection ID to import documents from.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_document_status:: Whether to preserve each document’s original ingest mode (agent_only vs standard) when importing. When True, documents with agent_only status remain agent_only in the target collection. When False, all documents use the ingest_mode parameter uniformly.
preserve_metadata:: Whether to preserve the documents’ existing metadata when importing.
migrate_scheduled_connectors:: Whether to move scheduled connectors from source collection to target collection after documents are imported. The source collection will have no scheduled connectors after this operation. Only the owner of both collections can use this flag.
copy_lifecycle_settings:: Whether to copy lifecycle settings (expiry_date, inactivity_interval, size_limit) from the source collection to the target collection.
skip_reparse:: Whether to skip re-parsing documents and only re-embed existing chunks with the target collection’s embedding model. Much faster than full import since it skips file fetch, PDF conversion, OCR, and chunking. Only re-embeds the text chunks. Cannot be combined with copy_document=True.

Import an already stored document to an existing collection

Args:

collection_id:: Collection ID to add documents to.
document_id:: Document ID to add.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
copy_document:: Whether to save a new copy of the document
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.
preserve_metadata:: Whether to preserve the document’s existing metadata when importing.

async ingest_agent_only_to_standard(collection_id: str, document_id: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, timeout: float | None = None)

For files uploaded in “agent_only” ingest mode, convert to PDF and parse

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:: String id of the collection to add the ingested documents into.
document_id:: ID of document to be parsed.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
restricted:: Whether the document should be restricted only to certain users.
permissions:: List of permissions. Each permission is a SharePermission object.
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.

Add files from the Azure Blob Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
container:: Name of the Azure Blob Storage container.
path:: Path or list of paths to files or directories within an Azure Blob Storage container. Examples: file1, dir1/file2, dir3/dir4/
account_name:: Name of a storage account
credentials:: The object with Azure credentials. If the object is not provided, only a public container will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Metadata to be associated with the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Ingests confluence pages into collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
base_url:: Url of confluence instance. Example: https://h2oai.atlassian.net/wiki
page_id:: The page id or ids of pages to be ingested.
credentials:: The object with Confluence credentials.
include_attachments:: A flag indicating whether to also ingest attachments with the page.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the local system into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
root_dir:: String path of where to look for files.
glob:: String of the glob pattern used to match files in the root directory.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

Add files from the Google Cloud Storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of GCS files or directories. Examples: gs://bucket/file, gs://bucket/../dir/
credentials:: The object holding a path to a JSON key of Google Cloud service account. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

async ingest_from_plain_text(collection_id: str, plain_text: str, file_name: str, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None)

Add plain text to a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
plain_text:: String of the plain text to ingest.
file_name:: String of the file name to use for the document.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds

Add files from the AWS S3 storage into a collection.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: The path or list of paths of S3 files or directories. Examples: s3://bucket/file, s3://bucket/../dir/
region:: The name of the region used for interaction with AWS services.
credentials:: The object with S3 credentials. If the object is not provided, only public buckets will be accessible.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
metadata:: Dictionary of metadata to add to the document.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

async ingest_from_sharepoint_online(collection_id: str, entries: Sequence[SharepointOnlineEntry], credentials: SharepointOnlineAppCredentials | SharepointOnlineUserCredentials, gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None)

Add files from SharePoint Online into a collection.

Supports both site/drive/folder/file entries and the drive_by_id entry type for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites — see issue #10695), mixed freely in a single call.

Args:

collection_id: String id of the collection to add the: ingested documents into.
entries: Sequence of SharepointOnlineEntry to ingest.: See the class docstring for entry-type semantics — including "drive_by_id" for drives only reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites).
credentials: Either SharepointOnlineAppCredentials: (application permissions) or SharepointOnlineUserCredentials (OAuth delegated).

gen_doc_summaries: Whether to auto-generate document summaries. gen_doc_questions: Whether to auto-generate sample questions. audio_input_language: Spoken-language hint for audio files. ocr_model: OCR model for image text extraction. tesseract_lang: Tesseract language for ocr_model='tesseract'. keep_tables_as_one_chunk: Keep parsed table tokens in a single

chunk.

chunk_by_page: Make each page its own chunk. handwriting_check: Use specialized models when handwriting is

detected.

metadata: Metadata to associate with the document. timeout: Timeout in seconds. ingest_mode: Ingest mode ("standard", "lite",

"agent_only").

async ingest_uploads(collection_id: str, upload_ids: Iterable[str], gen_doc_summaries: bool | None = None, gen_doc_questions: bool | None = None, audio_input_language: str | None = None, ocr_model: str | None = None, restricted: bool = False, permissions: List[SharePermission] | None = None, tesseract_lang: str | None = None, keep_tables_as_one_chunk: bool | None = None, chunk_by_page: bool | None = None, handwriting_check: bool | None = None, metadata: Dict[str, Any] | None = None, timeout: float | None = None, ingest_mode: str | None = None, encrypt_document: bool | None = None, callback: Callable[[Job], None] | None = None) → Job

Add uploaded documents into a specific collection.

See Also:

upload: Upload the files into the system to then be ingested into a collection. delete_upload: Delete uploaded file

Args:

collection_id:

String id of the collection to add the ingested documents into.

upload_ids:

List of string ids of each uploaded document to add to the collection.

gen_doc_summaries:

Whether to auto-generate document summaries (uses LLM)

gen_doc_questions:

Whether to auto-generate sample questions for each document (uses LLM)

audio_input_language:

Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.

ocr_model:

Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).

restricted:

Whether the document should be restricted only to certain users.

permissions:

List of permissions. Each permission is a SharePermission object.

tesseract_lang:

Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.

keep_tables_as_one_chunk:

When tables are identified by the table parser the table tokens will be kept in a single chunk.

chunk_by_page:

Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.

handwriting_check:

Check pages for handwriting. Will use specialized models if handwriting is found.

metadata:

Dictionary mapping upload_ids to their metadata. Each key must be an upload_id from the upload_ids list, and each value is a dictionary of metadata key-value pairs to associate with that document.

Example:

# Single document
metadata = {upload_id: {"category": "reports", "year": "2024"}}

# Multiple documents
metadata = {
    upload_id_1: {"category": "reports"},
    upload_id_2: {"category": "invoices"}
}

timeout:

Timeout in seconds.

ingest_mode:

Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

encrypt_document:

Whether to encrypt the document files at rest in object storage.

callback:

Function for processing job status info during the upload.

Crawl and ingest a URL into a collection.

The web page or document linked from this URL will be imported.

Args:

collection_id:: String id of the collection to add the ingested documents into.
url:: String of the url to crawl.
gen_doc_summaries:: Whether to auto-generate document summaries (uses LLM)
gen_doc_questions:: Whether to auto-generate sample questions for each document (uses LLM)
follow_links:: Whether to import all web pages linked from this URL will be imported. External links will be ignored. Links to other pages on the same domain will be followed as long as they are at the same level or below the URL you specify. Each page will be transformed into a PDF document.
max_depth:: Max depth of recursion when following links, only when follow_links is True. Max_depth of 0 means don’t follow any links, max_depth of 1 means follow only top-level links, etc. Use -1 for automatic (system settings).
max_documents:: Max number of documents when following links, only when follow_links is True. Use None for automatic (system defaults). Use -1 for max (system limit).
audio_input_language:: Language of audio files. Defaults to “auto” language detection. Pass empty string to see choices.
ocr_model:: Which method to use to extract text from images using AI-enabled optical character recognition (OCR) models. Pass empty string to see choices. docTR is best for Latin text, PaddleOCR is best for certain non-Latin languages, Tesseract covers a wide range of languages. Mississippi works well on handwriting. “auto” - Automatic will auto-select the best OCR model for every page. “off” - Disable OCR for speed, but all images will then be skipped (also no image captions will be made).
tesseract_lang:: Which language to use when using ocr_model=”tesseract”. Pass empty string to see choices.
keep_tables_as_one_chunk:: When tables are identified by the table parser the table tokens will be kept in a single chunk.
chunk_by_page:: Each page will be a chunk. keep_tables_as_one_chunk will be ignored if this is True.
handwriting_check:: Check pages for handwriting. Will use specialized models if handwriting is found.
timeout:: Timeout in seconds.
ingest_mode:: Ingest mode to use. “standard” - Files will be ingested for use with RAG “lite” - Files will be ingested for use with RAG, but minimal processing will be done, favoring ingest speed over accuracy “agent_only” - Bypasses standard ingestion. Files can only be used with agents.

async inspect_mcp_tool(tool_id: str | None = None, servers: dict | None = None, file_path: str | None = None, model: str | None = None) → dict

Unified MCP tool inspection.

Supports three modes (provide exactly one): 1. tool_id — inspect an existing local or remote MCP tool by its ID. 2. servers — inspect one or more remote MCP server configs (pre-add). 3. file_path — inspect an uploaded MCP package file (pre-add).

Args:

tool_id: ID of an existing MCP tool to inspect. servers: Dict mapping server names to config dicts for pre-add inspection. file_path: Path to an MCP package file (.py, .zip, .tar.gz) for pre-add inspection. model: Optional LLM model for security inspection.

Returns:

dict: Unified result with keys:

status: ‘success’ or ‘error’
servers: List of per-server inspection result dicts
error: Top-level error message if status is ‘error’

Example:

```python # Inspect an existing tool result = await client.inspect_mcp_tool(tool_id=”abc-123”) for srv in result[“servers”]:

print(f”{srv[‘server_name’]}: {srv[‘tool_count’]} tools”)

# Inspect a remote config before adding result = await client.inspect_mcp_tool(

servers={“playwright”: {“command”: “npx”, “args”: [“@playwright/mcp@latest”]}}

invalidate_cookie_session() → None: Clear any cached cookie-mode session state so the next request re-runs the bootstrap. Call this after a 401 to recover from server-side session expiry without tearing down the client.

async is_collection_permission_granted(collection_id: str, permission: str) → bool

async is_permission_granted(permission: str) → bool

async launch_custom_agent_tool(tool_id: str) → dict

Launch a custom agent tool via CodeAPI.

Args:: tool_id: The ID of the tool to launch.
Returns:: Dict with codeapi_job_id and codeapi_url.

async list_all_api_keys(offset: int, limit: int, key_filter: str = '') → List[APIKey]

Allows admins to list all the API keys that exist.

Args:

offset:: Int: How many keys to skip before returning.
limit:: Int: How many keys to return.
key_filter:: String: Only returns keys for usernames matching this filter.

Returns:

List[APIKey]: List of APIKeys with metadata about each key.

async list_all_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[CollectionInfo]

Fetch all users’ collection metadata sorted by last update time.

This is for admin use only and includes private, public, and shared collections in the result.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return collections matching by name, id, or username.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_all_jobs() → List[UserJobs]

List all jobs (to be used by admins only).

Returns:: list of UserJobs

async list_all_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

async list_all_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Note: Users with permission to manage prompt templates can use this to list hidden default prompt templates.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

async list_all_tags(linked_only: bool = False, user_scope: bool = False) → List[Tag]

Lists all existing tags.

Args:

linked_only:: When True, returns only tags associated with at least one document. Default is False, which returns all tags.
user_scope:: When True, scopes results to the current user: tags from the user’s accessible documents, plus tags the user created. Combined with linked_only=True, excludes the user’s unlinked tags. Default is False.

Returns:

List of Tags: List of existing tags.

async list_archived_chat_sessions(offset: int, limit: int, sort_column: str, ascending: bool, filter: str = '') → List[ChatSessionInfo]

List archived chat sessions.

Admin-only. Returns chat sessions that have been archived by the expiry sweep or manually by an admin.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
sort_column:: Sort column. One of: name, updated_at, archived_at, username, collection_name.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Optional filter to return sessions matching by name, id, collection name, or username.

Returns:

list of ChatSessionInfo: Metadata about each archived chat session.

async list_builtin_mcps() → dict

List built-in MCPs (Model Context Protocol servers) available for use.

Returns a dictionary with two lists: - oauth_apps: List of OAuth-based MCP applications - api_key_apps: List of API key-based MCP applications

Each MCP includes information about whether it’s already added as a tool and whether the related OAuth connector is connected.

Returns:: dict: Dictionary containing ‘oauth_apps’ and ‘api_key_apps’ lists

async list_chat_message_meta_part(message_id: str, info_type: str) → ChatMessageMeta

Fetch one chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.
info_type:: Metadata type to fetch. Valid choices are: “self_reflection”, “usage_stats”, “prompt_raw”, “llm_only”, “hyde1”, “py_client_code”

Returns:

ChatMessageMeta: Metadata information about the chat message.

async list_chat_message_references(message_id: str, limit: int | None = None) → List[ChatMessageReference]

Fetch metadata for references of a chat message.

References are only available for messages sent from an LLM, an empty list will be returned for messages sent by the user.

Args:

message_id:: String id of the message to get references for.
limit:: The number of references to consider based on the highest confidence scores.

Returns:

list of ChatMessageReference: Metadata including the document name, polygon information, and score.

async list_chat_messages(chat_session_id: str, offset: int, limit: int) → List[ChatMessage]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessage: Text and metadata for chat messages.

async list_chat_messages_full(chat_session_id: str, offset: int, limit: int) → List[ChatMessageFull]

Fetch chat message and metadata for messages in a chat session.

Messages without a reply_to are from the end user, messages with a reply_to are from an LLM and a response to a specific user message.

Args:

chat_session_id:: String id of the chat session to filter by.
offset:: How many chat messages to skip before returning.
limit:: How many chat messages to return.

Returns:

list of ChatMessageFull: Text and metadata for chat messages.

async list_chat_sessions_for_collection(collection_id: str, offset: int, limit: int, username: str | None = None) → List[ChatSessionForCollection]

Fetch chat session metadata for chat sessions in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.
username:: Optional username to filter chat sessions by owner.

Returns:

list of ChatSessionForCollection: Metadata about each chat session including the latest message.

async list_chat_sessions_for_document(document_id: str, offset: int, limit: int) → List[ChatSessionForDocument]

Fetch chat session metadata for chat session that produced a specific document (typically through agents).

Args:

document_id:: String id of the document to filter by.
offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionForDocument: Metadata about each chat session including the latest message.

async list_collection_group_permissions(collection_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given collection.

The returned list of group permissions denoting which groups have access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given collection.

async list_collection_permissions(collection_id: str) → List[SharePermission]

Returns a list of access permissions for a given collection.

The returned list of permissions denotes who has access to the collection and their access level.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given collection.

async list_collection_public_permissions(collection_id: str) → List[str]

Returns the public permissions for a given collection.

The returned list contains the permission strings that apply to public access of the collection.

Args:

collection_id:: ID of the collection to inspect.

Returns:

list of str: Public permissions list for the given collection.

async list_collections_for_document(document_id: str, offset: int, limit: int) → List[CollectionInfo]

Fetch metadata about each collection the document is a part of.

At this time, each document will only be available in a single collection.

Args:

document_id:: String id of the document to search for.
offset:: How many collections to skip before returning.
limit:: How many collections to return.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_custom_agent_key_associations(agent_id: str | None = None) → List[dict]

Lists custom agent key associations, optionally filtered by agent_id.

Args:

agent_id: Optional agent UUID to filter by

Returns:

List[dict]: Association objects with id, agent_id, env_key_name, key_id,: requirement_type, key_name, owner_email.

async list_custom_agent_tool_associations(agent_id: str | None = None, agent_name: str | None = None) → List[dict]

Lists custom agent tool associations, optionally filtered by agent_id or agent_name.

Args:: agent_id: Optional agent UUID to filter by agent_name: Optional agent name to filter by
Returns:: List[dict]: A list of association objects with agent_id, agent_name, tool_id, tool_name, mcp_server_name, etc.

async list_document_chunks(document_id: str, collection_id: str | None = None) → List[SearchResult]

Returns all chunks for a specific document.

Args:

document_id:: ID of the document.
collection_id:: ID of the collection the document belongs to. If not specified, an arbitrary collections containing the document is chosen.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

async list_documents_from_tags(collection_id: str, tags: List[str]) → List[Document]

Lists documents that have the specified set of tags within a collection. Args:

collection_id:
String The id of the collection to find documents in.

tags:
List of Strings representing the tags to retrieve documents for.

Returns:: List of Documents: All the documents with the specified tags.

async list_documents_in_collection(collection_id: str, offset: int, limit: int, metadata_filter: dict = {}) → List[DocumentInfo]

Fetch document metadata for documents in a collection.

Args:

collection_id:: String id of the collection to filter by.
offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.

Returns:

list of DocumentInfo: Metadata about each document.

async list_embedding_models() → List[str]

async list_extractor_group_permissions(extractor_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given extractor.

The returned list of group permissions denoting which groups have access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given extractor.

async list_extractor_permissions(extractor_id: str) → List[SharePermission]

Returns a list of access permissions for a given extractor.

The returned list of permissions denotes who has access to the extractor and their access level.

Args:

extractor_id:: ID of the extractor to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given extractor.

async list_extractor_results(extractor_id: str, job_id: str | None = None, offset: int | None = None, limit: int | None = None) → List[DocumentExtractionResult]

Retrieve extraction results produced by this extractor.

If job_id is specified, returns results for that specific extraction run. If job_id is omitted, returns all results produced by this extractor across all runs.

Args:

extractor_id:: String ID of the extractor.
job_id:: Optional job ID to retrieve results for a specific extraction run. If omitted, returns all results for this extractor.
offset:: Optional number of extraction results to skip before returning. Defaults to 0 if not specified.
limit:: Optional maximum number of extraction results to return. If not specified, returns all results.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ObjectNotFoundError: If the extractor is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor.

async list_extractors(offset: int | None = None, limit: int | None = None, name_filter: str | None = None) → List[Extractor]

Lists available extractors.

Args:: offset: Number of extractors to skip. Defaults to server-side default (0). limit: Maximum number of extractors to return. Defaults to server-side default. name_filter: Filter extractors by name.
Returns:: List[Extractor]: A list of available extractors.

async list_group_permissions(group_id: str) → List[UserPermission]

async list_group_permissions_by_name(group_names: List[str]) → List[UserPermission]

async list_group_roles(group_id: str) → List[UserRole]

async list_jobs() → List[Job]

List the user’s jobs.

Returns:: list of Job:

async list_list_chat_message_meta(message_id: str) → List[ChatMessageMeta]

Fetch chat message meta information.

Args:

message_id:: Message id to which the metadata should be pulled.

Returns:

list of ChatMessageMeta: Metadata about the chat message.

async list_mcp_tools(config_type: str = 'runner', server_names: List[str] | None = None, mcp_dir: str | None = None, include_remote: bool = True) → dict

List tools from configured MCP servers.

Args:

config_type: Type of config (‘runner’ or ‘creator’). server_names: Optional list of server names to filter. mcp_dir: Optional override directory for MCP configs. include_remote: Whether to include remote MCP servers (default True).

Returns:

dict: Result with keys:

status: ‘success’ or ‘error’
servers: Dict mapping server names to tool lists
total_servers: Number of servers found
total_tools: Total number of tools across all servers
error: Error message if status is ‘error’

Example:

```python result = await client.list_mcp_tools(config_type=”runner”) for server, info in result.get(“servers”, {}).items():

print(f”{server}: {info[‘tool_count’]} tools”)

```

async list_prompt_group_permissions(prompt_id: str) → List[GroupSharePermission]

Returns a list of group access permissions for a given prompt template.

The returned list of group permissions denoting which groups have access to the prompt template.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of GroupSharePermission: Group sharing permissions list for the given prompt template.

async list_prompt_permissions(prompt_id: str) → List[SharePermission]

Returns a list of access permissions for a given prompt template.

The returned list of permissions denotes who has access to the prompt template and their access level.

Args:

prompt_id:: ID of the prompt template to inspect.

Returns:

list of SharePermission: Sharing permissions list for the given prompt template.

async list_question_reply_feedback_data(offset: int, limit: int, collection_id: str | None = None, interval: str | None = None, no_collection: bool = False) → List[QuestionReplyData]

Fetch user’s questions and answers that have a feedback.

Questions and answers with metadata and feedback information.

Args:

offset:: How many conversations to skip before returning.
limit:: How many conversations to return.
collection_id:: Optional collection ID to filter by.
interval:: Optional time interval to filter by (e.g. “7 days”, “30 days”, “90 days”, “1 year”).
no_collection:: If True, only return feedbacks with no collection.

Returns:

list of QuestionReplyData: Metadata about questions and answers.

async list_recent_chat_sessions(offset: int, limit: int) → List[ChatSessionInfo]

Fetch user’s chat session metadata sorted by last update time.

Chats across all collections will be accessed.

Args:

offset:: How many chat sessions to skip before returning.
limit:: How many chat sessions to return.

Returns:

list of ChatSessionInfo: Metadata about each chat session including the latest message.

async list_recent_collections(offset: int, limit: int, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_recent_collections_filter(offset: int, limit: int, current_user_only: bool = False, name_filter: str = '') → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with filter options.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
name_filter:: Only returns collections with names matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_recent_collections_metadata_filter(offset: int, limit: int, current_user_only: bool, metadata_filter: dict) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time with a filter on metadata.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
current_user_only:: When true, will only return the user owned collections.
metadata_filter:: Only returns collections with metadata matching this filter.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_recent_collections_sort(offset: int, limit: int, sort_column: str, ascending: bool, current_user_only: bool = False) → List[CollectionInfo]

Fetch user’s collection metadata sorted by last update time.

Args:

offset:: How many collections to skip before returning.
limit:: How many collections to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
current_user_only:: When true, will only return the user owned collections.

Returns:

list of CollectionInfo: Metadata about each collection.

async list_recent_document_summaries(document_id: str, offset: int, limit: int) → List[ProcessedDocument]

Fetches recent document summaries/extractions/transformations

Args:

document_id:: document ID for which to return summaries
offset:: How many summaries to skip before returning summaries.
limit:: How many summaries to return.

async list_recent_documents(offset: int, limit: int, metadata_filter: dict = {}, username: str = '', status: str = '', source: str = '', chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfo]

Fetch user’s document metadata sorted by last update time.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
metadata_filter:: Metadata filter to apply to the documents.
username:: Filter documents by the username of the uploader (exact match).
status:: Filter documents by ingestion status (exact match). Values: unknown, scheduled, queued, running, completed, failed, canceled, agent_only.
source:: Filter documents by connector source (case-insensitive match, e.g. SharePoint, url, upload, Agent).
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfo: Metadata about each document.

async list_recent_documents_with_summaries(offset: int, limit: int, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

async list_recent_documents_with_summaries_sort(offset: int, limit: int, sort_column: str, ascending: bool, chat_session_id: str | None = None, group_by_source_chat: bool = False) → List[DocumentInfoSummary]

Fetch user’s document metadata sorted by last update time, including the latest document summary.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; the sort order then applies within each group. Documents with no source chat come last.

Returns:

list of DocumentInfoSummary: Metadata about each document.

async list_recent_documents_with_summaries_sort_filter_by_type(offset: int, limit: int, sort_column: str = 'updated_at', ascending: bool = False, filter: str = '', interval: str = '36500 days', origin: str = '', use_age: bool = False, document_type: str = 'current_user', chat_session_id: str | None = None, group_by_source_chat: bool = False) → DocumentInfoSummaryListing

Fetch a filtered, sorted page of the user’s documents with summaries.

Unlike list_recent_documents_with_summaries_sort, this performs the text search, origin filtering, and age windowing server-side and returns the total match count alongside the page so the caller can paginate without a separate count query.

All documents owned by the user, regardless of collection, are accessed.

Args:

offset:: How many documents to skip before returning.
limit:: How many documents to return. Pass 0 (or a negative value) for no limit (all matches from offset onward).
sort_column:: Column to sort by. One of name, username, type, size, page_count, connector, uri, original_type, original_mtime, status, updated_at.
ascending:: When True, return sorted by sort_column in ascending order.
filter:: Case-insensitive substring matched against the document’s name, type, connector, uri, original_type, id, and username. Empty string matches everything.
interval:: A PostgreSQL interval string (e.g. "7 days") bounding how far back to look. Defaults to "36500 days" (effectively no bound).
origin:: Restrict by document origin. One of "Generated" (agent output), "Indexed" (completed non-agent docs), "Importable" (completed docs), "Canceled", "Agent Only", or "" for no origin filter.
use_age:: When True, the interval window is measured against each document’s original_mtime instead of its updated_at.
document_type:: Visibility scope. "current_user" returns only the calling user’s documents; "public" returns all documents.
chat_session_id:: Restrict to documents generated by this chat session. None (the default) applies no such restriction. Only agent-generated files record a source session, so any non-None value excludes every user-uploaded document.
group_by_source_chat:: When True, order by the source chat session first so every page returns whole, contiguous groups; sort_column then orders rows within each group. Documents with no source chat come last.

Returns:

DocumentInfoSummaryListing: The requested page in documents and the total number of matching documents in total. Each document carries chat_session_id and chat_session_name when it was generated by an agent, and chat_session_visible says whether the caller can open that session (a visible session may still have no name).

async list_recent_prompt_templates(offset: int, limit: int) → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.

Returns:

list of PromptTemplate: set of prompts

async list_recent_prompt_templates_sort(offset: int, limit: int, sort_column: str, ascending: bool, template_type: str = 'all', filter: str = '') → List[PromptTemplate]

Fetch user’s prompt templates sorted by last update time.

Args:

offset:: How many prompt templates to skip before returning.
limit:: How many prompt templates to return.
sort_column:: Sort column.
ascending:: When True, return sorted by sort_column in ascending order.
template_type:: When set, will be used as a type filter, possible values are: all, user, system.
filter:: When set, will be used as a filter on some prompt template columns.

Returns:

list of PromptTemplate: set of prompts

async list_role_configurations(role_id: str) → List[ConfigItem]

Lists role configurations for a given role. Args:

role_id:
The role id to get configurations for.

Returns:: List[ConfigItem]: List of role configurations.

async list_scheduled_connectors_for_collection(collection_id: str) → List[ScheduledConnectorDetails]

List scheduled connectors associated with a collection.

Args:

collection_id:: String id of the collection to list scheduled connectors for.

Returns:

List[ScheduledConnectorDetails]: Metadata about each scheduled connector.

async list_secret_ids(connector_type: str | None = None) → List[str]

List available secret IDs from the SecureStore for cloud storage connectors.

Args:

connector_type: Type of connector (‘s3’, ‘gcs’, ‘azure_key’, ‘azure_sas’): If None, returns secrets for all connector types.

Returns:

List of secret IDs available for the specified connector type

async list_shared_chats(offset: int = 0, limit: int = 100, filter_text: str = '', filter_type: str = 'all', showcase_filter: str = 'all') → List[SharedChatInfo]

List shared chats created by the current user.

Args:

offset:: Number of items to skip for pagination.
limit:: Maximum number of items to return.
filter_text:: Optional text to filter shared chats by name.
filter_type:: Type filter. One of ‘all’, ‘frozen’, ‘active’, ‘private’, ‘public’.
showcase_filter:: Showcase membership filter. One of ‘all’, ‘featured’, ‘not_featured’.

Returns:

list of SharedChatInfo: List of shared chat metadata.

async list_system_groups() → List[UserGroup]

async list_system_permissions() → List[UserPermission]

async list_system_roles() → List[UserRole]

async list_upload() → List[str]

List pending file uploads to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:: upload: Upload the files into the system to then be ingested into a collection. ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file
Returns:: List[str]: The pending upload ids to be used in ingest jobs.
Raises:: Exception: The upload list request was unsuccessful.

async list_user_permissions(user_id: str | None = None) → List[UserPermission]

async list_user_role_permissions(roles: List[str]) → List[UserPermission]

async list_user_roles(user_id: str | None = None) → List[UserRole]

async list_users(offset: int, limit: int) → List[User]

List system users.

Returns a list of all registered users fo the system, a registered user, is a users that has logged in at least once.

Args:

offset:: How many users to skip before returning.
limit:: How many users to return.

Returns:

list of User: Metadata about each user.

async make_collection_private(collection_id: str)

Make a collection private

Once a collection is private, other users will no longer be able to access chat history or documents related to the collection.

Args:

collection_id:: ID of the collection to make private.

async make_collection_public(collection_id: str, permissions: List[str] | None = None)

Make a collection public

Once a collection is public, it will be accessible to all authenticated users of the system.

Args:

collection_id:: ID of the collection to make public.
permissions:: Optional: Collection specific permissions. If not provided, all permissions will default to true.

async make_extractor_private(extractor_id: str)

Make an extractor private

Once a extractor is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

extractore_id:: ID of the extractor to make private.

async make_extractor_public(extractor_id: str)

Make an extractor public

Once an extractor is public, it can be seen and used by all users.

Args:

extractor_id:: ID of the extractor to make public.

async make_prompt_template_private(prompt_template_id: str)

Make a prompt template private

Once a prompt template is private, other users will no longer be able to see or use it unless it has been shared individually or by group.

Args:

prompt_template_id:: ID of the prompt template to make private.

async make_prompt_template_public(prompt_template_id: str)

Make a prompt template public

Once a prompt template is public, it can be seen and used by all users.

Args:

prompt_template_id:: ID of the prompt template to make public.

async match_chunks(collection_id: str, vectors: List[List[float]], topics: List[str], offset: int, limit: int, cut_off: float = 0, width: int = 0) → List[SearchResult]

Find chunks related to a message using semantic search.

Chunks are sorted by relevance and similarity score to the message.

See Also: H2OGPTE.encode_for_retrieval to create vectors from messages.

Args:

collection_id:: ID of the collection to search within.
vectors:: A list of vectorized message for running semantic search.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.
cut_off:: Exclude matches with distances higher than this cut off.
width:: How many chunks before and after a match to return - not implemented.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

async migrate_chat_sessions_to_collection(source_collection_id: str, target_collection_id: str, timeout: float | None = None) → Job

Migrate chat sessions from one collection to another.

This method creates a job to migrate chat sessions between collections. Only the collection owner can perform this operation.

Args:

source_collection_id:: String ID of the source collection containing the chat sessions.
target_collection_id:: String ID of the target collection to migrate chat sessions to.
timeout:: Timeout in seconds.

async migrate_scheduled_connectors_to_collection(collection_id: str, src_collection_id: str, timeout: float | None = None) → Job

Move all scheduled connectors from a source collection to a target collection.

Connectors are moved, meaning the source collection will have no scheduled connectors after this operation. Both collections must be owned by the same user.

Args:

collection_id:: Target collection ID where scheduled connectors will be moved to.
src_collection_id:: Source collection ID to move scheduled connectors from.
timeout:: Timeout in seconds.

async pause_chat(question_id: str) → Result

Pause a streaming chat response.

Args:: question_id: The ID of the chat message/question to pause.
Returns:: Result: Status of the pause operation.
Raises:: Exception: If the user is not authorized to pause this chat or if the operation fails.

Processes a document to either create a global or piecewise summary/extraction/transformation of a document.

Effective prompt created (excluding the system prompt):

"{pre_prompt_summary}
"""
{text from document}
"""
{prompt_summary}"

Args:

document_id:

String id of the document to create a summary from.

system_prompt:

System Prompt

pre_prompt_summary:

Prompt that goes before each large piece of text to summarize

prompt_summary:

Prompt that goes after each large piece of text to summarize

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

llm:

LLM to use

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:: temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation enable_vision (str, default: “auto”) — Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”] visible_vision_models (List[str], default: [“auto”]) — Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic

max_num_chunks:

Max limit of chunks to send to the summarizer

sampling_strategy:

How to sample if the document has more chunks than max_num_chunks. Options are “auto”, “uniform”, “first”, “first+last”, default is “auto” (a hybrid of them all).

pages:

List of specific pages (of the ingested document in PDF form) to use from the document. 1-based indexing.

schema:

Optional JSON schema to use for guided json generation.

keep_intermediate_results:

Whether to keep intermediate results. Default: disabled. If disabled, further LLM calls are applied to the intermediate results until one global summary is obtained: map+reduce (i.e., summary). If enabled, the results’ content will be a list of strings (the results of applying the LLM to different pieces of document context): map (i.e., extract).

guardrails_settings:

Guardrails Settings.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context given to the LLM. Only used if enable_vision is disabled. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

timeout:

Amount of time in seconds to allow the request to run. The default is 86400 seconds.

Returns:

ProcessedDocument: Processed document. The content is either a string (keep_intermediate_results=False) or a list of strings (keep_intermediate_results=True).

Raises:

TimeoutError: The request did not complete in time. SessionError: No summary or extraction created. Document wasn’t part of a collection, or LLM timed out, etc.

async remove_admin_mcp_logo(mcp_id: str) → dict

Remove the logo from an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”)
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist
Example:: `python result = await client.remove_admin_mcp_logo("my_custom_builtin") print(result["message"]) # "Logo removed successfully" `

async remove_chat_session_expiry_date(chat_session_id: str) → str

Remove the expiry date from a chat session.

Args:

chat_session_id:: ID of the chat session to update.

async remove_collection_expiry_date(collection_id: str) → str

Remove an expiry date from a collection.

Args:

collection_id:: ID of the collection to update.

async remove_collection_inactivity_interval(collection_id: str) → str

Remove an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.

async remove_collection_size_limit(collection_id: str) → str

Remove a size limit for a collection.

Args:

collection_id:: ID of the collection to update.

async remove_collection_thumbnail(collection_id: str, timeout: float | None = None)

Remove a thumbnail from a collection.

Args:

collection_id:: Collection you want to remove the thumbnail from.
timeout:: Amount of time in seconds to allow the request to run. The default is 86400 seconds.

async remove_custom_agent_tool_from_codeapi(tool_id: str) → bool

Remove a custom agent tool from CodeAPI, terminating its job.

Args:: tool_id: The ID of the tool to remove from CodeAPI.
Returns:: True on success.

async remove_permissions_from_role(role_id: str, permission_name: str) → Result

async remove_role_from_group(group_id: str, roles: List[str]) → List[UserRole]

async remove_role_from_user(user_id: str, roles: List[str]) → List[UserRole]

async rename_chat_session(chat_session_id: str, name: str)

Update a chat session name

Args:

chat_session_id:: String id of the document to search for.
name:: The new chat session name.

async request_current_user_deletion() → str

Request deletion of the current user account.

This creates a deletion request and returns a delete ID that must be used to confirm the deletion within 5 minutes.

Returns:: str: Delete ID that must be used to confirm deletion.

async reset_all_collection_expirations(): Reset any expiry dates and inactivity intervals that have been set for all collections (admin only). This will also reset any archived collections back to active.

async reset_and_share_extractor(extractor_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to an extractor (except for the owner) and share it with the provided list of new users.

Args:

extractor_id:: ID of the extractor to un-share.
new_usernames:: The list of usernames belonging to the users this extractor will be shared with.

ShareResponseStatus: Status of share request.

async reset_and_share_extractor_with_groups(extractor_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to an extractor and share it with the provided list of new group ids.

Args:

extractor_id:: ID of the extractor to un-share.
new_groups:: The list of group ids this extractor will be shared with.

ShareResponseStatus: Status of share request.

async reset_and_share_prompt_template(prompt_id: str, new_usernames: List[str]) → ShareResponseStatus

Remove all users who have access to a prompt template (except for the owner) and share it with the provided list of new users.

Args:

prompt_id:: ID of the prompt template to un-share.
new_usernames:: The list of usernames belonging to the users this prompt template will be shared with.

ShareResponseStatus: Status of share request.

async reset_and_share_prompt_template_with_groups(prompt_id: str, new_groups: List[str]) → ShareResponseStatus

Remove all groups who have access to a prompt template and share it with the provided list of new group ids.

Args:

prompt_id:: ID of the prompt template to un-share.
new_groups:: The list of group ids this prompt template will be shared with.

ShareResponseStatus: Status of share request.

async reset_collection_prompt_settings(collection_id: str) → str

Reset the prompt settings for a given collection.

Args:

collection_id:: ID of the collection to update.

Returns:

str: ID of the updated collection.

async reset_roles_for_group(group_id: str, roles: List[str]) → List[UserRole]

async reset_roles_for_user(user_id: str, roles: List[str]) → List[UserRole]

async reset_user_configurations_for_user(key_name: str, user_id: str) → List[ConfigItem]

Reset a user configuration for a specific user (to be used by admins only).

Returns:: List[ConfigItem]: List of user configurations.

async resume_chat(question_id: str) → Result

Resume a paused chat response.

Args:: question_id: The ID of the chat message/question to resume.
Returns:: Result: Status of the resume operation.
Raises:: Exception: If the user is not authorized to resume this chat or if the operation fails.

async run_extractor(extractor_id: str, collection_id: str | None = None, document_id: str | None = None, files: List[Tuple[str, bytes]] | None = None, timeout: int | None = None) → List[DocumentExtractionResult]

Run an extractor on a collection, single document, or uploaded files and wait for completion.

This method creates a job to execute the specified extractor and blocks until the job finishes. Exactly one of collection_id, document_id, or files must be provided. Mixing files with collection_id or document_id is not allowed.

Args:

extractor_id:: String ID of the extractor to run.
collection_id:: String ID of the collection to run the extractor on.
document_id:: String ID of a single document to run the extractor on.
files:: List of (filename, bytes) tuples to run the extractor on directly, without requiring a collection. The files are uploaded temporarily and deleted after extraction completes.
timeout:: Optional timeout in seconds.

Returns:

List[DocumentExtractionResult]: A list of extraction results containing: document ID, document name, extracted content, and any errors. content is a dict when the extractor has an input JSON schema, which constrains the output to a JSON object, and a str holding the free-form text otherwise.

Raises:

ValueError: If files is provided together with collection_id or document_id. ObjectNotFoundError: If the extractor or collection is not found. UnauthorizedError: If the user doesn’t have permission to access the extractor or collection.

Example:

# Run extraction on a collection and wait for results
results = await client.run_extractor(
    extractor_id="extractor-123",
    collection_id="collection-456"
)

# Run extraction on a single document and wait for results
results = await client.run_extractor(
    extractor_id="extractor-123",
    document_id="document-789"
)

# Run extraction on uploaded files directly
with open("report.pdf", "rb") as f:
    results = await client.run_extractor(
        extractor_id="extractor-123",
        files=[("report.pdf", f.read())]
    )

for result in results:
    print(f"Document: {result.document_name}")
    print(f"Extracted content: {result.content}")

async run_selftest(llm: str, mode: str) → dict

Run a self-test for a given LLM Args:

llm:
Name of LLM

mode:
one of [“quick”, “rag”, “full”, “agent”]

Returns:: Dictionary with performance stats. If “error” is filled, the test failed.

async search_chunks(collection_id: str, query: str, topics: List[str], offset: int, limit: int) → List[SearchResult]

Find chunks related to a message using lexical search.

Chunks are sorted by relevance and similarity score to the message.

Args:

collection_id:: ID of the collection to search within.
query:: Question or imperative from the end user to search a collection for.
topics:: A list of document_ids used to filter which documents in the collection to search.
offset:: How many chunks to skip before returning chunks.
limit:: How many chunks to return.

Returns:

list of SearchResult: The document, text, score and related information of the chunk.

async send_hitl_message(question_id: str, message: str) → Result

Send a course correction message to a running agent.

Sends a human-in-the-loop message to a running agent. The agent will incorporate this guidance before its next LLM call.

Args:: question_id: The ID of the active streaming chat question. message: The course correction message to send to the agent.
Returns:: Result: Status of the send operation.
Raises:: Exception: If the user is not authorized or if the operation fails.

async set_api_key_expiration(api_key_id: str, expires_in: str | None = None) → Result

Allows admins to set an expiration on an API key.

Args:

api_key_id:: String: The id of the API key.
expires_in:: (Optional) String: The expiration for the API key as an interval or None (to remove an expiration that was previously set). Ex. “30 days” or “30 minutes”

Returns:

Result: Status of the expiration request.

async set_api_key_inactivity_interval(api_key_id: str, inactivity_interval: int | None = None) → Result

Allows admins to set an inactivity interval for an API key. This is how many days a key can be unused for (no activity) before it becomes invalid.

Args:

api_key_id:: String: The id of the API key.
inactivity_interval:: (Optional) int: The inactivity interval for the API key as an integer of days or None (to remove an inactivity interval that was previously set).

Returns:

Result: Status of the request.

async set_chat_message_votes(chat_message_id: str, votes: int) → Result

Change the vote value of a chat message.

Set the exact value of a vote for a chat message. Any message type can be updated, but only LLM response votes will be visible in the UI. The expectation is 0: unvoted, -1: dislike, 1 like. Values outside of this will not be viewable in the UI.

Args:

chat_message_id:: ID of a chat message, any message can be used but only LLM responses will be visible in the UI.
votes:: Integer value for the message. Only -1 and 1 will be visible in the UI as dislike and like respectively.

Returns:

Result: The status of the update.

Raises:

Exception: The upload request was unsuccessful.

async set_chat_session_collection(chat_session_id: str, collection_id: str | None) → str

Set the collection for a chat_session

Args:

chat_session_id:: ID of the chat session
collection_id:: ID of the collection, or None to chat with the LLM only.

Returns:

str: ID of the updated chat session

async set_chat_session_expiry_date(chat_session_id: str, expiry_date: str, timezone: str | None = None) → str

Set an expiry date for a chat session.

When the expiry date is reached, the chat session will be automatically archived and eventually deleted after the configured grace period.

Args:

chat_session_id:: ID of the chat session to update.
expiry_date:: The expiry date as a string in ‘YYYY-MM-DD’ format.
timezone:: Optional timezone to associate with expiry date (with IANA timezone support).

async set_chat_session_keep_forever(chat_session_id: str, keep_forever: bool) → str

Set whether a chat session should be preserved from auto-archival.

When keep_forever is True, the chat session will not be subject to inactivity-based or date-based expiry, and its expiry date is cleared permanently. When set to False, the global inactivity interval is re-applied and the inactivity timer is restarted, so the chat gets a full retention period before it is considered for archival again.

Args:

chat_session_id:: ID of the chat session to update.
keep_forever:: Whether to preserve the chat session from expiry.

async set_chat_session_prompt_template(chat_session_id: str, prompt_template_id: str | None) → str

Set the prompt template for a chat_session

Args:

chat_session_id:: ID of the chat session
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.

Returns:

str: ID of the updated chat session

async set_collection_exempt_from_chat_expiry(collection_id: str, exempt: bool) → str

Set whether a collection’s chat sessions are exempt from expiry.

When exempt is True, all chat sessions in the collection will be excluded from automatic expiry regardless of their individual settings.

Args:

collection_id:: ID of the collection to update.
exempt:: Whether to exempt chat sessions from expiry.

async set_collection_expiry_date(collection_id: str, expiry_date: str | date | datetime, timezone: str | None = None) → str

Set an expiry date for a collection.

Args:

collection_id:: ID of the collection to update.
expiry_date:: Expiry as a "YYYY-MM-DD" date string, a full ISO 8601 datetime string with optional timezone offset (e.g. "2026-09-30T17:00:00-05:00"), or a datetime.date / datetime.datetime object. A date-only value resolves to midnight (00:00:00) of that day in timezone.
timezone:: Optional timezone to associate with a date-only / offset-less expiry (with IANA timezone support). Ignored for parsing when expiry_date already carries an offset, but always stored as the collection’s expiry_timezone so the expiry is displayed in this zone. Defaults to the local machine’s zone.

async set_collection_inactivity_interval(collection_id: str, inactivity_interval: int) → str

Set an inactivity interval for a collection.

Args:

collection_id:: ID of the collection to update.
inactivity_interval:: The inactivity interval as an integer number of days.

async set_collection_prompt_template(collection_id: str, prompt_template_id: str | None, strict_check: bool = False) → str

Set the prompt template for a collection

Args:

collection_id:: ID of the collection to update.
prompt_template_id:: ID of the prompt template to get the prompts from. None to delete and fall back to system defaults.
strict_check:: whether to check that the collection’s embedding model and the prompt template are optimally compatible

Returns:

str: ID of the updated collection.

async set_collection_size_limit(collection_id: str, limit: int | str) → str

Set a maximum limit on the total size of documents (sum) added to a collection. The limit is measured in bytes.

Args:

collection_id:: ID of the collection to update.
limit:: The bytes limit, possible values follow the format: 12345, “1GB”, or “1GiB”.

async set_collection_thumbnail(collection_id: str, file_path: Path, timeout: float | None = None)

Upload an image file to be set as a collection’s thumbnail.

The image file will not be considered as a collection document. Acceptable image file types include: .png, .jpg, .jpeg, .svg

Args:

collection_id:: Collection you want to add the thumbnail to.
file_path:: Path to the image file. Must include appropriate file extension.
timeout:: Amount of time in seconds to allow the request to run.

Raises:

ValueError: The file is invalid. Exception: The upload request was unsuccessful.

async set_default_prompt_template_visibility(prompt_id: str, is_visible: bool)

Updates a flag specifying whether a default prompt template is visible or hidden to users.

Once you hide a default prompt template, users will no longer be able to use this prompt template. This will also affect collections and chats that have this as a default prompt template. Once you show a default prompt template, all users will be able to see and use this prompt template.

Args:

prompt_id:: ID of the default prompt template you would like to change the visibility of.
is_visible:: Whether the default prompt template should be visible.

async set_global_configuration(key_name: str, string_value: str, can_overwrite: bool, is_public: bool, value_type: str = None) → List[GlobalConfigItem]

Set a global configuration.

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the global config.
can_overwrite:: Whether user settings can override this global setting.
is_public:: Whether users can see the value for this global setting.
value_type:: The type of the value to be set for the global config.

Returns:

List[GlobalConfigItem]: List of global configurations.

async set_role_configuration(key_name: str, role_id: str, string_value: str, value_type: str = None) → List[ConfigItem]

Set a role configuration, overrides the global configuration. Args:

role_id:
The role id you want to apply the config for.

key_name:
The name of the global config key.

string_value:
The value to be set for the config.

value_type:
The type of the value to be set for the config.

Returns:: List[ConfigItem]: List of role configurations.

async set_role_priority(role_id: str, priority: int) → UserRole

Sets the priority for a role. Args:

role_id:
String: The id of the role to set the priority for.

priority:
Int: The priority value to set for the role. ex: 100, 200, 300…etc. The lower the number, the higher the priority.

Returns:: UserRole: The updated user role with the new priority.

async set_user_configuration_for_user(key_name: str, string_value: str, user_id: str, value_type: str = None) → List[ConfigItem]

Set a user configuration for a specific user (overrides the global configuration and to be used by admins only).

Note: Both default collection size limit and inactivity interval can be disabled. To do so, pass ‘-1’ as the string_value.

Args:

key_name:: The name of the global config key.
string_value:: The value to be set for the config.
user_id:: The user id you want to apply the config for.
value_type:: The type of the value to be set for the config.

Returns:

List[ConfigItem]: List of user configurations.

async share_chat_session(chat_session_id: str, is_private: bool = False, is_frozen: bool = True, includes_artifacts: bool = False) → ChatShareUrl

Share a chat session and get a publicly accessible URL.

Args:

chat_session_id:: String id of the chat session to share.
is_private:: If True, only authenticated users can view the shared chat. If False (default), the shared chat is publicly accessible.
is_frozen:: If True (default), a snapshot of the chat is created at share time. If False, the shared chat shows live updates from the source chat.
includes_artifacts:: If True, file artifacts referenced in messages are included. If False (default), artifacts are excluded.

Returns:

ChatShareUrl: Object containing the shareable URL and relative path.

async share_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Share a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

async share_collection_with_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a collection to a group.

The permission attribute defines the level of access, and which group can access the collection, the collection_id attribute denotes the collection to be shared.

Args:

collection_id:: ID of the collection to share.
permission:: Defines the rule for sharing, i.e. permission level and group.

Returns:

ShareResponseStatus: Status of share request.

async share_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Share an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

async share_extractor_with_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share an extractor to a group.

The permission attribute defines which group can access the extractor, the extractor_id attribute denotes the extractor to be shared.

Args:

extractor_id:: ID of the extractor to share.
permission:: Defines the group for sharing with.

Returns:

ShareResponseStatus: Status of share request.

async share_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Share a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to share.
permission:: Defines the rule for sharing, i.e. permission level.

Returns:

ShareResponseStatus: Status of share request.

async share_prompt_with_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Share a prompt to a group.

Args:

prompt_id:: ID of the prompt to share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

async stop_chat(question_id: str) → Result

Immediately stop/cancel a streaming chat response.

This will immediately halt response generation, which may result in an incomplete sentence or thought. For a more graceful termination, use finish_chat instead.

Args:: question_id: The ID of the chat message/question to stop immediately.
Returns:: Result: Status of the cancel operation.
Raises:: Exception: If the user is not authorized to cancel this chat or if the operation fails.

Summarize one or more contexts using an LLM.

Effective prompt created (excluding the system prompt):
"{pre_prompt_summary}
"""
{text_context_list}
"""
{prompt_summary}"
Args:

text_context_list:
List of raw text strings to be summarized.

system_prompt:
Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto for the model default or None for h2oGPTe defaults. Defaults to ‘’ for no system prompt.

pre_prompt_summary:
Text that is prepended before the list of texts. The default can be customized per environment, but the standard default is "In order to write a concise single-paragraph or bulleted list summary, pay attention to the following text:\n"

prompt_summary:
Text that is appended after the list of texts. The default can be customized per environment, but the standard default is "Using only the text above, write a condensed and concise summary of key results (preferably as bullet points):\n"

llm:
Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Default value is to use the first model (0th index).

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:
temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 seed (int, default: 0) — The seed for the random number generator, only used if temperature > 0, seed=0 will pick a random number for each call, seed > 0 will be fixed top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction min_max_new_tokens (int, default: 512) — Minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”] guided_json (dict, default: None) — If specified, the output will follow the JSON schema guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation guided_choice (Optional[List[str]], default: None) — If specified, the output will be exactly one of the choices. Only for models that support guided generation guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation

guardrails_settings:
Guardrails Settings.

timeout:
Timeout in seconds.

kwargs:

Dictionary of kwargs to pass to h2oGPT. Not recommended, see https://github.com/h2oai/h2ogpt for source code. Valid keys:
h2ogpt_key: str = “” chat_conversation: list[tuple[str, str]] | None = None docs_ordering_type: str | None = “best_near_prompt” max_input_tokens: int = -1 docs_token_handling: str = “split_or_merge” docs_joiner: str = “

“

image_file: Union[str, list] = None

Returns:: Answer: The response text and any errors.
Raises:: TimeoutError: If response isn’t completed in timeout seconds.

async summarize_document(*args, **kwargs) → DocumentSummary

async tag_document(document_id: str, tag_name: str) → str

Adds a tag to a document.

Args:

document_id:: String id of the document to attach the tag to.
tag_name:: String representing the tag to attach.

Returns:

String: The id of the newly created tag.

async unarchive_chat_session(chat_session_id: str) → str

Restore an archived chat session to an active state.

Admin-only. Resets the session status from ‘archived’ to ‘active’, clears archived_at, and restores the inactivity interval from the current global configuration.

Args:

chat_session_id:: ID of the chat session to restore.

async unarchive_collection(collection_id: str) → str

Restore an archived collection to an active status.

Args:

collection_id:: ID of the collection to restore.

async unshare_collection(collection_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a collection to a user.

The permission attribute defined the level of access, and who can access the collection, the collection_id attribute denotes the collection to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

async unshare_collection_for_all(collection_id: str) → ShareResponseStatus

Remove sharing of a collection to all other users but the original owner.

Args:

collection_id:: ID of the collection to un-share.

ShareResponseStatus: Status of share request.

async unshare_collection_from_group(collection_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of a collection from a group.

The permission attribute defines which group to remove access from, the collection_id attribute denotes the collection to be unshared. In case of un-sharing, the GroupSharePermission’s group_id is sufficient.

Args:

collection_id:: ID of the collection to un-share.
permission:: Defines the group for which collection access is revoked.

Returns:

ShareResponseStatus: Status of share request.

async unshare_extractor(extractor_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of an extractor to a user.

The permission attribute defined the level of access, and who can access the extractor, the extractor_id attribute denotes the extractor to be shared.

In case of un-sharing, the SharePermission’s user is sufficient.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the user for which extractor access is revoked.

ShareResponseStatus: Status of share request.

async unshare_extractor_for_all(extractor_id: str) → ShareResponseStatus

Remove sharing of an extractor to all other users but the original owner.

Args:

extractor_id:: ID of the extractor to un-share.

ShareResponseStatus: Status of share request.

async unshare_extractor_from_group(extractor_id: str, permission: GroupSharePermission) → ShareResponseStatus

Remove sharing of an extractor from a group.

The permission attribute defines which group to remove access from, the extractor_id attribute denotes the extractor to be unshared.

Args:

extractor_id:: ID of the extractor to un-share.
permission:: Defines the group for which extractor access is revoked.

Returns:

ShareResponseStatus: Status of share request.

async unshare_prompt(prompt_id: str, permission: SharePermission) → ShareResponseStatus

Remove sharing of a prompt template to a user.

Args:

prompt_id:: ID of the prompt template to un-share.
permission:: Defines the user for which collection access is revoked.

ShareResponseStatus: Status of share request.

async unshare_prompt_for_all(prompt_id: str) → ShareResponseStatus

Remove sharing of a prompt template to all other users but the original owner (owner action only).

Args:

prompt_id:: ID of the prompt template to un-share.

ShareResponseStatus: Status of share request.

async unshare_prompt_from_group(prompt_id: str, permission: GroupSharePermission) → ShareResponseStatus

Unshare a prompt from a group.

Args:

prompt_id:: ID of the prompt to un-share.
permission:: Specific permissions for a group.

Returns:

ShareResponseStatus: Status of share request.

async untag_document(document_id: str, tag_name: str) → str

Removes an existing tag from a document.

Args:

document_id:: String id of the document to remove the tag from.
tag_name:: String representing the tag to remove.

Returns:

String: The id of the removed tag.

async update_admin_mcp_logo(mcp_id: str, logo_path: str) → dict

Update the logo for an admin-created builtin MCP.

Args:: mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) logo_path: Path to the logo image file to upload
Returns:: dict: Dictionary with the updated MCP details
Raises:: UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the logo file is invalid or not found
Example:: `python result = await client.update_admin_mcp_logo("my_custom_builtin", "/path/to/logo.png") print(result["logo"]) # "/file?id=...&name=logo.png" `

async update_agent_key(key_id: str, name: str | None = None, value: str | None = None, key_type: str | None = None, description: str | None = None) → dict | None

async update_agent_tool_preference(reference_value: List[str]) → None

async update_collection(collection_id: str, name: str, description: str) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:: ID of the collection to update.
name:: New name of the collection, this is required.
description:: New description of the collection, this is required.

Returns:

str: ID of the updated collection.

async update_collection_metadata(collection_id: str, collection_metadata: dict) → str

Set the new collection metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_metadata:: Dictionary containing the new collection metadata.

Returns:

str: ID of the updated collection.

async update_collection_rag_type(collection_id: str, name: str, description: str, rag_type) → str

Update the metadata for a given collection.

All variables are required. You can use h2ogpte.get_collection(<id>).name or description to get the existing values if you only want to change one or the other.

Args:

collection_id:

ID of the collection to update.

name:

New name of the collection, this is required.

description:

New description of the collection, this is required.

rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.: Requires 1 Agent call.
"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.: Requires 1 Agent call with RAG tool execution.
"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code: execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.
"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts: to answer the query. Requires 1 LLM or Agent call.
"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).: Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.
"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant: contexts from a collection for generating a response. Requires 3 LLM calls.
"rag+" Summary RAG - Like RAG, but uses more context and recursive: summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.
"all_data" All Data RAG - Like Summary RAG, but includes all document: chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

Returns:

str: ID of the updated collection.

async update_collection_settings(collection_id: str, collection_settings: dict) → str

Set the new collection settings, must be complete. Be careful not to delete any settings you want to keep.

Args:

collection_id:: ID of the collection to update.
collection_settings:: Dictionary containing the new collection settings.

Returns:

str: ID of the updated collection.

async update_collection_workspace(collection_id: str, workspace: str) → str

Update the workspace associated with a collection.

Args:

collection_id:: ID of the collection to update.
workspace:: The workspace associated with the collection.

async update_custom_agent(agent_id: str, agent_args: dict, mcp_servers_mapping: dict | None = None) → str

Updates a custom agent’s arguments.

Args:: agent_id: The ID of the agent to update agent_args: New agent arguments mcp_servers_mapping: Optional dict mapping MCP server names to tool names (or None)

Example: {“powerpoint_server”: “powerpoint_mcp_tool”, “web_search”: None}
Returns:: The updated agent ID

async update_custom_agent_tool(tool_id: str, tool_args: dict, custom_tool_path: str | None = None) → str

Updates a custom agent tool’s arguments.

When custom_tool_path is provided, this will: 1. Upload the new file to object storage 2. Delete the old file from object storage 3. Update the tool’s configuration with the new file reference

Behavior change (v1.7.5): updates are per-tool. For remote_mcp tools, a mcp_config_json payload must describe exactly one server; a payload with multiple servers now raises an error instead of silently keeping the first server and dropping the rest. Use add_custom_agent_tool to create additional tools. Updating unsupported tool_type values (e.g. api_app/oauth_app) also raises a clear error.

Args:

tool_id: The ID of the tool to update tool_args: New tool arguments custom_tool_path: Optional path to a new file to replace the existing tool file

Returns:

The updated tool ID

Raises:

HTTPError: If the remote_mcp mcp_config_json contains more than: one server, or if the tool’s tool_type does not support updates.

async update_document_metadata(document_id: str, document_metadata: dict) → str

Set the new document metadata overwriting the existing metadata. Be careful not to delete any settings you want to keep.

Args:

document_id:: ID of the document to update.
document_metadata:: Dictionary containing the new document metadata.

Returns:

str: ID of the updated document.

async update_document_name(document_id: str, name: str) → str

Update the name metadata for a given document.

Args:

document_id:: ID of the document to update.
name:: New name of the document, must include file extension.

Returns:

str: ID of the updated document.

async update_document_uri(document_id: str, uri: str) → str

Update the URI metadata for a given document.

Args:

document_id:: ID of the document to update.
uri:: New URI of the document, this is required.

Returns:

str: ID of the updated document.

async update_prompt_template(id: str, name: str, description: str | None = None, lang: str | None = None, system_prompt: str | None = None, pre_prompt_query: str | None = None, prompt_query: str | None = None, hyde_no_rag_llm_prompt_extension: str | None = None, pre_prompt_summary: str | None = None, prompt_summary: str | None = None, system_prompt_reflection: str | None = None, pre_prompt_reflection: str | None = None, prompt_reflection: str | None = None, auto_gen_description_prompt: str | None = None, auto_gen_document_summary_pre_prompt_summary: str | None = None, auto_gen_document_summary_prompt_summary: str | None = None, auto_gen_document_sample_questions_prompt: str | None = None, default_sample_questions: List[str] | None = None, image_batch_image_prompt: str | None = None, image_batch_final_prompt: str | None = None) → str

Update a prompt template

Args:

id:: String ID of the prompt template to update
name:: Name of the prompt template
description:: Description of the prompt template
lang:: Language code
system_prompt:: System Prompt
pre_prompt_query:: Text that is prepended before the contextual document chunks.
prompt_query:: Text that is appended to the beginning of the user’s message.
hyde_no_rag_llm_prompt_extension:: LLM prompt extension.
pre_prompt_summary:: Prompt that goes before each large piece of text to summarize
prompt_summary:: Prompt that goes after each large piece of text to summarize
system_prompt_reflection:: System Prompt for self-reflection
pre_prompt_reflection:: Deprecated - ignored
prompt_reflection:: Template for self-reflection, must contain two occurrences of %s for full previous prompt (including system prompt, document related context and prompts if applicable, and user prompts) and answer
auto_gen_description_prompt:: prompt to create a description of the collection.
auto_gen_document_summary_pre_prompt_summary:: pre_prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_summary_prompt_summary:: prompt_summary for summary of a freshly imported document (if enabled).
auto_gen_document_sample_questions_prompt:: prompt to create sample questions for a freshly imported document (if enabled).
default_sample_questions:: default sample questions in case there are no auto-generated sample questions.
image_batch_final_prompt:: Prompt for each image batch for vision models
image_batch_image_prompt:: Prompt to reduce all answers each image batch for vision models

Returns:

str: The ID of the updated prompt template.

async update_question_reply_feedback(reply_id: str, expected_answer: str, user_comment: str)

Update feedback for a specific answer to a question.

Args:

reply_id:: UUID of the reply.
expected_answer:: Expected answer.
user_comment:: User comment.

Returns:

None

async update_secret(secret_id: str, secret: Dict[str, Any]) → None

Update an existing secret in the SecureStore.

Args:: secret_id: The ID of the secret to update. secret: A dictionary containing the updated secret data

(the payload stored under secret_value).
Returns:: None

async update_shared_chat(shared_chat_id: str, is_private: bool | None = None, includes_artifacts: bool | None = None) → None

Update a shared chat’s settings.

Only shared chats owned by the current user can be updated.

Args:

shared_chat_id:: ID of the shared chat to update.
is_private:: If provided, update the privacy setting.
includes_artifacts:: If provided, update the artifacts inclusion setting.

async update_tag(tag_name: str, description: str, format: str) → str

Updates a tag.

Args:

tag_name:: String representing the tag to update.
description:: String describing the tag.
format:: String representing the format of the tag.

Returns:

String: The id of the updated tag.

async update_user_builtin_mcp(mcp_id: str, mcp_config: dict) → dict

Update an existing user builtin MCP configuration.

Requires the ManageLibrary permission (admins hold it by default); the catalog is curated by permission, so any holder may edit any entry.

Args:

mcp_id: The ID of the MCP to update (e.g., “my_custom_builtin”) mcp_config: Dictionary containing the updated MCP configuration.

Required fields: - name: Display name of the MCP - description: Description of what the MCP does - type: Either “oauth_app” or “api_app” - mcp_config_json: The MCP server configuration JSON

Returns:

dict: Dictionary with the updated MCP details

Raises:

UnauthorizedError: If the caller lacks the ManageLibrary permission ObjectNotFoundError: If the MCP doesn’t exist InvalidArgumentError: If the MCP config is invalid

Example:

```python mcp_config = {

“name”: “My Updated MCP”, “description”: “Updated description”, “type”: “api_app”, “mcp_config_json”: {“command”: “npx”, “args”: [“-y”, “@my/mcp-server”]}

} result = await client.update_user_builtin_mcp(“my_custom_builtin”, mcp_config) ```

async upload(file_name: str, file: Any, uri: str | None = None) → str

Upload a file to the H2OGPTE backend.

Uploaded files are not yet accessible and need to be ingested into a collection.

See Also:

ingest_uploads: Add the uploaded files to a collection. delete_upload: Delete uploaded file

Args:

file_name:: What to name the file on the server, must include file extension.
file:: File object to upload, often an opened file from with open(…) as f.
uri:: Optional - URI you would like to associate with the file.

Returns:

str: The upload id to be used in ingest jobs.

Raises:

Exception: The upload request was unsuccessful.

class h2ogpte.Session(address: str, chat_session_id: str, client: H2OGPTE = None, prompt_template_id: str | None = None, open_timeout: int = 10, close_timeout: int = 10, max_connect_retries: int = 10, connect_retry_delay: int = 0.5, connect_retry_max_delay: int = 60)

Bases: object

Create and participate in a chat session.

This is a live connection to the h2oGPTe server contained to a specific chat session on top of a single collection of documents. Users will find all questions and responses in this session in a single chat history in the UI.

See Also:

H2OGPTE.connect: To initialize a session on an existing connection.

Args:

address:: Full URL of the h2oGPTe server to connect to.
chat_session_id:: The ID of the chat session the queries should be sent to.
client:: Set to the value of H2OGPTE client object used to perform other calls to the system.

Examples:

# Example 1: Best practice, create a session using the H2OGPTE module
with h2ogpte.connect(chat_session_id) as session:
    answer1 = session.query('How many paper clips were shipped to Scranton?', timeout=10)
    answer2 = session.query('Did David Brent co-sign the contract with Initech?', timeout=10)

# Example 2: Connect and disconnect manually
session = Session(
    address=address,
    client=client,
    chat_session_id=chat_session_id
)
session.connect()
answer = session.query("Are there any dogs in the documents?")
session.disconnect()

connect()

Connect to an h2oGPTe server.

This is primarily an internal function used when users create a session using with from the H2OGPTE.connection() function.

property connection: ClientConnection

disconnect()

Disconnect from an h2oGPTe server.

This is primarily an internal function used when users create a session using with from the H2OGPTE.connection() function.

Retrieval-augmented generation for a query on a collection.

Finds a collection of chunks relevant to the query using similarity scores. Sends these and any additional instructions to an LLM.

Format of questions or imperatives:

"{pre_prompt_query}
"""
{similar_context_chunks}
"""                {prompt_query}{message}"

Args:

message:

Query or instruction from the end user to the LLM.

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks. The default can be customized per environment, but the standard default is "Pay attention and remember the information below, which will help to answer the question or imperative after the context ends.\n"

prompt_query:

Text that is appended to the beginning of the user’s message. The default can be customized per environment, but the standard default is “According to only the information in the document sources provided within the context above, “

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

pre_prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Use None or “auto” for automatic model routing, set cost_controls for detailed control over automatic routing.

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering. top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation. seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed. repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty. max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction. min_max_new_tokens (int, default: 512) — minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”]. guided_json (dict, default: None) — If specified, the output will follow the JSON schema. guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_choice (Optional[List[str]], default: None — If specified, the output will be exactly one of the choices. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. enable_vision (str, default: “auto”) - Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”]. visible_vision_models (List[str], default: [“auto”]) - Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic. images_num_max (int, default: None) — Maximum number of images to process. json_preserve_system_prompt (bool, default: None) — Whether to preserve system prompt in JSON response. client_metadata (str, default: None) — Additional metadata to send with the request. min_chars_per_yield (int, default: 1) — Minimum characters to yield in streaming response. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort. cost_controls: Optional dictionary

max_cost (float) - Sets the maximum allowed cost in USD per LLM call when doing Automatic model routing. If the estimated cost based on input and output token counts is higher than this limit, the request will fail as early as possible. max_cost_per_million_tokens (float) - Only consider models that cost less than this value in USD per million tokens when doing automatic routing. Using the max of input and output cost. model (List[str] or None) - Optional subset of models to consider when doing automatic routing. None means consider all models. willingness_to_pay (float) - Controls the willingness to pay extra for a more accurate model for every LLM call when doing automatic routing, in units of USD per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated cost divided by the increase in estimated accuracy is no more than this value divided by 10%, up to the upper limit specified above. Lower values will try to keep the cost as low as possible, higher values will approach the cost limit to increase accuracy. 0 means unlimited. willingness_to_wait (float) - Controls the willingness to wait longer for a more accurate model for every LLM call when doing automatic routing, in units of seconds per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated time divided by the increase in estimated accuracy is no more than this value divided by 10%. Lower values will try to keep the time as low as possible, higher values will take longer to increase accuracy. 0 means unlimited.

use_agent (bool, default: False) - If True, use the AI agent (with access to tools) to generate the response. agent_accuracy (str, default: “standard”) - Effort level by the agent. Only if use_agent=True. One of [“quick”, “basic”, “standard”, “maximum”]. agent_max_turns (Optional[Union[str, int]], default: “auto”) - Optional max. number of back-and-forth turns with the agent. Only if use_agent=True. Either “auto” or an integer. agent_tools (Optional[Union[str, List[str]]], default: “auto”) - Either “auto”, “all”, “any” to enable all available tools, or a specific list of tools to use. Only if use_agent=True. Get full list by calling await self._lang(“get_agent_tools_options”). agent_type (str, default: “auto”) — Type of agent to use for task processing. agent_original_files (List[str], default: None) — List of file paths for agent to process. agent_timeout (int, default: None) — Timeout in seconds for each agent turn. agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent processing. agent_min_time (int, default: 0) — Minimum time in seconds for all agent processing. final_answer_guidelines_mode (str, default: “auto”) — Mode for formatting agent final answers. Options:

auto: chooses “detailed” for now, but may later adapt

detailed: full deep_research like final answer guidelines

detailed_no_file_links: Like detailed, but without files provided to LLM for final answer so LLM doesn’t over-emphasize showing file links except what it auto-decides from chat history

detailed_no_image_links: Like detailed, but without images provided to LLM for final answer so LLM doesn’t over-emphasize showing image links except what it auto-decides from chat history

detailed_no_links: Like detailed, but without files or images provided to LLM for final answer so LLM doesn’t over-emphasize showing file or image links except what it auto-decides from chat history

file_template: Use file final_answer_guidelines_template.txt (in agent_files or original_agent_files) that has optional f-strings: agent_accuracy, new_image_files, new_non_image_files, formatted_references

raw_LLM: Bypasses final answer guidelines and just stops after own final LLM response that has no executable code.

agent_code_writer_system_message (str, default: None) — System message for agent code writer. agent_num_executable_code_blocks_limit (int, default: 1) — Maximum number of executable code blocks. agent_system_site_packages (bool, default: True) — Whether agent has access to system site packages. agent_main_model (Optional[str], default: None) — Main model to use for agent. agent_max_stream_length (Optional[int], default: None) — Maximum stream length for agent response. agent_max_memory_usage (int, default: 16*1024**3) — Maximum memory usage for agent in bytes (16GB default). agent_main_reasoning_effort (Optional[int], default: None) — Effort level for main reasoning. agent_advanced_reasoning_effort (Optional[int], default: None) — Effort level for advanced reasoning. agent_max_confidence_level (Optional[int], default: None) — Maximum confidence level for agent responses. agent_planning_forced_mode (Optional[bool], default: None) — Whether to force planning mode for agent. agent_too_soon_forced_mode (Optional[bool], default: None) — Whether to force “too soon” mode for agent. agent_critique_forced_mode (Optional[int], default: None) — Whether to force critique mode for agent. agent_query_understanding_parallel_calls (Optional[int], default: None) — Number of parallel calls for query understanding. tool_building_mode (Optional[str], default: None) — Mode for tool building configuration. agent_stream_files (bool, default: True) — Whether to stream files from agent.

self_reflection_config:

Dictionary of arguments for self-reflection, can contain the following string:string mappings:

llm_reflection: str
"gpt-4-0613" or "" to disable reflection

prompt_reflection: str
‘Here’s the prompt and the response: """Prompt:\n%s\n"""\n\n""" Response:\n%s\n"""\n\nWhat is the quality of the response for the given prompt? Respond with a score ranging from Score: 0/10 (worst) to Score: 10/10 (best), and give a brief explanation why.'

system_prompt_reflection: str
""

llm_args_reflection: str
"{}"

rag_config:

Dictionary of arguments to control RAG (retrieval-augmented-generation) types. Can contain the following key/value pairs: rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.
Requires 1 Agent call.

"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.
Requires 1 Agent call with RAG tool execution.

"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code
execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.

"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts
to answer the query. Requires 1 LLM or Agent call.

"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.

"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant
contexts from a collection for generating a response. Requires 3 LLM calls.

"rag+" Summary RAG - Like RAG, but uses more context and recursive
summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.

"all_data" All Data RAG - Like Summary RAG, but includes all document
chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

hyde_no_rag_llm_prompt_extension: str

Add this prompt to every user’s prompt, when generating answers to be used for subsequent retrieval during HyDE. Only used when rag_type is “hyde1” or “hyde2”. example: '\nKeep the answer brief, and list the 5 most relevant key words at the end.'

num_neighbor_chunks_to_include: int

Number of neighboring chunks to include for every retrieved relevant chunk. Helps to keep surrounding context together. Only enabled for rag_type “rag+”. Defaults to 1.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context for a chat with a collection. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

rag_max_chunks:

Maximum number of document chunks to retrieve for RAG. If not specified (default: -1), actual number depends on rag_type and admin configuration. Set to >0 values to enable. Can be combined with rag_min_chunk_score.

rag_min_chunk_score:

Minimum score of document chunks to retrieve for RAG. If not specified (default: 0.0), will not filter chunks by score. Set to >0 values to enable. Can be combined with rag_max_chunks.

include_chat_history:

Whether to include chat history. Includes previous questions and answers for the current chat session for each new chat request. Disable if require deterministic answers for a given question. Choices are: [“on”,”off”,”auto”,True,False]

tags:

Filter documents by tags for RAG. Can be: - List format: [“red”, “blue”] includes documents with these tags - TagFilter object: TagFilter(include=[“red”], exclude=[“blue”])

metadata_filter:

A dictionary to filter documents by metadata, from which to pull the context for RAG.

timeout:

Amount of time in seconds to allow the request to run. The default is 1000 seconds.

retries:

Amount of retries to allow the request to run when hits a network issue. The default is 3.

callback:

Function for processing partial messages, used for streaming responses to an end user.

Returns:

ChatMessage: The response text and details about the response from the LLM. For example:

ChatMessage(
    id='XXX',
    content='The information provided in the context...',
    reply_to='YYY',
    votes=0,
    created_at=datetime.datetime(2023, 10, 24, 20, 12, 34, 875026)
    type_list=[],
)

Raises:

TimeoutError: The request did not complete in time.

class h2ogpte.SessionAsync(chat_session_id: str, client: H2OGPTEAsync, prompt_template_id: str | None = None, open_timeout: int = 10, close_timeout: int = 10, max_connect_retries: int = 10, connect_retry_delay: int = 0.5, connect_retry_max_delay: int = 60)

Bases: object

Create and participate in a chat session. This is a live connection to the h2oGPTe server contained to a specific chat session on top of a single collection of documents. Users will find all questions and responses in this session in a single chat history in the UI. See Also:

H2OGPTE.connect: To initialize a session on an existing connection.

Args:

address:: Full URL of the h2oGPTe server to connect to.
api_key:: API key for authentication to the h2oGPTe server. Users can generate a key by accessing the UI and navigating to the Settings.
chat_session_id:: The ID of the chat session the queries should be sent to.
verify:: Whether to verify the server’s TLS/SSL certificate. Can be a boolean or a path to a CA bundle. Defaults to True.

Examples::

async with h2ogpte.connect(_chat_session_id) as session:

answer1 = await session.query(: ‘How many paper clips were shipped to Scranton?’

) answer2 = await session.query(

‘Did David Brent co-sign the contract with Initech?’

)

async connect()

Retrieval-augmented generation for a query on a collection. Finds a collection of chunks relevant to the query using similarity scores. Sends these and any additional instructions to an LLM. Format of questions or imperatives:

"{pre_prompt_query}
"""
{similar_context_chunks}
"""            {prompt_query}{message}"

Args:

message:

Query or instruction from the end user to the LLM.

system_prompt:

Text sent to models which support system prompts. Gives the model overall context in how to respond. Use auto or None for the model default. Defaults to ‘’ for no system prompt.

pre_prompt_query:

Text that is prepended before the contextual document chunks. The default can be customized per environment, but the standard default is "Pay attention and remember the information below, which will help to answer the question or imperative after the context ends.\n"

prompt_query:

Text that is appended to the beginning of the user’s message. The default can be customized per environment, but the standard default is “According to only the information in the document sources provided within the context above, “

image_batch_final_prompt:

Prompt for each image batch for vision models

image_batch_image_prompt:

Prompt to reduce all answers each image batch for vision models

pre_prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

prompt_summary:

Not used, use H2OGPTE.process_document to summarize.

llm:

Name or index of LLM to send the query. Use H2OGPTE.get_llms() to see all available options. Use None or “auto” for automatic model routing, set cost_controls for detailed control over automatic routing.

llm_args:

Dictionary of kwargs to pass to the llm. Valid keys:

temperature (float, default: 0) — The value used to modulate the next token probabilities. Most deterministic: 0, Most creative: 1 top_k (int, default: 1) — The number of highest probability vocabulary tokens to keep for top-k-filtering. top_p (float, default: 1.0) — If set to float < 1, only the smallest set of most probable tokens with probabilities that add up to top_p or higher are kept for generation. seed (int, default: 0) — The seed for the random number generator when sampling during generation (if temp>0 or top_k>1 or top_p<1), seed=0 picks a random seed. repetition_penalty (float, default: 1.07) — The parameter for repetition penalty. 1.0 means no penalty. max_new_tokens (int, default: 1024) — Maximum number of new tokens to generate. This limit applies to each (map+reduce) step during summarization and each (map) step during extraction. min_max_new_tokens (int, default: 512) — minimum value for max_new_tokens when auto-adjusting for content of prompt, docs, etc. response_format (str, default: “text”) — Output type, one of [“text”, “json_object”, “json_code”]. guided_json (dict, default: None) — If specified, the output will follow the JSON schema. guided_regex (str, default: “”) — If specified, the output will follow the regex pattern. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_choice (Optional[List[str]], default: None — If specified, the output will be exactly one of the choices. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_grammar (str, default: “”) — If specified, the output will follow the context free grammar. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. guided_whitespace_pattern (str, default: “”) — If specified, will override the default whitespace pattern for guided json decoding. Only for models that support guided generation: check output of get_llms() for guided_vllm flag. enable_vision (str, default: “auto”) - Controls vision mode, send images to the LLM in addition to text chunks. Only if have models that support vision, use get_vision_capable_llm_names() to see list. One of [“on”, “off”, “auto”]. visible_vision_models (List[str], default: [“auto”]) - Controls which vision model to use when processing images. Use get_vision_capable_llm_names() to see list. Must provide exactly one model. [“auto”] for automatic. images_num_max (int, default: None) — Maximum number of images to process. json_preserve_system_prompt (bool, default: None) — Whether to preserve system prompt in JSON response. client_metadata (str, default: None) — Additional metadata to send with the request. min_chars_per_yield (int, default: 1) — Minimum characters to yield in streaming response. reasoning_effort (int, default: 0) — Level of reasoning effort for the model (higher values = deeper reasoning, e.g., 10000-65000). Use for models that support chain-of-thought reasoning. 0 means no additional reasoning effort. cost_controls: Optional dictionary

max_cost (float) - Sets the maximum allowed cost in USD per LLM call when doing Automatic model routing. If the estimated cost based on input and output token counts is higher than this limit, the request will fail as early as possible. max_cost_per_million_tokens (float) - Only consider models that cost less than this value in USD per million tokens when doing automatic routing. Using the max of input and output cost. model (List[str] or None) - Optional subset of models to consider when doing automatic routing. None means consider all models. willingness_to_pay (float) - Controls the willingness to pay extra for a more accurate model for every LLM call when doing automatic routing, in units of USD per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated cost divided by the increase in estimated accuracy is no more than this value divided by 10%, up to the upper limit specified above. Lower values will try to keep the cost as low as possible, higher values will approach the cost limit to increase accuracy. 0 means unlimited. willingness_to_wait (float) - Controls the willingness to wait longer for a more accurate model for every LLM call when doing automatic routing, in units of seconds per +10% increase in accuracy. We start with the least accurate model. For each more accurate model, we accept it if the increase in estimated time divided by the increase in estimated accuracy is no more than this value divided by 10%. Lower values will try to keep the time as low as possible, higher values will take longer to increase accuracy. 0 means unlimited.

use_agent (bool, default: False) - If True, use the AI agent (with access to tools) to generate the response. agent_accuracy (str, default: “standard”) - Effort level by the agent. Only if use_agent=True. One of [“quick”, “basic”, “standard”, “maximum”]. agent_max_turns (Optional[Union[str, int]], default: “auto”) - Optional max. number of back-and-forth turns with the agent. Only if use_agent=True. Either “auto” or an integer. agent_tools (Optional[Union[str, List[str]]], default: “auto”) - Either “auto”, “all”, “any” to enable all available tools, or a specific list of tools to use. Only if use_agent=True. Get full list by calling await self._lang(“get_agent_tools_options”). agent_type (str, default: “auto”) — Type of agent to use for task processing. agent_original_files (List[str], default: None) — List of file paths for agent to process. agent_timeout (int, default: None) — Timeout in seconds for each agent turn. agent_total_timeout (int, default: 3600) — Total timeout in seconds for all agent processing. agent_min_time (int, default: 0) — Minimum time in seconds for all agent processing. final_answer_guidelines_mode (str, default: “auto”) — Mode for formatting agent final answers. Options:

auto: chooses “detailed” for now, but may later adapt

detailed: full deep_research like final answer guidelines

detailed_no_file_links: Like detailed, but without files provided to LLM for final answer so LLM doesn’t over-emphasize showing file links except what it auto-decides from chat history

detailed_no_image_links: Like detailed, but without images provided to LLM for final answer so LLM doesn’t over-emphasize showing image links except what it auto-decides from chat history

detailed_no_links: Like detailed, but without files or images provided to LLM for final answer so LLM doesn’t over-emphasize showing file or image links except what it auto-decides from chat history

file_template: Use file final_answer_guidelines_template.txt (in agent_files or original_agent_files) that has optional f-strings: agent_accuracy, new_image_files, new_non_image_files, formatted_references

raw_LLM: Bypasses final answer guidelines and just stops after own final LLM response that has no executable code.

agent_code_writer_system_message (str, default: None) — System message for agent code writer. agent_num_executable_code_blocks_limit (int, default: 1) — Maximum number of executable code blocks. agent_system_site_packages (bool, default: True) — Whether agent has access to system site packages. agent_main_model (Optional[str], default: None) — Main model to use for agent. agent_max_stream_length (Optional[int], default: None) — Maximum stream length for agent response. agent_max_memory_usage (int, default: 16*1024**3) — Maximum memory usage for agent in bytes (16GB default). agent_main_reasoning_effort (Optional[int], default: None) — Effort level for main reasoning. agent_advanced_reasoning_effort (Optional[int], default: None) — Effort level for advanced reasoning. agent_max_confidence_level (Optional[int], default: None) — Maximum confidence level for agent responses. agent_planning_forced_mode (Optional[bool], default: None) — Whether to force planning mode for agent. agent_too_soon_forced_mode (Optional[bool], default: None) — Whether to force “too soon” mode for agent. agent_critique_forced_mode (Optional[int], default: None) — Whether to force critique mode for agent. agent_query_understanding_parallel_calls (Optional[int], default: None) — Number of parallel calls for query understanding. tool_building_mode (Optional[str], default: None) — Mode for tool building configuration. agent_stream_files (bool, default: True) — Whether to stream files from agent.

self_reflection_config:

Dictionary of arguments for self-reflection, can contain the following string:string mappings:

llm_reflection: str
"gpt-4-0613" or "" to disable reflection

prompt_reflection: str
‘Here’s the prompt and the response: """Prompt:\n%s\n"""\n\n""" Response:\n%s\n"""\n\nWhat is the quality of the response for the given prompt? Respond with a score ranging from Score: 0/10 (worst) to Score: 10/10 (best), and give a brief explanation why.'

system_prompt_reflection: str
""

llm_args_reflection: str
"{}"

rag_config:

Dictionary of arguments to control RAG (retrieval-augmented-generation) types. Can contain the following key/value pairs: rag_type: str one of

"auto" Automatically select the best rag_type. "llm_only" LLM Only - Answer the query without any supporting document contexts.

Requires 1 LLM or Agent call.

"agent_only" Agent Only - Answer the query with only original files passed to agent.
Requires 1 Agent call.

"agentic_rag" Agentic RAG - Agent with RAG tool that retrieves and answers from collection.
Requires 1 Agent call with RAG tool execution.

"rlm_rag" RLM RAG - Agent programmatically analyzes documents using Python code
execution and sub-LLM calls. Best for complex multi-hop reasoning over large documents. Requires 1 Agent call.

"rag" RAG (Retrieval Augmented Generation) - Use supporting document contexts
to answer the query. Requires 1 LLM or Agent call.

"hyde1" LLM Only + RAG composite - HyDE RAG (Hypothetical Document Embedding).
Use ‘LLM Only’ response to find relevant contexts from a collection for generating a response. Requires 2 LLM calls.

"hyde2" HyDE + RAG composite - Use the ‘HyDE RAG’ response to find relevant
contexts from a collection for generating a response. Requires 3 LLM calls.

"rag+" Summary RAG - Like RAG, but uses more context and recursive
summarization to overcome LLM context limits. Keeps all retrieved chunks, puts them in order, adds neighboring chunks, then uses the summary API to get the answer. Can require several LLM calls.

"all_data" All Data RAG - Like Summary RAG, but includes all document
chunks. Uses recursive summarization to overcome LLM context limits. Can require several LLM calls.

hyde_no_rag_llm_prompt_extension: str

Add this prompt to every user’s prompt, when generating answers to be used for subsequent retrieval during HyDE. Only used when rag_type is “hyde1” or “hyde2”. example: '\nKeep the answer brief, and list the 5 most relevant key words at the end.'

num_neighbor_chunks_to_include: int

Number of neighboring chunks to include for every retrieved relevant chunk. Helps to keep surrounding context together. Only enabled for rag_type “rag+”. Defaults to 1.

meta_data_to_include:

A dictionary containing flags that indicate whether each piece of document metadata is to be included as part of the context for a chat with a collection. Default is {

“name”: True, “text”: True, “page”: True, “captions”: True, “uri”: False, “connector”: False, “original_mtime”: False, “age”: False, “score”: False,

}

rag_max_chunks:

Maximum number of document chunks to retrieve for RAG. If not specified (default: -1), actual number depends on rag_type and admin configuration. Set to >0 values to enable. Can be combined with rag_min_chunk_score.

rag_min_chunk_score:

Minimum score of document chunks to retrieve for RAG. If not specified (default: 0.0), will not filter chunks by score. Set to >0 values to enable. Can be combined with rag_max_chunks.

include_chat_history:

Whether to include chat history. Includes previous questions and answers for the current chat session for each new chat request. Disable if require deterministic answers for a given question. Choices are: [“on”,”off”,”auto”,True,False]

tags:

Filter documents by tags for RAG. Can be: - List format: [“red”, “blue”] includes documents with these tags - TagFilter object: TagFilter(include=[“red”], exclude=[“blue”])

metadata_filter:

A dictionary to filter documents by metadata, from which to pull the context for RAG.

timeout:

Amount of time in seconds to allow the request to run. The default is 1000 seconds.

retries:

Amount of retries to allow the request to run when hits a network issue. The default is 3.

callback:

Function for processing partial messages, used for streaming responses to an end user.

Returns:

ChatMessage: The response text and details about the response from the LLM. For example:

ChatMessage(
    id='XXX',
    content='The information provided in the context...',
    reply_to='YYY',
    votes=0,
    created_at=datetime.datetime(2023, 10, 24, 20, 12, 34, 875026)
    type_list=[],
)

Raises:

TimeoutError: The request did not complete in time.

property websocket: WebSocketClientProtocol

class h2ogpte.SharepointOnlineAppCredentials(tenant_name: str, client_id: str, client_secret: str, admin_enumerate_drives: bool = False)

Bases: object

Credentials for SharePoint Online app authentication.

admin_enumerate_drives: bool = False

client_id: str

client_secret: str

tenant_name: str

to_payload() → Dict[str, Any]

class h2ogpte.SharepointOnlineEntry(entry_type: Literal['site', 'drive', 'drive_by_id', 'directory', 'file'], drive_id: str | None = None, object_id: str | None = None, web_url: str | None = None, name: str | None = None)

Bases: object

A SharePoint entry to ingest.

entry_type determines which other fields are required: - "site": object_id is required. - "drive": drive_id is required. - "drive_by_id": drive_id is required. Use this for drives only

reachable by direct drive_id (OneDrive personal, M365 group drives, drives in non-discoverable sites).

"directory": drive_id and object_id are required.
"file": drive_id and object_id are required.

drive_id: str | None = None

entry_type: Literal['site', 'drive', 'drive_by_id', 'directory', 'file']

name: str | None = None

object_id: str | None = None

to_payload() → Dict[str, Any]

web_url: str | None = None

class h2ogpte.SharepointOnlineUserCredentials(user_id: str, connector_id: str | None = None)

Bases: object

Credentials for SharePoint Online OAuth (delegated) authentication.

connector_id: str | None = None

to_payload() → Dict[str, Any]

user_id: str