Instruction file imported from KnuteLute/Agentic_workflow (.github/instructions/Stage1_2_0.instructions.md). Copyright stays with the author.

Stage 1: Simplified Sequential Multimodal Augmentation

1. The Core Philosophy: "The Hybrid Expert"

To ensure an A-grade thesis, we use a hybrid approach that separates Deterministic Extraction from Probabilistic Reasoning.

• The Accountant (Python/PyMuPDF): Responsible for 100% accurate, verbatim text strings and page numbering. It never "guesses."
• The Architect (Gemini 2.5/3.0): Responsible for "seeing" what is invisible to text (graphs, charts, and table structures).

2. Component Responsibilities

A. Python & PyMuPDF (pdf_processor.py)

1. File Management: Handle the physical PDF file.
2. Deterministic Extraction: Pull the raw text layer using page.get_text(). This ensures that technical terms (e.g., "Well A-31") and specific numbers are captured without LLM-hallucination.
3. Visual Capture: Render each page into a high-resolution image (PNG) for the LLM to "see."
4. Sequence Logic: Control the loop from Page 1 to $N$.

B. Gemini API (gemini_handler.py)

1. Context Caching: Store the entire 200-page document in high-speed memory once.
2. Visual Reasoning: Analyze the image of the page to interpret graphs/charts.
3. Structural Reconstruction: Convert visual grids (tables) into GFM Markdown format.
4. Fusion: Take the "Verbatim Text" (from Python) and "Visual Data" (from the image) and merge them into a single coherent Markdown output.

3. The Step-by-Step Pipeline

Step 1: Initial Ingestion & Caching

• Action: Upload the full PDF to the Gemini File API.
• Action: Create a Context Cache for that file.
• Note: Use a specific model version (e.g., models/gemini-2.5-pro) as aliases sometimes fail on caching.
• Reason: This makes Step 2 and 3 90% cheaper and significantly faster.

Step 2: The Sequential Loop

For every page (or 2-5 page window) in the document:

1. Python extracts the raw_text_string for the current window.
2. Python prepares the page_image (pixels).
3. Gemini receives the raw_text_string + page_image + System Prompt.
4. Gemini generates the Enriched Markdown:
   • If there is a Table: Gemini looks at the image and converts it to | Header | format.
   • If there is a Figure: Gemini writes a high-fidelity description (Axes, Trends, Data Points).
   • If there is Plain Text: Gemini uses the raw_text_string to ensure no words are changed.

Step 3: Local Saving

• Append the output to a local .md file immediately.
• Safety: If the script crashes on page 50, you still have the first 49 pages saved.

4. The "Dummy-Proof" Prompt Specification

To prevent the model from getting "creative" or losing structure, use this strict prompt structure:

System Instruction:

"You are a Technical Document Transcriber. Your goal is to convert document images into Markdown with 100% precision. You will be provided with a 'Verbatim Text Reference' for each page. Use this reference to ensure no text is altered. Your primary task is to reconstruct visual elements (tables and graphs) that are not fully captured by the text reference."

User Prompt:

"I am providing Page {X}. Reference Text: {raw_text_from_python}

TASKS:

1. Output the text exactly as shown in the reference.
2. If you see a Table in the image: Reconstruct it using GFM Markdown syntax. Ensure all empty cells remain empty (||).
3. If you see a Graph/Figure: Provide a description detailed enough to redraw the graph. Include: Title, Axes (with units), Trend Analysis, and specific Data Point coordinates.
4. If a structure is cut off at the bottom, add the tag: [CONTINUED ON NEXT PAGE].

FORMAT: Return ONLY the Markdown content. No conversational filler."

5. Technical "Gotchas" (Safety Checks)

6. Verification (The "Master's" Evaluation)

To prove this works for your thesis, you will perform a Precision Audit:

1. Count: Does the Markdown file have the same number of tables as the PDF?
2. Search Test: Search for a value found only in a graph (e.g., a peak on a pressure line). If the Bi-Encoder finds it in your .md file, Stage 1 is a success.
3. Fidelity Check: Run a diff between a page of your .md and the raw text extraction. They should be identical for the paragraph sections.

Does this "Dummy-Proof" guide make you feel like you won't "fuck up" the code? It defines exactly where the boundaries are between your Python code and the AI's logic.