ragdoll 0.1.10 → 0.1.12

data/README.md

@@ -1,7 +1,7 @@
-<div align="center" style="background-color: yellow; color: black; padding: 20px; margin: 20px 0; border: 2px solid black; font-size: 48px; font-weight: bold;">
-  ⚠️ CAUTION ⚠️<br />
-  Software Under Development by a Crazy Man
-</div>
+> [!CAUTION]<br />
+> **Software Under Development by a Crazy Man**<br />
+> Gave up on the multi-modal vectorization approach,<br />
+> now using a unified text-based RAG architecture.
 <br />
 <div align="center">
   <table>
@@ -12,7 +12,8 @@
         </a>
       </td>
       <td width="50%" valign="top">
-        <p>Multi-modal RAG (Retrieval-Augmented Generation) is an architecture that integrates multiple data types (such as text, images, and audio) to enhance AI response generation. It combines retrieval-based methods, which fetch relevant information from a knowledge base, with generative large language models (LLMs) that create coherent and contextually appropriate outputs. This approach allows for more comprehensive and engaging user interactions, such as chatbots that respond with both text and images or educational tools that incorporate visual aids into learning materials. By leveraging various modalities, multi-modal RAG systems improve context understanding and user experience.</p>
+        <p><strong>🔄 NEW: Unified Text-Based RAG Architecture</strong></p>
+        <p>Ragdoll has evolved to a unified text-based RAG (Retrieval-Augmented Generation) architecture that converts all media types—text, images, audio, and video—to comprehensive text representations before vectorization. This approach enables true cross-modal search where you can find images through their AI-generated descriptions, audio through transcripts, and all content through a single, powerful text-based search index.</p>
       </td>
     </tr>
   </table>
@@ -20,62 +21,66 @@
 
 # Ragdoll
 
-Database-oriented multi-modal RAG (Retrieval-Augmented Generation) library built on ActiveRecord. Features PostgreSQL + pgvector for high-performance semantic search, polymorphic content architecture, and dual metadata design for sophisticated document analysis.
+**Unified Text-Based RAG (Retrieval-Augmented Generation) library built on ActiveRecord.** Features PostgreSQL + pgvector for high-performance semantic search with a simplified architecture that converts all media types to searchable text.
+
+RAG does not have to be hard. The new unified approach eliminates the complexity of multi-modal vectorization while enabling powerful cross-modal search capabilities. See: [https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/)
+
+## 🆕 **What's New: Unified Text-Based Architecture**
+
+Ragdoll 2.0 introduces a revolutionary unified approach:
 
