@nexalink/carecompass-sdk 0.2.0-beta.15 → 0.4.0-beta.15

package/README.md

@@ -1,141 +1,190 @@
-# CareCompass Healthcare AI Infrastructure SDK
+# CareCompass SDK
 
-CareCompass helps healthcare teams launch branded healthcare navigation assistants, member support assistants, and patient-facing AI experiences inside their own portals or applications. The SDK combines an embeddable chat experience with Nexalink-hosted healthcare AI infrastructure, reducing the implementation effort required to move from idea to deployable healthcare navigation workflow.
+CareCompass is embeddable healthcare AI infrastructure for teams building AI-powered healthcare products.
 
-The SDK is publicly installable for developer convenience, but live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. CareCompass is designed for healthcare navigation and support workflows. It is not a general-purpose LLM SDK, not a medical diagnosis tool, not autonomous treatment recommendation software, and not a replacement for clinicians or clinical judgment.
+It gives healthcare companies a secure SDK and hosted runtime for adding LLM-powered experiences to their own applications without building the regulated AI stack from scratch: model routing, tenant-aware runtime APIs, browser-safe authentication, prompt controls, guardrails, origin validation, deployment checks, and healthcare-specific onboarding.
 
-## Who It's For
+CareCompass is for teams that want to ship their own AI product experience while relying on Nexalink to operate the healthcare AI infrastructure layer underneath.
 
-- Healthcare startups building AI-powered patient experiences
-- Payer innovation and member engagement teams
-- Employer-benefits platforms
-- Provider organizations adding patient-facing support workflows
-- Digital health engineering teams
-- Healthcare product teams that need AI infrastructure quickly
+The SDK gives teams two integration paths:
 
-## Why Teams Use CareCompass
+- **Headless core** for product teams that want full control over their own UI, workflow, state management, and rendering.
+- **Optional UI kit** for teams that want a fast, branded AI chat experience they can drop into a web app and customize over time.
 
-- **Faster deployment**: add a healthcare-focused AI assistant to an existing healthcare product without months of infrastructure work.
-- **Reduced engineering effort**: avoid building and operating the supporting healthcare AI infrastructure around the assistant.
-- **Hosted healthcare AI runtime**: chat requests route through Nexalink-hosted APIs and the CareCompass AI runtime.
-- **Embedded branded experience**: use the React component, JavaScript mount helper, generated embed page, or iframe with your display name, labels, theme, logo, and support links.
-- **Prompt and configuration controls**: define approved prompt context, welcome copy, placement, allowed origins, and deployment environment.
-- **Deployment controls**: use key management, origin allowlists, hosted validation, and staging/production credential separation.
-- **Enterprise onboarding**: support BAA-gated onboarding where PHI may be involved.
+CareCompass is not a diagnosis tool, autonomous treatment product, replacement for clinicians, or general-purpose LLM SDK. It is healthcare AI infrastructure for building compliance-oriented, embedded AI workflows.
 
-## Why Not Build It Yourself?
+## Why Teams Choose CareCompass
 
-Most healthcare teams can access foundation models through OpenAI, Anthropic, Bedrock, Azure OpenAI, or similar providers. The harder work is not obtaining an LLM. The harder work is building and operating the healthcare AI infrastructure around it:
+Healthcare teams can already access foundation models. The hard part is turning those models into production-ready healthcare software.
 
-- Healthcare-focused prompts and guardrails
-- Hosted inference infrastructure
-- Tenant isolation
-- Key management
-- Deployment validation
-- Browser embedding
-- Usage tracking
-- Compliance-oriented onboarding
+CareCompass packages the healthcare-specific infrastructure layer that most teams would otherwise need to build themselves:
 
