Transform Markdown into
Intelligent Knowledge

📖 Overview

Laravel Markdown RAG is a comprehensive Laravel package that transforms Markdown files into an AI-powered knowledge base. It uses vector embeddings, cosine similarity search, and large language models to answer user questions based on your documentation.

Requirements

🚀 Installation

1. Install via Composer
   bash Copy

   composer require nomanur/laravel-markdown-rag

2. Run Migrations
   bash Copy

   php artisan migrate

   This creates three tables:

   • histories — stores conversation messages
   • knowledge_chunks — stores text chunks, embeddings, and source metadata
   • knowledge_documents — stores metadata for each indexed markdown file
3. Publish Configuration (Optional)
   bash Copy

   php artisan vendor:publish --provider="Nomanur\LaravelMarkdownRAGServiceProvider" --tag="config"

4. Set Environment Variables
   env Copy

   OPENAI_API_KEY=your_api_key_here
   MARKDOWN_CHAT_RATE_LIMIT=100
   MARKDOWN_RERANKING=false
   MARKDOWN_QUERY_REWRITE=false
   AI_PROMPT_REWRITING=false

Publishable Components

⚙️ Configuration

The configuration file is published to config/laravel-markdown-rag.php. Here are all available options:

🏗️ System Architecture

The package operates in three distinct phases, creating a complete pipeline from markdown files to AI-powered answers:

Phase 1: Indexing

Phase 2: Chat

Phase 3: Visualization

Component Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Laravel Markdown RAG                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐   ┌──────────────┐   ┌────────────────┐  │
│  │  .md Files   │──▶│ TextSplitter │──▶│ KnowledgeDoc   │  │
│  │ (public/KB)  │   │  (chunking)  │   │ KnowledgeChunk │  │
│  └──────────────┘   └──────────────┘   └────────────────┘  │
│                           │                       │         │
│                           ▼                       ▼         │
│                    ┌──────────────┐  ┌──────────────────┐  │
│                    │ VectorService│─▶│   Database       │  │
│                    │ (embeddings) │  │  (chunks/docs)   │  │
│                    └──────────────┘  └──────────────────┘  │
│                                             │               │
│  ┌──────────────┐   ┌──────────────┐        │               │
│  │  User Chat   │──▶│KnowledgeAgent│◀───────┘               │
│  │ (Livewire)   │   │+ SearchTool  │                        │
│  └──────────────┘   └──────────────┘                        │
│         │                   │                                │
│         │  ┌────────────────┼──────────┐                    │
│         │  ▼                ▼          ▼                    │
│         │ QueryRewrite   RerankSvc   TSNE                   │
│         │ Service                     (visualization)        │
│         │  ▼                                                │
│         │ History Model                                     │
│         └───────────────────────────────────────────────────┘
│                                                             │
└─────────────────────────────────────────────────────────────┘

📚 Indexing System

Artisan Commands

php artisan markdownrag:index          # Index all .md files
php artisan markdownrag:index --clear  # Clear existing chunks first
php artisan queue:work                 # Start queue worker for background jobs

TextSplitter Strategy

The TextSplitter service intelligently chunks markdown content using a multi-strategy approach:

• Strategy 1: Split by double newlines (\n\n) — paragraph-based splitting
• Strategy 2: Split by single newlines (\n) — line-based fallback
• Strategy 3: Character-based splitting with word boundary awareness

VectorService Operations

The central service for all vector operations:

// Generate embeddings with retry logic
getEmbeddings(array $texts): array

// Store a chunk with its embedding
storeChunk(string $content, array $embedding, string $source, ?string $documentId, array $metadata): void

// Perform cosine similarity search
search(string $query, int $limit, ?string $documentId): Collection

// Reduce dimensions for visualization
reduceDimensions(array $embeddings): array

// Chunk documents and get statistics
chunkDocuments(array $documents): array
countCharacters(array $documents): int
countTokens(array $documents): int

Similarity Search Process

1. Generates an embedding for the query string
2. Performs cosine similarity search across all stored chunks
3. Optionally filters by documentId
4. Returns results sorted by similarity (highest first)

💬 Chat Interface

Routes

Livewire Components

Two chat components are provided:

RagChat (rag-chat)

• Limited to 50 messages in display
• Renders components.rag view
• Custom-styled chat interface with CSS custom properties
• Full dark mode support

WithoutFlux (without-flux)

• No message limit — shows all history
• Renders components.without-flux view
• Uses Marked.js for markdown rendering of AI responses
• Uses Tailwind CSS via CDN

KnowledgeSearchTool

The tool available to the AI agent for searching the knowledge base:

• Name: search_knowledge_base
• Parameters:
  • query (required, string) — the search query
  • document_id (optional, string) — limit search to a specific document

Search Pipeline

User Query → [Query Rewrite?] → Embedding → Similarity Search → [Rerank?] → Top 3 Results → AI Response

📈 Embedding Visualization

Access

Visit /vector-embedding while authenticated and verified.

How It Works

1. Fetches up to 100 KnowledgeChunk records from the database
2. Extracts their high-dimensional embeddings
3. Runs t-SNE (t-Distributed Stochastic Neighbor Embedding) to reduce dimensions to 2D
4. Renders a Plotly.js interactive scatter plot

