@opengeni/documents 0.2.31 → 0.2.36

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Settings } from '@opengeni/config';
-import { FileAsset, DocumentSearchMode, KnowledgeSourceKind, AddDocumentRequest, Document, CreateDocumentBaseRequest, DocumentBase, DocumentSearchResult } from '@opengeni/contracts';
+import { FileAsset, KnowledgeSourceKind, DocumentSearchMode, AddDocumentRequest, DocumentCurationStatus, Document, CreateDocumentBaseRequest, DocumentBase, DocumentSearchResult } from '@opengeni/contracts';
 import { Database } from '@opengeni/db';
 import { ObjectStorage } from '@opengeni/storage';
 
@@ -8,6 +8,11 @@ declare const DEFAULT_DOCUMENT_EMBEDDING_MODEL = "text-embedding-3-large";
 declare const DEFAULT_DOCUMENT_EMBEDDING_DIMENSIONS = 3072;
 declare const DEFAULT_DOCUMENT_CHUNK_SIZE = 1200;
 declare const DEFAULT_DOCUMENT_CHUNK_OVERLAP = 160;
+declare const DEFAULT_DOCUMENT_CURATION_MODEL = "gpt-4o-mini";
+declare const DOCUMENT_CURATION_MAX_INPUT_CHARS = 24000;
+declare const DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE = 0.75;
+declare const DEFAULT_BASE_NAME = "Default";
+declare const DEFAULT_BASE_DESCRIPTION = "Default base for dropped files and notes.";
 type ParsedDocument = {
     text: string;
     metadata?: Record<string, unknown>;
@@ -29,10 +34,54 @@ type DocumentEmbedder = {
     embedMany: (texts: string[]) => Promise<number[][]>;
     embedQuery: (text: string) => Promise<number[]>;
 };
+type DocumentCurationCandidateBase = {
+    id: string;
+    name: string;
+    description: string | null;
+};
+type DocumentCurationInput = {
+    /** Parsed document text, clipped to DOCUMENT_CURATION_MAX_INPUT_CHARS. */
+    text: string;
+    filename: string;
+    /** Current (usually filename-derived) title. */
+    title: string;
+    /** Candidate bases the document could be filed into (never its current base). */
+    bases: DocumentCurationCandidateBase[];
+};
+type DocumentCurationOutcome = {
+    title: string | null;
+    summary: string | null;
+    sourceKind: KnowledgeSourceKind | null;
+    topics: string[];
+    targetBaseId: string | null;
+    confidence: number;
+    reason: string | null;
+};
+type DocumentCurator = {
+    model: string;
+    curate: (input: DocumentCurationInput) => Promise<DocumentCurationOutcome>;
+};
 type DocumentServices = {
     parser: DocumentParser;
     chunker: DocumentChunker;
     embedder: DocumentEmbedder;
+    /** Optional: names/summarizes/categorizes dropped documents during indexing. */
+    curator?: DocumentCurator | undefined;
+};
+/**
+ * Read-scoping for document queries. Fail-closed: when a caller supplies no
+ * filter, private documents are invisible (only their creator may see them,
+ * and only by passing their subject id).
+ */
+type DocumentAccessFilter = {
+    /** Grant subject id of the human viewer; null/undefined hides private docs. */
+    viewerSubjectId?: string | null | undefined;
+    /**
+     * Agent retrieval surface: only agent-enabled documents. Workspace-visible
+     * documents are available to every agent; private documents are available
+     * only when the agent carries the creating subject as its viewer subject.
+     */
+    agentOnly?: boolean | undefined;
 };
 type DocumentSearchInput = {
     workspaceId: string;
@@ -42,6 +91,7 @@ type DocumentSearchInput = {
     mode?: DocumentSearchMode | undefined;
     sourceKinds?: KnowledgeSourceKind[] | undefined;
     aclTags?: string[] | undefined;
+    access?: DocumentAccessFilter | undefined;
 };
 type DocumentIndexHooks = {
     beforeEmbed?: (input: {
@@ -91,6 +141,37 @@ declare class DeterministicEmbeddingProvider implements DocumentEmbedder {
     embedMany(texts: string[]): Promise<number[][]>;
     embedQuery(text: string): Promise<number[]>;
 }
+/**
+ * Deterministic no-network curation: first meaningful line becomes the title,
+ * the opening text becomes the summary, and the kind is guessed from the
+ * filename/content type. Never proposes a base move (confidence 0). Used as
+ * the `heuristic` provider and as the in-pipeline fallback when the LLM
+ * curator fails — a drop must always end up named and summarized.
+ */
+declare function heuristicCuration(input: DocumentCurationInput, contentType?: string): DocumentCurationOutcome;
+declare class HeuristicCurationProvider implements DocumentCurator {
+    readonly model = "heuristic";
+    curate(input: DocumentCurationInput): Promise<DocumentCurationOutcome>;
+}
+declare class OpenAICurationProvider implements DocumentCurator {
+    private client;
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly defaultHeaders;
+    private readonly defaultQuery;
+    readonly model: string;
+    constructor(args: {
+        apiKey?: string | undefined;
+        baseURL?: string | undefined;
+        defaultHeaders?: Record<string, string> | undefined;
+        defaultQuery?: Record<string, string> | undefined;
+        model?: string | undefined;
+    });
+    curate(input: DocumentCurationInput): Promise<DocumentCurationOutcome>;
+    private openai;
+}
+/** Parse + clamp model output; a targetBaseId outside the candidate list is dropped. */
+declare function parseCurationOutcome(raw: string, bases: DocumentCurationCandidateBase[]): DocumentCurationOutcome;
 declare function createDocumentServices(settings?: Settings, overrides?: Partial<DocumentServices>): DocumentServices;
 declare function documentOpenAIEmbeddingConfig(settings?: Settings): {
     apiKey?: string | undefined;
@@ -104,25 +185,58 @@ declare function createDocumentBase(db: Database, input: CreateDocumentBaseReque
 }): Promise<DocumentBase>;
 declare function listDocumentBases(db: Database, workspaceId: string): Promise<DocumentBase[]>;
 declare function getDocumentBase(db: Database, workspaceId: string, baseId: string): Promise<DocumentBase | null>;
+/**
+ * Find-or-create the workspace's Default base — where knowledge drops land
+ * before configured curation files them elsewhere. Matched by name
+ * (case-insensitive) so a user-created "Default" is adopted rather than
+ * duplicated.
+ */
+declare function ensureDefaultBase(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+}): Promise<DocumentBase>;
 declare function addDocumentToBase(db: Database, input: AddDocumentRequest & {
     accountId: string;
     workspaceId: string;
     baseId: string;
+    createdBy?: string | null | undefined;
+    curationStatus?: DocumentCurationStatus | undefined;
+    access?: DocumentAccessFilter | undefined;
+}): Promise<Document>;
+/**
+ * Move a document and its indexed chunks to another base. With no explicit
+ * target, applies the stored curation suggestion. A 'suggested' or 'pending'
+ * document that gets moved counts as filed.
+ */
+declare function moveDocumentToBase(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    documentId: string;
+    targetBaseId?: string | null | undefined;
+    access?: DocumentAccessFilter | undefined;
 }): Promise<Document>;
 declare function deleteDocumentFromBase(db: Database, input: {
     accountId: string;
     workspaceId: string;
     baseId: string;
     documentId: string;
+    access?: DocumentAccessFilter | undefined;
 }): Promise<void>;
-declare function listDocuments(db: Database, workspaceId: string, baseId: string): Promise<Document[]>;
-declare function getDocument(db: Database, workspaceId: string, documentId: string): Promise<Document | null>;
-declare function queueDocumentForReindex(db: Database, workspaceId: string, documentId: string): Promise<Document>;
+declare function listDocuments(db: Database, workspaceId: string, baseId: string, access?: DocumentAccessFilter): Promise<Document[]>;
+declare function getDocument(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter): Promise<Document | null>;
+declare function queueDocumentForReindex(db: Database, workspaceId: string, documentId: string, access?: DocumentAccessFilter): Promise<Document>;
 declare function indexDocumentNow(db: Database, objectStorage: ObjectStorage, workspaceId: string, documentId: string, services?: DocumentServices, hooks?: DocumentIndexHooks): Promise<Document>;
 declare function searchDocuments(db: Database, input: DocumentSearchInput, services?: Pick<DocumentServices, "embedder">): Promise<DocumentSearchResult[]>;
-declare function getDocumentChunk(db: Database, workspaceId: string, chunkId: string): Promise<DocumentSearchResult | null>;
+declare function getDocumentChunk(db: Database, workspaceId: string, chunkId: string, access?: DocumentAccessFilter): Promise<DocumentSearchResult | null>;
+/** Whether a single already-fetched document is readable by this human viewer. */
+declare function canViewDocument(document: Pick<DocumentAccessRecord, "visibility" | "createdBy">, viewerSubjectId: string | null | undefined): boolean;
+type DocumentAccessRecord = {
+    visibility: string;
+    createdBy: string | null;
+    agentAccess: boolean;
+};
 declare function parseDocumentBytes(bytes: Uint8Array, file: FileAsset, parser?: DocumentParser): Promise<ParsedDocument>;
 declare function chunkText(text: string, maxChars?: number, overlapChars?: number): string[];
 declare function deterministicEmbedding(text: string, dimensions?: number): number[];
 
-export { DEFAULT_DOCUMENT_CHUNK_OVERLAP, DEFAULT_DOCUMENT_CHUNK_SIZE, DEFAULT_DOCUMENT_EMBEDDING_DIMENSIONS, DEFAULT_DOCUMENT_EMBEDDING_MODEL, DEFAULT_DOCUMENT_PARSER, DeterministicEmbeddingProvider, type DocumentChunk, type DocumentChunker, type DocumentEmbedder, type DocumentIndexHooks, type DocumentParser, type DocumentSearchInput, type DocumentServices, LiteParseDocumentParser, OpenAIEmbeddingProvider, type ParsedDocument, RecursiveTextChunker, addDocumentToBase, chunkText, createDocumentBase, createDocumentServices, deleteDocumentFromBase, deterministicEmbedding, documentOpenAIEmbeddingConfig, getDocument, getDocumentBase, getDocumentChunk, indexDocumentNow, listDocumentBases, listDocuments, parseDocumentBytes, queueDocumentForReindex, searchDocuments };
+export { DEFAULT_BASE_DESCRIPTION, DEFAULT_BASE_NAME, DEFAULT_DOCUMENT_CHUNK_OVERLAP, DEFAULT_DOCUMENT_CHUNK_SIZE, DEFAULT_DOCUMENT_CURATION_MODEL, DEFAULT_DOCUMENT_EMBEDDING_DIMENSIONS, DEFAULT_DOCUMENT_EMBEDDING_MODEL, DEFAULT_DOCUMENT_PARSER, DOCUMENT_CURATION_AUTO_FILE_CONFIDENCE, DOCUMENT_CURATION_MAX_INPUT_CHARS, DeterministicEmbeddingProvider, type DocumentAccessFilter, type DocumentChunk, type DocumentChunker, type DocumentCurationCandidateBase, type DocumentCurationInput, type DocumentCurationOutcome, type DocumentCurator, type DocumentEmbedder, type DocumentIndexHooks, type DocumentParser, type DocumentSearchInput, type DocumentServices, HeuristicCurationProvider, LiteParseDocumentParser, OpenAICurationProvider, OpenAIEmbeddingProvider, type ParsedDocument, RecursiveTextChunker, addDocumentToBase, canViewDocument, chunkText, createDocumentBase, createDocumentServices, deleteDocumentFromBase, deterministicEmbedding, documentOpenAIEmbeddingConfig, ensureDefaultBase, getDocument, getDocumentBase, getDocumentChunk, heuristicCuration, indexDocumentNow, listDocumentBases, listDocuments, moveDocumentToBase, parseCurationOutcome, parseDocumentBytes, queueDocumentForReindex, searchDocuments };