Introducing liteparse-grpc: A gRPC Server for LiteParse

LiteParse is a Rust library for parsing unstructured documents (PDFs, Office files, images) with bindings for Node.js, Python, and WebAssembly. We've already had a REST server (liteparse-rest ) exposing LiteParse over HTTP with multipart uploads. Today we're adding a second way to reach it over the network: @llamaindex/liteparse-grpc , a gRPC server built on the Node.js bindings library.

Why add gRPC alongside REST?

The REST server works well for simple HTTP clients and browser-friendly multipart uploads. gRPC is a better fit when you're calling LiteParse from other backend services: it gives you a typed contract via Protocol Buffers, efficient binary framing instead of JSON/multipart, and, since the .proto file is bundled with the package, an easy path to generating clients in Python, Go, Java, or any other language protoc supports, without hand-rolling an HTTP client against the REST API.

It's not a replacement for the REST server, but an additional interface for the same underlying LiteParse functionalities, aimed at service-to-service calls rather than direct file uploads from a browser.

What's inside the package

• A server binary (liteparse-grpc-server ) that runs the gRPC service
• A client binary (liteparse-grpc-client ) for exercising the service from the command line
• Generated TypeScript stubs for building your own client or server against the same .proto
• The raw parser.proto file, so you can generate stubs for other languages with protoc

The service

The server exposes three RPCs:

These mirror the same three operations the REST server exposes (/parse , /screenshots , /is-complex ), just over a different transport. Every request optionally carries a LiteParseConfig message (OCR language, output format, image mode, etc.) giving callers full control over parsing behavior regardless of which binding or language they're calling from.

Getting started

Option 1: Docker

The fastest way to get a server running, since it bundles all the system dependencies LiteParse needs (libvips, LibreOffice, ImageMagick).

# Pull the image from the GitHub Container Registry
docker pull ghcr.io/run-llama/liteparse-grpc:main

# Run it, exposing port 50051
docker run -p 50051:50051 ghcr.io/run-llama/liteparse-grpc:main

Your server is now reachable at localhost:50051. Override behavior with env vars, e.g.:

docker run -p 50051:50051 \
	-e LOG_LEVEL=debug \
	ghcr.io/run-llama/liteparse-grpc:main

Option 2: npm package

If you're already in a Node.js environment (and have the system libraries available), you can run the server directly:

npm install -g @llamaindex/liteparse-grpc

# Run the server
liteparse-grpc-server

# Or bind to a custom address
export GRPC_BIND_ADDR=0.0.0.0:50051 
liteparse-grpc-server

Configuration is done entirely through environment variables:

Trying it out with the CLI client

The NPM package also ships a client binary so you can exercise the service without writing any code:

# Parse a file to plain text
liteparse-grpc-client parse ./document.pdf

# Parse as markdown
liteparse-grpc-client parse ./document.pdf --markdown

# Check whether a document needs OCR
liteparse-grpc-client is-complex ./document.pdf

# Screenshot every page to a directory
liteparse-grpc-client screenshot ./document.pdf --dest-dir ./imgs

Calling it from your own code

For TypeScript/Node consumers, the generated stubs are re-exported from the package root:

import {
  ParserServiceClient,
  OutputFormat,
  ImageMode,
  type LiteParseConfig,
} from "@llamaindex/liteparse-grpc";
import * as grpc from "@grpc/grpc-js";

const client = new ParserServiceClient(
  "127.0.0.1:50051",
  grpc.credentials.createInsecure(),
);

const config: LiteParseConfig = {
  ocrLanguage: "eng",
  ocrEnabled: true,
  outputFormat: OutputFormat.OUTPUT_FORMAT_MARKDOWN,
  imageMode: ImageMode.IMAGE_MODE_OFF,
};

client.parse({ config, file /* Buffer of your document */ }, (err, response) => {
  if (err) throw err;
  console.log(response.text);
});

For other languages, point protoc at the bundled .proto file:

protoc \
  --proto_path=node_modules/@llamaindex/liteparse-grpc/proto \
  --python_out=./gen \
  --grpc_python_out=./gen \
  parser.proto

What's next

This gRPC server sits alongside the existing REST server as another way to reach LiteParse over the network, aimed at polyglot, service-to-service use cases. Give it a try and let us know what you'd like to see next.