SDK Reference

Official Python and JavaScript SDKs with identical feature coverage. Choose your language once — the tab selection persists across the page.

Installation

Terminal

pip install qlm

Requires Python 3.8+. No native dependencies.

Terminal

npm install @qlm/sdk

Works in Node.js 18+ and modern browsers. Zero dependencies.

Configuration

Python

import qlm

# Option 1: Pass directly
client = qlm.Client(api_key="qlm_live_YOUR_KEY")

# Option 2: Environment variable (recommended)
# export QLM_API_KEY=qlm_live_YOUR_KEY
client = qlm.Client()

# Custom base URL (for self-hosted)
client = qlm.Client(
    api_key="qlm_live_YOUR_KEY",
    base_url="https://your-instance.example.com",
    timeout=30  # seconds
)

JavaScript

import { QLMClient } from '@qlm/sdk';

// Option 1: Pass directly
const client = new QLMClient({ apiKey: 'qlm_live_YOUR_KEY' });

// Option 2: Environment variable (Node.js)
// QLM_API_KEY=qlm_live_YOUR_KEY
const client = new QLMClient();

// Custom base URL
const client = new QLMClient({
  apiKey: 'qlm_live_YOUR_KEY',
  baseUrl: 'https://your-instance.example.com',
  timeout: 30000  // milliseconds
});

Optimize

Select optimal items from an item bank using adaptive item selection.

Python

result = client.optimize(
    item_bank_id="ib_m3n4o5",
    skill_levels=[0.5, -0.2, 0.8],
    items_administered=["item_001", "item_002"],
    n_select=5,
    constraints={
        "max_time": 300,
        "content_balance": True,
        "exclude_items": ["item_099"]
    }
)

# Access results
result.job_id              # 'opt_7f2a3b4c'
result.status              # 'completed'
result.selected_items      # [{'item_id': 'item_014', 'rank': 1}, ...]

JavaScript

const result = await client.optimize({
  itemBankId: 'ib_m3n4o5',
  skillLevels: [0.5, -0.2, 0.8],
  itemsAdministered: ['item_001', 'item_002'],
  nSelect: 5,
  constraints: {
    maxTime: 300,
    contentBalance: true,
    excludeItems: ['item_099']
  }
});

// Access results
result.jobId;              // 'opt_7f2a3b4c'
result.status;             // 'completed'
result.selectedItems;      // [{itemId: 'item_014', rank: 1}, ...]

Sessions

Full lifecycle: create, submit responses, check status, and delete.

Create Session

Python

session = client.sessions.create(
    organization_id="org_x9y8z7",
    item_bank_id="ib_m3n4o5",
    domain="clinical",
    config={
        "max_items": 30,
        "completion_threshold": 0.95
    }
)

session.session_id  # 'ses_a1b2c3d4'
session.status      # 'active'

JavaScript

const session = await client.sessions.create({
  organizationId: 'org_x9y8z7',
  itemBankId: 'ib_m3n4o5',
  domain: 'clinical',
  config: {
    maxItems: 30,
    completionThreshold: 0.95
  }
});

session.sessionId; // 'ses_a1b2c3d4'

Submit Responses

Python

update = client.sessions.respond(
    session_id="ses_a1b2c3d4",
    responses=[
        {"item_id": "item_014", "value": 3},
        {"item_id": "item_027", "value": 1},
    ]
)

update.converged               # False
update.next_items              # [{'item_id': 'item_089', 'rank': 1}, ...]

JavaScript

const update = await client.sessions.respond('ses_a1b2c3d4', {
  responses: [
    { itemId: 'item_014', value: 3 },
    { itemId: 'item_027', value: 1 },
  ]
});

update.converged;              // false
update.nextItems;              // [{itemId: 'item_089', rank: 1}, ...]

Check Status

Python

status = client.sessions.get("ses_a1b2c3d4")

status.converged                 # True

JavaScript

const status = await client.sessions.get('ses_a1b2c3d4');

status.converged;                // true

Delete Session

Python

client.sessions.delete("ses_a1b2c3d4")
# Returns: {'deleted': True, 'session_id': 'ses_a1b2c3d4'}

JavaScript

await client.sessions.delete('ses_a1b2c3d4');
// Returns: { deleted: true, sessionId: 'ses_a1b2c3d4' }

Domains

Specialized domains use the same session API. Just change the domain parameter.

Python — All domains

# Clinical
session = client.sessions.create(domain="clinical", item_bank_id="ib_clinical_v2")

# Cybersecurity
session = client.sessions.create(domain="cyber", item_bank_id="ib_cyber_v1")

# Financial
session = client.sessions.create(domain="financial", item_bank_id="ib_fin_v1")

# Education
session = client.sessions.create(domain="education", item_bank_id="ib_edu_v1")

# HR / Talent
session = client.sessions.create(domain="hr", item_bank_id="ib_hr_v1")

# Compliance
session = client.sessions.create(domain="compliance", item_bank_id="ib_comp_v1")

# Medical
session = client.sessions.create(domain="medical", item_bank_id="ib_med_v1")

# Language
session = client.sessions.create(domain="language", item_bank_id="ib_lang_v1")

# Safety
session = client.sessions.create(domain="safety", item_bank_id="ib_safety_v1")

# Personality
session = client.sessions.create(domain="personality", item_bank_id="ib_pers_v1")

JavaScript — All domains

// Clinical
await client.sessions.create({ domain: 'clinical', itemBankId: 'ib_clinical_v2' });

// Cybersecurity
await client.sessions.create({ domain: 'cyber', itemBankId: 'ib_cyber_v1' });

// Financial
await client.sessions.create({ domain: 'financial', itemBankId: 'ib_fin_v1' });

// Education
await client.sessions.create({ domain: 'education', itemBankId: 'ib_edu_v1' });

// HR / Talent
await client.sessions.create({ domain: 'hr', itemBankId: 'ib_hr_v1' });

// Compliance, Medical, Language, Safety, Personality — same pattern

Error Handling

Both SDKs throw typed exceptions for API errors.

Python

from qlm.exceptions import (
    QLMError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    NotFoundError
)

try:
    result = client.optimize(item_bank_id="invalid", skill_levels=[0.5])
except AuthenticationError:
    print("Check your API key")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except NotFoundError:
    print("Resource not found")
except QLMError as e:
    print(f"API error: {e.status_code} {e.error_code}")

JavaScript

import {
  QLMError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  NotFoundError
} from '@qlm/sdk';

try {
  const result = await client.optimize({ itemBankId: 'invalid' });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Check your API key');
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof ValidationError) {
    console.error(`Invalid: ${err.message}`);
  } else if (err instanceof QLMError) {
    console.error(`API error: ${err.statusCode} ${err.errorCode}`);
  }
}