@infuro/cms-core 1.0.19 → 1.0.21

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CompanyDetails, T as TemplateContext, E as EmailTemplateResult, a as EmailTemplateName, O as OrderPlacedLineItem, S as StorageService, b as EntityMap$2 } from './index-D2C1O9b4.cjs';
-export { A as AnalyticsHandlerConfig, c as AuthHandlersConfig, B as BlogBySlugConfig, d as ChangePasswordConfig, e as CmsApiHandlerConfig, f as CmsGetter, g as CrudHandlerOptions, D as DashboardStatsConfig, h as EcommerceAnalyticsConfig, F as ForgotPasswordConfig, i as FormBySlugConfig, G as GetPublicSettingsGroupConfig, j as GetPublicSettingsGroupDataSource, I as InviteAcceptConfig, k as SetPasswordConfig, l as SettingsApiConfig, m as SocialLinkItem, n as StorefrontApiConfig, o as StorefrontOtpFlags, U as UploadHandlerConfig, p as UserAuthApiConfig, q as UserAvatarConfig, r as UserProfileConfig, s as UsersApiConfig, t as createAnalyticsHandlers, u as createBlogBySlugHandler, v as createChangePasswordHandler, w as createCmsApiHandler, x as createCrudByIdHandler, y as createCrudHandler, z as createDashboardStatsHandler, H as createEcommerceAnalyticsHandler, J as createForgotPasswordHandler, K as createFormBySlugHandler, L as createInviteAcceptHandler, M as createMediaZipExtractHandler, N as createSetPasswordHandler, P as createSettingsApiHandlers, Q as createStorefrontApiHandler, R as createUploadHandler, V as createUserAuthApiRouter, W as createUserAvatarHandler, X as createUserProfileHandler, Y as createUsersApiHandlers, Z as getCompanyDetailsFromSettings, _ as getPublicSettingsGroup, $ as mergeEmailLayoutCompanyDetails } from './index-D2C1O9b4.cjs';
+import { C as CompanyDetails, T as TemplateContext, E as EmailTemplateResult, a as EmailTemplateName, O as OrderPlacedLineItem, S as StorageService, b as EntityMap$2 } from './index-BGAh4fPQ.cjs';
+export { A as AnalyticsHandlerConfig, c as AuthHandlersConfig, B as BlogBySlugConfig, d as ChangePasswordConfig, e as ChatPublicConfig, f as CmsApiHandlerConfig, g as CmsGetter, h as CrudHandlerOptions, D as DashboardStatsConfig, i as EcommerceAnalyticsConfig, F as ForgotPasswordConfig, j as FormBySlugConfig, G as GetPublicSettingsGroupConfig, k as GetPublicSettingsGroupDataSource, I as InviteAcceptConfig, L as LlmAgentKnowledgeApiConfig, l as LlmAgentValidationRulesJson, P as ParsedLlmAgentValidation, m as SetPasswordConfig, n as SettingsApiConfig, o as SocialLinkItem, p as StorefrontApiConfig, q as StorefrontOtpFlags, U as UploadHandlerConfig, r as UserAuthApiConfig, s as UserAvatarConfig, t as UserProfileConfig, u as UsersApiConfig, v as createAnalyticsHandlers, w as createBlogBySlugHandler, x as createChangePasswordHandler, y as createCmsApiHandler, z as createCrudByIdHandler, H as createCrudHandler, J as createDashboardStatsHandler, K as createEcommerceAnalyticsHandler, M as createForgotPasswordHandler, N as createFormBySlugHandler, Q as createInviteAcceptHandler, R as createLlmAgentKnowledgeHandlers, V as createMediaZipExtractHandler, W as createSetPasswordHandler, X as createSettingsApiHandlers, Y as createStorefrontApiHandler, Z as createUploadHandler, _ as createUserAuthApiRouter, $ as createUserAvatarHandler, a0 as createUserProfileHandler, a1 as createUsersApiHandlers, a2 as getCompanyDetailsFromSettings, a3 as getPublicSettingsGroup, a4 as mergeEmailLayoutCompanyDetails, a5 as mergeGuardrailsIntoSystemPrompt, a6 as parseLlmAgentValidationRules, a7 as validateUserMessageAgainstAgentRules, a8 as validateUserMessageAgainstStructuredRules } from './index-BGAh4fPQ.cjs';
 import { ClassValue } from 'clsx';
 import * as typeorm from 'typeorm';
 import { DataSource, EntityTarget, ObjectLiteral } from 'typeorm';
@@ -500,7 +500,23 @@ interface LlmMessage {
     role: 'user' | 'assistant' | 'system';
     content: string;
 }
