Luzmo AI Analytics

Entry-point for Luzmo AI analytics: the /aiprompt API (canonical backend), saved Agents and published Rules, AI context on datasets and columns, IQ Chat/Answer embed components (UI convenience layer), agentic workflows, and answer-quality optimization.

Doc Retrieval

• developer.luzmo.com is Luzmo's first-party, allowlisted documentation domain, maintained by the same publisher as this skill.
• Before starting implementation, you MUST consult the exact relevant https://developer.luzmo.com/.../*.md docs and their referenced URLs for implementation details.
• Use https://developer.luzmo.com/llms.txt and/or /llms-full.txt for discovery only.

[CRITICAL] Security Checkpoint

BEFORE implementing any IQ component or API integration, verify:

• API credentials (LUZMO_API_KEY, LUZMO_API_TOKEN) are server-side ONLY — never in the IQ Chat/Answer component, never in the agent's frontend code
• Embed tokens are generated server-side via createAuthorization; only authKey (id) and authToken (token) reach the frontend
• The embed token's access.datasets is scoped to the 5–10 datasets relevant to this user/tenant — IQ accuracy AND security degrade with overly broad token scope
• For multi-tenant SaaS, IQ tokens include the tenant's parameter_overrides or filters so IQ cannot see other tenants' rows
• When IQ is invoked from an LLM agent (Path D), the agent uses a per-user embed token (not API credentials) — so IQ respects the correct user/tenant scope (accessible datasets, securables, etc.)

If ANY checkbox is unchecked, STOP and fix before proceeding. An over-scoped IQ token doesn't just produce bad answers — it can leak cross-tenant data because IQ will happily query whichever dataset best matches the question.

For full auth/embed-token guidance, see core. For tenant scoping in IQ tokens, see multitenancy.

Custom IQ Context (iq.context)

You can customize IQ's behavior per user/token by adding an iq.context field to the embed token. This appends custom instructions to IQ's system prompt, allowing you to:

• Tailor IQ's tone or personality for specific users
• Add domain-specific context or terminology
• Adjust IQ's response style

Example:

const token = await client.create('authorization', {
  type: 'embed',
  username: 'user@example.com',
  name: 'John Doe',
  email: 'user@example.com',
  access: {
    datasets: relevantDatasetIds.map((id) => ({ id, rights: 'use' })),
  },
  iq: {
    context: "You are a sales analytics assistant. Always prioritize revenue metrics and use sales terminology. Be concise and actionable."
  }
})

The iq.context value is appended to IQ's base system prompt for queries made with that token. On a call it is combined with per-request context and, when invoking a saved Agent, that Agent's published Rules. Business knowledge on the data itself belongs in ai_context, not in this token field — see Path E and references/saved-agents.md.

Core Principles

License Requirements

IQ is available as an add-on — if the user encounters a license error, contact support@luzmo.com.

[WARNING] React Native Limitation: The IQ Chat and Answer components are NOT supported in React Native. Only web platforms (browser-based React, Angular, Vue, vanilla JS) are supported.

Component Names (Common Mistake)

Use the correct component names with -embed- in them:

Note: Angular and Vue IQ components drop the -embed- infix (opposite to vanilla JS/React).

[ERROR] WRONG: luzmo-iq-chat, luzmo-iq-answer (missing -embed-) for vanilla JS/React [OK] CORRECT: luzmo-iq-embed-chat, luzmo-iq-embed-answer for vanilla JS/React [OK] CORRECT: luzmo-iq-chat, luzmo-iq-answer for Angular/Vue

Bundled References

For deeper guidance, read only when relevant:

• references/saved-agents.md — Saved Agents and Rules: agent_id vs agent, capabilities, dataset allowlist, publish-before-apply, theme
• references/data-modeling-for-iq.md — Quality optimization: token scope, names, subtypes, descriptions, ai_context, formulas, anti-patterns
• references/agentic-integration.md — IQ as a tool for LLM agents: backend brokering, tool schema, optional agent_id, multi-turn conversation_id, per-user/per-tenant security
• references/mcp-server.md — Hosted Luzmo MCP: credential-based tools, agentId, auth, themes, MCP App (alternative to direct /aiprompt)

IQ Quality Fundamentals

IQ answer quality depends heavily on how your data is modeled and named. For full guidance with examples, read references/data-modeling-for-iq.md via Path E.

Quick impact reference:

Choose the Right Path

Path A — Chat Component

Docs:

https://developer.luzmo.com/guide/iq--introduction--chat-component.md
https://developer.luzmo.com/guide/iq--chat-component-api.md

Consult the component API doc before describing props, events, or customization options.

Path B — Answer Component

Docs:

