qati-sdk 1.0.5 → 1.1.0

package/README.md

@@ -12,6 +12,7 @@ The main feature groups on the client are:
 - `client.trustState` — read risk and trust scores for users or other entities.
 - `client.advisory` — list persisted advisories for the tenant (with filters and pagination).
 - `client.explain` — fetch a composite explain / attribution payload for a single entity (by entity key).
+- `client.mccEvaluation` — list, retrieve, and manually trigger MCC evaluation traces (keyset pagination).
 - `client.events` — send telemetry events to the ingestion pipeline.
 - `client.webhooks` — manage webhook endpoints for a tenant (register, list, update, delete, trigger test delivery).
 - `client.quotas` — read and configure numeric caps (entities, monthly events, rate) for a tenant.
@@ -168,6 +169,134 @@ try {
 }
 ```
 
+## Query API: MCC evaluation traces
+
+MCC (Multi-Candidate Commit) evaluation traces record how the scoring engine evaluated candidate actions for an entity — branch scores, predicted risk tiers, constraint failures, and the selected commit. Use `client.mccEvaluation` to query persisted traces or run a manual evaluation against an entity's latest trust state via the Query API.
+
+Endpoints:
+
+- `GET /v1/mcc/evaluations` — list with optional filters and **keyset pagination**
+- `GET /v1/mcc/evaluations/{evaluation_id}` — fetch one trace by id
+- `POST /v1/mcc/evaluate` — run MCC-Lite against the entity's latest trust state and persist the trace
+
+Pagination uses a cursor, not an offset. Pass `after_id` from the previous page's `next_cursor`; when `next_cursor` is `null`, you have reached the last page.
+
+### List evaluations for an entity
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const page = await client.mccEvaluation.list({
+    entityKey: 'SESSION:conv-abc',
+    limit: 50,
+  });
+  console.log(page.total_count, page.evaluations.length);
+  for (const ev of page.evaluations) {
+    console.log(ev.evaluation_id, ev.commit_type, ev.degraded);
+  }
+} finally {
+  await client.close();
+}
+```
+
+Optional filters: `entity_key`, `since`, `until` (inclusive bounds on `created_at` as `Date` or ISO-8601 string), and `limit` (server caps at 100).
+
+### Paginate through all evaluations
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  let page = await client.mccEvaluation.list({
+    entity_key: 'USER:user-123',
+    limit: 50,
+  });
+  const allIds: string[] = [];
+
+  while (true) {
+    for (const ev of page.evaluations) {
+      allIds.push(ev.evaluation_id);
+    }
+    if (!page.next_cursor) break;
+    page = await client.mccEvaluation.list({
+      entity_key: 'USER:user-123',
+      limit: 50,
+      after_id: page.next_cursor,
+    });
+  }
+
+  console.log(`Fetched ${allIds.length} evaluation ids`);
+} finally {
+  await client.close();
+}
+```
+
+### Get one evaluation by id
+
+Returns the full trace including `evaluated_branches`, `selected_branch`, residuals, and version metadata. A missing id raises `QatiNotFoundError`.
+
+```ts
+import { Session, QatiNotFoundError } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const evaluationId = '550e8400-e29b-41d4-a716-446655440000';
+  try {
+    const trace = await client.mccEvaluation.get(evaluationId);
+    const branch = trace.selected_branch ?? trace.evaluated_branches[0];
+    if (branch) {
+      console.log(
+        trace.entity_key,
+        branch.action_type,
+        branch.predicted_risk_tier,
+        branch.branch_score,
+      );
+    }
+  } catch (e) {
+    if (e instanceof QatiNotFoundError) {
+      console.log('Evaluation not found');
+    } else {
+      throw e;
+    }
+  }
+} finally {
+  await client.close();
+}
+```
+
+### Trigger a manual evaluation
+
+Runs MCC-Lite against the entity's current trust state, persists the trace, and returns the full `MCCEvaluation`. Requires an existing trust state for the entity; otherwise raises `QatiNotFoundError`.
+
+```ts
+import { Session, QatiNotFoundError } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  try {
+    const trace = await client.mccEvaluation.evaluate('USER:alice');
+    console.log(trace.evaluation_id, trace.commit_type, trace.degraded);
+  } catch (e) {
+    if (e instanceof QatiNotFoundError) {
+      console.log('Trust state not found for entity');
+    } else {
+      throw e;
+    }
+  }
+} finally {
+  await client.close();
+}
+```
+
+Types `MCCEvaluation`, `MCCEvaluationListResponse`, `MCCBranchEvaluation`, and `ListMccEvaluationsOptions` are exported from `qati-sdk`.
+
 ## Webhooks
 
 `client.webhooks` manages webhook endpoints for a specific tenant. All methods require `tenantId` as their first argument — resolve it once with `client.tenant.verifyCredentials()` and reuse the value.
@@ -279,7 +408,11 @@ const client = session.createClient();
 try {
   const creds = await client.tenant.verifyCredentials();
   const quota = await client.quotas.get(creds.tenant_id);
-  console.log(quota.max_tracked_entities, quota.max_monthly_events, quota.max_events_per_second);
+  console.log(
+    quota.max_tracked_entities,
+    quota.max_monthly_events,
+    quota.max_events_per_second,
+  );
 } finally {
   await client.close();
 }
@@ -367,15 +500,65 @@ const v1Event = (signalPayload: object, extra: object = {}) => {
 };
 ```
 
