TrustifAI

🛡️Quantify, Visualize, and Explain Trust in AI.

TrustifAI is a Python-based framework designed to evaluate the trustworthiness of LLM responses and Retrieval-Augmented Generation (RAG) systems. Unlike simple evaluation frameworks that rely on a single "correctness" score, TrustifAI computes a multi-dimensional Trust Score based on grounding, consistency, alignment, and diversity.

It also includes visualizations to help showcase why a model output was deemed unreliable.

📊 Key Metrics

TrustifAI evaluates trustworthiness using four orthogonal vectors or trust signals. The final Trust Score is a weighted aggregation of these components.

Offline Metrics (For already generated RAG response)

Online Metrics (For Real-time response generation)

Applicable only for LLMs which supports logprobs. Might not be a good metric in case LLM is not calibrated enough. Newer LLMs are confident enough in hallucinated responses also, might not be suitable for such cases.

🚀 Installation

TrustifAI requires Python 3.10+.

pip install trustifai

#to enable tracing
pip install trustifai[trace]

# for tests
pip install trustifai[test]

OR

# Clone the repository
git clone https://github.com/Trustifai/trustifai.git
cd trustifai

# Install dependencies
pip install -r requirements.txt

Environment Setup

Create a .env file or export your API keys. TrustifAI uses LiteLLM, so it supports OpenAI, Azure, Anthropic, Gemini, Mistral, and more. (check .env.example)

⚡ Quick Start

1. Evaluate an existing RAG Response in a few lines of code.

Use this flow to score a query/answer pair against retrieved documents.

from trustifai import Trustifai, MetricContext
from langchain_core.documents import Document #langchain is not required, used here for demo only.

# 1. Define your RAG Context
context = MetricContext(
    query="What is the capital of India?",
    answer="The capital is New Delhi.",
    documents=[
        Document(page_content="New Delhi is the capital of India.", metadata={"source": "wiki.txt"})
    ]
)

# 2. Initialize Engine
trust_engine = Trustifai("config_file.yaml")

# 3. Calculate Score
result = trust_engine.get_trust_score(context)
print(f"Trust Score: {result['score']} | Decision: {result['label']}")

# 4. Visualize Logic
graph = trust_engine.build_reasoning_graph(result)
trust_engine.visualize(graph, graph_type="pyvis") # Saves to reasoning_graph.html

2. Generate with Confidence

Use TrustifAI to generate a response and immediately get a confidence score based on token log probabilities.

from trustifai import Trustifai

# Initialize (Context will be None for pure generation)
trust_engine = Trustifai(config_path="config_file.yaml")

# Generate response
result = trust_engine.generate(
    prompt="What is the capital of France?",
    system_prompt="You are a helpful assistant."
)

print(f"Response: {result['response']}")
print(f"Confidence: {result['metadata']['confidence_score']} ({result['metadata']['confidence_label']})")

⚙️ Configuration

Control the sensitivity of the evaluation using config_file.yaml.

#custom config can be passed on using config_path
trust_engine = Trustifai(config_path="config_file.yaml")

Refer: config_file.yaml

# 1. Model Configuration (via LiteLLM)
llm:
  type: "openai"
  params:
    model_name: "gpt-5"

# 2. Thresholds (Strictness)
metrics:
  - type: "evidence_coverage"
    enabled: true #any metric can be disabled (if not suitable for your use-case)
    params:
      STRONG_GROUNDING: 0.85 # Threshold for "Trusted" label
      PARTIAL_GROUNDING: 0.60
  - type: "consistency"
    enabled: true
    params:
      STABLE_CONSISTENCY: 0.90 # Requires 0.9 cosine sim to be "Stable"

# 3. Weighted Aggregation
# Adjust these based on your business priority.
score_weights:
  - type: "evidence_coverage"
    params: { weight: 0.40 } # Highest priority on factual accuracy
  - type: "semantic_drift"
    params: { weight: 0.30 }
  - type: "consistency"
    params: { weight: 0.20 }
  - type: "source_diversity"
    params: { weight: 0.10 }

🕸️ Reasoning Graphs

TrustifAI doesn't just give you a number; it gives you a map. The Reasoning Graph is a directed acyclic graph (DAG) representing the evaluation logic.

• Nodes: Represent individual metrics (Green=High Trust, Red=Low Trust).
• Edges: Represent the flow of data into the final aggregation.
• Interactive: The generated HTML uses PyVis for physics-based interaction.

To generate a graph:

# Generate interactive HTML
trust_engine.visualize(graph, graph_type="pyvis")

