{
  "markdown": "# Images-to-TeX & Markdown (Model Context Protocol)\n\nAn advanced semantic document parser and agentic \"skill\" that transforms images of textbooks, handwritten equations, and notes into strictly separated layers (Base Printed Content vs. Human Annotations) formatted as LaTeX or Markdown.\n\n## 🚀 Overview\n\nThis application acts as a high-precision OCR and document interpretation engine powered by **Google Gemini 1.5 Pro/Flash**. It is designed to be used both as a standalone CLI tool and as a **Model Context Protocol (MCP)** server, allowing AI agents (like Claude or Gemini) to interact with physical documents with extreme structural accuracy.\n\n## 🛠 Features\n\n-   **Structural Stratification**: Strictly separates the original printed text from human annotations (handwritten notes, highlights, margin clues).\n-   **Dual Mode Extraction**: Generates perfectly formatted LaTeX (for academic typesetting) and Markdown (for web/docs) simultaneously.\n-   **Intelligent Vision Pipeline**: Uses OpenCV for denoising, deskewing, and binarization to maximize OCR reliability.\n-   **Hybrid Processing Architecture**:\n    -   **Synchronous**: Low-latency processing for small documents using **Context Caching** to reduce costs.\n    -   **Asynchronous (Batch API)**: Background processing for massive PDFs (50+ pages) to avoid timeouts.\n-   **Job Management Ledger**: Centralized tracking of all background jobs in a `.jobs/` directory with a ledger for history and verification.\n-   **Self-Correction**: Robust retry logic that feeds linter/parsing errors back to the LLM to fix malformed JSON outputs.\n\n---\n\n## 🏗 How it Works (Architecture)\n\nThe following diagram illustrates the flow from an Agent request to the final extracted document:\n\n```mermaid\ngraph TD\n    User((User/Agent)) -->|MCP Call| MCP[MCP Server]\n    MCP -->|Invoke| PD[process_document]\n    \n    PD -->|Analyze| Threshold{Pages > Threshold?}\n    \n    subgraph \"Synchronous Flow (Small Docs)\"\n    Threshold -->|No| Sync[Local Execution]\n    Sync -->|vision.py| VP[PDF/Image Extraction]\n    VP -->|OpenCV| CV[Image Enhancement]\n    CV -->|Prompt| GAI[Gemini 1.5: Context Caching]\n    GAI -->|Stream JSON| Parse[Pydantic Validation]\n    Parse -->|JSON Result| User\n    end\n    \n    subgraph \"Asynchronous Flow (Large Docs)\"\n    Threshold -->|Yes| Async[Traffic Controller]\n    Async -->|Thread| BT[Background Task]\n    BT -->|Ledger| JM[Job Manager: .jobs/ledger.json]\n    BT -->|Upload| GFiles[Gemini Files API]\n    BT -->|JSONL| GBatch[Gemini Batch API]\n    Async -->|Local Job ID| User\n    end\n    \n    subgraph \"Status & Management\"\n    User -->|Call| CS[check_document_status]\n    CS -->|Check Ledger| JM\n    CS -->|Poll API| GBatch\n    GBatch -->|Done| Results[Download & Extract]\n    Results -->|.tex / .md| User\n    \n    User -->|Call| MJ[manage_jobs]\n    MJ -->|List/Cleanup| JM\n    end\n```\n\n---\n\n## 📦 Installation\n\n### Prerequisites\n- Python 3.10+\n- [Poppler](https://github.com/check-repos/poppler) (Required for PDF processing)\n  - macOS: `brew install poppler`\n  - Linux: `sudo apt-get install poppler-utils`\n\n### Setup\n1. **Clone & Install**:\n   ```bash\n   git clone <repository_url>\n   cd docs-to-code\n   pip install -r requirements.txt\n   ```\n\n2. **Configure Environment**:\n   Create a `.env` file in the root:\n   ```text\n   GOOGLE_API_KEY=your_gemini_api_key_here\n   ```\n\n---\n\n## 🤖 MCP Server Usage\n\nThis application is built as an MCP server. Add the following to your agent's configuration (e.g., `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"images-to-tex\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"src.interfaces.mcp_server\"],\n      \"cwd\": \"/absolute/path/to/docs-to-code\",\n      \"env\": {\n        \"GOOGLE_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Available Tools\n\n| Tool | Description | Key Arguments |\n| :--- | :--- | :--- |\n| `process_document` | Main entry point for PDF/Image processing. | `document_path`, `mode` (latex/markdown), `threshold_pages` |\n| `check_document_status` | Polls status for background/batch jobs. | `job_id`, `output_format` |\n| `manage_jobs` | Manages the local `.jobs/` ledger. | `action` (list/cleanup), `job_id` |\n\n---\n\n## 📂 Project Structure\n\n- `src/interfaces/`: Entry points (MCP Server, CLI).\n- `src/services/`: Core logic (Vision pipeline, Gemini Intelligence, Batch Processor).\n- `src/tools/`: High-level tool implementations.\n- `src/models/`: Pydantic data models for structured output.\n- `src/utils/`: Shared utilities (Job Manager, LLM prompt engineering).\n- `.jobs/`: (Gitignored) Local storage for background job states and ledger.\n\n## 📝 License\nMIT\n",
  "bytes": 4628,
  "sha": "c9f2f0467540afa07f35cfad6888232a94547d48b79ba6291e39d49d0ee750a0",
  "repo_slug": "carlosraulps/docs-to-code",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_carlosraulps_docs_to_code_3526c75d/readme"
}