How diegomarzaa/pdf-ocr-obsidian works
Project Type and Overall Purpose
• This is a PDF-to-Markdown conversion pipeline that automates OCR processing on PDFs using the Mistral AI OCR API.
• It offers multiple interfaces: a hosted/local web application (using app.py along with static files and HTML templates) and a Jupyter Notebook mode for step-by-step processing.
• The project is aimed at converting PDF documents into structured markdown files with extracted images, organized following Obsidian-compatible styling.
File Structure and Architectural Clues
• Top-level Files:
• app.py serves as the entry point for the web application.
• pdf-markdown-ocr.ipynb supports the notebook mode.
• requirements.txt, .env.copy, and other configuration files indicate dependency management and environment configuration.
• Directories:
• "templates" and "static" indicate the presence of web interface components (possibly using Flask or a similar framework).
• "doc" contains usage documentation and media (like usage gifs) to illustrate how the system works.
• "venv" suggests the use of a virtual environment.
• Additional folders mentioned in the README (such as pdfs_to_process, ocr_output, and pdfs-done) indicate the workflow’s file handling and output storage components, even if they are not explicitly in the file tree.
Main Components
a. User Interfaces:
• Web Frontend: Represented by the static files (HTML/CSS/JS) in the "templates" and "static" directories.
• Jupyter Notebook Interface: Represented by pdf-markdown-ocr.ipynb for interactive use.
b. Web Application Backend:
• The app.py file serves as the backend that manages API requests from the web UI, triggers the OCR process, and handles file uploads/downloads.
c. OCR Pipeline Module:
• Embodied by the logic that reads from a source folder (e.g., pdfs_to_process), calls the Mistral AI OCR API, and processes the returned data (extracted text and images).
• Includes components for saving markdown (output.md), caching raw OCR responses (ocr_response.json), and organizing images in designated subdirectories.
d. External Service:
• Mistral AI OCR API: An external service invoked by the system for text recognition.
e. File Management:
• Input and Output Directories: pdfs_to_process for incoming PDFs, ocr_output for storing each PDF’s processed markdown and images, and pdfs-done for archiving processed PDFs.
f. Configuration & Environment Management:
• Use of environment variable files (.env) for storing API keys and other configuration parameters.
Data Flow and Interactions
• Web App Flow (Local and Hosted Web App):
• The user uploads a PDF via the web interface.
• app.py receives the PDF, then:
-> Calls the OCR processing routine that sends the document to the Mistral AI API.
-> Receives and caches the OCR response as JSON.
-> Extracts text and images, then generates a structured markdown file (output.md) and organizes images.
• The output is made available for preview/download.
• Notebook/CLI Flow:
• The notebook interacts with the same OCR processing logic.
• It scans the pdfs_to_process folder, processes each PDF via the OCR API, and writes the output to ocr_output, moving processed PDFs to pdfs-done.
Architectural Patterns and Key Tech
• The separation of concerns: Frontend (static assets and HTML templates) versus Backend (app.py and processing logic).
• Interaction with external APIs for OCR.
• Use of Python scripting for both web service and notebook based operation.