@tagit/ai-client-core

Headless TypeScript client core for the tagIt AI orchestrator.

Use this package when you want to talk to the orchestrator directly and manage your own UI. It owns request shaping, streaming, retries, cancellation, conversation state, and optional collector emission.

This README is the source of truth for the core package.

What Is tagIt?

tagIt is the platform for building governed AI experiences. It gives teams a way to define AI use cases, connect models, optionally attach MCP servers, and shape the orchestration logic that drives the overall experience.

What Is the AI Orchestrator?

The AI Orchestrator is the runtime layer that executes a use case. It combines the configured model, optional tools and MCP servers, conversation context, and policy behavior to produce the response flow for a specific scenario.

Why This Package Exists

@tagit/ai-client-core is the client-side engine that connects your app to a tagIt account and a configured AI Orchestrator. You need a tagIt account and at least one configured use case before this package can drive a real experience.

MCP servers are optional, but they can extend the orchestrator with tools and external capabilities.

To learn more about tagIt and the orchestrator setup, visit tagit.live.

What This Package Provides

• AIClient for orchestrator communication and conversation state
• createDefaultConfig, validateConfig, and the config schema
• core types for orchestrator requests, stream chunks, messages, events, and collector payloads
• optional collector emission for TagIt conversation events

Public Imports

Supported public imports:

• @tagit/ai-client-core
• @tagit/ai-client-core/config
• @tagit/ai-client-core/types

