README

🇵🇸 Free Palestine

🤖💬 Chat With Your Logs Using Smart AI 💬🤖

Transform debugging from tedious to effortless! 🔍 → ⚡
Stop digging through dashboards and complex queries. Just ask your logs directly in plain English.

🐌 Traditional vs ⚡ AI-Powered

🐌 Traditional Way

Open Kibana/ElasticSearch dashboards
Write complex Datadog queries
Manual grep through log files
Filter thousands of log entries
Correlate timestamps & request IDs by hand
Spend hours finding root causes

Result: Hours of manual work 😩

⚡ AI Agent Way

// Just ask naturally!
$agent->ask("Why did payments fail?");
$agent->ask("What caused the 3 PM outage?");
$agent->ask("Show me timeout patterns");
$agent->ask("How many users affected?");

Result: Instant intelligent answers 🧠

📚 Docs & Examples

Live docs: ramyhakam.github.io/ai-log-inspector-agent

📚 Playground To Validate with your own logs and AI platform.

Playground: ramyhakam.github.io/ai-log-inspector-agent

💬 Real Examples - Ask Anything!

$agent = new LogInspectorAgent($platform, $model, $store);

// 🚨 Checkout Issues
$result = $agent->ask('Why did the last checkout request fail?');
// → "Payment gateway timeout after 30 seconds. The last 3 checkout attempts 
//    all failed with 'gateway_timeout' errors between 14:23-14:25."

// 🔍 Database Problems  
$result = $agent->ask('Show me all database errors from the last hour');
// → "Found 12 database connection failures. Pattern shows connection pool 
//    exhaustion starting at 15:30, affecting user authentication service."

// 🌊 Performance Issues
$result = $agent->ask('What caused the sudden spike in API response times?');
// → "Memory leak in Redis connection causing 2.5s delays. Started after 
//    deployment at 13:45, affecting 847 requests per minute."

// 🔐 Security Monitoring
$result = $agent->ask('Are there any suspicious login attempts?');
// → "Detected brute force attack from IP 192.168.1.100. 156 failed login 
//    attempts in 5 minutes targeting admin accounts."

// 📊 Impact Assessment
$result = $agent->ask('How many users were affected by the outage?');
// → "Based on error logs, approximately 2,341 unique users experienced 
//    service disruption between 14:15-14:32 during the database incident."

⚠️ Note - Built on Symfony AI (experimental). The package itself is NOT production-ready; platform maturity depends on your provider and deployment setup.

✨ What Makes It Special

🔍 Semantic Search - Understands context, not just keywords
🧠 AI Analysis - Explains what happened and why
⚡ Lightning Fast - Get answers in seconds, not hours
🛠️ Tool-Based - Extensible architecture with Symfony AI
📊 Vector Powered - Smart similarity matching
🔄 Fallback Ready - Works even when AI is unavailable
🌐 Multi-Platform - OpenAI, Anthropic, and Ollama support
🧩 Multi-Tool - log_search + request_context for request tracing
📂 File Upload Indexing - Upload logs and index via LogFileIndexer
💬 Session Chat - Persisted chat history for multi-turn investigations
🧪 Production Demo - Check Playground Demo

🚀 Quick Start

Requirements

PHP 8.4+
Composer 2+

Install

composer require hakam/ai-log-inspector-agent

Setup & Use

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Hakam\AiLogInspector\Agent\LogInspectorAgent;
use Hakam\AiLogInspector\Enum\PlatformEnum;
use Hakam\AiLogInspector\Platform\LogDocumentPlatformFactory;
use Hakam\AiLogInspector\Retriever\LogRetriever;
use Hakam\AiLogInspector\Store\VectorLogDocumentStore;
use Hakam\AiLogInspector\Tool\LogSearchTool;
use Hakam\AiLogInspector\Tool\RequestContextTool;
use Symfony\AI\Store\Bridge\Local\InMemoryStore;

// Brain platform (LLM) + Embedding platform
$brainPlatform = LogDocumentPlatformFactory::createBrainPlatform(
    PlatformEnum::OPENAI,
    [
        'api_key' => $_ENV['OPENAI_API_KEY'],
        'model' => 'gpt-4o-mini',
        'model_capabilities' => ['text', 'tool_calling'],
    ]
);
$embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform(
    PlatformEnum::OPENAI,
    [
        'api_key' => $_ENV['OPENAI_API_KEY'],
        'model' => 'text-embedding-3-small',
    ]
);

