A sophisticated document question-answering application built with Laravel, Livewire, and AI. Features a Linear-inspired dark theme UI for an elegant, modern experience.

• Document Ingestion: Upload or paste documents (txt/md) for processing
• Smart Chunking: Automatic text chunking with configurable overlap
• Vector Embeddings: OpenAI-powered embeddings for semantic search
• RAG Q&A: Ask questions and get AI-powered answers with source citations
• Linear-Inspired UI: Beautiful dark theme with refined typography and spacing
• Real-time Status: Monitor AI service connections and health

# Clone and install
git clone https://github.com/bmadigan/ask-my-doc.git
cd ask-my-doc
composer install && npm install

# Configure
cp .env.example .env
php artisan key:generate

# Add your OpenAI API key to .env
# OPENAI_API_KEY=sk-...

# Install Python dependencies
pip3 install -r overpass-ai/requirements.txt

# Setup database and build assets
php artisan migrate
npm run build

# Start development server
composer run dev

# Visit http://localhost:8000

• Backend: Laravel 12, PHP 8.4
• Frontend: Livewire 4, Tailwind CSS 4
• Database: SQLite with vector storage
• AI Bridge: bmadigan/overpass package via Composer
• Embeddings: OpenAI text-embedding-3-small
• Chat: OpenAI GPT-4o-mini
• Python: Vector similarity search with NumPy

• PHP 8.2+
• Composer
• Node.js & NPM
• Python 3.9+ with pip
• OpenAI API key

# Clone the repository
git clone <your-repo-url>
cd overpass-test

# Install PHP dependencies (includes bmadigan/overpass package)
composer install

# Install Node dependencies
npm install

# Install Python dependencies
pip3 install -r overpass-ai/requirements.txt

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=your-actual-api-key-here

# Run migrations
php artisan migrate

# Build frontend assets
npm run build

# Or run in development mode
npm run dev

# Start Laravel server
php artisan serve

# Or use the dev script (includes Vite, queue, and logs)
composer run dev

Visit http://localhost:8000

1. Ingest Documents

   • Navigate to "Ingest" page
   • Paste text or upload .txt/.md files
   • Configure chunk size (default: 1000 chars) and overlap (default: 200 chars)
   • Click "Chunk & Embed" to process

2. Ask Questions

   • Go to "Ask" page
   • Type your question (searches all documents automatically)
   • Get AI-powered answers with source citations

3. Monitor Status

   • Dashboard shows Overpass connection status
   • Real-time health checks for OpenAI and Python bridge
   • View recent documents and quick actions

Using the bmadigan/overpass package providing:

• OpenAI integration for embeddings and chat
• Python bridge for vector operations
• SQLite vector search with cosine similarity
• Graceful error handling and fallback responses

• documents: Stores document metadata
• chunks: Stores text chunks with embeddings (JSON)
• queries: Logs Q&A interactions for analytics

Located in overpass-ai/main.py:

• health_check: Service status verification
• create_embeddings: Generate OpenAI embeddings for text
• chat_query: Process chat completions through OpenAI
• sqlite_search: Vector similarity search with scoring
• vector_search: Generic vector operations
• analyze_data: AI-powered data analysis

The application features a Linear-inspired dark theme with:

• Color Palette: Neutral grays with subtle accent colors
• Typography: Inter font with refined spacing
• Components: Generous padding, subtle borders, smooth transitions
• Accessibility: High contrast for readability

# Run all tests
php artisan test

# Run specific test file
php artisan test tests/Feature/ExampleTest.php

# Run with filter
php artisan test --filter=testName

# Run Livewire component tests
php artisan test tests/Feature/Livewire/

Adjust in the UI or configure defaults:

• Chunk Size: 500-2000 characters
• Overlap Size: 0-500 characters

Configure in .env:

OVERPASS_EMBEDDING_MODEL=text-embedding-3-small
OVERPASS_CHAT_MODEL=gpt-4o-mini

OVERPASS_SCRIPT_PATH=/path/to/overpass-ai/main.py

# Application
APP_NAME="Ask My Doc"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

# Database
DB_CONNECTION=sqlite

# OpenAI Configuration
OPENAI_API_KEY=your-openai-api-key

# Overpass Configuration
OVERPASS_SCRIPT_PATH="${PWD}/overpass-ai/main.py"
OVERPASS_TIMEOUT=60
OVERPASS_MAX_OUTPUT=1048576
OVERPASS_EMBEDDING_MODEL=text-embedding-3-small
OVERPASS_CHAT_MODEL=gpt-4o-mini

Contributions are welcome! Please feel free to submit a Pull Request.

This project is open source and available under the MIT License.

• UI design inspired by Linear
• Powered by bmadigan/overpass package
• Built with Laravel and Livewire

If you see "Python: error" in the status card:

1. Ensure Python 3.9+ is installed
2. Install Python dependencies: pip3 install numpy openai python-dotenv
3. Check dependencies: pip3 list | grep -E "openai|numpy|dotenv"
4. Verify script path in .env
5. Test directly: python3 overpass-ai/main.py health_check '[]'

1. Verify API key is set correctly in .env
2. Check API key validity at https://platform.openai.com
3. Ensure you have sufficient credits

1. Ensure SQLite is installed
2. Check database file exists: database/database.sqlite
3. Re-run migrations if needed: php artisan migrate:fresh

For more information about the technologies used:

• Laravel Documentation
• Livewire Documentation
• OpenAI API Documentation
• Overpass Package