Conversational BI Quick Start Guide

Conversational BI Quick Start Guide

Get started with HeliosDB’s Conversational BI in 5 minutes.

Installation

Add to your Cargo.toml:

[dependencies]
heliosdb-conversational-bi = "7.0.0"
tokio = { version = "1.0", features = ["full"] }

Basic Usage

1. Create Engine

use heliosdb_conversational_bi::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure with your LLM provider
    let config = ConversationalConfig {
        primary_model: ModelConfig {
            provider: "openai".to_string(),
            model_name: "gpt-4".to_string(),
            api_key: std::env::var("OPENAI_API_KEY")?,
            ..Default::default()
        },
        ..Default::default()
    };

    let engine = ConversationalBiEngine::new(config).await?;

    Ok(())
}

2. Create Session

// Create a conversation session for a user
let session_id = engine.create_session("alice@example.com", "sales_db").await?;

3. Ask Questions

// Simple query
let response = engine.process_query(
    session_id,
    "Show me top 10 customers by revenue"
).await?;

if let Some(sql) = response.sql {
    println!("Generated SQL: {}", sql);
    println!("Explanation: {}", response.explanation);
    println!("Confidence: {:.1}%", response.confidence * 100.0);
}

4. Multi-Turn Conversations

// First question
engine.process_query(session_id, "Show me sales data for 2024").await?;

// Follow-up (uses context from previous turn)
engine.process_query(session_id, "Break it down by month").await?;

// Another follow-up
engine.process_query(session_id, "Which month had the highest sales?").await?;

Production Configuration

Enable All Security Features

use heliosdb_conversational_bi::production_config::*;

let production_config = ProductionConfig {
    // Rate limiting (60 queries per minute per tenant)
    enable_rate_limiting: true,
    rate_limit_qpm: 60,
    burst_allowance: 10,

    // Security
    enable_security_validation: true,
    max_query_length: 10_000,

    // Performance monitoring
    enable_performance_monitoring: true,
    target_latency_ms: 300,

    // Circuit breaker
    enable_circuit_breaker: true,

    ..Default::default()
};

// Production config is automatically applied in ConversationalBiEngine::new()

Monitor Performance

// Get latency metrics for a tenant
if let Some(metrics) = engine.get_performance_metrics("alice@example.com").await {
    println!("Latency p50: {}ms", metrics.p50);
    println!("Latency p95: {}ms", metrics.p95);
    println!("Latency p99: {}ms", metrics.p99);
}

// Check rate limit status
let tokens = engine.get_rate_limit_tokens("alice@example.com");
println!("Rate limit tokens remaining: {:.1}", tokens);

Advanced Features

1. Query Caching

// Semantic caching is enabled by default
let config = ConversationalConfig {
    enable_query_cache: true,  // Similar queries return cached results
    ..Default::default()
};

2. Multiple LLM Providers

let config = ConversationalConfig {
    primary_model: ModelConfig {
        provider: "openai".to_string(),
        model_name: "gpt-4".to_string(),
        api_key: std::env::var("OPENAI_API_KEY")?,
        ..Default::default()
    },
    // Fallback to different model if primary fails
    fallback_model: Some(ModelConfig {
        provider: "anthropic".to_string(),
        model_name: "claude-3-opus-20240229".to_string(),
        api_key: std::env::var("ANTHROPIC_API_KEY")?,
        ..Default::default()
    }),
    ..Default::default()
};

3. Session Management

// Get conversation history
let history = engine.get_history(session_id).await?;
for turn in history {
    println!("User: {}", turn.user_query);
    println!("SQL: {:?}", turn.sql);
    println!("---");
}

// Reset session (clear context)
engine.reset_session(session_id).await?;

// Delete session when done
engine.delete_session(session_id).await?;

Error Handling

use heliosdb_conversational_bi::error::*;

match engine.process_query(session_id, query).await {
    Ok(response) => {
        println!("SQL: {:?}", response.sql);
    }
    Err(ConversationalError::RateLimitExceeded { retry_after_secs, .. }) => {
        println!("Rate limit exceeded. Retry after {} seconds", retry_after_secs);
    }
    Err(ConversationalError::SecurityViolation(msg)) => {
        println!("Security violation: {}", msg);
    }
    Err(ConversationalError::ServiceUnavailable(msg)) => {
        println!("Service unavailable: {}", msg);
    }
    Err(e) => {
        eprintln!("Error: {}", e);
    }
}

