# HalluTrace AI
> LLM hallucination detection and tracing platform

## What is HalluTrace AI?
HalluTrace AI is a platform that helps developers detect hallucinations in their LLM (Large Language Model) outputs. It traces every LLM call, evaluates whether the output aligns with the system prompt, and provides real-time alerts when hallucinations are detected.

## How it works
1. Integrate our SDK (Python or JavaScript) or use the REST API
2. Send trace data: session_id, message type (agent/tool), input, output, system_prompt
3. Our engine automatically evaluates each response using LLM-as-judge
4. View scores (0-100, where 0 = no hallucination) in the dashboard
5. Get alerts via email, SMS, or webhook when scores exceed your threshold

## API Base URL
https://api.hallutraceai.com/v1/

## Authentication
All API calls require: Authorization: Bearer sk_live_your_api_key

## Core Endpoints

### Send Traces
POST /v1/traces
Content-Type: application/json
{
  "session_id": "chat-123",
  "messages": [
    {
      "message_id": "msg-001",
      "type": "agent",
      "input": "user question",
      "output": "llm response",
      "system_prompt": "your system prompt",
      "rag_context": "optional context",
      "model_name": "optional model name"
    }
  ]
}

### List Sessions
GET /v1/sessions?page=1&limit=20&from=2024-01-01&to=2024-12-31

### Get Messages
GET /v1/sessions/{session_uuid}/messages

### Run Evaluation
POST /v1/eval/run
{ "target": "session", "target_uuid": "session-uuid" }

### Get Eval Results
GET /v1/eval/results?session_uuid=xxx&min_score=0&max_score=100

### Export Data (JSON)
GET /v1/export/summary
GET /v1/export/chart-data

### Upload CSV
POST /v1/tables/{table_uuid}/upload

## Python SDK
pip install hallutraceai

from hallutraceai import HalluTrace
ht = HalluTrace(api_key="sk_live_xxx")
ht.trace(
    session_id="chat-123",
    type="agent",
    input="What is Python?",
    output="Python is a programming language.",
    system_prompt="You are a helpful assistant."
)

## JavaScript SDK
npm install hallutraceai

import { HalluTrace } from 'hallutraceai';
const ht = new HalluTrace({ apiKey: 'sk_live_xxx' });
await ht.trace({
  sessionId: 'chat-123',
  type: 'agent',
  input: 'What is Python?',
  output: 'Python is a programming language.',
  systemPrompt: 'You are a helpful assistant.'
});

## Scoring
- 0-10: Excellent (no hallucination)
- 11-30: Good (minor issues)
- 31-50: Warning (some misalignment)
- 51-70: Bad (significant hallucination)
- 71-100: Critical (largely fabricated)

## Pricing
- Free: 10,000 evals/month, 3 projects
- Pay as You Go: $0.001 per eval ($1 per 1,000)
- Enterprise: Custom pricing

## Links
- Website: https://hallutraceai.com
- API Docs: https://api.hallutraceai.com/v1/docs
- Dashboard: https://hallutraceai.com/dashboard