@swarmvaultai/engine 0.2.2 → 0.4.0

package/README.md

@@ -186,17 +186,21 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `reloadManagedSources(rootDir, { id, all, compile, brief, maxPages, maxDepth })` re-syncs one managed source or the full registry
 - `deleteManagedSource(rootDir, id)` removes a managed-source registry entry and transient sync state without deleting canonical vault artifacts
 - `ingestInput(rootDir, input, { includeAssets, maxAssetSize })` ingests a local file path or URL
+- `ingestInputDetailed(rootDir, input, { includeAssets, maxAssetSize })` returns a summary envelope with `created`, `updated`, `unchanged`, and `removed` manifests when one input expands into multiple sources
 - `addInput(rootDir, input, { author, contributor })` captures supported URLs into normalized markdown before ingesting them, or falls back to generic URL ingest
 - `ingestDirectory(rootDir, inputDir, { repoRoot, include, exclude, maxFiles, gitignore, extractClasses })` recursively ingests a local directory as a repo-aware code/content source tree
 - `importInbox(rootDir, inputDir?)` recursively imports supported inbox files plus markdown and HTML browser-clipper style bundles
 - managed sources support local directories, public GitHub repo root URLs, and bounded same-domain docs hubs
 - registry data lives in `state/sources.json`, working state lives under `state/sources/<id>/`, and source briefs are written to `wiki/outputs/source-briefs/<id>.md`
+- EPUB inputs split into chapter-level manifests with shared group metadata so books stay navigable instead of becoming one giant source
+- CSV and TSV inputs produce bounded tabular summaries with delimiter-aware previews and compact column hints
+- XLSX inputs extract workbook-level and sheet-level previews, while PPTX inputs extract slide text plus speaker notes when present
 - JavaScript, JSX, TypeScript, TSX, Python, Go, Rust, Java, Kotlin, Scala, Lua, Zig, C#, C, C++, PHP, Ruby, and PowerShell inputs are treated as code sources and compiled into both source pages and `wiki/code/` module pages
 - `.rst` and `.rest` inputs are treated as first-class text sources with lightweight heading and directive normalization before analysis
 - code manifests can carry `repoRelativePath`, and compile writes `state/code-index.json` so local imports can resolve across an ingested repo tree
 - repo-aware manifests, graph nodes, and graph pages can also carry `sourceClass` so first-party, third-party, resource, and generated material can be filtered and reported separately
 - HTML and markdown URL ingests localize remote image references into `raw/assets/<sourceId>/` by default and rewrite the stored markdown to local relative paths
-- PDF and DOCX ingests now write extracted-text and metadata sidecars under `state/extracts/`, and image ingest keeps the same sidecar model for vision extraction
+- PDF, DOCX, EPUB, CSV/TSV, XLSX, and PPTX ingests write extracted-text and metadata sidecars under `state/extracts/`, and image ingest keeps the same sidecar model for vision extraction
 - Tree-sitter-backed languages now verify runtime and grammar compatibility per language; failures stay local to the affected source and surface as diagnostics instead of aborting the whole compile
 
 ### Compile + Query

package/dist/index.d.ts

@@ -54,10 +54,10 @@ type PageStatus = "draft" | "candidate" | "active" | "archived";
 type PageManager = "system" | "human";
 type ApprovalEntryStatus = "pending" | "accepted" | "rejected";
 type ApprovalChangeType = "create" | "update" | "delete" | "promote";
-type SourceKind = "markdown" | "text" | "pdf" | "image" | "html" | "docx" | "binary" | "code";
+type SourceKind = "markdown" | "text" | "pdf" | "image" | "html" | "docx" | "epub" | "csv" | "xlsx" | "pptx" | "transcript" | "chat_export" | "email" | "calendar" | "binary" | "code";
 type SourceCaptureType = "arxiv" | "doi" | "tweet" | "article" | "url";
 type SourceClass = "first_party" | "third_party" | "resource" | "generated";
-type ManagedSourceKind = "directory" | "github_repo" | "crawl_url";
+type ManagedSourceKind = "directory" | "file" | "github_repo" | "crawl_url";
 type ManagedSourceStatus = "ready" | "missing" | "error";
 type CodeLanguage = "javascript" | "jsx" | "typescript" | "tsx" | "python" | "go" | "rust" | "java" | "kotlin" | "scala" | "lua" | "zig" | "csharp" | "c" | "cpp" | "php" | "ruby" | "powershell";
 type CodeSymbolKind = "function" | "class" | "interface" | "type_alias" | "enum" | "variable" | "struct" | "trait";