-CareCompass provides a managed healthcare AI infrastructure layer for these workflows, while keeping the embedded experience configurable for your application and brand.
+- secure hosted runtime APIs
+- tenant and environment routing
+- browser-safe embed authentication
+- origin allowlist validation
+- prompt and configuration controls
+- guardrails for regulated workflows
+- deployment readiness checks
+- white-label UI support
+- operational onboarding for healthcare use cases
+
+Instead of spending months building LLM infrastructure, product teams can use CareCompass to embed AI into their own application and focus on the workflow, customer experience, and clinical or operational use case they are trying to ship.
+
+## What You Can Build
+
+CareCompass can power healthcare AI features inside products such as:
+
+- clinical workflow copilots
+- patient engagement assistants
+- care navigation and resource guidance flows
+- benefits or plan guidance experiences
+- RCM and prior authorization support tools
+- onboarding and support flows for digital health products
+- internal operations copilots for healthcare teams
+- white-labeled AI assistants inside existing healthcare applications
+
+CareCompass is intentionally workflow-agnostic at the infrastructure layer. The customer owns the product experience; CareCompass provides the SDK, runtime, guardrails, and deployment model needed to make healthcare AI usable in production.
 
 ## What You Avoid Building
 
-- Model gateway
-- Chat embed
-- Prompt validation layer
-- Tenant and key management
-- Usage tracking
-- Hosted inference path
-- Staging and production credential separation
-- Deployment validation tooling
+CareCompass handles infrastructure that healthcare AI teams usually need before they can safely ship:
+
+- Hosted inference gateway
+- Tenant-aware runtime APIs
+- Browser-safe embed authentication model
+- Tenant and environment routing
+- Origin allowlist validation
+- Prompt and configuration validation
+- Guardrail enforcement
+- Streaming and retry lifecycle state
+- Default chat UI and iframe setup assets
+- Deployment readiness tooling
+- Anonymous deployment-health telemetry
 - Compliance-oriented onboarding workflow
 
-## What You Can Build
+## SDK Architecture
 
-- Member support assistants
-- Benefits navigation assistants
-- Provider discovery support flows
-- Employer healthcare navigation portals
-- Payer member engagement tools
-- Digital health support chat experiences
+```text
+Your product UI
+  |
+  | uses either
+  |-- CareCompass headless core
+  |-- CareCompass UI kit
+  |
+CareCompass SDK
+  |
+Nexalink-hosted CareCompass APIs
+  |
+CareCompass AI runtime
+```
 
-## Example Questions CareCompass Can Help With
+The browser receives only public embed configuration: tenant identifier, environment, public embed key, allowed origins, branding, labels, theme, placement, and approved prompt settings.
 
-CareCompass is intended for healthcare navigation and support, not diagnosis or treatment recommendations. Example navigation questions include:
+Secret API keys stay in CLI, server-side, or trusted setup workflows. The browser never receives model credentials or Nexalink API keys.
 
-- "How do I find an in-network cardiologist?"
-- "What does my deductible mean?"
-- "How do I schedule a specialist appointment?"
-- "Where can I find behavioral health resources?"
-- "What support resources are available through my plan?"
+## Integration Options
 
-## What CareCompass Is Not
+### 1. Headless Core
 
-- Not a general-purpose LLM SDK
-- Not a diagnosis tool
-- Not a replacement for clinical judgment
-- Not autonomous treatment recommendation software
+Use the headless core when your team already has a product surface and wants CareCompass to own the AI runtime lifecycle, not the UI.
 
-## Quick Start
+The core manages:
 
-Account creation and credentials are required because CareCompass is healthcare AI infrastructure for regulated deployment workflows, not an unauthenticated demo widget. The CLI requires Node.js 18 or newer.
+- message submission
+- poll-backed streaming lifecycle events
+- conversation snapshots
+- loading, error, timeout, and retry state
+- context injection
+- subscriptions for custom renderers
+- endpoint calls and telemetry integration
 
