guide

description: Guidelines for using llm-food globs: alwaysApply: true

The llm-food project is a Python-based service designed for converting various document formats (including PDF, DOCX, RTF, PPTX, HTML) into Markdown. It provides both synchronous and asynchronous processing capabilities, exposed through a FastAPI-based RESTful API (FastAPIServerEndpoints).

Key functionalities include:

• Synchronous Conversion: The /convert endpoint handles on-demand conversion of single files or URLs. This is managed by the SynchronousConversionService, which dynamically selects processing logic based on file type. For PDFs, it employs a configurable PDFProcessingStrategy, allowing users to choose between backends like Google Gemini, pymupdf4llm, or pypdf2 via an environment variable. This demonstrates the Strategy design pattern for flexible PDF handling.
• Asynchronous Batch Processing: The /batch endpoint, managed by the BatchJobOrchestrator, processes multiple files. It intelligently routes PDFs to Google's Gemini Batch Prediction API for scalable OCR and other formats to server-side FastAPI background tasks.
• State Management: Asynchronous job states, including individual file progress and Gemini sub-job details, are persisted in a local DuckDB database (TaskStateRepository). This ensures reliability for long-running tasks.
• API and Data Handling: FastAPIServerEndpoints act as Controllers, orchestrating calls to services. Pydantic models (APIDataModels) are extensively used as Data Transfer Objects (DTOs) for request/response validation and serialization, ensuring type safety. Optional API authentication is supported via Bearer tokens.
• Client Interaction: An asynchronous Python client library (LLMFoodClient), built with httpx, provides a Facade for easy programmatic interaction with the server's API. This client also powers the project's Command Line Interface (CLI).

The architecture emphasizes separation of concerns, with distinct abstractions for API handling, conversion logic, batch orchestration, and persistence. It leverages external services like Google Cloud Storage (GCS) for temporary file storage during batch PDF processing and the Google Gemini API for its advanced OCR capabilities. Configuration is managed through environment variables.

Source Repository: None

## Chapters

[FastAPIServerEndpoints](fastapiserverendpoints.mdc)
[APIDataModels (Pydantic)](apidatamodels__pydantic_.mdc)
[LLMFoodClient](llmfoodclient.mdc)
[SynchronousConversionService](synchronousconversionservice.mdc)
[BatchJobOrchestrator](batchjoborchestrator.mdc)
[PDFProcessingStrategy (Synchronous)](pdfprocessingstrategy__synchronous_.mdc)
[TaskStateRepository (DuckDB)](taskstaterepository__duckdb_.mdc)


---

Generated by [Rules for AI](https://github.com/altaidevorg/rules-for-ai)