SDK reference
understand()
Ask grounded, cited questions about any account, user, feature, or your whole portfolio.
understand() is the query surface — the reason Atune exists. Ask a
plain-language question about an entity and get a grounded, cited answer back.
import { understand } from "atune";
const result = await understand(entity, question);Entities
entity is one of:
| Entity | Example |
|---|---|
account:<externalId> | account:acme |
user:<accountExternalId>/<userExternalId> | user:acme/u_123 |
feature:<key> | feature:feature.report |
portfolio | your whole book of business |
Result
Every answer is grounded in that workspace's real signals and cited — and says
knows: false when there isn't enough understanding yet, instead of guessing.
type UnderstandResult = {
knows: boolean; // false ⇒ "not enough understanding yet"
answer: string; // plain-language, grounded in your signals
confidence: number; // 0..1
citations: { signal: string; value: string; when: string }[];
recommendedNext: string | null; // one action, only when confident
signals: Record<string, unknown>; // the structured grounding bundle (LLM-free)
};Always branch on knows before using answer:
const r = await understand("account:acme", "why did they go quiet?");
if (r.knows) {
console.log(r.answer); // grounded, cited
console.log(r.recommendedNext); // one action, when confident
} else {
// not enough understanding yet — don't force an answer
}Options
understand(entity, question, { apiKey, url, fetch });All optional. apiKey / url fall back to the ATUNE_API_KEY / ATUNE_URL
env vars; fetch lets you inject a custom fetch implementation.
Why it's trustworthy
The signals bundle is computed without an LLM, and citations point at the
exact facts behind an answer. See
Understanding & the Context Layer.