versions.py

Overview

The versions.py file is responsible for determining and providing the current version information of the InfiniFlow project, specifically the "ragflow" component. It implements mechanisms to retrieve version data from multiple sources including a static VERSION file or dynamically from Git tags in the source repository. This allows the application to report accurate version info during runtime, which is essential for debugging, logging, and deployment tracking.

Detailed Explanation

Global Variables

RAGFLOW_VERSION_INFO : str

• Description:
  A global cache variable initialized as "unknown". It stores the resolved version string once computed, preventing repeated file system or subprocess calls on subsequent requests.

• Usage:
  Used internally by the get_ragflow_version() function to store and return the current version.

Functions

get_ragflow_version() -> str

• Purpose:
  Returns the current version string for the ragflow component. It first tries to read from a VERSION file located relative to this script. If the file is missing, it attempts to derive version info from Git tags. It appends a "slim" or "full" suffix based on an environment variable LIGHTEN.

• Parameters:
  None

• Returns:
  str — The resolved version string.

• Behavior:

  1. Checks if RAGFLOW_VERSION_INFO is already set (not "unknown"), and returns it immediately if so (caching).

  2. Constructs an absolute path to the VERSION file located one directory level above the script.

  3. If the VERSION file exists:

     • Reads and strips its content, assigns it to RAGFLOW_VERSION_INFO.

  4. Else:

     • Calls get_closest_tag_and_count() to get the Git version description.

     • Reads the environment variable LIGHTEN (default "0").

     • Appends " slim" if LIGHTEN == 1, else " full" to the version string.

  5. Returns the version string.

• Usage Example:

  import versions
  
  version = versions.get_ragflow_version()
  print(f"Current ragflow version: {version}")
  

get_closest_tag_and_count() -> str

• Purpose:
  Retrieves the closest Git tag description relative to the current commit. Uses git describe command with specific options to get a human-readable version string.

• Parameters:
  None

• Returns:
  str — Git description string or "unknown" if the Git command fails.

• Implementation Details:

  • Runs the command:

    git describe --tags --match=v* --first-parent --always
    

    This command finds the closest tag matching the pattern v* on the first-parent lineage or returns the abbreviated commit hash if no tag is found.

  • Captures output, decodes it from bytes to UTF-8 string.

  • On any exception (e.g., not a git repository, git not installed), returns "unknown".

• Usage Example:

  import versions
  
  git_version = versions.get_closest_tag_and_count()
  print(f"Git derived version: {git_version}")
  

Important Implementation Details

• Caching:
  The version information is cached in the global RAGFLOW_VERSION_INFO variable after first retrieval to avoid repeated file I/O or subprocess calls, improving performance.

• Version source fallback:
  The code prioritizes reading from a static VERSION file for stable release info. If unavailable (e.g., during development or when running from source), it falls back to Git commands for dynamic versioning.

• Environment-based suffix:
  The version string is appended with " slim" or " full" depending on the LIGHTEN environment variable. This likely reflects different build or deployment configurations.

• Robustness:
  The Git invocation is wrapped in a try-except block to gracefully handle cases where Git is not available or the code is not in a Git repository.

Interaction with Other System Components

• The versions.py module is likely imported and used by other components of the InfiniFlow system to obtain version information, such as:

  • Logging and monitoring subsystems to annotate logs with version info.

  • Deployment scripts or health checks that verify running versions.

  • User interfaces or CLI tools that display version information on request.

• It depends on:

  • The presence of a VERSION file in the repository root (or one directory above this script).

  • Git being installed and the source code residing in a Git repository for dynamic version info.

• It does not modify any other parts of the system but serves as a utility module for version resolution.

Mermaid Class Diagram

The file contains only functions and a global variable and no classes. Thus, a flowchart of the main functions and their relationships is appropriate.

flowchart TD
    A[get_ragflow_version()] -->|Checks cache| B{RAGFLOW_VERSION_INFO != "unknown"?}
    B -- Yes --> C[Return cached version]
    B -- No --> D[Check for VERSION file]
    D -- Exists --> E[Read version from file]
    D -- Not Exists --> F[get_closest_tag_and_count()]
    F --> G[Read LIGHTEN env var]
    G --> H[Append " slim" or " full" suffix]
    E --> I[Set RAGFLOW_VERSION_INFO]
    H --> I
    I --> C
    F -.-> J[Subprocess git describe]
    J -.-> K[Return git version or "unknown"]

Summary

• versions.py provides the mechanism for retrieving the current version string of the ragflow component.

• It uses a cached global variable, reads a static VERSION file, or falls back to Git commands.

• It supports a "slim" or "full" version suffix based on environment configuration.

• The module is designed to be robust and efficient in providing version info for other parts of the InfiniFlow system.