@ happyvertical/ smrt- facts (欢快的垂直/扭曲)
具备语义分解,出处跟踪,S-m-r-t框架信心分数的知识库. 事实通过父母-子女连锁关系演变,与来源和主体相联,并经过3个区间调节,以防止重复.
安装
pnpm add @happyvertical/smrt-facts
使用量
import {
Fact, FactCollection,
FactSource, FactSourceCollection,
FactSubject, FactSubjectCollection,
FactContent, FactContentCollection,
FactTag, FactTagCollection,
calculateConfidence, normalizeText,
} from '@happyvertical/smrt-facts';
// Create a fact with provenance
const facts = await FactCollection.create({ db });
const fact = await facts.create({
textRefined: 'The Eiffel Tower is 330 meters tall',
type: 'measurement',
domain: 'landmarks',
status: 'active',
});
// Attach a source with credibility score
const sources = await FactSourceCollection.create({ db });
await sources.create({
factId: fact.id,
sourceUrl: 'https://example.com/eiffel-tower',
sourceTitle: 'Tourism Board',
credibility: 0.9,
});
// Recalculate confidence from all sources
await facts.recalculateConfidence(fact.id);
// 3-zone semantic reconciliation
// Exact normalized statements first reuse an active fact only within the same
// tenant, domain, and type. PostgreSQL callers are serialized on that key, so
// this identity guarantee also holds when embeddings fail or calls overlap.
// >= 0.85 similarity: auto-merge (same fact, update metadata)
// 0.60-0.85: optional typed decision, otherwise AI disambiguation
// Typed decisions merge only when their selected merge probability meets the
// conservative 0.75 operating threshold; uncertainty and provider errors branch.
// < 0.60: create new fact
const result = await facts.reconcile({
rawInput: 'The Eiffel Tower stands 330m tall',
type: 'measurement',
domain: 'landmarks',
source: { sourceUrl: 'https://another-source.com', credibility: 0.8 },
});
// result.action: 'created' | 'merged' | 'branched'
// Evolution chains: branch creates a successor fact linked via previousFactId
const successor = await facts.branch(fact.id, {
textRefined: 'The Eiffel Tower is 330 meters tall including the antenna',
}, 'correction');
// 'correction' and 'contradiction' mark the predecessor as superseded
// Walk evolution: root -> current (via previousFactId)
const chain = await facts.getEvolutionChain(successor.id);
// Find highest-confidence leaf (via getSuccessors)
const latest = await facts.getLatestInChain(fact.id);
// Full tree (BFS with cycle detection)
const tree = await facts.getEvolutionTree(fact.id);
// Per-fact navigation: getPredecessor / getSuccessors / hasPredecessor
const previous = await successor.getPredecessor();
const successors = await fact.getSuccessors();
if (successor.hasPredecessor()) {
// ...
}
// Entity briefing: all facts for a given entity
const briefing = await facts.getEntityBriefing('Place', placeId);
// { facts, totalCount, byType, byStatus }
API 密码
模型
| 导出 | 说明 |
|---|---|
Fact | 知识股 textRefined, (中文(简体) ), type, (中文(简体) ), status, (中文(简体) ), confidence, (中文(简体) ), previousFactId 用于进化链(前继指针;而不是结构等级边缘),以及自动生成的嵌入 |
FactSource | 证明记录 sourceUrl, (中文(简体) ), sourceType, (中文(简体) ), credibility (0-1), (中文(简体) ), extractedAt |
FactSubject | 多态实体链接( C)entityType + 键 entityId, (中文(简体) ), conflictColumns: ['fact_id', 'entity_type', 'entity_id'] |
FactContent | 把事实和内容联系起来的表格, conflictColumns: ['fact_id', 'content_id', 'relationship'] |
FactTag | 对事实的标签关联 |
收款
| 导出 | 说明 |
|---|---|
FactCollection | 按状态/类型/领域查询, reconcile(), (中文(简体) ), branch()进化的转弯, recalculateConfidence(), (中文(简体) ), getEntityBriefing(), (中文(简体) ), findWithGlobals(tenantId) |
FactSourceCollection | 源管理 getForFact() |
FactSubjectCollection | 主题与 getForFact(), (中文(简体) ), getForEntity() |
FactContentCollection | 事实与内容的关系 |
FactTagCollection | 事实标签管理 |
职能
| 导出 | 说明 |
|---|---|
calculateConfidence | 加权公式:基数为0.5 + 源量(最大为0.3) + 可信度(0.2) + 复用(0.1,10天后衰变) + 证实(0.1) 被夹入 [0, 1] |
normalizeText | 三进制,倒塌的白空格,小写 -- -- 用于去除比较 |
密钥类型
FactType (确认/观察/衡量/定义/关系/活动/意见/预测), FactStatus (待处理/正在处理/争议/已处理/已处理/已处理/已处理), EvolutionType (原始内容/更正/精炼/缩写/扩展/出现), SubjectRole, (中文(简体) ), ReconcileAction, (中文(简体) ), ReconcileOptions, (中文(简体) ), ReconcileResult, (中文(简体) ), FactContentRelationship, (中文(简体) ), EntityBriefing
依赖关系
@happyvertical/smrt-core- ORM、代码生成和语义搜索@happyvertical/smrt-tenancy- 可选多租户范围界定findWithGlobals()@happyvertical/ai- 大赦国际在和解方面的分歧
贡献者指南
见 AGENTS.md 用于软件包结构、变化、验证、,
和贡献者的指导.
编目标记
browseCatalog(query, { limit, offset, latestOnly, tenantId }) 默认为 25
除非 latestOnly: false 提供.
空清水清浏览和成功的语义搜索只将请求的水合物
SQL页面. 空缺候选人的资格仍受限制
offset + 2 * limit因此,解锁和解锁链可以返回a
简页。 语义学候选人检索仍受限制 offset + limit。 。 。 .
这些 SQL 窗口使用请求的页形值而不是收藏
defaultListLimit. 完整的租户可见的接班人可以连锁解析,甚至
当继任者位于候选窗口或状态过滤器外时。 隐含范围
信任关系保留了最新的接班人,与先前命令读取的匹配.
没有明确的租户,默认候选人身份是: active;带有
明确租户、租户和全球候选人除外 superseded。 。 。 .
includeSuperseded 删除状态过滤器。 租户仍在继续
并拒绝要求另一房客。 科学、技术和创新儿童
藏书既限制候选人,也限制继任者歧视他们.
目录读取正常应用 beforeList 候选人的前提,
准备检查,以及完整的后继图表,包括空查询.
明确租户/全球阅读使用 withTenantGlobalRead,允许内置
租地列表钩 狭长的范围 而商业钩 保持原始用户,
权限、租户上下文和系统/非系统身份。 实际系统呼叫
保持系统呼叫。 截取器拒绝和应用程序 SQL 失败
致召师.
只无法嵌入配置或查询- 嵌入提供者失败
允许文本倒置;语义授权失败永远不会发生.
在无法查询嵌入时, 文本倒转匹配精确的 JavaScript
表达式 `${textRefined} ${textRaw}`.toLowerCase().includes(query.toLowerCase())。 。 。 .
它继续使用 catalogSearch 存储和相同的SQL页面 traversal.
存储编码小写 UTF-16 单位为对齐的 ASCII 令牌, 保存
Unicode, 白空格, 字形通配符字符, 和代码单位边界
SQL 整理或大小写文件夹差异. 在文本前进行平面准备状态检查
搜索;如果任何允许的行未回填,则用回填指令来扔出.
数据库可以在内部扫描匹配行和演化边缘,但只扫描
事实页跨越数据库边界。 任意子字符串匹配
无法使用普通的 B- tree 索引;没有添加误导性搜索栏索引.
现有部署
这是一种明确的图案和数据迁移;普通读取从不创建图案.
停止旧的应用程序写入器, 部署新显示/ 代码, 然后运行 smrt db:migrate
(和 smrt db:status --parity) (中文(简体) ). 添加无效 catalog_search历史
排为 NULL 。 在启用目录文本读取前, 随您运行以下
应用程序的数据库配置并重复到 remaining 为 0 :
import { FactCollection } from '@happyvertical/smrt-facts';
import { withSystemContext } from '@happyvertical/smrt-tenancy';
const facts = await FactCollection.create({ db });
await withSystemContext(async () => {
while ((await facts.backfillCatalogSearch(100)).remaining > 0) {
// Each call is independently resumable; record progress in your job runner.
}
});
回填需要明确的系统上下文,每个调用最多100行的过程 默认( 最大为 1000) , 只更新源文本仍然匹配的 NULL 值 读取快照。 它不会改变源文本,时间戳,嵌入或修改. 崩溃或同时写作可以安全重试;必须停止持续的老写作 这样手术就可以完成 a. 子类型收集只包含其歧视者; 使用基地集合进行全员部署。 在计划改变前退后; 通过重新运行迁移/回填而不是丢弃历史数据来滚动.
Fact.save(),收集创建/get-或插入/get-或upsert,并生成模型
更新维护源字段的搜索存储. catalogSearch (a) 产生;
调用者不得编写,生成的运输表面排除使用
只读/敏感字段元数据。 衍生使用 :
可变 beforeSave 钩子和完整的子类 transformJSON 链条,
保持持续文本和搜索存储的一致性。 如果自定义转换省略了源列,则返回字符串以外的值
或显式的 NULL,或用未发音的 UTF-16 代词返回字符串,则写入
保留其普通适配器语义(保留、默认或强制);搜索存储为
无效为 NULL 而不是从实例值中猜测 。 已读目录文本
然后因准备错误而失败,直到特权限制回填读
实际坚持的栏目。 在自定义写入后运行回填
恢复目录文本读取 。 只有形状良好的字符串和明确的 NULL 源
数值在持久性之前已知。 查询编码仍然准确的 UTF-16
编码单位匹配,包括包含未发售代位的查询.
普通/公开系列化
保留所保存的标记,而不是从转换前实例文本中重算.
直接 SQL 写入器必须设置 catalog_search = NULL 当任一源文本
更改,然后在文本读取恢复前返回填充.
如果习惯写作者或发行前的执行产生了已知的停滞
非 NULL 搜索值, 明确设置受影响的行 catalog_search 改为
NULL和运行相同的被限制回填. 故意后补选 NULL
标记;它不扫描或修复非NULL值。 这是定点修复,
不是一个新列迁移的附加步骤.
在回填后不要让旧的应用程序作者继续活动: 它们无法维护 这种新的无常。 未来 JavaScript 下加码/编码的更改需要 清晰的新回填; 格式不依赖地块 .
PostgreSQL和SQLite运行的克恩克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克 DuckDB 查询
覆盖范围使用明确识别的 SQL 唯一固定: Cononical Fact schema
创建当前拒绝其演化的自我参照,在
2830号DuckDB水分问题
一个 DESCRIBE 每页加一个数据查询; PostgreSQL 和 SQLite 使用一个数据
如果有的话,在语义性候选人检索后进行查询。 文本倒置也执行一个
scalar 准备查询 .
编目 保存水分 afterList 在每个最后限定的页面上,
包括空页,取自生-query悬钩和相似性说明后. 一样
列表上下文和原始呼叫者身份在钩子之前/之后到达。 过滤或
编辑可能会缩短一页;浏览不会重新填充. 政策拒绝
传播并永不触发嵌入式无法获取的文本倒置 .
文本倒置由核心的提供者- 来源可用性结果选择 :
缺失嵌入配置或失败的查询嵌入使其得以实现。 错误
从授权、排名、SQL、水合物或结果的钩传播到没有改变,
甚至当一个召唤者抛出 EmbeddingUnavailableError 从那些行动.
目录文本读取准备状态保留数据库权限,即瞬间和未知
错误不变。 只收到确认的缺失表格/列驱动诊断
迁移/回填指令,保留原错误作为原因.
Fact 声明 catalog_search 作为其允许的最终衍生列; 自定义
正常化必须维护这一宣言,不能取代框架
身份、租户、修订或冲突栏.
调节准入范围
reconcile({ rawInput, tenantId, accessScope: 'public' }) 分区候选人
既包括租户,也包括精确、有应用定义的范围标志。 精确匹配和
语义排名在候选文本被水分或发送之前排除了其他范围
{\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}去散开 创造的事实和演变分支保留这一范围;
branch() 反对明确的范围变化。 使用公开收集的上游
例如 facts.list({ where: { tenantId, accessScope: 'public' } }) 范围
get() 重用结果时呼叫。 一般目录和演化 API 不
默示授权范围:申请必须授权访问和适用
其范围在提交证据或将条款事实联系起来之前即为上游.
托肯是大小写敏感、非空格字符串,最多256个字符没有 控制字符或未给付代位符。 他们是分区识别器, 未授权 全权证书申请必须来自可信赖的授权国; 绝不接受任意的客户端选择的符号作为阅读范围的权限. 事实必须仅以其范围所代表的能见度来汇总来源. 源元数据不能确定候选人的能见度.
accessScope 由服务器管理:生成的 REST/ MCP 创建和更新输入
在允许普通可写字字段时将其剥去。 信任的服务器侧
FactCollection.create(), (中文(简体) ), reconcile() 财务报告和审定财务报表 branch() 保持持续访问.
所有者授权的迁移代码可以指定字段并调用 save() 在一个
有对齐写符的系统上下文已停止;没有生成
重分类端点被曝光 。 不要暴露操作程序或
转发未信任的请求机构来引导收藏撰写.
运行标准 smrt db:migrate 在部署使用此字段的作者之前.
无效 Fact.accessScope 栏中未对已存在的行进行分类.
选择 accessScope (或通过) null) 只搜索此遗产 NULL
分区; 明确范围绝不包括遗留行。 没有迁移猜测
来源元数据的能见度。 只能通过
停止所有者授权的数据与对账写入器的迁移,或将它们分开并重新摘录到
适当范围。 范围变化不是普通的调节行动.
PostgreSQL 调节保留其交易事实/源写和 每个身份的锁。 SQLite 保留其现有的部分写合同:失败 来源书写可能留下事实,重试发现相同的范围精确事实. 在全部写入成功之前不要记录应用程序提取收据 .