+### Canonical scalar hashing (`stableHash`)
+
+Several payload fields store a hash of sensitive text (`action_hash`, `device_fingerprint_hash`, `query_hash`, `retrieval_hash`, `retrieved_context_hash`, `user_comment_hash`). Use the exported **`stableHash`** helper so your client matches the server canonical format:
+
+1. Unicode **NFC** normalization
+2. Strip outer whitespace, **lowercase**
+3. SHA-256 over UTF-8 bytes
+4. Prefix with `sha256:` (for example `sha256:2c26b46b…`)
+
+Empty, whitespace-only, or null/undefined input returns `undefined` — omit the field from the payload rather than hashing empty strings.
+
+```ts
+import { stableHash } from 'qati-sdk';
+
+const action = 'SELECT id FROM users LIMIT 10';
+const actionHash = stableHash(action); // sha256:…
+```
+
+On the Python SDK, use the same algorithm via `qati_lib.utils.crypto.stable_hash` (the server reference implementation).
+
 ### Available signal types
 
+All **17** v1 signal types have a matching `create*Event` builder exported from `qati-sdk`. Each builder validates `signal_payload` with **Zod** and returns a `RawEventRequest`. Required fields must be supplied; optional fields may be omitted (defaults apply where defined).
+
+| Signal type          | Builder                       | Notes                                       |
+| -------------------- | ----------------------------- | ------------------------------------------- |
+| `TRANSACTION`        | `createTransactionEvent`      | Financial / data-access transactions        |
+| `AUTH`               | `createAuthEvent`             | Login and MFA outcomes                      |
+| `BEHAVIOR`           | `createBehaviorEvent`         | Requires `behavior_type`, `deviation_score` |
+| `ANOMALY_FLAG`       | `createAnomalyFlagEvent`      | Requires `anomaly_type`, `severity`         |
+| `NETWORK_EVENT`      | `createNetworkEvent`          | IP/ASN reputation and threat scores         |
+| `MODEL_OUTPUT`       | `createModelOutputEvent`      | LLM output quality metrics                  |
+| `SYSTEM_TELEMETRY`   | `createSystemTelemetryEvent`  | Infra and OT telemetry                      |
+| `API_CALL`           | `createApiCallEvent`          | HTTP API invocation audit                   |
+| `WORKFLOW_ACTION`    | `createWorkflowActionEvent`   | Multi-step workflow governance              |
+| `TOOL_CALL`          | `createToolCallEvent`         | Post-execution tool invocation              |
+| `TOOL_CALL_PROPOSED` | `createToolCallProposedEvent` | **Pre-execution** tool proposal gate        |
+| `SESSION`            | `createSessionEvent`          | Conversation/session lifecycle              |
+| `PROMPT_INPUT`       | `createPromptInputEvent`      | User prompt risk signals                    |
+| `RAG_RETRIEVAL`      | `createRagRetrievalEvent`     | Retrieval quality and trust                 |
+| `CONTEXT_INTEGRITY`  | `createContextIntegrityEvent` | Prompt/context conflict detection           |
+| `POLICY_EVENT`       | `createPolicyEvent`           | Policy check outcomes                       |
+| `USER_FEEDBACK`      | `createUserFeedbackEvent`     | End-user feedback on responses              |
+
 #### Transaction
 
 ```ts
 import { createTransactionEvent, type TransactionSignalEvent } from 'qati-sdk';
 
 const raw = createTransactionEvent(
-  v1Event({ amount: 99.99 }) as TransactionSignalEvent,
+  v1Event({
+    amount: 99.99,
+    currency: 'USD',
+    channel: 'ECOM',
+    bulk_export: false,
+    contains_phi: false,
+    safety_critical: false,
+    authorized: true,
+  }) as TransactionSignalEvent,
 );
 ```
 
