TypeDialog/examples/10-ai-backend/README.md

# AI Backend Example

Demonstrates the TypeDialog AI backend with RAG (Retrieval-Augmented Generation) system.

⚠️ **Important**: The AI backend cannot remain a library. See **[INTEGRATION_GUIDE.md](INTEGRATION_GUIDE.md)** for how to integrate into real services.

## Features Shown

- **Creating a RAG System**: Initialize with configurable semantic/keyword weights
- **Batch Document Addition**: Efficient bulk document indexing
- **Document Retrieval**: Search using hybrid semantic + keyword approach
- **Batch Document Removal**: Efficient bulk document deletion
- **Performance Comparison**: Shows speedup of batch vs sequential operations

## What is the AI Backend?

The AI backend is **not a rendering backend** (like CLI, TUI, Web). It's a **library of AI/ML capabilities**:

- **RAG System**: Combines semantic search (embeddings) + keyword search (full-text)
- **Knowledge Graph**: Entity and relationship modeling using petgraph
- **Embeddings**: Text-to-vector conversion for semantic similarity
- **Vector Store**: HNSW-optimized approximate nearest neighbor search
- **Full-Text Indexer**: Efficient keyword-based document search
- **Persistence**: Save/load AI state to disk with version compatibility

## Running the Example

```bash
# Build the example
just build::ai

# Run the example
cargo run --example main --features ai_backend

# Or directly
cargo run --example main --features ai_backend --release
```

## Output Highlights

The example demonstrates:

1. **Batch Add Performance**: Adding 5 documents efficiently
2. **Retrieval Quality**: Combining semantic + keyword scores
3. **Batch Remove**: Efficiently removing multiple documents
4. **Performance Benchmark**: 20-document test showing ~2x speedup with batch ops

## API Overview

```rust
// Create RAG system
let mut rag = RagSystem::new(RagConfig::default())?;

// Add documents (batch - efficient for large sets)
let docs = vec![
    ("id1".into(), "content1".into()),
    ("id2".into(), "content2".into()),
];
rag.add_documents_batch(docs)?;

// Retrieve relevant documents
let results = rag.retrieve("query text")?;
for result in results {
    println!("{}: {}", result.doc_id, result.content);
}

// Remove documents (batch - efficient)
let removed = rag.remove_documents_batch(&["id1", "id2"]);

// Save/Load
rag.save_to_file("rag.bin")?;
let loaded = RagSystem::load_from_file("rag.bin")?;
```

## Configuration

`RagConfig` controls retrieval behavior:

```rust
RagConfig {
    semantic_weight: 0.6,     // Weight for vector similarity
    keyword_weight: 0.4,      // Weight for keyword matching
    max_results: 5,           // Maximum results to return
    min_score: 0.0,           // Minimum combined score threshold
}
```

## Integration Points

The AI backend can be integrated with:

- **CLI Backend**: Add AI-powered search to CLI prompts
- **TUI Backend**: Add semantic search UI
- **Web Backend**: Add AI features to HTTP forms
- **Custom Applications**: Use as a library in any Rust project

## Performance Notes

- **Vector Store**: Uses HNSW for O(log N) approximate nearest neighbor search
- **Batch Operations**: Avoid repeated index rebuilds (2x speedup typical)
- **Embeddings**: Deterministic hash-based (production: integrate real ML models)
- **Full-Text Index**: Simple substring matching (production: consider tantivy)

## Next Steps

- Integrate Knowledge Graph for relationship modeling
- Use real embedding models (OpenAI, local transformers)
- Add custom similarity metrics
- Implement caching strategies
- Build domain-specific RAG pipelines