@happyvertical/smrt-facts 0.51.32 → 0.51.34

package/dist/facts.d.ts

@@ -0,0 +1,173 @@
+/**
+ * FactCollection - Collection manager for Fact objects
+ *
+ * Provides query methods for facts by status, type, domain, and tenant.
+ * Implements reconcile(), branch(), evolution tree, and confidence methods.
+ */
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Fact } from './fact';
+import type { EntityBriefing, EvolutionType, FactClaimSupportAssessment, FactClaimSupportCandidate, FactClaimSupportOptions, FactContentRelationship, FactExtractionCandidate, FactExtractionOptions, FactOptions, FactStatus, FactType, ReconcileOptions, ReconcileResult } from './types';
+export declare class FactCollection extends SmrtCollection<Fact> {
+    static readonly _itemClass: typeof Fact;
+    /**
+     * Fetch one catalog page in SQL. The recursive branch walk may inspect more
+     * rows inside the database, but the outer query only materializes the page.
+     */
+    private listCatalogPage;
+    /**
+     * Get all active facts
+     */
+    getActive(): Promise<Fact[]>;
+    /**
+     * Get all pending facts
+     */
+    getPending(): Promise<Fact[]>;
+    /**
+     * Get facts by type
+     */
+    getByType(type: FactType): Promise<Fact[]>;
+    /**
+     * Get facts by domain
+     */
+    getByDomain(domain: string): Promise<Fact[]>;
+    /**
+     * Get facts by status
+     */
+    getByStatus(status: FactStatus): Promise<Fact[]>;
+    /**
+     * Get successor facts for a given predecessor (facts that evolved
+     * directly from `previousFactId`).
+     */
+    getSuccessors(previousFactId: string): Promise<Fact[]>;
+    /**
+     * Find all facts belonging to a specific tenant
+     */
+    findByTenant(tenantId: string): Promise<Fact[]>;
+    /**
+     * Find all global (tenant-less) facts.
+     *
+     * Routes through the shared tenant-global helper so it does not throw under
+     * an active tenant context (an explicit `tenant_id IS NULL` filter would be
+     * flagged as an isolation violation). (#1600)
+     */
+    findGlobal(): Promise<Fact[]>;
+    /**
+     * Find facts for a tenant including global facts.
+     *
+     * Fails closed if an active tenant context requests a different tenant's
+     * rows; the admin/system path keeps the cross-tenant capability. (#1600)
+     */
+    findWithGlobals(tenantId: string): Promise<Fact[]>;
+    /**
+     * Browse active facts for editorial association.
+     * Uses semantic search when a query is provided and falls back to text filtering
+     * if embeddings are unavailable.
+     */
+    browseCatalog(query?: string, options?: {
+        tenantId?: string | null;
+        limit?: number;
+        offset?: number;
+        minSimilarity?: number;
+        includeSuperseded?: boolean;
+        latestOnly?: boolean;
+    }): Promise<Fact[]>;
+    /**
+     * Explicit data migration after db:migrate adds catalog_search. Run under
+     * withSystemContext with old writers stopped. Repeating a batch is safe;
+     * concurrent source changes are protected by compare-and-set predicates.
+     * A subtype collection backfills only its STI discriminator.
+     */
+    backfillCatalogSearch(batchSize?: number): Promise<{
+        remaining: number;
+    }>;
+    /**
+     * Get all facts linked to a content item.
+     */
+    getForContent(contentId: string, options?: {
+        relationship?: FactContentRelationship;
+        includeSuperseded?: boolean;
+        latestOnly?: boolean;
+    }): Promise<Fact[]>;
+    /**
+     * Reconcile raw input against existing facts using semantic search + AI.
+     * Determines whether to create, merge, or branch.
+     *
+     * Algorithm:
+     * 1. semanticSearch(rawInput) against existing facts
+     * 2. Decision:
+     *    - No match above conflictThreshold (0.60) -> CREATE new fact
+     *    - Top match >= similarityThreshold (0.85) -> MERGE (add source, bump sourceCount)
+     *    - Ambiguous zone (0.60-0.85) -> optional typed decision, otherwise AI
+     *      text disambiguation. A typed merge must meet its separate confidence
+     *      probability threshold; uncertainty and failures branch conservatively.
+     * 3. Record FactSource if source metadata provided
+     * 4. Return { action, fact, source?, similarity?, matchedFact? }
+     */
+    reconcile(options: ReconcileOptions): Promise<ReconcileResult>;
+    /**
+     * Extract atomic factual statements from unstructured source text using AI.
+     *
+     * This method is intentionally non-persistent: callers can review, reconcile,
+     * link, or discard the returned candidates according to their app workflow.
+     */
+    extractCandidatesFromText(text: string, options?: FactExtractionOptions): Promise<FactExtractionCandidate[]>;
+    /**
+     * Extract material factual claims made by an article.
+     *
+     * This is intentionally separate from source extraction: source extraction
+     * finds evidence-backed facts, while claim extraction finds statements the
+     * draft itself needs to justify.
+     */
+    extractArticleClaims(text: string, options?: FactExtractionOptions): Promise<FactExtractionCandidate[]>;
+    /**
+     * Classify whether a claim is supported by candidate facts/evidence.
+     */
+    assessClaimSupport(claim: string, candidateFacts: FactClaimSupportCandidate[], options?: FactClaimSupportOptions): Promise<FactClaimSupportAssessment>;
+    /**
+     * Use AI to determine whether new input should be merged with
+     * or branched from an existing fact.
+     */
+    private _disambiguateWithAI;
+    /**
+     * Create a branched fact from an existing predecessor.
+     *
+     * For 'correction' and 'contradiction' evolution types, the
+     * predecessor is marked as superseded.
+     *
+     * @param previousFactId ID of the predecessor fact this branches from.
+     * @param data Partial fact options for the new successor.
+     * @param evolutionType How the successor relates to the predecessor.
+     */
+    branch(previousFactId: string, data: Partial<FactOptions>, evolutionType?: EvolutionType): Promise<Fact>;
+    /**
+     * Walk up the evolution chain via previousFactId, returning the
+     * predecessors followed by the current fact in order.
+     *
+     * @returns Array ordered from root (original) → current fact.
+     */
+    getEvolutionChain(factId: string): Promise<Fact[]>;
+    /**
+     * Walk down successors to find the latest (highest confidence) leaf.
+     * At each level, picks the successor with the highest confidence score.
+     */
+    getLatestInChain(factId: string): Promise<Fact>;
+    /**
+     * Find the root of the chain via `getEvolutionChain`, then collect every
+     * successor iteratively via BFS (queue-based, with a `visited` set for
+     * cycle protection). Returns the full tree as a flat array in BFS
+     * order — root first, then each level of successors.
+     */
+    getEvolutionTree(factId: string): Promise<Fact[]>;
+    /**
+     * Recalculate confidence score for a fact based on its sources.
+     * Uses calculateConfidence from utils.ts with data from FactSourceCollection.
+     */
+    recalculateConfidence(factId: string): Promise<number>;
+    /**
+     * Get a briefing of all facts related to a given entity.
+     * Finds all FactSubject links for the entity, loads corresponding facts,
+     * and returns summary statistics.
+     */
+    getEntityBriefing(entityType: string, entityId: string): Promise<EntityBriefing>;
+}
+//# sourceMappingURL=facts.d.ts.map

package/dist/facts.d.ts.map

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