@tagit/ai-client-core 0.3.0-beta.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +285 -16
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,13 +2,42 @@
2
2
 
3
3
  Headless TypeScript client core for the tagIt AI orchestrator.
4
4
 
5
- ## What This Package Does
5
+ 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.
6
6
 
7
- - builds the orchestrator request payload
8
- - manages chat state and history
9
- - handles streaming, retries, and cancellation
10
- - emits collector events when enabled
11
- - exposes the core config and types used by the React package
7
+ This README is the source of truth for the core package.
8
+
9
+ ## What Is tagIt?
10
+
11
+ 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.
12
+
13
+ ## What Is the AI Orchestrator?
14
+
15
+ 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.
16
+
17
+ ## Why This Package Exists
18
+
19
+ `@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.
20
+
21
+ MCP servers are optional, but they can extend the orchestrator with tools and external capabilities.
22
+
23
+ To learn more about tagIt and the orchestrator setup, visit [tagit.live](https://tagit.live).
24
+
25
+ ## What This Package Provides
26
+
27
+ - `AIClient` for orchestrator communication and conversation state
28
+ - `createDefaultConfig`, `validateConfig`, and the config schema
29
+ - core types for orchestrator requests, stream chunks, messages, events, and collector payloads
30
+ - optional collector emission for TagIt conversation events
31
+
32
+ ## Public Imports
33
+
34
+ Supported public imports:
35
+
36
+ - `@tagit/ai-client-core`
37
+ - `@tagit/ai-client-core/config`
38
+ - `@tagit/ai-client-core/types`
39
+
40
+ Do not import from `dist/*` or from internal source paths.
12
41
 
13
42
  ## Install
14
43
 
@@ -22,7 +51,10 @@ npm install @tagit/ai-client-core
22
51
  import { AIClient, createDefaultConfig } from '@tagit/ai-client-core';
23
52
 
24
53
  const client = new AIClient(
25
- createDefaultConfig('your-use-case-id', 'https://your-orchestrator.example.com', {
54
+ createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
55
+ orchestrator: {
56
+ apiKey: import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY,
57
+ },
26
58
  collector: {
27
59
  enabled: false,
28
60
  },
@@ -30,18 +62,255 @@ const client = new AIClient(
30
62
  );
31
63
  ```
32
64
 
33
- ## Configuration
65
+ ## Core Concepts
66
+
67
+ ### `AIClient`
68
+
69
+ `AIClient` is the stateful engine:
70
+
71
+ - builds the `/v1/chat` request
72
+ - manages the conversation transcript
73
+ - streams assistant output
74
+ - retries transient failures
75
+ - cancels in-flight requests
76
+ - emits collector events when enabled
77
+
78
+ ### `ClientConfig`
79
+
80
+ `ClientConfig` is the validated runtime configuration object that feeds the client.
81
+
82
+ ### `OrchestratorRequest`
83
+
84
+ `OrchestratorRequest` is the payload posted to the orchestrator `/v1/chat` endpoint.
85
+
86
+ ### `OrchestratorChunk`
87
+
88
+ `OrchestratorChunk` is the canonical SSE message shape expected from the orchestrator.
89
+
90
+ ## Configuration Dictionary
91
+
92
+ The core client is driven by a validated `ClientConfig`. If a field is omitted, the client uses its default.
93
+
94
+ ### `createDefaultConfig(useCaseId, orchestratorUrl, options?)`
95
+
96
+ This helper builds a safe starting config.
97
+
98
+ ```ts
99
+ const config = createDefaultConfig('uc-default-1lji40', 'https://ai.tagit.live', {
100
+ collector: {
101
+ enabled: false,
102
+ },
103
+ });
104
+ ```
105
+
106
+ | Field | Type / values | Default | What it does | Example |
107
+ |---|---|---:|---|---|
108
+ | `useCaseId` | `string` | required | Runtime use case identifier used by the orchestrator. | `'uc-default-1lji40'` |
109
+ | `orchestratorUrl` | URL string | required | Base URL for the orchestrator. Do not include `/v1/chat`. | `'https://ai.tagit.live'` |
110
+ | `options.orchestrator` | partial orchestrator config | `undefined` | Overrides specific orchestrator fields. | `{ apiKey: '...' }` |
111
+ | `options.collector` | partial collector config | `undefined` | Enables or customizes collector emission. | `{ enabled: false }` |
112
+ | `options.ui` | partial UI config | `undefined` | Overrides client UI/runtime behavior. | `{ streaming: true }` |
113
+
114
+ ### Orchestrator Config
115
+
116
+ `orchestrator.baseUrl` should point to the orchestrator root URL, not `/v1/chat`. The client appends `/v1/chat` internally.
117
+
118
+ | Field | Type / values | Required | What it does | Example |
119
+ |---|---|---:|---|---|
120
+ | `orchestrator.baseUrl` | URL string | yes | Base URL for the orchestrator. | `https://ai.tagit.live` |
121
+ | `orchestrator.useCaseId` | string | yes | Runtime use case ID to execute. | `uc-default-1lji40` |
122
+ | `orchestrator.apiKey` | string | no | Optional API key sent as `X-Api-Key`. | `import.meta.env.VITE_TAGIT_AI_ORCHESTRATOR_API_KEY` |
123
+ | `orchestrator.snapshotId` | string | no | Pins the client to a specific orchestration snapshot. | `snapshot_2026_04_14` |
124
+ | `orchestrator.timeoutMs` | positive integer | no | Request timeout in milliseconds. | `30000` |
125
+ | `orchestrator.maxRetries` | nonnegative integer | no | Number of retry attempts for transient failures. | `3` |
126
+
127
+ ### Collector Config
128
+
129
+ Collector is optional and can be disabled. When enabled, the client emits a TagIt conversation event after successful completion.
130
+
131
+ | Field | Type / values | Required when enabled | What it does | Example |
132
+ |---|---|---:|---|---|
133
+ | `collector.enabled` | `boolean` | yes | Turns collector emission on or off. | `true` |
134
+ | `collector.baseUrl` | URL string | yes | Collector endpoint base URL. | `https://collector.tagit.live` |
135
+ | `collector.tagId` | string | yes | Tag identifier used to route and classify collector events. | `tagit-site-demo` |
136
+ | `collector.acceptCookies` | `boolean` | no | Whether the widget should request/set cookies when emitting collector events. | `true` |
137
+ | `collector.userId` | string | no | Optional user identity for collector payloads. | `user_123` |
138
+ | `collector.agentId` | string | no | Optional agent identity for collector payloads. | `uc-default-1lji40` |
139
+ | `collector.entityId` | string | no | Optional entity identifier for the tracked subject. | `acct_456` |
140
+ | `collector.entityidType` | string | no | Entity type metadata. | `account` |
141
+ | `collector.entityidAlgo` | string | no | Entity ID algorithm metadata. | `sha256` |
142
+ | `collector.entityidOwner` | string | no | Entity owner metadata. | `tagit` |
143
+ | `collector.spaceId` | string | no | Optional space/context identifier. | `website-homepage` |
144
+ | `collector.sessionId` | string | no | Optional session identifier. | `session_abc123` |
145
+ | `collector.privacy.jurisdiction` | string | no | Privacy jurisdiction metadata. | `US-CA` |
146
+ | `collector.privacy.purposesConsent.analytics` | `boolean` | no | Consent flag for analytics collection. | `true` |
147
+
148
+ ### UI Config
149
+
150
+ | Field | Type / values | Default | What it does | Example |
151
+ |---|---|---:|---|---|
152
+ | `ui.theme` | `'light' \| 'dark'` | `undefined` | Forces the UI theme used by the React package. | `dark` |
153
+ | `ui.streaming` | `boolean` | `true` | Enables streaming response handling. | `true` |
154
+ | `ui.showToolCalls` | `boolean` | `true` | Shows tool call activity in the UI layer. | `true` |
155
+ | `ui.maxMessageCharacters.user` | positive integer | `2000` | Maximum user message length before truncation. | `2000` |
156
+ | `ui.maxMessageCharacters.assistant` | positive integer | `3000` | Maximum assistant message length before truncation. | `3000` |
157
+ | `ui.maxHistoryMessages` | positive integer | `50` | Maximum messages preserved before history trimming warnings. | `50` |
158
+
159
+ ## AIClient API
160
+
161
+ ### Constructor
162
+
163
+ ```ts
164
+ const client = new AIClient(config, options);
165
+ ```
166
+
167
+ | Field | Type | Required | What it does | Example |
168
+ |---|---|---:|---|---|
169
+ | `config` | `ClientConfig` | yes | Validated runtime configuration. | `createDefaultConfig(...)` |
170
+ | `options.transport` | `OrchestratorTransport` | no | Custom transport implementation for testing or alternate fetch behavior. | `new FetchOrchestratorTransport()` |
171
+
172
+ ### Methods
173
+
174
+ | Method | Signature | What it does | Example |
175
+ |---|---|---|---|
176
+ | `getState()` | `(): ConversationState` | Returns the current conversation snapshot. | `client.getState()` |
177
+ | `on(listener)` | `(): () => void` | Subscribes to client events and returns an unsubscribe function. | `client.on(handleEvent)` |
178
+ | `sendMessage()` | `(message, options?) => Promise<void>` | Sends a user message and streams the orchestrator response. | `await client.sendMessage('Hello')` |
179
+ | `cancel()` | `(): void` | Cancels the current in-flight request. | `client.cancel()` |
180
+ | `clearHistory()` | `(): void` | Clears the transcript and resets the conversation ID. | `client.clearHistory()` |
181
+ | `trimHistoryBefore()` | `(messageId) => string \| null` | Removes a message and everything after it. | `client.trimHistoryBefore(id)` |
182
+
183
+ ## Message Options
184
+
185
+ `sendMessage()` and `retry()` accept the same options bag.
186
+
187
+ | Field | Type / values | What it does | Example |
188
+ |---|---|---|---|
189
+ | `tools` | `'none' \| 'all' \| string[]` | Limits which MCP tools are available for the request. | `tools: 'none'` |
190
+ | `useCaseMessage` | `string` | Injects an additional use-case instruction as a system message. | `useCaseMessage: 'Keep it short and direct.'` |
191
+
192
+ ```ts
193
+ await client.sendMessage('Hello', {
194
+ tools: 'none',
195
+ useCaseMessage: 'You are helping a new customer onboard.',
196
+ });
197
+ ```
34
198
 
35
- The minimum runtime configuration is:
199
+ ## Conversation State
36
200
 
37
- - `useCaseId` - the tagIt use case to execute
38
- - `orchestrator.baseUrl` - the orchestrator base URL without `/v1/chat`; the client appends `/v1/chat` internally
201
+ `getState()` returns:
39
202
 
40
- Collector settings are optional unless you want telemetry:
203
+ | Field | Type | What it means | Example |
204
+ |---|---|---|---|
205
+ | `id` | `string` | Current conversation identifier. | `1713100000000-x8q1abcde` |
206
+ | `messages` | `Message[]` | Ordered message transcript. | `[{ role: 'user', ... }]` |
207
+ | `isLoading` | `boolean` | `true` while a request is in flight. | `true` |
208
+ | `isStreaming` | `boolean` | `true` while streaming response data is active. | `true` |
209
+ | `error` | `string \| undefined` | Safe user-facing error text. | `Request timed out before completion.` |
210
+ | `lastError` | `ClientErrorInfo \| undefined` | Structured internal error details. | `{ code: 'TIMEOUT', ... }` |
211
+ | `useCaseId` | `string` | Use case currently bound to the conversation. | `uc-default-1lji40` |
41
212
 
42
- - `collector.baseUrl`
43
- - `collector.tagId`
44
- - `collector.enabled`
213
+ ## Client Events
214
+
215
+ `client.on()` emits a typed event stream that you can use for debugging, analytics, or host UI updates.
216
+
217
+ | Event | What it means | Example payload |
218
+ |---|---|---|
219
+ | `message_added` | A message was appended to the transcript. | `{ type: 'message_added', message }` |
220
+ | `message_updated` | Existing message content changed, usually during streaming. | `{ type: 'message_updated', message }` |
221
+ | `state_synced` | Conversation state changed in a way the UI should re-read. | `{ type: 'state_synced' }` |
222
+ | `first_token` | First streamed token arrived for the assistant message. | `{ type: 'first_token', messageId }` |
223
+ | `stream_delta` | A partial assistant text chunk was received. | `{ type: 'stream_delta', messageId, text }` |
224
+ | `request_retried` | The client retried a failed request. | `{ type: 'request_retried', attempt, reason }` |
225
+ | `request_canceled` | The current request was canceled. | `{ type: 'request_canceled' }` |
226
+ | `request_failed` | The request failed and surfaced a structured error. | `{ type: 'request_failed', error }` |
227
+ | `streaming_completed_degraded` | Streaming finished, but only in degraded mode. | `{ type: 'streaming_completed_degraded', reason }` |
228
+ | `orchestrator_request` | The client is about to call the orchestrator. | `{ type: 'orchestrator_request', endpoint, request }` |
229
+ | `collector_event_request` | The client is about to send a collector event. | `{ type: 'collector_event_request', endpoint, payload }` |
230
+ | `collector_event_sent` | Collector event was sent successfully. | `{ type: 'collector_event_sent', endpoint, tagId }` |
231
+ | `collector_event_failed` | Collector event failed to send. | `{ type: 'collector_event_failed', endpoint, tagId, error }` |
232
+ | `collector_event_skipped` | Collector payload exceeded the size limit and was skipped. | `{ type: 'collector_event_skipped', reason, byteSize }` |
233
+ | `history_size_warning` | Transcript exceeded the configured message limit. | `{ type: 'history_size_warning', messageCount, limit }` |
234
+ | `tool_call_started` | The orchestrator started a tool call. | `{ type: 'tool_call_started', toolCall }` |
235
+ | `tool_call_completed` | The orchestrator completed a tool call. | `{ type: 'tool_call_completed', toolCall }` |
236
+ | `error` | A structured client error was emitted. | `{ type: 'error', error }` |
237
+ | `streaming_started` | Streaming response handling began. | `{ type: 'streaming_started' }` |
238
+ | `streaming_completed` | Streaming response handling completed successfully. | `{ type: 'streaming_completed' }` |
239
+
240
+ ## Orchestrator Request Shape
241
+
242
+ The core client posts a canonical request to `/v1/chat`.
243
+
244
+ | Field | Type / values | Required | What it does | Example |
245
+ |---|---|---:|---|---|
246
+ | `use_case_id` | string | yes | Runtime use case identifier. | `uc-default-1lji40` |
247
+ | `stream` | `boolean` | no | Requests SSE when `true`. | `true` |
248
+ | `messages` | array | yes | Message history sent to the orchestrator. | `[{ role: 'user', content: 'Hello' }]` |
249
+ | `tools` | `'none' \| 'all' \| string[]` | no | Limits which tools the orchestrator may use. | `['search_docs']` |
250
+ | `snapshot_id` | string | no | Pins the request to a published orchestration snapshot. | `snapshot_2026_04_14` |
251
+
252
+ Example:
253
+
254
+ ```ts
255
+ {
256
+ use_case_id: 'uc-default-1lji40',
257
+ stream: true,
258
+ messages: [
259
+ { role: 'system', content: 'Keep it short and direct.' },
260
+ { role: 'user', content: 'How do I get started?' },
261
+ ],
262
+ tools: 'none',
263
+ }
264
+ ```
265
+
266
+ ## Collector Contract
267
+
268
+ When collector emission is enabled, the client emits a conversation envelope after a successful turn.
269
+
270
+ | Field | Type | What it means | Example |
271
+ |---|---|---|---|
272
+ | `tagId` | string | Tag used to identify the emitting surface. | `tagit-site-demo` |
273
+ | `tagType` | string | Fixed TagIt collector tag type. | `web-sdk-nativeId` |
274
+ | `acceptCookies` | boolean | Whether cookies may be used for the collector event. | `false` |
275
+ | `remember` | boolean | Signals that the event should be retained for memory processing. | `true` |
276
+ | `eventType` | string | High-level event class. | `conversation` |
277
+ | `eventSubType` | string | Specific collector subtype. | `chat_turn` |
278
+ | `eventSubContext` | string | Context label for the event. | `uc-default-1lji40` |
279
+ | `eventGuid` | string | Unique event identifier. | `1713100000000-x8q1abcde` |
280
+ | `sessionId` | string | Optional session identifier. | `session_abc123` |
281
+ | `entityId` | string | Entity identity for the event subject. | `user_123` |
282
+ | `entityidType` | string | Entity type metadata. | `internal_user_id` |
283
+ | `entityidAlgo` | string | Entity ID algorithm metadata. | `native` |
284
+ | `entityidOwner` | string | Entity owner metadata. | `tagit-ai-client` |
285
+ | `privacy` | object | Optional privacy metadata. | `{ jurisdiction: 'US-CA' }` |
286
+ | `content.contentType` | string | Content envelope type. | `conversation` |
287
+ | `content.contentData.userId` | string | User identity used for the conversation event. | `user_123` |
288
+ | `content.contentData.agentId` | string | Agent identity used for the conversation event. | `uc-default-1lji40` |
289
+ | `content.contentData.conversationId` | string | Conversation identifier. | `1713100000000-x8q1abcde` |
290
+ | `content.contentData.userMessageId` | string | User message ID. | `1713100000001-y9z2bcdef` |
291
+ | `content.contentData.agentMessageId` | string \| null | Assistant message ID when present. | `1713100000002-z1a3cdefg` |
292
+ | `content.contentData.userMessage` | string | Captured user message content. | `How do I get started?` |
293
+ | `content.contentData.agentMessage` | string \| null | Captured assistant message content. | `Open the onboarding checklist...` |
294
+ | `content.contentData.spaceId` | string | Optional space identifier. | `website-homepage` |
295
+
296
+ ## Transport
297
+
298
+ If you need to replace `fetch`, implement `OrchestratorTransport` and pass it into the `AIClient` constructor.
299
+
300
+ ```ts
301
+ import type { OrchestratorTransport } from '@tagit/ai-client-core';
302
+
303
+ const transport: OrchestratorTransport = {
304
+ async send(request, context) {
305
+ return fetch(`${context.baseUrl}/v1/chat`, {
306
+ method: 'POST',
307
+ headers: context.headers,
308
+ body: JSON.stringify(request),
309
+ signal: context.signal,
310
+ });
311
+ },
312
+ };
313
+ ```
45
314
 
46
315
  ## Related Package
47
316
 
@@ -49,7 +318,7 @@ If you want the full embeddable React widget, install:
49
318
 
50
319
  - `@tagit/ai-client-react`
51
320
 
52
- That package consumes this core client and exposes `AIClientProvider`, hooks, and the self-contained `ChatWidget`.
321
+ That package consumes this core client and exposes `AIClientProvider`, hooks, and the built-in `ChatWidget`.
53
322
 
54
323
  ## Docs
55
324
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tagit/ai-client-core",
3
- "version": "0.3.0-beta.1",
3
+ "version": "0.4.0",
4
4
  "description": "Headless TypeScript client core for TagIt AI orchestrator",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",