api_service.py

Overview

The api_service.py file provides service-layer abstractions to interact with the underlying database models related to API tokens and conversational sessions within the InfiniFlow system. It primarily defines two service classes — APITokenService and API4ConversationService — which encapsulate database operations such as querying, updating, and aggregating data related to API tokens and conversations.

This file acts as a bridge between the database models and higher-level application logic, providing reusable and transaction-safe methods to manage API tokens and conversation data efficiently. It leverages the Peewee ORM for database interactions and uses a shared database connection context for executing queries.

Classes and Methods

APITokenService

A service class for managing API tokens. It extends a common base service (CommonService) and operates on the APIToken model.

Properties:

• model: Set to APIToken, representing the database model this service operates on.

Methods:

used(token: str) -> peewee.ModelUpdate

Marks an API token as used by updating its timestamp fields.

• Parameters:

  • token (str): The API token string to mark as used.

• Returns:

  • A Peewee update query object that updates the update_time and update_date fields for the specified token.

• Usage Example:

  APITokenService.used("abc123token").execute()
  

  This call updates the update_time and update_date of the token "abc123token" to the current time.

• Implementation Details:

  • Uses current_timestamp() to get the current time in a suitable format.

  • Uses datetime_format(datetime.now()) to format the date.

  • The method is wrapped with @DB.connection_context() to ensure database connection lifecycle management.

API4ConversationService

A service class managing conversational session records associated with API version 4 conversations. It extends CommonService and operates on the API4Conversation model.

Properties:

• model: Set to API4Conversation, the database model this service manages.

Methods:

get_list(dialog_id: int, tenant_id: int, page_number: int, items_per_page: int, orderby: str, desc: bool, id: int, user_id: Optional[int] = None, include_dsl: bool = True, keywords: str = "", from_date: Optional[str] = None, to_date: Optional[str] = None) -> Tuple[int, List[dict]]

Retrieves a paginated list of conversation sessions filtered by various parameters.

• Parameters:

  • dialog_id (int): The dialog/conversation ID to filter sessions.

  • tenant_id (int): The tenant ID owning the sessions (used in filtering or future extension).

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

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

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

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

  • id (int): Optional filter on a specific session ID.

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

  • include_dsl (bool, default True): Whether to include the dsl field in the results.

  • keywords (str, default empty): Keyword filter applied to the message content (case-insensitive).

  • from_date (str, optional): Filter records created on or after this date.

  • to_date (str, optional): Filter records created on or before this date.

• Returns:

  • A tuple:

    • count (int): Total number of matching records.

    • list (List[dict]): List of session records for the requested page, each as a dictionary.

• Usage Example:

  count, sessions = API4ConversationService.get_list(
      dialog_id=123,
      tenant_id=1,
      page_number=1,
      items_per_page=10,
      orderby="create_date",
      desc=True,
      id=None,
      user_id=456,
      include_dsl=False,
      keywords="hello",
      from_date="2024-01-01",
      to_date="2024-01-31"
  )
  

• Implementation Details:

  • Selects either all fields (including dsl) or all except dsl based on include_dsl.

  • Applies multiple optional filters on session ID, user ID, keywords in message, and date range.

  • Uses Peewee's fn.LOWER and contains for case-insensitive keyword search.

  • Orders results by the specified field and sort direction using a dynamic field getter.

  • Counts total matching records before pagination.

  • Applies pagination via Peewee's paginate() method.

  • Returns count and list of dictionary representations of sessions.

append_message(id: int, conversation: dict) -> int

Updates a conversation session with new message data and increments the round count.

• Parameters:

  • id (int): The ID of the conversation session to update.

  • conversation (dict): A dictionary containing fields and values to update in the conversation record.

• Returns:

  • int: Number of rows updated for the round increment operation.

• Usage Example:

  conversation_update = {"message": "New message content", "tokens": 100}
  API4ConversationService.append_message(42, conversation_update)
  

• Implementation Details:

  • Calls inherited update_by_id method to update the conversation fields.

  • Performs an atomic increment of the round field by 1.

  • Uses Peewee's update query with .where() clause on conversation ID.

