nomanur/laravel-markdown-rag

Transform Markdown files into AI-ready context with smart chunking and RAG capabilities for Laravel

0.2.5 2026-03-17 14:01 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0
• laravel/ai: ^0.2.5
• livewire/livewire: ^3.0|^4.0

Requires (Dev)

• orchestra/testbench: ^9.16
• phpunit/phpunit: ^10.0|^11.0

MIT

• nomanur rahman

• php
• markdown
• laravel
• ai
• nomanur
• rag
• laravel-markdown-rag

README

Laravel Markdown RAG is a package that allows you to build a Retrieval-Augmented Generation (RAG) system using Markdown files as your knowledge base, powered by Gemini AI.

Installation

You can install the package via composer:

composer require nomanur/laravel-markdown-rag

Publish the package assets and configuration:

php artisan vendor:publish --provider="Nomanur\LaravelMarkdownRAGServiceProvider"
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Run the migrations:

php artisan migrate

Configuration

Add the following environment variables to your .env file:

GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.5-flash
AI_EMBEDDING_PROVIDER=gemini
AI_DEFAULT_PROVIDER=gemini
MARKDOWN_INFO_PATH=knowledge-base
MARKDOWN_EMBEDDING_BATCH_SIZE=50
MARKDOWN_AI_RETRY_MAX_ATTEMPTS=3
MARKDOWN_QUERY_REWRITE=false
MARKDOWN_RERANKING=false

• MARKDOWN_CHAT_RATE_LIMIT: 5 (optional) if you want to rate the limit for the chat.
• MARKDOWN_INFO_PATH: (optional) the path to the markdown files in the public directory.
• MARKDOWN_EMBEDDING_BATCH_SIZE: (optional) the number of chunks to process in a single embedding request (default: 50).
• MARKDOWN_AI_RETRY_MAX_ATTEMPTS: (optional) the maximum number of retry attempts for AI requests (default: 3).
• MARKDOWN_QUERY_REWRITE: (optional) whether to enable query rewriting for better retrieval (default: false).
• MARKDOWN_RERANKING: (optional) whether to enable reranking of search results (default: false).

To use the configuration, update the code in config/ai.php with:

'default' => env('AI_DEFAULT_PROVIDER', 'ollama'),
'default_for_images' => env('AI_IMAGE_PROVIDER', 'gemini'),
'default_for_audio' => env('AI_AUDIO_PROVIDER', 'openai'),
'default_for_transcription' => env('AI_TRANSCRIPTION_PROVIDER', 'openai'),
'default_for_embeddings' => env('AI_EMBEDDING_PROVIDER', 'openai'),
'default_for_reranking' => env('AI_RERANKING_PROVIDER', 'cohere'),

'providers' => [
    'gemini' => [
        'driver' => 'gemini',
        'key' => env('GEMINI_API_KEY'),
        'models' => [
            'text' => [
                'default' => env('GEMINI_MODEL', 'gemini-1.5-flash'),
                'cheapest' => env('GEMINI_MODEL_CHEAPEST', 'gemini-1.5-flash'),
                'smartest' => env('GEMINI_MODEL_SMARTEST', 'gemini-2.0-pro-exp-02-05'),
            ],
        ],
    ],
],

Usage

1. Register Routes

Run the following command to register the necessary routes:

php artisan markdownrag:route

2. Setup Knowledge Base

Create a folder for your markdown files within the public directory. By default, this is public/knowledge-base, but you can change it using the MARKDOWN_INFO_PATH environment variable. Add your .md files there.

Example:

public/
└── knowledge-base/
    ├── company/
    │   ├── file1.md
    │   ├── file2.md
    │   └── file3.md
    └── product/
        ├── file1.md
        ├── file2.md
        └── file3.md

3. Indexing

Index your markdown files to make them searchable:

php artisan markdownrag:index

4. Accessing the Interface

You can access the chat interface at the following URL: your-domain.com/markdownrag

5. Customizing Message History

By default, KnowledgeAgent retrieves messages from the History model. You can customize how messages are resolved using one of the following options:

Option 1: Global override in AppServiceProvider

Use the resolveMessagesUsing static method to customize message resolution globally:

use Nomanur\Ai\Agents\KnowledgeAgent;
use Nomanur\Models\History;
use Laravel\Ai\Messages\Message;

KnowledgeAgent::resolveMessagesUsing(function ($agent) {
    return History::where('user_id', $agent->user->id)
        ->where('agent', 'knowledge')
        ->latest()
        ->skip(1) // Your custom skip logic
        ->when(config('laravel-markdown-rag.markdown_chat_rate_limit'), fn($query, $limit) => $query->limit($limit))
        ->get()
        ->reverse()
        ->map(fn($message) => new Message($message->role, $message->content))
        ->all();
});

Option 2: Inheritance in another project

If you are extending the agent in another project, you can override the messages() method directly:

use Nomanur\Ai\Agents\KnowledgeAgent;
use Nomanur\Models\History;
use Laravel\Ai\Messages\Message;

class ExtendedKnowledgeAgent extends KnowledgeAgent
{
    public function messages(): iterable
    {
        // Custom implementation with skip(1)
        return History::where('user_id', $this->user->id)
            ->where('agent', 'knowledge')
            ->latest()
            ->skip(1)
            ->when(config('laravel-markdown-rag.markdown_chat_rate_limit'), fn($query, $limit) => $query->limit($limit))
            ->get()
            ->reverse()
            ->map(fn($message) => new Message($message->role, $message->content))
            ->all();
    }
}

6. Customizing Instructions

By default, KnowledgeAgent retrieves its instructions from the associated document's system_prompt or falls back to a default prompt. You can customize the agent's instructions using one of the following options:

Option 1: Global override in AppServiceProvider

Use the resolveInstructionsUsing static method to customize instructions globally:

use Nomanur\Ai\Agents\KnowledgeAgent;

KnowledgeAgent::resolveInstructionsUsing(function (KnowledgeAgent $agent) {
    if ($agent->document) {
        return "You are an expert on {$agent->document->name}. Answer questions strictly based on it.";
    }
    
    return "You are a helpful AI assistant.";
});

Option 2: Inheritance in another project

You can also override the instructions() method directly by extending the agent:

use Nomanur\Ai\Agents\KnowledgeAgent;
use Stringable;

class ExtendedKnowledgeAgent extends KnowledgeAgent
{
    public function instructions(): Stringable|string
    {
        return "You are a highly capable and friendly assistant.";
    }
}

7. Customizing Tool Descriptions

You can also override the description of the KnowledgeSearchTool globally. This is useful if you want to give the AI more specific instructions about when to use the search tool:

use Nomanur\Ai\Tools\KnowledgeSearchTool;

KnowledgeSearchTool::resolveDescriptionUsing(function (KnowledgeSearchTool $tool) {
    return "Search the internal knowledge base for company policies and HR documents only.";
});

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• nomanur rahman
• All Contributors

License

The MIT License (MIT). Please see License File for more information.