@gencow/core 0.1.27 → 0.1.28

package/dist/document-types.d.ts

@@ -0,0 +1,65 @@
+export type DocumentVisibility = "private" | "shared" | "public";
+export type DocumentConvertMode = "auto" | "text-only" | "no-external-provider" | "prefer-external" | "force-external" | "force-ocr";
+export type DocumentConvertProvider = "auto" | "local_text" | "gemini" | "openai" | "ocr" | "custom_vlm";
+export type DocumentResolvedProvider = Exclude<DocumentConvertProvider, "auto">;
+export type DocumentProviderRoute = "local_text" | "vlm" | "ocr_fallback";
+export type DocumentCacheArtifact = "convert" | "embedding" | "summary" | "rerank";
+export type DocumentConvertInput = {
+    storageId: string;
+    filename?: string;
+    mimeType?: string;
+    corpus: string;
+    visibility: DocumentVisibility;
+    ownerUserId?: string;
+    mode?: DocumentConvertMode;
+    provider?: DocumentConvertProvider;
+};
+export type DocumentPage = {
+    page: number;
+    charStart: number;
+    charEnd: number;
+    previewText?: string;
+};
+export type DocumentSection = {
+    id: string;
+    title?: string;
+    depth: number;
+    path: string[];
+    pageStart?: number;
+    pageEnd?: number;
+    charStart: number;
+    charEnd: number;
+};
+export type DocumentProviderTrace = {
+    provider: DocumentResolvedProvider;
+    route: DocumentProviderRoute;
+    external: boolean;
+    requestId?: string;
+    durationMs: number;
+    bytes: number;
+};
+export type DocumentConvertResult = {
+    text: string;
+    markdown: string;
+    pages: DocumentPage[];
+    sections: DocumentSection[];
+    warnings: string[];
+    providerTrace: DocumentProviderTrace;
+};
+export interface GencowServicesCtx {
+}
+export interface WorkflowDocumentServicesCtx {
+    document: {
+        convert(input: DocumentConvertInput): Promise<DocumentConvertResult>;
+    };
+}
+export type DocumentCacheKeyInput = {
+    appId: string;
+    ownerUserId?: string | null;
+    corpus: string;
+    sourceKey: string;
+    checksum: string;
+    provider: DocumentResolvedProvider;
+    artifact: DocumentCacheArtifact;
+};
+export declare function buildDocumentCacheKey(input: DocumentCacheKeyInput): string;

package/dist/document-types.js

@@ -0,0 +1,15 @@
+function normalizeCachePart(value) {
+    return value.trim() || "unknown";
+}
+export function buildDocumentCacheKey(input) {
+    const owner = input.ownerUserId?.trim() ? input.ownerUserId.trim() : "shared";
+    return [
+        `app:${normalizeCachePart(input.appId)}`,
+        `user:${normalizeCachePart(owner)}`,
+        `corpus:${normalizeCachePart(input.corpus)}`,
+        `source:${normalizeCachePart(input.sourceKey)}`,
+        `checksum:${normalizeCachePart(input.checksum)}`,
+        `provider:${normalizeCachePart(input.provider)}`,
+        `artifact:${normalizeCachePart(input.artifact)}`,
+    ].join(":");
+}

package/dist/grounded-answer-types.d.ts

