gnosys 4.4.6 → 5.0.0

package/dist/lib/attachments.js

@@ -0,0 +1,154 @@
+/**
+ * Gnosys Attachments — File attachment management for multimodal ingestion.
+ *
+ * Stores binary files in .gnosys/attachments/<uuid>.<ext> with a JSON manifest
+ * at .gnosys/attachments/attachments.json for tracking metadata and memory links.
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as crypto from "crypto";
+// ─── MIME type lookup from extension ────────────────────────────────────
+const MIME_MAP = {
+    // Documents
+    pdf: "application/pdf",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    txt: "text/plain",
+    md: "text/markdown",
+    // Images
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    // Audio
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    m4a: "audio/mp4",
+    ogg: "audio/ogg",
+    flac: "audio/flac",
+    // Video
+    mp4: "video/mp4",
+    mkv: "video/x-matroska",
+    mov: "video/quicktime",
+    avi: "video/x-msvideo",
+    webm: "video/webm",
+};
+function mimeFromExtension(ext) {
+    return MIME_MAP[ext.toLowerCase()] || "application/octet-stream";
+}
+// ─── Helpers ────────────────────────────────────────────────────────────
+function getAttachmentsDir(storePath) {
+    return path.join(storePath, "attachments");
+}
+function getManifestPath(storePath) {
+    return path.join(getAttachmentsDir(storePath), "attachments.json");
+}
+async function readManifest(storePath) {
+    const manifestPath = getManifestPath(storePath);
+    try {
+        const raw = await fs.readFile(manifestPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { attachments: [] };
+    }
+}
+async function writeManifest(storePath, manifest) {
+    const manifestPath = getManifestPath(storePath);
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+/**
+ * Compute SHA-256 hash of a file's contents.
+ */
+async function hashFile(filePath) {
+    const content = await fs.readFile(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+// ─── Public API ─────────────────────────────────────────────────────────
+/**
+ * Initialize the attachments directory and manifest in a store.
+ * Safe to call multiple times — creates only if missing.
+ */
+export async function initAttachments(storePath) {
+    const dir = getAttachmentsDir(storePath);
+    await fs.mkdir(dir, { recursive: true });
+    const manifestPath = getManifestPath(storePath);
+    try {
+        await fs.access(manifestPath);
+    }
+    catch {
+        // Manifest doesn't exist — create empty one
+        await writeManifest(storePath, { attachments: [] });
+    }
+}
+/**
+ * Copy a file into .gnosys/attachments/<uuid>.<ext> and register it in the manifest.
+ * Returns the attachment record with metadata.
+ *
+ * If a file with the same content hash already exists, returns the existing record
+ * instead of creating a duplicate.
+ */
+export async function storeAttachment(storePath, filePath) {
+    // Make sure attachments dir exists
+    await initAttachments(storePath);
+    // Get file info
+    const stat = await fs.stat(filePath);
+    const originalName = path.basename(filePath);
+    const ext = path.extname(filePath).slice(1).toLowerCase() || "bin";
+    const contentHash = await hashFile(filePath);
+    // Check for duplicate by content hash
+    const manifest = await readManifest(storePath);
+    const existing = manifest.attachments.find((a) => a.contentHash === contentHash);
+    if (existing) {
+        return existing;
+    }
+    // Generate UUID and copy file
+    const uuid = crypto.randomUUID();
+    const destPath = path.join(getAttachmentsDir(storePath), `${uuid}.${ext}`);
+    await fs.copyFile(filePath, destPath);
+    // Create record
+    const record = {
+        uuid,
+        originalName,
+        extension: ext,
+        mimeType: mimeFromExtension(ext),
+        sizeBytes: stat.size,
+        contentHash,
+        createdAt: new Date().toISOString(),
+        memoryIds: [],
+    };
+    // Update manifest
+    manifest.attachments.push(record);
+    await writeManifest(storePath, manifest);
+    return record;
+}
+/**
+ * Read and return all attachment records from the manifest.
+ */
+export async function listAttachments(storePath) {
+    const manifest = await readManifest(storePath);
+    return manifest.attachments;
+}
+/**
+ * Get the full filesystem path for an attachment.
+ */
+export function getAttachmentPath(storePath, uuid, ext) {
+    return path.join(getAttachmentsDir(storePath), `${uuid}.${ext}`);
+}
+/**
+ * Link a memory ID to an attachment. Updates the manifest so the attachment
+ * tracks which memories reference it.
+ */
+export async function linkMemoryToAttachment(storePath, uuid, memoryId) {
+    const manifest = await readManifest(storePath);
+    const record = manifest.attachments.find((a) => a.uuid === uuid);
+    if (!record) {
+        throw new Error(`Attachment not found: ${uuid}`);
+    }
+    if (!record.memoryIds.includes(memoryId)) {
+        record.memoryIds.push(memoryId);
+        await writeManifest(storePath, manifest);
+    }
+}
+//# sourceMappingURL=attachments.js.map

package/dist/lib/attachments.js.map

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

package/dist/lib/audioExtract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Gnosys Audio Extraction — Transcribe audio files with timestamps.
+ *
+ * API-first approach: Groq Whisper API ($0.02/hr) -> OpenAI Whisper API -> local Whisper (opt-in).
+ *
+ * Part of v5.0 Phase 4: Multimodal Ingestion — Audio support.
+ */
+export interface TranscriptSegment {
+    text: string;
+    /** Start time in seconds */
+    startTime: number;
+    /** End time in seconds */
+    endTime: number;
+}
+export interface TranscriptResult {
+    segments: TranscriptSegment[];
+    fullText: string;
+    /** Total audio duration in seconds */
+    duration: number;
+    language?: string;
+}
+export interface TranscriptionOptions {
+    provider?: "groq" | "openai" | "local";
+    apiKey?: string;
+    model?: string;
+    language?: string;
+}
+/**
+ * Transcribe an audio file with timestamps.
+ *
+ * Provider resolution order:
+ * 1. If `options.provider` is specified, use that provider
+ * 2. Try Groq (if GNOSYS_GROQ_KEY or GROQ_API_KEY is set)
+ * 3. Try OpenAI (if GNOSYS_OPENAI_KEY or OPENAI_API_KEY is set)
+ * 4. Try local Whisper (if @xenova/transformers is installed)
+ * 5. Throw an error with setup instructions
+ */
+export declare function transcribeAudio(filePath: string, options?: TranscriptionOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=audioExtract.d.ts.map

package/dist/lib/audioExtract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioExtract.d.ts","sourceRoot":"","sources":["../../src/lib/audioExtract.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA8ND;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,gBAAgB,CAAC,CA+D3B"}

package/dist/lib/audioExtract.js

@@ -0,0 +1,220 @@
+/**
+ * Gnosys Audio Extraction — Transcribe audio files with timestamps.
+ *
+ * API-first approach: Groq Whisper API ($0.02/hr) -> OpenAI Whisper API -> local Whisper (opt-in).
+ *
+ * Part of v5.0 Phase 4: Multimodal Ingestion — Audio support.
+ */
+import * as fs from "fs/promises";
+import * as path from "path";
+// ─── MIME type detection for audio files ─────────────────────────────────
+const AUDIO_MIME = {
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".m4a": "audio/mp4",
+    ".ogg": "audio/ogg",
+    ".flac": "audio/flac",
+    ".webm": "audio/webm",
+    ".aac": "audio/aac",
+};
+function detectAudioMime(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return AUDIO_MIME[ext] || "audio/wav";
+}
+async function transcribeWithGroq(audioBuffer, fileName, mimeType, apiKey, options) {
+    const formData = new FormData();
+    formData.append("file", new Blob([new Uint8Array(audioBuffer)], { type: mimeType }), fileName);
+    formData.append("model", options?.model || "whisper-large-v3-turbo");
+    formData.append("response_format", "verbose_json");
+    formData.append("timestamp_granularities[]", "segment");
+    if (options?.language) {
+        formData.append("language", options.language);
+    }
+    const response = await fetch("https://api.groq.com/openai/v1/audio/transcriptions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: formData,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Groq Whisper API error (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    return parseWhisperResponse(data);
+}
+// ─── OpenAI Whisper API ─────────────────────────────────────────────────
+async function transcribeWithOpenAI(audioBuffer, fileName, mimeType, apiKey, options) {
+    const formData = new FormData();
+    formData.append("file", new Blob([new Uint8Array(audioBuffer)], { type: mimeType }), fileName);
+    formData.append("model", options?.model || "whisper-1");
+    formData.append("response_format", "verbose_json");
+    formData.append("timestamp_granularities[]", "segment");
+    if (options?.language) {
+        formData.append("language", options.language);
+    }
+    const response = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: formData,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`OpenAI Whisper API error (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    return parseWhisperResponse(data);
+}
+async function transcribeWithLocal(filePath, options) {
+    let pipeline;
+    try {
+        // Dynamic import — @xenova/transformers is an optional dependency
+        const transformers = await import("@xenova/transformers");
+        pipeline = transformers.pipeline;
+    }
+    catch {
+        throw new Error("Local Whisper transcription requires @xenova/transformers. " +
+            'Install it with: npm install @xenova/transformers\n' +
+            "Or set a Groq/OpenAI API key for cloud transcription.");
+    }
+    const modelName = options?.model || "Xenova/whisper-small";
+    const transcriber = await pipeline("automatic-speech-recognition", modelName);
+    const result = await transcriber(filePath, {
+        return_timestamps: true,
+        ...(options?.language ? { language: options.language } : {}),
+    });
+    const segments = [];
+    let duration = 0;
+    if (result.chunks && Array.isArray(result.chunks)) {
+        for (const chunk of result.chunks) {
+            const startTime = chunk.timestamp[0];
+            const endTime = chunk.timestamp[1] ?? startTime;
+            segments.push({
+                text: chunk.text.trim(),
+                startTime,
+                endTime,
+            });
+            if (endTime > duration) {
+                duration = endTime;
+            }
+        }
+    }
+    // If no segments were returned, create a single segment from the full text
+    if (segments.length === 0 && result.text) {
+        segments.push({
+            text: result.text.trim(),
+            startTime: 0,
+            endTime: 0,
+        });
+    }
+    return {
+        segments,
+        fullText: result.text.trim(),
+        duration,
+    };
+}
+// ─── Response parsing ───────────────────────────────────────────────────
+function parseWhisperResponse(data) {
+    const segments = [];
+    let duration = data.duration ?? 0;
+    if (data.segments && Array.isArray(data.segments)) {
+        for (const seg of data.segments) {
+            segments.push({
+                text: seg.text.trim(),
+                startTime: seg.start,
+                endTime: seg.end,
+            });
+            if (seg.end > duration) {
+                duration = seg.end;
+            }
+        }
+    }
+    // If the API returned no segments, create one from the full text
+    if (segments.length === 0 && data.text) {
+        segments.push({
+            text: data.text.trim(),
+            startTime: 0,
+            endTime: duration,
+        });
+    }
+    return {
+        segments,
+        fullText: data.text?.trim() || segments.map((s) => s.text).join(" "),
+        duration,
+        language: data.language,
+    };
+}
+// ─── API key resolution ─────────────────────────────────────────────────
+function resolveGroqKey(options) {
+    return options?.apiKey || process.env.GNOSYS_GROQ_KEY || process.env.GROQ_API_KEY;
+}
+function resolveOpenAIKey(options) {
+    return options?.apiKey || process.env.GNOSYS_OPENAI_KEY || process.env.OPENAI_API_KEY;
+}
+// ─── Public API ─────────────────────────────────────────────────────────
+/**
+ * Transcribe an audio file with timestamps.
+ *
+ * Provider resolution order:
+ * 1. If `options.provider` is specified, use that provider
+ * 2. Try Groq (if GNOSYS_GROQ_KEY or GROQ_API_KEY is set)
+ * 3. Try OpenAI (if GNOSYS_OPENAI_KEY or OPENAI_API_KEY is set)
+ * 4. Try local Whisper (if @xenova/transformers is installed)
+ * 5. Throw an error with setup instructions
+ */
+export async function transcribeAudio(filePath, options) {
+    // Read the audio file
+    const audioBuffer = await fs.readFile(filePath);
+    const fileName = path.basename(filePath);
+    const mimeType = detectAudioMime(filePath);
+    // 1. Explicit provider requested
+    if (options?.provider) {
+        switch (options.provider) {
+            case "groq": {
+                const key = resolveGroqKey(options);
+                if (!key) {
+                    throw new Error("Groq transcription requires an API key. " +
+                        "Set GNOSYS_GROQ_KEY or GROQ_API_KEY in your environment.");
+                }
+                return transcribeWithGroq(audioBuffer, fileName, mimeType, key, options);
+            }
+            case "openai": {
+                const key = resolveOpenAIKey(options);
+                if (!key) {
+                    throw new Error("OpenAI transcription requires an API key. " +
+                        "Set GNOSYS_OPENAI_KEY or OPENAI_API_KEY in your environment.");
+                }
+                return transcribeWithOpenAI(audioBuffer, fileName, mimeType, key, options);
+            }
+            case "local":
+                return transcribeWithLocal(filePath, options);
+        }
+    }
+    // 2. Try Groq (cheapest API option)
+    const groqKey = resolveGroqKey(options);
+    if (groqKey) {
+        return transcribeWithGroq(audioBuffer, fileName, mimeType, groqKey, options);
+    }
+    // 3. Try OpenAI
+    const openaiKey = resolveOpenAIKey(options);
+    if (openaiKey) {
+        return transcribeWithOpenAI(audioBuffer, fileName, mimeType, openaiKey, options);
+    }
+    // 4. Try local Whisper as a fallback
+    try {
+        return await transcribeWithLocal(filePath, options);
+    }
+    catch {
+        // Local Whisper not available — fall through to the error below
+    }
+    // 5. No provider available
+    throw new Error("No transcription provider available. Set up one of:\n" +
+        "  1. Groq API key: export GROQ_API_KEY=your-key  (cheapest, $0.02/hr)\n" +
+        "  2. OpenAI API key: export OPENAI_API_KEY=your-key\n" +
+        "  3. Local Whisper: npm install @xenova/transformers\n" +
+        "Or set multimodal.transcriptionProvider in gnosys.json.");
+}
+//# sourceMappingURL=audioExtract.js.map

package/dist/lib/audioExtract.js.map

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

package/dist/lib/chunkSplitter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Gnosys Chunk Splitter — Text chunking for multi-page content.
+ *
+ * Splits long text into memory-sized chunks at natural boundaries
+ * (paragraphs first, then sentences). Used by multimodal ingestion
+ * to break PDFs, transcripts, and documents into atomic memories.
+ */
+export interface TextChunk {
+    text: string;
+    index: number;
+    sourcePage?: string;
+    sourceTimerange?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ChunkOptions {
+    /** Target chunk size in characters (default: 1500) */
+    targetSize?: number;
+    /** Minimum chunk size — chunks below this merge with the next (default: 200) */
+    minSize?: number;
+    /** Maximum chunk size — paragraphs exceeding this get split at sentences (default: 4000) */
+    maxSize?: number;
+}
+/**
+ * Split a block of text into chunks at paragraph boundaries (double newlines).
+ *
+ * Algorithm:
+ * 1. Split at double-newline (paragraph) boundaries
+ * 2. Accumulate paragraphs until reaching targetSize
+ * 3. If a single paragraph exceeds maxSize, split it at sentence boundaries
+ * 4. Merge chunks that are under minSize with the next chunk
+ */
+export declare function splitIntoChunks(text: string, options?: ChunkOptions): TextChunk[];
+/**
+ * Split pre-segmented content (pages, transcript segments) into chunks.
+ *
+ * Each segment has its own page number or timerange metadata.
+ * Segments are chunked individually, preserving their source metadata.
+ * Short segments that are under minSize get merged with the next segment
+ * (only if they share the same page).
+ */
+export declare function splitSegments(segments: Array<{
+    text: string;
+    page?: string;
+    timerange?: string;
+}>, options?: ChunkOptions): TextChunk[];
+//# sourceMappingURL=chunkSplitter.d.ts.map

package/dist/lib/chunkSplitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunkSplitter.d.ts","sourceRoot":"","sources":["../../src/lib/chunkSplitter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyFD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,EAAE,CAkEjF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACpE,OAAO,CAAC,EAAE,YAAY,GACrB,SAAS,EAAE,CAkFb"}