Quick Start Guide
Get AletheionGuard up and running in 5 minutes
1. Installation
Install AletheionGuard with a single pip command:
pip install aletheion-guard
✓ This installs the Python SDK with pre-trained models included (~2.3MB)
2. Basic Usage
Audit any text for epistemic uncertainty:
from aletheion_guard import EpistemicAuditor
# Initialize auditor (models load automatically)
auditor = EpistemicAuditor()
# Audit a statement
audit = auditor.evaluate("Paris is the capital of France")
# Check results
print(f"Verdict: {audit.verdict}") # ACCEPT
print(f"Q1 (aleatoric): {audit.q1:.3f}") # 0.082
print(f"Q2 (epistemic): {audit.q2:.3f}") # 0.045
print(f"Height: {audit.height:.3f}") # 0.906
Understanding the Output:
- Q1 (Aleatoric): Irreducible data noise/ambiguity [0-1]
- Q2 (Epistemic): Model ignorance/hallucination risk [0-1]
- Height: Confidence/truth proximity [0-1], calculated as 1 - √(Q1² + Q2²)
- Verdict: ACCEPT (reliable), MAYBE (review needed), or REFUSED (unreliable)
3. Integrate with OpenAI
Audit responses from GPT models to detect hallucinations:
from openai import OpenAI
from aletheion_guard import EpistemicAuditor
# Initialize
client = OpenAI()
auditor = EpistemicAuditor()
# Get LLM response
prompt = "What is quantum entanglement?"
response = client.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": prompt}]
)
answer = response.choices[0].message.content
# Audit the response
audit = auditor.evaluate(answer, context=prompt)
# Handle based on verdict
if audit.verdict == "REFUSED":
print("⚠️ High uncertainty - answer may be unreliable")
print(f"Q2: {audit.q2:.3f}")
elif audit.verdict == "MAYBE":
print("⚡ Moderate confidence - please verify")
else:
print("✓ High confidence answer")
print(answer)
4. Use REST API (Cloud)
Prefer not to install anything? Use our hosted API:
Python with requests:
import requests
response = requests.post(
"https://aletheionguard.onrender.com/v1/audit",
headers={"X-API-Key": "your_api_key"},
json={"text": "Paris is the capital of France"}
)
audit = response.json()
print(audit["verdict"])
cURL:
curl -X POST https://aletheionguard.onrender.com/v1/audit \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"text": "Paris is the capital of France"}'
Note: Get your API key at aletheionguard.com/signup. Free tier includes 1,000 requests/month.
5. RAG Integration (Adaptive Retrieval)
Use Q2 (epistemic uncertainty) to trigger additional retrieval when the model lacks knowledge:
from langchain.vectorstores import Chroma
from langchain_openai import ChatOpenAI
from aletheion_guard import EpistemicAuditor
auditor = EpistemicAuditor()
llm = ChatOpenAI(model="gpt-4")
vectorstore = Chroma(...)
def adaptive_rag(query, k=3, max_retries=2):
for attempt in range(max_retries):
# Retrieve documents
docs = vectorstore.similarity_search(query, k=k)
context = "\n\n".join([d.page_content for d in docs])
# Generate answer
answer = llm.invoke(f"Context: {context}\n\nQ: {query}").content
# Audit the answer
audit = auditor.evaluate(answer, context=query)
# If Q2 is low, we have enough knowledge
if audit.q2 < 0.35:
return answer, audit
# High Q2: retrieve more context
print(f"Q2={audit.q2:.2f} - retrieving more context...")
k += 3
return "Unable to answer with confidence", audit
Key Insight: High Q2 means the model doesn't have enough knowledge. This is a perfect signal to retrieve more context or escalate to a human.
6. Batch Processing
Process multiple texts efficiently:
from aletheion_guard import EpistemicAuditor
auditor = EpistemicAuditor()
texts = [
"The Earth orbits the Sun",
"Water boils at 100°C at sea level",
"The Moon is made of cheese" # This should have high Q2
]
# Batch process (more efficient than individual calls)
audits = auditor.batch_evaluate(texts, batch_size=32)
for text, audit in zip(texts, audits):
print(f"{text[:30]}... → {audit.verdict} (Q2: {audit.q2:.3f})")
Next Steps
Common Use Cases
🔍 Hallucination Detection
Catch when LLMs generate false information with high Q2 scores
🎯 Quality Assurance
Automatically filter low-confidence responses before production
🔄 Adaptive Systems
Trigger re-retrieval, model switching, or human escalation
Need Help?
Get support from our community or check out the documentation