-```bash
-npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
-npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
-npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
-```
+```ts
+import { createCareCompassCore } from "@nexalink/carecompass-sdk/core";
+import config from "./carecompass/carecompass.config.json";
 
-`init` validates your Nexalink API key, stores it locally, and generates:
+const careCompass = createCareCompassCore(config, {
+  initialContext: {
+    userId: "user_123",
+    organizationId: "acme-health",
+  },
+});
+
+const unsubscribe = careCompass.subscribe((snapshot) => {
+  renderMessages(snapshot.messages);
+  renderLoading(snapshot.loading);
+  renderError(snapshot.error);
+});
+
+for await (const event of careCompass.streamMessage(
+  "Help me understand the next step in this workflow.",
+  { context: { workflow: "patient-onboarding" } },
+)) {
+  console.log(event.type);
+}
 
-- `carecompass/carecompass.config.json`
-- `carecompass/system-prompt.md`
-- `carecompass/carecompass-embed.html`
-- `carecompass/carecompass-iframe.html`
-- `carecompass/README.md`
+unsubscribe();
+careCompass.dispose();
+```
 
-`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package.
+The streaming API is lifecycle streaming over the existing CareCompass endpoint flow. It exposes submitted, status, completion, and error events so your UI can respond immediately while the hosted runtime works. It is not token-by-token model streaming.
 
-## How It Works
+### 2. Optional React UI Kit
 
-```text
-Your Application
-  ↓
-CareCompass SDK
-  ↓
-Nexalink Hosted APIs
-  ↓
-CareCompass AI Runtime
-```
+Use the UI kit when you want a fast branded AI interface with minimal setup.
 
-Your application renders the CareCompass UI through the SDK. The browser receives only public embed configuration: payer ID, environment, public embed key, branding, labels, theme, support links, approved prompt settings, placement, and telemetry defaults. The browser does not receive the secret API key, private model endpoint details, SageMaker credentials, AppSync signing roles, or Nexalink server-side allowlists.
+```tsx
+import { CareCompassChat } from "@nexalink/carecompass-sdk/ui";
+import config from "./carecompass/carecompass.config.json";
 
-Chat requests go to Nexalink-hosted CareCompass API routes. Those hosted routes are responsible for authorization, origin validation, tenant isolation, prompt guardrails, rate limiting, request attribution, usage tracking, and routing to the CareCompass AI runtime.
+export function HealthcareAssistant() {
+  return (
+    <CareCompassChat
+      config={config}
+      initialContext={{ userId: "user_123" }}
+      renderMessage={(message) => (
+        <p data-role={message.role}>{message.text}</p>
+      )}
+      retryLabel="Try again"
+      onEvent={(event) => console.log(event.type)}
+    />
+  );
+}
+```
 
-## Account, Credentials, and BAA Requirements
+The UI kit includes:
 
-A Nexalink account with SDK access is required beyond package installation so Nexalink can validate payer identity, deployment environment, allowed origins, approved prompt configuration, credentials, and API usage.
+- branded header, labels, disclaimer, and theme support
+- loading, error, and retry states
+- default assistant markdown rendering for headings, bold text, lists, rules, and tables
+- safe text rendering without raw HTML injection
+- `renderMessage` escape hatch for teams that want complete message-render control
+- compatibility with existing `CareCompassEmbed` and `mountCareCompass` integrations
 
-CareCompass uses two different keys:
+Custom message rendering:
 
-- **API key**: a secret credential for trusted setup and server-side or CLI workflows, including `init` sign-in and validation. Never include it in browser code, generated embed HTML, frontend config, or source control.
-- **Embed key**: a public browser-facing identifier for the CareCompass embed. It is safe to include in `carecompass.config.json` and generated snippets. It identifies the payer, environment, and embed client for runtime requests, but it is not a secret or proof of identity on its own.
+```tsx
+<CareCompassChat
+  config={config}
+  renderMessage={(message) => (
+    <MessageBubble role={message.role}>{message.text}</MessageBubble>
+  )}
+/>
+```
 
-API keys are issued in the Nexalink portal. When PHI may be involved, a tenant owner or admin may need to execute the canonical BAA before generating the first key. The secret API key is shown once, stored locally by the developer, and should be handled as a server-side or CLI credential.
+### 3. Existing Embed Compatibility
 
-## React Usage
+Existing embed integrations can keep using the root package exports.
 
 ```tsx
 import { CareCompassEmbed } from "@nexalink/carecompass-sdk";
 import config from "./carecompass/carecompass.config.json";
 
