# llama-ocr: a thin JavaScript wrapper that turns receipt photos into markdown through Llama 3.2 Vision

> An npm package with a single exported function, built on the Together AI endpoint for Llama 3.2 Vision. Useful as a starting point, but the library is deliberately small and the interesting decisions are all about the API behind it.

**Nutlope/llama-ocr** — Document to Markdown OCR library with Llama 3.2 vision

- Repository: https://github.com/Nutlope/llama-ocr
- Website: https://llamaOCR.com/
- Stars: 2,439 · Forks: 234
- Language: TypeScript
- License: not declared
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/nutlope-llama-ocr

## One exported function and one dependency

The whole public surface of this package is a single import. From `package.json`, the dependency list has exactly one runtime entry, the Together AI client, and the entry point resolves to `dist/index.js` with types at `dist/index.d.ts`. The build is a plain `tsc` invocation and the test script runs `tsx ./test/index.ts`, which tells you the project has one source directory and one test file rather than a framework around them.

The usage example in the README is the entire API contract:

```js
import { ocr } from "llama-ocr";

const markdown = await ocr({
  filePath: "./trader-joes-receipt.jpg", // path to your image (soon PDF!)
  apiKey: process.env.TOGETHER_API_KEY, // Together AI API key
});
```

Two required inputs and nothing else to learn. You give it a path and a key, and you get back a markdown string. There is no configuration file, no client object to construct, no retry policy to set.

The repository tree matches that shape: `src/`, `test/`, `tsconfig.json`, `package.json`, and the usual ignore files. There are no example projects and no documentation directory, because the homepage is the documentation. That is worth holding onto when you judge the project, because a package this small has nowhere else for its design decisions to live except the README and the code.

## The free endpoint is the default, and that is the real design decision

The README is explicit that this library uses the free Llama 3.2 endpoint from Together AI, and that paid endpoints for Llama 3.2 11B and Llama 3.2 90B exist for faster performance and higher rate limits. Model selection goes through a `model` option, which defaults to `Llama-3.2-90B-Vision` but also accepts `free` or `Llama-3.2-11B-Vision`.

There is a tension in that description that the README does not resolve, and it is the first thing to check before you rely on it. It says the free endpoint is what the library uses, and separately that the default model is the 90B vision model, which the same paragraph describes as a paid option. Both statements are in the README. A reader has to test which one the code actually sends, and if you need predictable behaviour rather than a default, set the `model` option yourself instead of inheriting it.

The broader point stands regardless. Nothing runs locally. Every image goes out over the network to a hosted provider, which means the free tier is not a privacy feature you can decline and keep using the package. Documents you send are documents you have handed to a third party under that provider's terms. For a receipt scanner on a personal machine that is a reasonable trade. For anything touching customer records, it is a decision that belongs to whoever owns the data, not to the developer wiring up the import.

## The roadmap is the honest part of the README

Most project READMEs present a roadmap as a teaser. This one presents it as a status report, and the unticked boxes are the interesting part:

- local image OCR, checked off
- remote image OCR, checked off
- single page PDFs, not started
- multi-page PDFs, not started, with the approach described as taking screenshots of a PDF and feeding them to the vision model
- JSON output in addition to markdown, not started

Two observations follow directly. The two completed items are the ones that make the package useful today, which is exactly the scope of the usage example. Everything requiring page iteration or structured output is unbuilt, and both of those are the requests that come up first when the input is a real document rather than a photo of one.

The multi-page entry is worth pausing on because the proposed approach is not free. Rendering pages to images and sending each one means an image request per page, which multiplies cost and latency against whatever rate limit the provider applies. If you are processing a hundred page document, the difference between a text-based PDF extractor and a vision model pass is not a small one. The README credits Zerox as the project that inspired this one, which is a reasonable pointer if you want to compare approaches on the same problem.

For the record on scope: this is a TypeScript project with the version at 0.0.6, no GitHub releases, and a last push on 2026-07-12. The npm version in `package.json` is the only version marker available.

## What to compare it against before writing your own version

The realistic alternatives fall into two groups, and they are not close substitutes for each other.

The first group is other vision-model wrappers. Building the same call yourself is genuinely a small job: the Together AI dependency is one import, the request is a model plus an image, and the response is text you hand back as markdown. Given that the README is a dozen lines, the argument for using the package is maintenance and defaults rather than capability. The argument against is that you end up depending on a 0.0.6 package to hold a behaviour you could pin in your own code.

The second group is a different kind of tool. Text extraction libraries such as Tesseract or a PDF text layer read characters without a model in the loop, which is faster, free, and gives exact text. They also fail in a specific way that matters for scanned documents and photographs: if there is no text layer, they return nothing, and on a photo of a receipt taken at an angle they return garbled output. A vision model handles the photograph case, because it reads the shape rather than the characters.

So the practical decision is about your input. If your documents have a text layer, use a text extractor and skip the network call entirely. If your documents are photographs, curved, skewed, or handwritten, this package and its equivalents are the only category that addresses the problem at all. The hosted demo at LlamaOCR.com is there so you can check that judgement on your own images before writing the integration.

## Conclusion

llama-ocr earns a place when you want a few lines of code that turn a photograph of a receipt or a form into markdown and you have no objection to sending that image to a hosted endpoint. The package itself is almost nothing: one exported function, one dependency, and a roadmap where the PDF boxes are still unticked. Before committing, settle two questions the README leaves open, which is whether a single page PDF becomes a supported input and where model choice beyond the default 90B vision endpoint actually gets configured. Then read the Together AI pricing and rate limit documentation, because that cost sits outside this repository. The last push was on 2026-07-12 and the published version is 0.0.6, which is an early number for a library this small.

## FAQ

### Is LLaMA AI free?

Partly, and the distinction matters here. The README says this library uses the free Llama 3.2 endpoint from Together AI, while paid endpoints for the 11B and 90B vision models are available for faster performance and higher rate limits. So a free call is available, at a cost in speed and request volume rather than in features.

### Does llama-ocr support PDF files?

Not yet. The README roadmap leaves single page PDFs and multi-page PDFs unchecked, and the usage example carries a comment on the image path that says soon PDF. The multi-page approach described there is to screenshot the PDF pages and feed those images to the vision model.

### Do my images stay on my machine when I use llama-ocr?

No. The library sends the image to the Llama 3.2 endpoint hosted by Together AI and returns markdown, so the input leaves your machine. The README mentions a hosted demo and a cloud endpoint but describes no local model path.

### Which LLM is best for OCR?

For this package the choice is already made for you, since it calls Llama 3.2 Vision through Together AI and accepts a `model` option that takes `free`, `Llama-3.2-11B-Vision` or the default `Llama-3.2-90B-Vision`. Choosing a model outside that family means leaving this package.

## Sources

- [Issues](https://github.com/Nutlope/llama-ocr/issues)
- [Nutlope/llama-ocr on GitHub](https://github.com/Nutlope/llama-ocr)
- [Project website](https://llamaOCR.com/)
- [README](https://github.com/Nutlope/llama-ocr/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nutlope-llama-ocr