# Generate Mermaid syntax for markdown documentation
print(trust_engine.visualize(graph, graph_type="mermaid"))

🧩 Extending TrustifAI (Custom Metrics)

You can plug in custom evaluation logic without modifying the core library.

• Inherit from BaseMetric and implement calculate().

• Register the metric with a unique key.

• Configure the weight in your YAML file.

Example: Adding a "Temporal Consistency" Metric

from trustifai.metrics import BaseMetric
from trustifai.structures import MetricResult

# 1. Define Metric
class TemporalConsistencyMetric(BaseMetric):
    """Detects temporal hallucinations - when the answer references dates/times
    that don't match the retrieved documents."""
    def calculate(self) -> MetricResult:
        # Extract dates from answer and documents
        answer_dates = self._extract_dates(self.context.answer) #assuming extract_dates logic is already implemented
        doc_dates = set()
        for doc in self.context.documents:
            doc_dates.update(self._extract_dates(doc.page_content))
        
        if not answer_dates:
            return MetricResult(
                score=1.0,
                label="No Temporal Claims",
                details={"answer_dates": [], "doc_dates": list(doc_dates)}
            )
        
        # Check if answer dates are within document date ranges
        supported_dates = [d for d in answer_dates if d in doc_dates]
        unsupported_dates = [d for d in answer_dates if d not in doc_dates]
        
        score = len(supported_dates) / len(answer_dates) if answer_dates else 1.0
        
        high_threshold = getattr(self.config.thresholds, 'TEMPORALLY_CONSISTENT', 0.8)
        low_threshold = getattr(self.config.thresholds, 'PARTIAL_TEMPORAL_ISSUES', 0.5)
        
        if score >= high_threshold:
            label = "Temporally Consistent"
        elif score >= low_threshold:
            label = "Partial Temporal Issues"
        else:
            label = "Temporal Hallucination Detected"
        
        return MetricResult(
            score=score,
            label=label,
            details={
                "answer_dates": answer_dates,
                "supported_dates": supported_dates,
                "unsupported_dates": unsupported_dates,
                "doc_dates": list(doc_dates)
            }
        )

# 2. Register Metric
from Trustifai import Trustifai
Trustifai.register_metric("temporal_consistency", TemporalConsistencyMetric)

# 3. Use in Trust Engine (Make sure to add it to config.yaml score_weights!)
trust_engine = Trustifai("config_file.yaml")
trust_score = trust_engine.get_trust_score(context)

Updated config.yaml:

metrics:
- type: "evidence_coverage"
    enabled: true
    params:

    ... # ... existing metrics ...
    
- type: "temporal_consistency"         # <--- Your new metric
    enabled: true
    params: 
      TEMPORALLY_CONSISTENT: 0.80
      PARTIAL_TEMPORAL_ISSUES: 0.50 

score_weights:
  - type: "evidence_coverage"
    params: { weight: 0.4 }
    # ... other existing metrics ...
  - type: "temporal_consistency"         # <--- Your new metric
    params: { weight: 0.1 }   # Weights must sum to ~1.0

🛠️ Flow

Input (Query, Answer, Documents)
    ↓
Validation & Type Normalization
    ├─ Accepts: Strings, LangChain/LlamaIndex Documents, Lists, Dicts
    └─ Returns: MetricContext
    ↓
Embedding Computation (Cached or Computed)
    ├─ Query embedding
    ├─ Answer embedding
    └─ Document embeddings
    ↓
Initialize Active Metrics
    ├─ Evidence Coverage Metric
    ├─ Semantic Drift Metric
    ├─ Epistemic Consistency Metric
    ├─ Source Diversity Metric
    └─ Confidence Metric (real-time only for response generation)
    ↓
Parallel Metric Execution
    ├─ Each metric: calculate(context) → MetricResult
    └─ Async-safe: Thread isolation for event loop conflicts
    ↓
Result Aggregation & Thresholding
    ├─ Weighted sum: Σ(weight_i × metric_score_i)
    ├─ Threshold classification: RELIABLE | ACCEPTABLE | UNRELIABLE
    └─ Cost accumulation
    ↓
Reasoning Graph Construction
    ├─ Nodes: Metrics, aggregation, decision
    ├─ Edges: Data flow relationships
    └─ Color-coded by confidence: green ≥ STRONG, orange ≥ PARTIAL, red < PARTIAL
    ↓
Output: TrustScore Result + Visualization

🎯 Benchmarks

• Amnesty QA

TODO

• Improve Tracing
• Support for GraphRAG