-export function MemberSupport() {
+export function HealthcareAssistant() {
   return <CareCompassEmbed config={config} />;
 }
 ```
 
-## JavaScript Usage
-
 ```ts
 import { mountCareCompass } from "@nexalink/carecompass-sdk";
 import config from "./carecompass/carecompass.config.json";
@@ -143,9 +192,31 @@ import config from "./carecompass/carecompass.config.json";
 mountCareCompass(document.getElementById("carecompass-root"), config);
 ```
 
-## Configuration Reference
+## Quick Start
+
+Live regulated use requires Nexalink onboarding, issued credentials, and BAA coverage where PHI may be involved. The package is publicly installable for developer convenience, but runtime access is credentialed.
+
+```bash
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://app.acme-health.com
+npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
+npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
+```
+
+`payerId` is the current tenant identifier used by the SDK. Despite the name, it can represent any healthcare customer workspace, including providers, digital health companies, RCM vendors, care platforms, AI healthcare products, and other healthcare organizations.
+
+`init` creates a starter setup kit:
+
+- `carecompass/carecompass.config.json`
+- `carecompass/system-prompt.md`
+- `carecompass/carecompass-embed.html`
+- `carecompass/carecompass-iframe.html`
+- `carecompass/README.md`
+
+`npx` does not install a permanent `carecompass` command. Keep using `npx @nexalink/carecompass-sdk <command>` or install the package in your project.
 
-`carecompass/carecompass.config.json` is safe to commit when it contains only public embed configuration. Store the secret API key only in local CLI credentials or an approved server-side secret store.
+## Public Configuration
+
+`carecompass.config.json` is safe to commit when it contains only public embed configuration. Do not put the secret API key in browser code, generated HTML, frontend config, or source control.
 
 ```json
 {
@@ -153,11 +224,11 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
   "environment": "staging",
   "apiBaseUrl": "https://www.nexalink.care",
   "embedKey": "embed_public_key_from_nexalink",
-  "allowedOrigins": ["https://members.acme-health.com"],
+  "allowedOrigins": ["https://app.acme-health.com"],
   "branding": {
     "displayName": "Acme Health",
-    "logoUrl": "https://members.acme-health.com/logo.svg",
-    "supportUrl": "https://members.acme-health.com/support"
+    "logoUrl": "https://app.acme-health.com/logo.svg",
+    "supportUrl": "https://app.acme-health.com/support"
   },
   "theme": {
     "primaryColor": "#2563eb",
@@ -167,15 +238,15 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
     "fontFamily": "system-ui, sans-serif"
   },
   "labels": {
-    "title": "Acme Care Guide",
-    "placeholder": "Ask about benefits, care options, or next steps...",
+    "title": "Acme AI Assistant",
+    "placeholder": "Ask about this workflow...",
     "sendButton": "Send",
-    "disclaimer": "CareCompass provides navigation support, not medical advice.",
+    "disclaimer": "This assistant provides support, not medical advice.",
     "errorMessage": "CareCompass is unavailable right now."
   },
   "prompt": {
     "systemInstructionFile": "./system-prompt.md",
-    "welcomeMessage": "How can I help you navigate your care today?",
+    "welcomeMessage": "How can I help?",
     "allowUserContext": false
   },
   "placement": {
@@ -185,39 +256,34 @@ mountCareCompass(document.getElementById("carecompass-root"), config);
 }
 ```
 
-`carecompass/system-prompt.md` defines approved context before a member message reaches the AI runtime: plan terminology, support boundaries, escalation rules, and navigation context. The CLI resolves the prompt file into `carecompass/carecompass-embed.html`; the browser receives prompt text, not a local file path. Nexalink guardrails still validate prompt content.
+## Credential Model
 
-`carecompass/carecompass-iframe.html` contains the iframe to place on the integrating page:
+CareCompass uses two key types:
 
-```html
-<iframe
-  title="Acme Health CareCompass"
-  src="/carecompass/carecompass-embed.html"
-  style="width: 100%; min-height: 640px; border: 0; border-radius: 8px;"
-  loading="lazy"
-></iframe>
-```
+- **API key**: secret credential for trusted setup, CLI validation, and server-side workflows. Never expose it in browser code.
+- **Embed key**: public browser-facing identifier used by the runtime embed. It identifies the tenant, environment, and embed client, but it is not a secret by itself.
 
-Serve `carecompass/carecompass-embed.html` at the iframe `src`, often by copying the generated `carecompass` folder into public/static assets.
+Nexalink-hosted routes remain responsible for authorization, origin validation, tenant isolation, prompt guardrails, rate limiting, request attribution, usage tracking, and routing to the CareCompass runtime.
 
 ## CLI Reference
 
 ### `init`
 
-Runs first-time setup: routes users to signup, validates the API key, stores it locally, and generates the config, prompt starter, embed page, iframe, and setup guide with only public embed configuration.
+Creates the local setup kit, validates credentials, stores the API key locally, and generates starter config and embed assets.
 
-Credentials are stored at `~/.nexalink/carecompass/credentials.json` by default. You can also set `CARECOMPASS_API_KEY`. For scripted setup, pass `--account-type developer`. Configure signup with `--developer-signup-url` or `CARECOMPASS_DEVELOPER_SIGNUP_URL`; default: `https://www.nexalink.care/developer/signup`.
+```bash
+npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://app.acme-health.com
+```
 
-Generated HTML defaults to bundler-friendly imports from `@nexalink/carecompass-sdk`. For a raw browser HTML demo that is not processed by a bundler, add `--snippet-mode cdn`.
+For raw browser HTML that is not processed by a bundler:
 
 ```bash
-npx @nexalink/carecompass-sdk init --account-type developer --api-key <nexalink-api-key> --payer-id acme-health --origin https://members.acme-health.com
-npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://members.acme-health.com
+npx @nexalink/carecompass-sdk init --account-type developer --snippet-mode cdn --payer-id acme-health --origin https://app.acme-health.com
 ```
 
 ### `validate`
 
-Checks local config shape and credentials, then hosted validation for `apiBaseUrl`, `embedKey`, `payerId`, `environment`, and `allowedOrigins` unless `--local-only` is passed. Browser-side validation uses public embed headers and does not send the secret API key.
+Checks local config shape and hosted runtime configuration.
 
 ```bash
 npx @nexalink/carecompass-sdk validate --config carecompass/carecompass.config.json
@@ -226,7 +292,7 @@ npx @nexalink/carecompass-sdk validate --local-only --config carecompass/carecom
 
 ### `snippet`
 
-Regenerates the HTML embed snippet after config, branding, origin, or prompt changes. `init` already runs this once.
+Regenerates embed HTML after config, branding, origin, or prompt changes.
 
 ```bash
 npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json
@@ -235,36 +301,42 @@ npx @nexalink/carecompass-sdk snippet --snippet-mode cdn --config carecompass/ca
 
 ### `doctor`
 
-Prints a deployment readiness summary for the selected config.
+Prints a deployment readiness summary.
 
 ```bash
 npx @nexalink/carecompass-sdk doctor --config carecompass/carecompass.config.json
 ```
 
-## Security and Compliance Model
+## Security And Compliance Positioning
 
-CareCompass is BAA-gated where PHI may be involved and HIPAA-oriented for regulated healthcare deployment workflows, but this README does not claim blanket HIPAA compliance for every implementation or deployment.
+CareCompass is BAA-gated where PHI may be involved and built for regulated healthcare workflows, but this README does not claim blanket HIPAA compliance for every implementation or deployment.
 
-The SDK keeps secret keys out of the browser. Browser code receives public embed configuration only. Staging and production `apiBaseUrl` values must be Nexalink-hosted HTTPS URLs; `localhost` is accepted only for `development`.
+The SDK is designed to keep sensitive operational details out of the browser:
 
-Nexalink-hosted API routes are responsible for authorization, origin allowlists, tenant isolation, prompt guardrails, rate limiting, request attribution, and usage tracking. Generated snippets escape serialized config, and React renders chat messages and labels as text.
+- no secret API keys in frontend config
+- no model endpoint credentials in browser code
+- no customer-managed telemetry switches in runtime config
+- no prompt, response, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, or file paths in SDK telemetry
+- generated snippets escape serialized config
+- default React rendering escapes raw HTML
 
-Telemetry is enabled automatically with Nexalink-managed defaults. The SDK sends only allowlisted anonymous deployment-health events to PostHog's public ingestion API. It does not bundle `posthog-js`, enable session replay or autocapture, identify users, set cookies, or persist analytics state. Prompts, responses, chat history, user context, PHI/PII, credentials, raw errors, stack traces, CLI arguments, terminal input, and file paths are excluded from telemetry.
+Telemetry is enabled with Nexalink-managed defaults and sends only allowlisted anonymous deployment-health events.
 
 ## Runtime Notes
 
-Some development and MVP environments may use scale-to-zero infrastructure, which can add cold-start latency to the first request after an idle period. The request still routes through Nexalink-hosted APIs; the browser embed does not receive infrastructure credentials or call the model endpoint directly.
+Some development and MVP environments may use scale-to-zero infrastructure, which can add cold-start latency to the first request after an idle period.
+
+Requests still route through Nexalink-hosted APIs. The browser embed does not receive infrastructure credentials or call model endpoints directly.
 
 ## Troubleshooting
 
 - `Missing Nexalink API key`: run `init`, choose Developer, and sign in. For scripts, pass `--account-type developer` with `--api-key <key>`, or set `CARECOMPASS_API_KEY` with `CARECOMPASS_ACCOUNT_TYPE=developer`.
 - `zsh: command not found: carecompass`: `npx` does not install a permanent command. Run `npx @nexalink/carecompass-sdk <command>` or install the package.
-- `@parcel/core: Failed to resolve 'https://esm.sh/...'`: regenerate with bundler mode: `npx @nexalink/carecompass-sdk snippet --config carecompass/carecompass.config.json`. CDN mode is for raw browser HTML.
-- `CareCompass could not reach http://localhost:3000`: hosted sandboxes cannot reach your machine's `localhost`. Test locally or use a deployed Nexalink `apiBaseUrl`. Run `validate` before typing into the embed.
-- `Origin is not authorized`: add the exact website origin to the Nexalink portal SDK configuration.
+- `@parcel/core: Failed to resolve 'https://esm.sh/...'`: regenerate with bundler mode. CDN mode is for raw browser HTML.
+- `CareCompass could not reach http://localhost:3000`: hosted sandboxes cannot reach your machine's `localhost`. Test locally or use a deployed Nexalink `apiBaseUrl`.
+- `Origin is not authorized`: add the exact website origin to the Nexalink SDK configuration.
 - `Prompt configuration violates CareCompass guardrails`: remove unsafe or unsupported instructions and re-run validation.
-- `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued in the Nexalink portal.
-- `CareCompass AppSync inference service is not configured`: Nexalink server operators should confirm `NEXT_PUBLIC_API_URL` or `CARECOMPASS_APPSYNC_URL`. The embed does not require a payer-provided LLM URL.
+- `CareCompass embed client is not authorized`: confirm `payerId`, `embedKey`, `environment`, and allowed origins match the key issued for the deployment.
 
 ## License