@adonis-agora/agent 0.1.0

package/dist/src/rag-media/diagnostics.js

@@ -0,0 +1,36 @@
+/**
+ * The `@adonis-agora/diagnostics` emit capability, published on this global slot at that package's
+ * module load. This bridge reads it STRUCTURALLY — it never imports or depends on the diagnostics
+ * package. When diagnostics isn't installed the slot is empty and emitting is an inert no-op that never
+ * throws back into an ingestion. Events land on `agora:rag:media.*`; the payload shapes below are the
+ * contract every observer (Telescope / dashboard) reads. Mirrors the agent core's `diagnostics.ts`.
+ */
+const EMIT_SLOT = Symbol.for('@agora/diagnostics:emit');
+/**
+ * Publish a rag-media event on `agora:rag:<event>` via the structural diagnostics slot. No-op when
+ * diagnostics isn't installed (the slot is empty) — and it never throws back into an ingestion.
+ */
+export function publishRagMedia(event, payload) {
+    const emit = globalThis[EMIT_SLOT];
+    if (typeof emit === 'function') {
+        try {
+            emit('rag', event, payload);
+        }
+        catch {
+            // diagnostics must never break an ingestion
+        }
+    }
+}
+export function publishRagMediaIngested(payload) {
+    publishRagMedia('media.ingested', payload);
+}
+export function publishRagMediaRemoved(payload) {
+    publishRagMedia('media.removed', payload);
+}
+export function publishRagMediaSkipped(payload) {
+    publishRagMedia('media.skipped', payload);
+}
+export function publishRagMediaFailed(payload) {
+    publishRagMedia('media.failed', payload);
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/src/rag-media/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/rag-media/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;AAwCxD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,KAAQ,EACR,OAAsC;IAEtC,MAAM,IAAI,GAAI,UAAsC,CAAC,SAAS,CAAuB,CAAC;IACtF,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,4CAA4C;QAC9C,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAgC;IACtE,eAAe,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AACD,MAAM,UAAU,sBAAsB,CAAC,OAA+B;IACpE,eAAe,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AACD,MAAM,UAAU,sBAAsB,CAAC,OAA+B;IACpE,eAAe,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,OAA8B;IAClE,eAAe,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/src/rag-media/index.d.ts

@@ -0,0 +1,5 @@
+export { type TextExtractor, type ExtractFn, MimeTextExtractor, UnsupportedContentTypeError, defaultTextExtractor, normalizeContentType, decodeUtf8, extractHtmlText, } from './text-extractor.js';
+export { UPLOAD_COMPLETE_CHANNEL, type UploadCompletePayload, envelopePayload, isUploadCompleteEvent, } from './media-events.js';
+export { mediaRagIngestion, MediaRagIngestion, MediaRagResolveRequiredError, type MediaRagIngestionConfig, type MediaManagerHandle, type DiskBytesReader, type MediaRef, type MediaIngestResult, type MediaIngestSkipReason, type ResolveMediaRef, } from './media-rag-ingestion.js';
+export { publishRagMedia, publishRagMediaIngested, publishRagMediaRemoved, publishRagMediaSkipped, publishRagMediaFailed, type RagMediaDiagnosticEvent, type RagMediaDiagnosticPayloads, type RagMediaIngestedPayload, type RagMediaRemovedPayload, type RagMediaSkippedPayload, type RagMediaFailedPayload, type RagMediaSkipReason, } from './diagnostics.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/rag-media/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag-media/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EACvB,KAAK,qBAAqB,EAC1B,eAAe,EACf,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,GACrB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC"}

package/dist/src/rag-media/index.js

@@ -0,0 +1,5 @@
+export { MimeTextExtractor, UnsupportedContentTypeError, defaultTextExtractor, normalizeContentType, decodeUtf8, extractHtmlText, } from './text-extractor.js';
+export { UPLOAD_COMPLETE_CHANNEL, envelopePayload, isUploadCompleteEvent, } from './media-events.js';
+export { mediaRagIngestion, MediaRagIngestion, MediaRagResolveRequiredError, } from './media-rag-ingestion.js';
+export { publishRagMedia, publishRagMediaIngested, publishRagMediaRemoved, publishRagMediaSkipped, publishRagMediaFailed, } from './diagnostics.js';
+//# sourceMappingURL=index.js.map

package/dist/src/rag-media/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag-media/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,iBAAiB,EACjB,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,EACpB,UAAU,EACV,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,uBAAuB,EAEvB,eAAe,EACf,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,4BAA4B,GAQ7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,GAQtB,MAAM,kBAAkB,CAAC"}

package/dist/src/rag-media/media-events.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `@adonis-agora/media` diagnostics contract this bridge reads, re-declared here so the
+ * integration couples to the *wire contract* (the `agora:media:*` channel) rather than importing the
+ * media package — `@adonis-agora/media` stays an OPTIONAL, structurally-typed peer. Keep these mirrors
+ * in sync with that library's core `diagnostics.ts` (`UploadCompletePayload`).
+ */
+/** The channel a media library publishes `upload.complete` on: `agora:media:upload.complete`. */
+export declare const UPLOAD_COMPLETE_CHANNEL = "agora:media:upload.complete";
+/**
+ * Emitted on `agora:media:upload.complete` when a stored upload finishes. It carries only the media
+ * record `id`, the storage `disk`, and the object `key` — NOT the owner/collection/content-type — so
+ * auto-ingesting it needs a `resolve` seam back to the media record (see
+ * {@link import('./media-rag-ingestion.js').MediaRagIngestionConfig.resolve}).
+ */
+export interface UploadCompletePayload {
+    id: string;
+    disk: string;
+    key: string;
+}
+/** Pull `.payload` off a diagnostics-channel message without an unguarded cast. */
+export declare function envelopePayload(message: unknown): unknown;
+export declare function isUploadCompleteEvent(payload: unknown): payload is UploadCompletePayload;
+//# sourceMappingURL=media-events.d.ts.map

package/dist/src/rag-media/media-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-events.d.ts","sourceRoot":"","sources":["../../../src/rag-media/media-events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iGAAiG;AACjG,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAOD,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKzD;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,qBAAqB,CAUxF"}

package/dist/src/rag-media/media-events.js

@@ -0,0 +1,28 @@
+/**
+ * The `@adonis-agora/media` diagnostics contract this bridge reads, re-declared here so the
+ * integration couples to the *wire contract* (the `agora:media:*` channel) rather than importing the
+ * media package — `@adonis-agora/media` stays an OPTIONAL, structurally-typed peer. Keep these mirrors
+ * in sync with that library's core `diagnostics.ts` (`UploadCompletePayload`).
+ */
+/** The channel a media library publishes `upload.complete` on: `agora:media:upload.complete`. */
+export const UPLOAD_COMPLETE_CHANNEL = 'agora:media:upload.complete';
+/** Pull `.payload` off a diagnostics-channel message without an unguarded cast. */
+export function envelopePayload(message) {
+    if (typeof message === 'object' && message !== null && 'payload' in message) {
+        return message.payload;
+    }
+    return undefined;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isUploadCompleteEvent(payload) {
+    if (typeof payload !== 'object' || payload === null) {
+        return false;
+    }
+    const candidate = payload;
+    return (isNonEmptyString(candidate.id) &&
+        isNonEmptyString(candidate.disk) &&
+        isNonEmptyString(candidate.key));
+}
+//# sourceMappingURL=media-events.js.map

package/dist/src/rag-media/media-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-events.js","sourceRoot":"","sources":["../../../src/rag-media/media-events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iGAAiG;AACjG,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AAmBrE,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;QAC5E,OAAQ,OAA8B,CAAC,OAAO,CAAC;IACjD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACpD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,SAAS,GAAG,OAAkC,CAAC;IACrD,OAAO,CACL,gBAAgB,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC;QAChC,gBAAgB,CAAC,SAAS,CAAC,GAAG,CAAC,CAChC,CAAC;AACJ,CAAC"}

package/dist/src/rag-media/media-rag-ingestion.d.ts

@@ -0,0 +1,155 @@
+import type { ChunkOptions } from '../rag/chunk.js';
+import type { VectorStore } from '../rag/vector-store.js';
+import type { EmbeddingProvider } from '../spi/embedding-provider.js';
+import { type UploadCompletePayload } from './media-events.js';
+import { type TextExtractor } from './text-extractor.js';
+/** The minimal, structural slice of an `@adonis-agora/media` disk this bridge reads bytes from. */
+export interface DiskBytesReader {
+    /** Return the object's raw bytes (a media disk's `getBytes(key)`). */
+    getBytes(key: string): Promise<Uint8Array>;
+}
+/**
+ * The minimal, structural slice of an `@adonis-agora/media` `MediaManager` this bridge needs — just
+ * `disk(name)` yielding a {@link DiskBytesReader}. Structural typing keeps `@adonis-agora/media` an
+ * OPTIONAL peer: nothing is imported from it, an app passes its live `MediaManager` (or any handle that
+ * satisfies this shape) at wiring time.
+ */
+export interface MediaManagerHandle {
+    disk(name?: string): DiskBytesReader;
+}
+/**
+ * A media file to ingest. `id` becomes the RAG document id (chunk ids `${id}#<n>`); `disk`/`key` locate
+ * the bytes through the {@link MediaManagerHandle}; `contentType` drives extractor dispatch. The owner /
+ * tenant fields are optional and, when present, tag every chunk's metadata so retrieval can filter by
+ * tenant/owner/collection.
+ */
+export interface MediaRef {
+    id: string;
+    disk: string;
+    key: string;
+    contentType: string;
+    ownerType?: string;
+    ownerId?: string;
+    collection?: string;
+    tenantRef?: string;
+    /** Byte size, when known up front — used only by the `maxBytes` gate; the bytes are the source of truth. */
+    size?: number;
+}
+export type MediaIngestSkipReason = 'unsupported-type' | 'too-large' | 'empty-text';
+export type MediaIngestResult = {
+    status: 'ingested';
+    chunks: number;
+} | {
+    status: 'skipped';
+    reason: MediaIngestSkipReason;
+};
+/** Turn an `upload.complete` diagnostics payload into an ingestable {@link MediaRef}, or `null` to skip. */
+export type ResolveMediaRef = (payload: UploadCompletePayload) => MediaRef | null | Promise<MediaRef | null>;
+/**
+ * Everything the media→RAG bridge needs. Only `media`, `embedder`, and `store` are required; the
+ * extractor defaults to {@link defaultTextExtractor} (text/*, JSON, HTML) so binary formats are skipped
+ * rather than indexed as garbage. Register a PDF/DOCX parser on a {@link import('./text-extractor.js').MimeTextExtractor}
+ * and pass it as `extractor` — the PDF library stays entirely on the host side (never a dependency here).
+ */
+export interface MediaRagIngestionConfig {
+    /** The media handle bytes are read through (an `@adonis-agora/media` `MediaManager`, structurally typed). */
+    media: MediaManagerHandle;
+    /** Embeds each chunk. Pass the same {@link EmbeddingProvider} the agent's retriever uses. */
+    embedder: EmbeddingProvider;
+    /** The RAG vector store chunks are upserted into (the same store the retriever searches). */
+    store: VectorStore;
+    /** Bytes → text. Default {@link defaultTextExtractor}. Register a PDF/DOCX hook to widen it. */
+    extractor?: TextExtractor;
+    /**
+     * Restrict ingestion to these content types (checked before the extractor). Omit/empty = every type
+     * the extractor supports. A content type not in this allow-list is skipped as `unsupported-type`.
+     */
+    contentTypes?: string[];
+    /** Chunking options forwarded to `chunkDocuments`. */
+    chunk?: ChunkOptions;
+    /** Skip (don't read) files larger than this many bytes (checked against `ref.size` when present). */
+    maxBytes?: number;
+    /**
+     * Resolve an `upload.complete` diagnostics payload (`{ id, disk, key }`) into a full {@link MediaRef}
+     * — the seam the auto-subscriber needs, since the event carries no content-type or owner metadata.
+     * Required to call {@link MediaRagIngestion.subscribe}; return `null` to skip an event.
+     */
+    resolve?: ResolveMediaRef;
+}
+/** Thrown by {@link MediaRagIngestion.subscribe} when no `resolve` seam was configured. */
+export declare class MediaRagResolveRequiredError extends Error {
+    constructor();
+}
+/**
+ * Bridges `@adonis-agora/media` uploads into the agent's RAG stack: fetch the bytes → extract text by
+ * content type → chunk → embed → upsert into the configured {@link VectorStore}, tagging every chunk
+ * with `{ mediaId, ownerType, ownerId, collection, tenantRef }` so retrieval can be scoped per
+ * tenant/owner/collection. Two triggers, both opt-in and no-op until wired:
+ *
+ * - {@link ingestMedia} — call it explicitly with a {@link MediaRef} (e.g. from your own upload flow).
+ * - {@link subscribe} — subscribe to the media library's `agora:media:upload.complete` diagnostics
+ *   channel and auto-ingest each finished upload (needs a `resolve` seam).
+ *
+ * Everything is structural: no import of `@adonis-agora/media`, and `node:diagnostics_channel` is a
+ * Node builtin, so there is no hard dependency on `@adonis-agora/diagnostics` for the subscribe path.
+ */
+export declare class MediaRagIngestion {
+    private readonly config;
+    private readonly extractor;
+    private readonly contentTypes;
+    private readonly inFlight;
+    private teardown;
+    constructor(config: MediaRagIngestionConfig);
+    /**
+     * Ingest one media file: content-type filter → size gate → read bytes → extract → remove-then-chunk
+     * → embed → upsert. Unsupported/oversized/empty files are skipped (not errors). Chunk metadata carries
+     * `{ mediaId, ownerType, ownerId, collection, tenantRef }` (only the fields present on `ref`).
+     */
+    ingestMedia(ref: MediaRef): Promise<MediaIngestResult>;
+    /** Drop a media document's chunks from the vector store — the delete half of keeping RAG in sync. */
+    removeMedia(mediaId: string): Promise<void>;
+    /**
+     * Guard + resolve + ingest one `upload.complete` diagnostics payload. Public so a caller can await it
+     * directly (deterministic tests) instead of going through the subscription. A no-op when `resolve`
+     * isn't configured, the payload isn't a valid `upload.complete`, or `resolve` returns `null`.
+     */
+    handleUploadComplete(payload: unknown): Promise<MediaIngestResult | undefined>;
+    /**
+     * Subscribe to the media library's `agora:media:upload.complete` channel and auto-ingest each finished
+     * upload. Idempotent (a second call is a no-op while already subscribed). Returns — and stores — an
+     * unsubscribe function; ingestion errors are caught and published on `agora:rag:media.failed` so a bad
+     * file never breaks the channel. Requires a `resolve` seam ({@link MediaRagResolveRequiredError}).
+     */
+    subscribe(): () => void;
+    /** Unsubscribe from the media channel (if subscribed) and await every in-flight auto-ingestion. */
+    unsubscribe(): Promise<void>;
+    /** Await every in-flight auto-ingestion — for graceful shutdown and deterministic tests. */
+    settle(): Promise<void>;
+    /** Whether the auto-subscriber is currently attached to the media channel. */
+    get subscribed(): boolean;
+    /** Handle one channel event with the same error boundary the subscriber uses. */
+    private ingestFromEvent;
+    private track;
+}
+/**
+ * Build a media→RAG ingestion bridge (idiomatic factory). Wire it in a provider's `boot()`:
+ *
+ * ```ts
+ * import { mediaRagIngestion } from '@adonis-agora/agent/rag-media'
+ *
+ * const ingestion = mediaRagIngestion({
+ *   media: await app.container.make('media.manager'),
+ *   embedder: myEmbedder,
+ *   store: myVectorStore,
+ *   contentTypes: ['text/plain', 'text/markdown', 'application/pdf'],
+ *   extractor: defaultTextExtractor().register('application/pdf', myPdfExtractor),
+ *   resolve: async ({ id, disk, key }) => lookupMediaRecord(id), // → MediaRef
+ * })
+ * const off = ingestion.subscribe() // auto-ingest on upload.complete
+ * ```
+ *
+ * Or trigger it explicitly: `await ingestion.ingestMedia(ref)`. Everything is opt-in and no-op until
+ * wired — nothing runs, subscribes, or imports the media/pdf peers unless you call it.
+ */
+export declare function mediaRagIngestion(config: MediaRagIngestionConfig): MediaRagIngestion;
+//# sourceMappingURL=media-rag-ingestion.d.ts.map

package/dist/src/rag-media/media-rag-ingestion.d.ts.map

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

package/dist/src/rag-media/media-rag-ingestion.js

@@ -0,0 +1,204 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { chunkDocuments, ingestChunks } from '../rag/ingest.js';
+import { publishRagMediaFailed, publishRagMediaIngested, publishRagMediaRemoved, publishRagMediaSkipped, } from './diagnostics.js';
+import { UPLOAD_COMPLETE_CHANNEL, envelopePayload, isUploadCompleteEvent, } from './media-events.js';
+import { UnsupportedContentTypeError, defaultTextExtractor, normalizeContentType, } from './text-extractor.js';
+/** Thrown by {@link MediaRagIngestion.subscribe} when no `resolve` seam was configured. */
+export class MediaRagResolveRequiredError extends Error {
+    constructor() {
+        super('mediaRagIngestion: subscribe() needs a `resolve` in the config to turn an upload.complete ' +
+            'payload ({ id, disk, key }) into a MediaRef with contentType/owner metadata.');
+        this.name = 'MediaRagResolveRequiredError';
+    }
+}
+/**
+ * Bridges `@adonis-agora/media` uploads into the agent's RAG stack: fetch the bytes → extract text by
+ * content type → chunk → embed → upsert into the configured {@link VectorStore}, tagging every chunk
+ * with `{ mediaId, ownerType, ownerId, collection, tenantRef }` so retrieval can be scoped per
+ * tenant/owner/collection. Two triggers, both opt-in and no-op until wired:
+ *
+ * - {@link ingestMedia} — call it explicitly with a {@link MediaRef} (e.g. from your own upload flow).
+ * - {@link subscribe} — subscribe to the media library's `agora:media:upload.complete` diagnostics
+ *   channel and auto-ingest each finished upload (needs a `resolve` seam).
+ *
+ * Everything is structural: no import of `@adonis-agora/media`, and `node:diagnostics_channel` is a
+ * Node builtin, so there is no hard dependency on `@adonis-agora/diagnostics` for the subscribe path.
+ */
+export class MediaRagIngestion {
+    config;
+    extractor;
+    contentTypes;
+    inFlight = new Set();
+    teardown = null;
+    constructor(config) {
+        this.config = config;
+        this.extractor = config.extractor ?? defaultTextExtractor();
+        this.contentTypes =
+            config.contentTypes !== undefined && config.contentTypes.length > 0
+                ? new Set(config.contentTypes.map((type) => normalizeContentType(type)))
+                : null;
+    }
+    /**
+     * Ingest one media file: content-type filter → size gate → read bytes → extract → remove-then-chunk
+     * → embed → upsert. Unsupported/oversized/empty files are skipped (not errors). Chunk metadata carries
+     * `{ mediaId, ownerType, ownerId, collection, tenantRef }` (only the fields present on `ref`).
+     */
+    async ingestMedia(ref) {
+        const contentType = normalizeContentType(ref.contentType);
+        if (this.contentTypes !== null && !this.contentTypes.has(contentType)) {
+            publishRagMediaSkipped({ mediaId: ref.id, contentType, reason: 'unsupported-type' });
+            return { status: 'skipped', reason: 'unsupported-type' };
+        }
+        if (this.config.maxBytes !== undefined &&
+            ref.size !== undefined &&
+            ref.size > this.config.maxBytes) {
+            publishRagMediaSkipped({ mediaId: ref.id, contentType, reason: 'too-large' });
+            return { status: 'skipped', reason: 'too-large' };
+        }
+        let text;
+        try {
+            const bytes = await this.config.media.disk(ref.disk).getBytes(ref.key);
+            text = await this.extractor.extract(Buffer.from(bytes), ref.contentType);
+        }
+        catch (error) {
+            if (error instanceof UnsupportedContentTypeError) {
+                publishRagMediaSkipped({ mediaId: ref.id, contentType, reason: 'unsupported-type' });
+                return { status: 'skipped', reason: 'unsupported-type' };
+            }
+            throw error;
+        }
+        if (text.trim() === '') {
+            publishRagMediaSkipped({ mediaId: ref.id, contentType, reason: 'empty-text' });
+            return { status: 'skipped', reason: 'empty-text' };
+        }
+        // remove-then-ingest so a re-upload that shrinks to fewer chunks doesn't leave a stale tail.
+        await this.config.store.remove(ref.id);
+        const document = {
+            id: ref.id,
+            text,
+            source: ref.key,
+            metadata: {
+                mediaId: ref.id,
+                ...(ref.ownerType !== undefined ? { ownerType: ref.ownerType } : {}),
+                ...(ref.ownerId !== undefined ? { ownerId: ref.ownerId } : {}),
+                ...(ref.collection !== undefined ? { collection: ref.collection } : {}),
+                ...(ref.tenantRef !== undefined ? { tenantRef: ref.tenantRef } : {}),
+            },
+        };
+        const chunks = chunkDocuments([document], this.config.chunk ?? {});
+        const count = await ingestChunks(chunks, {
+            embedder: this.config.embedder,
+            store: this.config.store,
+        });
+        publishRagMediaIngested({
+            mediaId: ref.id,
+            chunks: count,
+            ...(ref.ownerType !== undefined ? { ownerType: ref.ownerType } : {}),
+            ...(ref.ownerId !== undefined ? { ownerId: ref.ownerId } : {}),
+            ...(ref.collection !== undefined ? { collection: ref.collection } : {}),
+            ...(ref.tenantRef !== undefined ? { tenantRef: ref.tenantRef } : {}),
+        });
+        return { status: 'ingested', chunks: count };
+    }
+    /** Drop a media document's chunks from the vector store — the delete half of keeping RAG in sync. */
+    async removeMedia(mediaId) {
+        await this.config.store.remove(mediaId);
+        publishRagMediaRemoved({ mediaId });
+    }
+    /**
+     * Guard + resolve + ingest one `upload.complete` diagnostics payload. Public so a caller can await it
+     * directly (deterministic tests) instead of going through the subscription. A no-op when `resolve`
+     * isn't configured, the payload isn't a valid `upload.complete`, or `resolve` returns `null`.
+     */
+    async handleUploadComplete(payload) {
+        if (this.config.resolve === undefined || !isUploadCompleteEvent(payload)) {
+            return undefined;
+        }
+        const ref = await this.config.resolve(payload);
+        if (ref === null) {
+            return undefined;
+        }
+        return this.ingestMedia(ref);
+    }
+    /**
+     * Subscribe to the media library's `agora:media:upload.complete` channel and auto-ingest each finished
+     * upload. Idempotent (a second call is a no-op while already subscribed). Returns — and stores — an
+     * unsubscribe function; ingestion errors are caught and published on `agora:rag:media.failed` so a bad
+     * file never breaks the channel. Requires a `resolve` seam ({@link MediaRagResolveRequiredError}).
+     */
+    subscribe() {
+        if (this.config.resolve === undefined) {
+            throw new MediaRagResolveRequiredError();
+        }
+        if (this.teardown !== null) {
+            return this.teardown;
+        }
+        const channel = diagnostics_channel.channel(UPLOAD_COMPLETE_CHANNEL);
+        const listener = (message) => {
+            this.track(this.ingestFromEvent(envelopePayload(message)));
+        };
+        channel.subscribe(listener);
+        const teardown = () => {
+            channel.unsubscribe(listener);
+            this.teardown = null;
+        };
+        this.teardown = teardown;
+        return teardown;
+    }
+    /** Unsubscribe from the media channel (if subscribed) and await every in-flight auto-ingestion. */
+    async unsubscribe() {
+        this.teardown?.();
+        await this.settle();
+    }
+    /** Await every in-flight auto-ingestion — for graceful shutdown and deterministic tests. */
+    async settle() {
+        await Promise.allSettled([...this.inFlight]);
+    }
+    /** Whether the auto-subscriber is currently attached to the media channel. */
+    get subscribed() {
+        return this.teardown !== null;
+    }
+    /** Handle one channel event with the same error boundary the subscriber uses. */
+    async ingestFromEvent(payload) {
+        const mediaId = isUploadCompleteEvent(payload) ? payload.id : 'unknown';
+        try {
+            await this.handleUploadComplete(payload);
+        }
+        catch (error) {
+            publishRagMediaFailed({ mediaId, error: errorMessage(error) });
+        }
+    }
+    track(promise) {
+        const tracked = promise.finally(() => {
+            this.inFlight.delete(tracked);
+        });
+        this.inFlight.add(tracked);
+    }
+}
+/**
+ * Build a media→RAG ingestion bridge (idiomatic factory). Wire it in a provider's `boot()`:
+ *
+ * ```ts
+ * import { mediaRagIngestion } from '@adonis-agora/agent/rag-media'
+ *
+ * const ingestion = mediaRagIngestion({
+ *   media: await app.container.make('media.manager'),
+ *   embedder: myEmbedder,
+ *   store: myVectorStore,
+ *   contentTypes: ['text/plain', 'text/markdown', 'application/pdf'],
+ *   extractor: defaultTextExtractor().register('application/pdf', myPdfExtractor),
+ *   resolve: async ({ id, disk, key }) => lookupMediaRecord(id), // → MediaRef
+ * })
+ * const off = ingestion.subscribe() // auto-ingest on upload.complete
+ * ```
+ *
+ * Or trigger it explicitly: `await ingestion.ingestMedia(ref)`. Everything is opt-in and no-op until
+ * wired — nothing runs, subscribes, or imports the media/pdf peers unless you call it.
+ */
+export function mediaRagIngestion(config) {
+    return new MediaRagIngestion(config);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=media-rag-ingestion.js.map

package/dist/src/rag-media/media-rag-ingestion.js.map

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

package/dist/src/rag-media/text-extractor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Turns a media file's raw bytes into the plain text that gets chunked, embedded, and indexed. The
+ * extraction seam — so the RAG stack itself stays format-agnostic. Ships the text-family extractors;
+ * bring your own for PDF/DOCX/etc. by registering a parser on a {@link MimeTextExtractor} (so no PDF
+ * library is ever a hard dependency of `@adonis-agora/agent`). Mirrors the reference `rag-media`
+ * `TextExtractor` contract exactly.
+ */
+export interface TextExtractor {
+    extract(bytes: Buffer, contentType: string): Promise<string>;
+}
+/** Thrown when no extractor is registered for a content type — ingestion treats it as "skip, don't index". */
+export declare class UnsupportedContentTypeError extends Error {
+    readonly contentType: string;
+    constructor(contentType: string);
+}
+/** How a single content type (or `type/*` family) turns bytes into text. */
+export type ExtractFn = (bytes: Buffer, contentType: string) => string | Promise<string>;
+/**
+ * A {@link TextExtractor} that dispatches by content type. Register exact types (`application/json`) or
+ * a whole family (`text/*`); an exact match always wins over a family. Unregistered types throw
+ * {@link UnsupportedContentTypeError}. This is the extension point for binary formats:
+ * `.register('application/pdf', pdfFn)` — the PDF/DOCX library stays entirely on the host side.
+ */
+export declare class MimeTextExtractor implements TextExtractor {
+    private readonly exact;
+    private readonly families;
+    register(contentType: string, fn: ExtractFn): this;
+    extract(bytes: Buffer, contentType: string): Promise<string>;
+    /** Whether a content type would resolve to an extractor (without reading bytes). */
+    supports(contentType: string): boolean;
+    private resolve;
+}
+/** Strip any `; charset=…` parameter off a content type and lower-case it. */
+export declare function normalizeContentType(contentType: string): string;
+/** Decode bytes as UTF-8 — the extractor for `text/*` and JSON. */
+export declare function decodeUtf8(bytes: Buffer): string;
+/** Decode UTF-8 then strip HTML: drop `<script>`/`<style>` bodies and tags, decode common entities. */
+export declare function extractHtmlText(bytes: Buffer): string;
+/**
+ * The default extractor: `text/plain`, `text/csv`, `text/markdown` (and the whole `text/*` family) plus
+ * `application/json` decode as UTF-8, `text/html` is tag-stripped, and everything else — PDF, DOCX,
+ * images — throws {@link UnsupportedContentTypeError} (so binary formats are skipped rather than indexed
+ * as garbage). Extend it for those: `.register('application/pdf', myPdfExtractor)`.
+ */
+export declare function defaultTextExtractor(): MimeTextExtractor;
+//# sourceMappingURL=text-extractor.d.ts.map

package/dist/src/rag-media/text-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-extractor.d.ts","sourceRoot":"","sources":["../../../src/rag-media/text-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED,8GAA8G;AAC9G,qBAAa,2BAA4B,SAAQ,KAAK;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM;gBAAnB,WAAW,EAAE,MAAM;CAIzC;AAED,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEzF;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IAEpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI;IAU5C,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASlE,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAItC,OAAO,CAAC,OAAO;CAYhB;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAarD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAQxD"}