llama-parse · diff
git:20260701.f5bf8f5 to v2.0.0
165 added, 84 removed. Audit A to A.
---
name: llama-parse
description: "Use this skill to parse complex documents (PDFs, Word documents, PowerPoint presentations, Excel spreadsheets, or images) into clean Markdown or structured JSON using the LlamaParse API. Make sure to use this skill whenever the user asks to extract tables from PDFs, handle complex document structures (multi-column, charts, forms), parse files with custom prompt guidelines, or convert documents to LLM-ready markdown, even if they don't explicitly mention 'LlamaParse'."
+ compatibility: Needs a `LLAMA_CLOUD_API_KEY` defined within the environment. Works in both Python and Node.js environments.
+ license: MIT
+ metadata:
+ author: LlamaIndex
+ version: "2.0.0"
---
- # LlamaParse Document Parsing
+ # LlamaParse Document Parsing Skill
- A skill to parse complex files (PDF, DOCX, PPTX, XLSX, images) into clean Markdown or structured JSON using LlamaParse (Llama Cloud API). It preserves layouts, extracts tables accurately, and supports custom formatting instructions.
+ Parse unstructured documents (such as PDF, DOCX, PPTX, XLSX, images) with LlamaParse and extract their contents (text, markdown, images, JSON). This skill supports both **Python** (`llama-cloud` SDK) and **Node.js/TypeScript** (`@llamaindex/llama-cloud` SDK).
## When to use
Use this skill when:
- Normal text extractors (like `pdfplumber` or `pypdf`) fail to extract structured tables or handle complex document layouts.
- You need to parse files containing mathematical equations, complex charts, or forms.
- You need to convert documents (PDF/DOCX/PPTX) into high-quality Markdown optimized for RAG or LLM context ingestion.
- - You need custom parsing rules (e.g. "Extract tables as CSV", "Ignore headers and footers").
+ - You need custom parsing rules (e.g., "Extract tables as CSV", "Ignore headers and footers").
+ - You need to extract and download embedded images/screenshots from the documents.
- ## Setup and Prerequisites
+ ---
- 1. **Environment Variables**:
- LlamaParse requires a LlamaCloud API Key. Ensure the key is set:
- ```bash
- export LLAMA_CLOUD_API_KEY="llx-..."
- ```
- Get a free API key at [Llama Cloud](https://cloud.llamaindex.ai/). Alternatively, you can pass the key via the `-k` / `--api-key` command-line argument.
+ ## Setup and Prerequisites
- 2. **Dependencies**:
- Ensure `llama-parse` is installed:
- ```bash
- pip install llama-parse
- ```
+ ### 1. API Key
+ LlamaParse requires a LlamaCloud API Key. Ensure the key is set:
+ ```bash
+ export LLAMA_CLOUD_API_KEY="llx-..."
+ ```
+ Get a free API key at [Llama Cloud](https://cloud.llamaindex.ai/).
- ## How to Run the Parser Script
+ ### 2. Environment Selection & Installation
- This skill includes a helper script `parse.py` in the `scripts/` directory.
+ Depending on the workspace project stack, select either Python or TypeScript:
- ### 1. Basic Parsing to Markdown
- To parse a document and print the output to standard output:
+ #### For Python Environments
+ Install the unified Python SDK:
```bash
- python3 <skill_dir>/scripts/parse.py path/to/document.pdf
+ pip install llama-cloud
```
+ > [!NOTE]
+ > The older `llama-parse` package is deprecated. Always use `llama-cloud` for new implementations.
- To save the markdown result to a specific file:
+ #### For TypeScript/Node.js Environments
+ Install the unified Node.js SDK:
```bash
- python3 <skill_dir>/scripts/parse.py path/to/document.pdf -o output.md
+ npm install @llamaindex/llama-cloud@latest
```
- ### 2. Batch Parsing (Multiple Files)
- To parse multiple files at once. If `-o` is a directory, the parsed files will be written there using their original basenames (e.g. `doc1.md`, `doc2.md`):
- ```bash
- python3 <skill_dir>/scripts/parse.py doc1.pdf doc2.pdf -o path/to/output_dir/
- ```
+ ---
- If `-o` is a file path, the outputs will be concatenated:
- ```bash
- python3 <skill_dir>/scripts/parse.py doc1.pdf doc2.pdf -o combined_output.md
- ```
+ ## Helper Scripts
- ### 3. API Key Flag
- If you don't have the environment variable configured:
- ```bash
- python3 <skill_dir>/scripts/parse.py document.pdf -k "llx-your-api-key-here"
- ```
+ This skill includes pre-built helper scripts under the `scripts/` directory:
+ - [parse.py](file:///Users/alex/github/hankunpeng/skills/skills/llama-parse/scripts/parse.py) — Unified Python script.
+ - [parse.ts](file:///Users/alex/github/hankunpeng/skills/skills/llama-parse/scripts/parse.ts) — Unified TypeScript script (execute via `npx tsx`).
- ### 4. Page Range Control (target_pages)
- To save API tokens and only parse specific page ranges:
- ```bash
- python3 <skill_dir>/scripts/parse.py document.pdf -p "0,2-5"
- ```
+ ### Command-Line Arguments (Unified)
- ### 5. Multimodal / Vendor Model Mode (Recommended for Charts & Forms)
- To enable LlamaParse's advanced multimodal parsing using an LLM like GPT-4o to achieve high layout-fidelity extraction of complex figures and tables:
+ Both scripts support the same arguments:
+
+ | Option | Description |
+ |--------|-------------|
+ | `-o, --output <path>` | Path to output file or directory. If a directory is specified, outputs are written there with matching basenames. |
+ | `-k, --api-key <key>` | LlamaCloud API key (falls back to `LLAMA_CLOUD_API_KEY` env var). |
+ | `-t, --type <type>` | Result type: `markdown` or `text` (default: `markdown`). |
+ | `--tier <tier>` | Parsing tier: `fast`, `cost_effective`, `agentic`, `agentic_plus` (default: `agentic`). |
+ | `-i, --instruction <text>` | Custom parsing instructions (e.g. prompt guidelines). |
+ | `-l, --language <lang>` | OCR language code (e.g., `en`, `de`, `ch_sim`). |
+ | `-p, --pages <ranges>` | Page ranges to parse (comma-separated page numbers or ranges, e.g. `0,2-5`). |
+ | `-j, --json` | Output raw JSON containing structural page elements. |
+ | `-d, --download-images` | Download extracted images and screenshots from the document. |
+ | `--show-usage` | Show remaining credit usage of the free plan quota, then exit. |
+ | `-v, --verbose` | Enable verbose status/polling logs. |
+
+ ---
+
+ ## Execution Examples
+
+ ### 1. Basic Parsing to Markdown
```bash
- python3 <skill_dir>/scripts/parse.py document.pdf --use-vendor-model
+ # Python
+ python3 <skill_dir>/scripts/parse.py document.pdf -o output.md
+
+ # TypeScript
+ npx tsx <skill_dir>/scripts/parse.ts document.pdf -o output.md
```
- ### 6. Custom Parsing Instructions
- To parse with specific guidelines (e.g., how to treat tables or formatting):
+ ### 2. Extracting and Downloading Images
+ To download screenshots/extracted figures from the PDF to the output directory:
```bash
- python3 <skill_dir>/scripts/parse.py path/to/document.pdf -i "Format all headers with ## and convert all tables to clean markdown tables."
+ # Python
+ python3 <skill_dir>/scripts/parse.py document.pdf -d -o output_dir/
+
+ # TypeScript
+ npx tsx <skill_dir>/scripts/parse.ts document.pdf -d -o output_dir/
```
- ### 7. Parsing to JSON
- To extract raw structured JSON metadata containing page breakdowns, bounding boxes, or text blocks:
+ ### 3. Target Page Selection (Credit-Saving)
```bash
- python3 <skill_dir>/scripts/parse.py path/to/document.pdf -j -o output.json
+ # Parse pages 1, 3, 4, 5, 6 (0-indexed)
+ python3 <skill_dir>/scripts/parse.py document.pdf -p "0,2-5"
```
- ### 8. Language Selection
- Specify the document language for better OCR/parsing accuracy (e.g., `en` for English, `ch_sim` for Simplified Chinese):
+ ### 4. Custom Parsing Instruction & Advanced Tier
```bash
- python3 <skill_dir>/scripts/parse.py path/to/chinese_doc.pdf -l ch_sim
+ python3 <skill_dir>/scripts/parse.py document.pdf --tier agentic_plus -i "Format all tables as markdown, ignoring headers/footers."
```
- ### 9. Querying Account Usage/Quota
- To query your LlamaParse Free Plan credit usage directly without parsing files:
+ ### 5. Parse to Structured JSON
```bash
- python3 <skill_dir>/scripts/parse.py --show-usage
+ python3 <skill_dir>/scripts/parse.py document.pdf -j -o output.json
```
+ ---
- ## Python API Quick Reference
+ ## SDK Integration Reference
- You can also import and use LlamaParse directly inside Python:
+ For code integrations inside projects:
+ ### Python SDK Integration (`llama-cloud`)
+
```python
- from llama_parse import LlamaParse
+ import os
+ import time
+ from llama_cloud.client import LlamaCloud
+ from llama_cloud import LlamaParseAgenticOptions, LlamaParseOutputOptions
- # Initialize parser
- parser = LlamaParse(
- api_key="llx-...", # Optional if LLAMA_CLOUD_API_KEY is in env
- result_type="markdown", # "markdown" or "text"
- parsing_instruction="Extract tables cleanly.", # Optional
- language="en", # Optional
- target_pages="0,2-5", # Optional
- use_vendor_multimodal_model=True, # Optional
- vendor_multimodal_model_name="gpt-4o", # Optional
- verbose=True
+ client = LlamaCloud(token=os.environ["LLAMA_CLOUD_API_KEY"])
+
+ # 1. Upload file
+ with open("document.pdf", "rb") as f:
+ file_obj = client.files.upload_file(upload_file=f)
+
+ # 2. Start parse job
+ job = client.v_2.parse_file(
+ file_id=file_obj.id,
+ tier="agentic",
+ version="latest",
+ agentic_options=LlamaParseAgenticOptions(custom_prompt="Format tables cleanly."),
+ output_options=LlamaParseOutputOptions(images_to_save=["screenshot"])
)
- # Parse a file into LlamaIndex Document objects
- documents = parser.load_data("./my_document.pdf")
- full_text = "\n\n".join([doc.text for doc in documents])
+ # 3. Poll for completion
+ while True:
+ res = client.v_2.get_parse_job(job.id, expand=["markdown", "images_content_metadata"])
+ if res.job.status == "COMPLETED":
+ break
+ elif res.job.status in ("FAILED", "CANCELLED"):
+ raise Exception(f"Job failed: {res.job.error_message}")
+ time.sleep(2)
- # Parse a file to raw JSON
- json_results = parser.get_json_result("./my_document.pdf")
+ # 4. Extract results
+ markdown_text = "\n\n".join([p.markdown for p in res.markdown.pages if p.markdown])
+ print(markdown_text)
```
+ ### TypeScript SDK Integration (`@llamaindex/llama-cloud`)
+
+ ```typescript
+ import LlamaCloud from "@llamaindex/llama-cloud";
+ import { readFile } from "fs/promises";
+ import { basename } from "path";
+
+ const client = new LlamaCloud({
+ apiKey: process.env.LLAMA_CLOUD_API_KEY,
+ });
+
+ // 1. Upload file
+ const fileBuffer = await readFile("document.pdf");
+ const fileBlob = new File([fileBuffer], basename("document.pdf"));
+ const fileObj = await client.files.create({
+ file: fileBlob,
+ purpose: "parse",
+ });
+
+ // 2. Start parse job
+ const job = await client.v_2.parseFile({
+ file_id: fileObj.id,
+ tier: "agentic",
+ version: "latest",
+ output_options: {
+ images_to_save: ["screenshot"],
+ },
+ });
+
+ // 3. Poll for completion
+ let res: any;
+ while (true) {
+ res = await client.v_2.getParseJob(job.id, {
+ expand: ["markdown_full", "images_content_metadata"],
+ });
+ if (res.job?.status === "COMPLETED") break;
+ if (res.job?.status === "FAILED" || res.job?.status === "CANCELLED") {
+ throw new Error(`Job failed: ${res.job?.error_message}`);
+ }
+ await new Promise((resolve) => setTimeout(resolve, 2000));
+ }
+
+ // 4. Extract results
+ const markdownText = res.markdown_full ?? "";
+ console.log(markdownText);
+ ```
+
+ ---
+
## Troubleshooting & Best Practices
- - **Invalid API Key Error**: Double-check your `LLAMA_CLOUD_API_KEY`. It should start with `llx-`.
- - **Rate Limits**: If you run out of credits or hit concurrency rate limits, LlamaParse calls might fail. Use `-p` to target specific pages to save credits, or run with `-v` to debug API response codes.
- - **Form and Table Extraction**: For documents with heavily structured forms or graphics, always pass `--use-vendor-model` to invoke multimodal GPT-4o parsing.
- - **Empty Output**: Ensure the file type is supported. Supported file types include `.pdf`, `.docx`, `.pptx`, `.xlsx`, `.png`, `.jpg`, `.jpeg`, `.tiff`.
- - **Low Credits Warning**: If the remaining Free Plan credits fall below 100, the script will output a prominent `[WARNING] LlamaParse remaining credits are below 100!` message to alert the user of impending exhaustion.
+ - **Deprecated SDK Warning**: Avoid installing or importing the `llama-parse` pip library. Always use `llama-cloud` for Python development to prevent deprecation issues.
+ - **Model Selection in V2**: In LlamaCloud V2, model configuration (e.g. GPT-4o multimodal parsing) is determined by the `tier` parameter (`agentic` or `agentic_plus`) instead of legacy local parameters.
+ - **Save Quota / Page Range**: Use `-p` to target specific page numbers to avoid consuming unnecessary credits on long documents.
+ - **Image Auth Headers**: When downloading images/screenshots from LlamaCloud presigned URLs, you must include the Bearer Authorization header: `Authorization: Bearer <LLAMA_CLOUD_API_KEY>`.
- ## User Communication
- - **Immediately upon triggering**, before running any parsing tasks, run `python3 <skill_dir>/scripts/parse.py --show-usage` (or fetch programmatically) and notify the user of LlamaParse's Free Plan monthly limit (10,000 Credits) and how many credits have currently been used.
- - **Every time a conversion task completes**, display the updated Free Plan usage as printed by the script.
- - Report parsing completion details (e.g., number of pages, output format, output file path).
- - Show a brief preview of the parsed content to the user.
+ ---
+
+ ## User Communication Guidelines
+
+ 1. **Quota Warnings**: When initializing or executing a parse task, query and display LlamaParse's Free Plan credit usage to let the user know their current balance. Warn them clearly if remaining credits are below 100.
+ 2. **Result Previews**: After parsing finishes, report the details (number of parsed pages, generated outputs) and print a concise Markdown preview of the parsed content.