// Vector store + retriever
$store = new VectorLogDocumentStore(new InMemoryStore());
$retriever = new LogRetriever(
    embeddingPlatform: $embeddingPlatform->getPlatform(),
    model: 'text-embedding-3-small',
    logStore: $store
);

// Tools + agent
$logSearchTool = new LogSearchTool($store, $retriever, $brainPlatform);
$requestContextTool = new RequestContextTool($store, $retriever, $brainPlatform);
$agent = new LogInspectorAgent($brainPlatform, [$logSearchTool, $requestContextTool]);

// Index a few logs (in-memory)
use Hakam\AiLogInspector\Document\LogDocumentFactory;
use Hakam\AiLogInspector\Indexer\LogDocumentIndexer;

$indexer = new LogDocumentIndexer(
    embeddingPlatform: $embeddingPlatform->getPlatform(),
    model: 'text-embedding-3-small',
    logStore: $store
);

$docs = [
    LogDocumentFactory::createFromString('[2024-01-29 14:23:45] ERROR: Payment gateway timeout'),
    LogDocumentFactory::createFromString('[2024-01-29 14:23:46] ERROR: Stripe API returned 504'),
];
$indexer->indexLogDocuments($docs);

// Ask questions!
$result = $agent->ask('Why did the checkout fail?');
echo $result->getContent();

Advanced Questions

// Root cause analysis
$agent->ask('What caused the 500 errors in payment service?');

// Timeline investigation  
$agent->ask('What happened before the database failure?');

// Pattern discovery
$agent->ask('Are there recurring memory leak patterns?');

// Security investigation
$agent->ask('Suspicious auth patterns from IP 192.168.1.100?');

Response Structure

// Tool responses are structured (LogSearchTool / RequestContextTool / Playground API)
[
    'success' => true,                    // Found relevant logs?
    'reason' => 'Payment gateway timeout caused...',  // AI explanation
    'evidence_logs' => [                  // Supporting evidence
        [
            'id' => 'log_001',
            'content' => '[2024-01-15] ERROR: ...',
            'timestamp' => '2024-01-15T14:23:45Z',
            'level' => 'error',
            'source' => 'payment-service', 
            'tags' => ['payment', 'timeout']
        ]
    ]
]

LogInspectorAgent::ask() returns a ResultInterface (use getContent() for the AI response). The structured array above is the tool-level output used internally and by the playground API.

⚙️ Configuration

AI Platform Options

use Hakam\AiLogInspector\Enum\PlatformEnum;
use Hakam\AiLogInspector\Platform\LogDocumentPlatformFactory;

// OpenAI (brain + embeddings)
$brainPlatform = LogDocumentPlatformFactory::createBrainPlatform(
    PlatformEnum::OPENAI,
    [
        'api_key' => $_ENV['OPENAI_API_KEY'],
        'model' => 'gpt-4o-mini',
        'model_capabilities' => ['text', 'tool_calling'],
    ]
);
$embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform(
    PlatformEnum::OPENAI,
    [
        'api_key' => $_ENV['OPENAI_API_KEY'],
        'model' => 'text-embedding-3-small',
    ]
);

// Anthropic (brain only, embeddings via OpenAI or local)
$brainPlatform = LogDocumentPlatformFactory::createBrainPlatform(
    PlatformEnum::ANTHROPIC,
    [
        'api_key' => $_ENV['ANTHROPIC_API_KEY'],
        'model' => 'claude-3-5-sonnet-20241022',
        'model_capabilities' => ['text', 'tool_calling'],
    ]
);

// Ollama (local brain + local embeddings)
$brainPlatform = LogDocumentPlatformFactory::createBrainPlatform(
    PlatformEnum::OLLAMA,
    [
        'host' => 'http://localhost:11434',
        'model' => 'llama3.2:1b',
        'model_capabilities' => ['text', 'tool_calling'],
    ]
);
$embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform(
    PlatformEnum::OLLAMA,
    [
        'host' => 'http://localhost:11434',
        'model' => 'nomic-embed-text',
    ]
);

Vector Store Options

// Memory (testing)
use Symfony\AI\Store\Bridge\Local\InMemoryStore;
$store = new InMemoryStore();