+/** Passed to {@link LlmService.chat} / {@link LlmService.streamChat}; only `model`, `temperature`, and `max_tokens` are sent to the gateway. */
 interface LlmChatOptions {
+    systemPrompt?: string;
+    userPrompt?: string;
+    history?: LlmMessage[];
+    context?: string;
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+}
+/** Options for {@link LlmService.chatAgent} / {@link LlmService.streamChatAgent}: composes system + context + history + user into chat messages. */
+interface LlmAgentOptions {
+    systemPrompt?: string;
+    userPrompt: string;
+    history?: LlmMessage[];
+    /** RAG or other material; merged into the system message when set. */
+    context?: string;
     model?: string;
     temperature?: number;
     max_tokens?: number;
@@ -510,28 +526,85 @@ interface LlmServiceInterface {
         content: string;
     }>;
     streamChat(messages: LlmMessage[], options?: LlmChatOptions): AsyncIterable<string>;
-    /** OpenAI-compatible embeddings; returns [] if gateway does not support /v1/embeddings */
+    chatAgent(options: LlmAgentOptions): Promise<{
+        content: string;
+    }>;
+    streamChatAgent(options: LlmAgentOptions): AsyncIterable<string>;
+    /**
+     * Embeddings for RAG / knowledge base. Wire format depends on {@link LlmServiceEmbedOptions}:
+     * OpenAI `{base}/v1/embeddings`, or Hugging Face via `@huggingface/inference` (Hub-routed feature extraction) with legacy HTTP fallback.
+     */
     embed?(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
 }
+declare function parseHfInferenceEmbeddingBody(data: unknown): number[] | null;
+type LlmEmbeddingProvider = 'openai' | 'huggingface';
+interface LlmServiceEmbedOptions {
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Legacy manual HTTP base when the Inference SDK path fails; default `https://router.huggingface.co/v1` (router host is normalized to `…/hf-inference`). */
+    hfInferenceBaseUrl?: string;
+    /** Token for embedding calls; defaults to chat `apiKey`. */
+    embeddingApiKey?: string;
+    /**
+     * Default `model` for `POST …/v1/chat/completions` when the caller omits `model`.
+     * Set via plugin / CMS `LLM_CHAT_MODEL` or env `LLM_CHAT_MODEL`.
+     * If unset, the library picks a fallback from `LLM_GATEWAY_URL` (HF router vs OpenRouter-style).
+     */
+    defaultChatModel?: string;
+}
+/**
+ * Set `LLM_DEBUG=1` (or `true` / `yes`) to log composed chat payloads.
+ * Set `LLM_EMBED_DEBUG=1` for per-request embedding logs (verbose with many chunks).
+ * Set `LLM_CHAT_MODEL` for the default chat model when agents/requests omit `model` (gateway-specific id).
+ * If unset, fallback is chosen from `LLM_GATEWAY_URL` (HF vs other).
+ */
 declare class LlmService implements LlmServiceInterface {
+    private static embedHttpErrorLogged;
+    private static embedShapeErrorLogged;
+    private static embedSuccessLogged;
+    private static hfDimensionMismatchWarned;
+    private static hfInferenceSdkErrorLogged;
     private readonly baseURL;
     private readonly apiKey;
     private readonly defaultEmbeddingModel?;
-    private static embedWarned;
-    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string | undefined);
+    private readonly embeddingProvider;
+    private readonly hfInferenceBaseURL;
+    private readonly embeddingApiKey;
+    private readonly defaultChatModel;
+    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string, embedOpts?: LlmServiceEmbedOptions);
+    private resolveChatModel;
     private get base();
     private get url();
