SDK Reference

The Adaline SDK enables you to build production-ready AI agentic applications with enterprise-grade observability and deployment management.

Installation

TypeScript
Python

npm install @adaline/client @adaline/api

pip install adaline-client adaline-api

Overview

The Adaline SDK provides two core capabilities:

Deployment Management

Fetch and cache your deployed prompts with automatic background refresh:

getDeployment() / get_deployment() - Get a specific prompt deployment by ID
getLatestDeployment() / get_latest_deployment() - Get the latest prompt deployment by environment (e.g., production, staging)
initLatestDeployment() / init_latest_deployment() - Initialize cached prompt deployment with auto-refresh

Observability & Monitoring

Track every AI agentic application interaction with structured traces and spans:

Monitor - Buffer and batch log submissions with automatic retries and automatic flushing
Trace - High-level operation tracking (e.g., user request, workflow, agentic application interaction)
Span - Granular operation tracking (e.g., LLM call, tool execution, retrieval, embedding generation, function call, guardrail check, etc.)

Quick Start

TypeScript
Python

import { Adaline } from '@adaline/client';
import { Gateway } from '@adaline/gateway';
import { OpenAI } from '@adaline/openai';

// Initialize the Adaline client (reads ADALINE_API_KEY from environment)
const adaline = new Adaline();
const gateway = new Gateway();
const openaiProvider = new OpenAI();

// Get your deployed prompt configuration
const deployment = await adaline.getLatestDeployment({
  promptId: 'your-prompt-id',
  deploymentEnvironmentId: 'your-deployment-environment-id'
});

// Initialize monitoring for your project
const monitor = adaline.initMonitor({
  projectId: 'your-project-id',
  flushInterval: 5,
  maxBufferSize: 100
});

// Create a trace for the entire user interaction
const trace = monitor.logTrace({
  name: 'Chat Completion',
  sessionId: 'user-session-123'
});

// Log the LLM call as a span
const llmSpan = trace.logSpan({
  name: 'OpenAI GPT-4 Call',
  promptId: deployment.promptId,
  deploymentId: deployment.id
});

try {
  // Create model from deployment config
  const model = openaiProvider.chatModel({
    modelName: deployment.prompt.config.model,
    apiKey: process.env.OPENAI_API_KEY!
  });

  // Make your LLM call with the deployed configuration using Adaline Gateway
  const gatewayResponse = await gateway.completeChat({
    model,
    config: deployment.prompt.config.settings,
    messages: deployment.prompt.messages,
    tools: deployment.prompt.tools
  });

  // Update span with successful result
  llmSpan.update({
    status: 'success',
    content: {
      type: 'Model',
      provider: deployment.prompt.config.providerName,
      model: deployment.prompt.config.model,
      input: JSON.stringify(gatewayResponse.provider.request),
      output: JSON.stringify(gatewayResponse.provider.response)
    }
  });

  trace.update({ status: 'success' });
} catch (error) {
  llmSpan.update({ status: 'failure' });
  trace.update({ status: 'failure' });
}

// End tracking
trace.end();
await monitor.flush();

import asyncio
from openai import AsyncOpenAI
from adaline.main import Adaline
from adaline_api.models.log_span_content import LogSpanContent
from adaline_api.models.log_span_model_content import LogSpanModelContent
import json

async def main():
    # Initialize the Adaline client (reads ADALINE_API_KEY from environment)
    adaline = Adaline()

    # Get your deployed prompt configuration
    deployment = await adaline.get_latest_deployment(
        prompt_id="your-prompt-id",
        deployment_environment_id="your-deployment-environment-id"
    )

    # Initialize monitoring for your project
    monitor = adaline.init_monitor(
        project_id="your-project-id",
        flush_interval_seconds=5,
        max_buffer_size=100
    )

    # Create a trace for the entire user interaction
    trace = monitor.log_trace(
        name="Chat Completion",
        session_id="user-session-123"
    )

    # Log the LLM call as a span
    llm_span = trace.log_span(
        name="OpenAI GPT-4 Call",
        prompt_id=deployment.prompt_id,
        deployment_id=deployment.id
    )

    try:
        openai = AsyncOpenAI()
        response = await openai.chat.completions.create(
            model=deployment.prompt.config.model,
            messages=deployment.prompt.messages,
            **deployment.prompt.config.settings
        )

        llm_span.update({
            "status": "success",
            "content": LogSpanContent(
                actual_instance=LogSpanModelContent(
                    type="Model",
                    provider=deployment.prompt.config.provider_name,
                    model=deployment.prompt.config.model,
                    input=json.dumps(deployment.prompt.messages),
                    output=json.dumps(response.choices[0].message.model_dump())
                )
            )
        })

        trace.update({"status": "success"})
    except Exception:
        llm_span.update({"status": "failure"})
        trace.update({"status": "failure"})

    trace.end()
    await monitor.flush()
    monitor.stop()

asyncio.run(main())

Key Features

Automatic Background Refresh

Keep your prompts up-to-date without redeploying your application:

TypeScript
Python

const controller = await adaline.initLatestDeployment({
  promptId: 'your-prompt-id',
  deploymentEnvironmentId: 'your-deployment-environment-id',
  refreshInterval: 60
});

const deployment = await controller.get();
const refreshedDeployment = await controller.get(true);
controller.stop();

controller = await adaline.init_latest_deployment(
    prompt_id="your-prompt-id",
    deployment_environment_id="your-deployment-environment-id",
    refresh_interval=60
)

deployment = await controller.get()
refreshed_deployment = await controller.get(force_refresh=True)
await controller.stop()

Smart Buffering & Batching

Optimize performance with automatic batching and retry logic:

Logs are buffered in memory and flushed in batches
Automatic retry with exponential backoff on transient failures (5xx)
Configurable flush intervals and buffer sizes
Failed entries are counted and dropped, following the OpenTelemetry error handling principle

Comprehensive Observability

Track everything in your AI agentic application:

Model spans - LLM inference calls (streaming and non-streaming)
Tool spans - Function/API calls
Retrieval spans - RAG and vector database queries
Embeddings spans - Embedding generation
Function spans - Custom application logic
Guardrail spans - Safety and compliance checks

Rich Metadata

Attach detailed context to every operation and later search or filter on them.

Tags - Categorize and filter traces (e.g., ['production', 'high-priority'])
Attributes - Key-value metadata (e.g., { userId: '123', region: 'us-east' })
Sessions - Group related traces by session ID (e.g., user-session-123)
References - Link traces and spans with custom IDs (e.g., trace-ref-001)

Overview

Types

TypeScript

Python

​SDK Reference

​Installation

​Overview

​Deployment Management

​Observability & Monitoring

​Quick Start

​Key Features

​Automatic Background Refresh

​Smart Buffering & Batching

​Comprehensive Observability

​Rich Metadata

SDK Reference

Installation

Overview

Deployment Management

Observability & Monitoring

Quick Start

Key Features

Automatic Background Refresh

Smart Buffering & Batching

Comprehensive Observability

Rich Metadata