@@ -0,0 +1,62 @@
+import type { SearchFilter, SearchScope } from "./search-types.js";
+export type CitationCoverage = "direct" | "partial" | "context";
+export type ClaimSupportStatus = "supported" | "partially_supported" | "insufficient_evidence";
+export type GroundedAnswerMode = "qa" | "compare" | "topic";
+export type Citation = {
+    sourceId: string;
+    sourceTitle: string;
+    sectionId?: string;
+    sectionPath?: string[];
+    pageStart?: number;
+    pageEnd?: number;
+    chunkIds: string[];
+    snippet: string;
+    coverage: CitationCoverage;
+    confidence: number;
+};
+export type ClaimEvidenceMap = {
+    claimId: string;
+    claimText: string;
+    status: ClaimSupportStatus;
+    citations: Citation[];
+    missingEvidenceReasons?: string[];
+};
+export type GroundedAnswer = {
+    answer: string;
+    claims: ClaimEvidenceMap[];
+    citations: Citation[];
+    warnings: string[];
+    grounded: boolean;
+};
+export type GroundingBudget = {
+    maxVerifyLoops: number;
+    maxResearchQueriesPerLoop: number;
+    maxCitationsPerClaim: number;
+    maxClaimsPerAnswer: number;
+};
+export declare const DEFAULT_GROUNDING_BUDGET: GroundingBudget;
+export type GroundedClaimInput = {
+    claimId?: string;
+    claimText: string;
+    requiredTerms?: string[];
+};
+export type GroundedCompareInput = {
+    left: string;
+    right: string;
+};
+export type GroundedTopicInput = {
+    minDistinctSections?: number;
+};
+export type GroundedAnswerInput = {
+    question: string;
+    scope: SearchScope;
+    filters?: SearchFilter;
+    claims?: GroundedClaimInput[];
+    mode?: GroundedAnswerMode;
+    compare?: GroundedCompareInput;
+    topic?: GroundedTopicInput;
+    budget?: Partial<GroundingBudget>;
+};
+export type GroundingRuntime = {
+    answer(input: GroundedAnswerInput): Promise<GroundedAnswer>;
+};

package/dist/grounded-answer-types.js

@@ -0,0 +1,6 @@
+export const DEFAULT_GROUNDING_BUDGET = {
+    maxVerifyLoops: 2,
+    maxResearchQueriesPerLoop: 3,
+    maxCitationsPerClaim: 3,
+    maxClaimsPerAnswer: 12,
+};

package/dist/index.d.ts

@@ -5,8 +5,16 @@
  * All with Convex-compatible DX patterns.
  */
 export type { GencowCtx, AuthCtx, UserIdentity, QueryDef, MutationDef, RealtimeCtx, HttpActionDef, HttpActionRequest, HttpActionResponse, HttpActionHandler, AIContext, AIMessage, AIResult, } from "./reactive.js";
+export type { SearchPrimitive, SearchScope, SearchFilter, SearchOptions, VectorSearchOptions, HybridSearchOptions, SearchHit, SearchResponse, SearchTierConfig, } from "./search-types.js";
+export type { DocumentVisibility, DocumentConvertMode, DocumentConvertProvider, DocumentResolvedProvider, DocumentConvertInput, DocumentPage, DocumentSection, DocumentProviderTrace, DocumentConvertResult, DocumentCacheArtifact, DocumentCacheKeyInput, GencowServicesCtx, WorkflowDocumentServicesCtx, } from "./document-types.js";
+export { buildDocumentCacheKey } from "./document-types.js";
+export type { RagIngestReindexMode, RagIngestInput, RagIngestWorkflowArgs, RagIngestStartResult, RagIngestJobStatus, RagIngestJobRecord, } from "./rag-ingest-types.js";
+export type { CitationCoverage, ClaimSupportStatus, GroundedAnswerMode, Citation, ClaimEvidenceMap, GroundedAnswer, GroundingBudget, GroundedClaimInput, GroundedCompareInput, GroundedTopicInput, GroundedAnswerInput, GroundingRuntime, } from "./grounded-answer-types.js";
+export { DEFAULT_GROUNDING_BUDGET } from "./grounded-answer-types.js";
+export type { RagOperationKind, RagOperationMetricUnit, RagIndexHealth, RagOperationMetric, RagOperationsSummary, RagEvaluationExpectedClaim, RagEvaluationFixture, RagEvaluationFixtureResult, RagEvaluationRunResult, RagReindexMode, RagReindexPlan, } from "./rag-operations-types.js";
+export { ragCorpora, ragSources, ragSections, ragChunks, ragIngestJobs, ragOperationMetrics } from "./rag-schema.js";
 export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions, } from "./reactive.js";
