chat.py

Overview

The chat.py file is a Flask-based REST API controller module responsible for managing chat assistant entities within the InfiniFlow platform. It provides endpoints to create, update, delete, and list chat assistants (chats) scoped per tenant (user or organization).

The chats represent conversational assistants configured with knowledge bases (datasets), LLM models, prompt templates, and various operational parameters. This module handles the validation, persistence, and retrieval of chat configurations by interacting with several backend services and enforcing tenant-based access control.

Detailed Component Documentation

Routes Summary

HTTP Method	Endpoint	Function	Description
POST	`/chats`	`create`	Create a new chat assistant
PUT	`/chats/<chat_id>`	`update`	Update an existing chat assistant
DELETE	`/chats`	`delete`	Delete one or more chat assistants
GET	`/chats`	`list_chat`	List chats with optional filters

Functions

`create(tenant_id)`

Create a new chat assistant for the specified tenant.

Parameters:

tenant_id (str): The identifier of the tenant making the request (extracted from token).

Request Body (JSON):

name (str, required): Name of the chat assistant.
dataset_ids (List[str], optional): List of dataset (knowledge base) IDs associated with the chat.
llm (dict, optional): LLM model configuration, e.g., {"model_name": "some_llm_model"}.
prompt (dict, optional): Prompt configuration including keys like parameters, prologue, system, etc.
description, avatar, top_n, top_k, rerank_id, and additional chat configuration fields.

Returns:

JSON response with created chat details on success.
Error response if validation fails.

Functionality:

Validates dataset ownership and ensures datasets have parsed content.
Checks that all datasets use the same embedding model.
Validates and extracts the LLM model information.
Retrieves tenant info and defaults missing prompt parameters.
Validates prompt parameters usage.
Generates a unique UUID for the chat.
Prevents duplicate chat names within the tenant.
Saves the chat configuration via DialogService.
Formats the response by renaming certain keys to user-friendly aliases.
Returns the chat configuration as JSON.

Usage Example:

POST /chats
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "SupportAssistant",
  "dataset_ids": ["dataset1", "dataset2"],
  "llm": {"model_name": "gpt-4"},
  "prompt": {
    "system": "You are a helpful assistant...",
    "parameters": [{"key": "knowledge", "optional": false}]
  }
}

`update(tenant_id, chat_id)`

Update an existing chat assistant for the specified tenant.

Parameters:

tenant_id (str): Tenant identifier from token.
chat_id (str): ID of the chat assistant to update.

Request Body (JSON):

Fields to update, such as name, dataset_ids, llm, prompt, avatar, etc.

Returns:

Success JSON response if updated.
Error response if chat not found, ownership invalid, or validation fails.

Functionality:

Validates tenant ownership of the chat.
Validates dataset ownership and parsing if datasets are updated.
Validates consistent embedding models across datasets.
Validates LLM model existence.
Updates prompt configuration with proper key mappings.
Checks for duplicate chat names.
Merges new prompt and LLM settings with existing ones.
Updates the chat entry in the database.
Returns success or error accordingly.

`delete(tenant_id)`

Delete one or multiple chat assistants of the tenant.

Parameters:

tenant_id (str): Tenant identifier.

Request Body (JSON):

ids (List[str], optional): List of chat IDs to delete. If omitted, deletes all chats owned by tenant.

Returns:

Success response with count of deleted chats and any error messages.
Error response if no valid chat IDs found or if no deletion performed.

Functionality:

Retrieves the list of chat IDs to delete.
Checks duplicates and ownership.
Marks chats as invalid (soft delete) by updating status.
Returns partial success if some deletions fail.

`list_chat(tenant_id)`

Retrieve a paginated list of chat assistants for the tenant with optional filters.

Parameters (Query String):

id (str, optional): Filter by chat ID.
name (str, optional): Filter by chat name.
page (int, optional, default=1): Page number.
page_size (int, optional, default=30): Number of items per page.
orderby (str, optional, default='create_time'): Field to order by.
desc (bool, optional, default=True): Descending order flag.

Returns:

JSON list of chat assistants with detailed configuration and associated datasets.

Functionality:

Queries chats owned by tenant with filters.
For each chat, formats prompt keys for client friendliness.
Retrieves dataset details for each chat.
Returns paginated results.

Important Implementation Details and Algorithms

Ownership Validation: For datasets and chats, the module validates tenant ownership before proceeding with any operation to enforce access control.
Embedding Model Consistency: When multiple datasets are linked to a chat, it ensures all use the same embedding model to avoid model incompatibility.
Parameter Key Mapping: Converts internal prompt configuration keys (system, prologue, parameters, etc.) to more user-friendly names (prompt, opener, variables) to simplify client-side interaction.
Soft Delete: Chat deletions update the status to INVALID rather than hard deleting records, allowing potential recovery or audit.
Prompt Parameter Validation: Checks if all required parameters (non-optional) are actually referenced in the prompt template to prevent misconfiguration.
Rerank Model Validation: Validates rerank model IDs against a whitelist or tenant-registered models.

Interaction with Other Parts of the System

Services:
- DialogService: Core service for CRUD operations on chat assistant data.
- KnowledgebaseService: Used to validate and fetch dataset information.
- TenantLLMService: Manages tenant-specific LLM and embedding model information.
- TenantService: Retrieves tenant (user/organization) information.
Utilities:
- get_uuid(): Generates unique identifiers for chats.
- get_result(), get_error_data_result(): Standardize API response formats.
- check_duplicate_ids(): Utility to validate duplicate IDs in bulk deletion.
Security:
- Decorator token_required: Ensures API endpoints are secured and requests carry valid authorization tokens.
Settings:
- Uses settings.RetCode.AUTHENTICATION_ERROR for certain error codes.

Visual Diagram

Below is a Mermaid class diagram illustrating the main functions and their relationships to external services and key data components within chat.py.

classDiagram
    class chat {
        +create(tenant_id)
        +update(tenant_id, chat_id)
        +delete(tenant_id)
        +list_chat(tenant_id)
    }

    class DialogService {
        +query(...)
        +save(...)
        +update_by_id(...)
        +get_by_id(...)
        +get_list(...)
    }

    class KnowledgebaseService {
        +accessible(...)
        +query(...)
        +get_by_ids(...)
    }

    class TenantLLMService {
        +split_model_name_and_factory(...)
        +query(...)
    }

    class TenantService {
        +get_by_id(...)
    }

    class Utils {
        +get_uuid()
        +check_duplicate_ids(...)
        +get_result(...)
        +get_error_data_result(...)
    }

    chat --> DialogService : uses
    chat --> KnowledgebaseService : uses
    chat --> TenantLLMService : uses
    chat --> TenantService : uses
    chat --> Utils : uses

Summary

The chat.py file is a critical API controller facilitating tenant-scoped management of chat assistants. It ensures data consistency, ownership validation, and proper configuration of LLM and knowledge base integrations through well-defined REST endpoints. The module integrates tightly with backend services managing chats, datasets, tenant LLM models, and tenant metadata, providing a secure and robust interface for client applications to manage chat assistants effectively.