@@ -386,9 +569,13 @@ import { createAuthEvent, type AuthSignalEvent } from 'qati-sdk';
 
 const raw = createAuthEvent(
   v1Event({
-    result: 'success',
-    auth_method: 'password',
+    result: 'SUCCESS',
+    auth_method: 'MFA_TOTP',
     mfa_used: true,
+    mfa_bypassed: false,
+    failed_attempts: 0,
+    unusual_location: false,
+    after_hours_login: false,
   }) as AuthSignalEvent,
 );
 ```
@@ -401,7 +588,14 @@ import { createModelOutputEvent, type ModelOutputSignalEvent } from 'qati-sdk';
 const raw = createModelOutputEvent(
   v1Event({
     citation_rate: 0.95,
+    expected_citation_rate: 0.9,
+    policy_violations: 0,
+    tool_call_inconsistency: 0.02,
     eval_window_n: 1000,
+    hallucination_risk_score: 0.05,
+    grounding_score: 0.88,
+    contains_unsupported_claims: false,
+    finish_reason: 'STOP',
   }) as ModelOutputSignalEvent,
 );
 ```
@@ -419,31 +613,55 @@ const raw = createSystemTelemetryEvent(
     metric_name: 'p99_latency_ms',
     value: 120.0,
     baseline: 80.0,
+    window_seconds: 60,
+    error_rate: 0.01,
+    firmware_hash_changed: false,
+    expected_hash_match: true,
+    sensor_deviation_score: 0.1,
   }) as SystemTelemetrySignalEvent,
 );
 ```
 
 #### Anomaly flag
 
-`severity` must be between 0 and 1.
+`severity` and `anomaly_type` are required. Optional device and volume fields support agent/session abuse patterns.
 
 ```ts
 import { createAnomalyFlagEvent, type AnomalyFlagSignalEvent } from 'qati-sdk';
+import { stableHash } from 'qati-sdk';
 
 const raw = createAnomalyFlagEvent(
-  v1Event({ severity: 0.85 }) as AnomalyFlagSignalEvent,
+  v1Event({
+    severity: 0.85,
+    anomaly_type: 'HIGH_VOLUME_SESSION',
+    metric_name: 'requests_per_minute',
+    metric_value: 42,
+    threshold: 10,
+    window_seconds: 60,
+    device_trust_state: 'UNVERIFIED',
+    device_fingerprint_hash: stableHash('device-fingerprint-payload'),
+    request_count: 42,
+    baseline_request_count: 10,
+    volume_ratio: 4.2,
+  }) as AnomalyFlagSignalEvent,
 );
 ```
 
 #### Behavior
 
-`deviation_score` must be between 0 and 1.
-
 ```ts
 import { createBehaviorEvent, type BehaviorSignalEvent } from 'qati-sdk';
 
 const raw = createBehaviorEvent(
-  v1Event({ deviation_score: 0.4 }) as BehaviorSignalEvent,
+  v1Event({
+    behavior_type: 'chat_cadence',
+    deviation_score: 0.72,
+    current_value: 18,
+    baseline_value: 5,
+    unit: 'prompts_per_minute',
+    baseline_window_seconds: 3600,
+    current_window_seconds: 60,
+  }) as BehaviorSignalEvent,
 );
 ```
 
@@ -455,12 +673,271 @@ import { createNetworkEvent, type NetworkSignalEvent } from 'qati-sdk';
 const raw = createNetworkEvent(
   v1Event({
     ip: '198.51.100.10',
+    asn: 24940,
+    country: 'US',
     reputation_score: 0.2,
     threat_score: 0.7,
+    is_datacenter: true,
+    is_untrusted_segment: false,
+    asn_reputation: 0.15,
   }) as NetworkSignalEvent,
 );
 ```
 
