Documentation

Integrate acl-fast into your production AI systems in minutes.

ACL Fast SDK

ACL (Adaptive Context Layer) is a production reliability layer that sits between your app and any LLM provider. It prevents silent failures, detects and breaks response loops, fixes truncation, enhances output quality in real-time through the Kepler Intelligence Layer, and handles automatic retry with direct provider fallback — so your AI never goes down.

Package: acl-fast | Version: 2.7.6 | Node.js: >=16

Installation

npm install acl-fast@latest

Authentication

ACL uses two separate keys:

  • ACL_API_KEY - Your ACL account key from acl.friday.ai/dashboard
  • LLM_API_KEY - Your own provider key (OpenAI, Anthropic, etc.)
# ACL Backend endpoint
export ACL_BASE_URL="https://backend.friday.ai"
export ACL_API_KEY="acl_live_xxx"  # Your ACL key
export LLM_API_KEY="sk-xxx"      # Your LLM provider key

Quick Start

import { ACLClient } from "acl-fast";

const client = new ACLClient({
  apiKey: process.env.ACL_API_KEY!,
  baseUrl: process.env.ACL_BASE_URL!,
});

const result = await client.complete({
  prompt: "Summarize this incident report.",
  model: "gpt-4o",
  llm_api_key: process.env.LLM_API_KEY!,
  provider: "openai",
  session_id: "user_123:chat_abc",
});

if (result.success) {
  console.log(result.text);
} else {
  console.error(`${result.error_code}: ${result.error_message}`);
}

Supported Providers

OpenAI

const result = await client.complete({
  prompt: "Hello",
  model: "gpt-4o",
  provider: "openai",
  llm_api_key: "sk-...",
});

Anthropic

const result = await client.complete({
  prompt: "Hello",
  model: "claude-3-5-sonnet-20241022",
  provider: "anthropic",
  llm_api_key: "sk-ant-...",
});

Google Gemini

const result = await client.complete({
  prompt: "Hello",
  model: "gemini-1.5-pro",
  provider: "google",
  llm_api_key: "AIza...",
});

Groq

const result = await client.complete({
  prompt: "Hello",
  model: "llama-3.1-70b-versatile",
  provider: "groq",
  llm_api_key: "gsk_...",
});

Together AI

const result = await client.complete({
  prompt: "Hello",
  model: "meta-llama/Llama-3-70b-chat-hf",
  provider: "together",
  llm_api_key: "...",
});

Azure OpenAI

Requires azure_resource_name and azure_deployment_name from Azure Portal.

const client = new ACLClient({
  apiKey: process.env.ACL_API_KEY!,
});

const result = await client.complete({
  prompt: "Hello",
  model: "gpt-4",
  provider: "azure",
  llm_api_key: "your-azure-api-key",
  azure_resource_name: "my-company-openai",
  azure_deployment_name: "gpt-4-deployment",
  azure_api_version: "2024-02-15-preview",
});

OpenAI-Compatible Providers

These providers use OpenAI-compatible API:

Providerprovider valueAPI Key Format
Perplexityperplexitypplx-...
xAIxaixAI key
Mistralmistralmistral key
Cerebrascerebrascerebras key
SambaNovasambanovasambanova key
DeepInfradeepinfradeepinfra key
OpenRouteropenrouteropenrouter key
Fireworksfireworksfireworks key

Automatic Fallback

When ACL backend fails (server down, payment failed, network error), the SDK automatically falls back to direct provider call.

// When ACL backend fails, SDK automatically falls back to direct provider call
// Response includes fallback metadata:
{
  success: true,
  response: "...",
  task_success: true,
  metadata: {
    fallback_used: true,        // Set to true when direct call was used
    fallback_reason: "server_down" | "payment_failed" | "credits_expired"
  }
}

Fallback triggers on: HTTP 402 (payment), 500/502/503 (server error), network timeout.

Response Structure

// Success
{
  success: true,
  text: "AI response text",   // primary field — use this
  response: "AI response text", // legacy alias, same as text
  provider: "openai",
  model: "gpt-4o",
  finish_reason: "stop",
  tokens_input: 10,
  tokens_output: 50,
  total_tokens: 60,
  latency_ms: 1200,
  retries: 0,
  attempts_made: 1,
  loop_detected: false,
  loop_recovery_attempted: false,
  was_continued: false,
  continuation_count: 0,
  task_success: true,
  error_code: null,
  error_message: null,
}

// Error
{
  success: false,
  response: "",
  error_code: "ACL_ERR_VALIDATION",
  error_message: "prompt is required"
}

Compatibility Policy

  • Node.js: >=16
  • Module: CommonJS (dist/index.js)
  • Types: bundled .d.ts

Usage Terms

  • Proprietary SDK licensed for ACL service access only.
  • Valid ACL API key required.
  • Redistribution not permitted without written approval.