Common Patterns

1. Web API Integration (Axum Example)

use axum::{Router, Json, extract::State};
use std::sync::Arc;

#[derive(Clone)]
struct AppState {
    engine: Arc<ConversationalBiEngine>,
}

async fn query_handler(
    State(state): State<AppState>,
    Json(req): Json<QueryRequest>,
) -> Result<Json<QueryResponse>, AppError> {
    // Check authentication/authorization here

    let response = state.engine
        .process_query(req.session_id, &req.query)
        .await?;

    Ok(Json(QueryResponse {
        sql: response.sql,
        explanation: response.explanation,
        confidence: response.confidence,
        latency_ms: response.latency_ms,
    }))
}

#[tokio::main]
async fn main() {
    let engine = ConversationalBiEngine::new(config).await.unwrap();

    let app = Router::new()
        .route("/query", post(query_handler))
        .with_state(AppState {
            engine: Arc::new(engine),
        });

    // Run server...
}

2. Batch Processing

// Process multiple queries in parallel
let queries = vec![
    "Show sales by region",
    "What are the top products?",
    "List recent orders",
];

let futures: Vec<_> = queries
    .iter()
    .map(|q| engine.process_query(session_id, q))
    .collect();

let results = futures::future::join_all(futures).await;

for (query, result) in queries.iter().zip(results) {
    match result {
        Ok(response) => println!("Query: {} => SQL: {:?}", query, response.sql),
        Err(e) => eprintln!("Query: {} => Error: {}", query, e),
    }
}

3. Custom Metrics Collection

use tokio::time::{interval, Duration};

// Background task to collect metrics
tokio::spawn(async move {
    let mut tick = interval(Duration::from_secs(60));
    loop {
        tick.tick().await;

        for tenant_id in get_active_tenants() {
            if let Some(metrics) = engine.get_performance_metrics(&tenant_id).await {
                // Send to your monitoring system
                send_to_prometheus(&tenant_id, &metrics);
            }
        }
    }
});

Troubleshooting

High Latency

// Check if target latency is being exceeded
if let Some(metrics) = engine.get_performance_metrics(tenant_id).await {
    if metrics.p95 > 300 {
        println!("Warning: p95 latency ({}ms) exceeds target (300ms)", metrics.p95);
        // Consider:
        // - Optimizing schema loading
        // - Using faster LLM model
        // - Increasing cache hit rate
        // - Scaling horizontally
    }
}

Rate Limits

// Adjust rate limits based on tenant tier
let premium_config = ProductionConfig {
    rate_limit_qpm: 120,  // 2x for premium users
    burst_allowance: 20,
    ..Default::default()
};

Circuit Breaker Open

// Monitor circuit breaker state
// If seeing frequent "Service Unavailable" errors:
// 1. Check LLM API health
// 2. Review circuit breaker threshold
// 3. Adjust reset timeout
// 4. Implement fallback model

let config = ProductionConfig {
    circuit_breaker_threshold: 10,  // More tolerant
    circuit_breaker_reset_timeout_secs: 30,  // Faster recovery
    ..Default::default()
};

Best Practices

1. Always use HTTPS in production
2. Enable all security features (rate limiting, input validation)
3. Monitor latency metrics regularly
4. Set appropriate rate limits per tenant tier
5. Use semantic caching to reduce LLM API costs
6. Implement proper error handling for user-facing APIs
7. Test with BIRD benchmark to measure accuracy
8. Scale horizontally with load balancers
9. Use connection pooling for database metadata
10. Implement tenant isolation for multi-tenant deployments

Next Steps

• Review the Complete Documentation
• Run the BIRD Benchmark
• Explore Advanced Features
• Check Performance Tuning Guide

Support

• GitHub Issues: https://github.com/heliosdb/heliosdb/issues
• Documentation: /home/claude/HeliosDB/docs/
• Examples: /home/claude/HeliosDB/heliosdb-conversational-bi/examples/

---

Status: Production Ready Version: 7.0.0 Completion: 100%