ACL AGI TypeScript SDK (acl-fast)

Official TypeScript SDK for ACL AGI.

Installation

npm install acl-fast

AI Agent Install And Infra Setup

Use this flow when agents/dev tools install and run ACL in production:

1. Install SDK

npm install acl-fast@latest

2. Set environment variables (domain only, never raw server IP)

# Current ACL backend endpoint (HTTP)
export ACL_BASE_URL="https://backend.fridayaicore.in"

# Org-scoped ACL key from ACL dashboard
export ACL_API_KEY="acl_live_xxx"

# Provider key stays only with your app/agent runtime
export LLM_API_KEY="your_provider_key"

3. Initialize client using env vars

import { ACLClient } from 'acl-fast';

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

Security notes:

• Current deployment uses https://backend.fridayaicore.in by default.

Quick Start

import { ACLClient } from 'acl-fast';

const client = new ACLClient({ apiKey: 'acl_live_...' });

const result = await client.complete({
  prompt: 'Summarize this incident report.',
  model: 'gpt-4o',
  llm_api_key: process.env.LLM_API_KEY!,
  session_id: 'org_123:user_42:chat_abc', // keep stable per conversation
  max_retries: 3,
});

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

Latency Controls

new ACLClient(...) supports these runtime options:

• emitPostCompletionTelemetry (default: true): post-completion telemetry is non-blocking.
• precheckCacheTtlMs (default: 20000): short TTL cache for adaptive precheck calls.
• precheckCacheMaxEntries (default: 256): max in-memory precheck cache entries.

Every complete() response now includes timing metadata under metadata.acl_timing:

• precheck_ms
• provider_ms
• post_telemetry_ms
• wall_clock_ms

Runtime Contract

complete() always returns a stable top-level response shape on both success and failure:

• success
• error_code
• error_message
• provider
• model
• text and response

Validation and Safety

• Fail-fast validation for invalid/missing prompt, unresolved model, missing keys, and malformed provider key formats.
• Strict provider payload allowlist prevents internal ACL params from leaking to provider APIs.
• Secrets are redacted from surfaced error messages by default.
• Production default ACL base URL is https://backend.fridayaicore.in.

Retry Behavior

• complete() is server-executed: SDK calls /api/v1/complete/execute.
• If ACL backend is unavailable or returns auth/permission/server failures, SDK attempts direct-provider fallback locally.
• Retries/loop recovery/continuation handling are performed server-side in /complete/execute.
• Exponential backoff with jitter and cap:
• attempt 1: random delay 0-0.5s
• attempt 2: random delay 0-1s
• attempt 3: random delay 0-2s
• max cap per attempt: 8s

Compatibility Policy

• Node.js: >=16
• Module output: CommonJS (dist/index.js)
• Types: bundled .d.ts in dist/
• Release policy: include migration notes whenever response contract or validation behavior changes.

Usage Terms

• This SDK is proprietary and licensed for ACL service access only.
• A valid ACL API key is required.
• Redistribution, resale, sublicensing, and derivative redistribution are not permitted without written approval from ACL Team.

License

UNLICENSED / Proprietary. See LICENSE.