@happyvertical/smrt-facts 0.30.0

package/dist/types.d.ts

@@ -0,0 +1,371 @@
+import { PromptConfigOverrideInput } from '@happyvertical/smrt-prompts';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+/**
+ * Entity briefing - summary of all facts about an entity
+ */
+export declare interface EntityBriefing {
+    entityType: string;
+    entityId: string;
+    facts: Fact[];
+    totalCount: number;
+    byType: Record<string, number>;
+    byStatus: Record<string, number>;
+}
+
+/**
+ * How a fact evolved from its predecessor in the evolution chain.
+ */
+export declare type EvolutionType = 'original' | 'correction' | 'refinement' | 'contradiction' | 'extension' | 'merge';
+
+declare class Fact extends SmrtObject {
+    textRefined: string;
+    textRaw: string;
+    type: string;
+    status: string;
+    domain: string;
+    /**
+     * Self-referencing pointer to the predecessor fact in an evolution chain.
+     *
+     * This is NOT a structural hierarchy edge — Fact does not extend
+     * SmrtHierarchical. The chain represents knowledge evolution: an original
+     * fact, then corrections, refinements, contradictions, or extensions of
+     * that fact. See `evolutionType` for the kind of step.
+     */
+    previousFactId: string;
+    evolutionType: string;
+    sourceCount: number;
+    confidence: number;
+    metadata: string;
+    tenantId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: FactOptions);
+    getMetadata(): FactMetadata;
+    setMetadata(data: FactMetadata): void;
+    updateMetadata(updates: Partial<FactMetadata>): void;
+    getType(): FactType;
+    getStatus(): FactStatus;
+    getEvolutionType(): EvolutionType;
+    isActive(): boolean;
+    isSuperseded(): boolean;
+    /**
+     * Whether this fact has a predecessor in the evolution chain.
+     *
+     * Returns false for the framework default (`''`) and for any nullish
+     * value — defensive against rows whose `previous_fact_id` column is
+     * NULL (e.g. after a migration that left root facts un-backfilled).
+     */
+    hasPredecessor(): boolean;
+    /**
+     * Get the predecessor fact (the prior version in the evolution chain).
+     */
+    getPredecessor(): Promise<Fact | null>;
+    /**
+     * Get successor facts (facts that evolved directly from this one).
+     */
+    getSuccessors(): Promise<Fact[]>;
+    /**
+     * Get all sources for this fact
+     */
+    getSources(): Promise<FactSource[]>;
+    /**
+     * Get all subjects linked to this fact
+     */
+    getSubjects(): Promise<FactSubject[]>;
+}
+
+export declare interface FactClaimSupportAssessment {
+    status: FactClaimSupportStatus;
+    matchedFactIds: string[];
+    matchedEvidenceIds: string[];
+    rationale: string;
+    confidence?: number;
+}
+
+export declare interface FactClaimSupportCandidate {
+    id?: string | null;
+    statement: string;
+    evidence?: Array<{
+        id?: string | null;
+        status?: FactEvidenceStatus | null;
+        quote?: string | null;
+        sourceTitle?: string | null;
+        sourceUrl?: string | null;
+        locator?: string | null;
+    }>;
+}
+
+export declare interface FactClaimSupportOptions {
+    tenantId?: string | null;
+    promptOverride?: PromptConfigOverrideInput;
+}
+
+export declare type FactClaimSupportStatus = 'supported' | 'unsupported' | 'contradicted' | 'needs_review';
+
+/**
+ * Options for creating a FactContent join
+ */
+export declare interface FactContentOptions extends SmrtObjectOptions {
+    id?: string;
+    factId?: string;
+    contentId?: string;
+    relationship?: FactContentRelationship;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+/**
+ * Relationship between a fact and content
+ */
+export declare type FactContentRelationship = 'extracted_from' | 'referenced_in' | 'supports' | 'contradicts' | 'related';
+
+/**
+ * Options for creating concrete evidence for a fact.
+ */
+export declare interface FactEvidenceOptions extends SmrtObjectOptions {
+    id?: string;
+    factId?: string;
+    evidenceKey?: string;
+    status?: FactEvidenceStatus;
+    sourceKind?: string;
+    sourceId?: string;
+    sourceUrl?: string;
+    sourceTitle?: string;
+    quote?: string;
+    locator?: string;
+    extractionMethod?: string;
+    confidence?: number;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+/**
+ * Review status for a concrete evidence excerpt.
+ */
+export declare type FactEvidenceStatus = 'supports' | 'contradicts' | 'unclear' | 'irrelevant' | 'invalid';
+
+/**
+ * A candidate factual statement extracted from unstructured source text.
+ */
+export declare interface FactExtractionCandidate {
+    /** Concise, atomic factual statement suitable for audit */
+    statement: string;
+    /** Fact type classification */
+    type?: FactType;
+    /** Short source excerpt that supports the statement */
+    sourceExcerpt?: string;
+    /** Optional extraction confidence from 0 to 1 */
+    confidence?: number;
+    /** Optional extraction metadata */
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Options for AI-assisted fact extraction from source text.
+ */
+export declare interface FactExtractionOptions {
+    /** Domain to guide extraction and later reconciliation */
+    domain?: string;
+    /** Source type, e.g. agenda, minutes, article, transcript */
+    sourceType?: string;
+    /** Human-readable context for the source text */
+    context?: string;
+    /** Maximum number of facts to extract */
+    maxFacts?: number;
+    /** Fact types the extractor may return */
+    allowedTypes?: FactType[];
+    /** Tenant id used when resolving stored prompt overrides */
+    tenantId?: string | null;
+    /** Runtime prompt override for a single extraction call */
+    promptOverride?: PromptConfigOverrideInput;
+}
+
+/**
+ * Fact metadata structure (flexible, application-specific)
+ */
+export declare interface FactMetadata {
+    /** Original extraction context */
+    extractionContext?: string;
+    /** AI model used for refinement */
+    refinedBy?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Related fact IDs */
+    relatedFactIds?: string[];
+    /** Corroboration score from cross-referencing */
+    corroborationScore?: number;
+    /** Allow any other properties */
+    [key: string]: any;
+}
+
+/**
+ * Options for creating a Fact instance
+ */
+export declare interface FactOptions extends SmrtObjectOptions {
+    id?: string;
+    slug?: string;
+    type?: FactType;
+    status?: FactStatus;
+    domain?: string;
+    textRaw?: string;
+    textRefined?: string;
+    /**
+     * Self-referencing pointer to the predecessor fact in the evolution
+     * chain. NOT a structural hierarchy edge — see Fact.previousFactId.
+     */
+    previousFactId?: string;
+    evolutionType?: EvolutionType;
+    sourceCount?: number;
+    confidence?: number;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+declare class FactSource extends SmrtObject {
+    factId: string;
+    sourceType: string;
+    sourceUrl: string;
+    sourceTitle: string;
+    credibility: number;
+    extractedAt: Date;
+    metadata: string;
+    tenantId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: FactSourceOptions);
+    getMetadata(): Record<string, any>;
+    setMetadata(data: Record<string, any>): void;
+    updateMetadata(updates: Record<string, any>): void;
+    /**
+     * Get the fact this source belongs to
+     */
+    getFact(): Promise<Fact | null>;
+}
+
+/**
+ * Options for creating a FactSource instance
+ */
+export declare interface FactSourceOptions extends SmrtObjectOptions {
+    id?: string;
+    factId?: string;
+    sourceType?: string;
+    sourceUrl?: string;
+    sourceTitle?: string;
+    credibility?: number;
+    extractedAt?: Date;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+/**
+ * Fact lifecycle status
+ */
+export declare type FactStatus = 'pending' | 'active' | 'disputed' | 'superseded' | 'archived' | 'retracted';
+
+declare class FactSubject extends SmrtObject {
+    factId: string;
+    entityType: string;
+    entityId: string;
+    role: string;
+    metadata: string;
+    tenantId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: FactSubjectOptions);
+    getRole(): SubjectRole;
+    getMetadata(): Record<string, any>;
+    setMetadata(data: Record<string, any>): void;
+    updateMetadata(updates: Record<string, any>): void;
+    /**
+     * Get the fact this subject is linked to
+     */
+    getFact(): Promise<Fact | null>;
+}
+
+/**
+ * Options for creating a FactSubject instance
+ */
+export declare interface FactSubjectOptions extends SmrtObjectOptions {
+    id?: string;
+    factId?: string;
+    entityType?: string;
+    entityId?: string;
+    role?: SubjectRole;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+/**
+ * Options for creating a FactTag join
+ */
+export declare interface FactTagOptions extends SmrtObjectOptions {
+    id?: string;
+    factId?: string;
+    tagSlug?: string;
+    metadata?: string | Record<string, any>;
+    tenantId?: string | null;
+}
+
+/**
+ * Fact type classification
+ */
+export declare type FactType = 'assertion' | 'observation' | 'measurement' | 'definition' | 'relationship' | 'event' | 'opinion' | 'prediction';
+
+/**
+ * Reconcile action taken
+ */
+export declare type ReconcileAction = 'created' | 'merged' | 'branched';
+
+/**
+ * Options for the reconcile() operation
+ */
+export declare interface ReconcileOptions {
+    /** Raw text input to reconcile */
+    rawInput: string;
+    /** Similarity threshold for automatic merge (default: 0.85) */
+    similarityThreshold?: number;
+    /** Minimum similarity to consider a conflict (default: 0.60) */
+    conflictThreshold?: number;
+    /** Fact type classification */
+    type?: FactType;
+    /** Domain for the fact */
+    domain?: string;
+    /** Source metadata */
+    source?: {
+        sourceType?: string;
+        sourceUrl?: string;
+        sourceTitle?: string;
+        credibility?: number;
+        metadata?: Record<string, any>;
+    };
+    tenantId?: string | null;
+    /** Runtime prompt override for AI-assisted ambiguous reconciliation */
+    promptOverride?: PromptConfigOverrideInput;
+}
+
+/**
+ * Result of the reconcile() operation
+ */
+export declare interface ReconcileResult {
+    /** Action taken: created, merged, or branched */
+    action: ReconcileAction;
+    /** The resulting fact (created, updated, or branched) */
+    fact: Fact;
+    /** Source record if source metadata was provided */
+    source?: FactSource;
+    /** Cosine similarity score of the best match */
+    similarity?: number;
+    /** The existing fact that was matched (for merge/branch) */
+    matchedFact?: Fact;
+}
+
+/**
+ * Role of a subject entity in relation to a fact
+ */
+export declare type SubjectRole = 'subject' | 'object' | 'source' | 'location' | 'participant' | 'related';
+
+export { }

package/dist/types.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":[],"sourcesContent":[],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@happyvertical/smrt-facts",
+  "version": "0.30.0",
+  "description": "Distributed memory and knowledge management with provenance tracking for SMRT framework",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "dependencies": {
+    "@happyvertical/ai": "^0.74.7",
+    "@happyvertical/files": "^0.74.7",
+    "@happyvertical/logger": "^0.74.7",
+    "@happyvertical/sql": "^0.74.7",
+    "@happyvertical/utils": "^0.74.7",
+    "@happyvertical/smrt-core": "0.30.0",
+    "@happyvertical/smrt-prompts": "0.30.0",
+    "@happyvertical/smrt-tenancy": "0.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.9",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17",
+    "@happyvertical/smrt-vitest": "0.30.0"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "facts",
+    "knowledge",
+    "memory",
+    "provenance",
+    "smrt"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/facts"
+  },
+  "scripts": {
+    "build": "vite build --mode library",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "vite dev",
+    "pretest": "[ -f ../cli/dist/index.js ] && node ../cli/dist/index.js test --manifest-only || true",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}