Extractor Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin, single-purpose adapter: two facades (Extractor, Text), one abstract Extractor class, and a config file. It layers on top of openai-php/laravel rather than reimplementing an HTTP client, which keeps the abstraction shallow and replaceable.
• It fills a narrow but real gap: text acquisition (PDF, Word, HTML, web, image OCR) plus LLM-driven structured output with JSON Mode and optional Spatie laravel-data hydration. For a Laravel codebase already comfortable with facades and DTOs, the mental model maps cleanly.
• Lock-in is low by design. If the package is abandoned, the replacement is a Text helper class plus direct OpenAI::chat() calls with a JSON schema instruction — an estimated 2-5 engineering days per extractor in use. This materially de-risks the "buy" decision.
• It is not an extraction platform. There is no schema validation, no repair loop, no queueing, no cost accounting, no evaluation harness, and no human-review workflow. Those are the TPM's build responsibilities, not the package's.

Integration feasibility

• Installation is conventional: composer require, publish extractor-config, publish the OpenAI provider config, set OPENAI_API_KEY. No database migrations, no service provider gymnastics, no queue topology assumptions.
• Provider portability is supported via OPENAI_BASE_URI (Ollama, Together, Groq) and a documented Azure override that rebinds ClientContract in AppServiceProvider. That is enough to support self-hosted inference for PII-sensitive workflows and to avoid single-vendor exposure on the model side.
• Custom extractors are a clean extension point: extend the base class, implement prompt() and expectedOutputKey(), register with Extractor::extend(). Straightforward for a mid-level Laravel engineer.
• Unverified at this stage: Laravel/PHP version constraints (not stated in the README), presence and coverage of a test suite, and whether retries/backoff exist at all. These need to be confirmed from composer.json and the repo before committing.

Technical risk

• Output reliability. Extraction is prompt-driven. JSON Mode improves conformance but does not guarantee field presence, types, or non-hallucination. The package appears to offer no validation or re-ask path; the consuming application must own that.
• Prompt injection. Extracted documents are untrusted input funneled directly into a model prompt. A malicious PDF or HTML page can attempt to redirect the extraction. Treat all output as untrusted data and validate against a strict schema.
• SSRF surface. Text::web($url) fetches arbitrary URLs over HTTP. If any user-supplied URL reaches that method, an allowlist, scheme restriction, and response-size cap are mandatory.
• File-parsing surface. Text::word unzips and XML-parses uploads; Text::pdf uses smalot/pdfparser. Both process untrusted binaries. Zip-bomb and XXE exposure need review, and parsing should occur in an isolated worker.
• Vendor/model churn. Model names are exposed as Engine constants (GPT_4O_MINI, GPT_4O). OpenAI deprecations will silently break these; pin, test, and own the mapping.
• Unproven ecosystem signal. 226 stars, zero dependents, and an aggregate score of ~24.5 (opportunity ~20) indicate a package that is technically interesting but not yet validated in production elsewhere. Effectively a single-maintainer bus factor of one.
• Metadata anomaly. The listed last release (2026-08-25) is future-dated; verify actual tag cadence and commit activity on Packagist/GitHub before treating "releases" maturity as meaningful.

Key questions

1. What are the declared Laravel and PHP version constraints, and is there CI with a real test suite?
2. Does the package validate JSON responses, retry on malformed output, or handle maxTokens truncation?
3. Are temperature, retries, and backoff configurable, or must they be wrapped externally?
4. What is the documented behavior for scanned/image-only PDFs (Textract S3 path) — bucket, region, IAM, and polling timeout expectations?
5. Is there guidance on chunking documents that exceed the model context window?
6. What is the maintainer's stated support model and release cadence?
7. Does the README's Vision support (explicitly marked WIP) represent a stable surface or an experimental one?

Integration Approach

Stack fit

• Target: Laravel 10/11 on PHP 8.1+, with a queue worker pool already in place. The package assumes synchronous invocation; production use must wrap every call in a queued job.
• Pair with Spatie laravel-data only if the team already uses it — the package's DTO return mode is convenient but shallow, and the DTO cannot enforce correctness the model didn't produce.
• Store secrets in the platform secret manager, not .env on disk; the Azure binding example references env() directly and should be refactored to config().

Migration path

• Greenfield capability — there is no incumbent to displace. If manual data entry or a third-party OCR vendor exists, run the package in shadow mode in parallel for 4-6 weeks, writing results to a side table without affecting downstream records.
• Keep a human reviewer in the loop for any field that gates money, compliance, or customer-facing communication, until per-field precision is measured and stable.

Compatibility

• Pin an exact version in composer.json; do not float. Treat upgrades as change-managed events with a fixed evaluation corpus.
• For non-OpenAI or self-hosted endpoints, verify JSON Mode semantics provider-by-provider before relying on structured output — this is the most likely source of silent breakage across Ollama/Groq/Together.
• Azure requires a container binding; encapsulate it in a dedicated service provider and feature-flag it rather than inlining in AppServiceProvider.

Sequencing

1. PoC (1 sprint). Assemble a 50-document corpus of real, representative inputs. Measure per-field precision/recall against ground truth. Decide which document types are viable.
2. Reliability layer (1 sprint). Queued jobs, exponential backoff on 429/5xx, timeouts tuned above the 30s default, an extractions table persisting raw model output, parsed payload, model ID, prompt version, token counts, and latency.
3. Validation layer. Typed DTOs or Laravel validators per extractor; a single re-ask on validation failure; hard failure to a review queue rather than silent nulls.
4. Prompt governance. Version prompts in source control; use custom extractor classes (not the ad-hoc fields() API) for any document type with volume or business criticality.
5. Productionize. Per-tenant rate limits, cost metering, text-extraction caching keyed by file hash, and a review UI for low-confidence results.

Operational Impact

Maintenance

• Single maintainer, no dependents, no commercial backing. Assume you will own this code eventually. Keep a fork or a documented replacement path (direct openai-php calls) current.
• Ongoing maintenance burden is dominated by model and prompt drift, not package upgrades: re-run the evaluation corpus on every model change and monthly as a regression check.

Support

• No SLA. GitHub issues only. Internal escalation path must be staffed — budget roughly 0.2 FTE of a Laravel engineer for the first two quarters, dropping after stabilization.

Scaling

• Throughput is bounded by provider rate limits and per-call latency (30s default, 60s recommended). All invocations must be asynchronous; scale via queue workers, not web requests.
• The Textract S3 path introduces a long tail: multi-page PDFs can take minutes and require S3 lifecycle management, IAM policy upkeep, and polling with a hard timeout.
• Cost scales with tokens plus Textract pages. Enforce per-tenant quotas and cache extracted text aggressively — re-extracting the same document is pure waste.

Failure modes

• Malformed or truncated JSON (especially at maxTokens), hallucinated fields, and empty results indistinguishable from "no data present."
• Timeouts, 429s, and provider outages — need retry with jitter plus a circuit breaker.
• PDF parse failures on scanned documents; Textract job timeouts and S3 permission errors.
• Prompt injection from document content; SSRF via Text::web; parser exploits on crafted uploads.
• PII egress to a third-party model provider — a compliance and DPA review item, with self-hosted inference via OPENAI_BASE_URI as the mitigation path.

Ramp-up

• Package API surface is small; a mid-level Laravel engineer is productive in 1-2 days. The real cost is elsewhere: evaluation harness design, prompt engineering discipline, and reliability patterns — budget 2-3 sprints before this is defensible in production.
• Recommended framing for stakeholders: adopt as a tactical accelerator with a documented exit ramp, not as a strategic platform dependency.