README

Intelligent document processing for Laravel: turn an uploaded document (invoice, receipt, statement) into structured fields through a swappable processor chain. Each document is scoped to an owner (a workspace, organization, user) through whilesmart/eloquent-owner-access.

The package is host-agnostic. It does not hard-require an OCR service or an LLM: extraction and enrichment both sit behind contracts with null defaults, so it installs and tests without any external service.

Install

composer require whilesmart/eloquent-idp
php artisan migrate

Routes register automatically under the api prefix with auth:sanctum. Set IDP_REGISTER_ROUTES=false to mount them yourself.

Owning model

Add the trait to whatever owns documents:

use Whilesmart\Idp\Traits\HasDocuments;

class Workspace extends Model
{
    use HasDocuments;
}

$workspace->documents; // MorphMany<Document>

Endpoints

process accepts an owner (owner_type, owner_id), one of file or source_path, an optional kind, mime, and a schema array hinting the fields to extract.

How processing works

DocumentService::process($document, $contents, $filename, $schema):

1. Picks the highest-priority DocumentProcessor whose supports($mime, $ext) returns true, or a null baseline when none does.
2. Runs it to get a structured baseline, plus the raw extraction text when the processor implements ProvidesExtractionContext.
3. Passes both through the bound ExtractionEnricher to produce the final extracted fields.
4. Stores extracted, raw_text, status, and fires DocumentProcessed (or DocumentFailed).

Extraction engine

KreuzbergProcessor extracts text and tables via the Kreuzberg service (POST {base_url}/extract). It stays inert until idp.kreuzberg.base_url is set, so nothing hits the network in tests. Point it at a running instance:

KREUZBERG_BASE_URL=http://kreuzberg:8000
KREUZBERG_AUTH_TYPE=bearer
KREUZBERG_AUTH_CREDENTIALS=your-token-here

Register your own processor by resolving the manager and calling register($processor, $priority); a higher priority overrides the built-in engine for a type.

Enrichment

The default NullEnricher returns the baseline unchanged. To complete or validate fields with an LLM, bind your own implementation (the package does not require a specific LLM library):

use Whilesmart\Idp\Contracts\ExtractionEnricher;

$this->app->bind(ExtractionEnricher::class, PrismExtractionEnricher::class);

Events

DocumentProcessed and DocumentFailed carry the Document so the host can bridge results into its own systems.

Status

DocumentStatus: pending, processing, completed, failed. kind is a plain string, so new document kinds need no schema change.