acl-core-py 1.9.5

Official Python client for the Adaptive Context Layer (ACL)

ACL Python SDK (acl-core-py)

Official Python SDK for Adaptive Context Layer (ACL).

Installation

pip install acl-core-py

AI Agent Install And Infra Setup

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

1. Install SDK

pip install --upgrade acl-core-py

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

# Public ACL endpoint behind your domain/reverse proxy
export ACL_BASE_URL="https://backend.yourcompany.com"

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

# Provider key stays only with your app/agent runtime
export OPENAI_API_KEY="sk-xxx"

3. Initialize client using env vars

import os
from acl import ACLClient

client = ACLClient(
    api_key=os.environ["ACL_API_KEY"],
    base_url=os.environ["ACL_BASE_URL"],
)

Security notes:

• Do not hardcode keys in source code.
• Do not expose EC2/public IP in SDK config; always use DNS/domain.
• Rotate keys immediately if logs/screenshots accidentally leak them.
• Keep backend behind TLS (https) and firewall to trusted ports only.

Quick Start

from acl import ACLClient

client = ACLClient(api_key="acl_live_...")

result = client.complete(
    prompt="Summarize this incident report.",
    model="gpt-4o",
    llm_api_key="sk-...",
    max_retries=3,
)

if result["success"]:
    print(result["response"])
else:
    print(f"{result['error_code']}: {result['error_message']}")

Latency Controls (v1.9.0)

ACLClient(...) supports these runtime options:

• emit_post_completion_telemetry (default: True): post-completion telemetry is now non-blocking.
• precheck_cache_ttl_s (default: 20.0): short TTL cache for adaptive precheck calls.
• precheck_cache_max_entries (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.
• Default ACL backend base URL: http://backend.fridayaicore.in.

Retry Behavior

• Retries happen in SDK provider execution middleware (complete() path).
• 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

• Python: >=3.8
• Runtime dependencies: requests, urllib3, typing_extensions
• 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.