Features

• Interactive hover — shows source file name and content preview
• Displays total chunk count and t-SNE algorithm info
• Dark mode support
• Empty state with instruction to run markdownrag:index if no chunks exist

⚡ Services Deep Dive

QueryRewriteService

Improves search quality by rewriting user queries before embedding generation:

Keyword Mode

Enabled when markdown_query_rewrite=true and ai_prompt_rewriting=false. Removes ~150+ English stop words to extract key terms:

"What is the best way to configure the database?" → "best way configure database"

AI Mode

Enabled when ai_prompt_rewriting=true. Uses the LLM to rephrase follow-up questions into standalone queries, incorporating the last 5 conversation messages for context. Includes exponential backoff retry logic.

RerankService

Reorders search results for improved relevance:

Keyword Mode

Enabled when markdown_reranking=true and ai_prompt_rewriting=false. Scores chunks by keyword occurrence frequency, weighted by term length. Sorts by descending score and returns top 3.

AI Mode

Enabled when ai_prompt_rewriting=true. Sends chunks to the AI with instructions to rank them by relevance. Parses the LLM's response for chunk IDs, reorders the collection, and includes a safety fallback for any missed chunks.

🗄️ Database Models

History Model

Table: histories

Relations: belongsTo(User::class)

KnowledgeChunk Model

Table: knowledge_chunks

Key Method: similaritySearch($queryEmbedding, $limit, $documentId) — performs cosine similarity search

KnowledgeDocument Model

Table: knowledge_documents

🤖 AI Components

KnowledgeAgent

The core AI agent implementing Agent, Conversational, and HasTools interfaces from laravel/ai:

• Constructor: Accepts an authenticatedized user, optional documentId, and optional KnowledgeDocument object
• instructions(): Returns system instructions — either from a custom resolver, the document's system_prompt attribute, or the config default
• messages(): Returns conversation history from the History model, filtered by user and agent='knowledge'
• tools(): Returns a single KnowledgeSearchTool instance
• timeout(): Returns 60000ms (60 seconds)

Static Customization Hooks

// Override instructions globally
KnowledgeAgent::resolveInstructionsUsing(callable $resolver);

// Override message retrieval globally
KnowledgeAgent::resolveMessagesUsing(callable $resolver);

🎨 Customization

Publishing All Components

# Publish everything at once
php artisan vendor:publish --provider="Nomanur\LaravelMarkdownRAGServiceProvider"

Service Provider Auto-Registration

The service provider automatically registers:

• Views from resources/views under the laravel-markdown-rag namespace
• Migrations from src/Database/migrations
• Routes from routes/web.php
• Livewire components: rag-chat and without-flux
• Singleton binding for laravel-markdown-rag
• Console commands

🔧 Agent & Tool Customization

Customizing Agent Instructions

use Nomanur\Ai\Agents\KnowledgeAgent;

// Globally override agent instructions via closure
KnowledgeAgent::resolveInstructionsUsing(function (User $user, ?string $documentId, ?KnowledgeDocument $document) {
    return 'Your custom system instructions here...';
});

Customizing Message Retrieval

KnowledgeAgent::resolveMessagesUsing(function (User $user) {
    return History::query()
        ->where('user_id', $user->id)
        ->where('agent', 'custom_agent')
        ->latest()
        ->take(100)
        ->get();
});

Customizing Search Tool Description

use Nomanur\Ai\Tools\KnowledgeSearchTool;

KnowledgeSearchTool::resolveDescriptionUsing(function () {
    return 'Your custom tool description...';
});

🛠️ Artisan Commands

# Index all .md files from public/knowledge-base/
php artisan markdownrag:index

# Clear existing chunks before indexing
php artisan markdownrag:index --clear

# Start queue worker for background jobs
php artisan queue:work

# Append package routes to your routes/web.php (optional)
php artisan markdownrag:route

markdownrag:index

Indexes all .md files from public/{markdown_info_path}/. Displays a progress bar during indexing and creates KnowledgeDocument records for each file.

markdownrag:route

Appends the package routes to your application's routes/web.php file. Note: Routes are automatically loaded by the service provider by default, so this command is only needed if you've manually removed the route loading.

❓ Troubleshooting

No chunks indexed

• Ensure .md files exist in public/{markdown_info_path}/
• Check file permissions on the knowledge-base directory
• Run with --clear flag if you want to re-index

AI returns empty responses

• Verify your API key is set in .env
• Check laravel/ai configuration in config/ai.php
• Ensure embeddings were generated successfully during indexing

Chat interface not loading

• Ensure Livewire is installed and properly configured
• Check that @livewireStyles and @livewireScripts are included in your layout
• Verify the user is authenticated (routes require auth middleware)

Visualization page is empty

• Run php artisan markdownrag:index to populate chunks
• Check that knowledge_chunks table has records with valid embeddings

Queue jobs not processing

• Ensure the queue worker is running: php artisan queue:work
• Check your QUEUE_CONNECTION setting in .env (use database, redis, or sync)
• For development, you can set QUEUE_CONNECTION=sync to process jobs immediately
• Monitor queue worker logs for errors: php artisan queue:listen