@diegoaltoworks/chatter 0.55.0 → 0.57.0

package/dist/channels/whatsapp/index.mjs

@@ -676,6 +676,18 @@ async function answerOnce({
   }
   return completeOnce({ client, system, messages, temperature, model });
 }
+async function applyTransformReply(transformReply, input, logger) {
+  if (!transformReply) return input.text;
+  try {
+    return await transformReply(input);
+  } catch (error) {
+    logger?.error(
+      `transformReply threw for channel "${input.channel}"; sending the original reply`,
+      error
+    );
+    return input.text;
+  }
+}
 
 // src/core/buckets.ts
 function defaultBuckets(mode) {
@@ -725,14 +737,35 @@ async function prepareChat({
   messages,
   personaLayer,
   channelHint,
-  buckets
+  buckets,
+  sender,
+  rewriteQuery,
+  rerankContext,
+  logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
   if (!lastUserMsg) {
     throw new Error("no user message found in conversation");
   }
   const { topK, label } = MODE_SETTINGS[mode];
-  const ctx = await store.query(lastUserMsg.content, topK, buckets ?? defaultBuckets(mode));
+  let query = lastUserMsg.content;
+  if (rewriteQuery) {
+    try {
+      const rewritten = await rewriteQuery({ query, mode, sender });
+      if (typeof rewritten === "string" && rewritten.trim()) query = rewritten;
+    } catch (error) {
+      logger?.error("rewriteQuery threw; falling back to the original query", error);
+    }
+  }
+  let ctx = await store.query(query, topK, buckets ?? defaultBuckets(mode));
+  if (rerankContext) {
+    try {
+      const reranked = await rerankContext({ query, chunks: ctx });
+      if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
+    } catch (error) {
+      logger?.error("rerankContext threw; falling back to the original chunks", error);
+    }
+  }
   const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
   const hint = channelHint?.trim();
   const system = [
@@ -809,9 +842,13 @@ function createInboundPipeline(deps, config) {
       messages,
       personaLayer,
       channelHint: config.channelHint,
-      buckets
+      buckets,
+      sender,
+      rewriteQuery: config.rewriteQuery,
+      rerankContext: config.rerankContext,
+      logger: config.logger
     });
-    const { content } = await answerOnce({
+    const { content: produced } = await answerOnce({
       answerFn: config.answerFn,
       client: deps.client,
       system,
@@ -821,6 +858,11 @@ function createInboundPipeline(deps, config) {
       conversationId,
       model: config.model
     });
+    const content = await applyTransformReply(
+      config.transformReply,
+      { channel: config.channel ?? "channel", sender, conversationId, text: produced },
+      config.logger
+    );
     if (!content) {
       return { action: "ignore" };
     }
@@ -928,8 +970,12 @@ function createWhatsAppInboundHandler(config) {
   const pipeline = createInboundPipeline(
     { client: config.client, store: config.store, prompts: config.prompts },
     {
+      channel: "whatsapp",
       answerFn: config.answerFn,
       bucketsFor: config.bucketsFor,
+      rewriteQuery: config.rewriteQuery,
+      rerankContext: config.rerankContext,
+      transformReply: config.transformReply,
       model: config.model,
       channelHint: config.channelHint,
       personaResolver: personaResolver ? ({ sender, text }) => personaResolver({ senderPhone: sender, text }) : void 0,
@@ -941,7 +987,8 @@ function createWhatsAppInboundHandler(config) {
       unmuteReply: config.unmuteReply,
       dmRateLimit: config.dmRateLimit,
       groupRateLimit: config.groupRateLimit,
-      now: config.now
+      now: config.now,
+      logger
     }
   );
   return async function handleWhatsAppMessage(event) {

package/dist/core/answer.d.ts

@@ -13,6 +13,7 @@
  * exactly what it has always been.
  */
 import type OpenAI from "openai";
+import type { Logger } from "./logger";
 import type { PipelineMessage, PipelineMode } from "./pipeline";
 /** Token accounting in the OpenAI wire shape */
 export interface AnswerUsage {
@@ -66,6 +67,36 @@ export declare function answerOnce({ answerFn, client, system, messages, mode, s
     content: string;
     usage: AnswerUsage;
 }>;
+/** What a `transformReply` hook receives: the produced answer plus who/where it's going. */
+export interface TransformReplyInput {
+    /**
+     * Identifies the surface delivering this reply — a channel's own name
+     * (e.g. "whatsapp", "telegram") or a fixed identifier for an HTTP surface
+     * (e.g. "widget-public", "openai-compat-private").
+     */
+    channel: string;
+    sender?: string;
+    conversationId?: string;
+    text: string;
+}
+/**
+ * Modifies or vetoes an already-produced reply, after `answerFn`/the built-in
+ * completion and guardrails have run. A string result replaces the reply;
+ * `null` vetoes it — treated the same as an empty answer by every call site
+ * (nothing delivered; the channel pipeline never records an assistant turn
+ * for it, though the user's own turn — already appended before answering —
+ * stays recorded).
+ *
+ * Non-streaming surfaces only: a streaming response is delivered incrementally
+ * as it's produced, before a final answer exists to transform.
+ */
+export type TransformReply = (input: TransformReplyInput) => string | null | Promise<string | null>;
+/**
+ * Runs `transformReply` if configured. A throw/rejection is logged and the
+ * ORIGINAL text is returned — the delivery invariant: a bug in a plugin hook
+ * must never silently swallow an answer the model already produced.
+ */
+export declare function applyTransformReply(transformReply: TransformReply | undefined, input: TransformReplyInput, logger?: Pick<Logger, "error">): Promise<string | null>;
 /**
  * Stream an answer. A brain that returns a plain string cannot stream, so its
  * answer degrades to a single chunk followed by the stream's normal end —

package/dist/core/answer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAaxC"}
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEpG;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,KAAK,EAAE,mBAAmB,EAC1B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAaxC"}

package/dist/core/pipeline.d.ts

@@ -8,6 +8,7 @@
  * then ask for the answer via `answerOnce`/`answerStream` (see ./answer.ts)
  * so a caller-supplied brain is honoured.
  */
+import type { Logger } from "./logger";
 import type { PromptLoader } from "./prompts";
 import type { VectorStore } from "./retrieval";
 export type PipelineMode = "public" | "private";
@@ -23,6 +24,42 @@ export interface PreparedChat {
     /** Raw retrieved chunks, before being folded into `system` — for callers that log or display RAG context alongside the answer */
     context: string[];
 }
+/** What `rewriteQuery` sees for a turn. */
+export interface RewriteQueryArgs {
+    /** The latest user message's content — what retrieval would search on unmodified. */
+    query: string;
+    mode: PipelineMode;
+    /** Caller identity, where the surface has one. Absent on anonymous surfaces. */
+    sender?: string;
+}
+/**
+ * Rewrites the retrieval query before it reaches the vector store — e.g.
+ * expanding an ambiguous follow-up ("what about the second one?") into
+ * something embeddable on its own. Return the query unchanged to opt out for
+ * a given turn. A throw/rejection is caught by `prepareChat`, which falls
+ * back to the original query — a broken rewrite must never break retrieval.
+ */
+export type RewriteQuery = (ctx: RewriteQueryArgs) => string | Promise<string>;
+/** What `rerankContext` sees for a turn. */
+export interface RerankContextArgs {
+    /** The query retrieval actually ran with — post-`rewriteQuery`, if configured. */
+    query: string;
+    /** Chunks `store.query` returned, in its own order. */
+    chunks: string[];
+}
+/**
+ * Reorders, filters, or otherwise post-processes the chunks retrieval
+ * returned before they're folded into the system prompt. A throw/rejection
+ * is caught by `prepareChat`, which falls back to the original chunks in
+ * their original order — a broken reranker must never break retrieval.
+ *
+ * This is NOT the seam for access control. Because a failure falls back to
+ * the unfiltered chunks, a hook that drops chunks a sender shouldn't see
+ * would silently un-drop them on its own error — the opposite of safe
+ * failure. Scope decisions belong in `bucketsFor` (see ./buckets), which
+ * fails closed by design; use this hook for relevance/ordering only.
+ */
+export type RerankContext = (ctx: RerankContextArgs) => string[] | Promise<string[]>;
 /**
  * Run retrieval for the latest user message and assemble the system prompt.
  *
@@ -40,9 +77,15 @@ export interface PreparedChat {
  * `resolveBuckets` (see ./buckets) first, which is where the anonymous
  * ceiling is enforced.
  *
+ * `rewriteQuery` and `rerankContext` shape retrieval itself rather than the
+ * prompt around it: the former runs before `store.query`, the latter after.
+ * Both are optional and fail open — a throw, rejection, or malformed return
+ * value falls back to what retrieval would have done unmodified, so a buggy
+ * hook degrades relevance rather than breaking the chat path.
+ *
  * @throws if the conversation contains no user message
  */
-export declare function prepareChat({ store, prompts, mode, messages, personaLayer, channelHint, buckets, }: {
+export declare function prepareChat({ store, prompts, mode, messages, personaLayer, channelHint, buckets, sender, rewriteQuery, rerankContext, logger, }: {
     store: VectorStore;
     prompts: PromptLoader;
     mode: PipelineMode;
@@ -56,5 +99,13 @@ export declare function prepareChat({ store, prompts, mode, messages, personaLay
      * `["base", mode]`. An empty array retrieves nothing.
      */
     buckets?: string[];
+    /** Caller identity, passed through to `rewriteQuery`. Absent on anonymous surfaces. */
+    sender?: string;
+    /** Rewrites the retrieval query before `store.query` runs — see {@link RewriteQuery}. */
+    rewriteQuery?: RewriteQuery;
+    /** Post-processes retrieved chunks before they're folded into the prompt — see {@link RerankContext}. */
+    rerankContext?: RerankContext;
+    /** Logs a `rewriteQuery`/`rerankContext` throw before falling back. Unset: the failure is silent. */
+    logger?: Pick<Logger, "error">;
 }): Promise<PreparedChat>;
 //# sourceMappingURL=pipeline.d.ts.map

package/dist/core/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,iIAAiI;IACjI,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,EAChC,KAAK,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,OAAO,GACR,EAAE;IACD,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmBxB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,iIAAiI;IACjI,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/E,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAOrF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,EAChC,KAAK,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,OAAO,EACP,MAAM,EACN,YAAY,EACZ,aAAa,EACb,MAAM,GACP,EAAE;IACD,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,yGAAyG;IACzG,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qGAAqG;IACrG,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuCxB"}

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export type { ApiKeyOptions, ApiKeyPayload, VerifyResult } from "./auth";
 export { ApiKeyManager } from "./auth";
 export type { Channel } from "./channels";
 export type { ChatBotConfig, ChatButtonConfig, ChatConfig, ChatMessage, ChatMode, StreamCallbacks, } from "./client";
-export type { AnswerFn, AnswerFnInput, AnswerFnResult, AnswerOptions, AnswerUsage, } from "./core/answer";
-export { answerOnce, answerStream } from "./core/answer";
+export type { AnswerFn, AnswerFnInput, AnswerFnResult, AnswerOptions, AnswerUsage, TransformReply, TransformReplyInput, } from "./core/answer";
+export { answerOnce, answerStream, applyTransformReply } from "./core/answer";
 export type { BucketsFor, BucketsForContext } from "./core/buckets";
 export { defaultBuckets, resolveBuckets } from "./core/buckets";
 export { detectLeakage, guardOutput, scrubOutput } from "./core/guardrails";
@@ -25,7 +25,7 @@ export type { Logger, LogLevel } from "./core/logger";
 export { createConsoleLogger } from "./core/logger";
 export type { NormalizedChatBody } from "./core/messages";
 export { normalizeChatBody, normalizeMessages } from "./core/messages";
-export type { PipelineMessage, PipelineMode, PreparedChat } from "./core/pipeline";
+export type { PipelineMessage, PipelineMode, PreparedChat, RerankContext, RerankContextArgs, RewriteQuery, RewriteQueryArgs, } from "./core/pipeline";
 export { prepareChat } from "./core/pipeline";
 export { PromptLoader } from "./core/prompts";
 export type { VectorStoreOptions } from "./core/retrieval";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -36,6 +36,7 @@ __export(index_exports, {
   VectorStore: () => VectorStore,
   answerOnce: () => answerOnce,
   answerStream: () => answerStream,
+  applyTransformReply: () => applyTransformReply,
   chatBodyLimit: () => chatBodyLimit,
   completeOnce: () => completeOnce,
   completeStream: () => completeStream,
@@ -282,6 +283,18 @@ async function answerOnce({
   }
   return completeOnce({ client, system, messages, temperature, model });
 }
+async function applyTransformReply(transformReply, input, logger) {
+  if (!transformReply) return input.text;
+  try {
+    return await transformReply(input);
+  } catch (error) {
+    logger?.error(
+      `transformReply threw for channel "${input.channel}"; sending the original reply`,
+      error
+    );
+    return input.text;
+  }
+}
 async function* answerStream({
   answerFn,
   client,
@@ -445,14 +458,35 @@ async function prepareChat({
   messages,
   personaLayer,
   channelHint,
-  buckets
+  buckets,
+  sender,
+  rewriteQuery,
+  rerankContext,
+  logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
   if (!lastUserMsg) {
     throw new Error("no user message found in conversation");
   }
   const { topK, label } = MODE_SETTINGS[mode];
-  const ctx = await store.query(lastUserMsg.content, topK, buckets ?? defaultBuckets(mode));
+  let query = lastUserMsg.content;
+  if (rewriteQuery) {
+    try {
+      const rewritten = await rewriteQuery({ query, mode, sender });
+      if (typeof rewritten === "string" && rewritten.trim()) query = rewritten;
+    } catch (error) {
+      logger?.error("rewriteQuery threw; falling back to the original query", error);
+    }
+  }
+  let ctx = await store.query(query, topK, buckets ?? defaultBuckets(mode));
+  if (rerankContext) {
+    try {
+      const reranked = await rerankContext({ query, chunks: ctx });
+      if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
+    } catch (error) {
+      logger?.error("rerankContext threw; falling back to the original chunks", error);
+    }
+  }
   const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
   const hint = channelHint?.trim();
   const system = [
@@ -991,7 +1025,10 @@ async function createMCPServer(config) {
           prompts,
           mode: "public",
           messages: conversationMessages,
-          buckets
+          buckets,
+          rewriteQuery: config.rewriteQuery,
+          rerankContext: config.rerankContext,
+          logger: log
         });
         const result = await answerOnce({
           answerFn: config.answerFn,
@@ -1002,6 +1039,11 @@ async function createMCPServer(config) {
           conversationId: convId,
           model
         });
+        const replyText = await applyTransformReply(
+          config.transformReply,
+          { channel: "mcp-public", conversationId: convId, text: result.content },
+          log
+        );
         const cost = calculateCost(result.usage, config.openai.pricing);
         const duration = Date.now() - startTime;
         await logger.logChatInteraction(
@@ -1009,7 +1051,7 @@ async function createMCPServer(config) {
           convId,
           conversationMessages,
           ctx,
-          result.content,
+          replyText ?? "",
           duration,
           cost
         ).catch((err) => log.error("Logging error:", err));
@@ -1017,7 +1059,7 @@ async function createMCPServer(config) {
           content: [
             {
               type: "text",
-              text: result.content
+              text: replyText ?? ""
             }
           ],
           _meta: {
@@ -1072,7 +1114,10 @@ async function createMCPServer(config) {
           prompts,
           mode: "private",
           messages: conversationMessages,
-          buckets
+          buckets,
+          rewriteQuery: config.rewriteQuery,
+          rerankContext: config.rerankContext,
+          logger: log
         });
         const result = await answerOnce({
           answerFn: config.answerFn,
@@ -1083,6 +1128,11 @@ async function createMCPServer(config) {
           conversationId: convId,
           model
         });
+        const replyText = await applyTransformReply(
+          config.transformReply,
+          { channel: "mcp-private", conversationId: convId, text: result.content },
+          log
+        );
         const cost = calculateCost(result.usage, config.openai.pricing);
         const duration = Date.now() - startTime;
         await logger.logChatInteraction(
@@ -1090,7 +1140,7 @@ async function createMCPServer(config) {
           convId,
           conversationMessages,
           ctx,
-          result.content,
+          replyText ?? "",
           duration,
           cost
         ).catch((err) => log.error("Logging error:", err));
@@ -1098,7 +1148,7 @@ async function createMCPServer(config) {
           content: [
             {
               type: "text",
-              text: result.content
+              text: replyText ?? ""
             }
           ],
           _meta: {
@@ -1542,7 +1592,16 @@ function demoRoutes(deps) {
           return c.json({ error: "no user message found in conversation" }, 400);
         }
         const buckets = await resolveBuckets({ mode: "public", bucketsFor: config.bucketsFor });
-        const { system } = await prepareChat({ store, prompts, mode: "public", messages, buckets });
+        const { system } = await prepareChat({
+          store,
+          prompts,
+          mode: "public",
+          messages,
+          buckets,
+          rewriteQuery: config.rewriteQuery,
+          rerankContext: config.rerankContext,
+          logger
+        });
         const model = config.openai.model || DEFAULT_MODEL;
         const url = new URL(c.req.url);
         const wantsStream3 = url.searchParams.get("stream") === "1";
@@ -1571,7 +1630,12 @@ function demoRoutes(deps) {
           mode: "public",
           model
         });
-        return c.json({ reply: out.content });
+        const reply = await applyTransformReply(
+          config.transformReply,
+          { channel: "widget-demo", text: out.content },
+          logger
+        );
+        return c.json({ reply: reply ?? "" });
       } catch (error) {
         const err = error;
         logger.error("Demo chat error:", err);
@@ -1614,7 +1678,7 @@ function oversizedBodyError(message) {
   return { error: { message, type: "invalid_request_error" } };
 }
 function openaiRoutes(deps) {
-  const { client, store, config, prompts, apiKeyManager } = deps;
+  const { client, store, config, prompts, apiKeyManager, logger } = deps;
   const app = new import_hono2.Hono();
   const { limitPublic, limitPrivate } = createRateLimiter2(config);
   const requirePrivateJWT = createJWTMiddleware(config);
@@ -1656,13 +1720,23 @@ function openaiRoutes(deps) {
       sender: jwtSubject(c),
       bucketsFor: config.bucketsFor
     });
+    const sender = jwtSubject(c) ?? apiKeySubject(c);
     let system;
     try {
-      ({ system } = await prepareChat({ store, prompts, mode, messages, buckets }));
+      ({ system } = await prepareChat({
+        store,
+        prompts,
+        mode,
+        messages,
+        buckets,
+        sender,
+        rewriteQuery: config.rewriteQuery,
+        rerankContext: config.rerankContext,
+        logger
+      }));
     } catch {
       return errorJson(c, 400, "Conversation must contain at least one user message");
     }
-    const sender = jwtSubject(c) ?? apiKeySubject(c);
     const conversationId = clientConversationId(c, body) ?? crypto.randomUUID();
     c.header("x-conversation-id", conversationId);
     const id = `chatcmpl-${crypto.randomUUID()}`;
@@ -1709,13 +1783,18 @@ function openaiRoutes(deps) {
       temperature,
       model: serverModel
     });
+    const reply = await applyTransformReply(
+      config.transformReply,
+      { channel: `openai-compat-${mode}`, sender, conversationId, text: out.content },
+      logger
+    );
     return c.json({
       id,
       object: "chat.completion",
       created,
       model: serverModel,
       choices: [
-        { index: 0, message: { role: "assistant", content: out.content }, finish_reason: "stop" }
+        { index: 0, message: { role: "assistant", content: reply ?? "" }, finish_reason: "stop" }
       ],
       usage: out.usage
     });
@@ -1745,7 +1824,7 @@ function wantsStream(c) {
   return acc.includes("text/event-stream");
 }
 function privateRoutes(deps) {
-  const { client, store, config, prompts } = deps;
+  const { client, store, config, prompts, logger } = deps;
   const app = new import_hono3.Hono();
   const requirePrivateJWT = createJWTMiddleware(config);
   const { limitPrivate } = createRateLimiter2(config);
@@ -1767,7 +1846,17 @@ function privateRoutes(deps) {
     });
     let system;
     try {
-      ({ system } = await prepareChat({ store, prompts, mode: "private", messages, buckets }));
+      ({ system } = await prepareChat({
+        store,
+        prompts,
+        mode: "private",
+        messages,
+        buckets,
+        sender,
+        rewriteQuery: config.rewriteQuery,
+        rerankContext: config.rerankContext,
+        logger
+      }));
     } catch {
       return c.json({ error: "no user message found in conversation" }, 400);
     }
@@ -1800,7 +1889,12 @@ function privateRoutes(deps) {
       sender,
       model
     });
-    return c.json({ reply: out.content });
+    const reply = await applyTransformReply(
+      config.transformReply,
+      { channel: "widget-private", sender, text: out.content },
+      logger
+    );
+    return c.json({ reply: reply ?? "" });
   });
   return app;
 }
@@ -1838,7 +1932,16 @@ function publicRoutes(deps) {
     const buckets = await resolveBuckets({ mode: "public", bucketsFor: config.bucketsFor });
     let system;
     try {
-      ({ system } = await prepareChat({ store, prompts, mode: "public", messages, buckets }));
+      ({ system } = await prepareChat({
+        store,
+        prompts,
+        mode: "public",
+        messages,
+        buckets,
+        rewriteQuery: config.rewriteQuery,
+        rerankContext: config.rerankContext,
+        logger
+      }));
     } catch {
       return c.json({ error: "no user message found in conversation" }, 400);
     }
@@ -1862,7 +1965,12 @@ function publicRoutes(deps) {
       });
     }
     const out = await answerOnce({ answerFn, client, system, messages, mode: "public", model });
-    return c.json({ reply: out.content });
+    const reply = await applyTransformReply(
+      config.transformReply,
+      { channel: "widget-public", text: out.content },
+      logger
+    );
+    return c.json({ reply: reply ?? "" });
   });
   return app;
 }
@@ -2201,6 +2309,7 @@ function createShortener(config, fetchImpl = fetch) {
   VectorStore,
   answerOnce,
   answerStream,
+  applyTransformReply,
   chatBodyLimit,
   completeOnce,
   completeStream,