OxiRS Chat

AI-powered conversational interface for RDF knowledge graphs with RAG and natural language to SPARQL

Overview

oxirs-chat provides an intelligent conversational interface for querying and exploring RDF datasets. It combines Large Language Models (LLMs) with Retrieval-Augmented Generation (RAG) to enable natural language queries over semantic data, automatic SPARQL generation, and contextual explanations.

Key capabilities:

• Natural Language to SPARQL — Convert plain-English questions to SPARQL.
• RAG Integration — Retrieve relevant triples from the knowledge graph and pass them as context to the LLM.
• Multi-provider LLM — OpenAI and Anthropic out of the box; local providers configurable.
• Streaming responses — Word-by-word output via a channel-based API.
• Session persistence — Save and restore conversation sessions as JSON.
• Circuit breakers — Automatic fallback across LLM providers on failure.
• Schema introspection — Discover the RDF schema automatically to improve NL2SPARQL accuracy.
• Consciousness-inspired retrieval — Optional quantum-enhanced and consciousness-aware context assembly.

Installation

[dependencies]
oxirs-chat = "0.3.1"
oxirs-core  = "0.3.1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"

Optional features:

Quick Start

use oxirs_chat::{ChatConfig, OxiRSChat};
use oxirs_core::ConcreteStore;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 1. Open an in-memory RDF store.
    let store = Arc::new(ConcreteStore::new()?);

    // 2. Build the chat system.
    let chat = OxiRSChat::new(ChatConfig::default(), store).await?;

    // 3. Create a named session (one per user).
    let _session = chat.create_session("alice".to_string()).await?;

    // 4. Ask a natural-language question.
    //    Set OPENAI_API_KEY or ANTHROPIC_API_KEY for full LLM responses.
    let response = chat
        .process_message("alice", "What genes are linked to breast cancer?".to_string())
        .await?;

    println!("{}", response.content.to_text());
    Ok(())
}

Documentation

Examples

Run any example with:

OPENAI_API_KEY=sk-... cargo run --example kg_chat -p oxirs-chat

Configuration Reference

ChatConfig (session)

use oxirs_chat::ChatConfig;

let config = ChatConfig {
    max_context_tokens:      8000,   // Token budget for context window
    sliding_window_size:     20,     // Messages kept in sliding window
    enable_context_compression: true,
    temperature:             0.7,
    max_tokens:              2000,   // Max tokens in LLM response
    timeout_seconds:         30,
    enable_topic_tracking:   true,
    enable_sentiment_analysis: true,
    enable_intent_detection: true,
};

LLM provider selection

use oxirs_chat::{LLMConfig, OxiRSChat, ChatConfig};
use oxirs_core::ConcreteStore;
use std::sync::Arc;

# async fn example() -> anyhow::Result<()> {
let store = Arc::new(ConcreteStore::new()?);

// Use Anthropic provider only.
// ANTHROPIC_API_KEY is read from the environment automatically.
let mut llm_config = LLMConfig::default();
llm_config.providers.retain(|k, _| k == "anthropic");

let chat = OxiRSChat::new_with_llm_config(
    ChatConfig::default(),
    store,
    Some(llm_config),
).await?;
# Ok(())
# }

RAG retrieval depth

use oxirs_chat::rag::{RagConfig, RetrievalConfig};

let rag_config = RagConfig {
    retrieval: RetrievalConfig {
        max_results: 20,           // More retrieval candidates
        graph_traversal_depth: 3,  // Follow 3 hops in the graph
        similarity_threshold: 0.6,
        enable_entity_expansion: true,
        ..RetrievalConfig::default()
    },
    ..RagConfig::default()
};

Session Persistence

use oxirs_chat::{ChatConfig, OxiRSChat};
use oxirs_core::ConcreteStore;
use std::sync::Arc;

# async fn example() -> anyhow::Result<()> {
let store = Arc::new(ConcreteStore::new()?);
let chat = OxiRSChat::new(ChatConfig::default(), store).await?;

// Restore sessions saved in a previous run.
let loaded = chat.load_sessions("/var/lib/oxirs-chat/sessions").await?;
println!("Restored {} sessions", loaded);

// ... application runs ...

// Flush before shutdown.
chat.save_sessions("/var/lib/oxirs-chat/sessions").await?;
# Ok(())
# }

Streaming Responses

use oxirs_chat::{ChatConfig, OxiRSChat, StreamResponseChunk};
use oxirs_core::ConcreteStore;
use std::sync::Arc;

# async fn example() -> anyhow::Result<()> {
let store = Arc::new(ConcreteStore::new()?);
let chat = OxiRSChat::new(ChatConfig::default(), store).await?;
chat.create_session("alice".to_string()).await?;

let mut rx = chat
    .process_message_stream("alice", "Explain RDF graphs.".to_string())
    .await?;

while let Some(chunk) = rx.recv().await {
    match chunk {
        StreamResponseChunk::Content { text, .. } => print!("{}", text),
        StreamResponseChunk::Complete { total_time, .. } => {
            println!("\nDone in {:.2}s", total_time.as_secs_f64());
            break;
        }
        StreamResponseChunk::Error { error, .. } => {
            eprintln!("Error: {}", error.message);
            break;
        }
        _ => {}
    }
}
# Ok(())
# }

Environment Variables

Related Crates

• oxirs-core — RDF data model and store
• oxirs-vec — Vector search and HNSW indexes
• oxirs-embed — Knowledge graph embedding models
• oxirs-arq — SPARQL query engine
• oxirs-fuseki — SPARQL HTTP server

License

Apache-2.0 — see LICENSE-APACHE.

OxiRS Chat v0.3.1 — AI-powered conversational RDF interface by COOLJAPAN OU (Team Kitasan)