World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 图谱查询工具(#558):`paths_between`、`neighbors`、`timeline`,以及
//! `find_entities` 的排序和 `entity_facts` 的过滤与分组。
//!
//! 从前模型手里的图谱只有两个动作:按名找实体、倒出一个实体的全部事实。
//! 「OpenAI 和 Anthropic 的关系」要它自己把两边几百条事实在上下文里连线,
//! 十六次里三次连上;「OpenAI 的时间线」是一份 433 行的倾倒,它自己排序。
//! 这里把查询的活收回服务端:路径是服务端搜的,邻居按谓词分好组,时间线按
//! 世界时间排好,事实可以按谓词、对象类型、时段筛。
//!
//! **实体参数收 uuid 也收名字。** 收名字是为了省掉一轮 find_entities,以及那一轮
//! 之后常见的「你说的是哪个 OpenAI」——排序规则挑一个,把挑了谁、还有谁一并
//! 写在结果最上面,模型不同意就拿 id 再来一次。
use super::tools::{
entity_facts_detail, fact_line, just_before, literal_text, parse_when, Step, ToolCtx,
ToolResult, ToolSink,
};
use serde_json::{json, Value};
use std::collections::{BTreeMap, HashMap, HashSet};
use utopia_core::models::{EntityFact, GraphNode};
use utopia_store::paths::{Limits, Path, PathEdge};
use uuid::Uuid;
const NEIGHBORS_DEFAULT: usize = 40;
const TIMELINE_DEFAULT: usize = 60;
const FACTS_DEFAULT: usize = 80;
const LIST_MAX: usize = 300;
// ---- 实体参数 -------------------------------------------------------------------
/// 名字匹配的排序:**类型判出来的在前,同名精确命中在前,事实多的在前**。
///
/// 没类型的短语("lawsuit against OpenAI",#559)在有别的候选时不列:它们几乎全是
/// 抽取漏进来的描述,列出来只会把问题变成一次消歧。全是 untyped 时照列——一个
/// 类型都没判出来的库也得能用。**叫这个名字的照列,有没有类型都一样**:问的就是
/// "Acme",而 Acme 本身还没判出类型时,只剩一个 "Acme lawsuit" 是把人引到错的实体上,
/// 没类型的实体也得找得到(0009)。
pub(super) fn rank(mut hits: Vec<GraphNode>, query: &str) -> Vec<GraphNode> {
let q = query.trim().to_lowercase();
let exact = |n: &GraphNode| n.name.trim().to_lowercase() == q;
if hits.iter().any(|n| n.type_label.is_some()) {
hits.retain(|n| n.type_label.is_some() || exact(n));
}
hits.sort_by(|a, b| {
exact(b)
.cmp(&exact(a))
.then(b.degree.cmp(&a.degree))
.then_with(|| a.name.cmp(&b.name))
});
hits
}
/// 第一名是不是明显的那一个:只有它,或只有它精确命中,或它的事实数是第二名的三倍
pub(super) fn dominant(ranked: &[GraphNode], query: &str) -> bool {
let q = query.trim().to_lowercase();
match ranked {
[] => false,
[_] => true,
[first, second, ..] => {
let exact = |n: &GraphNode| n.name.trim().to_lowercase() == q;
(exact(first) && !exact(second)) || first.degree >= 3 * second.degree.max(1)
}
}
}
fn node_line(n: &GraphNode) -> String {
let dis = n
.disambiguator
.as_deref()
.map(|d| format!(" ({d})"))
.unwrap_or_default();
format!(
"{} | {}{} | {} | {} facts",
n.id,
n.name,
dis,
// 没判出类型的实体照样能被搜到、被引用(0009)
n.type_label.as_deref().unwrap_or("untyped"),
n.degree
)
}
/// 记下这一轮认下的实体。下一轮会被告知「直接用这些 id,别再按名字查」,所以这里
/// 只能是真的读过、或者搜索明确指向的那个——同一轮先按名字认、再按 id 读,只记一次
fn remember(sink: &mut ToolSink, n: &GraphNode) {
let id = n.id.to_string();
if sink.resolved.iter().any(|e| e["id"] == id.as_str()) {
return;
}
sink.resolved.push(json!({
"id": id, "name": n.name, "type": n.type_label
}));
}
/// 一个实体参数解析成 id。名字走 [`rank`],挑了谁写进 `note` 交给结果开头
struct Resolved {
id: Uuid,
name: String,
note: Option<String>,
/// 参数本来就是一个 id:没在库里查过,`name` 也只是那串 id
by_id: bool,
}
enum ResolveError {
Unresolved(String),
ReadFailed,
}
async fn resolve(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
raw: &str,
) -> Result<Resolved, ResolveError> {
let raw = raw.trim();
if raw.is_empty() {
return Err(ResolveError::Unresolved(
"an entity name or id is required".to_string(),
));
}
if let Ok(id) = raw.parse::<Uuid>() {
return Ok(Resolved {
id,
name: raw.to_string(),
note: None,
by_id: true,
});
}
let (hits, _) = lookup(ctx, raw).await.map_err(|e| {
tracing::warn!(error = %e, "Entity lookup failed");
ResolveError::ReadFailed
})?;
let (ranked, by_question) = rank_by_question(ctx, sink, rank(hits, raw), raw).await;
let Some(first) = ranked.first() else {
return Err(ResolveError::Unresolved(format!(
"no entity named \"{raw}\" in this base"
)));
};
remember(sink, first);
let others: Vec<String> = ranked
.iter()
.skip(1)
.take(4)
.map(|n| {
format!(
"{} ({}, {} facts, {})",
n.name,
n.type_label.as_deref().unwrap_or("untyped"),
n.degree,
n.id
)
})
.collect();
let mut note = format!(
"\"{raw}\" = {} ({}, {} facts)",
first.name,
first.type_label.as_deref().unwrap_or("untyped"),
first.degree
);
if by_question {
note.push_str(", closest to the question");
}
if !others.is_empty() {
note.push_str(&format!(
"; other matches: {}. Pass an id to choose another.",
others.join("; ")
));
}
Ok(Resolved {
id: first.id,
name: first.name.clone(),
note: Some(note),
by_id: false,
})
}
/// 时刻参数三件套:`at` 世界轴,`as_of` / `before` 记录轴(before 优先,减一微秒)
struct Moments {
at: Option<chrono::DateTime<chrono::Utc>>,
as_of: Option<chrono::DateTime<chrono::Utc>>,
before: Option<chrono::DateTime<chrono::Utc>>,
}
fn moments(args: &Value) -> Moments {
let at = args["at"].as_str().and_then(parse_when);
let before = args["before"].as_str().and_then(parse_when);
let as_of = match before {
Some(t) => Some(just_before(t)),
None => args["as_of"].as_str().and_then(parse_when),
};
Moments { at, as_of, before }
}
fn limit_of(args: &Value, default: usize) -> usize {
args["limit"]
.as_u64()
.map(|n| n as usize)
.filter(|n| *n > 0)
.unwrap_or(default)
.min(LIST_MAX)
}
fn contains_ci(haystack: Option<&str>, needle: &str) -> bool {
haystack.is_some_and(|h| h.to_lowercase().contains(&needle.to_lowercase()))
}
// ---- evidence marks (#935) -------------------------------------------------------
/// 这一次显示出来的事实各自的第一条有效证据(#935)。
///
/// 事实行上印它的 `[n]`,证据块登进这一轮的来源清单,界面上点开就是那句原话;从前
/// 图谱答出来的回答一个号也没有,界面只能说「未引用任何来源」。印哪一行时才登记,
/// 所以号码按出现的顺序排,与检索结果共用一套号(同一块只有一个号)。
///
/// 没有来源清单(MCP)、或证据读不出来时是空的:事实行照旧,不带号。
///
/// 每条事实还带着那条证据的引文(#968 的后续):号打开的是那一块,条目里的 `quotes`
/// 是块里说出它的那一句,界面据此把那句话标出来
struct Evidence(HashMap<Uuid, (utopia_core::models::ChunkView, Option<String>)>);
impl Evidence {
/// 事实 id 收成自有的 `Vec` 再传进来:借着显示列表的迭代器跨 await 持有,工具的
/// future 就不再对所有生命周期都是 `Send`(对话的钩子与 MCP 路由都要求它)
async fn load(
ctx: &ToolCtx<'_>,
fact_ids: Vec<Uuid>,
as_of: Option<chrono::DateTime<chrono::Utc>>,
) -> Self {
if !ctx.has_source_list() {
return Self(HashMap::new());
}
match utopia_store::graph::first_live_evidence(&ctx.state.pool, ctx.kb_id, &fact_ids, as_of)
.await
{
Ok(rows) => Self(
rows.into_iter()
.map(|(fact, chunk, quote)| (fact, (chunk, quote)))
.collect(),
),
Err(e) => {
tracing::warn!(error = %e, "Evidence lookup for citation marks failed");
Self(HashMap::new())
}
}
}
/// 关上这一行的那一行的号(#970 第二步):推出来的终点在那条事实的原句里写着
fn closer_mark(&self, sink: &mut ToolSink, f: &EntityFact) -> String {
f.closed_by_id
.map(|id| self.mark(sink, id))
.unwrap_or_default()
}
/// ` [n]`:这条事实的证据登进清单后的号。没有有效证据的事实(派生事实也是)不带号
fn mark(&self, sink: &mut ToolSink, fact_id: Uuid) -> String {
match self.0.get(&fact_id) {
Some((chunk, quote)) => {
let n = super::tools::cite(sink, chunk.id.to_string(), |n| {
super::tools::source_json(n, chunk)
});
if let Some(quote) = quote {
super::tools::add_quote(sink, n, quote);
}
format!(" [{n}]")
}
None => String::new(),
}
}
}
/// 显示的事实加上关上它们的那几行(#970 第二步):一次证据查询把两边的块都读回来
fn with_closers<'f>(facts: impl IntoIterator<Item = &'f EntityFact>) -> Vec<Uuid> {
facts
.into_iter()
.flat_map(|f| std::iter::once(f.id).chain(f.closed_by_id))
.collect()
}
// ---- find_entities ---------------------------------------------------------------
pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let name = args["name"].as_str().unwrap_or("").to_string();
let (hits, total) = match lookup(ctx, &name).await {
Ok(found) => found,
Err(e) => {
tracing::warn!(error = %e, "Entity lookup failed");
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("entity", name, "failed").status("failed").json(),
)
.error();
}
};
let read = hits.len();
let (ranked, by_question) = rank_by_question(ctx, sink, rank(hits, &name), &name).await;
let clear = by_question || dominant(&ranked, &name);
let mut text = if ranked.is_empty() {
"No matching entities.".to_string()
} else if clear {
let mut lines = vec![format!("Best match: {}", node_line(&ranked[0]))];
if ranked.len() > 1 {
lines.push("Other matches:".to_string());
lines.extend(ranked[1..].iter().map(node_line));
}
lines.join("\n")
} else {
let mut lines = vec![format!(
"Several entities match \"{name}\"; pick by type and fact count, or ask the user:"
)];
lines.extend(ranked.iter().map(node_line));
lines.join("\n")
};
// 截断要说出来(与 `rule_matches` 同一条):只读了前几个,模型会把它们当成这个
// 名字的全部,然后告诉人「库里只有这几个」
if let Some(total) = total.filter(|t| *t > read as i64) {
text.push_str(&format!(
"\n({total} entities have a name containing \"{name}\"; only the first {read} were \
read. A longer or more exact name narrows the search.)"
));
}
// 同名歧义时候选只是搜索结果,不是认下的实体。从前这里全记,下一轮就收到一串
// 同名的 id 和一句「直接用这些」,没选的那个还常常排在前面。选中的那个在它被
// 读的时候记(entity_facts / neighbors / timeline);上一轮的候选另有工具往返
// 的回放可查
if let Some(best) = ranked.first().filter(|_| clear) {
remember(sink, best);
}
let mut step =
Step::new("entity", name.as_str(), format!("{} matches", ranked.len())).count(ranked.len());
if let Some(total) = total.filter(|t| *t > read as i64) {
step = step.total(total as usize);
}
ToolResult::new(text, step.json()).structured(json!({
"kb_id": ctx.kb_id,
"entities": ranked.iter().map(|n| json!({
"id": n.id, "name": n.name, "type_key": n.type_key,
"type_label": n.type_label, "disambiguator": n.disambiguator,
"fact_count": n.degree,
})).collect::<Vec<_>>()
}))
}
// ---- entity_facts ----------------------------------------------------------------
/// 事实的另一端:对端实体,或属性值
/// 边上的属性(0037)跟在对端后面:`Vega Capital [amount: 5000000000 $]`。
/// 模型读事实行时最常问的就是"投了多少",数不在行里它就答"没有金额信息"。
/// 按文档角色词记的属性(0061)接在后面,名字是角色词:`[lines: 10-42]`
fn qualifiers_text(f: &EntityFact) -> String {
let typed = f
.qualifiers
.iter()
.map(|q| qualifier_text(&q.key, q.value.as_ref(), q.entity_name.as_deref()));
let worded = f
.statement_qualifiers
.iter()
.map(|q| qualifier_text(&q.role, q.value.as_ref(), q.entity_name.as_deref()));
let parts: Vec<String> = typed.chain(worded).collect();
if parts.is_empty() {
return String::new();
}
format!(" [{}]", parts.join(", "))
}
fn qualifier_text(name: &str, value: Option<&Value>, entity_name: Option<&str>) -> String {
let v = value
.and_then(|v| v.get("value"))
.map(|v| match v {
Value::String(s) => s.clone(),
other => other.to_string(),
})
.or_else(|| entity_name.map(String::from))
.unwrap_or_else(|| "?".to_string());
let u = value
.and_then(|v| v.get("unit"))
.and_then(|u| u.as_str())
.map(|u| format!(" {u}"))
.unwrap_or_default();
format!("{name}: {v}{u}")
}
fn other_text(f: &EntityFact) -> String {
let literal = f
.object_value
.as_ref()
.and_then(literal_text)
.filter(|_| f.other_name.is_none());
f.other_name
.as_deref()
.or(literal.as_deref())
.unwrap_or("?")
.to_string()
}
/// `closer_mark` 是关上它的那一行证据的号(#970 第二步;MCP 与没有证据时为空)
fn range_text(f: &EntityFact, closer_mark: &str) -> String {
let successor =
super::tools::successor_text(f.closed_by.as_deref(), f.closed_by_value.as_ref());
let range = crate::time_text::span(crate::time_text::Span {
valid_from: f.valid_from,
from_precision: f.valid_from_precision.as_deref(),
valid_to: f.valid_to,
to_precision: f.valid_to_precision.as_deref(),
holds_from: f.holds_from,
holds_to: f.holds_to,
end_derived: f.end_derived,
corrected: f.corrected_ends.as_deref(),
closed_by: successor.as_deref().map(|who| (who, closer_mark)),
correction_note: f.correction_note.as_deref(),
});
if range.is_empty() {
range
} else {
format!(" ({range})")
}
}
fn confidence_text(f: &EntityFact) -> String {
format!("[{}%]", (f.confidence * 100.0).round() as i32)
}
/// 谓词组的抬头:出边 `pred →`,入边 `← pred`
fn group_key(f: &EntityFact) -> String {
let pred = f.predicate_label.as_deref().unwrap_or("?");
if f.direction == "out" {
format!("{pred} →")
} else {
format!("← {pred}")
}
}
/// 按谓词分组,多的组在前;组内保持传入顺序(时间序)。回 (组名, 该组事实)
pub(super) fn grouped(facts: &[EntityFact]) -> Vec<(String, Vec<&EntityFact>)> {
let mut groups: BTreeMap<String, Vec<&EntityFact>> = BTreeMap::new();
for f in facts {
groups.entry(group_key(f)).or_default().push(f);
}
let mut out: Vec<(String, Vec<&EntityFact>)> = groups.into_iter().collect();
out.sort_by(|a, b| b.1.len().cmp(&a.1.len()).then_with(|| a.0.cmp(&b.0)));
out
}
/// 过滤没命中时告诉模型这个实体身上有哪些谓词:它猜的词("board member")和
/// 库里的词(`comprised`、`has_member`)常常对不上(#560),空手而回它只会再猜一次
pub(super) fn predicates_of(facts: &[EntityFact]) -> String {
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
for f in facts {
*counts.entry(group_key(f)).or_default() += 1;
}
let mut named: Vec<(String, usize)> = counts.into_iter().collect();
named.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
named
.iter()
.take(20)
.map(|(k, n)| format!("{k} ({n})"))
.collect::<Vec<_>>()
.join(", ")
}
/// 子串找不到时按词找:每个词各去库里捞一把,名字里含的词数达到「全部减一、至少两个」
/// 的候选算命中("OpenAI board members" → "OpenAI's board of directors")。
/// 模型给的名字常带一个库里没有的词(members、公司、这个),全词命中会把它们全漏掉
///
/// 回的是查到的实体,以及这个名字一共命中几个。只读前八个,总数用来告诉模型这不是
/// 全部;按词拼凑的那一路没有总数
async fn lookup(
ctx: &ToolCtx<'_>,
raw: &str,
) -> utopia_core::AppResult<(Vec<GraphNode>, Option<i64>)> {
// 工具调用来自聊天 / MCP:当下的问题,不在回放里。传 None 让 `degree` 按
// 现在算——和现状一致,回放图上的搜索框另走 `/kbs/{id}/entities` 自己挂
// 时刻
let (hits, total) =
utopia_store::graph::search_entities(&ctx.state.pool, ctx.kb_id, raw, 8, 0, None).await?;
if !hits.is_empty() {
return Ok((hits, Some(total)));
}
let words: Vec<&str> = raw.split_whitespace().filter(|w| w.len() >= 2).collect();
if words.len() < 2 {
return Ok((hits, Some(total)));
}
let mut pool: Vec<GraphNode> = Vec::new();
for w in &words {
let (found, _) =
utopia_store::graph::search_entities(&ctx.state.pool, ctx.kb_id, w, 40, 0, None)
.await?;
for n in found {
if !pool.iter().any(|p| p.id == n.id) {
pool.push(n);
}
}
}
let need = words.len().saturating_sub(1).max(2);
let mut scored: Vec<(usize, GraphNode)> = pool
.into_iter()
.map(|n| (word_score(&n.name, &words), n))
.filter(|(s, _)| *s >= need)
.collect();
scored.sort_by(|a, b| b.0.cmp(&a.0).then(b.1.degree.cmp(&a.1.degree)));
Ok((scored.into_iter().map(|(_, n)| n).take(8).collect(), None))
}
/// 名字里含了几个词(大小写不敏感)
pub(super) fn word_score(name: &str, words: &[&str]) -> usize {
let lower = name.to_lowercase();
words
.iter()
.filter(|w| lower.contains(&w.to_lowercase()))
.count()
}
/// 同名候选按问题排:用户的问题嵌成向量,与候选的上下文画像比,近的在前。问题一轮
/// 只嵌一次(`embed_once`):这一轮里每按名字查一次实体都会走到这里,句子却是同一句。
/// 精确命中仍在前(问 OpenAI 就先给叫 OpenAI 的),画像只在同一档里排序。
/// 没有问题(MCP)、没有嵌入模型、只有一个候选:原样返回,第二个值说明有没有用上
async fn rank_by_question(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
ranked: Vec<GraphNode>,
query: &str,
) -> (Vec<GraphNode>, bool) {
if ranked.len() < 2 {
return (ranked, false);
}
let Some(question) = ctx.question else {
return (ranked, false);
};
let Some(vec) = ctx.embed_once(sink, question).await else {
return (ranked, false);
};
let ids: Vec<Uuid> = ranked.iter().map(|n| n.id).collect();
let Ok(dist) =
utopia_store::graph::profile_distances(&ctx.state.pool, ctx.kb_id, &ids, &vec).await
else {
return (ranked, false);
};
let dist: HashMap<Uuid, f64> = dist.into_iter().collect();
(reorder_by_distance(ranked, query, &dist), true)
}
/// 纯函数:精确命中的一档在前;档内按画像距离升序,没有画像的垫底;再按事实数
pub(super) fn reorder_by_distance(
mut ranked: Vec<GraphNode>,
query: &str,
dist: &HashMap<Uuid, f64>,
) -> Vec<GraphNode> {
let q = query.trim().to_lowercase();
let exact = |n: &GraphNode| n.name.trim().to_lowercase() == q;
ranked.sort_by(|a, b| {
exact(b)
.cmp(&exact(a))
.then_with(|| {
let da = dist.get(&a.id).copied().unwrap_or(f64::MAX);
let db = dist.get(&b.id).copied().unwrap_or(f64::MAX);
da.partial_cmp(&db).unwrap_or(std::cmp::Ordering::Equal)
})
.then(b.degree.cmp(&a.degree))
});
ranked
}
/// 谓词参数与库里的词对齐:模型说 "board member",库里叫 `has_member`。子串对不上时
/// 把它嵌一次,取最近的关系类型(关系向量在 `relation_types.embedding`),距离在
/// 上限内的算它说的是那几个。自动扩本体造出的关系没有向量(#560),对不到
const PREDICATE_DISTANCE: f32 = 0.45;
const PREDICATE_CANDIDATES: i64 = 5;
async fn aligned_predicates(ctx: &ToolCtx<'_>, sink: &mut ToolSink, word: &str) -> Vec<String> {
let Some(vec) = ctx.embed_once(sink, word).await else {
return Vec::new();
};
let near = utopia_store::ontology::nearest_relation_types(
&ctx.state.pool,
ctx.kb_id,
&vec,
PREDICATE_CANDIDATES,
None,
)
.await
.unwrap_or_default();
for c in &near {
tracing::debug!(word, key = c.key, distance = c.distance, "谓词对齐候选");
}
near.into_iter()
.filter(|c| c.distance <= PREDICATE_DISTANCE)
.map(|c| c.key)
.collect()
}
/// 过滤;谓词按子串对不上时向量对齐一次,回一句说明给结果开头
async fn filtered<'f>(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
facts: &'f [EntityFact],
filter: &FactFilter<'_>,
) -> (Vec<&'f EntityFact>, Option<String>) {
let kept: Vec<&EntityFact> = facts.iter().filter(|f| filter.keeps(f)).collect();
let Some(word) = filter.predicate else {
return (kept, None);
};
if !kept.is_empty() || facts.is_empty() {
return (kept, None);
}
let keys: HashSet<String> = aligned_predicates(ctx, sink, word)
.await
.into_iter()
.collect();
if keys.is_empty() {
return (kept, None);
}
let widened = FactFilter {
predicate: None,
..*filter
};
let kept: Vec<&EntityFact> = facts
.iter()
.filter(|f| {
widened.keeps(f) && f.predicate_key.as_deref().is_some_and(|k| keys.contains(k))
})
.collect();
let mut names: Vec<&str> = keys.iter().map(String::as_str).collect();
names.sort();
let note = format!("predicate \"{word}\" read as {}", names.join(", "));
(kept, Some(note))
}
#[derive(Clone, Copy)]
struct FactFilter<'a> {
predicate: Option<&'a str>,
object_type: Option<&'a str>,
since: Option<chrono::DateTime<chrono::Utc>>,
until: Option<chrono::DateTime<chrono::Utc>>,
}
impl FactFilter<'_> {
fn from_args(args: &Value) -> FactFilter<'_> {
FactFilter {
predicate: args["predicate"].as_str().filter(|s| !s.trim().is_empty()),
object_type: args["object_type"]
.as_str()
.filter(|s| !s.trim().is_empty()),
since: args["since"].as_str().and_then(parse_when),
until: args["until"].as_str().and_then(parse_when),
}
}
fn narrows(&self) -> bool {
self.predicate.is_some()
|| self.object_type.is_some()
|| self.since.is_some()
|| self.until.is_some()
}
/// 时段用**说出来的**区间:起点在 until 之前、终点在 since 之后(开放的终点算在后)
fn keeps(&self, f: &EntityFact) -> bool {
if let Some(p) = self.predicate {
if !contains_ci(f.predicate_key.as_deref(), p)
&& !contains_ci(f.predicate_label.as_deref(), p)
{
return false;
}
}
if let Some(t) = self.object_type {
if !contains_ci(f.other_type.as_deref(), t) {
return false;
}
}
if let Some(until) = self.until {
if f.valid_from.is_some_and(|from| from > until) {
return false;
}
}
if let Some(since) = self.since {
if f.valid_to.is_some_and(|to| to < since) {
return false;
}
}
true
}
}
pub async fn entity_facts(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let raw = args["entity_id"]
.as_str()
.or_else(|| args["entity"].as_str())
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
Err(ResolveError::ReadFailed) => {
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("facts", "?", "failed").status("failed").json(),
)
.error();
}
Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!(
"Invalid entity: {e} (expected a name, or the uuid returned by find_entities)."
),
Step::new("facts", "?", "invalid id")
.status("not_found")
.json(),
)
.error()
}
};
let m = moments(args);
let filter = FactFilter::from_args(args);
let limit = limit_of(args, FACTS_DEFAULT);
let (node, facts) =
match utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, m.at, m.as_of)
.await
{
Ok(detail) => detail,
Err(e) => {
let text = if matches!(e, utopia_core::AppError::NotFound) {
"Entity not found."
} else {
tracing::warn!(error = %e, "Entity facts lookup failed");
"Could not read the entity facts."
};
return ToolResult::new(
text.into(),
Step::new("facts", "?", "failed").status("failed").json(),
)
.error();
}
};
// 按 id 读的也是认下:模型常常先搜到一串同名的,再按 id 读其中一个,读的这个
// 才是这一轮说的那个(按名字认下的 `resolve` 已记过,这里不会重复)
remember(sink, &node);
// 规则的结论也是这个实体的一部分(0021)。**不给的话模型会拿那些读数自己再判
// 一遍**——而阈值写在规则里,它看不见,于是两处判断迟早不一致
let derived = match
// 两根轴一起传(#549):as_of 回到三月,派生也回到三月
utopia_store::reasoning::derived_for_entity(
&ctx.state.pool,
ctx.kb_id,
who.id,
m.at,
m.as_of,
)
.await {
Ok(derived) => derived,
Err(e) => {
tracing::warn!(error = %e, "Derived facts lookup failed");
return ToolResult::new("Could not read the derived facts.".into(),
Step::new("facts", node.name, "failed").status("failed").json()).error();
}
};
let derived_lines: Vec<String> = derived
.iter()
.map(|d| {
format!(
"{} · {} · {} [rule: {}]",
d.subject,
d.predicate,
d.object,
d.rule_name.as_deref().unwrap_or(&d.rule),
)
})
.collect();
// 名字单独一行(0041):「海探1」和「海洋探测器1号」是同一个,模型答题时要知道
let names = utopia_store::names::for_entity(&ctx.state.pool, ctx.kb_id, who.id, m.as_of)
.await
.unwrap_or_else(|e| {
tracing::warn!(error = %e, "Entity names lookup failed");
Vec::new()
});
let (kept, aligned) = filtered(ctx, sink, &facts, &filter).await;
let shown: Vec<&EntityFact> = kept.iter().copied().take(limit).collect();
let mut lines: Vec<String> = Vec::new();
if let Some(note) = &who.note {
lines.push(note.clone());
}
let other_names: Vec<&str> = names
.iter()
.filter(|n| !n.canonical)
.map(|n| n.name.as_str())
.collect();
if !other_names.is_empty() {
lines.push(format!("Also known as: {}", other_names.join(", ")));
}
if let Some(a) = &aligned {
lines.push(a.clone());
}
let type_label = node.type_label.as_deref().unwrap_or("untyped");
if facts.is_empty() && derived.is_empty() {
lines.push(match m.at {
Some(t) => format!(
"{}: no facts valid as of {}.",
node.name,
crate::time_text::instant(t)
),
None => format!("{}: no recorded facts.", node.name),
});
} else {
let mut head = format!("{} ({type_label}) · {} facts", node.name, facts.len());
if filter.narrows() {
head.push_str(&format!(", {} match the filter", kept.len()));
if kept.is_empty() {
head.push_str(&format!(
". Predicates on this entity: {}",
predicates_of(&facts)
));
}
}
if shown.len() < kept.len() {
head.push_str(&format!(
", {} shown. Narrow with predicate=, object_type=, since/until; timeline for the \
dated ones; neighbors for the related entities",
shown.len()
));
}
lines.push(head);
let ids = with_closers(shown.iter().copied());
let evidence = Evidence::load(ctx, ids, m.as_of).await;
let shown_owned: Vec<EntityFact> = shown.iter().map(|f| (*f).clone()).collect();
for (key, group) in grouped(&shown_owned) {
lines.push(format!("## {key} ({})", group.len()));
for f in group {
let closer = evidence.closer_mark(sink, f);
lines.push(format!(
"{}{}{} {}{}",
other_text(f),
qualifiers_text(f),
range_text(f, &closer),
confidence_text(f),
evidence.mark(sink, f.id)
));
}
}
// 派生事实自己不带号:它是规则算出来的,出处在它的前提上,前提各带各的
lines.extend(derived_lines);
}
let detail = entity_facts_detail(shown.len(), m.at, m.as_of, m.before);
ToolResult::new(
lines.join("\n"),
Step::new("facts", node.name.as_str(), detail)
.count(shown.len())
.moments(m.at, m.as_of, m.before)
.json(),
)
.structured(json!({
"kb_id": ctx.kb_id,
"entity": {"id": node.id, "name": node.name,
"type_key": node.type_key, "type_label": node.type_label},
"names": names.iter().map(|n| json!({
"fact_id": n.fact_id, "name": n.name, "canonical": n.canonical,
"recorded_at": n.recorded_at, "valid_from": n.valid_from, "valid_to": n.valid_to,
"document_ids": n.document_ids,
})).collect::<Vec<_>>(),
"at": m.at, "as_of": m.as_of, "before": m.before,
"total_facts": facts.len(), "matched_facts": kept.len(),
"limit": limit, "truncated": shown.len() < kept.len(),
"facts": shown.iter().map(|f| json!({
"id": f.id, "direction": f.direction,
"predicate_key": f.predicate_key, "predicate_label": f.predicate_label,
"inferred": f.inferred, "temporal": f.temporal,
"other_id": f.other_id, "other_name": f.other_name,
"object_value": f.object_value, "confidence": f.confidence,
"qualifiers": f.qualifiers.iter().map(|q| json!({
"qualifier_type_id": q.qualifier_type_id, "key": q.key, "label": q.label,
"value": q.value, "entity_id": q.entity_id, "entity_name": q.entity_name,
})).collect::<Vec<_>>(),
"statement_qualifiers": f.statement_qualifiers,
"valid_from": f.valid_from, "valid_to": f.valid_to,
"valid_from_precision": f.valid_from_precision,
"valid_to_precision": f.valid_to_precision,
"holds_from": f.holds_from, "holds_to": f.holds_to,
"recorded_at": f.recorded_at, "invalidated_at": f.invalidated_at,
"supersedes": f.supersedes, "document_ids": f.document_ids,
})).collect::<Vec<_>>(),
"derived_facts": derived.iter().map(|d| json!({
"id": d.id, "subject_id": d.subject_id, "subject": d.subject,
"predicate_id": d.predicate_id, "predicate": d.predicate,
"object_id": d.object_id, "object": d.object, "object_value": d.object_value,
"rule": d.rule, "rule_name": d.rule_name,
"rule_id": d.rule_id, "attribute_rule_id": d.attribute_rule_id,
"valid_from": d.valid_from, "valid_to": d.valid_to,
"valid_from_precision": d.valid_from_precision,
"valid_to_precision": d.valid_to_precision,
"derived_at": d.derived_at, "invalidated_at": d.invalidated_at,
"confidence": d.confidence,
})).collect::<Vec<_>>()
}))
}
// ---- neighbors -------------------------------------------------------------------
pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let raw = args["entity"]
.as_str()
.or_else(|| args["entity_id"].as_str())
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
Err(ResolveError::ReadFailed) => {
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("neighbors", "?", "failed")
.status("failed")
.json(),
)
.error();
}
Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown entity: {e}."),
Step::new("neighbors", "?", "unknown entity")
.status("not_found")
.json(),
)
}
};
let m = moments(args);
let filter = FactFilter::from_args(args);
let limit = limit_of(args, NEIGHBORS_DEFAULT);
let (node, facts) =
match utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, m.at, m.as_of)
.await
{
Ok(detail) => detail,
Err(utopia_core::AppError::NotFound) => {
return ToolResult::new(
"Entity not found.".to_string(),
Step::new("neighbors", "?", "not found")
.status("not_found")
.json(),
);
}
Err(e) => {
tracing::warn!(error = %e, "Entity neighbors lookup failed");
return ToolResult::new(
"Could not read the entity facts.".into(),
Step::new("neighbors", "?", "failed")
.status("failed")
.json(),
)
.error();
}
};
remember(sink, &node);
// 邻居是对端**实体**;属性值不算邻居,entity_facts 里有
let (matched, aligned) = filtered(ctx, sink, &facts, &filter).await;
let linked: Vec<&EntityFact> = matched
.into_iter()
.filter(|f| f.other_id.is_some())
.collect();
let shown: Vec<EntityFact> = linked.iter().take(limit).map(|f| (*f).clone()).collect();
let mut lines: Vec<String> = Vec::new();
if let Some(note) = &who.note {
lines.push(note.clone());
}
if let Some(a) = &aligned {
lines.push(a.clone());
}
let type_label = node.type_label.as_deref().unwrap_or("untyped");
if shown.is_empty() {
let all_linked: Vec<EntityFact> = facts
.iter()
.filter(|f| f.other_id.is_some())
.cloned()
.collect();
let hint = if filter.narrows() && !all_linked.is_empty() {
format!(" Predicates on this entity: {}", predicates_of(&all_linked))
} else {
String::new()
};
lines.push(format!(
"{} ({type_label}): no linked entities{}.{hint}",
node.name,
if filter.narrows() {
" match the filter"
} else {
""
}
));
} else {
let ids = with_closers(shown.iter());
let evidence = Evidence::load(ctx, ids, m.as_of).await;
let groups = grouped(&shown);
// 数的是对端实体,不是事实:同一条边常是两条事实(一条带日期一条不带)
let entities: HashSet<Uuid> = linked.iter().filter_map(|f| f.other_id).collect();
let mut head = format!(
"{} ({type_label}): {} linked entities under {} predicates",
node.name,
entities.len(),
groups.len()
);
if shown.len() < linked.len() {
head.push_str(&format!(
" ({} shown; narrow with predicate= or object_type=)",
shown.len()
));
}
lines.push(head);
for (key, group) in groups {
let items: Vec<String> = group
.iter()
.map(|f| {
let ty = f
.other_type
.as_deref()
.map(|t| format!(" [{t}]"))
.unwrap_or_default();
let closer = evidence.closer_mark(sink, f);
format!(
"{}{}{} {}{}",
other_text(f),
ty,
range_text(f, &closer),
confidence_text(f),
evidence.mark(sink, f.id)
)
})
.collect();
lines.push(format!("{key} {}", items.join(" · ")));
}
}
let detail = format!("{} of {} linked", shown.len(), linked.len());
ToolResult::new(
lines.join("\n"),
Step::new("neighbors", node.name, detail)
.count(shown.len())
.total(linked.len())
.json(),
)
}
// ---- timeline --------------------------------------------------------------------
pub async fn timeline(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let raw = args["entity"]
.as_str()
.or_else(|| args["entity_id"].as_str())
.unwrap_or("");
let who = match resolve(ctx, sink, raw).await {
Ok(r) => r,
Err(ResolveError::ReadFailed) => {
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("timeline", "?", "failed").status("failed").json(),
)
.error();
}
Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown entity: {e}."),
Step::new("timeline", "?", "unknown entity")
.status("not_found")
.json(),
)
}
};
let m = moments(args);
let filter = FactFilter::from_args(args);
let limit = limit_of(args, TIMELINE_DEFAULT);
let (node, facts) =
match utopia_store::graph::entity_detail(&ctx.state.pool, ctx.kb_id, who.id, None, m.as_of)
.await
{
Ok(detail) => detail,
Err(utopia_core::AppError::NotFound) => {
return ToolResult::new(
"Entity not found.".to_string(),
Step::new("timeline", "?", "not found")
.status("not_found")
.json(),
);
}
Err(e) => {
tracing::warn!(error = %e, "Entity timeline lookup failed");
return ToolResult::new(
"Could not read the entity facts.".into(),
Step::new("timeline", "?", "failed").status("failed").json(),
)
.error();
}
};
remember(sink, &node);
// 只要**说出了世界时间**的事实。没日期的那些起点是摄取时刻,排进时间线只会
// 把一篇文章的日期当成事件的日期
let (matched, aligned) = filtered(ctx, sink, &facts, &filter).await;
let mut dated: Vec<&EntityFact> = matched
.into_iter()
.filter(|f| f.valid_from.is_some())
.collect();
dated.sort_by_key(|f| f.valid_from);
let undated = facts.iter().filter(|f| f.valid_from.is_none()).count();
let shown: Vec<&EntityFact> = dated.iter().copied().take(limit).collect();
let mut lines: Vec<String> = Vec::new();
if let Some(note) = &who.note {
lines.push(note.clone());
}
if let Some(a) = &aligned {
lines.push(a.clone());
}
let type_label = node.type_label.as_deref().unwrap_or("untyped");
if shown.is_empty() {
lines.push(format!(
"{} ({type_label}): no dated facts{}; {undated} facts carry no date (entity_facts lists them).",
node.name,
if filter.narrows() { " in that window" } else { "" }
));
} else {
let first = shown[0].valid_from.expect("dated");
let last = shown[shown.len() - 1].valid_from.expect("dated");
let mut head = format!("{} ({type_label}): {} dated facts", node.name, dated.len());
if shown.len() < dated.len() {
head.push_str(&format!(
", {} shown from {} to {} (pass since/until to see the rest)",
shown.len(),
crate::time_text::world(first, shown[0].valid_from_precision.as_deref()),
crate::time_text::world(
last,
shown[shown.len() - 1].valid_from_precision.as_deref()
)
));
}
if undated > 0 {
head.push_str(&format!(
"; {undated} undated facts omitted (entity_facts has them)"
));
}
lines.push(head);
let ids = with_closers(shown.iter().copied());
let evidence = Evidence::load(ctx, ids, m.as_of).await;
for f in &shown {
let stamp = crate::time_text::world(
f.valid_from.expect("dated"),
f.valid_from_precision.as_deref(),
);
let closer = evidence.closer_mark(sink, f);
lines.push(format!(
"{stamp} {}{}",
fact_line(f, &closer),
evidence.mark(sink, f.id)
));
}
}
let detail = format!("{} of {} dated", shown.len(), dated.len());
ToolResult::new(
lines.join("\n"),
Step::new("timeline", node.name, detail)
.count(shown.len())
.total(dated.len())
.json(),
)
}
// ---- paths_between ---------------------------------------------------------------
/// 一条边在链上的写法:顺着走 `A —pred→ B`,逆着走 `A ←pred— B`
pub(super) fn edge_text(prev: Uuid, e: &PathEdge, closer_mark: &str) -> String {
let pred = e.predicate.as_deref().unwrap_or("?");
let successor =
super::tools::successor_text(e.closed_by.as_deref(), e.closed_by_value.as_ref());
let range = crate::time_text::span(crate::time_text::Span {
valid_from: e.valid_from,
from_precision: e.valid_from_precision.as_deref(),
valid_to: e.valid_to,
to_precision: e.valid_to_precision.as_deref(),
holds_from: e.holds_from,
holds_to: e.holds_to,
end_derived: e.end_derived,
corrected: e.corrected_ends.as_deref(),
closed_by: successor.as_deref().map(|who| (who, closer_mark)),
correction_note: e.correction_note.as_deref(),
});
let range = if range.is_empty() {
range
} else {
format!(" ({range})")
};
let conf = (e.confidence * 100.0).round() as i32;
if e.subject_id == prev {
format!(
"{} —{pred}→ {}{range} [{conf}%]",
e.subject_name, e.object_name
)
} else {
format!(
"{} ←{pred}— {}{range} [{conf}%]",
e.object_name, e.subject_name
)
}
}
#[cfg(test)]
pub(super) fn path_text(p: &Path) -> String {
path_text_marked(p, |_| String::new())
}
/// 一条路径,每一跳后面跟着 `mark` 给那条事实的东西(对话里是它证据的 `[n]`,#935);
/// 时间线关上的那一跳,关它的那一行也由 `mark` 给号(#970 第二步)
fn path_text_marked(p: &Path, mut mark: impl FnMut(Uuid) -> String) -> String {
let mut parts = Vec::new();
for (i, e) in p.edges.iter().enumerate() {
let closer = e.closed_by_id.map(&mut mark).unwrap_or_default();
let own = mark(e.fact_id);
parts.push(format!("{}{own}", edge_text(p.nodes[i], e, &closer)));
}
parts.join("; ")
}
/// 一个端点在这条路径上的名字:路径两头的边写着它
fn name_on_path(p: &Path, id: Uuid) -> Option<&str> {
p.edges.iter().find_map(|e| {
if e.subject_id == id {
Some(e.subject_name.as_str())
} else if e.object_id == id {
Some(e.object_name.as_str())
} else {
None
}
})
}
pub async fn paths_between(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let mut notes = Vec::new();
let mut ends = Vec::new();
for key in ["from", "to"] {
match resolve(ctx, sink, args[key].as_str().unwrap_or("")).await {
Ok(r) => {
if let Some(n) = &r.note {
notes.push(n.clone());
}
ends.push(r);
}
Err(ResolveError::ReadFailed) => {
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("path", "?", "failed").status("failed").json(),
)
.error();
}
Err(ResolveError::Unresolved(e)) => {
return ToolResult::new(
format!("Unknown `{key}`: {e}."),
Step::new("path", "?", "unknown entity")
.status("not_found")
.json(),
)
}
}
}
let m = moments(args);
let max_hops = args["max_hops"]
.as_u64()
.map(|n| n as usize)
.unwrap_or(3)
.clamp(1, 3);
let limits = Limits {
max_hops,
..Limits::default()
};
let paths = match utopia_store::paths::paths_between(
&ctx.state.pool,
ctx.kb_id,
ends[0].id,
ends[1].id,
m.at,
m.as_of,
limits,
)
.await
{
Ok(p) => p,
Err(e) => {
tracing::warn!(error = %e, "Path search failed");
return ToolResult::new(
"Could not search paths.".into(),
Step::new("path", "?", "failed").status("failed").json(),
)
.error();
}
};
// 以 id 给出的一端没在库里查过。找到了路径,它就在路上,名字写在边上;没找到,
// 可能只是这个 id 不在这个库(抄错的、别的库的)——那时「两者之间没有路径」
// 读起来像一个关于图的事实,所以先认一遍,认不出就照实说
for (key, end) in ["from", "to"].into_iter().zip(ends.iter_mut()) {
if !end.by_id {
continue;
}
if let Some(p) = paths.first() {
if let Some(name) = name_on_path(p, end.id) {
end.name = name.to_string();
}
continue;
}
match utopia_store::graph::entity_node(&ctx.state.pool, ctx.kb_id, end.id, m.as_of).await {
Ok(Some(node)) => end.name = node.name,
Ok(None) => {
return ToolResult::new(
format!(
"Unknown `{key}`: no entity with id {} in this base.",
end.id
),
Step::new("path", "?", "unknown entity")
.status("not_found")
.json(),
)
}
Err(e) => {
tracing::warn!(error = %e, "Entity lookup failed");
return ToolResult::new(
"Could not look up entities.".into(),
Step::new("path", "?", "failed").status("failed").json(),
)
.error();
}
}
}
let (from, to) = (&ends[0], &ends[1]);
let label = format!("{} ↔ {}", from.name, to.name);
let when = match (m.at, m.before, m.as_of) {
(Some(t), _, _) => format!(" at {}", crate::time_text::world(t, Some("day"))),
(None, Some(b), _) => format!(" as recorded before {}", crate::time_text::instant(b)),
(None, None, Some(r)) => format!(" as recorded by {}", crate::time_text::instant(r)),
(None, None, None) => String::new(),
};
let mut lines = notes;
if paths.is_empty() {
lines.push(format!(
"No path of up to {max_hops} hop{} between {} and {}{when}. They may be unrelated in \
this base, or connected only through a hub; try neighbors on each.",
if max_hops == 1 { "" } else { "s" },
from.name,
to.name
));
return ToolResult::new(
lines.join("\n"),
Step::new("path", label, "no path").count(0).json(),
);
}
let shortest = paths[0].hops();
lines.push(format!(
"{} path{} between {} and {}{when} (up to {max_hops} hops, shortest first):",
paths.len(),
if paths.len() == 1 { "" } else { "s" },
from.name,
to.name
));
// 每一跳是一条事实,各带各的号;时间线关上的那一跳,关它的那一行也要号
let hops: Vec<Uuid> = paths
.iter()
.flat_map(|p| {
p.edges
.iter()
.flat_map(|e| std::iter::once(e.fact_id).chain(e.closed_by_id))
})
.collect();
let evidence = Evidence::load(ctx, hops, m.as_of).await;
for (i, p) in paths.iter().enumerate() {
let text = path_text_marked(p, |fact| evidence.mark(sink, fact));
lines.push(format!("{}. {}", i + 1, text));
}
if paths.len() >= limits.max_paths {
lines.push(format!(
"(Only the first {} paths, shortest first, are listed; there may be more.)",
limits.max_paths
));
}
let detail = format!(
"{} path{}, shortest {shortest} hop{}",
paths.len(),
if paths.len() == 1 { "" } else { "s" },
if shortest == 1 { "" } else { "s" }
);
ToolResult::new(
lines.join("\n"),
Step::new("path", label, detail)
.count(paths.len())
.more(paths.len() >= limits.max_paths)
.field("hops", shortest)
.json(),
)
}
#[cfg(test)]
mod tests {
use super::*;
fn node(name: &str, ty: Option<&str>, degree: i64) -> GraphNode {
GraphNode {
id: Uuid::now_v7(),
name: name.into(),
type_key: ty.map(|t| t.to_lowercase()),
type_label: ty.map(String::from),
color: "#000".into(),
shape: "circle".into(),
degree,
disambiguator: None,
}
}
/// 短语实体(untyped)不列,精确命中在前,事实多的在前
#[test]
fn a_name_match_is_ranked_by_type_exactness_and_weight() {
let hits = vec![
node("lawsuit against OpenAI", None, 5),
node("OpenAI's board of directors", Some("Organization"), 23),
node("OpenAI", Some("ResearchProject"), 555),
node("OpenAI LP", Some("Corporation"), 6),
];
let ranked = rank(hits, "OpenAI");
let names: Vec<&str> = ranked.iter().map(|n| n.name.as_str()).collect();
assert_eq!(
names,
["OpenAI", "OpenAI's board of directors", "OpenAI LP"],
"untyped 短语不列,精确命中第一"
);
assert!(
dominant(&ranked, "OpenAI"),
"精确命中且事实数是第二名的三倍"
);
}
/// 精确命中的 untyped 实体不被同名的有类型实体挤掉
#[test]
fn an_exact_untyped_match_is_not_hidden_by_a_typed_namesake() {
let ranked = rank(
vec![
node("Acme lawsuit", Some("Event"), 1),
node("Acme", None, 200),
node("Acme corporate history", None, 4),
],
"Acme",
);
let names: Vec<&str> = ranked.iter().map(|n| n.name.as_str()).collect();
assert_eq!(
names,
["Acme", "Acme lawsuit"],
"叫这个名字的 untyped 照列且在前;别的 untyped 短语仍不列"
);
assert!(dominant(&ranked, "Acme"), "只有它精确命中");
}
#[test]
fn a_base_with_no_types_still_lists_its_entities() {
let ranked = rank(
vec![node("Acme", None, 3), node("Acme Corp", None, 9)],
"acme",
);
let names: Vec<&str> = ranked.iter().map(|n| n.name.as_str()).collect();
assert_eq!(
names,
["Acme", "Acme Corp"],
"全 untyped 时照列,精确命中在前"
);
assert!(dominant(&ranked, "acme"));
}
/// 谁都不明显:两个同名同量级的实体,不替模型挑
#[test]
fn two_namesakes_of_equal_weight_are_not_dominant() {
let ranked = rank(
vec![
node("Zhang Wei", Some("Person"), 12),
node("Zhang Wei", Some("Person"), 10),
],
"Zhang Wei",
);
assert!(!dominant(&ranked, "Zhang Wei"));
let ranked = rank(
vec![
node("Zhang Wei", Some("Person"), 40),
node("Zhang Wei", Some("Person"), 10),
],
"Zhang Wei",
);
assert!(dominant(&ranked, "Zhang Wei"), "事实数三倍以上就明显");
}
fn fact(direction: &str, pred: &str, other: &str, other_type: Option<&str>) -> EntityFact {
EntityFact {
said_as: None,
recorded_at: chrono::Utc::now(),
invalidated_at: None,
supersedes: None,
document_ids: vec![],
id: Uuid::now_v7(),
direction: direction.into(),
predicate_key: Some(pred.into()),
predicate_label: Some(pred.into()),
inferred: false,
temporal: Some("state".into()),
other_id: Some(Uuid::now_v7()),
other_name: Some(other.into()),
other_type: other_type.map(String::from),
qualifiers: Vec::new(),
statement_qualifiers: Vec::new(),
object_value: None,
valid_from: Some("2021-01-01T00:00:00Z".parse().unwrap()),
valid_to: None,
valid_from_precision: Some("year".into()),
valid_to_precision: None,
holds_from: Some("2021-01-01T00:00:00Z".parse().unwrap()),
holds_to: None,
attested_by: None,
confidence: 0.9,
evidence_count: 1,
stale: false,
corrected: false,
end_derived: false,
end_after_period: false,
time_corrected: false,
corrected_ends: None,
closed_by_id: None,
closed_by: None,
closed_by_value: None,
correction_note: None,
last_evidence_time: None,
contested: None,
}
}
/// 问题的向量只在同一档里排序:精确命中的仍在前,档内近的先,没画像的垫底
#[test]
fn the_question_orders_namesakes_but_not_over_an_exact_match() {
let exact_far = node("Sam Altman", Some("Organization"), 66);
let exact_near = node("Sam Altman", Some("Person"), 27);
let partial_nearest = node("Sam Altman's efforts", Some("Event"), 2);
let no_profile = node("Sam Altman Jr", Some("Person"), 1);
let mut dist = HashMap::new();
dist.insert(exact_far.id, 0.40);
dist.insert(exact_near.id, 0.20);
dist.insert(partial_nearest.id, 0.05);
let ranked = reorder_by_distance(
vec![
exact_far.clone(),
no_profile.clone(),
partial_nearest.clone(),
exact_near.clone(),
],
"Sam Altman",
&dist,
);
let ids: Vec<Uuid> = ranked.iter().map(|n| n.id).collect();
assert_eq!(
ids,
vec![
exact_near.id,
exact_far.id,
partial_nearest.id,
no_profile.id
]
);
}
#[test]
fn a_multi_word_name_is_scored_by_the_words_it_contains() {
let words = ["OpenAI", "board", "members"];
assert_eq!(word_score("OpenAI's board of directors", &words), 2);
assert_eq!(word_score("OpenAI LP", &words), 1);
assert_eq!(word_score("openai board members list", &words), 3);
}
/// 空手而回时把实体身上的谓词报出来,多的在前
#[test]
fn an_empty_filter_names_the_predicates_that_exist() {
let facts = vec![
fact("out", "comprised", "Ilya Sutskever", Some("Person")),
fact("out", "comprised", "Helen Toner", Some("Person")),
fact("in", "removed", "Sam Altman", Some("Person")),
];
assert_eq!(predicates_of(&facts), "comprised → (2), ← removed (1)");
}
/// 分组:多的组在前,出边 `pred →`,入边 `← pred`
#[test]
fn facts_group_by_predicate_largest_group_first() {
let facts = vec![
fact("out", "employee", "Bob", Some("Person")),
fact("in", "founder", "Carol", Some("Person")),
fact("out", "employee", "Dan", Some("Person")),
];
let groups = grouped(&facts);
let keys: Vec<&str> = groups.iter().map(|(k, _)| k.as_str()).collect();
assert_eq!(keys, ["employee →", "← founder"]);
assert_eq!(groups[0].1.len(), 2);
}
/// 过滤:谓词按子串、对象类型按子串、时段按说出来的区间
#[test]
fn a_filter_reads_predicate_type_and_window() {
let mut f = fact("out", "works_for", "Acme", Some("Organization"));
f.valid_from = Some("2019-01-01T00:00:00Z".parse().unwrap());
f.valid_to = Some("2020-06-01T00:00:00Z".parse().unwrap());
fn filter<'a>(
p: Option<&'a str>,
t: Option<&'a str>,
since: Option<&str>,
until: Option<&str>,
) -> FactFilter<'a> {
FactFilter {
predicate: p,
object_type: t,
since: since.map(|s| s.parse().unwrap()),
until: until.map(|s| s.parse().unwrap()),
}
}
assert!(filter(Some("works"), None, None, None).keeps(&f));
assert!(!filter(Some("founder"), None, None, None).keeps(&f));
assert!(filter(None, Some("organ"), None, None).keeps(&f));
assert!(!filter(None, Some("person"), None, None).keeps(&f));
assert!(
filter(None, None, Some("2020-01-01T00:00:00Z"), None).keeps(&f),
"2020 年初它还在"
);
assert!(
!filter(None, None, Some("2021-01-01T00:00:00Z"), None).keeps(&f),
"2021 年它已结束"
);
assert!(
!filter(None, None, None, Some("2018-06-01T00:00:00Z")).keeps(&f),
"2018 年它还没开始"
);
assert!(!filter(None, None, None, None).narrows());
}
/// 链的写法:顺着走用 →,逆着走用 ←,每条边带自己的区间
#[test]
fn a_chain_reads_in_walking_order() {
let (a, x, b) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
let edge = |s: Uuid, sn: &str, o: Uuid, on: &str, pred: &str| PathEdge {
fact_id: Uuid::now_v7(),
subject_id: s,
subject_name: sn.into(),
object_id: o,
object_name: on.into(),
predicate: Some(pred.into()),
valid_from: Some("2021-01-01T00:00:00Z".parse().unwrap()),
valid_from_precision: Some("year".into()),
valid_to: None,
valid_to_precision: None,
holds_from: Some("2021-01-01T00:00:00Z".parse().unwrap()),
holds_to: None,
confidence: 0.9,
end_derived: false,
time_corrected: false,
corrected_ends: None,
closed_by_id: None,
closed_by: None,
closed_by_value: None,
correction_note: None,
};
let p = Path {
nodes: vec![a, x, b],
edges: vec![
edge(a, "OpenAI", x, "Dario Amodei", "employee"),
edge(x, "Dario Amodei", b, "Anthropic", "founder"),
],
specificity: 0.0,
};
assert_eq!(
path_text(&p),
"OpenAI —employee→ Dario Amodei (2021 → now) [90%]; Dario Amodei —founder→ Anthropic (2021 → now) [90%]"
);
let back = Path {
nodes: vec![b, x, a],
edges: vec![
edge(x, "Dario Amodei", b, "Anthropic", "founder"),
edge(a, "OpenAI", x, "Dario Amodei", "employee"),
],
specificity: 0.0,
};
assert_eq!(
path_text(&back),
"Anthropic ←founder— Dario Amodei (2021 → now) [90%]; Dario Amodei ←employee— OpenAI (2021 → now) [90%]"
);
}
#[test]
fn qualifier_strings_are_text_not_json_encodings() {
use utopia_core::models::FactQualifier;
let mut f = fact("out", "works_for", "Acme", None);
assert_eq!(qualifiers_text(&f), "");
for (value, expected) in [
(json!({"value":"等级 \"A\""}), "等级 \"A\""),
(json!({"value":"ends\""}), "ends\""),
(json!({"value":"C:\\reports\\a.txt"}), "C:\\reports\\a.txt"),
(json!({"value":"line one\n第二行"}), "line one\n第二行"),
(json!({"value":"中文“引号”"}), "中文“引号”"),
(json!({"value":10}), "10"),
(json!({"value":true}), "true"),
(json!({"value":false}), "false"),
(json!({"value":10,"unit":"kg"}), "10 kg"),
(json!({"value":null}), "null"),
] {
f.qualifiers = vec![FactQualifier {
qualifier_type_id: Uuid::now_v7(),
key: "detail".into(),
label: "Detail".into(),
value: Some(value),
entity_id: None,
entity_name: None,
}];
assert_eq!(qualifiers_text(&f), format!(" [detail: {expected}]"));
}
f.qualifiers[0].value = None;
f.qualifiers[0].entity_id = f.other_id;
f.qualifiers[0].entity_name = Some("Acme".into());
assert_eq!(qualifiers_text(&f), " [detail: Acme]");
f.qualifiers[0].entity_name = None;
assert_eq!(qualifiers_text(&f), " [detail: ?]");
}
}