// Production stores
use Symfony\AI\Store\Bridge\Chroma\ChromaStore;
use Symfony\AI\Store\Bridge\Pinecone\PineconeStore;

$store = new ChromaStore($config);
$store = new PineconeStore($config);

Custom System Prompts

$customPrompt = 'You are a security log analyzer. Focus on threats and incidents.';

$agent = new LogInspectorAgent($platform, [$logSearchTool, $requestContextTool], $customPrompt);

🧰 Tools & Capabilities

LogSearchTool (log_search)

Semantic or keyword search over indexed logs
Returns structured results with evidence logs and AI analysis

RequestContextTool (request_context)

Trace a request, session, or trace ID across distributed logs
Returns chronological log context for end-to-end debugging

Multi-tool agent example

See examples/multi-tool-agent-example.php for intelligent tool selection

💬 Conversational Debugging

use Hakam\AiLogInspector\Chat\LogInspectorChatFactory;

$chat = LogInspectorChatFactory::createSession(
    sessionId: 'incident-2026-02-06',
    platform: $platform,
    searchTool: $logSearchTool,
    contextTool: $requestContextTool,
    storagePath: sys_get_temp_dir() . '/log-inspector-sessions'
);

$chat->startInvestigation('Payment outage - Feb 6, 2026');
$chat->ask('What payment errors occurred?');
$chat->followUp('Were there any database issues around that time?');
$summary = $chat->summarize();
echo $summary->getContent();

🧪 Playground API

Run the multi-platform playground API:

php -S localhost:8080 examples/playground-api.php

Key endpoints:

GET /health
POST /init (preload sample logs and cache vectors)
POST /upload (upload log file, index with LogFileIndexer)
GET /logs
GET /init-status
POST /chat
POST /reset

Features:

Separate brain and embedding models per request
OpenAI, Anthropic, or Ollama per request
Session-based chat history
Cached vector store per session

Environment variables:

OLLAMA_URL (default: http://localhost:11434)
OLLAMA_MODEL (default: llama3.1:8b)
CHROMA_URL (default: http://localhost:8000)
CHROMA_COLLECTION (default: log-inspector)
REDIS_URL (default: redis://localhost:6379)
ALLOWED_ORIGINS (default: *)

📚 Local Docs

The documentation site content is in website/docs.

Live docs: ramyhakam.github.io/ai-log-inspector-agent

🧪 Testing & Validation - REAL WORKING PACKAGE

🎯 PROOF IT WORKS: Comprehensive end-to-end tests with real Ollama integration.

✅ Full Functional Test Suite

13/13 tests PASSING with real Ollama (llama3.2:1b):

💳 Payment system analysis - Real e-commerce error investigation
🛡️ Security incident detection - Brute force & auth failure analysis
💾 Database performance issues - Connection timeouts & query problems
🐛 Application error analysis - Exception handling & memory issues
⚡ Performance monitoring - API response time analysis
📊 50+ realistic PHP logs from actual applications

🏃‍♂️ Run Tests Yourself

# Setup Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3.2:1b

# Run full test suite
OLLAMA_MODEL=llama3.2:1b vendor/bin/phpunit test/Functional/

Results: 104 successful assertions, 2-10s response times, multi-platform support proven.

🚀 Extend Testing

Want to test with YOUR logs? Add more realistic log examples:

Expand test/fixtures/logs/ with logs from:
- ✅ Laravel applications - Real Laravel/Eloquent errors (included)
- ✅ Kubernetes pods - OOMKilled, CrashLoopBackOff, resource issues (included)
- ✅ Microservices - Circuit breakers, service mesh, distributed tracing (included)
- Symfony applications
- API gateways
- Docker containers
Test real scenarios:
- "What caused the 3 AM outage?"
- "Show me memory leaks in user service"
- "Find all failed credit card transactions"
- "Analyze API rate limiting errors"
Validate with your AI platform:
- OpenAI (full semantic search)
- Anthropic (full semantic search)
- Ollama (intelligent keyword fallback)

This package works with REAL data and REAL AI models - test it yourself!

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open Pull Request

Made with ❤️ for developers who hate digging through logs!

Transform your debugging experience today 🚀

hakam / ai-log-inspector-agent

Maintainers

Details