realtimex-deeptutor 0.5.0.post1__py3-none-any.whl

src/api/routers/knowledge.py

@@ -0,0 +1,821 @@
+"""
+Knowledge Base API Router
+=========================
+
+Handles knowledge base CRUD operations, file uploads, and initialization.
+"""
+
+import asyncio
+from datetime import datetime
+import os
+from pathlib import Path
+import shutil
+import sys
+import traceback
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    File,
+    Form,
+    HTTPException,
+    UploadFile,
+    WebSocket,
+    WebSocketDisconnect,
+)
+from pydantic import BaseModel
+
+from src.api.utils.progress_broadcaster import ProgressBroadcaster
+from src.api.utils.task_id_manager import TaskIDManager
+from src.knowledge.add_documents import DocumentAdder
+from src.knowledge.initializer import KnowledgeBaseInitializer
+from src.knowledge.manager import KnowledgeBaseManager
+from src.knowledge.progress_tracker import ProgressStage, ProgressTracker
+from src.utils.document_validator import DocumentValidator
+from src.utils.error_utils import format_exception_message
+
+_project_root = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(_project_root))
+from src.logging import get_logger
+from src.services.config import load_config_with_main
+from src.services.llm import get_llm_config
+
+# Initialize logger with config
+project_root = Path(__file__).parent.parent.parent.parent
+config = load_config_with_main("solve_config.yaml", project_root)  # Use any config to get main.yaml
+log_dir = config.get("paths", {}).get("user_log_dir") or config.get("logging", {}).get("log_dir")
+logger = get_logger("Knowledge", level="INFO", log_dir=log_dir)
+
+router = APIRouter()
+
+# Constants for byte conversions
+BYTES_PER_GB = 1024**3
+BYTES_PER_MB = 1024**2
+
+
+def format_bytes_human_readable(size_bytes: int) -> str:
+    """Format bytes into human-readable string (GB, MB, or bytes)."""
+    if size_bytes >= BYTES_PER_GB:
+        return f"{size_bytes / BYTES_PER_GB:.1f} GB"
+    elif size_bytes >= BYTES_PER_MB:
+        return f"{size_bytes / BYTES_PER_MB:.1f} MB"
+    else:
+        return f"{size_bytes} bytes"
+
+
+_kb_base_dir = _project_root / "data" / "knowledge_bases"
+
+# Lazy initialization
+kb_manager = None
+
+
+def get_kb_manager():
+    """Get KnowledgeBaseManager instance (lazy init)"""
+    global kb_manager
+    if kb_manager is None:
+        kb_manager = KnowledgeBaseManager(base_dir=str(_kb_base_dir))
+    return kb_manager
+
+
+class KnowledgeBaseInfo(BaseModel):
+    name: str
+    is_default: bool
+    statistics: dict
+
+
+class LinkFolderRequest(BaseModel):
+    """Request model for linking a local folder to a KB."""
+
+    folder_path: str
+
+
+class LinkedFolderInfo(BaseModel):
+    """Response model for linked folder information."""
+
+    id: str
+    path: str
+    added_at: str
+    file_count: int
+
+
+async def run_initialization_task(initializer: KnowledgeBaseInitializer):
+    """Background task for knowledge base initialization"""
+    task_manager = TaskIDManager.get_instance()
+    task_id = task_manager.generate_task_id("kb_init", initializer.kb_name)
+
+    try:
+        if not initializer.progress_tracker:
+            initializer.progress_tracker = ProgressTracker(
+                initializer.kb_name, initializer.base_dir
+            )
+
+        initializer.progress_tracker.task_id = task_id
+
+        logger.info(f"[{task_id}] Initializing KB: {initializer.kb_name}")
+
+        await initializer.process_documents()
+        initializer.extract_numbered_items()
+
+        initializer.progress_tracker.update(
+            ProgressStage.COMPLETED, "Knowledge base initialization complete!", current=1, total=1
+        )
+
+        logger.success(f"[{task_id}] KB '{initializer.kb_name}' initialized")
+        task_manager.update_task_status(task_id, "completed")
+    except Exception as e:
+        error_msg = str(e)
+
+        logger.error(f"[{task_id}] KB '{initializer.kb_name}' init failed: {error_msg}")
+
+        task_manager.update_task_status(task_id, "error", error=error_msg)
+
+        if initializer.progress_tracker:
+            initializer.progress_tracker.update(
+                ProgressStage.ERROR, f"Initialization failed: {error_msg}", error=error_msg
+            )
+
+
+async def run_upload_processing_task(
+    kb_name: str,
+    base_dir: str,
+    api_key: str,
+    base_url: str,
+    uploaded_file_paths: list[str],
+    rag_provider: str = None,
+):
+    """Background task for processing uploaded files"""
+    task_manager = TaskIDManager.get_instance()
+    task_key = f"{kb_name}_upload_{len(uploaded_file_paths)}"
+    task_id = task_manager.generate_task_id("kb_upload", task_key)
+
+    progress_tracker = ProgressTracker(kb_name, Path(base_dir))
+    progress_tracker.task_id = task_id
+
+    try:
+        logger.info(f"[{task_id}] Processing {len(uploaded_file_paths)} files to KB '{kb_name}'")
+        progress_tracker.update(
+            ProgressStage.PROCESSING_DOCUMENTS,
+            f"Processing {len(uploaded_file_paths)} files...",
+            current=0,
+            total=len(uploaded_file_paths),
+        )
+
+        adder = DocumentAdder(
+            kb_name=kb_name,
+            base_dir=base_dir,
+            api_key=api_key,
+            base_url=base_url,
+            progress_tracker=progress_tracker,
+            rag_provider=rag_provider,
+        )
+
+        new_files = [Path(path) for path in uploaded_file_paths]
+        processed_files = await adder.process_new_documents(new_files)
+
+        if processed_files:
+            progress_tracker.update(
+                ProgressStage.EXTRACTING_ITEMS,
+                "Extracting numbered items...",
+                current=0,
+                total=len(processed_files),
+            )
+            adder.extract_numbered_items_for_new_docs(processed_files, batch_size=20)
+
+        adder.update_metadata(len(new_files))
+
+        progress_tracker.update(
+            ProgressStage.COMPLETED,
+            f"Successfully processed {len(processed_files)} files!",
+            current=len(processed_files),
+            total=len(processed_files),
+        )
+
+        logger.success(f"[{task_id}] Processed {len(processed_files)} files to KB '{kb_name}'")
+        task_manager.update_task_status(task_id, "completed")
+    except Exception as e:
+        error_msg = f"Upload processing failed (KB '{kb_name}'): {e}"
+        logger.error(f"[{task_id}] {error_msg}")
+
+        task_manager.update_task_status(task_id, "error", error=error_msg)
+
+        progress_tracker.update(
+            ProgressStage.ERROR, f"Processing failed: {error_msg}", error=error_msg
+        )
+
+
+@router.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    try:
+        manager = get_kb_manager()
+        config_exists = manager.config_file.exists()
+        kb_count = len(manager.list_knowledge_bases())
+        return {
+            "status": "ok",
+            "config_file": str(manager.config_file),
+            "config_exists": config_exists,
+            "base_dir": str(manager.base_dir),
+            "base_dir_exists": manager.base_dir.exists(),
+            "knowledge_bases_count": kb_count,
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e), "traceback": traceback.format_exc()}
+
+
+@router.get("/rag-providers")
+async def get_rag_providers():
+    """Get list of available RAG providers."""
+    try:
+        from src.services.rag.service import RAGService
+
+        providers = RAGService.list_providers()
+        return {"providers": providers}
+    except Exception as e:
+        logger.error(f"Error getting RAG providers: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/configs")
+async def get_all_kb_configs():
+    """Get all knowledge base configurations from centralized config file."""
+    try:
+        from src.services.config import get_kb_config_service
+
+        service = get_kb_config_service()
+        return service.get_all_configs()
+    except Exception as e:
+        logger.error(f"Error getting KB configs: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{kb_name}/config")
+async def get_kb_config(kb_name: str):
+    """Get configuration for a specific knowledge base."""
+    try:
+        from src.services.config import get_kb_config_service
+
+        service = get_kb_config_service()
+        config = service.get_kb_config(kb_name)
+        return {"kb_name": kb_name, "config": config}
+    except Exception as e:
+        logger.error(f"Error getting config for KB '{kb_name}': {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/{kb_name}/config")
+async def update_kb_config(kb_name: str, config: dict):
+    """Update configuration for a specific knowledge base."""
+    try:
+        from src.services.config import get_kb_config_service
+
+        service = get_kb_config_service()
+        service.set_kb_config(kb_name, config)
+        return {"status": "success", "kb_name": kb_name, "config": service.get_kb_config(kb_name)}
+    except Exception as e:
+        logger.error(f"Error updating config for KB '{kb_name}': {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/configs/sync")
+async def sync_configs_from_metadata():
+    """Sync all KB configurations from their metadata.json files to centralized config."""
+    try:
+        from src.services.config import get_kb_config_service
+
+        service = get_kb_config_service()
+        service.sync_all_from_metadata(_kb_base_dir)
+        return {"status": "success", "message": "Configurations synced from metadata files"}
+    except Exception as e:
+        logger.error(f"Error syncing configs: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/default")
+async def get_default_kb():
+    """Get the default knowledge base."""
+    try:
+        manager = get_kb_manager()
+        default_kb = manager.get_default()
+        return {"default_kb": default_kb}
+    except Exception as e:
+        logger.error(f"Error getting default KB: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/default/{kb_name}")
+async def set_default_kb(kb_name: str):
+    """Set the default knowledge base."""
+    try:
+        manager = get_kb_manager()
+
+        # Verify KB exists
+        if kb_name not in manager.list_knowledge_bases():
+            raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+
+        manager.set_default(kb_name)
+        return {"status": "success", "default_kb": kb_name}
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error setting default KB: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/list", response_model=list[KnowledgeBaseInfo])
+async def list_knowledge_bases():
+    """List all available knowledge bases with their details."""
+    try:
+        manager = get_kb_manager()
+        kb_names = manager.list_knowledge_bases()
+
+        logger.info(f"Found {len(kb_names)} knowledge bases: {kb_names}")
+
+        if not kb_names:
+            logger.info("No knowledge bases found, returning empty list")
+            return []
+
+        result = []
+        errors = []
+
+        for name in kb_names:
+            try:
+                info = manager.get_info(name)
+                logger.debug(f"Successfully got info for KB '{name}': {info.get('statistics', {})}")
+                result.append(
+                    KnowledgeBaseInfo(
+                        name=info["name"],
+                        is_default=info["is_default"],
+                        statistics=info.get("statistics", {}),
+                    )
+                )
+            except Exception as e:
+                error_msg = f"Error getting info for KB '{name}': {e}"
+                errors.append(error_msg)
+                logger.warning(f"{error_msg}\n{traceback.format_exc()}")
+                try:
+                    kb_dir = manager.base_dir / name
+                    if kb_dir.exists():
+                        logger.info(f"KB '{name}' directory exists, creating fallback info")
+                        result.append(
+                            KnowledgeBaseInfo(
+                                name=name,
+                                is_default=name == manager.get_default(),
+                                statistics={
+                                    "raw_documents": 0,
+                                    "images": 0,
+                                    "content_lists": 0,
+                                    "rag_initialized": False,
+                                },
+                            )
+                        )
+                except Exception as fallback_err:
+                    logger.error(f"Fallback also failed for KB '{name}': {fallback_err}")
+
+        if errors and not result:
+            error_detail = f"Failed to load knowledge bases. Errors: {'; '.join(errors)}"
+            logger.error(error_detail)
+            raise HTTPException(status_code=500, detail=error_detail)
+
+        if errors:
+            logger.warning(
+                f"Some KBs had errors, returning {len(result)} results. Errors: {errors}"
+            )
+
+        logger.info(f"Returning {len(result)} knowledge bases")
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        error_msg = f"Error listing knowledge bases: {e}"
+        logger.error(f"{error_msg}\n{traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=f"Failed to list knowledge bases: {e!s}")
+
+
+@router.get("/{kb_name}")
+async def get_knowledge_base_details(kb_name: str):
+    """Get detailed info for a specific KB."""
+    try:
+        manager = get_kb_manager()
+        return manager.get_info(kb_name)
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{kb_name}")
+async def delete_knowledge_base(kb_name: str):
+    """Delete a knowledge base."""
+    try:
+        manager = get_kb_manager()
+        success = manager.delete_knowledge_base(kb_name, confirm=True)
+        if not success:
+            raise HTTPException(status_code=400, detail="Failed to delete knowledge base")
+        logger.info(f"KB '{kb_name}' deleted")
+        return {"message": f"Knowledge base '{kb_name}' deleted successfully"}
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/{kb_name}/upload")
+async def upload_files(
+    kb_name: str,
+    background_tasks: BackgroundTasks,
+    files: list[UploadFile] = File(...),
+    rag_provider: str = Form(None),
+):
+    """Upload files to a knowledge base and process them in background."""
+    try:
+        manager = get_kb_manager()
+        kb_path = manager.get_knowledge_base_path(kb_name)
+        raw_dir = kb_path / "raw"
+        raw_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            llm_config = get_llm_config()
+            api_key = llm_config.api_key
+            base_url = llm_config.base_url
+        except ValueError as e:
+            raise HTTPException(status_code=500, detail=f"LLM config error: {e!s}")
+
+        uploaded_files = []
+        uploaded_file_paths = []
+
+        # 1. Save files and validate size during streaming
+        for file in files:
+            file_path = None
+            try:
+                # Sanitize filename first (without size validation)
+                sanitized_filename = DocumentValidator.validate_upload_safety(file.filename, None)
+                file.filename = sanitized_filename
+
+                # Save file to disk with size checking during streaming
+                file_path = raw_dir / file.filename
+                max_size = DocumentValidator.MAX_FILE_SIZE
+                written_bytes = 0
+                with open(file_path, "wb") as buffer:
+                    for chunk in iter(lambda: file.file.read(8192), b""):
+                        written_bytes += len(chunk)
+                        if written_bytes > max_size:
+                            # Format size in human-readable format
+                            size_str = format_bytes_human_readable(max_size)
+                            raise HTTPException(
+                                status_code=400,
+                                detail=f"File '{file.filename}' exceeds maximum size limit of {size_str}",
+                            )
+                        buffer.write(chunk)
+
+                # Validate with actual size (additional checks)
+                DocumentValidator.validate_upload_safety(file.filename, written_bytes)
+
+                uploaded_files.append(file.filename)
+                uploaded_file_paths.append(str(file_path))
+
+            except Exception as e:
+                # Clean up partially saved file
+                if file_path and file_path.exists():
+                    try:
+                        os.unlink(file_path)
+                    except OSError:
+                        pass
+
+                error_message = (
+                    f"Validation failed for file '{file.filename}': {format_exception_message(e)}"
+                )
+                logger.error(error_message, exc_info=True)
+                raise HTTPException(status_code=400, detail=error_message) from e
+
+        logger.info(f"Uploading {len(uploaded_files)} files to KB '{kb_name}'")
+
+        background_tasks.add_task(
+            run_upload_processing_task,
+            kb_name=kb_name,
+            base_dir=str(_kb_base_dir),
+            api_key=api_key,
+            base_url=base_url,
+            uploaded_file_paths=uploaded_file_paths,
+            rag_provider=rag_provider,
+        )
+
+        return {
+            "message": f"Uploaded {len(uploaded_files)} files. Processing in background.",
+            "files": uploaded_files,
+        }
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        # Unexpected failure (Server error)
+        formatted_error = format_exception_message(e)
+        raise HTTPException(status_code=500, detail=formatted_error) from e
+
+
+@router.post("/create")
+async def create_knowledge_base(
+    background_tasks: BackgroundTasks,
+    name: str = Form(...),
+    files: list[UploadFile] = File(...),
+    rag_provider: str = Form("raganything"),
+):
+    """Create a new knowledge base and initialize it with files."""
+    try:
+        manager = get_kb_manager()
+        if name in manager.list_knowledge_bases():
+            raise HTTPException(status_code=400, detail=f"Knowledge base '{name}' already exists")
+
+        try:
+            llm_config = get_llm_config()
+            api_key = llm_config.api_key
+            base_url = llm_config.base_url
+        except ValueError as e:
+            raise HTTPException(status_code=500, detail=f"LLM config error: {e!s}")
+
+        progress_tracker = ProgressTracker(name, _kb_base_dir)
+
+        logger.info(f"Creating KB: {name}")
+
+        progress_tracker.update(
+            ProgressStage.INITIALIZING, "Initializing knowledge base...", current=0, total=0
+        )
+
+        initializer = KnowledgeBaseInitializer(
+            kb_name=name,
+            base_dir=str(_kb_base_dir),
+            api_key=api_key,
+            base_url=base_url,
+            progress_tracker=progress_tracker,
+            rag_provider=rag_provider,
+        )
+
+        initializer.create_directory_structure()
+
+        manager = get_kb_manager()
+        if name not in manager.list_knowledge_bases():
+            logger.warning(f"KB {name} not found in config, registering manually")
+            initializer._register_to_config()
+
+        uploaded_files = []
+        for file in files:
+            file_path = initializer.raw_dir / file.filename
+            with open(file_path, "wb") as buffer:
+                shutil.copyfileobj(file.file, buffer)
+            uploaded_files.append(file.filename)
+
+        progress_tracker.update(
+            ProgressStage.PROCESSING_DOCUMENTS,
+            f"Saved {len(uploaded_files)} files, preparing to process...",
+            current=0,
+            total=len(uploaded_files),
+        )
+
+        background_tasks.add_task(run_initialization_task, initializer)
+
+        logger.success(f"KB '{name}' created, processing {len(uploaded_files)} files in background")
+
+        return {
+            "message": f"Knowledge base '{name}' created. Processing {len(uploaded_files)} files in background.",
+            "name": name,
+            "files": uploaded_files,
+        }
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to create KB: {e}")
+        logger.debug(traceback.format_exc())
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{kb_name}/progress")
+async def get_progress(kb_name: str):
+    """Get initialization progress for a knowledge base"""
+    try:
+        progress_tracker = ProgressTracker(kb_name, _kb_base_dir)
+        progress = progress_tracker.get_progress()
+
+        if progress is None:
+            return {"status": "not_started", "message": "Initialization not started"}
+
+        return progress
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/{kb_name}/progress/clear")
+async def clear_progress(kb_name: str):
+    """Clear progress file for a knowledge base (useful for stuck states)"""
+    try:
+        progress_tracker = ProgressTracker(kb_name, _kb_base_dir)
+        progress_tracker.clear()
+        return {"status": "success", "message": f"Progress cleared for {kb_name}"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.websocket("/{kb_name}/progress/ws")
+async def websocket_progress(websocket: WebSocket, kb_name: str):
+    """WebSocket endpoint for real-time progress updates"""
+    await websocket.accept()
+
+    broadcaster = ProgressBroadcaster.get_instance()
+
+    try:
+        await broadcaster.connect(kb_name, websocket)
+
+        progress_tracker = ProgressTracker(kb_name, _kb_base_dir)
+        initial_progress = progress_tracker.get_progress()
+
+        # Check if KB is already ready (has rag_storage)
+        kb_dir = _kb_base_dir / kb_name
+        rag_storage_dir = kb_dir / "rag_storage"
+        kb_is_ready = rag_storage_dir.exists() and rag_storage_dir.is_dir()
+
+        # Only send non-completed progress if KB is not ready
+        # or if progress is recent (within 5 minutes)
+        if initial_progress:
+            stage = initial_progress.get("stage")
+            timestamp = initial_progress.get("timestamp")
+
+            should_send = False
+            if stage in ["completed", "error"] or not kb_is_ready:
+                should_send = True
+            elif timestamp:
+                # Check if progress is recent
+                try:
+                    progress_time = datetime.fromisoformat(timestamp)
+                    now = datetime.now()
+                    age_seconds = (now - progress_time).total_seconds()
+                    if age_seconds < 300:  # 5 minutes
+                        should_send = True
+                except:
+                    pass
+
+            if should_send:
+                await websocket.send_json({"type": "progress", "data": initial_progress})
+
+        last_progress = initial_progress
+        last_timestamp = initial_progress.get("timestamp") if initial_progress else None
+
+        while True:
+            try:
+                try:
+                    await asyncio.wait_for(websocket.receive_text(), timeout=1.0)
+                except asyncio.TimeoutError:
+                    current_progress = progress_tracker.get_progress()
+                    if current_progress:
+                        current_timestamp = current_progress.get("timestamp")
+                        if current_timestamp != last_timestamp:
+                            await websocket.send_json(
+                                {"type": "progress", "data": current_progress}
+                            )
+                            last_progress = current_progress
+                            last_timestamp = current_timestamp
+
+                            if current_progress.get("stage") in ["completed", "error"]:
+                                await asyncio.sleep(3)
+                                break
+                    continue
+
+            except WebSocketDisconnect:
+                break
+            except Exception:
+                break
+
+    except Exception as e:
+        logger.debug(f"Progress WS error: {e}")
+        try:
+            await websocket.send_json({"type": "error", "message": str(e)})
+        except:
+            pass
+    finally:
+        await broadcaster.disconnect(kb_name, websocket)
+        try:
+            await websocket.close()
+        except:
+            pass
+
+
+@router.post("/{kb_name}/link-folder", response_model=LinkedFolderInfo)
+async def link_folder(kb_name: str, request: LinkFolderRequest):
+    """
+    Link a local folder to a knowledge base.
+
+    This allows syncing documents from a local folder (which can be
+    synced with SharePoint, Google Drive, OneLake, etc.) to the KB.
+
+    The folder path supports:
+    - Absolute paths: /Users/name/Documents or C:\\Users\\name\\Documents
+    - Home directory: ~/Documents
+    - Relative paths (resolved from server working directory)
+    """
+    try:
+        manager = get_kb_manager()
+        folder_info = manager.link_folder(kb_name, request.folder_path)
+        logger.info(f"Linked folder '{request.folder_path}' to KB '{kb_name}'")
+        return LinkedFolderInfo(**folder_info)
+    except ValueError as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            raise HTTPException(status_code=404, detail=error_msg)
+        raise HTTPException(status_code=400, detail=error_msg)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/{kb_name}/linked-folders", response_model=list[LinkedFolderInfo])
+async def get_linked_folders(kb_name: str):
+    """Get list of linked folders for a knowledge base."""
+    try:
+        manager = get_kb_manager()
+        folders = manager.get_linked_folders(kb_name)
+        return [LinkedFolderInfo(**f) for f in folders]
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/{kb_name}/linked-folders/{folder_id}")
+async def unlink_folder(kb_name: str, folder_id: str):
+    """Unlink a folder from a knowledge base."""
+    try:
+        manager = get_kb_manager()
+        success = manager.unlink_folder(kb_name, folder_id)
+        if not success:
+            raise HTTPException(status_code=404, detail=f"Folder '{folder_id}' not found")
+        logger.info(f"Unlinked folder '{folder_id}' from KB '{kb_name}'")
+        return {"message": "Folder unlinked successfully", "folder_id": folder_id}
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/{kb_name}/sync-folder/{folder_id}")
+async def sync_folder(kb_name: str, folder_id: str, background_tasks: BackgroundTasks):
+    """
+    Sync files from a linked folder to the knowledge base.
+
+    This scans the linked folder for supported documents and processes
+    any new files that haven't been added yet.
+    """
+    try:
+        manager = get_kb_manager()
+
+        # Get linked folders and find the one with matching ID
+        folders = manager.get_linked_folders(kb_name)
+        folder_info = next((f for f in folders if f["id"] == folder_id), None)
+
+        if not folder_info:
+            raise HTTPException(status_code=404, detail=f"Linked folder '{folder_id}' not found")
+
+        folder_path = folder_info["path"]
+
+        # Check for changes (new or modified files)
+        changes = manager.detect_folder_changes(kb_name, folder_id)
+        files_to_process = changes["new_files"] + changes["modified_files"]
+
+        if not files_to_process:
+            return {"message": "No new or modified files to sync", "files": [], "file_count": 0}
+
+        # Get LLM config
+        try:
+            llm_config = get_llm_config()
+            api_key = llm_config.api_key
+            base_url = llm_config.base_url
+        except ValueError as e:
+            raise HTTPException(status_code=500, detail=f"LLM config error: {e!s}")
+
+        logger.info(
+            f"Syncing {len(files_to_process)} files from folder '{folder_path}' to KB '{kb_name}'"
+        )
+
+        # NOTE: We DO NOT update sync state here anymore.
+        # It is updated in run_upload_processing_task only after successful processing.
+        # This prevents marking files as synced if processing fails (race condition fix).
+
+        # Add background task to process files
+        background_tasks.add_task(
+            run_upload_processing_task,
+            kb_name=kb_name,
+            base_dir=str(_kb_base_dir),
+            api_key=api_key,
+            base_url=base_url,
+            uploaded_file_paths=files_to_process,
+            folder_id=folder_id,  # Pass folder_id to update state on success
+        )
+
+        return {
+            "message": f"Syncing {len(files_to_process)} files from linked folder",
+            "folder_path": folder_path,
+            "new_files": changes["new_count"],
+            "modified_files": changes["modified_count"],
+            "file_count": len(files_to_process),
+        }
+    except HTTPException:
+        raise
+    except ValueError:
+        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))