+#### Tool call (executed)
+
+```ts
+import { createToolCallEvent, type ToolCallSignalEvent } from 'qati-sdk';
+
+const raw = createToolCallEvent(
+  v1Event({
+    tool_name: 'search_docs',
+    tool_category: 'RETRIEVAL',
+    action: 'query',
+    authorized: true,
+    safety_critical: false,
+    external_side_effect: false,
+    tool_call_success: true,
+    latency_ms: 120,
+    argument_risk_score: 0.1,
+    records_accessed: 3,
+    contains_sensitive_data: false,
+    contains_phi: false,
+    sensitive_data_involved: false,
+    sensitive_domain: false,
+  }) as ToolCallSignalEvent,
+);
+```
+
+#### Tool call proposed (pre-execution)
+
+Use **`TOOL_CALL_PROPOSED`** before a tool runs to record governance metadata. **`action_hash`** is required when the action text is sensitive; compute it with `stableHash(action)`.
+
+```ts
+import {
+  createToolCallProposedEvent,
+  stableHash,
+  type ToolCallProposedSignalEvent,
+} from 'qati-sdk';
+
+const action = 'SELECT id, email FROM users LIMIT 10';
+
+const raw = createToolCallProposedEvent(
+  v1Event({
+    tool_name: 'db_query',
+    tool_category: 'DATABASE',
+    action,
+    action_hash: stableHash(action)!,
+    authorized: false,
+    approval_required: true,
+    approval_missing: true,
+    approval_type: 'HUMAN',
+    argument_risk_score: 0.85,
+    argument_risk_reasons: ['bulk_pii_access'],
+    contains_sensitive_data: true,
+    data_scope: 'ORGANIZATION',
+    action_scope: 'ORGANIZATION',
+    execution_pending: true,
+    rollback_available: false,
+  }) as ToolCallProposedSignalEvent,
+);
+```
+
+#### Session
+
+```ts
+import { createSessionEvent, type SessionSignalEvent } from 'qati-sdk';
+
+const raw = createSessionEvent(
+  v1Event({
+    session_status: 'ACTIVE',
+    session_age_seconds: 300,
+    turn_count: 12,
+    messages_last_minute: 8,
+    conversation_id: 'conv-abc',
+    message_count: 24,
+    window_seconds: 300,
+    cadence_deviation: 0.4,
+    inter_message_interval_ms: 1500,
+  }) as SessionSignalEvent,
+);
+```
+
+#### Prompt input
+
+```ts
+import {
+  createPromptInputEvent,
+  stableHash,
+  type PromptInputSignalEvent,
+} from 'qati-sdk';
+
+const prompt = 'Summarize the last three support tickets.';
+const promptHash = stableHash(prompt)?.replace(/^sha256:/, '');
+
+const raw = createPromptInputEvent(
+  v1Event({
+    prompt_length_chars: prompt.length,
+    conversation_turn_index: 3,
+    contains_instruction_override: false,
+    contains_tool_request: true,
+    contains_secret_request: false,
+    prompt_injection_score: 0.05,
+    prompt_hash: promptHash,
+    rapid_repeat: false,
+    prompt_sequence_index: 3,
+  }) as PromptInputSignalEvent,
+);
+```
+
+#### RAG retrieval
+
+```ts
+import {
+  createRagRetrievalEvent,
+  stableHash,
+  type RagRetrievalSignalEvent,
+} from 'qati-sdk';
+
+const bundle = 'doc-1|doc-2|doc-3';
+
+const raw = createRagRetrievalEvent(
+  v1Event({
+    retriever_id: 'retriever-prod',
+    query_hash: stableHash('customer refund policy'),
+    documents_retrieved: 3,
+    top_k: 5,
+    average_relevance_score: 0.82,
+    source_trust_score: 0.9,
+    lowest_source_trust_score: 0.7,
+    untrusted_source_count: 0,
+    retrieved_context_tokens: 1200,
+    context_injection_score: 0.02,
+    document_ids: ['doc-1', 'doc-2', 'doc-3'],
+    retrieval_hash: stableHash(bundle),
+    contains_sensitive_data: false,
+  }) as RagRetrievalSignalEvent,
+);
+```
+
+#### Context integrity
+
+```ts
+import {
+  createContextIntegrityEvent,
+  stableHash,
+  type ContextIntegritySignalEvent,
+} from 'qati-sdk';
+
+const raw = createContextIntegrityEvent(
+  v1Event({
+    context_source: 'RETRIEVED_DOCUMENT',
+    instruction_conflict_detected: true,
+    untrusted_instruction_detected: false,
+    context_priority_violation: false,
+    context_drift_score: 0.35,
+    prompt_injection_score: 0.12,
+    retrieved_context_hash: stableHash('assembled-context-bundle'),
+    untrusted_source_count: 1,
+    source_trust_score: 0.6,
+    contains_instruction_override: false,
+  }) as ContextIntegritySignalEvent,
+);
+```
+
+#### API call
+
+```ts
+import { createApiCallEvent, type ApiCallSignalEvent } from 'qati-sdk';
+
+const raw = createApiCallEvent(
+  v1Event({
+    service_id: 'payments-api',
+    endpoint: '/v1/transfers',
+    method: 'POST',
+    status_code: 201,
+    authorized: true,
+    authentication_present: true,
+    external_side_effect: true,
+    records_modified: 1,
+    contains_sensitive_data: true,
+    latency_ms: 85,
+    retry_count: 0,
+  }) as ApiCallSignalEvent,
+);
+```
+
+#### Workflow action
+
+```ts
+import {
+  createWorkflowActionEvent,
+  type WorkflowActionSignalEvent,
+} from 'qati-sdk';
+
+const raw = createWorkflowActionEvent(
+  v1Event({
+    workflow_name: 'payment_approval',
+    workflow_id: 'wf-001',
+    workflow_type: 'approval',
+    action_name: 'submit_wire_transfer',
+    action_category: 'FINANCIAL',
+    action_stage: 'PROPOSED',
+    actor_type: 'AI_AGENT',
+    approval_required: true,
+    approval_missing: true,
+    approval_type: 'DUAL_CONTROL',
+    financially_material: true,
+    financial_amount: 50000,
+    financial_currency: 'USD',
+    data_scope: 'ORGANIZATION',
+    action_scope: 'EXTERNAL',
+    contains_sensitive_data: true,
+  }) as WorkflowActionSignalEvent,
+);
+```
+
+#### Policy event
+
+```ts
+import { createPolicyEvent, type PolicyEventSignalEvent } from 'qati-sdk';
+
+const raw = createPolicyEvent(
+  v1Event({
+    policy_check_name: 'content_safety',
+    policy_category: 'SAFETY',
+    policy_result: 'WARN',
+    severity: 0.4,
+    blocked: false,
+    violation_count: 1,
+    policy_confidence: 0.92,
+    redaction_applied: true,
+  }) as PolicyEventSignalEvent,
+);
+```
+
+#### User feedback
+
+```ts
+import {
+  createUserFeedbackEvent,
+  stableHash,
+  type UserFeedbackSignalEvent,
+} from 'qati-sdk';
+
+const raw = createUserFeedbackEvent(
+  v1Event({
+    feedback_type: 'THUMBS_DOWN',
+    reported_issue: true,
+    issue_type: 'hallucination',
+    severity: 0.7,
+    response_id: 'resp-123',
+    user_comment_hash: stableHash('The cited regulation does not exist.'),
+    conversation_id: 'conv-abc',
+  }) as UserFeedbackSignalEvent,
+);
+```
+
 Note: At this point `raw` is an in-memory object. Nothing has been sent over the network yet. Proceed to Step 5 to deliver it.
 
 ### Canonical wire shape (`RawEventRequest` / `BaseEvent`)
