session.py

Overview

The session.py file is a Flask-based API module within the InfiniFlow system that manages conversational sessions and completions for chatbots and agents. It provides RESTful endpoints to create, update, list, delete, and interact with chat sessions, agents, and knowledge bases. The file also supports OpenAI-like chat completions, streaming responses, and handles querying and managing user conversations, sessions, and agent states.

Key functionalities include:

Session lifecycle management for chats and agents (create, update, list, delete sessions).
Various chat completion endpoints supporting streaming and non-streaming modes.
OpenAI-compatible chat completion APIs for both chats and agents.
Support for question answering (ask_about), related question generation, and knowledge base retrieval.
Interaction with multiple backend services such as DialogService, ConversationService, UserCanvasService, and others.
Streaming responses using Server-Sent Events (SSE) for real-time chat and completion updates.
Access control and token-based authentication to ensure session and agent ownership.

Classes and Functions

The file primarily defines Flask route handler functions decorated with @manager.route and @token_required. There are no explicit classes defined within this file.

1. `create(tenant_id, chat_id)`

Route: POST /chats/<chat_id>/sessions

Creates a new chat session for a given chat (dialog).

Parameters:
- tenant_id (str): Tenant identifier extracted from token.
- chat_id (str): Identifier of the chat/dialog.
Request JSON:
- Optional name (str): Name for the new session. Defaults to "New session".
- Optional user_id (str): User identifier associated with the session.
Returns: JSON response with the created session data or error.
Usage Example:

curl -X POST https://api.example.com/chats/12345/sessions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Session", "user_id": "user_001"}'

2. `create_agent_session(tenant_id, agent_id)`

Route: POST /agents/<agent_id>/sessions

Creates a new session for an agent.

Parameters:
- tenant_id (str): Tenant ID from token.
- agent_id (str): Agent identifier.
Query Params:
- Optional user_id (str): Defaults to tenant ID.
Returns: JSON response with session data including the agent's DSL (domain-specific language) state.

3. `update(tenant_id, chat_id, session_id)`

Route: PUT /chats/<chat_id>/sessions/<session_id>

Updates attributes of an existing chat session except for messages and references.

Restrictions:
- Cannot modify message, messages, or reference.
- name must not be empty if provided.
Returns: Success or error JSON response.

4. `chat_completion(tenant_id, chat_id)`

Route: POST /chats/<chat_id>/completions

Handles chat completions for a session:

Supports streaming response (SSE) or normal JSON response.
Validates ownership and session presence.
Uses the rag_completion generator from conversation service.

5. `chat_completion_openai_like(tenant_id, chat_id)`

Route: POST /chats_openai/<chat_id>/chat/completions

OpenAI-like chat completion endpoint supporting:

Streaming and non-streaming modes.
Detailed token usage reporting.
Incremental reasoning and content streaming.
Inclusion of references and final content in last chunk.

Request JSON:

model (str): Model identifier.
messages (list): List of message dicts with roles (user, assistant, system).
stream (bool, optional): Whether to stream the response (default True).
reference (bool, optional): Whether to include reference data.

Usage Example:

See the large docstring inside the function for curl and Python OpenAI client examples.

6. `agents_completion_openai_compatibility(tenant_id, agent_id)`

Route: POST /agents_openai/<agent_id>/chat/completions

OpenAI-compatible chat completion endpoint for agents.

Similar streaming and non-streaming support.
Ensures messages have valid roles.
Uses completionOpenAI for generating responses.

7. `agent_completions(tenant_id, agent_id)`

Route: POST /agents/<agent_id>/completions

Chat completions endpoint for agents.

Supports streaming via SSE.
Collects and merges content and reference data from streamed chunks.
Returns consolidated result for non-streaming requests.

8. `list_session(tenant_id, chat_id)`

Route: GET /chats/<chat_id>/sessions

Lists sessions for a chat with pagination and filtering.

Supports filtering by id, name, user_id.
Supports ordering and descending/ascending order.
Processes message references and transforms them into an API-friendly format.

9. `list_agent_session(tenant_id, agent_id)`

Route: GET /agents/<agent_id>/sessions

Lists sessions for an agent with similar filtering and pagination as chat sessions.

10. `delete(tenant_id, chat_id)`

Route: DELETE /chats/<chat_id>/sessions

Deletes one or multiple chat sessions.

Accepts JSON body with ids list; deletes all if no ids provided.
Validates ownership and returns partial success if some deletions fail.

11. `delete_agent_session(tenant_id, agent_id)`

Route: DELETE /agents/<agent_id>/sessions

Deletes one or multiple sessions for an agent, similar to delete.

12. `ask_about(tenant_id)`

Route: POST /sessions/ask

Asks a question against specified knowledge base datasets.

Requires question (str) and dataset_ids (list) in JSON body.
Streams answers back via SSE.
Checks access permissions and dataset parsing status.

13. `related_questions(tenant_id)`

Route: POST /sessions/related_questions

Generates related search terms for a given user question.

Uses a prompt engineering approach with LLM.
Supports optional industry parameter to specialize results.
Returns a list of related search terms.

14. `chatbot_completions(dialog_id)`

Route: POST /chatbots/<dialog_id>/completions

Chatbot completion endpoint with API key validation.

Supports streaming and non-streaming.
Uses iframe_completion to generate answers.

15. `chatbots_inputs(dialog_id)`

Route: GET /chatbots/<dialog_id>/info

Fetches chatbot metadata (title, avatar, prologue) for UI rendering.

Requires API key validation.

16. `agent_bot_completions(agent_id)`

Route: POST /agentbots/<agent_id>/completions

Agent bot completion endpoint with API key validation.

Supports streaming.
Uses agent_completion for answer generation.

