Tensalis API Reference

Authorization: Bearer YOUR_API_KEY

POST https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify

Content-Type: application/json

{
  "response": "string (required)",
  "reference_facts": ["string"] (required),
  "threshold": float (optional, default: 0.85),
  "return_details": boolean (optional, default: false)
}

{
  "status": "VALIDATED",
  "confidence": 0.92,
  "processing_time_ms": 1847,
  "model_version": "5.4.1"
}

{
  "status": "BLOCKED",
  "confidence": 0.73,
  "processing_time_ms": 2134,
  "model_version": "5.4.1",
  "details": {
    "entailment_score": 0.73,
    "contradiction_score": 0.18,
    "neutral_score": 0.09,
    "classification": "NEUTRAL",
    "reasoning": "Response contains claims that cannot be verified from source context"
  }
}

IF entailment_score >= threshold (default: 0.85):
    status = "VALIDATED"

ELSE:
    status = "BLOCKED"

{
  "error": "Missing required field: response",
  "status": "error",
  "code": 400
}

{
  "error": "Response text too long (max 2000 tokens)",
  "status": "error",
  "code": 422
}

{
  "error": "Model inference failed",
  "status": "error",
  "code": 500
}

{
  "error": "Service temporarily unavailable",
  "status": "error",
  "code": 503,
  "retry_after": 60
}

import requests

def verify_response(llm_output: str, context: list[str]) -> dict:
    """Verify LLM output against source context."""
    response = requests.post(
        "https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify",
        json={
            "response": llm_output,
            "reference_facts": context
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Example usage
context = [
    "Our return policy allows returns within 30 days of purchase.",
    "All returns must include original packaging and receipt."
]

llm_output = "You can return items within 30 days with the receipt."

result = verify_response(llm_output, context)

if result["status"] == "VALIDATED":
    print(f"✅ Response verified (confidence: {result['confidence']:.2%})")
else:
    print(f"❌ Response blocked (confidence: {result['confidence']:.2%})")

✅ Response verified (confidence: 92.00%)

import requests
from typing import Optional

def verify_with_retry(
    llm_output: str, 
    context: list[str],
    threshold: float = 0.85,
    max_retries: int = 3
) -> Optional[dict]:
    """Verify with automatic retry on transient failures."""

    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify",
                json={
                    "response": llm_output,
                    "reference_facts": context,
                    "threshold": threshold,
                    "return_details": True
                },
                timeout=10
            )

            if response.status_code == 200:
                return response.json()
            elif response.status_code == 503:
                # Service unavailable - wait and retry
                retry_after = response.json().get("retry_after", 5)
                print(f"Service busy, retrying in {retry_after}s...")
                time.sleep(retry_after)
                continue
            else:
                # Non-retryable error
                response.raise_for_status()

        except requests.exceptions.Timeout:
            print(f"Timeout on attempt {attempt + 1}/{max_retries}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            else:
                raise

    return None

# Example usage
result = verify_with_retry(
    llm_output="Returns accepted within 90 days.",  # Wrong!
    context=["Return policy: 30 days from purchase."],
    threshold=0.85
)

if result:
    print(f"Status: {result['status']}")
    print(f"Confidence: {result['confidence']:.2%}")
    print(f"Reasoning: {result['details']['reasoning']}")

Status: BLOCKED
Confidence: 67.00%
Reasoning: Response contains numerical value (90 days) that contradicts context (30 days)

async function verifyResponse(llmOutput, context, threshold = 0.85) {
  try {
    const response = await fetch(
      'https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          response: llmOutput,
          reference_facts: context,
          threshold: threshold
        })
      }
    );

    if (!response.ok) {
      throw new Error(`Verification failed: ${response.statusText}`);
    }

    const result = await response.json();
    return result;

  } catch (error) {
    console.error('Verification error:', error);
    throw error;
  }
}

// Example usage
const context = [
  "Battery life: up to 8 hours of continuous use",
  "Charging time: 2 hours for full charge"
];

const llmOutput = "The battery lasts 8 hours and charges in 2 hours.";

verifyResponse(llmOutput, context)
  .then(result => {
    console.log(`Status: ${result.status}`);
    console.log(`Confidence: ${(result.confidence * 100).toFixed(1)}%`);
  })
  .catch(error => {
    console.error('Failed to verify:', error);
  });

curl -X POST https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "response": "The product ships within 24 hours.",
    "reference_facts": ["Standard shipping: 2-3 business days processing"],
    "threshold": 0.85
  }'

{
  "status": "BLOCKED",
  "confidence": 0.71,
  "processing_time_ms": 1923,
  "model_version": "5.4.1"
}

curl -X POST https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "response": "Multi-factor authentication is required for all accounts.",
    "reference_facts": ["MFA is optional but recommended for enhanced security"],
    "threshold": 0.85,
    "return_details": true
  }'

