sema-unstructured

Extract structured document elements from PDFs, images, and Office files via the Unstructured.io API.

sema-unstructured uploads a document as a multipart form to the Unstructured partition endpoint and returns the API's JSON array of elements — titles, paragraphs, tables, and list items, each with its text and metadata.

Install

sema pkg add sema-unstructured

Quick start

(import "sema-unstructured")

;; UNSTRUCTURED_API_KEY is read from the environment.
(define client (unstructured/client))

;; Partition a file straight from disk.
(define elements (unstructured/partition client "report.pdf" {:strategy "hi_res"}))

(println (length elements))
;; => 42

(println (get (first elements) :type))
;; => "Title"

;; Flatten every element's text into one string.
(println (unstructured/text-of elements))
;; => "Annual Report 2026\nExecutive summary ...\n..."

API

unstructured/client

(unstructured/client)
(unstructured/client {:api-key "..." :base-url "..." :timeout 120000})

Builds a client map passed as the first argument to every call. Options:

• :api-key — defaults to the UNSTRUCTURED_API_KEY environment variable.
• :base-url — defaults to "https://api.unstructuredapp.io". Set this to the tenant URL shown when your account was created if it differs.
• :timeout — request timeout in milliseconds (default 120000; partitioning large files is slow).

Errors if no API key is passed or found in the environment. The key is never logged.

(define client (unstructured/client {:api-key (env "UNSTRUCTURED_API_KEY")}))

unstructured/partition

(unstructured/partition client source)
(unstructured/partition client source opts)

Partitions a document via POST /general/v0/general and returns a list of element maps ({:type .. :element_id .. :text .. :metadata ..}).

source is either:

• a file path string — the file's bytes are read and uploaded, and its basename becomes the upload filename; or
• a {:bytes <bytevector> :filename "name.ext"} map — the bytes are uploaded verbatim under the given filename (use this when the document is already in memory).

Options map:

• :strategy — "auto", "hi_res", "fast", "ocr_only", or "vlm". Omitted → the API's default strategy.
• :chunking-strategy — e.g. "by_title" or "basic". Omitted → no chunking.
• :params — a map of any other form fields the endpoint accepts (keyword or string keys), e.g. {:languages "eng" :coordinates #t}. Booleans are sent as "true"/"false".

;; From a path, high-resolution layout parsing, chunked by title.
(unstructured/partition client "invoice.pdf"
                        {:strategy "hi_res" :chunking-strategy "by_title"})

;; From in-memory bytes with extra form fields.
(unstructured/partition client
                        {:bytes (file/read-bytes "scan.png") :filename "scan.png"}
                        {:strategy "ocr_only" :params {:languages "eng"}})

unstructured/text-of

(unstructured/text-of elements)

Joins the :text of a partition result into a single newline-separated string. Elements without text (e.g. images) contribute nothing. nil or an empty list yields "".

(unstructured/text-of (list {:type "Title" :text "Heading"}
                            {:type "Image"}
                            {:type "NarrativeText" :text "Body."}))
;; => "Heading\nBody."

unstructured/request

(unstructured/request client method path opts)

Low-level request used by every wrapper; reach for it to call endpoints the wrappers don't cover. method is "GET"/"POST"/..., path an API path or a full URL. opts is a map: :multipart (a list of {:name .. :content .. :filename ..?} parts for form uploads) or :body (a map → JSON body). Returns the decoded JSON body (nil when empty); raises on non-2xx with the method, path, status, and the API's message.

(unstructured/request client "POST" "/general/v0/general"
  {:multipart (list {:name "files" :content (file/read-bytes "a.pdf") :filename "a.pdf"}
                    {:name "strategy" :content "fast"})})

Authentication

Get an API key from the Unstructured Platform and expose it as an environment variable:

export UNSTRUCTURED_API_KEY="your-key-here"

The key is sent in the unstructured-api-key request header. If your account was provisioned with a dedicated API URL, pass it via :base-url on the client.

Testing

sema tests.sema

The offline suite covers client construction, source validation, response shaping, and error mapping. The live test hits the real API and runs only when UNSTRUCTURED_API_KEY is set.

License

MIT