super-document-processor 0.1.3__py3-none-any.whl

super_document_processor/main.py

@@ -0,0 +1,826 @@
+import os
+import sys
+import json
+import time
+import uuid
+import logging
+import argparse
+import tempfile
+import threading
+from typing import Optional, List, Dict, Any
+
+# Ensure standard output and error support UTF-8 on Windows
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except AttributeError:
+        pass
+
+from processor import process_file, SUPPORTED_EXTENSIONS, IMAGE_EXTENSIONS, PORT, HOST
+
+logger = logging.getLogger("super_document_processor")
+
+def create_app():
+    """Dynamically import FastAPI dependencies and build the REST API application."""
+    from fastapi import FastAPI, UploadFile, File, Request, HTTPException, Response
+    from fastapi.responses import Response
+    from fastapi.middleware.cors import CORSMiddleware
+    from pydantic import BaseModel
+
+    app = FastAPI(
+        title="Super Document Processor API",
+        description="High-fidelity multi-format document parsing and chunking REST API for RAG pipelines."
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    class HealthResponse(BaseModel):
+        status: str
+        supported_extensions_count: int
+        supported_extensions: List[str]
+
+    class ProcessPathRequest(BaseModel):
+        file_path: str
+        process_images: Optional[bool] = None
+        model: Optional[str] = None
+
+    class ProcessResponse(BaseModel):
+        filename: str
+        total_chunks: int
+        chunks: List[Dict[str, Any]]
+
+    class AsyncJobSubmitResponse(BaseModel):
+        job_id: str
+        filename: str
+        status: str
+        poll_url: str
+
+    class AsyncJobStatusResponse(BaseModel):
+        job_id: str
+        filename: str
+        status: str
+        progress: int
+        created_at: float
+        completed_at: Optional[float] = None
+        total_chunks: Optional[int] = None
+        chunks: Optional[List[Dict[str, Any]]] = None
+        error: Optional[str] = None
+
+    # Resolve shared jobs storage location (supports Docker volume /data and local dev)
+    jobs_dir = os.getenv("JOBS_DIR")
+    if not jobs_dir:
+        if os.path.exists("/data") and os.access("/data", os.W_OK):
+            jobs_dir = "/data/jobs"
+        else:
+            jobs_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data", "jobs")
+    os.makedirs(jobs_dir, exist_ok=True)
+    temp_uploads_dir = os.path.join(os.path.dirname(jobs_dir), "temp_uploads")
+    os.makedirs(temp_uploads_dir, exist_ok=True)
+
+    def cleanup_old_jobs(max_age_seconds: int = 900):
+        """Auto-purge abandoned job files older than 15 minutes to prevent disk bloat."""
+        try:
+            now = time.time()
+            for fname in os.listdir(jobs_dir):
+                if fname.endswith(".json"):
+                    fpath = os.path.join(jobs_dir, fname)
+                    if os.path.isfile(fpath) and (now - os.path.getmtime(fpath)) > max_age_seconds:
+                        try:
+                            os.remove(fpath)
+                        except Exception:
+                            pass
+        except Exception:
+            pass
+
+    @app.get("/", tags=["General"])
+    def root():
+        return {
+            "service": "Super Document Processor API",
+            "health": "/health",
+            "docs": "/docs",
+            "process_sync": "/process",
+            "process_async": "/process-async",
+            "job_poll": "/jobs/{job_id}",
+            "convert_pptx": "/convert/pptx",
+            "supported_extensions_count": len(SUPPORTED_EXTENSIONS)
+        }
+
+    @app.get("/health", response_model=HealthResponse, tags=["General"])
+    def health_check():
+        return {
+            "status": "healthy",
+            "supported_extensions_count": len(SUPPORTED_EXTENSIONS),
+            "supported_extensions": sorted(list(SUPPORTED_EXTENSIONS))
+        }
+
+    @app.post(
+        "/process",
+        response_model=ProcessResponse,
+        tags=["Processing"],
+        summary="Process Document",
+        description="Unified document processing endpoint. Provide either an uploaded file (`file`) as multipart/form-data OR a server/volume file path (`file_path` as JSON or form field). Providing both or neither will return a 400 error."
+    )
+    async def process_document(request: Request):
+        content_type = request.headers.get("content-type", "").lower()
+        file_path = None
+        upload_file = None
+        process_images = None
+        model = None
+
+        if "application/json" in content_type:
+            try:
+                body = await request.json()
+            except Exception:
+                raise HTTPException(status_code=400, detail="Invalid JSON payload.")
+            file_path = body.get("file_path")
+            process_images = body.get("process_images")
+            model = body.get("model")
+        else:
+            try:
+                form = await request.form()
+            except Exception:
+                form = {}
+            raw_file = form.get("file")
+            if raw_file is not None and hasattr(raw_file, "filename") and raw_file.filename:
+                upload_file = raw_file
+            
+            raw_path = form.get("file_path")
+            if raw_path and str(raw_path).strip():
+                file_path = str(raw_path).strip()
+
+            form_proc_img = form.get("process_images")
+            if form_proc_img is not None:
+                if isinstance(form_proc_img, str):
+                    process_images = form_proc_img.lower() in ("true", "1", "yes")
+                else:
+                    process_images = bool(form_proc_img)
+            form_model = form.get("model")
+            if form_model:
+                model = str(form_model)
+
+        # Fallback to query parameters if not specified in body/form
+        if process_images is None and "process_images" in request.query_params:
+            process_images = request.query_params["process_images"].lower() in ("true", "1", "yes")
+        if not model and "model" in request.query_params:
+            model = request.query_params["model"]
+        if not file_path and not upload_file and "file_path" in request.query_params:
+            file_path = request.query_params["file_path"]
+
+        # Validate mutual exclusivity: cannot provide both
+        if upload_file and file_path:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot provide both an uploaded 'file' and a 'file_path'. Please provide only one."
+            )
+
+        # Validate presence: must provide at least one
+        if not upload_file and not file_path:
+            raise HTTPException(
+                status_code=400,
+                detail="Either an uploaded 'file' or a 'file_path' must be provided."
+            )
+
+        from starlette.concurrency import run_in_threadpool
+
+        if upload_file:
+            if not upload_file.filename:
+                raise HTTPException(status_code=400, detail="Uploaded file must have a filename.")
+            ext = os.path.splitext(upload_file.filename)[1].lower()
+            if ext not in SUPPORTED_EXTENSIONS:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Unsupported file type '{ext}'. Supported: {sorted(list(SUPPORTED_EXTENSIONS))}"
+                )
+            with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tmp:
+                tmp_path = tmp.name
+                content = await upload_file.read()
+                tmp.write(content)
+
+            try:
+                chunks = await run_in_threadpool(
+                    process_file,
+                    tmp_path,
+                    original_filename=upload_file.filename,
+                    process_images=process_images,
+                    model=model
+                )
+                return {
+                    "filename": upload_file.filename,
+                    "total_chunks": len(chunks),
+                    "chunks": chunks
+                }
+            except ValueError as e:
+                raise HTTPException(status_code=400, detail=str(e))
+            except Exception as e:
+                raise HTTPException(status_code=500, detail=f"Processing failed: {str(e)}")
+            finally:
+                if os.path.exists(tmp_path):
+                    try:
+                        os.remove(tmp_path)
+                    except Exception:
+                        pass
+        else:
+            if not os.path.exists(file_path):
+                raise HTTPException(status_code=404, detail=f"File not found: {file_path}")
+            ext = os.path.splitext(file_path)[1].lower()
+            if ext not in SUPPORTED_EXTENSIONS:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Unsupported file type '{ext}'. Supported: {sorted(list(SUPPORTED_EXTENSIONS))}"
+                )
+            try:
+                chunks = await run_in_threadpool(
+                    process_file,
+                    file_path,
+                    process_images=process_images,
+                    model=model
+                )
+                return {
+                    "filename": os.path.basename(file_path),
+                    "total_chunks": len(chunks),
+                    "chunks": chunks
+                }
+            except ValueError as e:
+                raise HTTPException(status_code=400, detail=str(e))
+            except Exception as e:
+                raise HTTPException(status_code=500, detail=f"Processing failed: {str(e)}")
+
+    @app.post("/process-path", response_model=ProcessResponse, tags=["Processing"], include_in_schema=False)
+    async def process_local_document_path_legacy(request: Request):
+        """Backward-compatible alias for /process using file_path."""
+        return await process_document(request)
+
+    @app.post("/process-async", response_model=AsyncJobSubmitResponse, tags=["Async Processing"])
+    async def process_document_async(
+        file: UploadFile = File(...),
+        process_images: Optional[bool] = None,
+        model: Optional[str] = None
+    ):
+        if not file.filename:
+            raise HTTPException(status_code=400, detail="Uploaded file must have a filename.")
+
+        ext = os.path.splitext(file.filename)[1].lower()
+        if ext not in SUPPORTED_EXTENSIONS:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unsupported file type '{ext}'. Supported: {sorted(list(SUPPORTED_EXTENSIONS))}"
+            )
+
+        job_id = str(uuid.uuid4())
+        created_at = time.time()
+        job_file = os.path.join(jobs_dir, f"{job_id}.json")
+        upload_path = os.path.join(temp_uploads_dir, f"{job_id}_{file.filename}")
+
+        # Save uploaded file to shared storage
+        with open(upload_path, "wb") as f:
+            content = await file.read()
+            f.write(content)
+
+        # Initialize job metadata on shared storage
+        initial_payload = {
+            "job_id": job_id,
+            "filename": file.filename,
+            "status": "processing",
+            "progress": 0,
+            "created_at": created_at,
+            "completed_at": None,
+            "total_chunks": None,
+            "chunks": None,
+            "error": None
+        }
+        with open(job_file, "w", encoding="utf-8") as f:
+            json.dump(initial_payload, f, ensure_ascii=False)
+
+        def _worker():
+            try:
+                chunks = process_file(
+                    upload_path,
+                    original_filename=file.filename,
+                    process_images=process_images,
+                    model=model
+                )
+                done_payload = {
+                    "job_id": job_id,
+                    "filename": file.filename,
+                    "status": "completed",
+                    "progress": 100,
+                    "created_at": created_at,
+                    "completed_at": time.time(),
+                    "total_chunks": len(chunks),
+                    "chunks": chunks,
+                    "error": None
+                }
+                tmp_job = f"{job_file}.tmp"
+                with open(tmp_job, "w", encoding="utf-8") as f:
+                    json.dump(done_payload, f, ensure_ascii=False)
+                os.replace(tmp_job, job_file)
+            except Exception as e:
+                err_payload = {
+                    "job_id": job_id,
+                    "filename": file.filename,
+                    "status": "failed",
+                    "progress": 0,
+                    "created_at": created_at,
+                    "completed_at": time.time(),
+                    "total_chunks": 0,
+                    "chunks": None,
+                    "error": str(e)
+                }
+                tmp_job = f"{job_file}.tmp"
+                with open(tmp_job, "w", encoding="utf-8") as f:
+                    json.dump(err_payload, f, ensure_ascii=False)
+                os.replace(tmp_job, job_file)
+            finally:
+                if os.path.exists(upload_path):
+                    try:
+                        os.remove(upload_path)
+                    except Exception:
+                        pass
+                cleanup_old_jobs()
+
+        threading.Thread(target=_worker, daemon=True).start()
+
+        return {
+            "job_id": job_id,
+            "filename": file.filename,
+            "status": "processing",
+            "poll_url": f"/jobs/{job_id}"
+        }
+
+    @app.get("/jobs/{job_id}", response_model=AsyncJobStatusResponse, tags=["Async Processing"])
+    def get_job_status(job_id: str):
+        job_file = os.path.join(jobs_dir, f"{job_id}.json")
+        if not os.path.exists(job_file):
+            raise HTTPException(status_code=404, detail=f"Job '{job_id}' not found.")
+        try:
+            with open(job_file, "r", encoding="utf-8") as f:
+                data = json.load(f)
+
+            # Once the client retrieves the final result (completed or failed), delete the file immediately
+            if data.get("status") in ("completed", "failed"):
+                try:
+                    os.remove(job_file)
+                except Exception:
+                    pass
+
+            return data
+        except HTTPException:
+            raise
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Failed to read job state: {str(e)}")
+
+    @app.post(
+        "/convert/pptx",
+        tags=["Conversion"],
+        summary="Convert PPTX to SVG or PNG Images",
+        description="Renders slides of a PowerPoint (.pptx) file to clean SVG or PNG images with Aspose evaluation watermarks stripped. Supports single slide streaming, JSON base64 payloads, or zip archive download."
+    )
+    async def convert_pptx_endpoint(request: Request):
+        content_type = request.headers.get("content-type", "").lower()
+        file_path = None
+        upload_file = None
+        fmt = "svg"
+        slide = None
+        scale = 2.0
+        as_zip = False
+        response_type = None
+
+        if "application/json" in content_type:
+            try:
+                body = await request.json()
+            except Exception:
+                raise HTTPException(status_code=400, detail="Invalid JSON payload.")
+            file_path = body.get("file_path")
+            fmt = body.get("format", "svg")
+            slide = body.get("slide")
+            try:
+                scale = float(body.get("scale", 2.0))
+            except (ValueError, TypeError):
+                scale = 2.0
+            as_zip = bool(body.get("as_zip", False))
+            response_type = body.get("response_type")
+        else:
+            try:
+                form = await request.form()
+            except Exception:
+                form = {}
+            raw_file = form.get("file")
+            if raw_file is not None and hasattr(raw_file, "filename") and raw_file.filename:
+                upload_file = raw_file
+            
+            raw_path = form.get("file_path")
+            if raw_path and str(raw_path).strip():
+                file_path = str(raw_path).strip()
+            
+            if form.get("format"):
+                fmt = str(form.get("format"))
+            if form.get("slide"):
+                try:
+                    slide = int(form.get("slide"))
+                except (ValueError, TypeError):
+                    pass
+            if form.get("scale"):
+                try:
+                    scale = float(form.get("scale"))
+                except (ValueError, TypeError):
+                    pass
+            if form.get("as_zip") is not None:
+                as_zip = str(form.get("as_zip")).lower() in ("true", "1", "yes")
+            if form.get("response_type"):
+                response_type = str(form.get("response_type"))
+
+        # Fallback to query parameters
+        if "format" in request.query_params:
+            fmt = request.query_params["format"]
+        if "slide" in request.query_params:
+            try:
+                slide = int(request.query_params["slide"])
+            except (ValueError, TypeError):
+                pass
+        if "scale" in request.query_params:
+            try:
+                scale = float(request.query_params["scale"])
+            except (ValueError, TypeError):
+                pass
+        if "as_zip" in request.query_params:
+            as_zip = request.query_params["as_zip"].lower() in ("true", "1", "yes")
+        if "response_type" in request.query_params:
+            response_type = request.query_params["response_type"]
+        if not file_path and not upload_file and "file_path" in request.query_params:
+            file_path = request.query_params["file_path"]
+
+        if upload_file and file_path:
+            raise HTTPException(
+                status_code=400,
+                detail="Cannot provide both an uploaded 'file' and a 'file_path'. Please provide only one."
+            )
+        if not upload_file and not file_path:
+            raise HTTPException(
+                status_code=400,
+                detail="Either an uploaded 'file' or a 'file_path' must be provided."
+            )
+
+        from starlette.concurrency import run_in_threadpool
+        try:
+            from super_document_processor.utils.pptx_converter import convert_pptx, create_pptx_render_zip
+        except ImportError:
+            from utils.pptx_converter import convert_pptx, create_pptx_render_zip
+
+        norm_fmt = "png" if fmt.lower() in ("png", "img", "image") else "svg"
+
+        pptx_source = None
+        filename = "presentation.pptx"
+
+        if upload_file:
+            if not upload_file.filename or not upload_file.filename.lower().endswith(".pptx"):
+                raise HTTPException(status_code=400, detail="Uploaded file must be a .pptx file.")
+            filename = upload_file.filename
+            content = await upload_file.read()
+            pptx_source = content
+        else:
+            if not os.path.exists(file_path):
+                raise HTTPException(status_code=404, detail=f"File not found: {file_path}")
+            if not file_path.lower().endswith(".pptx"):
+                raise HTTPException(status_code=400, detail="Target file must be a .pptx file.")
+            filename = os.path.basename(file_path)
+            pptx_source = file_path
+
+        try:
+            # 1. Download all as ZIP archive if requested
+            if as_zip:
+                zip_bytes = await run_in_threadpool(create_pptx_render_zip, pptx_source, format=norm_fmt, scale=scale)
+                base_name = os.path.splitext(filename)[0]
+                return Response(
+                    content=zip_bytes,
+                    media_type="application/zip",
+                    headers={"Content-Disposition": f'attachment; filename="{base_name}_{norm_fmt}.zip"'}
+                )
+
+            # 2. Convert PPTX
+            render_res = await run_in_threadpool(
+                convert_pptx,
+                pptx_source,
+                format=norm_fmt,
+                slide=slide,
+                scale=scale
+            )
+
+            # 3. If single slide requested and binary direct streaming is selected (default for single slide unless response_type=json)
+            if slide is not None and response_type != "json":
+                media_type = "image/svg+xml" if norm_fmt == "svg" else "image/png"
+                return Response(content=render_res["raw_bytes"], media_type=media_type)
+
+            # 4. Return clean JSON response
+            if "slides" in render_res:
+                clean_slides = []
+                for s in render_res["slides"]:
+                    item = {"slide": s["slide"], "format": s["format"]}
+                    if s["format"] == "svg":
+                        item["svg"] = s["content"]
+                    else:
+                        item["png_base64"] = s["content_base64"]
+                    clean_slides.append(item)
+                return {
+                    "filename": filename,
+                    "format": render_res["format"],
+                    "total_slides": render_res["total_slides"],
+                    "slides": clean_slides
+                }
+            else:
+                resp = {
+                    "filename": filename,
+                    "slide": render_res["slide"],
+                    "total_slides": render_res["total_slides"],
+                    "format": render_res["format"]
+                }
+                if render_res["format"] == "svg":
+                    resp["svg"] = render_res["content"]
+                else:
+                    resp["png_base64"] = render_res["content_base64"]
+                return resp
+
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"PPTX conversion failed: {str(e)}")
+
+    return app
+
+def start_server(host: Optional[str] = None, port: Optional[int] = None):
+    """Dynamically launch the FastAPI server via uvicorn."""
+    import uvicorn
+    h = host or HOST
+    p = port or PORT
+    logger.info(f"Starting Super Document Processor API on http://{h}:{p}")
+    app = create_app()
+    uvicorn.run(app, host=h, port=p)
+
+
+def __getattr__(name: str):
+    """Module-level attribute getter supporting ASGI servers (e.g. uvicorn main:app)."""
+    if name == "app":
+        global _app
+        if "_app" not in globals():
+            _app = create_app()
+        return _app
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Super Document Processor - High-fidelity multi-format document parser & chunker for RAG"
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        help="Path to the document to process (PDF, DOCX, PPTX, XLSX, images, plain text, etc.)"
+    )
+    parser.add_argument(
+        "--serve",
+        "-s",
+        action="store_true",
+        help="Start the FastAPI HTTP REST API server"
+    )
+    parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=PORT,
+        help=f"Port to listen on when in server mode (default: env PORT, if specified)"
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=HOST,
+        help="Host address to bind to when in server mode (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output raw JSON array of chunks"
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        default=None,
+        help="Path to save output (JSON or text depending on --json flag)"
+    )
+    parser.add_argument(
+        "--process-images",
+        dest="process_images",
+        action="store_true",
+        default=False,
+        help="Enable AI vision processing of embedded images and tables (default: False)"
+    )
+    parser.add_argument(
+        "--no-process-images",
+        dest="process_images",
+        action="store_false",
+        help="Explicitly disable AI vision processing of embedded images and tables"
+    )
+    parser.add_argument(
+        "--model",
+        "-m",
+        type=str,
+        default=None,
+        help="Vision model name for image and table extraction (e.g. gpt-4o, google-gemini-3-flash)"
+    )
+    parser.add_argument(
+        "--convert-pptx",
+        "-c",
+        dest="convert_pptx",
+        action="store_true",
+        default=False,
+        help="Convert PPTX slides to clean SVG or PNG images instead of text chunking"
+    )
+    parser.add_argument(
+        "--format",
+        "-f",
+        dest="format",
+        type=str,
+        default="svg",
+        choices=["svg", "png"],
+        help="Target format for PPTX slide conversion (svg or png, default: svg)"
+    )
+    parser.add_argument(
+        "--slide",
+        dest="slide",
+        type=int,
+        default=None,
+        help="1-based slide index to convert (default: all slides)"
+    )
+    parser.add_argument(
+        "--scale",
+        dest="scale",
+        type=float,
+        default=2.0,
+        help="Image resolution scale multiplier for PPTX rendering (default: 2.0)"
+    )
+    parser.add_argument(
+        "--as-zip",
+        dest="as_zip",
+        action="store_true",
+        default=False,
+        help="Bundle all converted slides into a single .zip archive file"
+    )
+
+    args = parser.parse_args()
+
+    # Mode 1: Server Mode
+    if args.serve:
+        start_server(host=args.host, port=args.port)
+        return
+
+    # Mode 2: No arguments -> print help
+    if not args.file:
+        parser.print_help()
+        print("\nSupported file extensions:")
+        print(", ".join(sorted(SUPPORTED_EXTENSIONS)))
+        sys.exit(0)
+
+    # Mode 3: File validation
+    file_path = args.file
+    if not os.path.exists(file_path):
+        print(f"Error: File not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    file_ext = os.path.splitext(file_path)[1].lower()
+
+    # Mode 4: CLI PPTX Conversion Mode
+    if args.convert_pptx:
+        if file_ext != ".pptx":
+            print(f"Error: --convert-pptx only supports .pptx files, got '{file_ext}'.", file=sys.stderr)
+            sys.exit(1)
+            
+        try:
+            from super_document_processor.utils.pptx_converter import convert_pptx, create_pptx_render_zip
+        except ImportError:
+            from utils.pptx_converter import convert_pptx, create_pptx_render_zip
+            
+        try:
+            norm_fmt = "png" if args.format.lower() in ("png", "img", "image") else "svg"
+            if args.as_zip:
+                zip_bytes = create_pptx_render_zip(file_path, format=norm_fmt, scale=args.scale)
+                out_path = args.output or f"{os.path.splitext(file_path)[0]}_{norm_fmt}.zip"
+                with open(out_path, "wb") as f:
+                    f.write(zip_bytes)
+                print(f"Saved {norm_fmt.upper()} ZIP archive to: {out_path}")
+                return
+
+            render_res = convert_pptx(file_path, format=norm_fmt, slide=args.slide, scale=args.scale)
+            
+            if args.json:
+                clean_slides = []
+                if "slides" in render_res:
+                    for s in render_res["slides"]:
+                        item = {"slide": s["slide"], "format": s["format"]}
+                        if s["format"] == "svg":
+                            item["svg"] = s["content"]
+                        else:
+                            item["png_base64"] = s["content_base64"]
+                        clean_slides.append(item)
+                    out_json = {
+                        "filename": os.path.basename(file_path),
+                        "format": render_res["format"],
+                        "total_slides": render_res["total_slides"],
+                        "slides": clean_slides
+                    }
+                else:
+                    out_json = {
+                        "filename": os.path.basename(file_path),
+                        "slide": render_res["slide"],
+                        "total_slides": render_res["total_slides"],
+                        "format": render_res["format"]
+                    }
+                    if render_res["format"] == "svg":
+                        out_json["svg"] = render_res["content"]
+                    else:
+                        out_json["png_base64"] = render_res["content_base64"]
+                output_str = json.dumps(out_json, indent=2, ensure_ascii=False)
+                if args.output:
+                    with open(args.output, "w", encoding="utf-8") as f:
+                        f.write(output_str)
+                    print(f"Results written to: {args.output}")
+                else:
+                    print(output_str)
+                return
+
+            # Saving raw files (SVG or PNG)
+            if "slides" in render_res:
+                out_dir = args.output or os.path.splitext(file_path)[0] + f"_{norm_fmt}"
+                os.makedirs(out_dir, exist_ok=True)
+                ext = "svg" if render_res["format"] == "svg" else "png"
+                for item in render_res["slides"]:
+                    slide_path = os.path.join(out_dir, f"slide_{item['slide']}.{ext}")
+                    mode = "w" if ext == "svg" else "wb"
+                    content = item["content"] if ext == "svg" else item["raw_bytes"]
+                    encoding = "utf-8" if ext == "svg" else None
+                    with open(slide_path, mode, encoding=encoding) as f:
+                        f.write(content)
+                print(f"Exported {len(render_res['slides'])} {ext.upper()} slides to directory: {out_dir}")
+            else:
+                ext = "svg" if render_res["format"] == "svg" else "png"
+                out_path = args.output or f"{os.path.splitext(file_path)[0]}_slide_{render_res['slide']}.{ext}"
+                mode = "w" if ext == "svg" else "wb"
+                content = render_res["content"] if ext == "svg" else render_res["raw_bytes"]
+                encoding = "utf-8" if ext == "svg" else None
+                with open(out_path, mode, encoding=encoding) as f:
+                    f.write(content)
+                print(f"Exported slide {render_res['slide']} to: {out_path}")
+            return
+        except Exception as e:
+            print(f"Error converting PPTX '{file_path}': {e}", file=sys.stderr)
+            sys.exit(1)
+    if file_ext in IMAGE_EXTENSIONS and not args.process_images:
+        print(f"Error: Processing image file '{os.path.basename(file_path)}' requires --process-images to be enabled.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.process_images and not args.model:
+        print("Error: --process-images requires a vision model. Please specify one using --model / -m (e.g., --model gpt-4o).", file=sys.stderr)
+        sys.exit(1)
+
+    if args.model and not args.process_images:
+        print("Error: --model was specified, but --process-images is not enabled. Add --process-images to process images/tables with vision, or remove --model.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        chunks = process_file(file_path, process_images=args.process_images, model=args.model)
+    except Exception as e:
+        print(f"Error processing file '{file_path}': {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.json:
+        output_str = json.dumps(chunks, indent=2, ensure_ascii=False)
+    else:
+        lines = [
+            f"Processed: {file_path}",
+            f"Total Chunks: {len(chunks)}",
+            "=" * 60
+        ]
+        for chunk in chunks:
+            idx = chunk.get("chunkIndex", 0)
+            name = chunk.get("filename", "")
+            content = chunk.get("content", "")
+            lines.append(f"\n--- [Chunk {idx}] ({name}) [{len(content)} chars] ---")
+            lines.append(content)
+            lines.append("-" * 60)
+        output_str = "\n".join(lines)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output_str)
+        print(f"Results written to: {args.output}")
+    else:
+        print(output_str)
+
+
+if __name__ == "__main__":
+    main()