🔍 Code Extractor

Flask API endpoint that returns a hierarchical document tree structure from a configured document folder, supporting lazy loading and full expansion modes for efficient navigation and search.

Purpose

This endpoint provides a REST API for retrieving the document folder structure in a tree format. It supports three modes: (1) lazy loading of immediate children only for a given path, (2) loading children of a specific subfolder path, and (3) full recursive expansion of the entire tree for search functionality. The endpoint is designed to handle large document repositories efficiently by loading only necessary portions of the tree on demand.

Source Code

def api_document_tree():
    """Get hierarchical document tree for source selection - lazy loading support"""
    import time
    start_time = time.time()
    
    # Get optional path parameter for lazy loading
    path_param = request.args.get('path', '')
    expand_all = request.args.get('expand_all', 'false').lower() == 'true'
    
    logger.info(f"[DOCUMENT_TREE] Starting tree build for path: {path_param or 'root'}, expand_all: {expand_all}")
    
    try:
        if not config.DOCUMENT_FOLDER.exists():
            logger.warning(f"[DOCUMENT_TREE] Document folder does not exist: {config.DOCUMENT_FOLDER}")
            return jsonify({
                'type': 'folder',
                'name': 'qa_docs',
                'path': '',
                'children': [],
                'message': 'Document folder does not exist yet'
            })
        
        # If expand_all is true, recursively load everything for search
        if expand_all:
            logger.info("[DOCUMENT_TREE] Building fully expanded tree for search")
            tree = build_document_tree_recursive(config.DOCUMENT_FOLDER, '')
        # Build tree for requested path (or root if no path specified)
        elif path_param:
            target_path = config.DOCUMENT_FOLDER / path_param
            if not target_path.exists() or not target_path.is_dir():
                return jsonify({'error': 'Invalid path'}), 400
            tree = build_document_tree_lazy(target_path, path_param)
        else:
            # Root level - only show immediate children (no recursion)
            tree = build_document_tree_lazy(config.DOCUMENT_FOLDER, '')
        
        elapsed = time.time() - start_time
        logger.info(f"[DOCUMENT_TREE] Tree built in {elapsed:.2f}s for path: {path_param or 'root'}")
        
        return jsonify(tree)
        
    except Exception as e:
        elapsed = time.time() - start_time
        logger.error(f"[DOCUMENT_TREE] Error after {elapsed:.2f}s: {e}")
        return jsonify({'error': str(e)}), 500

Return Value

Returns a JSON response with HTTP status code. On success (200): a tree structure object containing 'type' (folder/file), 'name', 'path', and 'children' array. May include 'message' field if document folder doesn't exist. On error (400): JSON with 'error' key for invalid paths. On error (500): JSON with 'error' key containing exception message. The tree structure is built by helper functions build_document_tree_recursive or build_document_tree_lazy.

Dependencies

• flask
• logging
• time
• pathlib
• config

Required Imports

from flask import Flask, request, jsonify
import logging
import time
from pathlib import Path
import config

Conditional/Optional Imports

These imports are only needed under specific conditions:

import time

Usage Example

# Assuming Flask app is set up with this route
# GET request to retrieve root level documents (lazy load)
curl 'http://localhost:5000/api/document-tree'

# GET request to retrieve children of specific folder
curl 'http://localhost:5000/api/document-tree?path=subfolder/nested'

# GET request to retrieve fully expanded tree for search
curl 'http://localhost:5000/api/document-tree?expand_all=true'

# Example response structure:
# {
#   'type': 'folder',
#   'name': 'qa_docs',
#   'path': '',
#   'children': [
#     {'type': 'file', 'name': 'doc1.pdf', 'path': 'doc1.pdf'},
#     {'type': 'folder', 'name': 'subfolder', 'path': 'subfolder', 'children': []}
#   ]
# }

Best Practices

• The endpoint implements lazy loading by default to handle large document repositories efficiently
• Performance timing is logged for monitoring and optimization purposes
• Path validation is performed to prevent directory traversal attacks
• The expand_all parameter should be used sparingly as it loads the entire tree structure
• Error handling returns appropriate HTTP status codes (400 for client errors, 500 for server errors)
• The function checks for document folder existence before attempting to build the tree
• Logging includes contextual information with [DOCUMENT_TREE] prefix for easier debugging
• The path parameter should be relative to config.DOCUMENT_FOLDER, not an absolute path
• Helper functions build_document_tree_recursive and build_document_tree_lazy must be implemented separately
• Consider implementing caching for frequently accessed paths to improve performance

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function api_folders 84.1% similar

  Flask API endpoint that returns a hierarchical JSON tree structure of all folders (excluding files) within the configured document folder, used for folder selection in upload interfaces.

  From: /tf/active/vicechatdev/docchat/app.py

• function build_document_tree_lazy 67.7% similar

  Builds a single-level document tree structure for lazy loading, scanning only immediate children of a target directory without recursively loading subdirectories.

  From: /tf/active/vicechatdev/docchat/app.py

• function build_document_tree_recursive 66.3% similar

  Recursively builds a complete hierarchical tree structure of documents and folders from a target directory path, filtering for supported file types and skipping hidden/cache directories.

  From: /tf/active/vicechatdev/docchat/app.py

• function api_get_document 61.7% similar

  Flask API endpoint that retrieves a specific document by ID, validates user access permissions, and returns the document data as JSON.

  From: /tf/active/vicechatdev/vice_ai/complex_app.py

• function api_list_documents_v1 61.2% similar

  Flask API endpoint that retrieves and returns a list of all documents uploaded by the currently authenticated user, including metadata such as filename, size, and creation date.

  From: /tf/active/vicechatdev/vice_ai/app.py