-    /**
-     * OpenAI-compatible embeddings. Returns [] if endpoint not available or unexpected response.
-     * Server must implement: POST /v1/embeddings
-     * Body: { model: string, input: string }
-     * Response: { data: [ { embedding: number[] } ] } or { embedding: number[] }
-     */
+    private llmDebugEnabled;
+    /** Per-request embedding logs (noisy with many chunks). Set `LLM_EMBED_DEBUG=1`. */
+    private embedDebugEnabled;
+    private logAgentComposition;
+    private logChatCompletionsRequest;
     embed(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
+    /**
+     * POST `{ url }` with OpenAI-style `{ model, input }` and Bearer token; parses `{ data:[{embedding}] }`.
+     */
+    private fetchOpenAiShapeEmbeddings;
+    /**
+     * Hugging Face–recommended path: Hub resolves a provider that supports `feature-extraction` for the model.
+     */
+    private embedViaHuggingfaceInferenceSdk;
+    /** Base URL for legacy `…/pipeline/…` and `…/models/{model}` tries (HF router only). */
+    private hfLegacyInferenceBase;
+    /**
+     * Hugging Face embeddings: `@huggingface/inference` (Hub-routed feature extraction), then
+     * legacy direct `hf-inference` HTTP tries. Note: `https://router.huggingface.co/v1/embeddings` is not
+     * offered for embeddings (OpenAI-compatible `/v1` on HF is chat-only).
+     */
+    private embedHuggingFaceInference;
+    private buildAgentMessages;
+    chatAgent(options: LlmAgentOptions): Promise<{
+        content: string;
+    }>;
+    streamChatAgent(options: LlmAgentOptions): AsyncIterable<string>;
     chat(messages: LlmMessage[], options?: LlmChatOptions): Promise<{
         content: string;
     }>;
@@ -541,8 +614,19 @@ declare class LlmService implements LlmServiceInterface {
 interface LlmPluginConfig {
     baseURL?: string;
     apiKey?: string;
-    /** Default model for embed(); also from env EMBEDDING_MODEL (e.g. for Qwen use your server's embedding model name). */
+    /** Default chat model when agents omit `model` (`POST /v1/chat/completions`). Env: `LLM_CHAT_MODEL`. If unset, inferred from `LLM_GATEWAY_URL` (HF vs OpenRouter-style default). */
+    defaultChatModel?: string;
+    /** Default model for embed(); also from env EMBEDDING_MODEL. */
     embeddingModel?: string;
+    /**
+     * `openai` (default): `POST {LLM_GATEWAY_URL}/v1/embeddings`.
+     * `huggingface`: `@huggingface/inference` feature extraction (Hub-routed), with legacy `…/hf-inference/…` HTTP fallback. Env: `EMBEDDING_PROVIDER=huggingface`.
+     */
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Legacy HTTP base if the SDK path fails; default `https://router.huggingface.co/v1` (router hosts map to `…/hf-inference`). Env: `HF_INFERENCE_URL`. */
+    hfInferenceBaseUrl?: string;
+    /** Optional; defaults to `apiKey`. Env: `EMBEDDING_API_KEY`. */
+    embeddingApiKey?: string;
 }
 declare function llmPlugin(config?: LlmPluginConfig): CmsPlugin<LlmService | undefined>;
 
@@ -1415,7 +1499,34 @@ declare class Wishlist {
     items: WishlistItem[];
 }
 
+declare class LlmAgent {
+    id: number;
+    name: string;
+    /** Stable key for API / widgets (e.g. `support`, `sales`). */
+    slug: string;
+    /** Passed as `systemPrompt` to `LlmService.chatAgent`. */
+    systemInstruction: string;
+    model: string | null;
+    temperature: number | null;
+    maxTokens: number | null;
+    /**
+     * Rules string: plain prose → appended to system prompt as output guardrails; JSON → see `parseLlmAgentValidationRules` in cms-handlers
+     * (structural checks + optional `guardrails` / `outputRules` / `outputInstructions` for the model).
+     */
+    validationRules: string | null;
+    enabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+    deleted: boolean;
+    createdBy: number | null;
+    updatedBy: number | null;
+    deletedBy: number | null;
+}
+/** Partial {@link LlmAgentOptions} for merging with `userPrompt` / `history` / `context`. */
+declare function llmAgentToChatAgentOptions(agent: LlmAgent): Pick<LlmAgentOptions, 'systemPrompt' | 'model' | 'temperature' | 'max_tokens'>;
+
 /** Map API resource segment (e.g. "blogs", "form_submissions") to entity. Used by CRUD handler. */
 declare const CMS_ENTITY_MAP: Record<string, EntityTarget<typeorm.ObjectLiteral>>;
 
-export { Address, type AnalyticsPluginConfig, Attribute, Blog, Brand, CMS_ENTITY_MAP, type CachePluginConfig, type CacheService, type CaptchaProviderId, type CaptchaPublicConfig, CaptchaService, type CaptchaVerifyResult, Cart, CartItem, Category, ChatConversation, ChatMessage, type CmsApp, type CmsPlugin, Collection, Comment, CompanyDetails, Config, Contact, type CreateCmsAppOptions, type DataSourceManager, type ERPPluginConfig, type ERPPluginInstance, ERPSubmissionService, type EmailData, type EmailJobPayload, type EmailPluginConfig, EmailService, type EmailServiceInterface, EmailTemplateName, EmailTemplateResult, EntityMap$2 as EntityMap, type ErpContactSyncInput, type ErpCreateContactPayload, type ErpJobPayload, type ErpPaidOrderDataSource, type ErpPaidOrderEntityMap, type ExtraPublicWriteRule, Form, FormField, FormSubmission, KnowledgeBaseChunk, KnowledgeBaseDocument, type LlmChatOptions, type LlmMessage, type LlmPluginConfig, LlmService, type LlmServiceInterface, type LocalStoragePluginConfig, type Logger, Media, MessageTemplate, Order, OrderItem, type OrderPlacedEmailPayload, OrderPlacedLineItem, OtpChallenge, type OtpChannel, type OtpPurpose, Page, PasswordResetToken, Payment, type PaymentIntent, type PaymentPluginConfig, type PaymentServiceInterface, Permission, type PipelineNames, type PluginContext, Product, ProductAttribute, ProductCategory, ProductTax, type PublicThemeSettingsPayload, type QueuePluginConfig, type QueueService, type RenderEmailOptions, type RenderedEmail, type S3StoragePluginConfig, Seo, type SeoLike, type SeoMetadataOverrides, type SmsJobPayload, type SmsPluginConfig, type SmsProviderChoice, type SmsProviderId, type SmsServiceConfig, type SmsServiceInterface, StorageService, Tag, Tax, TemplateContext, User, UserGroup, Wishlist, WishlistItem, ZIP_MIME_TYPES, allowRateLimit, analyticsPlugin, assertCaptchaOk, buildCaptchaPublicConfig, cachePlugin, captchaPlugin, cn, countRecentOtpSends, createCmsApp, createDataSourceManager, createOtpChallenge, emailPlugin, emailTemplates, erpPlugin, fetchSeoBySlug, formatDate, formatDateOnly, formatDateTime, generateNumericOtp, generateSlug, hashOtpCode, isZipMedia, joinRecipientsForSend, linkUnclaimedContactToUser, llmPlugin, loadPublicThemeSettings, localStoragePlugin, mergeSeoBySlug, normalizePhoneE164, parseEmailRecipientsFromConfig, paymentPlugin, queueEmail, queueErp, queueErpCreateContactIfEnabled, queueErpPaidOrderForOrderId, queueOrderPlacedEmails, queuePlugin, queueSms, rateLimitCheckoutPost, rateLimitKeyForApiRequest, rateLimitPublicApiIfNeeded, registerEmailQueueProcessor, registerErpQueueProcessor, registerSmsQueueProcessor, relativePathFromMediaParentId, renderEmail, renderLayout, resolvePublicMetadata, s3StoragePlugin, sanitizeMediaFolderPath, sanitizeStorageSegment, seedDefaultAdmin, sendOrderPlacedEmailsAfterConfirmation, serializeEmailRecipients, shouldRateLimitPublicWrite, smsPlugin, truncateText, validateSlug, verifyAndConsumeOtpChallenge, verifyOtpCodeHash };
+export { Address, type AnalyticsPluginConfig, Attribute, Blog, Brand, CMS_ENTITY_MAP, type CachePluginConfig, type CacheService, type CaptchaProviderId, type CaptchaPublicConfig, CaptchaService, type CaptchaVerifyResult, Cart, CartItem, Category, ChatConversation, ChatMessage, type CmsApp, type CmsPlugin, Collection, Comment, CompanyDetails, Config, Contact, type CreateCmsAppOptions, type DataSourceManager, type ERPPluginConfig, type ERPPluginInstance, ERPSubmissionService, type EmailData, type EmailJobPayload, type EmailPluginConfig, EmailService, type EmailServiceInterface, EmailTemplateName, EmailTemplateResult, EntityMap$2 as EntityMap, type ErpContactSyncInput, type ErpCreateContactPayload, type ErpJobPayload, type ErpPaidOrderDataSource, type ErpPaidOrderEntityMap, type ExtraPublicWriteRule, Form, FormField, FormSubmission, KnowledgeBaseChunk, KnowledgeBaseDocument, LlmAgent, type LlmAgentOptions, type LlmChatOptions, type LlmEmbeddingProvider, type LlmMessage, type LlmPluginConfig, LlmService, type LlmServiceEmbedOptions, type LlmServiceInterface, type LocalStoragePluginConfig, type Logger, Media, MessageTemplate, Order, OrderItem, type OrderPlacedEmailPayload, OrderPlacedLineItem, OtpChallenge, type OtpChannel, type OtpPurpose, Page, PasswordResetToken, Payment, type PaymentIntent, type PaymentPluginConfig, type PaymentServiceInterface, Permission, type PipelineNames, type PluginContext, Product, ProductAttribute, ProductCategory, ProductTax, type PublicThemeSettingsPayload, type QueuePluginConfig, type QueueService, type RenderEmailOptions, type RenderedEmail, type S3StoragePluginConfig, Seo, type SeoLike, type SeoMetadataOverrides, type SmsJobPayload, type SmsPluginConfig, type SmsProviderChoice, type SmsProviderId, type SmsServiceConfig, type SmsServiceInterface, StorageService, Tag, Tax, TemplateContext, User, UserGroup, Wishlist, WishlistItem, ZIP_MIME_TYPES, allowRateLimit, analyticsPlugin, assertCaptchaOk, buildCaptchaPublicConfig, cachePlugin, captchaPlugin, cn, countRecentOtpSends, createCmsApp, createDataSourceManager, createOtpChallenge, emailPlugin, emailTemplates, erpPlugin, fetchSeoBySlug, formatDate, formatDateOnly, formatDateTime, generateNumericOtp, generateSlug, hashOtpCode, isZipMedia, joinRecipientsForSend, linkUnclaimedContactToUser, llmAgentToChatAgentOptions, llmPlugin, loadPublicThemeSettings, localStoragePlugin, mergeSeoBySlug, normalizePhoneE164, parseEmailRecipientsFromConfig, parseHfInferenceEmbeddingBody, paymentPlugin, queueEmail, queueErp, queueErpCreateContactIfEnabled, queueErpPaidOrderForOrderId, queueOrderPlacedEmails, queuePlugin, queueSms, rateLimitCheckoutPost, rateLimitKeyForApiRequest, rateLimitPublicApiIfNeeded, registerEmailQueueProcessor, registerErpQueueProcessor, registerSmsQueueProcessor, relativePathFromMediaParentId, renderEmail, renderLayout, resolvePublicMetadata, s3StoragePlugin, sanitizeMediaFolderPath, sanitizeStorageSegment, seedDefaultAdmin, sendOrderPlacedEmailsAfterConfirmation, serializeEmailRecipients, shouldRateLimitPublicWrite, smsPlugin, truncateText, validateSlug, verifyAndConsumeOtpChallenge, verifyOtpCodeHash };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CompanyDetails, T as TemplateContext, E as EmailTemplateResult, a as EmailTemplateName, O as OrderPlacedLineItem, S as StorageService, b as EntityMap$2 } from './index-GMn7-9PX.js';
-export { A as AnalyticsHandlerConfig, c as AuthHandlersConfig, B as BlogBySlugConfig, d as ChangePasswordConfig, e as CmsApiHandlerConfig, f as CmsGetter, g as CrudHandlerOptions, D as DashboardStatsConfig, h as EcommerceAnalyticsConfig, F as ForgotPasswordConfig, i as FormBySlugConfig, G as GetPublicSettingsGroupConfig, j as GetPublicSettingsGroupDataSource, I as InviteAcceptConfig, k as SetPasswordConfig, l as SettingsApiConfig, m as SocialLinkItem, n as StorefrontApiConfig, o as StorefrontOtpFlags, U as UploadHandlerConfig, p as UserAuthApiConfig, q as UserAvatarConfig, r as UserProfileConfig, s as UsersApiConfig, t as createAnalyticsHandlers, u as createBlogBySlugHandler, v as createChangePasswordHandler, w as createCmsApiHandler, x as createCrudByIdHandler, y as createCrudHandler, z as createDashboardStatsHandler, H as createEcommerceAnalyticsHandler, J as createForgotPasswordHandler, K as createFormBySlugHandler, L as createInviteAcceptHandler, M as createMediaZipExtractHandler, N as createSetPasswordHandler, P as createSettingsApiHandlers, Q as createStorefrontApiHandler, R as createUploadHandler, V as createUserAuthApiRouter, W as createUserAvatarHandler, X as createUserProfileHandler, Y as createUsersApiHandlers, Z as getCompanyDetailsFromSettings, _ as getPublicSettingsGroup, $ as mergeEmailLayoutCompanyDetails } from './index-GMn7-9PX.js';
+import { C as CompanyDetails, T as TemplateContext, E as EmailTemplateResult, a as EmailTemplateName, O as OrderPlacedLineItem, S as StorageService, b as EntityMap$2 } from './index-Cnwh7B3r.js';
+export { A as AnalyticsHandlerConfig, c as AuthHandlersConfig, B as BlogBySlugConfig, d as ChangePasswordConfig, e as ChatPublicConfig, f as CmsApiHandlerConfig, g as CmsGetter, h as CrudHandlerOptions, D as DashboardStatsConfig, i as EcommerceAnalyticsConfig, F as ForgotPasswordConfig, j as FormBySlugConfig, G as GetPublicSettingsGroupConfig, k as GetPublicSettingsGroupDataSource, I as InviteAcceptConfig, L as LlmAgentKnowledgeApiConfig, l as LlmAgentValidationRulesJson, P as ParsedLlmAgentValidation, m as SetPasswordConfig, n as SettingsApiConfig, o as SocialLinkItem, p as StorefrontApiConfig, q as StorefrontOtpFlags, U as UploadHandlerConfig, r as UserAuthApiConfig, s as UserAvatarConfig, t as UserProfileConfig, u as UsersApiConfig, v as createAnalyticsHandlers, w as createBlogBySlugHandler, x as createChangePasswordHandler, y as createCmsApiHandler, z as createCrudByIdHandler, H as createCrudHandler, J as createDashboardStatsHandler, K as createEcommerceAnalyticsHandler, M as createForgotPasswordHandler, N as createFormBySlugHandler, Q as createInviteAcceptHandler, R as createLlmAgentKnowledgeHandlers, V as createMediaZipExtractHandler, W as createSetPasswordHandler, X as createSettingsApiHandlers, Y as createStorefrontApiHandler, Z as createUploadHandler, _ as createUserAuthApiRouter, $ as createUserAvatarHandler, a0 as createUserProfileHandler, a1 as createUsersApiHandlers, a2 as getCompanyDetailsFromSettings, a3 as getPublicSettingsGroup, a4 as mergeEmailLayoutCompanyDetails, a5 as mergeGuardrailsIntoSystemPrompt, a6 as parseLlmAgentValidationRules, a7 as validateUserMessageAgainstAgentRules, a8 as validateUserMessageAgainstStructuredRules } from './index-Cnwh7B3r.js';
 import { ClassValue } from 'clsx';
 import * as typeorm from 'typeorm';
 import { DataSource, EntityTarget, ObjectLiteral } from 'typeorm';
@@ -500,7 +500,23 @@ interface LlmMessage {
     role: 'user' | 'assistant' | 'system';
     content: string;
 }
+/** Passed to {@link LlmService.chat} / {@link LlmService.streamChat}; only `model`, `temperature`, and `max_tokens` are sent to the gateway. */
 interface LlmChatOptions {
+    systemPrompt?: string;
+    userPrompt?: string;
+    history?: LlmMessage[];
+    context?: string;
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+}
+/** Options for {@link LlmService.chatAgent} / {@link LlmService.streamChatAgent}: composes system + context + history + user into chat messages. */
+interface LlmAgentOptions {
+    systemPrompt?: string;
+    userPrompt: string;
+    history?: LlmMessage[];
+    /** RAG or other material; merged into the system message when set. */
+    context?: string;
     model?: string;
     temperature?: number;
     max_tokens?: number;
@@ -510,28 +526,85 @@ interface LlmServiceInterface {
         content: string;
     }>;
     streamChat(messages: LlmMessage[], options?: LlmChatOptions): AsyncIterable<string>;
-    /** OpenAI-compatible embeddings; returns [] if gateway does not support /v1/embeddings */
+    chatAgent(options: LlmAgentOptions): Promise<{
+        content: string;
+    }>;
+    streamChatAgent(options: LlmAgentOptions): AsyncIterable<string>;
+    /**
+     * Embeddings for RAG / knowledge base. Wire format depends on {@link LlmServiceEmbedOptions}:
+     * OpenAI `{base}/v1/embeddings`, or Hugging Face via `@huggingface/inference` (Hub-routed feature extraction) with legacy HTTP fallback.
+     */
     embed?(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
 }
+declare function parseHfInferenceEmbeddingBody(data: unknown): number[] | null;
+type LlmEmbeddingProvider = 'openai' | 'huggingface';
+interface LlmServiceEmbedOptions {
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Legacy manual HTTP base when the Inference SDK path fails; default `https://router.huggingface.co/v1` (router host is normalized to `…/hf-inference`). */
+    hfInferenceBaseUrl?: string;
+    /** Token for embedding calls; defaults to chat `apiKey`. */
+    embeddingApiKey?: string;
+    /**
+     * Default `model` for `POST …/v1/chat/completions` when the caller omits `model`.
+     * Set via plugin / CMS `LLM_CHAT_MODEL` or env `LLM_CHAT_MODEL`.
+     * If unset, the library picks a fallback from `LLM_GATEWAY_URL` (HF router vs OpenRouter-style).
+     */
+    defaultChatModel?: string;
+}
+/**
+ * Set `LLM_DEBUG=1` (or `true` / `yes`) to log composed chat payloads.
+ * Set `LLM_EMBED_DEBUG=1` for per-request embedding logs (verbose with many chunks).
+ * Set `LLM_CHAT_MODEL` for the default chat model when agents/requests omit `model` (gateway-specific id).
+ * If unset, fallback is chosen from `LLM_GATEWAY_URL` (HF vs other).
+ */
 declare class LlmService implements LlmServiceInterface {
+    private static embedHttpErrorLogged;
+    private static embedShapeErrorLogged;
+    private static embedSuccessLogged;
+    private static hfDimensionMismatchWarned;
+    private static hfInferenceSdkErrorLogged;
     private readonly baseURL;
     private readonly apiKey;
     private readonly defaultEmbeddingModel?;
-    private static embedWarned;
-    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string | undefined);
+    private readonly embeddingProvider;
+    private readonly hfInferenceBaseURL;
+    private readonly embeddingApiKey;
+    private readonly defaultChatModel;
+    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string, embedOpts?: LlmServiceEmbedOptions);
+    private resolveChatModel;
     private get base();
     private get url();
-    /**
-     * OpenAI-compatible embeddings. Returns [] if endpoint not available or unexpected response.
-     * Server must implement: POST /v1/embeddings
-     * Body: { model: string, input: string }
-     * Response: { data: [ { embedding: number[] } ] } or { embedding: number[] }
-     */
+    private llmDebugEnabled;
+    /** Per-request embedding logs (noisy with many chunks). Set `LLM_EMBED_DEBUG=1`. */
+    private embedDebugEnabled;
+    private logAgentComposition;
+    private logChatCompletionsRequest;
     embed(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
+    /**
+     * POST `{ url }` with OpenAI-style `{ model, input }` and Bearer token; parses `{ data:[{embedding}] }`.
+     */
+    private fetchOpenAiShapeEmbeddings;
+    /**
+     * Hugging Face–recommended path: Hub resolves a provider that supports `feature-extraction` for the model.
+     */
+    private embedViaHuggingfaceInferenceSdk;
+    /** Base URL for legacy `…/pipeline/…` and `…/models/{model}` tries (HF router only). */
+    private hfLegacyInferenceBase;
+    /**
+     * Hugging Face embeddings: `@huggingface/inference` (Hub-routed feature extraction), then
+     * legacy direct `hf-inference` HTTP tries. Note: `https://router.huggingface.co/v1/embeddings` is not
+     * offered for embeddings (OpenAI-compatible `/v1` on HF is chat-only).
+     */
+    private embedHuggingFaceInference;
+    private buildAgentMessages;
+    chatAgent(options: LlmAgentOptions): Promise<{
+        content: string;
+    }>;
+    streamChatAgent(options: LlmAgentOptions): AsyncIterable<string>;
     chat(messages: LlmMessage[], options?: LlmChatOptions): Promise<{
         content: string;
     }>;
@@ -541,8 +614,19 @@ declare class LlmService implements LlmServiceInterface {
 interface LlmPluginConfig {
     baseURL?: string;
     apiKey?: string;
-    /** Default model for embed(); also from env EMBEDDING_MODEL (e.g. for Qwen use your server's embedding model name). */
+    /** Default chat model when agents omit `model` (`POST /v1/chat/completions`). Env: `LLM_CHAT_MODEL`. If unset, inferred from `LLM_GATEWAY_URL` (HF vs OpenRouter-style default). */
+    defaultChatModel?: string;
+    /** Default model for embed(); also from env EMBEDDING_MODEL. */
     embeddingModel?: string;
+    /**
+     * `openai` (default): `POST {LLM_GATEWAY_URL}/v1/embeddings`.
+     * `huggingface`: `@huggingface/inference` feature extraction (Hub-routed), with legacy `…/hf-inference/…` HTTP fallback. Env: `EMBEDDING_PROVIDER=huggingface`.
+     */
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Legacy HTTP base if the SDK path fails; default `https://router.huggingface.co/v1` (router hosts map to `…/hf-inference`). Env: `HF_INFERENCE_URL`. */
+    hfInferenceBaseUrl?: string;
+    /** Optional; defaults to `apiKey`. Env: `EMBEDDING_API_KEY`. */
+    embeddingApiKey?: string;
 }
 declare function llmPlugin(config?: LlmPluginConfig): CmsPlugin<LlmService | undefined>;
 
@@ -1415,7 +1499,34 @@ declare class Wishlist {
     items: WishlistItem[];
 }
 
+declare class LlmAgent {
+    id: number;
+    name: string;
+    /** Stable key for API / widgets (e.g. `support`, `sales`). */
+    slug: string;
+    /** Passed as `systemPrompt` to `LlmService.chatAgent`. */
+    systemInstruction: string;
+    model: string | null;
+    temperature: number | null;
+    maxTokens: number | null;
+    /**
+     * Rules string: plain prose → appended to system prompt as output guardrails; JSON → see `parseLlmAgentValidationRules` in cms-handlers
+     * (structural checks + optional `guardrails` / `outputRules` / `outputInstructions` for the model).
+     */
+    validationRules: string | null;
+    enabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+    deleted: boolean;
+    createdBy: number | null;
+    updatedBy: number | null;
+    deletedBy: number | null;
+}
+/** Partial {@link LlmAgentOptions} for merging with `userPrompt` / `history` / `context`. */
+declare function llmAgentToChatAgentOptions(agent: LlmAgent): Pick<LlmAgentOptions, 'systemPrompt' | 'model' | 'temperature' | 'max_tokens'>;
+
 /** Map API resource segment (e.g. "blogs", "form_submissions") to entity. Used by CRUD handler. */
 declare const CMS_ENTITY_MAP: Record<string, EntityTarget<typeorm.ObjectLiteral>>;
 
-export { Address, type AnalyticsPluginConfig, Attribute, Blog, Brand, CMS_ENTITY_MAP, type CachePluginConfig, type CacheService, type CaptchaProviderId, type CaptchaPublicConfig, CaptchaService, type CaptchaVerifyResult, Cart, CartItem, Category, ChatConversation, ChatMessage, type CmsApp, type CmsPlugin, Collection, Comment, CompanyDetails, Config, Contact, type CreateCmsAppOptions, type DataSourceManager, type ERPPluginConfig, type ERPPluginInstance, ERPSubmissionService, type EmailData, type EmailJobPayload, type EmailPluginConfig, EmailService, type EmailServiceInterface, EmailTemplateName, EmailTemplateResult, EntityMap$2 as EntityMap, type ErpContactSyncInput, type ErpCreateContactPayload, type ErpJobPayload, type ErpPaidOrderDataSource, type ErpPaidOrderEntityMap, type ExtraPublicWriteRule, Form, FormField, FormSubmission, KnowledgeBaseChunk, KnowledgeBaseDocument, type LlmChatOptions, type LlmMessage, type LlmPluginConfig, LlmService, type LlmServiceInterface, type LocalStoragePluginConfig, type Logger, Media, MessageTemplate, Order, OrderItem, type OrderPlacedEmailPayload, OrderPlacedLineItem, OtpChallenge, type OtpChannel, type OtpPurpose, Page, PasswordResetToken, Payment, type PaymentIntent, type PaymentPluginConfig, type PaymentServiceInterface, Permission, type PipelineNames, type PluginContext, Product, ProductAttribute, ProductCategory, ProductTax, type PublicThemeSettingsPayload, type QueuePluginConfig, type QueueService, type RenderEmailOptions, type RenderedEmail, type S3StoragePluginConfig, Seo, type SeoLike, type SeoMetadataOverrides, type SmsJobPayload, type SmsPluginConfig, type SmsProviderChoice, type SmsProviderId, type SmsServiceConfig, type SmsServiceInterface, StorageService, Tag, Tax, TemplateContext, User, UserGroup, Wishlist, WishlistItem, ZIP_MIME_TYPES, allowRateLimit, analyticsPlugin, assertCaptchaOk, buildCaptchaPublicConfig, cachePlugin, captchaPlugin, cn, countRecentOtpSends, createCmsApp, createDataSourceManager, createOtpChallenge, emailPlugin, emailTemplates, erpPlugin, fetchSeoBySlug, formatDate, formatDateOnly, formatDateTime, generateNumericOtp, generateSlug, hashOtpCode, isZipMedia, joinRecipientsForSend, linkUnclaimedContactToUser, llmPlugin, loadPublicThemeSettings, localStoragePlugin, mergeSeoBySlug, normalizePhoneE164, parseEmailRecipientsFromConfig, paymentPlugin, queueEmail, queueErp, queueErpCreateContactIfEnabled, queueErpPaidOrderForOrderId, queueOrderPlacedEmails, queuePlugin, queueSms, rateLimitCheckoutPost, rateLimitKeyForApiRequest, rateLimitPublicApiIfNeeded, registerEmailQueueProcessor, registerErpQueueProcessor, registerSmsQueueProcessor, relativePathFromMediaParentId, renderEmail, renderLayout, resolvePublicMetadata, s3StoragePlugin, sanitizeMediaFolderPath, sanitizeStorageSegment, seedDefaultAdmin, sendOrderPlacedEmailsAfterConfirmation, serializeEmailRecipients, shouldRateLimitPublicWrite, smsPlugin, truncateText, validateSlug, verifyAndConsumeOtpChallenge, verifyOtpCodeHash };
+export { Address, type AnalyticsPluginConfig, Attribute, Blog, Brand, CMS_ENTITY_MAP, type CachePluginConfig, type CacheService, type CaptchaProviderId, type CaptchaPublicConfig, CaptchaService, type CaptchaVerifyResult, Cart, CartItem, Category, ChatConversation, ChatMessage, type CmsApp, type CmsPlugin, Collection, Comment, CompanyDetails, Config, Contact, type CreateCmsAppOptions, type DataSourceManager, type ERPPluginConfig, type ERPPluginInstance, ERPSubmissionService, type EmailData, type EmailJobPayload, type EmailPluginConfig, EmailService, type EmailServiceInterface, EmailTemplateName, EmailTemplateResult, EntityMap$2 as EntityMap, type ErpContactSyncInput, type ErpCreateContactPayload, type ErpJobPayload, type ErpPaidOrderDataSource, type ErpPaidOrderEntityMap, type ExtraPublicWriteRule, Form, FormField, FormSubmission, KnowledgeBaseChunk, KnowledgeBaseDocument, LlmAgent, type LlmAgentOptions, type LlmChatOptions, type LlmEmbeddingProvider, type LlmMessage, type LlmPluginConfig, LlmService, type LlmServiceEmbedOptions, type LlmServiceInterface, type LocalStoragePluginConfig, type Logger, Media, MessageTemplate, Order, OrderItem, type OrderPlacedEmailPayload, OrderPlacedLineItem, OtpChallenge, type OtpChannel, type OtpPurpose, Page, PasswordResetToken, Payment, type PaymentIntent, type PaymentPluginConfig, type PaymentServiceInterface, Permission, type PipelineNames, type PluginContext, Product, ProductAttribute, ProductCategory, ProductTax, type PublicThemeSettingsPayload, type QueuePluginConfig, type QueueService, type RenderEmailOptions, type RenderedEmail, type S3StoragePluginConfig, Seo, type SeoLike, type SeoMetadataOverrides, type SmsJobPayload, type SmsPluginConfig, type SmsProviderChoice, type SmsProviderId, type SmsServiceConfig, type SmsServiceInterface, StorageService, Tag, Tax, TemplateContext, User, UserGroup, Wishlist, WishlistItem, ZIP_MIME_TYPES, allowRateLimit, analyticsPlugin, assertCaptchaOk, buildCaptchaPublicConfig, cachePlugin, captchaPlugin, cn, countRecentOtpSends, createCmsApp, createDataSourceManager, createOtpChallenge, emailPlugin, emailTemplates, erpPlugin, fetchSeoBySlug, formatDate, formatDateOnly, formatDateTime, generateNumericOtp, generateSlug, hashOtpCode, isZipMedia, joinRecipientsForSend, linkUnclaimedContactToUser, llmAgentToChatAgentOptions, llmPlugin, loadPublicThemeSettings, localStoragePlugin, mergeSeoBySlug, normalizePhoneE164, parseEmailRecipientsFromConfig, parseHfInferenceEmbeddingBody, paymentPlugin, queueEmail, queueErp, queueErpCreateContactIfEnabled, queueErpPaidOrderForOrderId, queueOrderPlacedEmails, queuePlugin, queueSms, rateLimitCheckoutPost, rateLimitKeyForApiRequest, rateLimitPublicApiIfNeeded, registerEmailQueueProcessor, registerErpQueueProcessor, registerSmsQueueProcessor, relativePathFromMediaParentId, renderEmail, renderLayout, resolvePublicMetadata, s3StoragePlugin, sanitizeMediaFolderPath, sanitizeStorageSegment, seedDefaultAdmin, sendOrderPlacedEmailsAfterConfirmation, serializeEmailRecipients, shouldRateLimitPublicWrite, smsPlugin, truncateText, validateSlug, verifyAndConsumeOtpChallenge, verifyOtpCodeHash };