ragbridge / php
PHP client for the ragbridge retrieval-augmented generation service
Requires
- php: ^8.2
- php-http/discovery: ^1.20
- psr/http-client: ^1.0
- psr/http-factory: ^1.1
Requires (Dev)
- doctrine/orm: ^3.5
- laravel/pint: ^1.30
- nyholm/psr7: ^1.8
- orchestra/testbench: ^10.0||^11.0
- pestphp/pest: ^3.8
- php-http/mock-client: ^1.6
- phpstan/phpstan: ^2.2
- phpstan/phpstan-doctrine: ^2.0
- phpstan/phpstan-strict-rules: ^2.0
- symfony/cache: ^6.4||^7.0||^8.0
- symfony/config: ^6.4||^7.0||^8.0
- symfony/dependency-injection: ^6.4||^7.0||^8.0
- symfony/http-client: ^6.4||^7.0||^8.0
- symfony/http-kernel: ^6.4||^7.0||^8.0
- symfony/messenger: ^6.4||^7.0||^8.0
Suggests
- doctrine/orm: Required to sync Doctrine entities to the service (^3.5)
- illuminate/support: Required to use the Laravel integration (^12.0 or ^13.0)
- symfony/framework-bundle: Required to use the Symfony integration (^6.4, ^7.0 or ^8.0)
- symfony/http-client: Lets the Symfony integration send requests through the application's HTTP client (^6.4, ^7.0 or ^8.0)
- symfony/messenger: Required to sync Doctrine entities to the service (^6.4, ^7.0 or ^8.0)
Provides
None
Conflicts
None
Replaces
None
README
PHP client for ragbridge, a self-hosted retrieval-augmented generation (RAG) service. Upload documents, ask questions in natural language and get answers together with the sources they came from, from plain PHP, Laravel or Symfony.
The package is a small, typed client for the service's HTTP API. Retrieval, embedding and generation all happen in the service.
Read more: Bringing RAG to PHP: Architecture, Trade-offs, and Measurements, an overview of the service, this client, and the design decisions behind them.
Features
- Upload PDF, Markdown and plain-text documents, streamed from disk, and list, fetch and delete them
- Ask questions and get an answer with its sources; choose the retrieval mode and the number of chunks, and optionally see why each chunk was found
- Search without generating an answer, ask multi-step questions with the agent, and check that the service is alive and ready
- Keep documents identified by your own id in step with your records, and, in Laravel and Symfony, sync Eloquent models or Doctrine entities automatically through a queue
- Optional retries with exponential backoff for transient failures, off by default
- Typed, immutable response objects instead of arrays
- One exception hierarchy for authentication, validation, transport and server errors
- Works with any PSR-18 HTTP client, with no hard dependency on Guzzle
- Laravel service provider, configuration and facade, and a Symfony bundle
Requirements
- PHP 8.2 or later
- A running ragbridge service and an API key for it (see the quick start). Documents identified by an id of your application need service 1.2.0 or later.
- A PSR-18 HTTP client and PSR-17 factories, for example Guzzle or Symfony HttpClient with
nyholm/psr7. Laravel already includes one.
Installation
composer require ragbridge/php
If your project has no HTTP client yet, install one as well, for example
composer require guzzlehttp/guzzle. The package finds the client that is installed. For
Laravel and Symfony, follow the framework guides below.
Documentation
| Guide | What it covers |
|---|---|
| Quick start | From starting the service to a first answer, in plain PHP, Laravel and Symfony |
| Usage | Creating a client, uploading documents, asking questions and handling errors |
| Laravel | Installation, configuration, facade and testing |
| Symfony | Bundle setup, configuration and the HTTP client |
| Sync | Keeping Eloquent models or Doctrine entities in step with the service through a queue |
| Example application | A small upload-and-ask app to run and read |
| Versioning | The public API that semantic versioning covers |
| Roadmap, Changelog, Decisions | Where the project is going, what changed, and why |
Supported versions
| Component | Versions |
|---|---|
| PHP | 8.2, 8.3, 8.4 |
| Laravel | 12, 13 |
| Symfony | 6.4, 7, 8 |
All of them are tested in CI on every change.
Versioning
The package follows semantic versioning. What counts as public API is defined in docs/versioning.md.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md first. To report a security issue, follow SECURITY.md.
License
Released under the MIT License.