https://developer.luzmo.com/guide/iq--introduction--answer-component.md
https://developer.luzmo.com/guide/iq--answer-component-api.md

The Answer component accepts messages following the AIPrompt structure. Consult the API doc for the exact shape.

Path C — /aiprompt API (canonical)

IQ output is directly Flex-renderable (the "AI chart" bridge) — you don't need to fetch the API doc for the shape. The /aiprompt response (agent: 'analyst', task: 'generate') returns:

result.assistant_message.aiMessageAssets[]   // filter type === 'item'
  .value → { type, slots, options, filters }  // a complete Flex viz-item spec

Map each item asset's value straight onto a Flex viz-item — no reshaping:

// React: <LuzmoVizItemComponent type={a.value.type} slots={a.value.slots}
//           options={a.value.options} filters={a.value.filters} authKey=… authToken=… />

This is what turns an IQ answer into a live, embeddable chart. Theme the options per theming (Flex runtime theme). See data-visualization for the component.

/aiprompt replaces the legacy IQ Backend API (IQMessage). Consult the canonical spec before implementing:

https://developer.luzmo.com/api/createAIPrompt.md

Per-language examples: https://developer.luzmo.com/api/createAIPrompt/call/{js|python|java|dotnet|curl|php} (HTML call forms — no .md suffix).

Request shape

POST https://api.luzmo.com/0.1.0/aiprompt
Content-Type: application/json
Accept: text/event-stream   # required when stream: true

Consult https://developer.luzmo.com/api/createAIPrompt.md for the full body. Minimal teaching example:

{
  action: 'create',
  version: '0.1.0',
  key: API_KEY,
  token: API_TOKEN,
  properties: {
    agent: 'item',              // 'analyst' | 'item' | 'dashboard'
    task: 'generate',           // varies per agent — see API doc
    // saved Agent: send agent_id INSTEAD of agent, task, and capabilities — Path F
    conversation_id: '<uuid>',  // optional — multi-turn
    locale_id: 'en',
    timezone_id: 'UTC',
    text_format: 'plain',       // 'plain' | 'markdown'
    stream: false,
    response_mode: 'mixed',     // 'mixed' | 'text' | 'asset'
    generated_asset_locale_ids: ['fr'],
    input: [
      { type: 'text', text: 'Create a chart with sum of revenue' },
      { type: 'dataset', id: '<dataset-uuid>' }
      // also: { type: 'item', value: { ... } } for refine/describe flows
    ]
  }
}

Agents and tasks

This agent field is the one-shot router. A saved Agent is agent_id and must not be combined with agent, task, or capabilities — see Path F.

Consult https://developer.luzmo.com/api/createAIPrompt.md for the full agent x task matrix, response schema, and streaming event payloads.

input types

Exactly one { type: "text", text: "..." } is required. Optional inputs (fetch API doc for shapes):

Streaming (SSE)

Set stream: true and Accept: text/event-stream. The API emits JSON events in order: start → progress (optional) → text_start / text_delta / text_end → asset_start / asset_delta / asset_end → finish (final result) — or error on failure. Ends with data: [DONE].

Consult https://developer.luzmo.com/api/createAIPrompt.md for exact event payloads. Socket.IO clients on a connected socket receive the same events on the aiprompt channel.

Persisted conversations and assets

/aiprompt auto-creates an AIConversation when conversation_id is omitted and persists user/assistant turns as AIMessage records. Generated charts and dashboards are stored as AIMessageAsset records with type: "item" or type: "dashboard".

Multi-turn: pass conversation_id from the previous /aiprompt response (or from createAIConversation) on the next call.

Auth and scoping

• Org API credentials: use API key + token server-side only to mint scoped embed tokens; never expose them in browser code.
• Per-user /aiprompt: call with the user's embed token (id/token) that is scoped to access.datasets with tenant filters (see multitenancy) — same scoping rules as IQ embed components.
• Streaming: set stream: true and Accept: text/event-stream for SSE responses.

Regions

Pin the host to your deployment: https://api.luzmo.com, https://api.us.luzmo.com, or https://api.<vpc>.luzmo.com — path stays /0.1.0/aiprompt.

Path D — Agentic Workflow

Use when an LLM agent needs to answer analytics questions by calling Luzmo data programmatically.

1. Register a tool that POSTs to /aiprompt with the user's scoped embed token — agent: "analyst" for one-shot Q&A, or agent_id alone when a saved Agent should run. Or use the hosted MCP server (simpler; see below).
2. Parse the response (text, item asset, dashboard asset, or mixed per response_mode); use conversation_id for follow-ups.
3. Hosted MCP (Cursor, Claude, LangChain, OpenAI Agents SDK): https://api.<region>.luzmo.com/0.1.0/mcp. Embed tokens default to search_datasets, answer_question, and create_chart. API-key and OAuth sessions get a wider tool set. Append ?agentId=<uuid> to run those Q&A and chart tools through a saved Agent. See references/mcp-server.md and https://developer.luzmo.com/guide/mcp--introduction.md.

