conversation_service.py

Overview

The conversation_service.py file is a core backend module responsible for managing conversational sessions within the InfiniFlow system. It provides services to create, retrieve, update, and stream chatbot conversation data associated with specific dialogs and users. The file implements the ConversationService class to interface with the database model for conversations and defines several functions to handle generation and streaming of chatbot answers, including session management and reference data structuring.

Key functionalities include:

• Querying and paginating conversation sessions (ConversationService.get_list)

• Structuring chatbot answers with reference chunks (structure_answer)

• Handling streaming and non-streaming chatbot completions (completion and iframe_completion)

• Interaction with other system components like dialogs, API services, and chat generation logic

Classes and Functions

Class: ConversationService(CommonService)

A service class extending CommonService to provide conversation-specific database operations. It operates on the Conversation model.

Properties

• model (class attribute): set to the Conversation database model.

Methods

• get_list(dialog_id, page_number, items_per_page, orderby, desc, id, name, user_id=None)

  Retrieves a paginated and optionally filtered list of conversation sessions associated with a given dialog.

  • Parameters:

    • dialog_id (str/int): The ID of the dialog whose conversations are queried.

    • page_number (int): The page number for pagination.

    • items_per_page (int): Number of items per page.

    • orderby (str): The field by which to order results.

    • desc (bool): Whether to order descending (True) or ascending (False).

    • id (str/int): Optional filter by conversation ID.

    • name (str): Optional filter by conversation name.

    • user_id (str/int, optional): Optional filter by user ID.

  • Returns:

    • List[Dict]: A list of dictionaries representing conversation sessions.

  • Usage Example:

    conversations = ConversationService.get_list(
        dialog_id="abc123",
        page_number=1,
        items_per_page=20,
        orderby="created_at",
        desc=True,
        id=None,
        name=None,
        user_id="user456"
    )
    

Function: structure_answer(conv, ans, message_id, session_id)

Processes and structures the answer returned by the chatbot, adding metadata, references, and updating the conversation object accordingly.

• Parameters:

  • conv (Conversation or dict-like): The conversation object to update.

  • ans (dict): The answer dictionary containing at least an "answer" string and "reference".

  • message_id (str): The unique ID of the current message.

  • session_id (str): The conversation session ID.

• Returns:

  • dict: The updated answer dictionary with additional metadata.

• Implementation Details:

  • Ensures reference is a dictionary.

  • Formats the reference into chunks using chunks_format.

  • Updates or appends the assistant's message in the conversation's message list.

  • Updates the conversation's reference list.

• Usage Example:

  updated_ans = structure_answer(conv, ans, "msg123", "sess456")
  

Function: completion(tenant_id, chat_id, question, name="New session", session_id=None, stream=True, **kwargs)

Handles generation and streaming of chatbot responses for a given dialog and question.

• Parameters:

  • tenant_id (str): Tenant identifier for multi-tenancy.

  • chat_id (str): Dialog ID associated with the conversation.

  • question (str): User's question/input string.

  • name (str, optional): Name of the conversation session (default: "New session").

  • session_id (str, optional): Existing session ID or None to create new.

  • stream (bool, optional): Whether to stream the answer chunks or send as a whole (default: True).

  • **kwargs: Additional keyword arguments passed to the underlying chat function (e.g., user_id, kb_ids).

• Returns:

  • Generator yielding JSON-encoded strings representing streamed data chunks or the full answer.

• Implementation Details:

  • Validates ownership of the dialog via DialogService.

  • Creates a new conversation session if session_id is not provided, including a prologue message.

  • Appends user question and assistant placeholder messages to the conversation.

  • Calls the chat function from dialog_service to get chatbot responses.

  • Updates the conversation in the database incrementally.

  • Handles streaming responses or returns a single answer.

  • Yields structured JSON events suitable for Server-Sent Events (SSE).

• Usage Example:

  for chunk in completion(
      tenant_id="tenant1",
      chat_id="chat123",
      question="What is InfiniFlow?",
      user_id="user1"
  ):
      print(chunk)
  

Function: iframe_completion(dialog_id, question, session_id=None, stream=True, **kwargs)

Similar to completion, but tailored for iframe-based frontends or API4 conversations.

• Parameters:

  • dialog_id (str): Dialog ID.

  • question (str): User's question.

  • session_id (str, optional): Session ID.

  • stream (bool, optional): Enable streaming (default True).

  • **kwargs: Additional parameters such as user_id.

• Returns:

  • Generator yielding JSON-encoded strings for streaming or a single answer.

• Implementation Details:

  • Retrieves dialog and session via DialogService and API4ConversationService.

  • Creates new session if none exists.

  • Appends question message and prepares conversation messages to send to chat.

  • Uses chat for generating responses.

  • Updates conversation messages via API4ConversationService.

  • Yields structured streaming or single JSON responses similar to completion.

• Usage Example:

  for response in iframe_completion(
      dialog_id="dialog789",
      question="Explain the RAG model.",
      user_id="user123"
  ):
      print(response)
  

Important Implementation Details and Algorithms

• Streaming via Generators:
  Both completion and iframe_completion functions use Python generators to yield partial chatbot responses incrementally. This supports real-time streaming of answers over HTTP using Server-Sent Events (SSE) or similar streaming protocols.

• Message and Reference Management:
  The conversation messages are stored as lists of dictionaries with roles (user, assistant, system). The assistant's answers and their references are appended or updated in the conversation object. References are chunked for better display or processing using chunks_format.

• Session Management:
  New sessions are initialized with a prologue message from the dialog's prompt configuration. Session IDs are generated if not supplied, ensuring unique tracking.

• Database Interaction:
  Uses Peewee ORM models with connection context managers to query and update conversations and dialogs consistently. Updates are made incrementally as new chatbot answers are streamed.

• Chat Integration:
  The chat function from dialog_service handles the core chatbot logic, interfacing with underlying models or APIs to generate conversational answers.

Interactions with Other System Components

• DialogService:
  Used to query dialogs and validate access rights and prompt configurations.

• Conversation Model:
  Database model representing conversation sessions, messages, and references.

• API4ConversationService:
  Similar service for managing API4 conversations, used in the iframe completion function.

• Chat Function (chat from dialog_service):
  Main engine for chatbot response generation.

• Utility Functions:

  • get_uuid for generating unique session or message IDs.

  • chunks_format for formatting reference data into chunks.

• Database (DB):
  Context manager for database connection handling.

Mermaid Class Diagram

classDiagram
    class ConversationService {
        <<CommonService>>
        +model
        +get_list(dialog_id, page_number, items_per_page, orderby, desc, id, name, user_id=None)
    }

    class DialogService {
        +query(...)
        +get_by_id(...)
    }

    class API4ConversationService {
        +save(...)
        +get_by_id(...)
        +append_message(...)
    }

    class Conversation {
        +id
        +dialog_id
        +name
        +message
        +reference
        +user_id
    }

    ConversationService --> Conversation
    completion ..> DialogService : uses
    completion ..> ConversationService : uses
    iframe_completion ..> DialogService : uses
    iframe_completion ..> API4ConversationService : uses

Summary

The conversation_service.py module is a critical backend component for managing conversational chatbot sessions in the InfiniFlow platform. It facilitates session lifecycle management, message structuring, streaming of chatbot answers, and maintains synchronization between dialogs, conversations, and API services. The file is designed to provide robust, scalable interaction patterns with support for streaming responses, multi-tenant dialog ownership, and embedded iframe interactions.