@glamcor/dna-ai-assistant

Shared DNA AI assistant panel package for DNA microsites.

Installation

npm install @glamcor/dna-ai-assistant

React and React DOM are peer dependencies:

{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}

Import Styles

Import the package CSS once in the app shell, usually next to shared nav styles:

import '@glamcor/dna-ai-assistant/styles.css';

tokens.css is also exported if a host app wants only the AI design tokens:

import '@glamcor/dna-ai-assistant/tokens.css';

Usage

import { DNAAssistant } from '@glamcor/dna-ai-assistant';
import '@glamcor/dna-ai-assistant/styles.css';

export function PageAssistant() {
  return (
    <DNAAssistant
      app="nitrogen"
      pageId="orders.detail"
      entityType="salesOrder"
      entityId="SO-10482"
      user={{ id: "user-123", role: "warehouse" }}
    />
  );
}

Exports

• DNAAssistant
• DNAAssistantProps
• TriggerState
• ActionTier
• Sensitivity
• AppKey
• AIAnswerResponse
• Evidence
• TraceStep
• NextAction

Publishing context

Host apps publish page/record context so the assistant shows human-readable grounding instead of raw paths. Context is re-sent on every turn, so the LLM always knows where the user is and what they are looking at.

Context shape

| Field | Type | Purpose | |-------|------|---------| | pageTitle | string | Human-readable page title, e.g. "Executive Pulse" | | entityType | string | Record type, e.g. "salesOrder", "deliveryNote" | | entityId | string | Canonical record ID, e.g. "SO-1234" (not a URL path) | | recordSummary | string | One-sentence state summary for the LLM prompt | | extra.capabilities | string[] | Available actions on the current page, e.g. ["dashboard.proposeWidget"] |

Declarative: <DNAAssistantContextSetter />

Place one setter for the page title in your layout:

<DNAAssistantContextSetter
  pageTitle="Executive Pulse"
  extra={{ capabilities: ['dashboard.proposeWidget'] }}
/>

And another for record details on a detail page:

<DNAAssistantContextSetter
  entityType="salesOrder"
  entityId="SO-1234"
  recordSummary="Stuck in pack, 2 SKUs unavailable"
/>

Imperative: useDNAAssistantSetter()

For class components or effects that cannot render the declarative setter:

const setAssistantContext = useDNAAssistantSetter();

useEffect(() => {
  setAssistantContext({
    pageTitle: 'Executive Pulse',
    entityType: 'salesOrder',
    entityId: 'SO-1234',
    recordSummary: 'Stuck in pack, 2 SKUs unavailable',
    extra: { capabilities: ['dashboard.proposeWidget'] },
  });
}, [setAssistantContext]);

Merge semantics

setContext and <DNAAssistantContextSetter /> merge new values into the existing context:

• Provided fields overwrite existing values.
• Omitted fields are preserved.
• extra is shallow-merged ({ ...prevExtra, ...nextExtra }).
• Pass true as the second argument to replace the whole context:

setAssistantContext({ pageTitle: 'New page' }, true);

This lets multiple setters coexist safely: a layout setter can own pageTitle while a record detail setter owns entityId/recordSummary.

Publish

npm run type-check
npm run build
npm pack --dry-run
npm publish --access public

After publishing, update consumer repos from /Users/erikkaiser/DNA:

npm run update:ai-assistant