@@ -231,7 +231,7 @@ interface SourceAttachment {
     mimeType: string;
     originalPath?: string;
 }
-type ExtractionKind = "plain_text" | "html_readability" | "pdf_text" | "docx_text" | "image_vision";
+type ExtractionKind = "plain_text" | "html_readability" | "pdf_text" | "docx_text" | "epub_text" | "csv_text" | "xlsx_text" | "pptx_text" | "transcript_text" | "chat_export_text" | "email_text" | "calendar_text" | "image_vision";
 interface ExtractionTerm {
     name: string;
     description: string;
@@ -284,6 +284,15 @@ interface DirectoryIngestResult {
     updated: SourceManifest[];
     skipped: DirectoryIngestSkip[];
 }
+interface InputIngestResult {
+    input: string;
+    scannedCount: number;
+    created: SourceManifest[];
+    updated: SourceManifest[];
+    unchanged: SourceManifest[];
+    removed: SourceManifest[];
+    skipped: DirectoryIngestSkip[];
+}
 interface SourceManifest {
     sourceId: string;
     title: string;
@@ -302,6 +311,13 @@ interface SourceManifest {
     mimeType: string;
     contentHash: string;
     semanticHash: string;
+    sourceGroupId?: string;
+    sourceGroupTitle?: string;
+    sourcePartKey?: string;
+    partIndex?: number;
+    partCount?: number;
+    partTitle?: string;
+    details?: Record<string, string>;
     createdAt: string;
     updatedAt: string;
     attachments?: SourceAttachment[];
@@ -746,6 +762,7 @@ interface InstallAgentResult {
 interface ManagedSourceAddOptions {
     compile?: boolean;
     brief?: boolean;
+    review?: boolean;
     maxPages?: number;
     maxDepth?: number;
 }
@@ -757,15 +774,25 @@ interface ManagedSourceAddResult {
     source: ManagedSourceRecord;
     compile?: CompileResult;
     briefGenerated: boolean;
+    review?: SourceReviewResult;
 }
 interface ManagedSourceReloadResult {
     sources: ManagedSourceRecord[];
     compile?: CompileResult;
     briefPaths: string[];
+    reviews: SourceReviewResult[];
 }
 interface ManagedSourceDeleteResult {
     removed: ManagedSourceRecord;
 }
+interface SourceReviewResult {
+    sourceId: string;
+    pageId: string;
+    reviewPath: string;
+    staged: boolean;
+    approvalId?: string;
+    approvalDir?: string;
+}
 interface GitHookStatus {
     repoRoot: string | null;
     postCommit: "installed" | "not_installed" | "other_content";
@@ -1206,6 +1233,7 @@ declare function uninstallGitHooks(rootDir: string): Promise<GitHookStatus>;
 declare function listTrackedRepoRoots(rootDir: string): Promise<string[]>;
 declare function syncTrackedRepos(rootDir: string, options?: IngestOptions, repoRoots?: string[]): Promise<RepoSyncResult>;
 declare function syncTrackedReposForWatch(rootDir: string, options?: IngestOptions, repoRoots?: string[]): Promise<WatchRepoSyncResult>;
+declare function ingestInputDetailed(rootDir: string, input: string, options?: IngestOptions): Promise<InputIngestResult>;
 declare function ingestInput(rootDir: string, input: string, options?: IngestOptions): Promise<SourceManifest>;
 declare function addInput(rootDir: string, input: string, options?: AddOptions): Promise<AddResult>;
 declare function ingestDirectory(rootDir: string, inputDir: string, options?: IngestOptions): Promise<DirectoryIngestResult>;
@@ -1242,11 +1270,35 @@ interface LoadedVaultSchemas {
 declare function loadVaultSchemas(rootDir: string): Promise<LoadedVaultSchemas>;
 declare function loadVaultSchema(rootDir: string): Promise<VaultSchema>;
 
+type SourceReviewScope = {
+    id: string;
+    title: string;
+    sourceIds: string[];
+};
+declare function reviewSourceScope(rootDir: string, scope: SourceReviewScope): Promise<SourceReviewResult>;
+declare function reviewManagedSource(rootDir: string, id: string): Promise<SourceReviewResult>;
 declare function listManagedSourceRecords(rootDir: string): Promise<ManagedSourceRecord[]>;
 declare function addManagedSource(rootDir: string, input: string, options?: ManagedSourceAddOptions): Promise<ManagedSourceAddResult>;
 declare function reloadManagedSources(rootDir: string, options?: ManagedSourceReloadOptions): Promise<ManagedSourceReloadResult>;
 declare function deleteManagedSource(rootDir: string, id: string): Promise<ManagedSourceDeleteResult>;
 
+type GeneratedOutputArtifacts = {
+    answer: string;
+    outputAssets: OutputAsset[];
+    assetFiles: Array<{
+        relativePath: string;
+        content: string | Uint8Array;
+        encoding?: BufferEncoding;
+    }>;
+};
+declare function stageGeneratedOutputPages(rootDir: string, stagedPages: Array<{
+    page: GraphPage;
+    content: string;
+    assetFiles?: GeneratedOutputArtifacts["assetFiles"];
+}>): Promise<{
+    approvalId: string;
+    approvalDir: string;
+}>;
 declare function listApprovals(rootDir: string): Promise<ApprovalSummary[]>;
 declare function readApproval(rootDir: string, approvalId: string, options?: {
     diff?: boolean;
@@ -1327,4 +1379,4 @@ declare function getWatchStatus(rootDir: string): Promise<WatchStatusResult>;
 declare function createWebSearchAdapter(id: string, config: WebSearchProviderConfig, rootDir: string): Promise<WebSearchAdapter>;
 declare function getWebSearchAdapterForTask(rootDir: string, task: "deepLintProvider"): Promise<WebSearchAdapter>;
 
-export { type AddOptions, type AddResult, type AgentType, type AnalyzedTerm, type ApprovalChangeType, type ApprovalDetail, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryStatus, type ApprovalManifest, type ApprovalSummary, type BenchmarkArtifact, type BenchmarkOptions, type BenchmarkQuestionResult, type BenchmarkSummary, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, type DirectoryIngestResult, type DirectoryIngestSkip, type EmbeddingCacheArtifact, type EmbeddingCacheEntry, type EvidenceClass, type ExploreOptions, type ExploreResult, type ExploreStepResult, type ExtractionClaim, type ExtractionKind, type ExtractionTerm, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GitHookStatus, type GraphArtifact, type GraphEdge, type GraphExplainNeighbor, type GraphExplainResult, type GraphExportFormat, type GraphExportResult, type GraphHyperedge, type GraphNode, type GraphPage, type GraphPathResult, type GraphPushCounts, type GraphPushNeo4jOptions, type GraphPushResult, type GraphQueryMatch, type GraphQueryResult, type GraphReportArtifact, type ImageGenerationRequest, type ImageGenerationResponse, type ImageVisionExtraction, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type InstallAgentOptions, type InstallAgentResult, type LintFinding, type LintOptions, type ManagedSourceAddOptions, type ManagedSourceAddResult, type ManagedSourceDeleteResult, type ManagedSourceKind, type ManagedSourceRecord, type ManagedSourceReloadOptions, type ManagedSourceReloadResult, type ManagedSourceStatus, type ManagedSourceSyncCounts, type ManagedSourcesArtifact, type Neo4jGraphSinkConfig, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type PendingSemanticRefreshEntry, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type RepoSyncResult, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceCaptureType, type SourceClaim, type SourceClass, type SourceExtractionArtifact, type SourceKind, type SourceManifest, type SourceRationale, type VaultConfig, type WatchController, type WatchOptions, type WatchRepoSyncResult, type WatchRunRecord, type WatchStatusResult, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, addInput, addManagedSource, agentTypeSchema, archiveCandidate, assertProviderCapability, benchmarkVault, bootstrapDemo, compileVault, createMcpServer, createProvider, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, deleteManagedSource, explainGraphVault, exploreVault, exportGraphFormat, exportGraphHtml, getGitHookStatus, getProviderForTask, getWatchStatus, getWebSearchAdapterForTask, getWorkspaceInfo, importInbox, ingestDirectory, ingestInput, initVault, initWorkspace, installAgent, installConfiguredAgents, installGitHooks, lintVault, listApprovals, listCandidates, listGodNodes, listGraphHyperedges, listManagedSourceRecords, listManifests, listPages, listSchedules, listTrackedRepoRoots, loadVaultConfig, loadVaultSchema, loadVaultSchemas, pathGraphVault, promoteCandidate, providerCapabilitySchema, providerTypeSchema, pushGraphNeo4j, queryGraphVault, queryVault, readApproval, readExtractedText, readGraphReport, readPage, rejectApproval, reloadManagedSources, resolvePaths, runSchedule, runWatchCycle, searchVault, serveSchedules, startGraphServer, startMcpServer, syncTrackedRepos, syncTrackedReposForWatch, uninstallGitHooks, watchVault, webSearchProviderTypeSchema };
+export { type AddOptions, type AddResult, type AgentType, type AnalyzedTerm, type ApprovalChangeType, type ApprovalDetail, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryStatus, type ApprovalManifest, type ApprovalSummary, type BenchmarkArtifact, type BenchmarkOptions, type BenchmarkQuestionResult, type BenchmarkSummary, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, type DirectoryIngestResult, type DirectoryIngestSkip, type EmbeddingCacheArtifact, type EmbeddingCacheEntry, type EvidenceClass, type ExploreOptions, type ExploreResult, type ExploreStepResult, type ExtractionClaim, type ExtractionKind, type ExtractionTerm, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GitHookStatus, type GraphArtifact, type GraphEdge, type GraphExplainNeighbor, type GraphExplainResult, type GraphExportFormat, type GraphExportResult, type GraphHyperedge, type GraphNode, type GraphPage, type GraphPathResult, type GraphPushCounts, type GraphPushNeo4jOptions, type GraphPushResult, type GraphQueryMatch, type GraphQueryResult, type GraphReportArtifact, type ImageGenerationRequest, type ImageGenerationResponse, type ImageVisionExtraction, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type InputIngestResult, type InstallAgentOptions, type InstallAgentResult, type LintFinding, type LintOptions, type ManagedSourceAddOptions, type ManagedSourceAddResult, type ManagedSourceDeleteResult, type ManagedSourceKind, type ManagedSourceRecord, type ManagedSourceReloadOptions, type ManagedSourceReloadResult, type ManagedSourceStatus, type ManagedSourceSyncCounts, type ManagedSourcesArtifact, type Neo4jGraphSinkConfig, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type PendingSemanticRefreshEntry, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type RepoSyncResult, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceCaptureType, type SourceClaim, type SourceClass, type SourceExtractionArtifact, type SourceKind, type SourceManifest, type SourceRationale, type SourceReviewResult, type VaultConfig, type WatchController, type WatchOptions, type WatchRepoSyncResult, type WatchRunRecord, type WatchStatusResult, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, addInput, addManagedSource, agentTypeSchema, archiveCandidate, assertProviderCapability, benchmarkVault, bootstrapDemo, compileVault, createMcpServer, createProvider, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, deleteManagedSource, explainGraphVault, exploreVault, exportGraphFormat, exportGraphHtml, getGitHookStatus, getProviderForTask, getWatchStatus, getWebSearchAdapterForTask, getWorkspaceInfo, importInbox, ingestDirectory, ingestInput, ingestInputDetailed, initVault, initWorkspace, installAgent, installConfiguredAgents, installGitHooks, lintVault, listApprovals, listCandidates, listGodNodes, listGraphHyperedges, listManagedSourceRecords, listManifests, listPages, listSchedules, listTrackedRepoRoots, loadVaultConfig, loadVaultSchema, loadVaultSchemas, pathGraphVault, promoteCandidate, providerCapabilitySchema, providerTypeSchema, pushGraphNeo4j, queryGraphVault, queryVault, readApproval, readExtractedText, readGraphReport, readPage, rejectApproval, reloadManagedSources, resolvePaths, reviewManagedSource, reviewSourceScope, runSchedule, runWatchCycle, searchVault, serveSchedules, stageGeneratedOutputPages, startGraphServer, startMcpServer, syncTrackedRepos, syncTrackedReposForWatch, uninstallGitHooks, watchVault, webSearchProviderTypeSchema };