stats(tenant_id: int, from_date: str, to_date: str, source: Optional[str] = None) -> List[dict]

Generates statistical aggregates of conversation sessions over a date range, optionally filtering by source.

• Parameters:

  • tenant_id (int): Tenant ID to filter dialogs.

  • from_date (str): Starting date string in YYYY-MM-DD or datetime format.

  • to_date (str): Ending date string in YYYY-MM-DD or datetime format.

  • source (str, optional): Source filter for sessions.

• Returns:

  • List[dict]: List of daily statistical summaries with the following keys:

    • dt: Date truncated to day.

    • pv: Count of sessions (page views).

    • uv: Count of distinct users (unique visitors).

    • tokens: Sum of tokens used.

    • duration: Sum of session durations.

    • round: Average number of rounds.

    • thumb_up: Sum of thumbs-up feedback.

• Usage Example:

  stats = API4ConversationService.stats(
      tenant_id=1,
      from_date="2024-01-01",
      to_date="2024-01-31",
      source="web"
  )
  

• Implementation Details:

  • Extends to_date to end of day time ("23:59:59") if only a date string is provided.

  • Joins with the Dialog table to ensure dialogs belong to the specified tenant.

  • Filters sessions by create date range and optional source.

  • Groups results by day using Peewee's truncate("day") function.

  • Uses Peewee aggregation functions (COUNT, SUM, AVG) for statistics.

  • Returns results as dictionaries.

Important Implementation Details and Algorithms

• Database Context Management:
  Every class method interacting with the database is decorated with @DB.connection_context(), ensuring proper opening and closing of database connections around the method execution. This promotes safe, transactional interactions with the database.

• Dynamic Field Selection:
  In API4ConversationService.get_list(), the inclusion or exclusion of the dsl field is dynamically handled by selecting fields from the model metadata. This optimizes queries based on whether the potentially large dsl field is needed.

• Flexible Filtering and Pagination:
  The get_list() method supports a variety of filters (by dialog, user, keywords, date ranges) and sorting options, making it versatile for UI or API consumption. Pagination is implemented using Peewee's built-in .paginate().

• Statistical Aggregation:
  The stats() method performs grouped aggregation on daily conversation data, calculating multiple metrics such as unique user counts and average rounds. This supports analytics and monitoring features in the application.

Interaction with Other Parts of the System

• Database Models:
  This service module depends on Peewee ORM models imported from api.db.db_models:

  • APIToken: Represents API tokens.

  • API4Conversation: Represents conversation sessions.

  • Dialog: Represents dialog metadata, used in joins.

• CommonService Base Class:
  Both service classes inherit from CommonService (imported from api.db.services.common_service), which likely provides shared methods such as update_by_id and common CRUD operations.

• Utility Functions:
  Uses utility functions current_timestamp and datetime_format from api.utils for consistent time formatting.

• Database Connection (DB):
  Uses the DB object to manage connection context via the @DB.connection_context() decorator, ensuring connection lifecycle management.

• Application Layer:
  These services are intended to be used by API handlers, controllers, or business logic layers that require database access for tokens and conversations.

Visual Diagram

The following Mermaid class diagram illustrates the structure of this file, showing the service classes, their inheritance from CommonService, and key methods:

classDiagram
    class CommonService {
        <<abstract>>
        +update_by_id(id, data)
        +<other common methods>()
    }
    class APITokenService {
        +model = APIToken
        +used(token)
    }
    class API4ConversationService {
        +model = API4Conversation
        +get_list(dialog_id, tenant_id, page_number, items_per_page, orderby, desc, id, user_id, include_dsl, keywords, from_date, to_date)
        +append_message(id, conversation)
        +stats(tenant_id, from_date, to_date, source)
    }
    CommonService <|-- APITokenService
    CommonService <|-- API4ConversationService

Summary

api_service.py provides robust service interfaces for managing API tokens and conversation sessions in the InfiniFlow system. It abstracts complex query logic, filtering, pagination, and aggregation into clear, reusable class methods. This design promotes clean separation between database access and application logic, facilitates maintainability, and supports scalable analytics and token management workflows.