{
  "status": "BLOCKED",
  "confidence": 0.42,
  "processing_time_ms": 2087,
  "model_version": "5.4.1",
  "details": {
    "entailment_score": 0.42,
    "contradiction_score": 0.51,
    "neutral_score": 0.07,
    "classification": "CONTRADICTION",
    "reasoning": "Response states MFA is 'required' but context indicates 'optional' - semantic antonyms detected despite 95.8% embedding similarity"
  }
}

def chunk_and_verify(long_response: str, context: list[str]) -> list[dict]:
    """Verify a long response by chunking into paragraphs."""
    chunks = long_response.split('\n\n')  # Split by paragraph
    results = []

    for i, chunk in enumerate(chunks):
        if not chunk.strip():
            continue

        result = verify_response(chunk, context)
        results.append({
            'chunk_index': i,
            'text': chunk,
            'status': result['status'],
            'confidence': result['confidence']
        })

    return results

context = [
    "Pricing: $99/month for Pro plan",
    "Features: Unlimited projects, 10GB storage, priority support",
    "Free trial: 14 days, no credit card required"
]

context = [
    "We have various pricing tiers available",
    "Multiple features are included",
    "Trial period is offered"
]

# Test different thresholds on your data
thresholds = [0.75, 0.80, 0.85, 0.90, 0.95]
test_cases = [...]  # Your test data

for threshold in thresholds:
    validated = sum(
        1 for case in test_cases 
        if verify_response(case['response'], case['context'], threshold)['status'] == 'VALIDATED'
    )
    print(f"Threshold {threshold}: {validated}/{len(test_cases)} validated ({validated/len(test_cases):.1%})")

Threshold 0.75: 38/50 validated (76.0%)
Threshold 0.80: 32/50 validated (64.0%)
Threshold 0.85: 24/50 validated (48.0%)  ← Production default
Threshold 0.90: 18/50 validated (36.0%)
Threshold 0.95: 12/50 validated (24.0%)

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session():
    """Create session with automatic retries."""
    session = requests.Session()

    retry_strategy = Retry(
        total=3,
        status_forcelist=[429, 500, 502, 503, 504],
        backoff_factor=1,  # Wait 1s, 2s, 4s between retries
        allowed_methods=["POST"]
    )

    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)

    return session

# Use it
session = create_session()
response = session.post(
    "https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify",
    json={"response": "...", "reference_facts": [...]},
    timeout=10
)

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def verify_and_log(llm_output: str, context: list[str]) -> dict:
    """Verify and log results for monitoring."""
    result = verify_response(llm_output, context)

    logger.info(
        f"Verification: status={result['status']}, "
        f"confidence={result['confidence']:.2f}, "
        f"latency={result['processing_time_ms']}ms"
    )

    # Send to your monitoring system (Datadog, New Relic, etc)
    # metrics.increment(f"tensalis.{result['status'].lower()}")
    # metrics.histogram("tensalis.confidence", result['confidence'])
    # metrics.histogram("tensalis.latency", result['processing_time_ms'])

    return result

# 1. Lower threshold
result = verify_response(output, context, threshold=0.75)

# 2. Improve LLM prompting
prompt = """
Answer based ONLY on the following context. 
Do not add information not explicitly stated.
Be concise and factual.

Context: {context}

Question: {question}
"""

# 3. Add more complete context
context = [
    # Add all relevant details from source documents
    # Include specific facts, numbers, requirements
]

# 1. Implement warming (ping periodically)
import schedule
import time

def keep_warm():
    try:
        verify_response("test", ["test"], timeout=5)
    except:
        pass

schedule.every(5).minutes.do(keep_warm)

# 2. Use async/await for multiple requests
import asyncio
import aiohttp

async def verify_async(llm_output, context):
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://tensalis-engine-zlqsb5lbna-uc.a.run.app/v1/verify",
            json={"response": llm_output, "reference_facts": context}
        ) as response:
            return await response.json()

# Verify multiple responses in parallel
results = await asyncio.gather(
    verify_async(output1, context1),
    verify_async(output2, context2),
    verify_async(output3, context3)
)

# Use higher threshold for critical applications
result = verify_response(
    llm_output, 
    context, 
    threshold=0.90  # Stricter
)

# Or request detailed scores to investigate
result = verify_response(
    llm_output, 
    context,
    threshold=0.85,
    return_details=True
)

if result['status'] == 'VALIDATED' and result['details']['neutral_score'] > 0.15:
    # High neutral score suggests uncertainty - consider blocking
    print("Warning: Validated but uncertain (high neutral score)")

# Register webhook
POST /v1/webhooks
{
  "url": "https://your-app.com/tensalis-webhook",
  "events": ["verification.completed", "verification.failed"]
}

# Your webhook endpoint receives:
POST https://your-app.com/tensalis-webhook
{
  "event": "verification.completed",
  "timestamp": "2025-12-17T10:30:00Z",
  "data": {
    "verification_id": "ver_1234567890",
    "status": "BLOCKED",
    "confidence": 0.73,
    "processing_time_ms": 1847
  }
}