-export type { Storage } from "./storage.js";
+export type { Storage, StoredFile } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export type { Scheduler, ScheduleOptions, FailedJob, CreateSchedulerOptions, ScheduledJobRecord, } from "./scheduler.js";
 export { workflow, getWorkflowDef, getRegisteredWorkflows, getWorkflowResumeActionName, getWorkflowRealtimeKey, createWorkflowRealtimeToken, serializeWorkflowValue, deserializeWorkflowValue, parseWorkflowDurationMs, DEFAULT_WORKFLOW_MAX_DURATION_MS, DEFAULT_WORKFLOW_MAX_RETRIES, WORKFLOW_RESUME_ACTION_PREFIX, WORKFLOW_REALTIME_KEY_PREFIX, } from "./workflow.js";
@@ -17,6 +25,7 @@ export { v, parseArgs, GencowValidationError } from "./v.js";
 export type { Validator, Infer, InferArgs } from "./v.js";
 export { withRetry } from "./retry.js";
 export type { RetryOptions } from "./retry.js";
+export { filterTenantRuntimeEnvVars, isReservedTenantRuntimeEnvKey } from "./runtime-env-policy.js";
 export { cronJobs } from "./crons.js";
 export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons.js";
 export { defineAuth } from "./auth-config.js";

package/dist/index.js

@@ -4,6 +4,9 @@
  * Provides: query, mutation, storage, scheduler, auth
  * All with Convex-compatible DX patterns.
  */
+export { buildDocumentCacheKey } from "./document-types.js";
+export { DEFAULT_GROUNDING_BUDGET } from "./grounded-answer-types.js";
+export { ragCorpora, ragSources, ragSections, ragChunks, ragIngestJobs, ragOperationMetrics } from "./rag-schema.js";
 export { query, mutation, httpAction, buildRealtimeCtx, subscribe, unsubscribe, registerClient, deregisterClient, handleWsMessage, getQueryHandler, getQueryDef, getRegisteredQueries, getRegisteredMutations, getRegisteredHttpActions, } from "./reactive.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export { workflow, getWorkflowDef, getRegisteredWorkflows, getWorkflowResumeActionName, getWorkflowRealtimeKey, createWorkflowRealtimeToken, serializeWorkflowValue, deserializeWorkflowValue, parseWorkflowDurationMs, DEFAULT_WORKFLOW_MAX_DURATION_MS, DEFAULT_WORKFLOW_MAX_RETRIES, WORKFLOW_RESUME_ACTION_PREFIX, WORKFLOW_REALTIME_KEY_PREFIX, } from "./workflow.js";
@@ -11,6 +14,7 @@ export { deriveWorkflowStatus } from "./workflow-types.js";
 export { loadWorkflowSnapshot } from "./workflows-api.js";
 export { v, parseArgs, GencowValidationError } from "./v.js";
 export { withRetry } from "./retry.js";
+export { filterTenantRuntimeEnvVars, isReservedTenantRuntimeEnvKey } from "./runtime-env-policy.js";
 export { cronJobs } from "./crons.js";
 export { defineAuth } from "./auth-config.js";
 // ─── RLS + CRUD Factory ───────────

package/dist/rag-ingest-types.d.ts

