LlamaParse Document Parsing Skill

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 to extract and download embedded images/screenshots from the documents.

---

Setup and Prerequisites

1. API Key

LlamaParse requires a LlamaCloud API Key. Ensure the key is set:

export LLAMA_CLOUD_API_KEY="llx-..."

Get a free API key at Llama Cloud.

2. Environment Selection & Installation

Depending on the workspace project stack, select either Python or TypeScript:

For Python Environments

Install the unified Python SDK:

pip install llama-cloud

[!NOTE] The older llama-parse package is deprecated. Always use llama-cloud for new implementations.

For TypeScript/Node.js Environments

Install the unified Node.js SDK:

npm install @llamaindex/llama-cloud@latest

---

Helper Scripts

This skill includes pre-built helper scripts under the scripts/ directory:

• parse.py — Unified Python script.
• parse.ts — Unified TypeScript script (execute via npx tsx).

Command-Line Arguments (Unified)

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

# 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

2. Extracting and Downloading Images

To download screenshots/extracted figures from the PDF to the output directory:

# 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/

3. Target Page Selection (Credit-Saving)

# Parse pages 1, 3, 4, 5, 6 (0-indexed)
python3 <skill_dir>/scripts/parse.py document.pdf -p "0,2-5"

4. Custom Parsing Instruction & Advanced Tier

python3 <skill_dir>/scripts/parse.py document.pdf --tier agentic_plus -i "Format all tables as markdown, ignoring headers/footers."

5. Parse to Structured JSON

python3 <skill_dir>/scripts/parse.py document.pdf -j -o output.json

---

SDK Integration Reference

For code integrations inside projects:

Python SDK Integration (llama-cloud)

import os
import time
from llama_cloud.client import LlamaCloud
from llama_cloud import LlamaParseAgenticOptions, LlamaParseOutputOptions

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"])
)

# 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)

# 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)

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

• 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 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.