Do not import from dist/* or from internal source paths.

Install

npm install @tagit/ai-client-core

Quick Start

import { AIClient, createDefaultConfig } from '@tagit/ai-client-core';

const client = new AIClient(
  createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
    user: {
      entityId: 'anonymous-or-authenticated-user-id',
      userId: 'optional-friendly-user-id',
      entityidType: 'internal_user_id',
      entityidAlgo: 'native',
      entityidOwner: 'your-service',
    },
    conversation: {
      conversationId: 'optional-durable-conversation-id',
      title: 'Optional conversation title',
      memoryMaxTurns: 6,
    },
    orchestrator: {
      apiKey: import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY,
    },
    collector: {
      enabled: false,
    },
  }),
);

Core Concepts

AIClient

AIClient is the stateful engine:

• builds the /v2/chat request
• manages the conversation transcript
• streams assistant output
• retries transient failures
• cancels in-flight requests
• emits collector events when enabled

ClientConfig

ClientConfig is the validated runtime configuration object that feeds the client.

OrchestratorRequest

OrchestratorRequest is the payload posted to the orchestrator /v2/chat endpoint.

OrchestratorChunk

OrchestratorChunk is the canonical SSE message shape expected from the orchestrator.

Configuration Dictionary

The core client is driven by a validated ClientConfig. If a field is omitted, the client uses its default.

createDefaultConfig(useCaseId, orchestratorUrl, options?)

This helper builds a safe starting config.

const config = createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
  collector: {
    enabled: false,
  },
});

| Field | Type / values | Default | What it does | Example | |---|---|---:|---|---| | useCaseId | string | required | Runtime use case identifier used by the orchestrator. | 'uc-default-1lji40' | | orchestratorUrl | URL string | required | Base URL for the orchestrator. Do not include /v2/chat. | 'https://ai.tagit.live' | | options.orchestrator | partial orchestrator config | undefined | Overrides specific orchestrator fields. | { apiKey: '...' } | | options.user | user identity config | undefined | Shared identity used by orchestrator memory and collector events. | { entityId: 'user_123' } | | options.conversation | conversation config | undefined | Durable conversation id, title, and memory window. | { memoryMaxTurns: 6 } | | options.collector | partial collector config | undefined | Enables or customizes collector emission. | { enabled: false } | | options.ui | partial UI config | undefined | Overrides client UI/runtime behavior. | { streaming: true } |

Shared User Config

The user block is the single identity source for V2. At minimum, production integrations should provide user.entityId. When user.userId is omitted, the SDK uses user.entityId as the orchestrator user_id and collector content.contentData.userId.

| Field | Type / values | Required | What it does | Example | |---|---|---:|---|---| | user.entityId | string | yes for production | Primary user or anonymous entity identifier supplied by the host app. | visitor_abc123 | | user.userId | string | no | Optional friendly/application user id. Defaults to entityId. | sandro | | user.entityidType | string | no | Entity type metadata for collector normalization. | internal_user_id | | user.entityidAlgo | string | no | Entity ID algorithm metadata. | native | | user.entityidOwner | string | no | Entity owner metadata. | tagit.live |

Shared Conversation Config

The conversation block controls durable memory. The SDK sends only the current user message to the orchestrator; the orchestrator rehydrates recent history server-side using conversationId and userId.

| Field | Type / values | Required | What it does | Example | |---|---|---:|---|---| | conversation.conversationId | string | no | Durable conversation identifier. Generated locally when omitted. | conv-homepage-001 | | conversation.title | string | no | Optional user-facing title sent to the orchestrator. | Homepage assistant | | conversation.memoryMaxTurns | nonnegative integer | no | Server-side recent-history window. Use 0 to disable rehydration. | 6 |

Orchestrator Config

orchestrator.baseUrl should point to the orchestrator root URL, not /v2/chat. The client appends /v2/chat internally.

| Field | Type / values | Required | What it does | Example | |---|---|---:|---|---| | orchestrator.baseUrl | URL string | yes | Base URL for the orchestrator. | https://ai.tagit.live | | orchestrator.useCaseId | string | yes | Runtime use case ID to execute. | uc-default-1lji40 | | orchestrator.apiKey | string | no | Optional API key sent as X-Api-Key. | import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY | | orchestrator.snapshotId | string | no | Pins the client to a specific orchestration snapshot. | snapshot_2026_04_14 | | orchestrator.timeoutMs | positive integer | no | Request timeout in milliseconds. | 30000 | | orchestrator.maxRetries | nonnegative integer | no | Number of retry attempts for transient failures. | 3 |

Collector Config

Collector is optional and can be disabled. When enabled, the client emits a TagIt conversation event after successful completion.

| Field | Type / values | Required when enabled | What it does | Example | |---|---|---:|---|---| | collector.enabled | boolean | yes | Turns collector emission on or off. | true | | collector.baseUrl | URL string | yes | Collector endpoint base URL. | https://collector.tagit.live | | collector.tagId | string | yes | Tag identifier used to route and classify collector events. | tagit-site-demo | | collector.acceptCookies | boolean | no | Whether the widget should request/set cookies when emitting collector events. | true | | collector.agentId | string | no | Optional collector agent identity. Defaults to the request use case id. | uc-default-1lji40 | | collector.eventSubContext | string | no | Optional sub-context identifier for the event surface. | website-homepage | | collector.sessionId | string | no | Optional collector session identifier. It is not the primary durable conversation id when conversation.conversationId exists. | session_abc123 | | collector.privacy.jurisdiction | string | no | Privacy jurisdiction metadata. | US-CA | | collector.privacy.purposesConsent.analytics | boolean | no | Consent flag for analytics collection. | true |

Legacy collector identity fields are still accepted for migration compatibility, but new integrations should put identity in the shared user block.

UI Config

| Field | Type / values | Default | What it does | Example | |---|---|---:|---|---| | ui.theme | 'light' \| 'dark' | undefined | Forces the UI theme used by the React package. | dark | | ui.streaming | boolean | true | Enables streaming response handling. | true | | ui.showToolCalls | boolean | true | Shows tool call activity in the UI layer. | true | | ui.maxMessageCharacters.user | positive integer | 2000 | Maximum user message length before truncation. | 2000 | | ui.maxMessageCharacters.assistant | positive integer | 3000 | Maximum assistant message length before truncation. | 3000 | | ui.maxHistoryMessages | positive integer | 50 | Maximum messages preserved before history trimming warnings. | 50 |

AIClient API

Constructor

const client = new AIClient(config, options);

| Field | Type | Required | What it does | Example | |---|---|---:|---|---| | config | ClientConfig | yes | Validated runtime configuration. | createDefaultConfig(...) | | options.transport | OrchestratorTransport | no | Custom transport implementation for testing or alternate fetch behavior. | new FetchOrchestratorTransport() |

Methods

| Method | Signature | What it does | Example | |---|---|---|---| | getState() | (): ConversationState | Returns the current conversation snapshot. | client.getState() | | on(listener) | (): () => void | Subscribes to client events and returns an unsubscribe function. | client.on(handleEvent) | | sendMessage() | (message, options?) => Promise<void> | Sends a user message and streams the orchestrator response. | await client.sendMessage('Hello') | | cancel() | (): void | Cancels the current in-flight request. | client.cancel() | | clearHistory() | (): void | Clears the local transcript. If conversation.conversationId is configured, the durable id is preserved. | client.clearHistory() | | trimHistoryBefore() | (messageId) => string \| null | Removes a message and everything after it. | client.trimHistoryBefore(id) |

Message Options

sendMessage() and retry() accept the same options bag.

| Field | Type / values | What it does | Example | |---|---|---|---| | tools | 'none' \| 'all' \| string[] | Limits which MCP tools are available for the request. | tools: 'none' | | useCaseMessage | string | Injects an additional use-case instruction as a system message. | useCaseMessage: 'Keep it short and direct.' | | userId | string | Overrides the resolved user id for this request. | userId: 'request-user' | | useCaseId | string | Overrides the configured use case for this request. | useCaseId: 'uc-other' | | snapshotId | string | Overrides the configured snapshot for this request. | snapshotId: 'snap-123' | | conversationId | string | Overrides the durable conversation id for this request. | conversationId: 'conv-other' | | conversationTitle | string | Overrides the conversation title for this request. | conversationTitle: 'Support chat' | | conversationMemoryMaxTurns | number | Overrides the server-side memory window for this request. | conversationMemoryMaxTurns: 0 |

await client.sendMessage('Hello', {
  tools: 'none',
  useCaseMessage: 'You are helping a new customer onboard.',
  conversationMemoryMaxTurns: 6,
});

Conversation State

getState() returns:

| Field | Type | What it means | Example | |---|---|---|---| | id | string | Current conversation identifier. | 1713100000000-x8q1abcde | | messages | Message[] | Ordered message transcript. | [{ role: 'user', ... }] | | isLoading | boolean | true while a request is in flight. | true | | isStreaming | boolean | true while streaming response data is active. | true | | error | string \| undefined | Safe user-facing error text. | Request timed out before completion. | | lastError | ClientErrorInfo \| undefined | Structured internal error details. | { code: 'TIMEOUT', ... } | | useCaseId | string | Use case currently bound to the conversation. | uc-default-1lji40 | | workflowId | string \| undefined | Latest workflow run id returned by a V2 workflow use case. | wf_123 | | workflowStatus | string \| undefined | Latest workflow status returned by the orchestrator. | completed | | checkpointPrompt | string \| undefined | Latest checkpoint prompt returned by a workflow use case. | Review before continuing? |

Checkpoint action UI is not included in the beta React widget. Consumers can inspect workflow metadata from state/events and add explicit continue/revise/cancel controls in a later integration.

Client Events

client.on() emits a typed event stream that you can use for debugging, analytics, or host UI updates.

| Event | What it means | Example payload | |---|---|---| | message_added | A message was appended to the transcript. | { type: 'message_added', message } | | message_updated | Existing message content changed, usually during streaming. | { type: 'message_updated', message } | | state_synced | Conversation state changed in a way the UI should re-read. | { type: 'state_synced' } | | first_token | First streamed token arrived for the assistant message. | { type: 'first_token', messageId } | | stream_delta | A partial assistant text chunk was received. | { type: 'stream_delta', messageId, text } | | request_retried | The client retried a failed request. | { type: 'request_retried', attempt, reason } | | request_canceled | The current request was canceled. | { type: 'request_canceled' } | | request_failed | The request failed and surfaced a structured error. | { type: 'request_failed', error } | | streaming_completed_degraded | Streaming finished, but only in degraded mode. | { type: 'streaming_completed_degraded', reason } | | orchestrator_request | The client is about to call the orchestrator. | { type: 'orchestrator_request', endpoint, request } | | collector_event_request | The client is about to send a collector event. | { type: 'collector_event_request', endpoint, payload } | | collector_event_sent | Collector event was sent successfully. | { type: 'collector_event_sent', endpoint, tagId } | | collector_event_failed | Collector event failed to send. | { type: 'collector_event_failed', endpoint, tagId, error } | | collector_event_skipped | Collector payload exceeded the size limit and was skipped. | { type: 'collector_event_skipped', reason, byteSize } | | history_size_warning | Transcript exceeded the configured message limit. | { type: 'history_size_warning', messageCount, limit } | | tool_call_started | The orchestrator started a tool call. | { type: 'tool_call_started', toolCall } | | tool_call_completed | The orchestrator completed a tool call. | { type: 'tool_call_completed', toolCall } | | error | A structured client error was emitted. | { type: 'error', error } | | streaming_started | Streaming response handling began. | { type: 'streaming_started' } | | streaming_completed | Streaming response handling completed successfully. | { type: 'streaming_completed' } |

Orchestrator Request Shape

The core client posts a canonical request to /v2/chat.

| Field | Type / values | Required | What it does | Example | |---|---|---:|---|---| | use_case_id | string | yes | Runtime use case identifier. | uc-default-1lji40 | | stream | boolean | no | Requests SSE when true. | true | | messages | array | yes | Current user message, plus optional useCaseMessage system instruction. Server-side memory comes from conversation_id. | [{ role: 'user', content: 'Hello' }] | | tools | 'none' \| 'all' \| string[] | no | Limits which tools the orchestrator may use. | ['search_docs'] | | snapshot_id | string | no | Pins the request to a published orchestration snapshot. | snapshot_2026_04_14 | | runtime_version | 'v2' | yes | Runtime contract marker sent by the client. | v2 | | user_id | string | yes | User id for ownership and conversation memory. | visitor_abc123 | | conversation_id | string | yes | Durable conversation id. | conv-homepage-001 | | session_id | string | no | Backward-compatible mirror of conversation_id during migration. | conv-homepage-001 | | conversation_title | string | no | Optional conversation title. | Homepage assistant | | conversation_memory_max_turns | number | no | Server-side memory window. | 6 |

Example:

{
  use_case_id: 'uc-default-1lji40',
  runtime_version: 'v2',
  user_id: 'visitor_abc123',
  conversation_id: 'conv-homepage-001',
  session_id: 'conv-homepage-001',
  conversation_memory_max_turns: 6,
  stream: true,
  messages: [
    { role: 'user', content: 'How do I get started?' },
  ],
  tools: 'none',
}

Collector Contract

When collector emission is enabled, the client emits a conversation envelope after a successful turn.

| Field | Type | What it means | Example | |---|---|---|---| | tagId | string | Tag used to identify the emitting surface. | tagit-site-demo | | tagType | string | Fixed TagIt collector tag type. | web-sdk-nativeId | | acceptCookies | boolean | Whether cookies may be used for the collector event. | false | | remember | boolean | Signals that the event should be retained for memory processing. | true | | eventType | string | High-level event class. | conversation | | eventSubType | string | Specific collector subtype. | chat_turn | | eventSubContext | string | Context or sub-context label for the event. | website-homepage | | eventGuid | string | Unique event identifier. | 1713100000000-x8q1abcde | | sessionId | string | Optional session identifier. | session_abc123 | | entityId | string | Entity identity for the event subject. | user_123 | | entityidType | string | Entity type metadata. | internal_user_id | | entityidAlgo | string | Entity ID algorithm metadata. | native | | entityidOwner | string | Entity owner metadata. | tagit-ai-client | | privacy | object | Optional privacy metadata. | { jurisdiction: 'US-CA' } | | content.contentType | string | Content envelope type. | conversation | | content.contentData.userId | string | User identity used for the conversation event. | user_123 | | content.contentData.agentId | string | Agent identity used for the conversation event. | uc-default-1lji40 | | content.contentData.conversationId | string | Conversation identifier. | 1713100000000-x8q1abcde | | content.contentData.userMessageId | string | User message ID. | 1713100000001-y9z2bcdef | | content.contentData.agentMessageId | string | null | Assistant message ID when present. | 1713100000002-z1a3cdefg | | content.contentData.userMessage | string | Captured user message content. | How do I get started? | | content.contentData.agentMessage | string | null | Captured assistant message content. | Open the onboarding checklist... |

Transport

If you need to replace fetch, implement OrchestratorTransport and pass it into the AIClient constructor.

import type { OrchestratorTransport } from '@tagit/ai-client-core';

const transport: OrchestratorTransport = {
  async send(request, context) {
    return fetch(`${context.baseUrl}${context.endpointPath}`, {
      method: 'POST',
      headers: context.headers,
      body: JSON.stringify(request),
      signal: context.signal,
    });
  },
};

Related Package

If you want the full embeddable React widget, install:

• @tagit/ai-client-react

That package consumes this core client and exposes AIClientProvider, hooks, and the built-in ChatWidget.

Docs

• React package integration guide
• Root README