@infuro/cms-core 1.0.19 → 1.0.20

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-DGtM2Gsk.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-DGtM2Gsk.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,62 @@ 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 Inference `…/models/{model}`.
+     */
     embed?(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
 }
+/**
+ * Normalize Hugging Face Inference feature-extraction response to a single `number[]`.
+ */
+declare function parseHfInferenceEmbeddingBody(data: unknown): number[] | null;
+type LlmEmbeddingProvider = 'openai' | 'huggingface';
+interface LlmServiceEmbedOptions {
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Default `https://api-inference.huggingface.co` when using Hugging Face Inference. */
+    hfInferenceBaseUrl?: string;
+    /** Token for embedding calls; defaults to chat `apiKey`. */
+    embeddingApiKey?: 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).
+ */
 declare class LlmService implements LlmServiceInterface {
+    private static embedHttpErrorLogged;
+    private static embedShapeErrorLogged;
+    private static embedSuccessLogged;
+    private static hfDimensionMismatchWarned;
     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;
+    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string, embedOpts?: LlmServiceEmbedOptions);
     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[]>;
+    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 +591,17 @@ 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 model for embed(); also from env EMBEDDING_MODEL. */
     embeddingModel?: string;
+    /**
+     * `openai` (default): `POST {LLM_GATEWAY_URL}/v1/embeddings`.
+     * `huggingface`: `POST {HF_INFERENCE_URL}/models/{EMBEDDING_MODEL}` (Inference API). Env: `EMBEDDING_PROVIDER=huggingface`.
+     */
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Hugging Face Inference API base; default `https://api-inference.huggingface.co`. 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 +1474,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--GBYw5JE.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--GBYw5JE.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,62 @@ 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 Inference `…/models/{model}`.
+     */
     embed?(text: string, options?: {
         model?: string;
     }): Promise<number[]>;
 }
+/**
+ * Normalize Hugging Face Inference feature-extraction response to a single `number[]`.
+ */
+declare function parseHfInferenceEmbeddingBody(data: unknown): number[] | null;
+type LlmEmbeddingProvider = 'openai' | 'huggingface';
+interface LlmServiceEmbedOptions {
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Default `https://api-inference.huggingface.co` when using Hugging Face Inference. */
+    hfInferenceBaseUrl?: string;
+    /** Token for embedding calls; defaults to chat `apiKey`. */
+    embeddingApiKey?: 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).
+ */
 declare class LlmService implements LlmServiceInterface {
+    private static embedHttpErrorLogged;
+    private static embedShapeErrorLogged;
+    private static embedSuccessLogged;
+    private static hfDimensionMismatchWarned;
     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;
+    constructor(baseURL: string, apiKey: string, defaultEmbeddingModel?: string, embedOpts?: LlmServiceEmbedOptions);
     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[]>;
+    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 +591,17 @@ 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 model for embed(); also from env EMBEDDING_MODEL. */
     embeddingModel?: string;
+    /**
+     * `openai` (default): `POST {LLM_GATEWAY_URL}/v1/embeddings`.
+     * `huggingface`: `POST {HF_INFERENCE_URL}/models/{EMBEDDING_MODEL}` (Inference API). Env: `EMBEDDING_PROVIDER=huggingface`.
+     */
+    embeddingProvider?: LlmEmbeddingProvider;
+    /** Hugging Face Inference API base; default `https://api-inference.huggingface.co`. 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 +1474,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 };