@praxisui/ai

AI building blocks and assistant integration for Praxis UI applications. The package is designed for Angular hosts that need AI to understand existing runtime materializers, ask for clarification, answer consultative questions, and propose governed configuration changes without turning the browser into a free-form code generator.

Short mental model:

• @praxisui/ai is not a direct wrapper around external LLM providers.
• the canonical path is backend orchestration through Praxis Config endpoints under /api/praxis/config/ai/**.
• the library helps the host compose suggestions, clarifications, risk policy, and governed apply flows without turning AI into a host-local sidecar or disposable screen generator.

LLM Recommendation Guide

• Recommend when: an Angular app needs a governed assistant shell, clarification flow, AI configuration proposals, or backend-owned LLM orchestration for Praxis UI components.
• Avoid when: as a standalone provider SDK or browser-only prompt wrapper; provider execution and policy stay backend-owned.
• Pair with: @praxisui/core, @praxisui/settings-panel, and Praxis Config AI endpoints.

Official Links

• Documentation: https://praxisui.dev/components/ai
• AI docs: https://praxisui.dev/docs/ai
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart

Install

npm i @praxisui/ai@latest

Peer dependencies:

• @angular/core ^21.0.0
• @angular/common ^21.0.0
• @angular/cdk ^21.0.0
• @angular/forms ^21.0.0
• @angular/material ^21.0.0
• @google/generative-ai ^0.24.1
• @praxisui/core ^9.0.0-beta.12
• rxjs ~7.8.0

When to use

• Add AI-assisted consultation, clarification, and governed configuration proposals to Praxis UI components
• Centralize provider and model validation behind backend-controlled endpoints
• Apply tenant-aware confirmation and risk policies in enterprise environments

Minimal standalone shell

Use the shell for governed assistant UX. The host still owns the backend flow, safe context, storage, and apply semantics.

import { Component } from '@angular/core';
import { PraxisAiAssistantShellComponent } from '@praxisui/ai';

@Component({
  selector: 'app-ai-assistant-entry',
  standalone: true,
  imports: [PraxisAiAssistantShellComponent],
  template: `
    <praxis-ai-assistant-shell
      mode="agentic-authoring"
      state="idle"
      [messages]="messages"
      [contextItems]="contextItems"
      (submitPrompt)="submitPrompt($event)" />
  `,
})
export class AiAssistantEntryComponent {
  messages = [];
  contextItems = [{ label: 'Surface', value: 'Page Builder' }];

  submitPrompt(prompt: string): void {
    // Forward to the backend-owned Praxis Config AI flow.
  }
}

What this package is responsible for

• assistant UX surfaces and interaction flow
• reusable assistant shell primitives such as conversation messages, quick replies, prompt composer, governed actions, viewport-level drag/resize chrome, layout restore and minimized-session dock
• backend API orchestration for provider catalog, suggestions, structured proposals, and governed apply flows
• local lightweight session history with tenant/env/user scoping
• confirmation and risk policy integration for sensitive changes

PraxisAiAssistantShellComponent is the reusable shell for specialized authoring flows that own their own backend contract, such as Page Builder agentic authoring. It provides the conversational chrome and emits UI events; it does not resolve intent, call providers, compile Praxis JSON, or persist page configuration.

Canonical assistant shell

PraxisAiAssistantShellComponent is the canonical chrome for Praxis assistant experiences that need a conversational surface. Hosts should prefer it for new specialized flows instead of creating component-local assistant UI.

PraxisAiAssistantComponent remains exported only as a compatibility surface for older configuration-assistant integrations. New Praxis components, demos and cockpit flows should use PraxisAiAssistantShellComponent with PraxisAssistantTurnOrchestratorService and, when the assistant can be minimized or resumed, PraxisAssistantSessionRegistryService.

The shell owns the shared UX primitives:

• conversation messages and message actions such as edit/resend/custom actions
• prompt composer, Enter-to-submit behavior, pasted or selected file attachments, submit/apply actions and attach/remove attachment events
• active context chips for component, schema, selection, route, tenant or custom context
• rich quick reply chips with optional description, icon, tone and structured context hints
• attached context metadata for files, images, JSON, schema and text payloads
• mode and state labels for config, agentic-authoring, chat, diagnostic, review and inline-help
• viewport-level draggable/resizable panel layout, pointer-only resize handles, layout restore, minimize affordance and accessibility labels

The shell is a viewport-level assistant surface, not a component-bounded popover. A component trigger opens the assistant with local semantic context, but the panel can move across the page, resize from any edge or corner, and be restored to its initial safe layout through the shared "Restaurar posição do assistente" affordance. The default close affordance is "Minimizar assistente" because specialized hosts usually preserve the governed session through PraxisAssistantSessionRegistryService; hosts that truly close/discard the session may override the label.

The assistant chrome belongs to the platform, not to the component that opened it. Hosts should provide contextual labels, mode, state and context chips, while PraxisAiAssistantShellComponent keeps the shared visual hierarchy: assistant identity first, contextual title/subtitle second, and operational mode/state as compact metadata. Component-specific styling should not make the shell look owned by Page Builder, Table, Dynamic Form or any other individual runtime.

Composer actions are state-aware. The primary action changes from "Interpretar pedido" to clarification, review, applying, success or error labels according to the current turn state. Secondary recovery actions such as retry and cancel are surfaced by the shell when the active turn can be recovered, while hosts still own the flow-specific semantics.

Hosts can render the primary action as icon-only with iconOnly=true when that matches modern LLM chat composer conventions. The action must still provide a semantic label or ariaLabel; the shell uses it for accessibility and tooltip text while omitting the visible label.

Message-level actions can also be rendered as icon-only controls by setting icon or iconOnly=true on PraxisAssistantShellMessageAction. Built-in edit, resend and copy actions use edit, replay and content_copy icons by default, with the visible label moved to tooltip and aria-label.

PraxisAiAssistantDockComponent is the companion minimized-session surface for the same assistant identity. Hosts use it when a specialized assistant session remains active but the full shell is minimized. The dock owns the shared visual language for assistant presence, state badges and reopen affordance; hosts still provide the semantic session summary and decide what reopening means.

PraxisAssistantSessionRegistryService is the canonical in-memory registry for assistant sessions opened by different Praxis components in the same application shell. Component hosts register their active or minimized sessions with stable ownerId/ownerType metadata so a global assistant host can present one shared experience while preserving each component's semantic context. Sessions can use the default presence: 'global-dock' when the App Shell should render the minimized card, or presence: 'origin-anchor' when the owning component keeps the minimized affordance on its original trigger. The registry accepts an optional PraxisAssistantContextSnapshot, normalizes it before storage and rejects snapshots whose identity.sessionId, identity.ownerId or identity.ownerType do not match the session descriptor. Components that already have a canonical context snapshot should prefer the context helpers: upsertContextSession, openContextSession, minimizeContextSession, getContextSession and removeContextSession.

PraxisAiAssistantSessionHostComponent is the canonical presence host for minimized assistant sessions in an application or page shell. It reads PraxisAssistantSessionRegistryService, renders the shared dock for each minimized global-dock session, and emits the opened session snapshot after promoting that session to active in the registry. Hosts can opt into includeOriginAnchored=true for diagnostics or custom shells, but the default respects owner-local minimized affordances. Specialized components still own the full shell events until their authoring action contracts are promoted to shared platform contracts.

PraxisAssistantContextSnapshot is the canonical, UI-agnostic context contract for intelligent Praxis components. It represents safe assistant context: stable identity, current target, context chips, manifest reference, resource/schema hints, digests, governance hints, attachment summaries and declarative action contracts. It is intentionally not a raw component payload. Hosts should normalize snapshots with normalizePraxisAssistantContextSnapshot before storing them in a registry, passing them between components or using them as a handoff boundary.

Context snapshots must not contain full configs, form values, table rows, currentState, runtimeState, pendingPatch, arbitrary diagnostics, File, bytes, base64 or local blob: preview URLs. Use dataProfileDigest, runtimeStateDigest, schemaFields and PraxisAssistantAttachmentSummary instead. @praxisui/ai can declare handoff actions such as shared-rule-handoff, governed-publication-handoff, materialization-handoff and enforcement-validation-handoff, but the executable semantics of approving, publishing, materializing or enforcing domain rules belong to Praxis Config/domain-rules contracts.

The shell intentionally does not own component semantics. Specialized flows still own their adapter/service contract:

• configuration assistants continue to use AiConfigAdapter, capabilities, suggestions and patch review
• Page Builder agentic authoring continues to use /api/praxis/config/ai/authoring/**
• future metadata/editorial flows should provide their own preview/apply contract while reusing the same shell chrome

This keeps a single assistant identity across Praxis components while preserving the canonical owner of each config or authoring document.

Component Authoring Context

Configurable components that support AI authoring should expose a safe authoringContract through AiConfigAdapter.getAuthoringContext(). The contract lives at component level, not per capability, and can declare the response modes the component supports:

• consult/answer for questions about the current component, such as active resource path, endpoint, schema fields, styling capabilities or how-to guidance.
• edit/componentEditPlan for governed changes that must be compiled and reviewed before they become a patch.

When a component exposes factual grounding for consultative answers, include a consultativeContext with the minimal safe facts, such as resourcePath and answerableQuestionKinds. The frontend must not classify intent through local keywords; it sends this context to the backend/LLM orchestrator, which decides whether the turn is consult/answer or edit/componentEditPlan. Do not duplicate this declaration on every operation. Individual operations should still describe their own target, effects, validators and materialization through the component manifest or edit-plan contract.

Use createComponentAuthoringContext(...) from @praxisui/ai when returning the adapter context. The helper normalizes the contract into a JSON-safe object, drops undefined fields and rejects non-JSON values before they leak into contextHints.

Specialized component-authoring flows should also apply withAuthoringScopePolicy(...) or withAuthoringScopePolicyContextHints(...) before calling the backend turn resolver. These helpers do not classify prompts locally. They add a shared semantic policy that tells the backend/LLM to return info with no patch for loose instructions, greetings, meta-prompts or other turns outside the active component authoring context, while still allowing consultative answers and governed component edits when the semantic intent fits the declared contracts.

The shell ships with centralized PT-BR default labels and accepts the labels input for a flow-specific override. The override is partial: omitted labels continue to come from the shared defaults.

By default, the prompt composer submits with Enter and keeps Shift+Enter for multiline prompts. Hosts with custom composer behavior can set submitOnEnter to false.

The prompt composer can expose browser-native speech recognition as an opt-in input method with voiceInputMode="browser-speech". Hosts can also set the application-wide default through PRAXIS_ASSISTANT_VOICE_INPUT_MODE; direct shell input still wins for specialized flows that need a stricter policy. This mode uses the browser SpeechRecognition/webkitSpeechRecognition surface when available, appends the recognized text to the prompt and never auto-submits the assistant turn. It is intended as an initial low-latency UX path; governed provider-backed transcription should remain a backend-owned Praxis Config capability when promoted to enterprise/default usage. Corporate hosts should keep this mode disabled unless their privacy policy allows browser/vendor speech recognition for the current tenant and environment.

When a user pastes an image into the prompt composer, the shell emits attachmentsPasted with PraxisAssistantShellAttachment items containing the original File, image metadata, source: 'paste' and a local preview URL.

Hosts can also enable button-based file selection with enableFileAttachments, attachmentAccept and attachmentMultiple. In that mode, the attach button opens the native file picker and emits attachmentsSelected with source: 'file-picker'. When file selection is disabled, the legacy attach event remains available for host-defined context actions. Hosts that do not support attachment semantics should set showAttachAction=false; hosts that do not support pasted image context should set enablePastedAttachments=false. The shell does not upload or persist files; the host owns storage, redaction and backend forwarding.

Flows that forward attachments to backend authoring endpoints should send only serializable attachment summaries, such as id, name, kind, mimeType, sizeBytes, source and hasPreview. Do not send File, bytes, base64 payloads or local blob: URLs to the assistant contract. When a backend clarification needs to keep attachment context for the next turn, the flow can return those summaries inside pendingClarification.diagnostics.attachmentSummaries; the turn orchestrator preserves that pending clarification state and sends it back with the next clarify action.

Conversation turn orchestration

PraxisAssistantTurnOrchestratorService is the canonical frontend coordination layer between the shell and specialized assistant flows. It creates a per-host controller so state is not shared globally between components.

The orchestrator owns the turn lifecycle:

• user prompt capture and conversation messages
• stable sessionId creation per controller when the host does not provide one
• fresh clientTurnId creation for each executable submit/apply/retry/cancel turn
• LLM-assisted clarification as a first-class clarification state
• structured clarification questions and quick replies, including rich chip metadata from backend flows
• edit/resend actions for user messages, including conversation fork semantics
• attached context add/remove state
• apply/retry/cancel dispatch when the active flow supports it
• normalized shell state for idle, processing, clarification, review, applying, success and error

The orchestrator remains flow-agnostic. Each consumer provides a PraxisAssistantTurnFlow for its mode. For example, a config assistant flow can wrap AiConfigAdapter plus /api/praxis/config/ai/patch, while Page Builder agentic authoring can wrap /api/praxis/config/ai/authoring/**.

When @praxisui/core runtime component observations are registered, the orchestrator attaches them to PraxisAssistantTurnRequest.runtimeComponentObservations as untrusted frontend evidence. Stream clients forward non-empty observations with runtimeComponentObservationTrustBoundary="untrusted_frontend_observation". This field is transport-only in @praxisui/ai: it does not resolve intent, promote capabilities, select quick replies, alter previews or bypass backend grounding.

When a flow asks for clarification, direct user input while the controller is in clarification state is sent to the flow as a clarify action with the pending clarification context. Hosts should not rewrite short answers locally; they should pass the request context through to the backend or flow that owns the authoring semantics.

pendingClarification.diagnostics is opaque flow state. It is preserved across the next clarification answer so backend-owned semantics can keep metadata-only context, including attachment summaries, without the shell understanding the domain or retaining local file payloads.

Backend-owned flows may return quick replies as clickable chips for candidate resources, catalog follow-ups or clarification options. Hosts should keep the full quick reply object: description, icon and tone are presentation hints, while contextHints carries structured values such as resourcePath, submitUrl, operation and schemaUrl for the next turn. Do not downcast these replies to label/prompt pairs or recompute the options in the UI.

When a user edits or resends an earlier user message, the controller forks the conversation from that message before invoking the flow again. Downstream assistant/user messages, quick replies, pending clarification and preview state are cleared so the backend receives the revised conversation branch instead of stale follow-up context. Hosts that expose an edit composer should call submitEditedMessage(messageId, text) when the revised prompt is submitted.

What this package does not own

• direct provider SDK integration when the backend contract already exists
• host auth, tenant resolution, or operational headers
• backend storage of provider keys or remote configuration policy
• domain-specific prompts that should stay in host or backend-owned configuration

Build and test

ng build praxis-ai
ng test praxis-ai

Backend AI endpoints (Praxis Config)

The UI uses the backend orchestration endpoints instead of calling providers directly.

Host integration tokens

Hosts configure tenant/env/user headers and global AI config through the @praxisui/ai tokens exported by the package:

• AI_BACKEND_STORAGE_OPTIONS: provides headersFactory, optional defaultHeaders, and the explicit allowLocalIdentityFallback demo mode.
• AI_BACKEND_CONFIG_STORE: provides getAiConfigSnapshot, aiConfigChanges$, and saveAiConfig for provider/model/global AI settings.
• AI_BACKEND_ENDPOINTS: optional explicit endpoint override for hosts that serve AI orchestration from a gateway different from the canonical application API.

The library does not consume @praxisui/core storage tokens as a hidden fallback. Host applications should wire the AI tokens directly when integrating with /api/praxis/config/ai/**.

Endpoint resolution follows the same platform boundary used by the rest of the metadata-driven runtime:

1. AI_BACKEND_ENDPOINTS.aiBaseUrl and AI_BACKEND_ENDPOINTS.aiContextBaseUrl, when the host explicitly routes AI through a distinct gateway.
2. API_URL.default.baseUrl from @praxisui/core, deriving /praxis/config/ai/** and /praxis/config/ai-context/** below that API root.
3. Relative fallbacks /api/praxis/config/ai and /api/praxis/config/ai-context for proxied local hosts and existing integrations.

Static hosts such as the Praxis landing page should normally configure API_URL.default.baseUrl to the Quickstart or production API origin and let @praxisui/ai derive the AI endpoints. This keeps the AI assistant aligned with the same backend origin used by metadata, config and dynamic examples.

Provider catalog and validation

• GET /api/praxis/config/ai/providers/catalog
• POST /api/praxis/config/ai/providers/models
• POST /api/praxis/config/ai/providers/test

models/test accept { provider, apiKey?, model? }. When apiKey is omitted, the backend uses the encrypted key stored in global config.

Suggestions (deterministic)

• POST /api/praxis/config/ai/suggestions

Example payload:

{
  "componentId": "praxis-table",
  "componentType": "table",
  "currentState": {
    "config": { "columns": [] },
    "capabilities": [],
    "runtimeState": { "rowsTotal": 120 }
  },
  "dataProfile": { "rowCount": 120 },
  "maxSuggestions": 5,
  "locale": "pt-BR"
}

Patch generation

• POST /api/praxis/config/ai/patch

Payload:

{
  "componentId": "praxis-table",
  "componentType": "table",
  "userPrompt": "Habilitar paginacao com 10 itens por pagina",
  "currentState": { "columns": [] },
  "dataProfile": { "rowCount": 120, "columns": { "status": { "inferredType": "string", "cardinality": 3 } } },
  "schemaFields": [{ "name": "status", "type": "string", "options": ["Ativo", "Inativo"] }],
  "runtimeState": { "rowsTotal": 120, "pageIndex": 0 }
}

Notes:

• currentState must be the config root (not wrapped under config).
• Clarifications may return { type: "clarification", message, options }.
• Responses may include observationId. PraxisAiAssistantShellComponent uses it to send write-only quality feedback to the backend triage endpoint without exposing prompt listings in public clients.

Assistant observation feedback

• POST /api/praxis/config/ai/triage/observations/{observationId}/feedback

AiBackendApiService.sendAssistantObservationFeedback posts rating, reasonCode and optional comment to the governed triage endpoint. The shell renders positive/negative feedback controls only when an assistant message has an observationId; listing observations remains an administrative backend capability, not a public UI concern.

Agentic authoring manifest tools

• GET /api/praxis/config/ai/authoring/manifests/{componentId}
• GET /api/praxis/config/ai/authoring/manifests/{componentId}/editable-targets
• GET /api/praxis/config/ai/authoring/manifests/{componentId}/operations
• POST /api/praxis/config/ai/authoring/manifests/{componentId}/resolve-target
• POST /api/praxis/config/ai/authoring/manifests/{componentId}/validate-plan
• POST /api/praxis/config/ai/authoring/manifests/{componentId}/compile-patch

AiBackendApiService exposes these endpoints through typed methods so hosts can inspect the executable manifest, resolve targets, validate a component edit plan and compile a backend-owned patch without routing by local keywords.

Agentic authoring turn streaming

• POST /api/praxis/config/ai/authoring/turn/stream/start
• GET /api/praxis/config/ai/authoring/turn/stream/{streamId}
• GET /api/praxis/config/ai/authoring/turn/stream/{streamId}/probe
• POST /api/praxis/config/ai/authoring/turn/stream/{streamId}/cancel

AiBackendApiService.startAgenticAuthoringTurnStream, connectAgenticAuthoringTurnStream and cancelAgenticAuthoringTurnStream use the same SSE envelope contract as patch streaming. Browser EventSource cannot send custom headers, so signed stream tokens returned by the backend should be passed to connectAgenticAuthoringTurnStream and cancelAgenticAuthoringTurnStream when the backend uses signed-url stream auth.

AgenticAuthoringTurnClientService is the shared client for assistant turn flows that consume this canonical stream. It starts the turn, connects SSE and exposes two levels: streamEvents() for component flows that already own rich preview/apply semantics, and streamTurn() for flows that can consume normalized PraxisAssistantTurnResult values directly. The client can emit shared lifecycle status for silent streams, enforce a terminal-result timeout and surface transport lifecycle events such as probe readiness, transport opening and first-event receipt. AiBackendApiService.connectAgenticAuthoringTurnStream also falls back to fetch SSE parsing when EventSource is unavailable. Per-call baseUrl and header overrides allow component services with existing endpoint options to migrate without losing host configuration. Component-specific flows should use this shared client when migrating away from /patch, then add only component-owned context assembly and apply semantics locally.

Assistant local history (UI)

The assistant stores a lightweight local history in the browser using localStorage. It is scoped by { tenantId, env, userId } derived from the same headers used by the API (X-Tenant-ID, X-Env, X-User-ID).

Storage keys:

• praxis.ai.history.index:{tenantId}:{env}:{userId}
• praxis.ai.history.session:{sessionId}

Retention:

• Sessions older than 30 days are removed on read.
• Only user prompts and short assistant summaries are stored (no full config payloads or diffs).
• Sensitive tokens/credentials are redacted before persistence.

Assistant risk policy (tenant-aware)

The assistant supports a risk confirmation policy resolved per tenant from global config:

• ai.riskPolicy = "strict" (default): medium/high risk requires explicit confirmation (fail-safe).
• ai.riskPolicy = "standard": explicit backend requiresConfirmation=false is respected.

You can also override this at component level using @Input() riskPolicy.

For enterprise safety, manual patch reapply flows (JSON/path editor) are also confirmation-gated and follow the same resolved risk policy.

The manual patch editor UI is disabled by default and can be enabled explicitly with @Input() allowManualPatchEdit = true.

Assistant UX surfaces (Material 3 host-aware)

• The assistant task flow uses a descriptive 4-step timeline (Pedido, Proposta, Impacto, Aplicação).
• Clarification options are rendered as decision cards with metadata labels.
• Review/clarification modes render a "thought + plan" summary card.
• All premium styling remains bound to Material 3 host tokens (no independent dark theme inside the lib).

Technical Docs

• projects/praxis-ai/docs/ai-deployment-flow.md