@tungpastry/pupperfish-framework 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZenLog Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @tungpastry/pupperfish-framework
+
+Headless Pupperfish runtime cho Node/TypeScript host app.
+
+Xem thêm:
+
+- `../../docs/pupperfish-framework.md`
+- `src/contracts.ts`
+- `src/runtime.ts`

package/dist/answer.d.ts

@@ -0,0 +1,15 @@
+import type { PupperfishAiProvider, PupperfishRuntimeConfig } from "./contracts.js";
+import type { PupperfishEvidenceItem, PupperfishImageEvidence, PupperfishMemoryEvidence, PupperfishPlannerMode } from "./types.js";
+export declare function composePupperfishAnswer(params: {
+    aiProvider: PupperfishAiProvider;
+    config: PupperfishRuntimeConfig;
+    query: string;
+    mode: PupperfishPlannerMode;
+    evidence: PupperfishEvidenceItem[];
+    memories: PupperfishMemoryEvidence[];
+    charts: PupperfishImageEvidence[];
+}): Promise<{
+    answer: string;
+    assumptions: string[];
+    confidence: number;
+}>;

package/dist/answer.js

@@ -0,0 +1,86 @@
+function evidenceLine(item) {
+    if (item.kind === "log") {
+        return `- [log:${item.entryUid}] ${item.dateText} ${item.timeText} | ${item.activity} | Outcome: ${item.outcome} | Next: ${item.nextAction ?? "(trống)"}`;
+    }
+    if (item.kind === "summary") {
+        return `- [summary:${item.summaryUid}] ${item.summaryDate} ${item.scope} | ${item.summaryText}`;
+    }
+    if (item.kind === "memory") {
+        return `- [memory:${item.memoryUid}] ${item.memoryType} | ${item.memoryText}`;
+    }
+    return `- [image:${item.imageUid}] ${item.chartLabel} ${item.symbol ?? ""} ${item.timeframe ?? ""}`.trim();
+}
+export async function composePupperfishAnswer(params) {
+    const assumptions = [];
+    const assistantName = params.config.branding.assistantName || "Pupperfish";
+    const productName = params.config.branding.productName || "host app";
+    const language = params.config.answerPolicy?.language ?? "tiếng Việt";
+    if (params.evidence.length < 1) {
+        assumptions.push("Không có bằng chứng khớp mạnh; trả lời theo dữ liệu hạn chế.");
+        return {
+            answer: `Chưa tìm thấy bằng chứng đủ mạnh trong ${productName}. Bạn có thể ghi thêm dữ liệu hoặc cung cấp phạm vi thời gian cụ thể để truy vấn chính xác hơn.`,
+            assumptions,
+            confidence: 0.28,
+        };
+    }
+    const prompt = [
+        `Bạn là ${assistantName} assistant cho ${productName}.`,
+        `Mode: ${params.mode}`,
+        `User query: ${params.query}`,
+        "Yêu cầu:",
+        `1) Trả lời ngắn gọn bằng ${language}.`,
+        "2) Chỉ dùng dữ kiện từ Evidence.",
+        "3) Nếu chưa chắc, nói rõ giả định.",
+        "4) Cuối câu trả lời thêm mục Nguồn: [kind:uid] cách nhau bằng dấu phẩy.",
+        "Evidence:",
+        ...params.evidence.map(evidenceLine),
+    ].join("\n");
+    try {
+        const generated = await params.aiProvider.generateAnswer(prompt);
+        const topScore = params.evidence[0]?.score ?? 0;
+        const confidence = Math.max(0.25, Math.min(0.95, topScore));
+        return {
+            answer: generated.text,
+            assumptions,
+            confidence,
+        };
+    }
+    catch {
+        assumptions.push("Dùng fallback composer do generate service không phản hồi.");
+        const sourceList = params.evidence
+            .slice(0, 6)
+            .map((item) => {
+            if (item.kind === "log") {
+                return `[log:${item.entryUid}]`;
+            }
+            if (item.kind === "summary") {
+                return `[summary:${item.summaryUid}]`;
+            }
+            if (item.kind === "memory") {
+                return `[memory:${item.memoryUid}]`;
+            }
+            return `[image:${item.imageUid}]`;
+        })
+            .join(", ");
+        const keyPoints = params.evidence
+            .slice(0, 3)
+            .map((item) => {
+            if (item.kind === "log") {
+                return `- ${item.dateText} ${item.timeText}: ${item.activity} -> ${item.outcome}`;
+            }
+            if (item.kind === "summary") {
+                return `- Summary ${item.summaryDate}/${item.scope}: ${item.summaryText}`;
+            }
+            if (item.kind === "memory") {
+                return `- Memory ${item.memoryType}: ${item.memoryText}`;
+            }
+            return `- Image ${item.chartLabel} (${item.symbol ?? "n/a"} ${item.timeframe ?? ""})`;
+        })
+            .join("\n");
+        return {
+            answer: `Mình đã tổng hợp từ dữ liệu ${productName}:\n${keyPoints}\nNguồn: ${sourceList || "(không có)"}`,
+            assumptions,
+            confidence: Math.max(0.2, Math.min(0.9, params.evidence[0]?.score ?? 0.3)),
+        };
+    }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,116 @@
+import type { PupperfishConversationTurn, PupperfishCreateImageInput, PupperfishDeleteImageResult, PupperfishImageEvidence, PupperfishLogDetail, PupperfishLogEvidence, PupperfishLogImageTarget, PupperfishMemoryEvidence, PupperfishPersistedImage, PupperfishPlannerMode, PupperfishStoredImage, PupperfishSummaryEvidence, PupperfishTradeImageItem, PupperfishUpdateTradeImagePayload, PupperfishWorkerCycleResult, QueryLogFilters, QueryMemoryFilters, QuerySummaryFilters, WorkerJobPayload, WorkerJobType } from "./types.js";
+export type PupperfishUploadFile = {
+    name: string;
+    type: string;
+    size: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+};
+export type PupperfishBrandingConfig = {
+    assistantName: string;
+    productName: string;
+};
+export type PupperfishPlannerKeyword = {
+    mode: PupperfishPlannerMode;
+    pattern: RegExp;
+};
+export type PupperfishRuntimeConfig = {
+    branding: PupperfishBrandingConfig;
+    locale?: string;
+    plannerKeywords?: PupperfishPlannerKeyword[];
+    answerPolicy?: {
+        language?: string;
+        concise?: boolean;
+    };
+    limits?: {
+        topKDefault?: number;
+        topKMax?: number;
+        uploadMaxBytes?: number;
+        workerBatchLimit?: number;
+    };
+};
+export interface PupperfishRepositories {
+    searchLogs(query: string, filters: QueryLogFilters, topK: number): Promise<PupperfishLogEvidence[]>;
+    searchSummaries(query: string, filters: QuerySummaryFilters, topK: number): Promise<PupperfishSummaryEvidence[]>;
+    searchMemories(query: string, filters: QueryMemoryFilters, topK: number): Promise<PupperfishMemoryEvidence[]>;
+    searchImages(query: string, topK: number): Promise<PupperfishImageEvidence[]>;
+    getLog(entryUid: string): Promise<PupperfishLogDetail | null>;
+    getSummary(summaryUid: string): Promise<Record<string, unknown> | null>;
+    getMemory(memoryUid: string): Promise<Record<string, unknown> | null>;
+    getImage(imageUid: string): Promise<PupperfishStoredImage | null>;
+    getSimilarImages(imageUid: string, topK: number): Promise<PupperfishImageEvidence[]>;
+    listLogImages(entryUid: string): Promise<PupperfishTradeImageItem[] | null>;
+    getLogImageTarget(entryUid: string): Promise<PupperfishLogImageTarget | null>;
+    createImageForLog(input: PupperfishCreateImageInput): Promise<PupperfishStoredImage>;
+    updateImage(imageUid: string, payload: PupperfishUpdateTradeImagePayload): Promise<PupperfishStoredImage>;
+    deleteImage(imageUid: string): Promise<PupperfishDeleteImageResult>;
+    recordConversation?(params: {
+        convoUid: string;
+        userId: string;
+        requestUid: string;
+        turns: PupperfishConversationTurn[];
+    }): Promise<void>;
+}
+export interface PupperfishAiProvider {
+    embedText?(text: string): Promise<{
+        embedding: number[];
+        model: string;
+        source: string;
+    }>;
+    embedImage?(bytes: Uint8Array): Promise<{
+        embedding: number[];
+        model: string;
+        source: string;
+    }>;
+    generateAnswer(prompt: string): Promise<{
+        text: string;
+        model: string;
+        source: string;
+    }>;
+}
+export interface PupperfishStorageProvider {
+    persistImage(file: PupperfishUploadFile): Promise<PupperfishPersistedImage>;
+    deletePersistedImage(persisted: PupperfishPersistedImage): Promise<void>;
+    deleteStoredImage(pointer: PupperfishStoredImage): Promise<void>;
+    resolveStoredImagePath(pointer: PupperfishStoredImage): Promise<string>;
+    buildImageDownloadUrl(imageUid: string): string;
+}
+export interface PupperfishJobQueue {
+    enqueue(jobType: WorkerJobType, payload: WorkerJobPayload, priority?: number): Promise<void>;
+    enqueueMany(jobs: Array<{
+        jobType: WorkerJobType;
+        payload: WorkerJobPayload;
+        priority?: number;
+    }>): Promise<void>;
+    runWorkerCycle(limit: number): Promise<PupperfishWorkerCycleResult>;
+    onLogsChanged(logs: Array<{
+        id: string;
+    }>): Promise<void>;
+    onImageChanged(imageId: string): Promise<void>;
+    onSummaryChanged(summaryId: string, sourceLogIds: string[]): Promise<void>;
+}
+export interface PupperfishAuditLogger {
+    logRetrieveSuccess(params: {
+        requestUid: string;
+        userId: string;
+        queryText: string;
+        queryMode: PupperfishPlannerMode;
+        entryUid: string | null;
+        imageUid: string | null;
+        summaryScope: string | null;
+        filters: Record<string, unknown>;
+        retrievedCount: number;
+        latencyMs: number;
+        responseJson: Record<string, unknown>;
+        requestJson: Record<string, unknown>;
+    }): Promise<void>;
+    logRetrieveError(params: {
+        requestUid: string;
+        userId: string;
+        queryText: string;
+        queryMode: PupperfishPlannerMode;
+        filters: Record<string, unknown>;
+        errorCode: string;
+        requestJson: Record<string, unknown>;
+        responseJson: Record<string, unknown>;
+    }): Promise<void>;
+}

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/embeddings.d.ts

@@ -0,0 +1,5 @@
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export declare function deterministicEmbeddingFromText(text: string, dimensions?: number): number[];
+export declare function deterministicEmbeddingFromBuffer(buffer: Buffer, dimensions?: number): number[];
+export declare function normalizeVector(vector: number[]): number[];
+export declare function coerceNumberArray(input: unknown): number[];

package/dist/embeddings.js

@@ -0,0 +1,60 @@
+import { createHash } from "crypto";
+export function cosineSimilarity(a, b) {
+    if (!a.length || !b.length || a.length !== b.length) {
+        return 0;
+    }
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let index = 0; index < a.length; index += 1) {
+        dot += a[index] * b[index];
+        normA += a[index] * a[index];
+        normB += b[index] * b[index];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+export function deterministicEmbeddingFromText(text, dimensions = 64) {
+    const out = new Array(dimensions).fill(0);
+    if (!text.trim()) {
+        return out;
+    }
+    const hash = createHash("sha256").update(text).digest();
+    for (let index = 0; index < dimensions; index += 1) {
+        const base = hash[index % hash.length] ?? 0;
+        out[index] = (base / 255) * 2 - 1;
+    }
+    return normalizeVector(out);
+}
+export function deterministicEmbeddingFromBuffer(buffer, dimensions = 64) {
+    const out = new Array(dimensions).fill(0);
+    if (buffer.length < 1) {
+        return out;
+    }
+    for (let index = 0; index < dimensions; index += 1) {
+        const value = buffer[index % buffer.length] ?? 0;
+        out[index] = (value / 255) * 2 - 1;
+    }
+    return normalizeVector(out);
+}
+export function normalizeVector(vector) {
+    let norm = 0;
+    for (const value of vector) {
+        norm += value * value;
+    }
+    if (norm === 0) {
+        return vector;
+    }
+    const sqrt = Math.sqrt(norm);
+    return vector.map((value) => value / sqrt);
+}
+export function coerceNumberArray(input) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input
+        .map((value) => (typeof value === "number" && Number.isFinite(value) ? value : null))
+        .filter((value) => value !== null);
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class PupperfishError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export declare function isPupperfishError(error: unknown): error is PupperfishError;

package/dist/errors.js

@@ -0,0 +1,13 @@
+export class PupperfishError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 400) {
+        super(message);
+        this.name = "PupperfishError";
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isPupperfishError(error) {
+    return error instanceof PupperfishError;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./normalize.js";
+export * from "./planner.js";
+export * from "./embeddings.js";
+export * from "./answer.js";
+export * from "./runtime.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./contracts.js";
+export * from "./errors.js";
+export * from "./normalize.js";
+export * from "./planner.js";
+export * from "./embeddings.js";
+export * from "./answer.js";
+export * from "./runtime.js";

package/dist/normalize.d.ts

@@ -0,0 +1,7 @@
+export declare function normalizeText(input: string): string;
+export declare function tokenizeText(input: string): string[];
+export declare function buildOutcomeCode(outcome: string): string | null;
+export declare function buildActionCode(nextAction: string | null | undefined): string | null;
+export declare function buildContextStruct(context: string | null | undefined): Record<string, unknown>;
+export declare function createDeterministicUid(prefix: string, payload: string): string;
+export declare function sanitizeList(input: string[]): string[];

package/dist/normalize.js

@@ -0,0 +1,73 @@
+import { createHash } from "crypto";
+export function normalizeText(input) {
+    return input
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^\p{L}\p{N}\s_:/.-]+/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+export function tokenizeText(input) {
+    const normalized = normalizeText(input);
+    if (!normalized) {
+        return [];
+    }
+    const tokens = normalized
+        .split(/\s+/)
+        .filter((token) => token.length >= 2)
+        .slice(0, 64);
+    return Array.from(new Set(tokens));
+}
+export function buildOutcomeCode(outcome) {
+    const normalized = normalizeText(outcome);
+    if (!normalized) {
+        return null;
+    }
+    if (/(done|xong|hoan thanh|completed|success|ok)/.test(normalized)) {
+        return "done";
+    }
+    if (/(watch|theo doi|monitor|waiting|dang theo doi)/.test(normalized)) {
+        return "watching";
+    }
+    if (/(fail|that bai|loi|error|miss)/.test(normalized)) {
+        return "failed";
+    }
+    return null;
+}
+export function buildActionCode(nextAction) {
+    const normalized = normalizeText(nextAction ?? "");
+    if (!normalized) {
+        return null;
+    }
+    if (/(alert|canh bao|set alert)/.test(normalized)) {
+        return "set_alert";
+    }
+    if (/(review|xem lai|kiem tra)/.test(normalized)) {
+        return "review";
+    }
+    if (/(execute|vao lenh|entry|mo lenh)/.test(normalized)) {
+        return "execute";
+    }
+    return normalized.slice(0, 40);
+}
+export function buildContextStruct(context) {
+    const source = context ?? "";
+    const normalized = normalizeText(source);
+    const symbolMatch = source.match(/\b([A-Z]{3,6}\/?[A-Z]{0,6})\b/);
+    const timeframeMatch = source.match(/\b(M1|M5|M15|M30|H1|H4|D1|W1)\b/i);
+    return {
+        hasSma: /\bsma\d+/i.test(source),
+        hasAlert: /(alert|canh bao)/i.test(source),
+        symbol: symbolMatch?.[1] ?? null,
+        timeframe: timeframeMatch?.[1]?.toUpperCase() ?? null,
+        tokens: tokenizeText(normalized),
+    };
+}
+export function createDeterministicUid(prefix, payload) {
+    const digest = createHash("sha1").update(payload).digest("hex");
+    return `${prefix}_${digest.slice(0, 20)}`;
+}
+export function sanitizeList(input) {
+    return input.map((item) => item.trim()).filter(Boolean);
+}

package/dist/planner.d.ts

@@ -0,0 +1,4 @@
+import type { PupperfishPlannerKeyword } from "./contracts.js";
+import type { PupperfishPlannerMode } from "./types.js";
+export declare function getDefaultPlannerKeywords(): PupperfishPlannerKeyword[];
+export declare function resolvePlannerMode(query: string, forcedMode?: string, keywords?: PupperfishPlannerKeyword[]): PupperfishPlannerMode;

package/dist/planner.js

@@ -0,0 +1,23 @@
+import { normalizeText } from "./normalize.js";
+const DEFAULT_KEYWORDS = [
+    { mode: "image", pattern: /\b(image|chart|anh|hinh|screenshot|candlestick|biểu đồ|bieu do)\b/i },
+    { mode: "summary", pattern: /\b(summary|tong hop|tổng hợp|session|tokyo|london|newyork|today)\b/i },
+    { mode: "memory", pattern: /\b(memory|ghi nho|nhớ|rule|quy tac|thoi quen|bai hoc)\b/i },
+    { mode: "sql", pattern: /\b(log|entry|nhat ky|nhật ký|lenh|lệnh|trade)\b/i },
+];
+export function getDefaultPlannerKeywords() {
+    return DEFAULT_KEYWORDS;
+}
+export function resolvePlannerMode(query, forcedMode, keywords = DEFAULT_KEYWORDS) {
+    const forced = (forcedMode ?? "").trim().toLowerCase();
+    if (forced === "sql" || forced === "summary" || forced === "memory" || forced === "image" || forced === "hybrid") {
+        return forced;
+    }
+    const normalized = normalizeText(query);
+    for (const item of keywords) {
+        if (item.pattern.test(normalized)) {
+            return item.mode;
+        }
+    }
+    return "hybrid";
+}

package/dist/runtime.d.ts

@@ -0,0 +1,38 @@
+import type { PupperfishAiProvider, PupperfishAuditLogger, PupperfishJobQueue, PupperfishRepositories, PupperfishRuntimeConfig, PupperfishStorageProvider, PupperfishUploadFile } from "./contracts.js";
+import type { PupperfishRetrieveRequest, PupperfishRetrieveResult, PupperfishTradeImageItem, PupperfishUpdateTradeImagePayload, QueryLogFilters, QueryMemoryFilters, QuerySummaryFilters } from "./types.js";
+export declare function createPupperfishRuntime(params: {
+    repositories: PupperfishRepositories;
+    aiProvider: PupperfishAiProvider;
+    storageProvider: PupperfishStorageProvider;
+    jobQueue: PupperfishJobQueue;
+    auditLogger: PupperfishAuditLogger;
+    config: PupperfishRuntimeConfig;
+}): {
+    retrieve: (input: PupperfishRetrieveRequest, userId?: string) => Promise<PupperfishRetrieveResult>;
+    searchLogs: (query: string, filters: QueryLogFilters, topK: number) => Promise<import("./types.js").PupperfishLogEvidence[]>;
+    searchSummaries: (query: string, filters: QuerySummaryFilters, topK: number) => Promise<import("./types.js").PupperfishSummaryEvidence[]>;
+    searchMemories: (query: string, filters: QueryMemoryFilters, topK: number) => Promise<import("./types.js").PupperfishMemoryEvidence[]>;
+    searchImages: (query: string, topK: number) => Promise<import("./types.js").PupperfishImageEvidence[]>;
+    getLog: (entryUid: string) => Promise<import("./types.js").PupperfishLogDetail | null>;
+    getSummary: (summaryUid: string) => Promise<Record<string, unknown> | null>;
+    getMemory: (memoryUid: string) => Promise<Record<string, unknown> | null>;
+    getImage: (imageUid: string) => Promise<import("./types.js").PupperfishStoredImage | null>;
+    getSimilarImages: (imageUid: string, topK: number) => Promise<import("./types.js").PupperfishImageEvidence[]>;
+    listLogImages: (entryUid: string) => Promise<PupperfishTradeImageItem[] | null>;
+    uploadImage: (entryUid: string, payload: {
+        file: PupperfishUploadFile;
+        chartLabel?: string | null;
+        symbol?: string | null;
+        timeframe?: string | null;
+        note?: string | null;
+        imageSlot?: number | null;
+    }, userId?: string) => Promise<PupperfishTradeImageItem>;
+    updateImage: (imageUid: string, payload: PupperfishUpdateTradeImagePayload) => Promise<PupperfishTradeImageItem>;
+    deleteImage: (imageUid: string) => Promise<import("./types.js").PupperfishDeleteImageResult>;
+    runWorkerCycle(limit?: number): Promise<import("./types.js").PupperfishWorkerCycleResult>;
+    onLogChanged(logs: Array<{
+        id: string;
+    }>): Promise<void>;
+    onImageChanged(imageId: string): Promise<void>;
+    onSummaryChanged(summaryId: string, sourceLogIds: string[]): Promise<void>;
+};

package/dist/runtime.js

@@ -0,0 +1,344 @@
+import { randomUUID } from "crypto";
+import { PupperfishError } from "./errors.js";
+import { composePupperfishAnswer } from "./answer.js";
+import { getDefaultPlannerKeywords, resolvePlannerMode } from "./planner.js";
+function trimQuery(query) {
+    return typeof query === "string" ? query.trim() : "";
+}
+function readFilterString(filters, key) {
+    const value = filters[key];
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized || undefined;
+}
+function parseFilters(input) {
+    const raw = input.filters && typeof input.filters === "object" ? input.filters : {};
+    return {
+        logFilters: {
+            fromDate: readFilterString(raw, "fromDate"),
+            toDate: readFilterString(raw, "toDate"),
+            tag: readFilterString(raw, "tag"),
+            activity: readFilterString(raw, "activity"),
+            context: readFilterString(raw, "context"),
+            outcome: readFilterString(raw, "outcome"),
+            timeFrom: readFilterString(raw, "timeFrom"),
+            timeTo: readFilterString(raw, "timeTo"),
+        },
+        summaryFilters: {
+            scope: readFilterString(raw, "scope"),
+            source: readFilterString(raw, "source"),
+            status: readFilterString(raw, "status"),
+            fromDate: readFilterString(raw, "fromDate"),
+            toDate: readFilterString(raw, "toDate"),
+        },
+        memoryFilters: {
+            memoryType: readFilterString(raw, "memoryType"),
+            sourceType: readFilterString(raw, "sourceType"),
+            status: readFilterString(raw, "status"),
+        },
+    };
+}
+function clampTopK(value, config) {
+    const fallback = config.limits?.topKDefault ?? 8;
+    const max = config.limits?.topKMax ?? 20;
+    const numeric = typeof value === "number" ? value : Number(value ?? fallback);
+    if (!Number.isFinite(numeric)) {
+        return fallback;
+    }
+    return Math.min(Math.max(Math.trunc(numeric), 1), max);
+}
+function evidenceKey(item) {
+    if (item.kind === "log") {
+        return `log:${item.entryUid}`;
+    }
+    if (item.kind === "summary") {
+        return `summary:${item.summaryUid}`;
+    }
+    if (item.kind === "memory") {
+        return `memory:${item.memoryUid}`;
+    }
+    return `image:${item.imageUid}`;
+}
+function rankEvidence(items, topK) {
+    const bestByKey = new Map();
+    for (const item of items) {
+        const key = evidenceKey(item);
+        const previous = bestByKey.get(key);
+        if (!previous || item.score > previous.score) {
+            bestByKey.set(key, item);
+        }
+    }
+    return [...bestByKey.values()]
+        .sort((left, right) => right.score - left.score)
+        .slice(0, topK);
+}
+function modeUsesLogs(mode) {
+    return mode === "sql" || mode === "hybrid";
+}
+function modeUsesSummaries(mode) {
+    return mode === "summary" || mode === "hybrid";
+}
+function modeUsesMemories(mode) {
+    return mode === "memory" || mode === "hybrid";
+}
+function modeUsesImages(mode) {
+    return mode === "image" || mode === "hybrid";
+}
+function buildSources(evidence) {
+    return evidence.map((item) => {
+        if (item.kind === "log") {
+            return { kind: "log", uid: item.entryUid };
+        }
+        if (item.kind === "summary") {
+            return { kind: "summary", uid: item.summaryUid };
+        }
+        if (item.kind === "memory") {
+            return { kind: "memory", uid: item.memoryUid };
+        }
+        return { kind: "image", uid: item.imageUid };
+    });
+}
+function normalizeUploadText(value) {
+    const normalized = (value ?? "").trim();
+    return normalized || null;
+}
+function parseImageSlot(raw) {
+    if (raw === null || raw === undefined || raw === "") {
+        return null;
+    }
+    const parsed = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(parsed)) {
+        throw new PupperfishError("PUPPERFISH_IMAGE_SLOT_INVALID", "imageSlot phải là số nguyên dương.", 400);
+    }
+    return Math.max(1, Math.trunc(parsed));
+}
+export function createPupperfishRuntime(params) {
+    const { repositories, aiProvider, storageProvider, jobQueue, auditLogger, config } = params;
+    const plannerKeywords = config.plannerKeywords ?? getDefaultPlannerKeywords();
+    const uploadMaxBytes = config.limits?.uploadMaxBytes ?? 10 * 1024 * 1024;
+    async function retrieve(input, userId = "admin") {
+        const query = trimQuery(input.query);
+        if (!query) {
+            throw new PupperfishError("PUPPERFISH_QUERY_REQUIRED", "query không được để trống.", 400);
+        }
+        const requestUid = randomUUID();
+        const convoUid = typeof input.convoUid === "string" && input.convoUid.trim() ? input.convoUid.trim() : randomUUID();
+        const topK = clampTopK(input.topK, config);
+        const mode = resolvePlannerMode(query, input.mode, plannerKeywords);
+        const { logFilters, summaryFilters, memoryFilters } = parseFilters(input);
+        const startedAt = Date.now();
+        try {
+            const logsPromise = modeUsesLogs(mode) ? repositories.searchLogs(query, logFilters, Math.max(6, topK)) : Promise.resolve([]);
+            const summariesPromise = modeUsesSummaries(mode)
+                ? repositories.searchSummaries(query, summaryFilters, Math.max(4, Math.floor(topK * 0.75)))
+                : Promise.resolve([]);
+            const memoriesPromise = modeUsesMemories(mode)
+                ? repositories.searchMemories(query, memoryFilters, Math.max(4, Math.floor(topK * 0.75)))
+                : Promise.resolve([]);
+            const imagesPromise = modeUsesImages(mode) ? repositories.searchImages(query, Math.max(4, topK)) : Promise.resolve([]);
+            const [logs, summaries, memories, images] = await Promise.all([logsPromise, summariesPromise, memoriesPromise, imagesPromise]);
+            let evidence = rankEvidence([...logs, ...summaries, ...memories, ...images], topK);
+            const needsFallbackMerge = evidence.length < 1 || (mode === "hybrid" && evidence.length < Math.min(2, topK));
+            let fallbackEvidenceUsed = false;
+            if (needsFallbackMerge) {
+                const [fallbackLogs, fallbackSummaries, fallbackMemories, fallbackImages] = await Promise.all([
+                    modeUsesLogs(mode) ? repositories.searchLogs("", logFilters, Math.max(4, topK)) : Promise.resolve([]),
+                    modeUsesSummaries(mode)
+                        ? repositories.searchSummaries("", summaryFilters, Math.max(3, Math.floor(topK * 0.75)))
+                        : Promise.resolve([]),
+                    modeUsesMemories(mode)
+                        ? repositories.searchMemories("", memoryFilters, Math.max(3, Math.floor(topK * 0.75)))
+                        : Promise.resolve([]),
+                    modeUsesImages(mode) ? repositories.searchImages("", Math.max(3, topK)) : Promise.resolve([]),
+                ]);
+                const merged = rankEvidence([...evidence, ...fallbackLogs, ...fallbackSummaries, ...fallbackMemories, ...fallbackImages], topK);
+                fallbackEvidenceUsed = merged.length > evidence.length;
+                evidence = merged;
+            }
+            const composed = await composePupperfishAnswer({
+                aiProvider,
+                config,
+                query,
+                mode,
+                evidence,
+                memories,
+                charts: images,
+            });
+            const sources = buildSources(evidence);
+            const latencyMs = Date.now() - startedAt;
+            if (repositories.recordConversation) {
+                await repositories.recordConversation({
+                    convoUid,
+                    userId,
+                    requestUid,
+                    turns: [
+                        {
+                            role: "user",
+                            content: query,
+                            metadata: { source: "pupperfish", requestUid },
+                        },
+                        {
+                            role: "assistant",
+                            content: composed.answer,
+                            metadata: { source: "pupperfish", requestUid, mode, fallbackEvidenceUsed },
+                        },
+                    ],
+                });
+            }
+            await auditLogger.logRetrieveSuccess({
+                requestUid,
+                userId,
+                queryText: query,
+                queryMode: mode,
+                entryUid: evidence.find((item) => item.kind === "log")?.entryUid ?? null,
+                imageUid: evidence.find((item) => item.kind === "image")?.imageUid ?? null,
+                summaryScope: evidence.find((item) => item.kind === "summary")?.scope ?? null,
+                filters: input.filters ?? {},
+                retrievedCount: evidence.length,
+                latencyMs,
+                requestJson: input,
+                responseJson: {
+                    mode,
+                    sources,
+                    confidence: composed.confidence,
+                    fallbackEvidenceUsed,
+                },
+            });
+            return {
+                requestUid,
+                convoUid,
+                mode,
+                answer: composed.answer,
+                confidence: composed.confidence,
+                assumptions: composed.assumptions,
+                evidence,
+                charts: images,
+                memories,
+                sources,
+                latencyMs,
+            };
+        }
+        catch (error) {
+            const code = error instanceof PupperfishError ? error.code : "PUPPERFISH_RETRIEVE_FAILED";
+            await auditLogger.logRetrieveError({
+                requestUid,
+                userId,
+                queryText: query,
+                queryMode: mode,
+                filters: input.filters ?? {},
+                errorCode: code,
+                requestJson: input,
+                responseJson: {
+                    error: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
+    }
+    async function uploadImage(entryUid, payload, userId = "admin") {
+        const normalizedEntryUid = entryUid.trim();
+        if (!normalizedEntryUid) {
+            throw new PupperfishError("PUPPERFISH_ENTRY_UID_INVALID", "entryUid không hợp lệ.", 400);
+        }
+        if (!payload.file) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_FILE_REQUIRED", "Thiếu file upload.", 400);
+        }
+        if (payload.file.size < 1) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_EMPTY", "File ảnh rỗng.", 400);
+        }
+        if (!payload.file.type || !payload.file.type.toLowerCase().startsWith("image/")) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_FILE_INVALID_TYPE", "Chỉ chấp nhận file ảnh (image/*).", 400);
+        }
+        if (payload.file.size > uploadMaxBytes) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_FILE_TOO_LARGE", `Dung lượng ảnh tối đa là ${Math.trunc(uploadMaxBytes / (1024 * 1024))}MB.`, 400);
+        }
+        const target = await repositories.getLogImageTarget(normalizedEntryUid);
+        if (!target) {
+            throw new PupperfishError("PUPPERFISH_LOG_NOT_FOUND", "Không tìm thấy log theo entryUid.", 404);
+        }
+        const requestedSlot = parseImageSlot(payload.imageSlot);
+        const occupied = new Set(target.occupiedSlots);
+        if (requestedSlot && occupied.has(requestedSlot)) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_SLOT_CONFLICT", "imageSlot đã tồn tại cho log này.", 409);
+        }
+        const imageSlot = requestedSlot ?? (target.occupiedSlots.length > 0 ? Math.max(...target.occupiedSlots) + 1 : 1);
+        const persisted = await storageProvider.persistImage(payload.file);
+        try {
+            const created = await repositories.createImageForLog({
+                imageUid: persisted.imageUid,
+                entryId: target.entryId,
+                entryUid: target.entryUid,
+                imageSlot,
+                chartLabel: normalizeUploadText(payload.chartLabel)?.slice(0, 120) ?? "Chart",
+                symbol: normalizeUploadText(payload.symbol),
+                timeframe: normalizeUploadText(payload.timeframe)?.toUpperCase() ?? null,
+                note: normalizeUploadText(payload.note),
+                filePath: persisted.absolutePath,
+                fileUrl: storageProvider.buildImageDownloadUrl(persisted.imageUid),
+                fileName: persisted.fileName,
+                mimeType: persisted.mimeType,
+                fileSizeBytes: persisted.fileSizeBytes,
+                sha256: persisted.sha256,
+                uploadedBy: userId,
+                relativePath: persisted.relativePath,
+            });
+            await jobQueue.onImageChanged(created.id);
+            return created;
+        }
+        catch (error) {
+            await storageProvider.deletePersistedImage(persisted);
+            throw error;
+        }
+    }
+    async function updateImage(imageUid, payload) {
+        const normalizedUid = imageUid.trim();
+        if (!normalizedUid) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_UID_INVALID", "imageUid không hợp lệ.", 400);
+        }
+        const updated = await repositories.updateImage(normalizedUid, payload);
+        await jobQueue.onImageChanged(updated.id);
+        return updated;
+    }
+    async function deleteImage(imageUid) {
+        const normalizedUid = imageUid.trim();
+        if (!normalizedUid) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_UID_INVALID", "imageUid không hợp lệ.", 400);
+        }
+        const image = await repositories.getImage(normalizedUid);
+        if (!image) {
+            throw new PupperfishError("PUPPERFISH_IMAGE_NOT_FOUND", "Không tìm thấy ảnh theo imageUid.", 404);
+        }
+        await storageProvider.deleteStoredImage(image);
+        return repositories.deleteImage(normalizedUid);
+    }
+    return {
+        retrieve,
+        searchLogs: repositories.searchLogs,
+        searchSummaries: repositories.searchSummaries,
+        searchMemories: repositories.searchMemories,
+        searchImages: repositories.searchImages,
+        getLog: repositories.getLog,
+        getSummary: repositories.getSummary,
+        getMemory: repositories.getMemory,
+        getImage: repositories.getImage,
+        getSimilarImages: repositories.getSimilarImages,
+        listLogImages: repositories.listLogImages,
+        uploadImage,
+        updateImage,
+        deleteImage,
+        runWorkerCycle(limit) {
+            return jobQueue.runWorkerCycle(limit ?? config.limits?.workerBatchLimit ?? 8);
+        },
+        onLogChanged(logs) {
+            return jobQueue.onLogsChanged(logs);
+        },
+        onImageChanged(imageId) {
+            return jobQueue.onImageChanged(imageId);
+        },
+        onSummaryChanged(summaryId, sourceLogIds) {
+            return jobQueue.onSummaryChanged(summaryId, sourceLogIds);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,201 @@
+export type PupperfishPlannerMode = "sql" | "summary" | "memory" | "image" | "hybrid";
+export type PupperfishEvidenceKind = "log" | "summary" | "memory" | "image";
+export type PupperfishLogEvidence = {
+    kind: "log";
+    id: string;
+    entryUid: string;
+    dateText: string;
+    timeText: string;
+    activity: string;
+    context: string | null;
+    outcome: string;
+    nextAction: string | null;
+    moodEnergy: string | null;
+    tags: string[];
+    score: number;
+};
+export type PupperfishSummaryEvidence = {
+    kind: "summary";
+    id: string;
+    summaryUid: string;
+    summaryDate: string;
+    scope: string;
+    source: string;
+    status: string;
+    summaryText: string;
+    nextAction: string | null;
+    score: number;
+};
+export type PupperfishMemoryEvidence = {
+    kind: "memory";
+    id: string;
+    memoryUid: string;
+    memoryType: string;
+    title: string | null;
+    memoryText: string;
+    importanceScore: number;
+    confidenceScore: number;
+    score: number;
+};
+export type PupperfishImageEvidence = {
+    kind: "image";
+    id: string;
+    imageUid: string;
+    entryUid: string;
+    chartLabel: string;
+    symbol: string | null;
+    timeframe: string | null;
+    fileName: string;
+    fileUrl: string | null;
+    score: number;
+};
+export type PupperfishEvidenceItem = PupperfishLogEvidence | PupperfishSummaryEvidence | PupperfishMemoryEvidence | PupperfishImageEvidence;
+export type PupperfishRetrieveRequest = {
+    query: string;
+    mode?: PupperfishPlannerMode;
+    topK?: number;
+    convoUid?: string;
+    filters?: Record<string, unknown>;
+};
+export type PupperfishRetrieveSource = {
+    kind: PupperfishEvidenceKind;
+    uid: string;
+};
+export type PupperfishRetrieveResult = {
+    requestUid: string;
+    convoUid: string;
+    mode: PupperfishPlannerMode;
+    answer: string;
+    confidence: number;
+    assumptions: string[];
+    evidence: PupperfishEvidenceItem[];
+    charts: PupperfishImageEvidence[];
+    memories: PupperfishMemoryEvidence[];
+    sources: PupperfishRetrieveSource[];
+    latencyMs: number;
+};
+export type WorkerJobType = "text_embedding_job" | "summary_embedding_job" | "image_embedding_job" | "memory_extraction_job" | "summary_linking_job" | "summary_memory_job" | "reembed_backfill_job";
+export type WorkerJobPayload = Record<string, unknown>;
+export type WorkerJob = {
+    id: string;
+    jobType: WorkerJobType;
+    payload: WorkerJobPayload;
+    retryCount: number;
+    maxRetries: number;
+};
+export type QueryLogFilters = {
+    fromDate?: string;
+    toDate?: string;
+    tag?: string;
+    activity?: string;
+    context?: string;
+    outcome?: string;
+    timeFrom?: string;
+    timeTo?: string;
+};
+export type QuerySummaryFilters = {
+    scope?: string;
+    source?: string;
+    status?: string;
+    fromDate?: string;
+    toDate?: string;
+};
+export type QueryMemoryFilters = {
+    memoryType?: string;
+    sourceType?: string;
+    status?: string;
+};
+export type PupperfishLogDetail = {
+    entryUid: string;
+    dateText: string;
+    timeText: string;
+    activity: string;
+    outcome: string;
+    nextAction: string | null;
+    tags: string[];
+};
+export type PupperfishTradeImageItem = {
+    id: string;
+    imageUid: string;
+    entryUid: string;
+    imageSlot: number;
+    chartLabel: string;
+    symbol: string | null;
+    timeframe: string | null;
+    note: string | null;
+    fileName: string;
+    fileUrl: string | null;
+    mimeType: string;
+    fileSizeBytes: string | null;
+    widthPx: number | null;
+    heightPx: number | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type PupperfishStoredImagePointer = {
+    filePath: string | null;
+    meta?: unknown;
+};
+export type PupperfishStoredImage = PupperfishTradeImageItem & PupperfishStoredImagePointer & {
+    entry: {
+        id: string;
+        entryUid: string;
+        dateText: string;
+        timeText: string;
+        activity: string;
+        outcome: string;
+    };
+};
+export type PupperfishUpdateTradeImagePayload = {
+    chartLabel?: string | null;
+    symbol?: string | null;
+    timeframe?: string | null;
+    note?: string | null;
+    imageSlot?: number | null;
+};
+export type PupperfishDeleteImageResult = {
+    imageUid: string;
+    deleted: boolean;
+};
+export type PupperfishLogImageTarget = {
+    entryId: string;
+    entryUid: string;
+    occupiedSlots: number[];
+};
+export type PupperfishPersistedImage = {
+    imageUid: string;
+    absolutePath: string;
+    relativePath: string;
+    fileName: string;
+    fileSizeBytes: bigint | string;
+    mimeType: string;
+    sha256: string;
+};
+export type PupperfishCreateImageInput = {
+    imageUid: string;
+    entryId: string;
+    entryUid: string;
+    imageSlot: number;
+    chartLabel: string;
+    symbol: string | null;
+    timeframe: string | null;
+    note: string | null;
+    filePath: string;
+    fileUrl: string | null;
+    fileName: string;
+    mimeType: string;
+    fileSizeBytes: bigint | string | null;
+    sha256: string | null;
+    uploadedBy: string;
+    relativePath: string | null;
+};
+export type PupperfishConversationTurn = {
+    role: "user" | "assistant";
+    content: string;
+    metadata?: Record<string, unknown>;
+};
+export type PupperfishWorkerCycleResult = {
+    claimed: number;
+    done: number;
+    failed: number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@tungpastry/pupperfish-framework",
+  "version": "0.1.0",
+  "description": "Headless Pupperfish runtime and contracts for host apps.",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "build": "npm run clean && tsc -p tsconfig.build.json"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./normalize": {
+      "types": "./dist/normalize.d.ts",
+      "import": "./dist/normalize.js"
+    },
+    "./planner": {
+      "types": "./dist/planner.d.ts",
+      "import": "./dist/planner.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./embeddings": {
+      "types": "./dist/embeddings.d.ts",
+      "import": "./dist/embeddings.js"
+    },
+    "./answer": {
+      "types": "./dist/answer.d.ts",
+      "import": "./dist/answer.js"
+    }
+  }
+}