17. `begin_inputs(agent_id)`

Route: GET /agentbots/<agent_id>/inputs

Fetches input form components and metadata for an agent's canvas.

Requires API key validation.
Returns title, avatar, input form, prologue, and mode.

18. `ask_about_embedded()`

Route: POST /searchbots/ask

Embedded search bot question answering with API key validation.

Streams answers.
Supports optional search configuration.

19. `retrieval_test_embedded()`

Route: POST /searchbots/retrieval_test

Tests retrieval functionality against a knowledge base.

Supports filters like similarity threshold, top-k, rerank model.
Supports cross-languages and keyword extraction.
Returns ranked chunks from knowledge base.

20. `related_questions_embedded()`

Route: POST /searchbots/related_questions

Generates related questions for embedded search bots.

Supports search app configuration.
Returns list of related search terms.

21. `detail_share_embedded()`

Route: GET /searchbots/detail

Fetches detailed information about a search app.

Requires API key validation.
Validates permission.

22. `mindmap()`

Route: POST /searchbots/mindmap

Generates a mind map based on a question and knowledge base IDs.

Returns mind map structure or error.

Important Implementation Details

Authentication & Authorization: Most endpoints are protected by @token_required decorator, which ensures tenant-level access. Some endpoints validate API tokens explicitly from headers.
Streaming Responses: Uses Flask's Response with text/event-stream MIME type to stream data chunks (Server-Sent Events). This is used for chat completions and question answering to deliver incremental updates.
Reference Handling: Sessions and completions sometimes include "reference" data pointing to documents or chunks supporting generated answers. The code carefully restructures and cleans this data for API consumers.
OpenAI API Compatibility: Several endpoints implement API patterns compatible with OpenAI's chat completion API, including streaming delta chunks and token usage statistics.
DSL & Canvas: Agent sessions involve a DSL (domain-specific language) representation stored in JSON, manipulated using a Canvas class, which seems to model agent behavior or workflow.
Prompt Engineering: Related question generation and other LLM interactions use carefully crafted prompts and configurations.
Error Handling: Returns structured error responses and partial successes for batch operations.

System Interaction

DialogService: Manages dialogs/chats metadata.
ConversationService / API4ConversationService: Manages conversational sessions and message histories.
UserCanvasService: Manages agent canvases and DSL states.
KnowledgebaseService: Handles knowledge base datasets and access rights.
SearchService: Manages search app configurations.
LLMBundle: Abstraction over different LLM models for chat, embedding, reranking.
agent_completion, rag_completion, iframe_completion: Generators that produce streaming completion data for different use cases.
APIToken: Validates API keys for external clients.

These services typically interface with the database and backend AI components.

Visual Diagram

The following Mermaid class diagram summarizes the major Flask route handler functions and their relationships with key services and data entities in this file:

classDiagram
    class SessionAPI {
        +create(tenant_id, chat_id)
        +create_agent_session(tenant_id, agent_id)
        +update(tenant_id, chat_id, session_id)
        +chat_completion(tenant_id, chat_id)
        +chat_completion_openai_like(tenant_id, chat_id)
        +agents_completion_openai_compatibility(tenant_id, agent_id)
        +agent_completions(tenant_id, agent_id)
        +list_session(tenant_id, chat_id)
        +list_agent_session(tenant_id, agent_id)
        +delete(tenant_id, chat_id)
        +delete_agent_session(tenant_id, agent_id)
        +ask_about(tenant_id)
        +related_questions(tenant_id)
        +chatbot_completions(dialog_id)
        +chatbots_inputs(dialog_id)
        +agent_bot_completions(agent_id)
        +begin_inputs(agent_id)
        +ask_about_embedded()
        +retrieval_test_embedded()
        +related_questions_embedded()
        +detail_share_embedded()
        +mindmap()
    }

    class DialogService
    class ConversationService
    class API4ConversationService
    class UserCanvasService
    class KnowledgebaseService
    class SearchService
    class LLMBundle
    class APIToken

    SessionAPI --> DialogService : uses
    SessionAPI --> ConversationService : uses
    SessionAPI --> API4ConversationService : uses
    SessionAPI --> UserCanvasService : uses
    SessionAPI --> KnowledgebaseService : uses
    SessionAPI --> SearchService : uses
    SessionAPI --> LLMBundle : uses
    SessionAPI --> APIToken : validates

Summary

session.py is a core API module managing chat and agent conversational sessions in InfiniFlow. It covers session CRUD, chat completions with streaming, OpenAI-compatible interfaces, knowledge base querying, and auxiliary utilities for related questions and mind maps. It orchestrates multiple backend services and enforces security and ownership via token validation. The file is designed for scalability and supports real-time streaming interactions to provide responsive AI-powered chat experiences.

End of Documentation for session.py

session.py

Overview

Classes and Functions

1. create(tenant_id, chat_id)

2. create_agent_session(tenant_id, agent_id)

3. update(tenant_id, chat_id, session_id)

4. chat_completion(tenant_id, chat_id)

5. chat_completion_openai_like(tenant_id, chat_id)

6. agents_completion_openai_compatibility(tenant_id, agent_id)

7. agent_completions(tenant_id, agent_id)

8. list_session(tenant_id, chat_id)

9. list_agent_session(tenant_id, agent_id)

10. delete(tenant_id, chat_id)

11. delete_agent_session(tenant_id, agent_id)

12. ask_about(tenant_id)

13. related_questions(tenant_id)

14. chatbot_completions(dialog_id)

15. chatbots_inputs(dialog_id)

16. agent_bot_completions(agent_id)

17. begin_inputs(agent_id)

18. ask_about_embedded()

19. retrieval_test_embedded()

20. related_questions_embedded()

21. detail_share_embedded()

22. mindmap()