Larai Kit Laravel Package

v0.2.4 (2026-05-02)

This release resolves community issues #9–#13 with a focus on data integrity, ingestion consistency, and streaming extensibility.

Added

• IngestionService::ingestFromDisk($disk, $path, $scope) for re-ingesting already-stored files.
• ChatStreamResponse::withOnComplete(callable) for post-stream persistence/hooks.
• New queued ingestion entry jobs for text and URL flows (ProcessTextAssetJob, FetchUrlAssetJob).
• docs/redundancy-audit-v0.2.4.md with non-blocking follow-up cleanup items.

Fixed

• Asset deletion now dispatches vector cleanup after commit to prevent orphaned vectors.
• pgvector cleanup now deletes by source_meta.chunk_id with ID fallback.
• Terminal ingestion events (AssetIndexed, AssetFailed) now defer at transaction commit boundaries across web/CLI/worker contexts.
• ingestText() and ingestUrl() now follow async pipeline behavior consistent with ingestFile().

Docs and Versioning

• Version bumped to 0.2.4.
• README and ingestion/agents docs updated for new APIs and event timing semantics.

Verification

• Full automated suite + smoke coverage passed: 19 tests, 52 assertions.

Highlights

• Real token counts on usage events — ChatCompleted and EmbeddingsCompleted now carry provider-reported token counts instead of hardcoded zeros, so billing and cost analytics work without a second API call. (#6)
• Env-configurable health endpoint middleware — LARAI_HEALTH_MIDDLEWARE (pipe-separated) lets monitoring systems hit the health endpoint without pulling in the full auth guard. (#7)
• Terminal ingestion events — AssetIndexed / AssetFailed fire after the outer DB transaction commits, eliminating the race that forced callers to match assets by source_name. (#5)
• PHPUnit scaffold — first six tests land, covering the new DTO, streaming usage contract, and ChatService event dispatch.

Added

#6 — Usage telemetry

• ChatCompleted.inputTokens / outputTokens are populated from the SDK's AgentResponse::$usage (non-streaming) and StreamableAgentResponse::$usage (streaming, read after the stream drains via StreamEnd::combineUsage()). Works for OpenAI, Anthropic, and Gemini since all three route through the same Usage object.
• durationMs is now populated on the streaming path too (was hardcoded 0).
• OpenAiEmbedding::embedManyWithUsage(): EmbeddingResult — new optional method returning vectors + provider-reported token count. EmbedChunksJob detects it via method_exists() and emits real tokenCount on EmbeddingsCompleted.
• Duck-typed extraction against usage->promptTokens / completionTokens — third-party providers, test doubles, and future SDK shape changes don't break the pipeline.

#7 — Health middleware

• LARAI_HEALTH_MIDDLEWARE env var accepts a pipe-separated middleware list, e.g. auth|throttle:60,1. Pipe is used instead of comma because Laravel's rate-limit syntax throttle:60,1 ("60 requests per minute") contains a comma — a comma-separated parser would silently break it.
• Defaults to auth to preserve existing behavior. Set empty for public access behind an ingress allowlist.
• Documented in docs/configuration.md under "Health Endpoint".

#5 — Terminal ingestion events

• New AssetIndexed and AssetFailed events fired after Ingestion::markState() reaches a terminal state.
• Dispatched via dispatch()->afterResponse() in web requests, so listeners run after the caller's outer transaction commits and ai_asset_id is stored on your domain rows.
• In CLI / queue-worker contexts they fire immediately (no response boundary to defer against).
• IngestionStateChanged behavior unchanged — prefer the terminal events when you only care about "did it work."

Test infrastructure

• phpunit/phpunit ^11.0 and orchestra/testbench ^9.0|^10.0 as dev deps.
• phpunit.xml.dist, tests/TestCase.php.
• Six unit + feature tests covering EmbeddingResult, ChatStreamResponse, and ChatService event dispatch.
• Run with composer test.

Fixed

• OpenAiEmbedding::embedMany() was not actually batching. Despite the name, the implementation looped $this->embed($text) once per chunk — one HTTP request per input. It now delegates to embedManyWithUsage() which uses Embeddings::for($texts)->generate() with a batch size of 96. For a 200-chunk document this drops embedding API calls from 200 to 3.

Backward compatibility

Fully backward compatible:

• EmbeddingProvider contract unchanged — third-party implementations continue to work (they just report tokenCount: 0 on EmbeddingsCompleted).
• ChatCompleted / EmbeddingsCompleted event shape unchanged — only the values inside change from 0 to real numbers.
• LARAI_HEALTH_MIDDLEWARE unset → defaults to ['auth'] (same as v0.2.2).

Install

composer require laraigent/larai-kit:^0.2.3

Critical fix for two regressions introduced in v0.2.1. Upgrade immediately if you're on v0.2.1.

Fixed

• Fatal boot error — DoctorCommand::warn() was declared private but overrides a public parent method. PHP refused to load the class, crashing the app on boot. Renamed to printWarn() matching the existing printFail() pattern.
• Streaming emitted JSON instead of text — ChatStreamResponse serialized non-text stream events (StreamEnd, etc.) as JSON and yielded them as text deltas. Now uses duck typing on the delta property; metadata events are silently skipped.

Upgrade

composer update laraigent/larai-kit

Bug fixes for issues reported by the community (#2).

Fixed

• Stale ingestion state on returned Asset — ingestFile(), ingestText(), and ingestUrl() now return the asset with a fresh ingestion relationship pre-loaded. No more $asset->fresh() needed.
• Missing upgrade migration for scope column — users upgrading from v0.1.x no longer get "table has no column named scope". Safe for both fresh installs and upgrades.
• No warning for missing parsers — larai:doctor now shows [WARN] Pdf parser and [WARN] Docx parser when optional packages aren't installed, instead of letting users discover this via runtime crash.

Upgrade

composer update laraigent/larai-kit
php artisan migrate

Five new features, all opt-in with zero breaking changes.

Conversation Persistence (GAP-3)

• Conversation model (UUID primary key, scope-aware) + Message model
• ConversationManager — create, list, delete conversations, append messages
• ChatService::sendMessage() accepts optional conversationId — loads history from DB, persists both user + assistant turns
• When conversationId is null, behavior is identical to v0.1.x (fully backward compatible)
• New tables: ai_conversations, ai_messages

URL Ingestion (GAP-4)

• IngestionService::ingestUrl(string $url, array $scope = []) — fetch, parse, chunk, embed
• UrlFetcher with SSRF protection — blocks private IPs (10.x, 192.168.x, 127.x), file:// scheme, DNS rebinding
• HtmlParser — DOMDocument-based content extraction, strips nav/footer/script/style, extracts article/main/body
• Routes by content-type: text/html, text/plain, text/markdown
• Configurable: LARAI_URL_TIMEOUT, LARAI_URL_MAX_SIZE_MB, LARAI_URL_USER_AGENT

Streaming Chat (GAP-7)

• ChatService::streamMessage() — returns ChatStreamResponse
• Implements IteratorAggregate (foreach in PHP) + Responsable (return from controller = auto-SSE)
• Streams text deltas, then sources as final event, then done
• Persists to conversation and dispatches usage event on completion
• sendMessage() is unchanged

Usage / Cost Tracking (GAP-8)

• ChatCompleted and EmbeddingsCompleted events dispatched automatically
• Events carry: provider, model, token counts, duration, scope, conversation ID
• Usage model + ai_usage table for opt-in persistence
• Enable with LARAI_TRACK_USAGE=true — disabled by default, events always fire regardless
• RecordUsage listener writes to DB only when enabled

Web Health Endpoint (DX-4)

• HealthCheck service — extracted from DoctorCommand, returns structured JSON
• HealthController at configurable path (default _larai/health), supports ?deep=true
• DoctorCommand refactored to delegate to HealthCheck — same CLI output
• Enable with LARAI_HEALTH_ENABLED=true — disabled by default

New Files (15)

3 migrations, 3 models (Conversation, Message, Usage), 2 events, 1 listener, ConversationManager, UrlFetcher, HtmlParser, ChatStreamResponse, HealthCheck, HealthController

Upgrade

composer update laraigent/larai-kit php artisan migrate

Fixes all issues from #1. See CHANGELOG.md for full details.

Bug Fixes

• embed() crash, PHP timeout, retry/backoff, zero-chunk success, generic default prompt

New Features

• Multi-tenant scoping (prevents data leaks across customers)
• Batch embedding (embedMany) and batch vector upsert (upsertMany)
• ChatService accepts custom agents, scope, and history
• IngestionStateChanged events for pipeline observability
• larai:doctor --deep for live API testing

Upgrade

composer update laraigent/larai-kit php artisan migrate # adds scope column to ai_assets

First public release. See CHANGELOG.md for details.