kreuzberg

Kind	ffi-zig
Capabilities	ffi file
Categories	document text-processing ffi
Keywords	kreuzberg document extraction pdf ocr text ffi

Kreuzberg document extraction bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/basic.kit`	Basic usage example
`examples/batch.kit`	Example: batch
`examples/info.kit`	Example: info
`examples/ocr.kit`	Example: ocr
`examples/validation.kit`	Example: validation
`include/kreuzberg.h`	Kreuzberg C FFI header
`kit.toml`	Package manifest with metadata and dependencies
`src/kreuzberg.kit`	Kit wrapper API for Kreuzberg document extraction
`tests/all-functions.test.kit`	Tests for API surface coverage
`tests/error-types.test.kit`	Tests for Kreuzberg error variants
`tests/kreuzberg.test.kit`	Tests for package constants and helpers
`tests/real-file.test.kit`	Tests for real-file helper behavior
`zig/kit_ffi.zig`	Shared Kit Zig FFI helpers
`zig/kreuzberg.zig`	Zig FFI module for Kreuzberg

Dependencies

No Kit package dependencies.

This package requires the native libkreuzberg_ffi library to be available at runtime. Install or build the Kreuzberg FFI library and make sure it can be found from one of the configured native library paths, such as /usr/local/lib or /opt/homebrew/lib.

Installation

kit add gitlab.com/kit-lang/packages/kit-kreuzberg.git

Usage

import Kit.Kreuzberg as Kreuzberg

main = fn =>
  # Show the native Kreuzberg library version, if available.
  match Kreuzberg.version
    | Some version -> println "Kreuzberg version: ${version}"
    | None -> println "Kreuzberg version: not available"

  # Extract plain text from a document path.
  match Kreuzberg.extract-file "document.pdf"
    | Ok content ->
        println "Content length: ${String.length content} characters"
    | Err e ->
        println "Extraction failed: ${e}"

  # Extract full document metadata.
  match Kreuzberg.extract-file-full "document.pdf"
    | Ok doc ->
        println "MIME type: ${doc.mime-type}"
        println "Content length: ${String.length doc.content} characters"
    | Err e ->
        println "Full extraction failed: ${e}"

  # Detect MIME types from file paths or byte prefixes.
  match Kreuzberg.detect-mime "document.pdf"
    | Some mime -> println "document.pdf: ${mime}"
    | None -> println "document.pdf: unknown MIME type"

  match Kreuzberg.detect-mime-bytes "%PDF-1.4"
    | Some mime -> println "PDF bytes: ${mime}"
    | None -> println "Could not detect MIME type"

  # Validate MIME types before extracting.
  match Kreuzberg.validate-mime-type "application/pdf"
    | Some canonical -> println "Canonical MIME type: ${canonical}"
    | None -> println "Invalid MIME type"

  # Extract from raw bytes with an explicit MIME type.
  sample = "Hello from Kit and Kreuzberg."
  match Kreuzberg.extract-bytes sample "text/plain"
    | Ok content -> println "Extracted from bytes: ${String.length content} chars"
    | Err e -> println "Bytes extraction failed: ${e}"

main

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi --allow=file

Compile examples to a native binary:

kit build examples/basic.kit --allow=ffi --allow=file && ./basic

Running Tests

Run the test suite:

kit test --allow=ffi --allow=file

Run the test suite with coverage:

kit test --coverage --allow=ffi --allow=file

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Running Parity Checks

Run interpreter/compiler parity for the examples:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/kreuzberg/, making it available for import as Kit.Kreuzberg in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

`KreuzbergError`

Error type for Kreuzberg document extraction operations. Variants distinguish between extraction, configuration, and unsupported format errors.

Variants

KreuzbergExtractError {message}

KreuzbergConfigError {message}

KreuzbergUnsupportedError {message}