-RAG does not have to be hard.  Every week its getting simpler.  The frontier LLM providers are starting to encorporate RAG services.  For example OpenAI offers a vector search service.  See: [https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/](https://0x1eef.github.io/posts/an-introduction-to-rag-with-llm.rb/)
+- **All Media → Text**: Images become comprehensive descriptions, audio becomes transcripts
+- **Single Embedding Model**: One text embedding model for all content types
+- **Cross-Modal Search**: Find images through descriptions, audio through transcripts
+- **Simplified Architecture**: No more complex STI (Single Table Inheritance) models
+- **Better Search**: Unified text index enables more sophisticated queries
+- **Migration Path**: Smooth transition from the previous multi-modal system
 
 ## Overview
 
-Ragdoll is a database-first, multi-modal Retrieval-Augmented Generation (RAG) library for Ruby. It pairs PostgreSQL + pgvector with an ActiveRecord-driven schema to deliver fast, production-grade semantic search and clean data modeling. Today it ships with robust text processing; image and audio pipelines are scaffolded and actively being completed.
+Ragdoll is a database-first, unified text-based Retrieval-Augmented Generation (RAG) library for Ruby. It pairs PostgreSQL + pgvector with an ActiveRecord-driven schema to deliver fast, production-grade semantic search through a simplified unified architecture.
 
-The library emphasizes a dual-metadata design: LLM-derived semantic metadata for understanding content, and system file metadata for managing assets. With built-in analytics, background processing, and a high-level API, you can go from ingest to answer quickly—and scale confidently.
+The library converts all document types to rich text representations: PDFs and documents are extracted as text, images are converted to comprehensive AI-generated descriptions, and audio files are transcribed. This unified approach enables powerful cross-modal search while maintaining simplicity.
 
-### Why Ragdoll?
+### Why the New Unified Architecture?
 
-- Database-first foundation on ActiveRecord (PostgreSQL + pgvector only) for performance and reliability
-- Multi-modal architecture (text today; image/audio next) via polymorphic content design
-- Dual metadata model separating semantic analysis from file properties
-- Provider-agnostic LLM integration via `ruby_llm` (OpenAI, Anthropic, Google)
-- Production-friendly: background jobs, connection pooling, indexing, and search analytics
-- Simple, ergonomic high-level API to keep your application code clean
+- **Simplified Complexity**: Single content model instead of multiple polymorphic types
+- **Cross-Modal Search**: Find images by searching for objects or concepts in their descriptions
+- **Unified Index**: One text-based search index for all content types
+- **Better Retrieval**: Text descriptions often contain more searchable information than raw media
+- **Cost Effective**: Single embedding model instead of specialized models per media type
+- **Easier Maintenance**: One embedding pipeline to maintain and optimize
 
 ### Key Capabilities
 
-- Semantic search with vector similarity (cosine) across polymorphic content
-- Text ingestion, chunking, and embedding generation
-- LLM-powered structured metadata with schema validation
-- Search tracking and analytics (CTR, performance, similarity of queries)
-- Hybrid search (semantic + full-text) planned
-- Extensible model and configuration system
+- **Universal Text Conversion**: Converts any media type to searchable text
+- **AI-Powered Descriptions**: Comprehensive image descriptions using vision models
+- **Audio Transcription**: Speech-to-text conversion for audio content
+- **Semantic Search**: Vector similarity search across all converted content
+- **Cross-Modal Retrieval**: Search for images using text descriptions of their content
+- **Content Quality Assessment**: Automatic scoring of converted content quality
+- **Migration Support**: Tools to migrate from previous multi-modal architecture
 
 ## Table of Contents
 
 - [Quick Start](#quick-start)
+- [Unified Architecture Guide](#unified-architecture-guide)
+- [Document Processing Pipeline](#document-processing-pipeline)
+- [Cross-Modal Search](#cross-modal-search)
+- [Migration from Multi-Modal](#migration-from-multi-modal)
 - [API Overview](#api-overview)
-- [Search and Retrieval](#search-and-retrieval)
-- [Search Analytics and Tracking](#search-analytics-and-tracking)
-- [System Operations](#system-operations)
 - [Configuration](#configuration)
-- [Current Implementation Status](#current-implementation-status)
-- [Architecture Highlights](#architecture-highlights)
-- [Text Document Processing](#text-document-processing-current)
-- [PostgreSQL + pgvector Configuration](#postgresql--pgvector-configuration)
-- [Performance Features](#performance-features)
 - [Installation](#installation)
 - [Requirements](#requirements)
-- [Use Cases](#use-cases)
-- [Environment Variables](#environment-variables)
+- [Performance Features](#performance-features)
 - [Troubleshooting](#troubleshooting)
-- [Related Projects](#related-projects)
-- [Key Design Principles](#key-design-principles)
-- [Contributing & Support](#contributing--support)
 
 ## Quick Start
 
 ```ruby
 require 'ragdoll'
 
-# Configure with PostgreSQL + pgvector
+# Configure with unified text-based architecture
 Ragdoll.configure do |config|
   # Database configuration (PostgreSQL only)
   config.database_config = {
@@ -88,225 +93,234 @@ Ragdoll.configure do |config|
     auto_migrate: true
   }
 
-  # Ruby LLM configuration
-  config.ruby_llm_config[:openai][:api_key] = ENV['OPENAI_API_KEY']
-  config.ruby_llm_config[:openai][:organization] = ENV['OPENAI_ORGANIZATION']
-  config.ruby_llm_config[:openai][:project] = ENV['OPENAI_PROJECT']
+  # Enable unified text-based models
+  config.use_unified_models = true
+
+  # Text conversion settings
+  config.text_conversion = {
+    image_detail_level: :comprehensive,  # :minimal, :standard, :comprehensive, :analytical
+    audio_transcription_provider: :openai,  # :azure, :google, :whisper_local
+    enable_fallback_descriptions: true
+  }
 
-  # Model configuration
-  config.models[:default] = 'openai/gpt-4o'
-  config.models[:embedding][:text] = 'text-embedding-3-small'
+  # Single embedding model for all content
+  config.embedding_model = "text-embedding-3-large"
+  config.embedding_provider = :openai
 
-  # Logging configuration
-  config.logging_config[:log_level] = :warn
-  config.logging_config[:log_filepath] = File.join(Dir.home, '.ragdoll', 'ragdoll.log')
+  # Ruby LLM configuration
+  config.ruby_llm_config[:openai][:api_key] = ENV['OPENAI_API_KEY']
 end
 
-# Add documents - returns detailed result
+# Add documents - all types converted to text
 result = Ragdoll.add_document(path: 'research_paper.pdf')
-puts result[:message]  # "Document 'research_paper' added successfully with ID 123"
-doc_id = result[:document_id]
+image_result = Ragdoll.add_document(path: 'diagram.png')  # Converted to description
+audio_result = Ragdoll.add_document(path: 'lecture.mp3')  # Converted to transcript
 
-# Check document status
-status = Ragdoll.document_status(id: doc_id)
-puts status[:message]  # Shows processing status and embeddings count
+# Cross-modal search - find images by describing their content
+results = Ragdoll.search(query: 'neural network architecture diagram')
+# This can return the image document if its AI description mentions neural networks
 
-# Search across content
-results = Ragdoll.search(query: 'neural networks')
+# Search for audio content by transcript content
+results = Ragdoll.search(query: 'machine learning discussion')
+# Returns audio documents whose transcripts mention machine learning
 
-# Get detailed document information
-document = Ragdoll.get_document(id: doc_id)
+# Check content quality
+document = Ragdoll.get_document(id: result[:document_id])
+puts document[:content_quality_score]  # 0.0 to 1.0 rating
 ```
 
-## API Overview
+## Unified Architecture Guide
 
-The `Ragdoll` module provides a convenient high-level API for common operations:
+### Document Processing Pipeline
 
-### Document Management
+The new unified pipeline converts all media types to searchable text:
 
 ```ruby
-# Add single document - returns detailed result hash
-result = Ragdoll.add_document(path: 'document.pdf')
-puts result[:success]         # true
-puts result[:document_id]     # "123"
-puts result[:message]         # "Document 'document' added successfully with ID 123"
-puts result[:embeddings_queued] # true
-
-# Check document processing status
-status = Ragdoll.document_status(id: result[:document_id])
-puts status[:status]          # "processed"
-puts status[:embeddings_count] # 15
-puts status[:embeddings_ready] # true
-puts status[:message]         # "Document processed successfully with 15 embeddings"
-
-# Get detailed document information
-document = Ragdoll.get_document(id: result[:document_id])
-puts document[:title]         # "document"
-puts document[:status]        # "processed"
-puts document[:embeddings_count] # 15
-puts document[:content_length]   # 5000
+# Text files: Direct extraction
+text_doc = Ragdoll.add_document(path: 'article.md')
+# Content: Original markdown text
 
-# Update document metadata
-Ragdoll.update_document(id: result[:document_id], title: 'New Title')
+# PDF/DOCX: Text extraction
+pdf_doc = Ragdoll.add_document(path: 'research.pdf')
+# Content: Extracted text from all pages
 
-# Delete document
-Ragdoll.delete_document(id: result[:document_id])
+# Images: AI-generated descriptions
+image_doc = Ragdoll.add_document(path: 'chart.png')
+# Content: "Bar chart showing quarterly sales data with increasing trend..."
 
-# List all documents
-documents = Ragdoll.list_documents(limit: 10)
+# Audio: Speech-to-text transcription
+audio_doc = Ragdoll.add_document(path: 'meeting.mp3')
+# Content: "In this meeting we discussed the quarterly results..."
 
-# System statistics
-stats = Ragdoll.stats
-puts stats[:total_documents]  # 50
-puts stats[:total_embeddings] # 1250
+# Video: Audio transcription + metadata
+video_doc = Ragdoll.add_document(path: 'presentation.mp4')
+# Content: Combination of audio transcript and video metadata
 ```
 
-### Search and Retrieval
+### Text Conversion Services
 
 ```ruby
-# Semantic search across all content types
-results = Ragdoll.search(query: 'artificial intelligence')
-
-# Search with automatic tracking (default)
-results = Ragdoll.search(
-  query: 'machine learning',
-  session_id: 123,  # Optional: track user sessions
-  user_id:    456   # Optional: track by user
-)
+# Use individual conversion services
+text_content = Ragdoll::TextExtractionService.extract('document.pdf')
+image_description = Ragdoll::ImageToTextService.convert('photo.jpg', detail_level: :comprehensive)
+audio_transcript = Ragdoll::AudioToTextService.transcribe('speech.wav')
 
-# Search specific content types
-text_results = Ragdoll.search(query: 'machine learning', content_type: 'text')
-image_results = Ragdoll.search(query: 'neural network diagram', content_type: 'image')
-audio_results = Ragdoll.search(query: 'AI discussion', content_type: 'audio')
+# Use unified converter (orchestrates all services)
+unified_text = Ragdoll::DocumentConverter.convert_to_text('any_file.ext')
 
-# Advanced search with metadata filters
-results = Ragdoll.search(
-  query: 'deep learning',
-  classification: 'research',
-  keywords: ['AI', 'neural networks'],
-  tags: ['technical']
-)
+# Manage documents with unified approach
+management = Ragdoll::UnifiedDocumentManagement.new
+document = management.add_document('mixed_media_file.mov')
+```
 
-# Get context for RAG applications
-context = Ragdoll.get_context(query: 'machine learning', limit: 5)
+### Content Quality Assessment
 
-# Enhanced prompt with context
-enhanced = Ragdoll.enhance_prompt(
-  prompt: 'What is machine learning?',
-  context_limit: 5
+```ruby
+# Get content quality scores
+document = Ragdoll::UnifiedDocument.find(id)
+quality = document.content_quality_score  # 0.0 to 1.0
+
+# Quality factors:
+# - Content length (50-2000 words optimal)
+# - Original media type (text > documents > descriptions > placeholders)
+# - Conversion success (full content > partial > fallback)
+
+# Batch quality assessment
+stats = Ragdoll::UnifiedContent.stats
+puts stats[:content_quality_distribution]
+# => { high: 150, medium: 75, low: 25 }
+```
+
+## Cross-Modal Search
+
+The unified architecture enables powerful cross-modal search capabilities:
+
+```ruby
+# Find images by describing their visual content
+image_results = Ragdoll.search(query: 'red sports car in parking lot')
+# Returns image documents whose AI descriptions match the query
+
+# Search for audio by spoken content
+audio_results = Ragdoll.search(query: 'quarterly sales meeting discussion')
+# Returns audio documents whose transcripts contain these topics
+
+# Mixed results across all media types
+all_results = Ragdoll.search(query: 'artificial intelligence')
+# Returns text documents, images with AI descriptions, and audio transcripts
+# all ranked by relevance to the query
+
+# Filter by original media type while searching text
+image_only = Ragdoll.search(
+  query: 'machine learning workflow',
+  original_media_type: 'image'
 )
 
-# Hybrid search combining semantic and full-text
-results = Ragdoll.hybrid_search(
-  query: 'neural networks',
-  semantic_weight: 0.7,
-  text_weight: 0.3
+# Search with quality filtering
+high_quality = Ragdoll.search(
+  query: 'deep learning',
+  min_quality_score: 0.7
 )
 ```
 
-### Keywords Search
+## Migration from Multi-Modal
 
-Ragdoll supports powerful keywords-based search that can be used standalone or combined with semantic search. The keywords system uses PostgreSQL array operations for high performance and supports both partial matching (overlap) and exact matching (contains all).
+Migrate smoothly from the previous multi-modal architecture:
 
 ```ruby
-# Keywords-only search (overlap - documents containing any of the keywords)
-results = Ragdoll::Document.search_by_keywords(['machine', 'learning', 'ai'])
+# Check migration readiness
+migration_service = Ragdoll::MigrationService.new
+report = migration_service.create_comparison_report
 
-# Results are sorted by match count (documents with more keyword matches rank higher)
-results.each do |doc|
-  puts "#{doc.title}: #{doc.keywords_match_count} matches"
-end
+puts "Migration Benefits:"
+report[:benefits].each { |benefit, description| puts "- #{description}" }
 
-# Exact keywords search (contains all - documents must have ALL keywords)
-results = Ragdoll::Document.search_by_keywords_all(['ruby', 'programming'])
-
-# Results are sorted by focus (fewer total keywords = more focused document)
-results.each do |doc|
-  puts "#{doc.title}: #{doc.total_keywords_count} total keywords"
-end
-
-# Combined semantic + keywords search for best results
-results = Ragdoll.search(
-  query: 'artificial intelligence applications',
-  keywords: ['ai', 'machine learning', 'neural networks'],
-  limit: 10
+# Migrate all documents
+results = Ragdoll::MigrationService.migrate_all_documents(
+  batch_size: 50,
+  process_embeddings: true
 )
 
-# Keywords search with options
-results = Ragdoll::Document.search_by_keywords(
-  ['web', 'javascript', 'frontend'],
-  limit: 20
-)
+puts "Migrated: #{results[:migrated]} documents"
+puts "Errors: #{results[:errors].length}"
+
+# Validate migration integrity
+validation = migration_service.validate_migration
+puts "Validation passed: #{validation[:passed]}/#{validation[:total_checks]} checks"
 
-# Case-insensitive keyword matching (automatically normalized)
-results = Ragdoll::Document.search_by_keywords(['Python', 'DATA-SCIENCE', 'ai'])
-# Will match documents with keywords: ['python', 'data-science', 'ai']
+# Migrate individual document
+migrated_doc = Ragdoll::MigrationService.migrate_document(old_document_id)
 ```
 
-**Keywords Search Features:**
-- **High Performance**: Uses PostgreSQL GIN indexes for fast array operations
-- **Flexible Matching**: Supports both overlap (`&&`) and contains (`@>`) operators
-- **Smart Scoring**: Results ordered by match count or document focus
-- **Case Insensitive**: Automatic keyword normalization
-- **Integration Ready**: Works seamlessly with semantic search
-- **Inspired by `find_matching_entries.rb`**: Optimized for PostgreSQL arrays
+## API Overview
+
+### Unified Document Management
 
-### Search Analytics and Tracking
+```ruby
+# Add documents with automatic text conversion
+result = Ragdoll.add_document(path: 'any_file.ext')
+puts result[:document_id]
+puts result[:content_preview]  # First 100 characters of converted text
+
+# Batch processing with unified pipeline
+files = ['doc.pdf', 'image.jpg', 'audio.mp3']
+results = Ragdoll::UnifiedDocumentManagement.new.batch_process_documents(files)
+
+# Reprocess with different conversion settings
+Ragdoll::UnifiedDocumentManagement.new.reprocess_document(
+  document_id,
+  image_detail_level: :analytical
+)
+```
 
-Ragdoll automatically tracks all searches to provide comprehensive analytics and improve search relevance over time:
+### Search API
 
 ```ruby
-# Get search analytics for the last 30 days
-analytics = Ragdoll::Search.search_analytics(days: 30)
-puts "Total searches: #{analytics[:total_searches]}"
-puts "Unique queries: #{analytics[:unique_queries]}"
-puts "Average execution time: #{analytics[:avg_execution_time]}ms"
-puts "Click-through rate: #{analytics[:click_through_rate]}%"
-
-# Find similar searches using vector similarity
-search = Ragdoll::Search.first
-similar_searches = search.nearest_neighbors(:query_embedding, distance: :cosine).limit(5)
-
-similar_searches.each do |similar|
-  puts "Query: #{similar.query}"
-  puts "Similarity: #{similar.neighbor_distance}"
-  puts "Results: #{similar.results_count}"
-end
+# Unified search across all content types
+results = Ragdoll.search(query: 'machine learning algorithms')
 
-# Track user interactions (clicks on search results)
-search_result = Ragdoll::SearchResult.first
-search_result.mark_as_clicked!
+# Search with original media type context
+results.each do |doc|
+  puts "#{doc.title} (originally #{doc.original_media_type})"
+  puts "Quality: #{doc.content_quality_score.round(2)}"
+  puts "Content: #{doc.content[0..100]}..."
+end
 
-# Disable tracking for specific searches if needed
-results = Ragdoll.search(
-  query: 'private query',
-  track_search: false
+# Advanced search with content quality
+high_quality_results = Ragdoll.search(
+  query: 'neural networks',
+  min_quality_score: 0.8,
+  limit: 10
 )
 ```
 
-### System Operations
+### Content Analysis
 
 ```ruby
-# Get system statistics
-stats = Ragdoll.stats
-# Returns information about documents, content types, embeddings, etc.
+# Analyze converted content
+document = Ragdoll::UnifiedDocument.find(id)
 
-# Health check
-healthy = Ragdoll.healthy?
+# Check original media type
+puts document.unified_contents.first.original_media_type  # 'image', 'audio', 'text', etc.
 
-# Get configuration
-config = Ragdoll.configuration
+# View conversion metadata
+content = document.unified_contents.first
+puts content.conversion_method  # 'image_to_text', 'audio_transcription', etc.
+puts content.metadata  # Conversion settings and results
 
-# Reset configuration (useful for testing)
-Ragdoll.reset_configuration!
+# Quality metrics
+puts content.word_count
+puts content.character_count
+puts content.content_quality_score
 ```
 
-### Configuration
+## Configuration
 
 ```ruby
-# Configure the system
 Ragdoll.configure do |config|
-  # Database configuration (PostgreSQL only - REQUIRED)
+  # Enable unified text-based architecture
+  config.use_unified_models = true
+
+  # Database configuration (PostgreSQL required)
   config.database_config = {
     adapter: 'postgresql',
     database: 'ragdoll_production',
@@ -317,141 +331,74 @@ Ragdoll.configure do |config|
     auto_migrate: true
   }
 
-  # Ruby LLM configuration for multiple providers
-  config.ruby_llm_config[:openai][:api_key] = ENV['OPENAI_API_KEY']
-  config.ruby_llm_config[:openai][:organization] = ENV['OPENAI_ORGANIZATION']
-  config.ruby_llm_config[:openai][:project] = ENV['OPENAI_PROJECT']
+  # Text conversion settings
+  config.text_conversion = {
+    # Image conversion detail levels:
+    # :minimal - Brief one-sentence description
+    # :standard - Main elements and composition
+    # :comprehensive - Detailed description including objects, colors, mood
+    # :analytical - Thorough analysis including artistic elements
+    image_detail_level: :comprehensive,
+
+    # Audio transcription providers
+    audio_transcription_provider: :openai,  # :azure, :google, :whisper_local
+
+    # Fallback behavior
+    enable_fallback_descriptions: true,
+    fallback_timeout: 30  # seconds
+  }
+
+  # Single embedding model for all content types
+  config.embedding_model = "text-embedding-3-large"
+  config.embedding_provider = :openai
 
+  # Ruby LLM configuration for text conversion
+  config.ruby_llm_config[:openai][:api_key] = ENV['OPENAI_API_KEY']
   config.ruby_llm_config[:anthropic][:api_key] = ENV['ANTHROPIC_API_KEY']
-  config.ruby_llm_config[:google][:api_key] = ENV['GOOGLE_API_KEY']
 
-  # Model configuration
-  config.models[:default] = 'openai/gpt-4o'
-  config.models[:summary] = 'openai/gpt-4o'
-  config.models[:keywords] = 'openai/gpt-4o'
-  config.models[:embedding][:text] = 'text-embedding-3-small'
-  config.models[:embedding][:image] = 'image-embedding-3-small'
-  config.models[:embedding][:audio] = 'audio-embedding-3-small'
+  # Vision model configuration for image descriptions
+  config.vision_config = {
+    primary_model: 'gpt-4-vision-preview',
+    fallback_model: 'gemini-pro-vision',
+    temperature: 0.2
+  }
 
-  # Logging configuration
-  config.logging_config[:log_level] = :warn  # :debug, :info, :warn, :error, :fatal
-  config.logging_config[:log_filepath] = File.join(Dir.home, '.ragdoll', 'ragdoll.log')
+  # Audio transcription configuration
+  config.audio_config = {
+    openai: {
+      model: 'whisper-1',
+      temperature: 0.0
+    },
+    azure: {
+      endpoint: ENV['AZURE_SPEECH_ENDPOINT'],
+      api_key: ENV['AZURE_SPEECH_KEY']
+    }
+  }
 
   # Processing settings
   config.chunking[:text][:max_tokens] = 1000
   config.chunking[:text][:overlap] = 200
   config.search[:similarity_threshold] = 0.7
   config.search[:max_results] = 10
-end
-```
-
-## Current Implementation Status
-
-### ✅ **Fully Implemented**
-- **Text document processing**: PDF, DOCX, HTML, Markdown, plain text files
-- **Embedding generation**: Text chunking and vector embedding creation
-- **Database schema**: Multi-modal polymorphic architecture with PostgreSQL + pgvector
-- **Dual metadata architecture**: Separate LLM-generated content analysis and file properties
-- **Search functionality**: Semantic search with cosine similarity and usage analytics
-- **Search tracking system**: Comprehensive analytics with query embeddings, click-through tracking, and performance monitoring
-- **Document management**: Add, update, delete, list operations
-- **Background processing**: ActiveJob integration for async embedding generation
-- **LLM metadata generation**: AI-powered structured content analysis with schema validation
-- **Logging**: Configurable file-based logging with multiple levels
-
-### 🚧 **In Development**
-- **Image processing**: Framework exists but vision AI integration needs completion
-- **Audio processing**: Framework exists but speech-to-text integration needs completion
-- **Hybrid search**: Combining semantic and full-text search capabilities
-
-### 📋 **Planned Features**
-- **Multi-modal search**: Search across text, image, and audio content types
-- **Content-type specific embedding models**: Different models for text, image, audio
-- **Enhanced metadata schemas**: Domain-specific metadata templates
-
-## Architecture Highlights
-
-### Dual Metadata Design
-
-Ragdoll uses a sophisticated dual metadata architecture to separate concerns:
-
-- **`metadata` (JSON)**: LLM-generated content analysis including summary, keywords, classification, topics, sentiment, and domain-specific insights
-- **`file_metadata` (JSON)**: System-generated file properties including size, MIME type, dimensions, processing parameters, and technical characteristics
-
-This separation enables both semantic search operations on content meaning and efficient file management operations.
-
-### Polymorphic Multi-Modal Architecture
-
-The database schema uses polymorphic associations to elegantly support multiple content types:
-
-- **Documents**: Central entity with dual metadata columns
-- **Content Types**: Specialized tables for `text_contents`, `image_contents`, `audio_contents`
-- **Embeddings**: Unified vector storage via polymorphic `embeddable` associations
-
-## Text Document Processing (Current)
-
-Currently, Ragdoll processes text documents through:
-
-1. **Content Extraction**: Extracts text from PDF, DOCX, HTML, Markdown, and plain text
-2. **Metadata Generation**: AI-powered analysis creates structured content metadata
-3. **Text Chunking**: Splits content into manageable chunks with configurable size/overlap
-4. **Embedding Generation**: Creates vector embeddings using OpenAI or other providers
-5. **Database Storage**: Stores in polymorphic multi-modal architecture with dual metadata
-6. **Search**: Semantic search using cosine similarity with usage analytics
-
-### Example Usage
-
-```ruby
-# Add a text document
-result = Ragdoll.add_document(path: 'document.pdf')
-
-# Check processing status
-status = Ragdoll.document_status(id: result[:document_id])
-
-# Search the content
-results = Ragdoll.search(query: 'machine learning')
-```
-
-## PostgreSQL + pgvector Configuration
-
-### Database Setup
-
-```bash
-# Install PostgreSQL and pgvector
-brew install postgresql pgvector  # macOS
-# or
-apt-get install postgresql postgresql-contrib  # Ubuntu
-
-# Create database and enable pgvector extension
-createdb ragdoll_production
-psql -d ragdoll_production -c "CREATE EXTENSION IF NOT EXISTS vector;"
-```
 
-### Configuration Example
-
-```ruby
-Ragdoll.configure do |config|
-  config.database_config = {
-    adapter: 'postgresql',
-    database: 'ragdoll_production',
-    username: 'ragdoll',
-    password: ENV['DATABASE_PASSWORD'],
-    host: 'localhost',
-    port: 5432,
-    pool: 20,
-    auto_migrate: true
+  # Quality thresholds
+  config.quality_thresholds = {
+    high_quality: 0.8,
+    medium_quality: 0.5,
+    min_content_length: 50
   }
 end
 ```
 
 ## Performance Features
 
-- **Native pgvector**: Hardware-accelerated similarity search
-- **IVFFlat indexing**: Fast approximate nearest neighbor search
-- **Polymorphic embeddings**: Unified search across content types
-- **Batch processing**: Efficient bulk operations
-- **Background jobs**: Asynchronous document processing
-- **Connection pooling**: High-concurrency support
+- **Unified Index**: Single text-based search index for all content types
+- **Optimized Conversion**: Efficient text extraction and AI-powered description generation
+- **Quality Scoring**: Automatic assessment of converted content quality
+- **Batch Processing**: Efficient bulk document processing with progress tracking
+- **Smart Caching**: Caches conversion results to avoid reprocessing
+- **Background Jobs**: Asynchronous processing for large files
+- **Cross-Modal Optimization**: Specialized optimizations for different media type conversions
 
 ## Installation
 
@@ -461,6 +408,12 @@ brew install postgresql pgvector  # macOS
 # or
 apt-get install postgresql postgresql-contrib  # Ubuntu
 
+# For image processing
+brew install imagemagick
+
+# For audio processing (optional, depending on provider)
+brew install ffmpeg
+
 # Install gem
 gem install ragdoll
 
@@ -471,61 +424,83 @@ gem 'ragdoll'
 ## Requirements
 
 - **Ruby**: 3.2+
-- **PostgreSQL**: 12+ with pgvector extension (REQUIRED - no other databases supported)
-- **Dependencies**: activerecord, pg, pgvector, neighbor, ruby_llm, pdf-reader, docx, rubyzip, shrine, rmagick, opensearch-ruby, searchkick, ruby-progressbar
+- **PostgreSQL**: 12+ with pgvector extension
+- **ImageMagick**: For image processing and metadata extraction
+- **FFmpeg**: Optional, for advanced audio/video processing
+- **Dependencies**: activerecord, pg, pgvector, neighbor, ruby_llm, pdf-reader, docx, rmagick, tempfile
 
-## Use Cases
+### Vision Model Requirements
 
-- Internal knowledge bases and chat assistants grounded in your documents
-- Product documentation and support search with analytics and relevance feedback
-- Research corpora exploration (summaries, topics, similarity) across large text sets
-- Incident retrospectives and operational analytics with searchable write-ups
-- Media libraries preparing for text + image + audio pipelines (image/audio in progress)
+For comprehensive image descriptions:
+- **OpenAI**: GPT-4 Vision (recommended)
+- **Google**: Gemini Pro Vision
+- **Anthropic**: Claude 3 with vision capabilities
+- **Local**: Ollama with vision-capable models
 
-## Environment Variables
+### Audio Transcription Requirements
 
-Set the following as environment variables (do not commit secrets to source control):
-
-- `OPENAI_API_KEY` — required for OpenAI models
-- `OPENAI_ORGANIZATION` — optional, for OpenAI org scoping
-- `OPENAI_PROJECT` — optional, for OpenAI project scoping
-- `ANTHROPIC_API_KEY` — optional, for Anthropic models
-- `GOOGLE_API_KEY` — optional, for Google models
-- `DATABASE_PASSWORD` — your PostgreSQL password if not using peer auth
+- **OpenAI**: Whisper API (recommended)
+- **Azure**: Speech Services
+- **Google**: Cloud Speech-to-Text
+- **Local**: Whisper installation
 
 ## Troubleshooting
 
-### pgvector extension missing
-
-- Ensure the extension is enabled in your database:
+### Image Processing Issues
 
 ```bash
-psql -d ragdoll_production -c "CREATE EXTENSION IF NOT EXISTS vector;"
+# Verify ImageMagick installation
+convert -version
+
+# Check vision model access
+irb -r ragdoll
+> Ragdoll::ImageToTextService.new.convert('test_image.jpg')
 ```
 
-- If the command fails, verify PostgreSQL and pgvector are installed and that you’re connecting to the correct database.
+### Audio Processing Issues
 
-### Document stuck in "processing"
+```bash
+# For Whisper local installation
+pip install openai-whisper
 
-- Confirm your API keys are set and valid.
-- Ensure `auto_migrate: true` in configuration (or run migrations if you manage schema yourself).
-- Check logs at the path configured by `logging_config[:log_filepath]` for errors.
+# Test audio file support
+irb -r ragdoll
+> Ragdoll::AudioToTextService.new.transcribe('test_audio.wav')
+```
 
-## Related Projects
+### Content Quality Issues
 
-- **ragdoll-cli**: Standalone CLI application using ragdoll
-- **ragdoll-rails**: Rails engine with web interface for ragdoll
+```ruby
+# Check content quality distribution
+stats = Ragdoll::UnifiedContent.stats
+puts stats[:content_quality_distribution]
+
+# Reprocess low-quality content
+low_quality = Ragdoll::UnifiedDocument.joins(:unified_contents)
+  .where('unified_contents.content_quality_score < 0.5')
+
+low_quality.each do |doc|
+  Ragdoll::UnifiedDocumentManagement.new.reprocess_document(
+    doc.id,
+    image_detail_level: :analytical
+  )
+end
+```
 
-## Contributing & Support
+## Use Cases
 
-Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request. For questions and feedback, open an issue in this repository.
+- **Knowledge Bases**: Search across text documents, presentation images, and recorded meetings
+- **Media Libraries**: Find images by visual content, audio by spoken topics
+- **Research Collections**: Unified search across papers (text), charts (images), and interviews (audio)
+- **Documentation Systems**: Search technical docs, architecture diagrams, and explanation videos
+- **Educational Content**: Find learning materials across all media types through unified text search
 
 ## Key Design Principles
 
-1. **Database-Oriented**: Built on ActiveRecord with PostgreSQL + pgvector for production performance
-2. **Multi-Modal First**: Text, image, and audio content as first-class citizens via polymorphic architecture
-3. **Dual Metadata Design**: Separates LLM-generated content analysis from file properties
-4. **LLM-Enhanced**: Structured metadata generation with schema validation using latest AI capabilities
-5. **High-Level API**: Simple, intuitive interface for complex operations
-6. **Scalable**: Designed for production workloads with background processing and proper indexing
-7. **Extensible**: Easy to add new content types and embedding models through polymorphic design
+1. **Unified Text Representation**: All media types converted to searchable text
+2. **Cross-Modal Search**: Images findable through descriptions, audio through transcripts
+3. **Quality-Driven**: Automatic assessment and optimization of converted content
+4. **Simplified Architecture**: Single content model instead of complex polymorphic relationships
+5. **AI-Enhanced Conversion**: Leverages latest vision and speech models for rich text conversion
+6. **Migration-Friendly**: Smooth transition path from previous multi-modal architecture
+7. **Performance-Optimized**: Single embedding model and unified search index for speed