@framers/agentos-ext-diarization 0.2.0

package/dist/SlidingWindowExtractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlidingWindowExtractor.js","sourceRoot":"","sources":["../src/SlidingWindowExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAa3C,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,sBAAuB,SAAQ,YAAY;IAmCnC;IACA;IACA;IApCnB,4EAA4E;IAC5E,gBAAgB;IAChB,4EAA4E;IAE5E,iEAAiE;IACzD,MAAM,CAAe;IAE7B,oDAAoD;IAC5C,QAAQ,GAAG,CAAC,CAAC;IAErB,4EAA4E;IAC5E,0CAA0C;IAC1C,4EAA4E;IAE5E,2CAA2C;IAC1B,gBAAgB,CAAS;IAE1C,mEAAmE;IAClD,cAAc,CAAS;IAExC,4EAA4E;IAC5E,cAAc;IACd,4EAA4E;IAE5E;;;;;;;;OAQG;IACH,YACmB,cAAsB,IAAI,EAC1B,YAAoB,GAAG,EACvB,aAAqB,MAAM;QAE5C,KAAK,EAAE,CAAC;QAJS,gBAAW,GAAX,WAAW,CAAe;QAC1B,cAAS,GAAT,SAAS,CAAc;QACvB,eAAU,GAAV,UAAU,CAAiB;QAI5C,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;QACtE,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,UAAU,CAAC,CAAC;QAElE,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACjD,MAAM,IAAI,UAAU,CAClB,cAAc,SAAS,oDAAoD,WAAW,GAAG,CAC1F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACxD,CAAC;IAED,4EAA4E;IAC5E,aAAa;IACb,4EAA4E;IAE5E;;;;;;;;OAQG;IACH,SAAS,CAAC,KAAiB;QACzB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,IAAI,CAAC,QAAQ,KAAK,CAAC;YAAE,OAAO;QAChC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,4EAA4E;IAC5E,YAAY;IACZ,4EAA4E;IAE5E,sDAAsD;IACtD,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,4EAA4E;IAC5E,mBAAmB;IACnB,4EAA4E;IAE5E;;;;OAIG;IACK,WAAW,CAAC,OAAqB;QACvC,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,OAAO,SAAS,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC;YACxD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;YAElE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnF,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC;YAC3B,SAAS,IAAI,SAAS,CAAC;YAEvB,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;gBAC3C,yDAAyD;gBACzD,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;gBAE9C,sDAAsD;gBACtD,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,cAAc,CAAC;gBACjE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;gBAC/D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/SpeakerEmbeddingCache.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @file SpeakerEmbeddingCache.ts
+ * @description Stores and matches speaker voiceprints using cosine similarity.
+ *
+ * Each speaker is represented as a running centroid — the mean of all
+ * embeddings observed so far.  New audio embeddings are matched against
+ * existing centroids; if the best match exceeds the similarity threshold the
+ * frame is attributed to that speaker and the centroid is updated.  Otherwise
+ * a new `Speaker_N` identity is created.
+ *
+ * @module diarization/SpeakerEmbeddingCache
+ */
+/**
+ * Compute the cosine similarity between two embedding vectors.
+ *
+ * Returns a value in the range `[-1, 1]`.  A small epsilon is added to the
+ * denominator to prevent division-by-zero on silent/zero frames.
+ *
+ * @param a - First embedding vector.
+ * @param b - Second embedding vector.
+ * @returns Cosine similarity.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * In-memory cache of speaker voiceprint centroids.
+ *
+ * Centroids are updated with an online running-average as new embeddings
+ * arrive, so memory usage is O(speakers × embedding dimensions) regardless of
+ * the number of frames observed.
+ *
+ * @example
+ * ```ts
+ * const cache = new SpeakerEmbeddingCache(0.7);
+ * const { speakerId, isNew } = cache.getOrCreateSpeaker(embedding);
+ * ```
+ */
+export declare class SpeakerEmbeddingCache {
+    private readonly threshold;
+    /**
+     * Centroid map: `speakerId → { embedding, count }`.
+     *
+     * Access via {@link centroids} for testing/introspection.
+     */
+    private readonly _centroids;
+    /**
+     * @param threshold - Minimum cosine similarity required to attribute a new
+     *   embedding to an existing speaker.  Embeddings below this threshold
+     *   create a new speaker identity.
+     *   @defaultValue 0.7
+     */
+    constructor(threshold?: number);
+    /**
+     * Update the running centroid for `speakerId` with a new embedding.
+     *
+     * The centroid is recalculated as an online running average:
+     * `new_mean = old_mean + (x - old_mean) / (count + 1)`.
+     *
+     * @param speakerId - Speaker identity to update.
+     * @param embedding - New embedding vector to incorporate.
+     */
+    addEmbedding(speakerId: string, embedding: Float32Array): void;
+    /**
+     * Find the existing speaker whose centroid is most similar to `embedding`.
+     *
+     * Returns `null` if no speaker exceeds the similarity threshold or the cache
+     * is empty.
+     *
+     * @param embedding - Query embedding vector.
+     * @returns Best match above threshold, or `null`.
+     */
+    findClosestSpeaker(embedding: Float32Array): {
+        speakerId: string;
+        similarity: number;
+    } | null;
+    /**
+     * Look up or create a speaker identity for `embedding`.
+     *
+     * If a match above the threshold is found, the centroid is updated and the
+     * existing ID is returned.  Otherwise a new `Speaker_N` identity is
+     * registered.
+     *
+     * @param embedding - Audio embedding to resolve.
+     * @returns Speaker ID and whether a new identity was created.
+     */
+    getOrCreateSpeaker(embedding: Float32Array): {
+        speakerId: string;
+        isNew: boolean;
+    };
+    /**
+     * Pre-register a known speaker voiceprint, overwriting any existing centroid
+     * for this ID.
+     *
+     * Use this to seed the cache with enrolment recordings before a session
+     * begins so that known participants are matched by name rather than the
+     * auto-generated `Speaker_N` label.
+     *
+     * @param id - Human-readable speaker identifier.
+     * @param voiceprint - Reference embedding for this speaker.
+     */
+    enrollSpeaker(id: string, voiceprint: Float32Array): void;
+    /**
+     * Read-only view of the internal centroid map.
+     *
+     * Returns a snapshot — modifications to the returned map do not affect the
+     * cache.
+     */
+    get centroids(): Map<string, Float32Array>;
+    /** Number of distinct speaker identities currently tracked. */
+    get size(): number;
+    /**
+     * Remove all centroids from the cache.
+     *
+     * Useful for resetting state between test cases.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=SpeakerEmbeddingCache.d.ts.map

package/dist/SpeakerEmbeddingCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpeakerEmbeddingCache.d.ts","sourceRoot":"","sources":["../src/SpeakerEmbeddingCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAYzE;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,qBAAqB;IAsBpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjBtC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAM/D;;;;;OAKG;gBAC0B,SAAS,GAAE,MAAY;IAMpD;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG,IAAI;IAuB9D;;;;;;;;OAQG;IACH,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAmB7F;;;;;;;;;OASG;IACH,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;IAalF;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,IAAI;IAQzD;;;;;OAKG;IACH,IAAI,SAAS,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAMzC;IAED,+DAA+D;IAC/D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/SpeakerEmbeddingCache.js

@@ -0,0 +1,193 @@
+/**
+ * @file SpeakerEmbeddingCache.ts
+ * @description Stores and matches speaker voiceprints using cosine similarity.
+ *
+ * Each speaker is represented as a running centroid — the mean of all
+ * embeddings observed so far.  New audio embeddings are matched against
+ * existing centroids; if the best match exceeds the similarity threshold the
+ * frame is attributed to that speaker and the centroid is updated.  Otherwise
+ * a new `Speaker_N` identity is created.
+ *
+ * @module diarization/SpeakerEmbeddingCache
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Compute the cosine similarity between two embedding vectors.
+ *
+ * Returns a value in the range `[-1, 1]`.  A small epsilon is added to the
+ * denominator to prevent division-by-zero on silent/zero frames.
+ *
+ * @param a - First embedding vector.
+ * @param b - Second embedding vector.
+ * @returns Cosine similarity.
+ */
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        magA += (a[i]) ** 2;
+        magB += (b[i]) ** 2;
+    }
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB) + 1e-8);
+}
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * In-memory cache of speaker voiceprint centroids.
+ *
+ * Centroids are updated with an online running-average as new embeddings
+ * arrive, so memory usage is O(speakers × embedding dimensions) regardless of
+ * the number of frames observed.
+ *
+ * @example
+ * ```ts
+ * const cache = new SpeakerEmbeddingCache(0.7);
+ * const { speakerId, isNew } = cache.getOrCreateSpeaker(embedding);
+ * ```
+ */
+export class SpeakerEmbeddingCache {
+    threshold;
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /**
+     * Centroid map: `speakerId → { embedding, count }`.
+     *
+     * Access via {@link centroids} for testing/introspection.
+     */
+    _centroids = new Map();
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param threshold - Minimum cosine similarity required to attribute a new
+     *   embedding to an existing speaker.  Embeddings below this threshold
+     *   create a new speaker identity.
+     *   @defaultValue 0.7
+     */
+    constructor(threshold = 0.7) {
+        this.threshold = threshold;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Update the running centroid for `speakerId` with a new embedding.
+     *
+     * The centroid is recalculated as an online running average:
+     * `new_mean = old_mean + (x - old_mean) / (count + 1)`.
+     *
+     * @param speakerId - Speaker identity to update.
+     * @param embedding - New embedding vector to incorporate.
+     */
+    addEmbedding(speakerId, embedding) {
+        const existing = this._centroids.get(speakerId);
+        if (!existing) {
+            // First frame — store a copy of the embedding directly.
+            this._centroids.set(speakerId, {
+                embedding: embedding.slice(),
+                count: 1,
+            });
+            return;
+        }
+        // Online running average: mean_n = mean_{n-1} + (x - mean_{n-1}) / n
+        const newCount = existing.count + 1;
+        const newEmbedding = new Float32Array(existing.embedding.length);
+        for (let i = 0; i < existing.embedding.length; i++) {
+            newEmbedding[i] = existing.embedding[i] + (embedding[i] - existing.embedding[i]) / newCount;
+        }
+        this._centroids.set(speakerId, { embedding: newEmbedding, count: newCount });
+    }
+    /**
+     * Find the existing speaker whose centroid is most similar to `embedding`.
+     *
+     * Returns `null` if no speaker exceeds the similarity threshold or the cache
+     * is empty.
+     *
+     * @param embedding - Query embedding vector.
+     * @returns Best match above threshold, or `null`.
+     */
+    findClosestSpeaker(embedding) {
+        let bestId = null;
+        let bestSim = -Infinity;
+        for (const [id, entry] of this._centroids) {
+            const sim = cosineSimilarity(embedding, entry.embedding);
+            if (sim > bestSim) {
+                bestSim = sim;
+                bestId = id;
+            }
+        }
+        if (bestId === null || bestSim < this.threshold) {
+            return null;
+        }
+        return { speakerId: bestId, similarity: bestSim };
+    }
+    /**
+     * Look up or create a speaker identity for `embedding`.
+     *
+     * If a match above the threshold is found, the centroid is updated and the
+     * existing ID is returned.  Otherwise a new `Speaker_N` identity is
+     * registered.
+     *
+     * @param embedding - Audio embedding to resolve.
+     * @returns Speaker ID and whether a new identity was created.
+     */
+    getOrCreateSpeaker(embedding) {
+        const match = this.findClosestSpeaker(embedding);
+        if (match) {
+            this.addEmbedding(match.speakerId, embedding);
+            return { speakerId: match.speakerId, isNew: false };
+        }
+        const newId = `Speaker_${this._centroids.size}`;
+        this.addEmbedding(newId, embedding);
+        return { speakerId: newId, isNew: true };
+    }
+    /**
+     * Pre-register a known speaker voiceprint, overwriting any existing centroid
+     * for this ID.
+     *
+     * Use this to seed the cache with enrolment recordings before a session
+     * begins so that known participants are matched by name rather than the
+     * auto-generated `Speaker_N` label.
+     *
+     * @param id - Human-readable speaker identifier.
+     * @param voiceprint - Reference embedding for this speaker.
+     */
+    enrollSpeaker(id, voiceprint) {
+        this._centroids.set(id, { embedding: voiceprint.slice(), count: 1 });
+    }
+    // -------------------------------------------------------------------------
+    // Accessors (useful for testing and ClusteringStrategy)
+    // -------------------------------------------------------------------------
+    /**
+     * Read-only view of the internal centroid map.
+     *
+     * Returns a snapshot — modifications to the returned map do not affect the
+     * cache.
+     */
+    get centroids() {
+        const result = new Map();
+        for (const [id, entry] of this._centroids) {
+            result.set(id, entry.embedding.slice());
+        }
+        return result;
+    }
+    /** Number of distinct speaker identities currently tracked. */
+    get size() {
+        return this._centroids.size;
+    }
+    /**
+     * Remove all centroids from the cache.
+     *
+     * Useful for resetting state between test cases.
+     */
+    clear() {
+        this._centroids.clear();
+    }
+}
+//# sourceMappingURL=SpeakerEmbeddingCache.js.map

package/dist/SpeakerEmbeddingCache.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Diarization extension pack.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createDiarizationEngine } from '@framers/agentos-ext-diarization';
+ *
+ * const engine = createDiarizationEngine();
+ * const session = engine.startSession({ backend: 'local' });
+ * session.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-diarization" }] }
+ * ```
+ *
+ * @module diarization
+ */
+import { DiarizationEngine } from './DiarizationEngine.js';
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+    id: string;
+    kind: string;
+    payload: unknown;
+    enableByDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+    id: string;
+    descriptors: ExtensionDescriptor[];
+}
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+    getSecret?: (id: string) => string | undefined;
+    options?: Record<string, unknown>;
+}
+/**
+ * Create a standalone {@link DiarizationEngine} instance.
+ *
+ * Use this when composing the engine programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @returns A configured {@link DiarizationEngine}.
+ */
+export declare function createDiarizationEngine(): DiarizationEngine;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Returns an {@link ExtensionPack} containing a single `diarization-provider`
+ * descriptor backed by {@link DiarizationEngine}.
+ *
+ * @param _context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(_context: ExtensionPackContext): ExtensionPack;
+export * from './types.js';
+export { DiarizationEngine } from './DiarizationEngine.js';
+export { DiarizationSession } from './DiarizationSession.js';
+export { SpeakerEmbeddingCache, cosineSimilarity } from './SpeakerEmbeddingCache.js';
+export { ClusteringStrategy } from './ClusteringStrategy.js';
+export { SlidingWindowExtractor } from './SlidingWindowExtractor.js';
+export { ProviderDiarizationBackend } from './ProviderDiarizationBackend.js';
+export { LocalDiarizationBackend } from './LocalDiarizationBackend.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAM3D,2DAA2D;AAC3D,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,4DAA4D;AAC5D,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AASD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,aAAa,CAejF;AAMD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Diarization extension pack.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createDiarizationEngine } from '@framers/agentos-ext-diarization';
+ *
+ * const engine = createDiarizationEngine();
+ * const session = engine.startSession({ backend: 'local' });
+ * session.on('speaker_identified', ({ speakerId }) => console.log(speakerId));
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-diarization" }] }
+ * ```
+ *
+ * @module diarization
+ */
+import { DiarizationEngine } from './DiarizationEngine.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_DIARIZATION = 'diarization-provider';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link DiarizationEngine} instance.
+ *
+ * Use this when composing the engine programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @returns A configured {@link DiarizationEngine}.
+ */
+export function createDiarizationEngine() {
+    return new DiarizationEngine();
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Returns an {@link ExtensionPack} containing a single `diarization-provider`
+ * descriptor backed by {@link DiarizationEngine}.
+ *
+ * @param _context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(_context) {
+    const engine = new DiarizationEngine();
+    return {
+        id: 'diarization',
+        descriptors: [
+            {
+                id: 'diarization-engine',
+                kind: EXTENSION_KIND_DIARIZATION,
+                payload: engine,
+                enableByDefault: true,
+                metadata: { providerId: 'diarization-local' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export * from './types.js';
+export { DiarizationEngine } from './DiarizationEngine.js';
+export { DiarizationSession } from './DiarizationSession.js';
+export { SpeakerEmbeddingCache, cosineSimilarity } from './SpeakerEmbeddingCache.js';
+export { ClusteringStrategy } from './ClusteringStrategy.js';
+export { SlidingWindowExtractor } from './SlidingWindowExtractor.js';
+export { ProviderDiarizationBackend } from './ProviderDiarizationBackend.js';
+export { LocalDiarizationBackend } from './LocalDiarizationBackend.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA2B3D,uEAAuE;AACvE,MAAM,0BAA0B,GAAG,sBAAsB,CAAC;AAE1D,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,iBAAiB,EAAE,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA8B;IAChE,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAEvC,OAAO;QACL,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,oBAAoB;gBACxB,IAAI,EAAE,0BAA0B;gBAChC,OAAO,EAAE,MAAM;gBACf,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,mBAAmB,EAAE;aAC9C;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @file types.ts
+ * @description Core types for the diarization extension pack.
+ *
+ * These types define the public contract shared between the engine, session
+ * implementations, and calling code.  They intentionally avoid importing from
+ * `@framers/agentos` so the pack can boot in environments where the core
+ * package is not yet available.
+ *
+ * @module diarization/types
+ */
+import type { EventEmitter } from 'node:events';
+/**
+ * Minimal audio frame type used by the diarization pipeline.
+ *
+ * Matches the `AudioFrame` shape from `@framers/agentos` voice types so that
+ * frames can be forwarded without conversion.
+ */
+export interface AudioFrame {
+    /** Raw 32-bit float PCM samples, normalised to the range `[-1, 1]`. */
+    samples: Float32Array;
+    /** Sample rate in Hz (e.g. 16000). */
+    sampleRate: number;
+    /** Wall-clock timestamp in milliseconds when the frame was captured. */
+    timestamp: number;
+}
+/**
+ * A single word or token produced by an STT provider, optionally annotated
+ * with a speaker label.
+ */
+export interface TranscriptWord {
+    /** The recognised word text. */
+    word: string;
+    /** Start time of the word in seconds (relative to session start). */
+    start: number;
+    /** End time of the word in seconds (relative to session start). */
+    end: number;
+    /** Provider-assigned speaker label, e.g. `'0'` or `'Speaker_1'`. */
+    speaker?: string;
+    /** Per-word confidence in the range `[0, 1]`. */
+    confidence?: number;
+}
+/**
+ * A transcript event as emitted by an STT provider session.
+ *
+ * Diarization operates on these events when running in provider-delegated
+ * mode; the `words` array carries word-level speaker annotations.
+ */
+export interface TranscriptEvent {
+    /** Full transcript text for this event. */
+    text: string;
+    /** Whether this is a finalised (stable) transcript hypothesis. */
+    isFinal: boolean;
+    /** Word-level tokens with optional speaker labels. */
+    words?: TranscriptWord[];
+    /** Session-relative timestamp in milliseconds. */
+    timestamp: number;
+}
+/**
+ * A contiguous audio or text segment attributed to a single speaker.
+ */
+export interface DiarizedSegment {
+    /** Resolved speaker identifier (e.g. `'Alice'` or `'Speaker_0'`). */
+    speakerId: string;
+    /** Transcript text for this segment, if available. */
+    text?: string;
+    /** Segment start time in milliseconds (wall clock). */
+    startMs: number;
+    /** Segment end time in milliseconds (wall clock). */
+    endMs: number;
+    /** Confidence score for the speaker attribution in the range `[0, 1]`. */
+    confidence: number;
+}
+/**
+ * Payload for the `speaker_identified` event emitted by a
+ * {@link IDiarizationSession}.
+ */
+export interface SpeakerIdentified {
+    /** Resolved speaker identifier. */
+    speakerId: string;
+    /** Confidence in the range `[0, 1]`. */
+    confidence: number;
+    /** Wall-clock timestamp in milliseconds when this identification was made. */
+    timestamp: number;
+}
+/**
+ * Configuration object for {@link IDiarizationEngine.startSession}.
+ */
+export interface DiarizationConfig {
+    /**
+     * Backend to use.
+     * - `'provider'` — extract speaker labels from STT provider word results.
+     * - `'local'` — use the built-in spectral-centroid sliding-window backend.
+     * @defaultValue 'local'
+     */
+    backend?: 'provider' | 'local';
+    /**
+     * Cosine similarity threshold for speaker matching.
+     * Embeddings with similarity above this value are attributed to the same
+     * speaker.
+     * @defaultValue 0.7
+     */
+    similarityThreshold?: number;
+    /**
+     * Hint for the clustering strategy — how many distinct speakers are expected
+     * in this session.  When set, the engine will try to merge centroids until
+     * this count is reached.
+     */
+    expectedSpeakers?: number;
+    /**
+     * Chunk duration in milliseconds for the sliding-window extractor.
+     * @defaultValue 1500
+     */
+    chunkSizeMs?: number;
+    /**
+     * Overlap between consecutive chunks in milliseconds.
+     * @defaultValue 500
+     */
+    overlapMs?: number;
+    /**
+     * Audio sample rate in Hz.
+     * @defaultValue 16000
+     */
+    sampleRate?: number;
+}
+/**
+ * A live diarization session.
+ *
+ * Extends `EventEmitter` so callers can subscribe to `speaker_identified`,
+ * `segment_ready`, `error`, and `close` events.
+ */
+export interface IDiarizationSession extends EventEmitter {
+    /**
+     * Push a raw audio frame into the diarization pipeline.
+     *
+     * In local mode, frames are accumulated in a sliding window and processed
+     * when a full chunk is ready.  In provider mode, this is a no-op (speaker
+     * labels come from {@link labelTranscript}).
+     */
+    pushAudio(frame: AudioFrame): void;
+    /**
+     * Attach provider-supplied speaker labels to a transcript event and return
+     * the resulting {@link DiarizedSegment} (if enough information is present).
+     *
+     * In provider mode this is the primary data path.  In local mode, the engine
+     * merges the text with the most recent speaker identification.
+     */
+    labelTranscript(event: TranscriptEvent): DiarizedSegment | null;
+    /**
+     * Pre-register a known speaker voiceprint so the engine can label them by
+     * name rather than an auto-generated `Speaker_N` identifier.
+     *
+     * @param id - Human-readable speaker name or identifier.
+     * @param voiceprint - 32-bit float embedding vector representing the
+     *   speaker's vocal characteristics.
+     */
+    enrollSpeaker(id: string, voiceprint: Float32Array): void;
+    /**
+     * Terminate the session and release all resources.
+     *
+     * After `close()` is called, no further events will be emitted.
+     */
+    close(): void;
+}
+/**
+ * Factory interface for creating diarization sessions.
+ */
+export interface IDiarizationEngine {
+    /**
+     * Create and start a new {@link IDiarizationSession}.
+     *
+     * @param config - Optional session configuration.
+     * @returns A ready-to-use diarization session.
+     */
+    startSession(config?: DiarizationConfig): IDiarizationSession;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,OAAO,EAAE,YAAY,CAAC;IACtB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD;;;;;;OAMG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEnC;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CAAC;IAEhE;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAE1D;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,YAAY,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;CAC/D"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * @file types.ts
+ * @description Core types for the diarization extension pack.
+ *
+ * These types define the public contract shared between the engine, session
+ * implementations, and calling code.  They intentionally avoid importing from
+ * `@framers/agentos` so the pack can boot in environments where the core
+ * package is not yet available.
+ *
+ * @module diarization/types
+ */
+export {};
+//# sourceMappingURL=types.js.map