@@ -653,7 +1130,12 @@ const v1Event = (signalPayload: object, extra: object = {}) => {
 };
 
 try {
-  createAnomalyFlagEvent(v1Event({ severity: 2.0 }) as AnomalyFlagSignalEvent);
+  createAnomalyFlagEvent(
+    v1Event({
+      severity: 2.0,
+      anomaly_type: 'NEW_DEVICE',
+    }) as AnomalyFlagSignalEvent,
+  );
 } catch (e) {
   if (e instanceof ZodError) console.log(e.issues);
 }
@@ -674,15 +1156,18 @@ Transient failures are retried automatically for **`POST /v1/events:batch`** acc
 
 ## Appendix: API surface (compact)
 
-| Symbol             | Role                                                                                                                                                                                                       |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Session`          | `new Session(config?)`, `session.config`, `session.createClient(httpClients?)`.                                                                                                                            |
-| `Client`           | Namespaces: `tenant`, `trustState`, `advisory`, `explain`, `events`, `webhooks`, `quotas`; `await client.close()`.                                                                                         |
-| `client.events`    | `enqueue`, `flush`, `shutdown`, `pendingCount`, `onIngestionFailure`.                                                                                                                                      |
-| `client.webhooks`  | `list(tenantId)`, `create(tenantId, body)`, `patch(tenantId, webhookId, body)`, `delete(tenantId, webhookId)`, `test(tenantId, webhookId)`.                                                                |
-| `client.quotas`    | `get(tenantId)`, `upsert(tenantId, body)`.                                                                                                                                                                 |
-| `create*Event`     | `createTransactionEvent`, `createAuthEvent`, `createModelOutputEvent`, `createSystemTelemetryEvent`, `createAnomalyFlagEvent`, `createBehaviorEvent`, `createNetworkEvent` — all exported from `qati-sdk`. |
-| Config             | `resolveQatiConfig`, `parseQatiConfig`, `baseUrlFor`, types `QatiConfigInput` / `QatiConfigOutput`.                                                                                                        |
-| Errors             | `QatiSDKError`, `QatiAPIError`, `QatiAuthError`, `QatiNotFoundError`, `QatiRateLimitError`, `QatiServerError`, `QatiConfigError`.                                                                          |
+| Symbol                 | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Session`              | `new Session(config?)`, `session.config`, `session.createClient(httpClients?)`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `Client`               | Namespaces: `tenant`, `trustState`, `advisory`, `explain`, `mccEvaluation`, `events`, `webhooks`, `quotas`; `await client.close()`.                                                                                                                                                                                                                                                                                                                                                                |
+| `client.mccEvaluation` | `list(options?)`, `get(evaluationId)`, `evaluate(entityKey)`. Keyset pagination via `after_id` / `next_cursor` (no offset).                                                                                                                                                                                                                                                                                                                                                                        |
+| MCC types              | `MCCEvaluation`, `MCCEvaluationListResponse`, `MCCBranchEvaluation`, `ListMccEvaluationsOptions` — exported from `qati-sdk`.                                                                                                                                                                                                                                                                                                                                                                       |
+| `client.events`        | `enqueue`, `flush`, `shutdown`, `pendingCount`, `onIngestionFailure`.                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `client.webhooks`      | `list(tenantId)`, `create(tenantId, body)`, `patch(tenantId, webhookId, body)`, `delete(tenantId, webhookId)`, `test(tenantId, webhookId)`.                                                                                                                                                                                                                                                                                                                                                        |
+| `client.quotas`        | `get(tenantId)`, `upsert(tenantId, body)`.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `create*Event`         | All 17 v1 builders — `createTransactionEvent`, `createAuthEvent`, `createBehaviorEvent`, `createAnomalyFlagEvent`, `createNetworkEvent`, `createModelOutputEvent`, `createSystemTelemetryEvent`, `createApiCallEvent`, `createWorkflowActionEvent`, `createToolCallEvent`, **`createToolCallProposedEvent`**, `createSessionEvent`, `createPromptInputEvent`, `createRagRetrievalEvent`, `createContextIntegrityEvent`, `createPolicyEvent`, `createUserFeedbackEvent` — exported from `qati-sdk`. |
+| `stableHash`           | Canonical scalar string hashing (`sha256:` prefix); use for hash payload fields.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Config                 | `resolveQatiConfig`, `parseQatiConfig`, `baseUrlFor`, types `QatiConfigInput` / `QatiConfigOutput`.                                                                                                                                                                                                                                                                                                                                                                                                |
+| Errors                 | `QatiSDKError`, `QatiAPIError`, `QatiAuthError`, `QatiNotFoundError`, `QatiRateLimitError`, `QatiServerError`, `QatiConfigError`.                                                                                                                                                                                                                                                                                                                                                                  |
 
 `HttpClient.request(...)` exists for advanced use; prefer resource methods for application code.