Abbox Guard Documentation

ABBOX_API_KEY=abbox_live_your_key_id_your_secret
ABBOX_API_BASE_URL=https://api.abbox.com  # or your self-hosted URL

npm install @abbox/guard

import { checkWithAbboxGuard, shouldBlock, hasSuggestedRewrite } from '@abbox/guard';

// Abbox Guard: Check prompt before processing
try {
  const decision = await checkWithAbboxGuard(
    {
      prompt: parsed.data.prompt,
      source: "abbox-saas-server",
      actorId: "system",
    },
    {
      apiKey: process.env.ABBOX_API_KEY,
      baseUrl: process.env.ABBOX_API_BASE_URL || "http://localhost:4000",
    },
  );
  // Block if decision is "block" or has suggested rewrite
  if (shouldBlock(decision) || hasSuggestedRewrite(decision)) {
    return res.json({
      abboxGuard: {
        decision: decision.decision,
        reason: decision.reason,
        suggestedRewrite: decision.suggested_rewrite,
      },
      message:
        decision.decision === "block"
          ? "Request blocked by abbox guard policy."
          : "Request requires modification. See suggested_rewrite.",
      data: [],
      rowCount: 0,
    });
  }
  // If allowed, continue with normal flow
} catch (e: any) {
  console.error("[ask-route] Abbox Guard error:", e);
  return res.status(500).json({
    error: "abbox_guard_error",
    message: `Failed to check prompt: ${String(e?.message ?? e)}`,
  });
}

Pattern 1: Block and Return Error

const decision = await checkWithAbboxGuard({
  prompt,
  source: 'my-app',
  actorId: userId
});

if (decision.decision === 'block') {
  throw new Error(`Request blocked: ${decision.reason}`);
}

// Continue with AI processing

Pattern 2: Suggest Rewrite to User

const decision = await checkWithAbboxGuard({
  prompt,
  source: 'my-app',
  actorId: userId
});

if (decision.suggested_rewrite) {
  return {
    error: 'Please rephrase your request',
    suggestion: decision.suggested_rewrite,
    reason: decision.reason
  };
}

// Continue with AI processing

Pattern 3: Auto-Apply Rewrite

let finalPrompt = prompt;
const decision = await checkWithAbboxGuard({
  prompt,
  source: 'my-app',
  actorId: userId
});

if (decision.decision === 'block') {
  throw new Error(`Request blocked: ${decision.reason}`);
}

if (decision.suggested_rewrite) {
  finalPrompt = decision.suggested_rewrite;
  // Optionally log that a rewrite was applied
}

// Continue with AI processing using finalPrompt

Pattern 4: Fail-Open (Allow on Error)

import { checkWithAbboxGuardFailOpen } from '@abbox/guard';

try {
  const decision = await checkWithAbboxGuardFailOpen({
    prompt,
    source: 'my-app',
    actorId: userId
  });
  if (decision.decision === 'block') {
    throw new Error(`Blocked: ${decision.reason}`);
  }
} catch (error) {
  // If Abbox Guard is unavailable, allow the request
  console.warn('Abbox Guard unavailable, allowing request:', error);
}

// Continue with AI processing

Pattern 5: Fail-Closed (Block on Error)

import { checkWithAbboxGuardFailClosed } from '@abbox/guard';

try {
  const decision = await checkWithAbboxGuardFailClosed({
    prompt,
    source: 'my-app',
    actorId: userId
  });
  if (decision.decision === 'block') {
    throw new Error(`Blocked: ${decision.reason}`);
  }
} catch (error) {
  // If Abbox Guard is unavailable, block the request for security
  throw new Error('Policy check unavailable - request blocked for security');
}

Node.js / Express

const express = require('express');
const app = express();

async function checkPromptWithAbbox(prompt, source, actorId) {
  const response = await fetch(`${process.env.ABBOX_API_BASE_URL}/v1/decide`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.ABBOX_API_KEY}`
    },
    body: JSON.stringify({
      prompt,
      source,
      actor: { id: actorId },
      metadata: {}
    })
  });
  return await response.json();
}

app.post('/api/chat', async (req, res) => {
  const { prompt, userId } = req.body;
  
  const decision = await checkPromptWithAbbox(prompt, 'my-app', userId);
  
  if (decision.decision === 'block') {
    return res.status(403).json({ error: decision.reason });
  }
  
  // Continue with AI processing...
});

Python / FastAPI

import os
import httpx

async def check_prompt_with_abbox(prompt: str, source: str, actor_id: str):
    api_key = os.getenv('ABBOX_API_KEY')
    base_url = os.getenv('ABBOX_API_BASE_URL', 'https://api.abbox.com')
    
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{base_url}/v1/decide",
            headers={
                'Authorization': f'Bearer {api_key}',
                'Content-Type': 'application/json'
            },
            json={
                'prompt': prompt,
                'source': source,
                'actor': {'id': actor_id},
                'metadata': {}
            }
        )
        return response.json()

@app.post('/api/chat')
async def chat(request: ChatRequest):
    decision = await check_prompt_with_abbox(
        request.prompt, 'my-app', request.user_id
    )
    
    if decision['decision'] == 'block':
        raise HTTPException(status_code=403, detail=decision['reason'])
    
    # Continue with AI processing...

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

type Decision struct {
    Decision        string `json:"decision"`
    Reason          string `json:"reason"`
    SuggestedRewrite string `json:"suggested_rewrite"`
}

func checkPromptWithAbbox(prompt, source, actorID string) (*Decision, error) {
    apiKey := os.Getenv("ABBOX_API_KEY")
    baseURL := os.Getenv("ABBOX_API_BASE_URL")
    if baseURL == "" {
        baseURL = "https://api.abbox.com"
    }
    
    body, _ := json.Marshal(map[string]interface{}{
        "prompt": prompt,
        "source": source,
        "actor": map[string]string{"id": actorID},
        "metadata": map[string]interface{}{},
    })
    
    req, _ := http.NewRequest("POST", baseURL+"/v1/decide", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    
    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var decision Decision
    json.NewDecoder(resp.Body).Decode(&decision)
    return &decision, nil
}

"Invalid or missing API key"

• Verify ABBOX_API_KEY is set correctly
• Ensure the key format is abbox_live_{keyId}_{secret}
• Check for extra spaces or newlines in the environment variable

"Policy check unavailable"

• Check network connectivity to ABBOX_API_BASE_URL
• Verify the API endpoint is accessible
• Check API status at your dashboard

Timeout errors

• Increase timeout for Abbox Guard calls
• Consider implementing retry logic with exponential backoff
• Use fail-open pattern if timeouts are frequent