Getting Started

Minimal Setup

Installation

composer require laraigent/larai-kit
php artisan vendor:publish --provider="LarAIgent\LarAIKit\LarAIKitServiceProvider" --tag="config"

Publish migrations and run:

php artisan migrate

Configure AI Provider Add your API keys to .env (e.g., OPENAI_API_KEY) and set the default provider in config/larai-kit.php:
```
'providers' => [
    'default' => 'openai',
],
```

First Use Case: Document Ingestion Upload a PDF/DOCX via a controller:

use LarAIgent\LarAIKit\Facades\Document;

public function ingestDocument(Request $request) {
    $file = $request->file('document');
    $document = Document::ingest($file)->save();
    return response()->json(['id' => $document->id]);
}

Query the Vector Store

use LarAIgent\LarAIKit\Facades\VectorSearch;

$results = VectorSearch::search('What is RAG?', 3);

Where to Look First

Docs: LarAI Kit Documentation (check for README.md and docs/ folder in the repo).
Config: config/larai-kit.php for provider settings, chunking logic, and multi-tenancy.
Migrations: database/migrations/ for vector store tables (e.g., vector_documents, vector_chunks).

Implementation Patterns

Core Workflows

1. Document Ingestion Pipeline

Chunking: Configure chunk size/overlap in config/larai-kit.php:
```
'chunking' => [
    'size' => 512,
    'overlap' => 50,
],
```

Batch Processing: Use Document::ingestBatch() for bulk uploads:

$documents = collect([$file1, $file2])->each->ingest()->toArray();
Document::ingestBatch($documents)->process();

2. RAG Querying

Basic RAG:

$response = VectorSearch::rag('Explain Laravel RAG', 3, 'gpt-3.5-turbo');

Custom Prompt Templates: Override defaults in app/Providers/LarAIKitServiceProvider.php:

public function boot() {
    LarAIKit::setRagTemplate(function ($query, $context) {
        return "Answer using ONLY this context: {$context}";
    });
}

3. Streaming Chat

Real-Time Responses:

$stream = Chat::stream('What is Laravel?', [
    'model' => 'gpt-4',
    'temperature' => 0.3,
]);
return response()->stream(fn () => $stream);

Multi-Turn Conversations:

$conversation = Chat::start('User', 'Hello');
$conversation->reply('Bot', 'Hi there!');
$response = $conversation->ask('How are you?');

4. Multi-Tenant Scoping

Automatic Tenant Isolation:

LarAIKit::setTenant('tenant_id_123');
$results = VectorSearch::search('Query'); // Only searches tenant_id_123

Manual Override:

VectorSearch::forTenant('tenant_id_456')->search('Query');

Integration Tips

Laravel AI SDK Compatibility: Use existing Laravel\AI\ classes (e.g., Laravel\AI\Services\OpenAI) alongside LarAIKit for hybrid workflows.

Event Listeners: Extend document ingestion with listeners:

Document::ingested(function ($document) {
    // Post-process chunks (e.g., log, index elsewhere)
});

Queue Jobs: Offload heavy processing (e.g., chunking) to queues:
```
Document::ingest($file)->dispatchSyncOn('chunking-queue');
```

Gotchas and Tips

Pitfalls

Vector Store Mismatches
- Issue: Using pgvector without the correct extension installed.
- Fix: Run CREATE EXTENSION vector; in PostgreSQL before migrating.
- Debug: Check config/larai-kit.php for vector_store setting and ensure it matches your DB setup.
Chunking Overhead
- Issue: Large documents (>10MB) may time out during chunking.
- Fix: Increase PHP max_execution_time or process in chunks:
```
Document::ingest($file)->chunkSize(1024)->overlap(100)->save();
```

Multi-Tenancy Leaks

Issue: Forgetting to set the tenant context before queries.

Fix: Use middleware to auto-set tenants:

public function handle(Request $request, Closure $next) {
    LarAIKit::setTenant(auth()->user()->tenant_id);
    return $next($request);
}

Rate Limiting
- Issue: Hitting API limits during batch operations.
- Fix: Configure retry logic in config/larai-kit.php:
```
'retry' => [
    'max_attempts' => 3,
    'delay' => 1000, // ms
],
```

Debugging

Log Chunks: Enable chunk logging in config:
```
'debug' => [
    'log_chunks' => true,
],
```
Check storage/logs/larai-kit.log for chunk boundaries.
Vector Search Queries: Inspect raw queries with:
```
VectorSearch::enableQueryLogging();
```

Extension Points

Custom Vector Stores

Implement LarAIgent\LarAIKit\Contracts\VectorStore for unsupported databases (e.g., Milvus):

class MilvusStore implements VectorStore {
    public function search($query, $limit) { ... }
}

'vector_stores' => [
    'milvus' => \App\Services\MilvusStore::class,
],

Embedding Providers

Extend LarAIgent\LarAIKit\Contracts\EmbeddingProvider for custom models:

class CustomEmbeddingProvider implements EmbeddingProvider {
    public function embed($text) { ... }
}

Bind in AppServiceProvider:

LarAIKit::extend('custom', function () {
    return new CustomEmbeddingProvider();
});

Post-Processing Hooks

Modify chunks after ingestion:

Document::ingested(function ($document) {
    $document->chunks()->each(function ($chunk) {
        // Sanitize, translate, or enrich chunks
    });
});

Configuration Quirks

Default Model Fallback: If config/larai-kit.php doesn’t specify a default model, it uses gpt-3.5-turbo.
Chunk Overlap: Set overlap to 0 for non-overlapping chunks (faster but less context).
Streaming Timeout: Adjust config/larai-kit.php streaming_timeout (default: 60 seconds) for long responses.

Pro Tips

Hybrid Search: Combine keyword and vector search:

$results = VectorSearch::hybridSearch('Laravel OR "AI agent"', 5);

Caching: Cache frequent queries:

$results = Cache::remember("rag_{$query}", now()->addHours(1), function () use ($query) {
    return VectorSearch::search($query, 3);
});

Monitor Usage: Track token consumption with middleware:

public function handle($request, Closure $next) {
    $startTokens = LarAIKit::getTokenCount();
    $response = $next($request);
    $usedTokens = LarAIKit::getTokenCount() - $startTokens;
    // Log or alert on high usage
    return $response;
}

Larai Kit Laravel Package