LLM Integration¶

Integrate AI capabilities into your apps using IRIS (Intelligent Research and Insight System).

Overview¶

The Virtualitics SDK provides LLM integration through:

Chat Interface: Interactive conversations with users
Custom Agents: Specialized AI assistants for specific tasks
Context Injection: Provide app-specific context to the LLM
Request/Response Hooks: Pre and post-process LLM interactions

Adding Chat to Your App¶

Basic Chat¶

from virtualitics_sdk.llm import Chat

class ChatStep(Step):
    def run(self, flow_metadata):
        chat = Chat(
            id="assistant",
            title="AI Assistant",
            system_prompt="You are a helpful data analysis assistant."
        )

        return Page(
            title="Chat",
            sections=[
                Section(
                    title="Ask Questions",
                    cards=[Card(title="AI Assistant", content=[chat])]
                )
            ]
        )

Context-Aware Chat¶

Provide app-specific context to the LLM:

def run(self, flow_metadata):
    # Get current data
    df = self._inLink.dataset.data

    # Create context-aware prompt
    system_prompt = f"""
    You are analyzing a dataset with {len(df)} rows and {len(df.columns)} columns.

    Columns: {', '.join(df.columns)}

    Help the user understand and analyze this data.
    """

    chat = Chat(
        id="data_chat",
        title="Data Assistant",
        system_prompt=system_prompt
    )

    return Page(...)

App-Level LLM Hooks¶

Intercept and modify LLM requests and responses:

from virtualitics_sdk import App

async def on_llm_request(request_data, link, flow_metadata):
    """Pre-process before sending to LLM."""
    # Add dataset context
    if hasattr(link, 'dataset'):
        df = link.dataset.data
        request_data["context"] = {
            "dataset_info": {
                "shape": df.shape,
                "columns": list(df.columns),
                "dtypes": df.dtypes.to_dict()
            }
        }

    return request_data

async def on_llm_response(response_data, link, flow_metadata):
    """Post-process LLM response."""
    # Log the response
    print(f"LLM responded: {response_data}")

    # Could modify response here if needed
    return response_data

# Create app with LLM hooks
app = App(
    name="AI-Powered App",
    description="App with LLM integration",
    on_llm_request=on_llm_request,
    on_llm_response=on_llm_response
)

Custom AI Agents¶

Create specialized agents for specific tasks:

from virtualitics_sdk.llm.agent import DispatcherAgentInterface

class DataAnalysisAgent(DispatcherAgentInterface):
    """Agent specialized in data analysis."""

    async def handle_query(self, query: str, context: dict) -> str:
        # Get dataset from context
        dataset = context.get('dataset')

        if not dataset:
            return "No dataset available to analyze."

        df = dataset.data

        # Handle different query types
        if 'summary' in query.lower():
            summary = df.describe().to_string()
            return f"Dataset Summary:\n\n{summary}"

        elif 'correlation' in query.lower():
            numeric_cols = df.select_dtypes(include='number').columns
            if len(numeric_cols) > 1:
                corr = df[numeric_cols].corr().to_string()
                return f"Correlation Matrix:\n\n{corr}"
            else:
                return "Not enough numeric columns for correlation."

        else:
            return "I can help with: summary statistics, correlation analysis"

# Use agent in app
analysis_agent = DataAnalysisAgent()

app = App(
    name="Smart Analysis",
    description="App with custom AI agent",
    agent=analysis_agent
)

Default Prompts¶

Suggest questions to users:

app = App(
    name="Sales Analysis",
    description="Analyze sales data with AI",
    default_prompts=[
        "What are the top selling products?",
        "Show me sales trends over time",
        "Identify any anomalies in the data",
        "What factors correlate with high sales?"
    ]
)

Step-Level Agents¶

Attach agents to specific steps:

step = AnalysisStep(
    title="AI-Powered Analysis",
    description="Analyze data with AI assistance",
    parent="Analysis",
    type=StepType.RESULTS,
    page=Page(...),
    agent=analysis_agent
)

Best Practices¶

Clear System Prompts: Be specific about the AI's role and capabilities
Provide Context: Include relevant data context in prompts
Limit Scope: Focus AI on specific tasks rather than general purpose
Validate Responses: Don't blindly trust LLM outputs
Handle Errors: LLM may be unavailable, handle gracefully
User Guidance: Provide example prompts to guide users

Example: Complete LLM-Powered Step¶

class LLMAnalysisStep(Step):
    def run(self, flow_metadata):
        # Get data
        df = self._inLink.dataset.data

        # Create data summary for context
        data_summary = f"""
        Dataset: {len(df)} rows, {len(df.columns)} columns
        Columns: {', '.join(df.columns)}
        Numeric columns: {', '.join(df.select_dtypes(include='number').columns)}
        """

        # Create chat with context
        chat = Chat(
            id="analysis_chat",
            title="AI Analysis Assistant",
            system_prompt=f"""
            You are a data analysis expert. Help analyze this dataset:

            {data_summary}

            Provide insights, suggest analyses, and answer questions about the data.
            """
        )

        return Page(
            title="AI-Powered Analysis",
            sections=[
                Section(
                    title="Chat with AI",
                    cards=[
                        Card(
                            title="Analysis Assistant",
                            content=[
                                RichText(f"**Dataset Overview:**\n{data_summary}"),
                                chat
                            ]
                        )
                    ]
                )
            ]
        )