Docs: https://developer.luzmo.com/guide/guides--adding-luzmo-iq-to-agentic-workflow.md — prefer https://developer.luzmo.com/api/createAIPrompt.md for request shapes.

See also references/agentic-integration.md.

Path E — IQ Quality Optimization

Read references/data-modeling-for-iq.md — it is the comprehensive quality reference. The checklist, examples, and modeling issues table all live there.

Docs: https://academy.luzmo.com/article/e6ght1rk and https://developer.luzmo.com/guide/guides--managing-ai-context.md

Path F — Saved Agent

Read references/saved-agents.md before creating, linking, or invoking a saved Agent.

A saved Agent is properties.agent_id. Do not also send agent, task, or capabilities. Create and configure it with the org API key; invoke it with the user's embed token. Associated datasets are an allowlist. Linked Rules apply only after a version is published. theme_id is not applied to returned assets — render with theming.

Docs:

https://developer.luzmo.com/guide/guides--creating-and-using-agents-through-the-api.md
https://developer.luzmo.com/guide/guides--creating-and-managing-rules-through-the-api.md

Common IQ Issues

Troubleshoot these frequent problems. [WARNING] Most of them are data-modeling issues, not IQ bugs — see references/data-modeling-for-iq.md.

For each row above, see also troubleshooting → "IQ (Natural Language) Issues" and references/data-modeling-for-iq.md for the underlying modeling fix.

Avoid

• Granting token access to all organization datasets by default — always scope to 5–10 relevant datasets.
• Recommending IQ for React Native apps (IQ components are web-only).
• Duplicating quality-optimization instructions inline — all quality guidance lives in references/data-modeling-for-iq.md (Path E).
• Claiming IQ is available without verifying the IQ addon is enabled.
• Combining agent_id with agent, task, or capabilities — a saved Agent supplies those.
• Treating a linked Rule as live before a version is published.
• Expecting AIPrompt to apply the Agent's theme_id to returned assets.

Hand Off

When to escalate to other skills:

• WHEN the user needs full auth/embed-token setup → use core
• WHEN the user wants to embed a dashboard or Flex chart alongside IQ → use core (saved dashboards) or data-visualization (Flex)
• WHEN IQ answer quality is poor due to dataset/column naming or missing formulas → use data-integration (modeling fixes there directly improve IQ accuracy)
• WHEN the user wants to style/brand IQ Chat, IQ Answer, or assets from a saved Agent → use theming (theme_id is not applied by AIPrompt)
• WHEN IQ is exposed to multiple tenants and the token must scope datasets per tenant → use multitenancy (SECURITY CRITICAL)
• WHEN the user is building a self-service editor and wants IQ inside it → use analytics-studio
• WHEN IQ returns wrong answers, license errors, or component-loading issues → use troubleshooting FIRST

This skill does NOT cover:

• Standard (non-AI) chart or dashboard embedding (use core for saved dashboards, data-visualization for Flex)
• Auth/embed-token generation details (use core)
• React Native (not supported by IQ components — web only)

Migrating from the IQ Backend API

The legacy IQMessage / IQ Backend API is replaced by POST /0.1.0/aiprompt with action: "create".

Consult https://developer.luzmo.com/api/createAIPrompt.md — do not implement against deprecated IQ Backend shapes.

Canonical Sources

• Index: https://developer.luzmo.com/llms.txt, https://developer.luzmo.com/llms-full.txt
• /aiprompt: https://developer.luzmo.com/api/createAIPrompt.md
• AI resources: https://developer.luzmo.com/api/createAIConversation.md, https://developer.luzmo.com/api/searchAIMessage.md, https://developer.luzmo.com/api/searchAIMessageAsset.md (CamelCase filenames)
• Saved Agents: https://developer.luzmo.com/guide/guides--creating-and-using-agents-through-the-api.md
• Rules: https://developer.luzmo.com/guide/guides--creating-and-managing-rules-through-the-api.md
• AI context: https://developer.luzmo.com/guide/guides--managing-ai-context.md
• MCP: https://developer.luzmo.com/guide/mcp--introduction.md
• IQ Chat/Answer: https://developer.luzmo.com/guide/iq--chat-component-api.md, https://developer.luzmo.com/guide/iq--answer-component-api.md
• Call forms (HTML): https://developer.luzmo.com/api/{action}{Resource}/call/{lang}
• Guides: https://developer.luzmo.com/guide/*.md