@@ -0,0 +1,39 @@
+import type { DocumentConvertProvider, DocumentConvertMode, DocumentProviderTrace, DocumentVisibility } from "./document-types.js";
+export type RagIngestReindexMode = "if_changed" | "force";
+export type RagIngestJobStatus = "queued" | "converting" | "chunking" | "embedding" | "upserting" | "completed" | "failed" | "canceled";
+export type RagIngestInput = {
+    storageId: string;
+    corpus: string;
+    visibility: DocumentVisibility;
+    ownerUserId?: string;
+    sourceKey?: string;
+    metadata?: Record<string, unknown>;
+    reindexMode?: RagIngestReindexMode;
+    mode?: DocumentConvertMode;
+    provider?: DocumentConvertProvider;
+};
+export type RagIngestWorkflowArgs = RagIngestInput & {
+    jobId: string;
+    sourceId: string;
+};
+export type RagIngestStartResult = {
+    workflowId: string;
+    jobId: string;
+    sourceId: string;
+    status: "queued";
+};
+export type RagIngestJobRecord = {
+    id: string;
+    workflowId: string;
+    sourceId: string;
+    corpus: string;
+    visibility: DocumentVisibility;
+    ownerUserId: string | null;
+    status: RagIngestJobStatus;
+    stage: string;
+    providerTrace: Partial<DocumentProviderTrace> | Record<string, never>;
+    metrics: Record<string, unknown>;
+    error: string | null;
+    startedAt: string;
+    completedAt: string | null;
+};

package/dist/rag-ingest-types.js

@@ -0,0 +1 @@
+export {};

package/dist/rag-operations-types.d.ts

@@ -0,0 +1,81 @@
+import type { SearchScope } from "./search-types.js";
+export type RagOperationKind = "ingest" | "retrieve" | "answer" | "reindex" | "evaluate";
+export type RagOperationMetricUnit = "ms" | "count" | "tokens" | "usd";
+export type RagIndexHealth = "ready" | "empty" | "degraded" | "failed";
+export type RagOperationMetric = {
+    id: string;
+    appId: string;
+    corpus: string;
+    visibility: SearchScope["visibility"];
+    ownerUserId: string | null;
+    operation: RagOperationKind;
+    jobId: string | null;
+    workflowId: string | null;
+    sourceId: string | null;
+    metricName: string;
+    metricValue: number;
+    unit: RagOperationMetricUnit | null;
+    metadata: Record<string, unknown>;
+    recordedAt: string;
+};
+export type RagOperationsSummary = {
+    corpus: string;
+    visibility: SearchScope["visibility"];
+    ownerUserId: string | null;
+    sourceCount: number;
+    sectionCount: number;
+    chunkCount: number;
+    jobCounts: Record<string, number>;
+    latestJob: {
+        id: string;
+        status: string;
+        stage: string;
+        updatedAt: string;
+    } | null;
+    recentMetricCounts: Record<string, number>;
+    averageLatencyMs: number | null;
+    indexHealth: RagIndexHealth;
+};
+export type RagEvaluationExpectedClaim = {
+    claim: string;
+    verdict: "supported" | "partial" | "unsupported";
+};
+export type RagEvaluationFixture = {
+    name: string;
+    scope: SearchScope;
+    query: string;
+    expectedSourceIds?: string[];
+    expectedCitationCountMin?: number;
+    expectedClaims?: RagEvaluationExpectedClaim[];
+};
+export type RagEvaluationFixtureResult = {
+    name: string;
+    ok: boolean;
+    failures: string[];
+    matchedSourceIds: string[];
+    citationCount: number;
+    claimStatuses: Array<{
+        claim: string;
+        expected: RagEvaluationExpectedClaim["verdict"];
+        actual: string | null;
+    }>;
+};
+export type RagEvaluationRunResult = {
+    ok: boolean;
+    total: number;
+    passed: number;
+    failed: number;
+    results: RagEvaluationFixtureResult[];
+};
+export type RagReindexMode = "source-changed" | "section-changed" | "corpus-policy-changed" | "full-rebuild";
+export type RagReindexPlan = {
+    corpus: string;
+    visibility: SearchScope["visibility"];
+    ownerUserId: string | null;
+    mode: RagReindexMode;
+    reason: string;
+    sourceIds: string[];
+    sourceCount: number;
+    estimatedChunkCount: number;
+    requiresConfirmation: boolean;
+};

package/dist/rag-operations-types.js

@@ -0,0 +1 @@
+export {};