ahmednour / eloquent-rag
The Eloquent synchronization layer for Laravel AI's RAG stack — model lifecycle sync, dependency tracking, invalidation, chunk management, and rebuild tooling.
Requires
- php: ^8.3
- illuminate/database: ^13.29
- illuminate/queue: ^13.29
- illuminate/support: ^13.29
- laravel/ai: ^0.11.2
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.17
- orchestra/testbench: ^11.0
- pestphp/pest: ^4.0
- pestphp/pest-plugin-laravel: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.1.0-beta.1
- dev-embed-can-waste-a-provider-call-on-content-that
- dev-define-explicit-queue-retry-backoff-timeout-uniq
- dev-readme-status-installation-sections-are-stale-cl
- dev-syncragdocument-aborts-the-rest-of-its-batch-whe
- dev-specify-and-test-the-contract-when-rag-connectio
- dev-document-the-contract-of-ragsearch-scope-what-th
- dev-add-concurrency-idempotency-tests-for-dependency
- dev-embed-silently-embeds-an-empty-string-when-a-chu
- dev-validate-embedding-provider-response-count-and-d
- dev-race-document-status-can-flip-to-synced-on-a-sta
- dev-expand-backend-integration-and-vector-lifecycle-2
- dev-expand-backend-integration-and-vector-lifecycle
- dev-validate-and-cap-the-rag-search-limit
- dev-support-or-explicitly-document-custom-eloquent-d
- dev-prevent-stale-embeddings-when-sync-and-embed-job
- dev-add-real-mariadb-and-postgresql-pgvector-integra
- dev-make-rag-document-deletion-transaction-safe
- dev-preserve-semantic-ordering-during-canonicalizati
- dev-introduce-a-tokenizer-abstraction-for-model-awar
- dev-validate-declared-dependency-relation-paths-duri
- dev-add-real-mariadb-and-postgresql-vector-integrati-3
- dev-add-real-mariadb-and-postgresql-vector-integrati-2
- dev-add-real-mariadb-and-postgresql-vector-integrati
- dev-add-configurable-similarity-threshold-to-rag-sea
- dev-add-document-level-score-aggregation-for-chunk-b
- dev-invalidate-embeddings-when-embedding-configurati
- dev-invalidate-chunk-embeddings-when-chunk-content-c
- dev-test-suite-fails-once-ci-can-actually-run-it-vec
This package is auto-updated.
Last update: 2026-09-15 14:44:06 UTC
README
The Eloquent synchronization layer for Laravel AI's RAG stack.
This package does not implement vector search. It integrates Eloquent models with Laravel's AI and vector capabilities, providing model lifecycle synchronization, dependency tracking, invalidation, chunk management, and rebuild tooling.
Status
All five phases of the build plan are complete: dependency-graph spike,
document/chunk model, Eloquent lifecycle, Laravel AI integration, CLI &
operability, and release readiness. v0.1.0-beta.1 is tagged and
published on Packagist.
CI (see .github/workflows/tests.yml) runs the
acceptance suites against real MariaDB 11.7 and PostgreSQL+pgvector service
containers across the supported PHP/Laravel matrix, with a guard that fails
the build if either suite silently skips; see
docs/benchmarks.md and the acceptance tests under
tests/Integration/ for exactly what that does and doesn't prove. It's
tagged as a beta: correctness-critical paths are implemented and covered by
unit/feature tests plus the real-backend acceptance suites, but the package
has no production usage history yet, so treat it accordingly.
Requirements
| Target | Supported | Requirement |
|---|---|---|
| MariaDB 11.7+ | ✅ | Laravel 13.29+ (vector query builder API) |
| PostgreSQL + pgvector | ✅ | Laravel 13.x |
| Plain MySQL 8.x | ❌ | No native vector backend — not supported |
See docs/backend-support.md for the full picture (including why the check is stricter than Laravel's own) or ADR-0003 for the original decision record.
Installation
composer require ahmednour/eloquent-rag
(Published on Packagist as of v0.1.0-beta.1 — a beta with no production
usage history yet. See docs/installation.md for the
full setup.)
Documentation
- docs/installation.md
- docs/definition-api.md —
HasRag,toRagDefinition(), sync/embed/search - docs/dependency-model.md — how documents declare and track dependencies
- docs/fanout-behavior.md — batching, coalescing, and the two limitations you need to know about
- docs/backend-support.md — the support matrix and what
rag:doctorchecks - docs/tokenization.md — the
Tokenizercontract and plugging in model-aware chunk sizing - docs/rebuild-and-migration.md — choosing between
rag:sync/rag:rebuild/rag:prune/rag:forget - docs/benchmarks.md — fan-out at 10k/100k/1M documents, published honestly
- docs/principles.md — core principle + explicit non-goals
- docs/adr/ — Architecture Decision Records
Roadmap
Development followed a phased plan: dependency-graph spike → document/chunk
model → Eloquent lifecycle → Laravel AI integration → CLI & operability →
release. All five phases are complete. See
.orca/drops/eloquent-rag-build-plan.md for the full plan and
docs/spikes/0001-dependency-graph.md for the spike that validated the
riskiest part of the design before any of it was built.
License
MIT. See LICENSE.