factoid 0.1.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- factoid/__init__.py +50 -0
- factoid/api.py +162 -0
- factoid/app.py +939 -0
- factoid/cli.py +1092 -0
- factoid/dates.py +55 -0
- factoid/document.py +624 -0
- factoid/entity.py +311 -0
- factoid/evals.py +352 -0
- factoid/exports.py +381 -0
- factoid/fact.py +534 -0
- factoid/fact_evals.py +235 -0
- factoid/judge.py +164 -0
- factoid/mcp_server.py +196 -0
- factoid/models.py +582 -0
- factoid/project.py +93 -0
- factoid/project_id.py +40 -0
- factoid/prompts/extract.md.j2 +53 -0
- factoid/prompts/repair.md.j2 +38 -0
- factoid/prompts/situate.md.j2 +8 -0
- factoid/prompts/struct_parser.md.j2 +45 -0
- factoid/runtime.py +89 -0
- factoid/scaffold.py +198 -0
- factoid/search.py +268 -0
- factoid/serve.py +130 -0
- factoid/settings.py +57 -0
- factoid/steps.py +75 -0
- factoid/store.py +317 -0
- factoid/stores.py +19 -0
- factoid/structured.py +479 -0
- factoid/templates.py +89 -0
- factoid/trait.py +76 -0
- factoid/validity.py +68 -0
- factoid/version.py +69 -0
- factoid-0.1.3.dist-info/METADATA +1030 -0
- factoid-0.1.3.dist-info/RECORD +38 -0
- factoid-0.1.3.dist-info/WHEEL +4 -0
- factoid-0.1.3.dist-info/entry_points.txt +2 -0
- factoid-0.1.3.dist-info/licenses/LICENSE +21 -0
factoid/__init__.py
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Factoid turns documents into facts and entities."""
|
|
2
|
+
|
|
3
|
+
from .app import Factoid, IngestResult, SearchHit
|
|
4
|
+
from .dates import DateError
|
|
5
|
+
from .document import Chunk, Document, Passage, ProseDocument, Raw
|
|
6
|
+
from .entity import Entity
|
|
7
|
+
from .fact import Fact, Mention, Quote
|
|
8
|
+
from .fact_evals import DecisionFloors, EvalResult, FactEval, Nli
|
|
9
|
+
from .judge import Choice, Judgments, Noul, Score, judge
|
|
10
|
+
from .models import Model
|
|
11
|
+
from .settings import Settings
|
|
12
|
+
from .steps import Skip
|
|
13
|
+
from .structured import Identity, Ignore, Property, StructuredDocument, Text
|
|
14
|
+
from .templates import template
|
|
15
|
+
from .trait import FactTrait
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"Choice",
|
|
19
|
+
"Chunk",
|
|
20
|
+
"DateError",
|
|
21
|
+
"DecisionFloors",
|
|
22
|
+
"Document",
|
|
23
|
+
"Entity",
|
|
24
|
+
"EvalResult",
|
|
25
|
+
"Fact",
|
|
26
|
+
"FactEval",
|
|
27
|
+
"FactTrait",
|
|
28
|
+
"Factoid",
|
|
29
|
+
"Identity",
|
|
30
|
+
"Ignore",
|
|
31
|
+
"IngestResult",
|
|
32
|
+
"Judgments",
|
|
33
|
+
"Mention",
|
|
34
|
+
"Model",
|
|
35
|
+
"Nli",
|
|
36
|
+
"Noul",
|
|
37
|
+
"Passage",
|
|
38
|
+
"Property",
|
|
39
|
+
"ProseDocument",
|
|
40
|
+
"Quote",
|
|
41
|
+
"Raw",
|
|
42
|
+
"Score",
|
|
43
|
+
"SearchHit",
|
|
44
|
+
"Settings",
|
|
45
|
+
"Skip",
|
|
46
|
+
"StructuredDocument",
|
|
47
|
+
"Text",
|
|
48
|
+
"judge",
|
|
49
|
+
"template",
|
|
50
|
+
]
|
factoid/api.py
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"""Reads and writes as plain JSON-ready dicts, shared by `factoid serve` (HTTP) and `factoid mcp`.
|
|
2
|
+
|
|
3
|
+
Each function takes the project's app and returns lists and dicts of strings, numbers, and booleans, with dates as
|
|
4
|
+
ISO 8601 strings, so a server can send the result as it is.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import json
|
|
10
|
+
from datetime import date, datetime
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
__all__ = ["NotFound", "entities", "entity", "fact", "facts", "ingest", "search", "stats"]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class NotFound(LookupError):
|
|
17
|
+
"""No fact, entity, or class by that name or id."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def search(app: Any, query: str, *, about: str | None = None, as_of: str | None = None, top_k: int = 10,
|
|
21
|
+
chunks: bool = False) -> list[dict[str, Any]]:
|
|
22
|
+
"""Facts that match `query`, best first. `about` limits them to one entity (a name, key, or id); `as_of` weights
|
|
23
|
+
them by how likely each was still true on that date (a bare date is midnight UTC), and includes superseded facts
|
|
24
|
+
that were true then."""
|
|
25
|
+
entity = _entity(app, about) if about else None
|
|
26
|
+
if as_of and len(as_of) == 10: # a bare date, such as 2026-06-01, means midnight UTC
|
|
27
|
+
as_of += "T00:00:00Z"
|
|
28
|
+
top_k = max(1, min(int(top_k), 100))
|
|
29
|
+
if chunks:
|
|
30
|
+
return [_plain(r) for r in app.search_chunks(query, about=entity, top_k=top_k)]
|
|
31
|
+
hits = app.search_facts(query, about=entity, as_of=as_of, top_k=top_k)
|
|
32
|
+
return [{**_fact(app, h.fact), "score": round(h.score, 6), "validity": round(h.validity, 4),
|
|
33
|
+
"contradicted_by": h.contradiction_ids} for h in hits]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def fact(app: Any, fact_id: str) -> dict[str, Any]:
|
|
37
|
+
"""One fact with its quotes, mentions, relations to other facts, and history."""
|
|
38
|
+
found = app.load_fact(fact_id)
|
|
39
|
+
if found is None:
|
|
40
|
+
raise NotFound(f"no fact {fact_id}")
|
|
41
|
+
out = _fact(app, found)
|
|
42
|
+
out["relations"] = [{"fact_id": r["fact_id"], "relation": r["relation"], "other_id": r["other_id"]}
|
|
43
|
+
for r in app.store.relations(found.id)]
|
|
44
|
+
out["events"] = [{"seq": r["seq"], "at": r["at"], "type": r["type"], "data": json.loads(r["data"] or "{}")}
|
|
45
|
+
for r in app.store.events_for(found.id)]
|
|
46
|
+
return out
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def facts(app: Any, *, document: str | None = None, trait: str | None = None, status: str = "current",
|
|
50
|
+
limit: int = 50) -> list[dict[str, Any]]:
|
|
51
|
+
"""Facts in the order they were added. `document` is a document's id, title, or file name; `status` is one
|
|
52
|
+
status or `all`; `limit` 0 means every fact."""
|
|
53
|
+
sql = ("select f.id, f.class, f.text, f.status, f.traits, f.document_id, d.title, d.uri from facts f "
|
|
54
|
+
"left join documents d on d.id = f.document_id where 1 = 1")
|
|
55
|
+
params: list[Any] = []
|
|
56
|
+
if status != "all":
|
|
57
|
+
sql += " and f.status = ?"
|
|
58
|
+
params.append(status)
|
|
59
|
+
if document:
|
|
60
|
+
sql += " and (d.id = ? or d.title = ? or d.uri = ? or d.uri like ?)"
|
|
61
|
+
params += [document, document, document, f"%/{document}"]
|
|
62
|
+
if trait:
|
|
63
|
+
sql += " and exists (select 1 from json_each(f.traits) t where t.value = ?)"
|
|
64
|
+
params.append(trait)
|
|
65
|
+
sql += " order by f.created_at, f.rowid"
|
|
66
|
+
if limit:
|
|
67
|
+
sql += f" limit {int(limit)}"
|
|
68
|
+
return [{"id": r["id"], "class": r["class"], "text": r["text"], "status": r["status"],
|
|
69
|
+
"traits": json.loads(r["traits"] or "[]"),
|
|
70
|
+
"document": {"id": r["document_id"], "title": r["title"], "uri": r["uri"]}}
|
|
71
|
+
for r in app.store.query(sql, params)]
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def entities(app: Any, *, class_name: str | None = None, name: str | None = None,
|
|
75
|
+
limit: int = 100) -> list[dict[str, Any]]:
|
|
76
|
+
"""Entities with their fact counts, most facts first. `name` matches part of a name or another name."""
|
|
77
|
+
sql = ("select e.id, e.class, e.kind, e.name, e.aliases, count(distinct m.fact_id) facts from entities e "
|
|
78
|
+
"left join mentions m on m.entity_id = e.id where e.merged_into is null")
|
|
79
|
+
params: list[Any] = []
|
|
80
|
+
if class_name:
|
|
81
|
+
sql += " and e.class = ?"
|
|
82
|
+
params.append(class_name)
|
|
83
|
+
if name:
|
|
84
|
+
sql += " and (lower(e.name) like ? or lower(e.aliases) like ?)"
|
|
85
|
+
params += [f"%{name.lower()}%"] * 2
|
|
86
|
+
sql += " group by e.id order by facts desc, e.name"
|
|
87
|
+
if limit:
|
|
88
|
+
sql += f" limit {int(limit)}"
|
|
89
|
+
return [{"id": r["id"], "class": r["class"], "kind": r["kind"], "name": r["name"],
|
|
90
|
+
"aliases": json.loads(r["aliases"] or "[]"), "facts": r["facts"]} for r in app.store.query(sql, params)]
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def entity(app: Any, name_or_id: str, *, limit: int = 50) -> dict[str, Any]:
|
|
94
|
+
"""One entity (by id, key, name, or other name), its current facts, newest first, and the entities it appears
|
|
95
|
+
with most."""
|
|
96
|
+
found = _entity(app, name_or_id)
|
|
97
|
+
out: dict[str, Any] = {"id": found.id, "class": type(found).__qualname__, "kind": found.kind,
|
|
98
|
+
"name": found.name, "aliases": list(found.aliases)}
|
|
99
|
+
out["facts"] = [_fact(app, f) for f in app.entity_facts(found)[:limit]]
|
|
100
|
+
out["related"] = [{"id": r["entity"].id, "name": r["entity"].name, "co_mentions": r["co_mentions"],
|
|
101
|
+
"weight": r["weight"]} for r in app.related_entities(found)[:20]]
|
|
102
|
+
return out
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def stats(app: Any) -> dict[str, Any]:
|
|
106
|
+
"""Counts of documents, facts, and entities by class and status."""
|
|
107
|
+
return _plain(app.stats())
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def ingest(app: Any, text: str, *, document_type: str | None = None, uri: str | None = None,
|
|
111
|
+
title: str | None = None, metadata: dict[str, Any] | None = None) -> dict[str, Any]:
|
|
112
|
+
"""Ingest one document's text and return the facts kept and rejected. `document_type` names a document class in
|
|
113
|
+
the project; without it, the project's classifiers pick one."""
|
|
114
|
+
klass = None
|
|
115
|
+
if document_type:
|
|
116
|
+
klass = next((k for k in app.document_classes if k.__qualname__ == document_type), None)
|
|
117
|
+
if klass is None:
|
|
118
|
+
names = ", ".join(k.__qualname__ for k in app.document_classes) or "none"
|
|
119
|
+
raise NotFound(f"no document class {document_type}; the project has: {names}")
|
|
120
|
+
result = app.ingest_text(text, document_type=klass, metadata=metadata, uri=uri, title=title)
|
|
121
|
+
return {"document": {"id": result.document.id, "class": type(result.document).__qualname__,
|
|
122
|
+
"uri": result.document.uri, "title": result.document.title},
|
|
123
|
+
"unchanged": result.unchanged, "facts": [_fact(app, f) for f in result.facts],
|
|
124
|
+
"rejected": [{"text": r.text, "reasons": list(r.reasons)} for r in result.rejected],
|
|
125
|
+
"duplicates": result.duplicates}
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
# -- shapes -------------------------------------------------------------------------------------------------
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def _entity(app: Any, name_or_id: str) -> Any:
|
|
132
|
+
from .entity import Entity
|
|
133
|
+
|
|
134
|
+
found = app.load_entity(name_or_id) or Entity.find(name_or_id)
|
|
135
|
+
if found is None:
|
|
136
|
+
raise NotFound(f"no entity named {name_or_id!r}")
|
|
137
|
+
return found
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def _fact(app: Any, f: Any) -> dict[str, Any]:
|
|
141
|
+
return {
|
|
142
|
+
"id": f.id, "class": type(f).__qualname__, "text": f.text, "status": f.status, "traits": f.trait_names,
|
|
143
|
+
"valid_from": _iso(f.valid_from), "valid_until": _iso(f.valid_until), "expires": f.expires,
|
|
144
|
+
"still_valid": round(f.valid_at(), 4),
|
|
145
|
+
"document": {"id": f.document_id, "title": app.document_title(f.document_id)},
|
|
146
|
+
"quotes": [{"document_id": q.document_id, "passage": q.passage_n, "section": q.section, "text": q.text,
|
|
147
|
+
"speaker": q.speaker, "said_at": q.said_at} for q in f.quotes],
|
|
148
|
+
"mentions": [{"text": m.text, "role": m.role, "entity_id": m.entity_id} for m in f.mentions],
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _iso(value: Any) -> Any:
|
|
153
|
+
return value.isoformat() if isinstance(value, (datetime, date)) else value
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _plain(value: Any) -> Any:
|
|
157
|
+
"""Dates to ISO strings, recursively, so `json.dumps` takes the result."""
|
|
158
|
+
if isinstance(value, dict):
|
|
159
|
+
return {str(k): _plain(v) for k, v in value.items()}
|
|
160
|
+
if isinstance(value, (list, tuple, set)):
|
|
161
|
+
return [_plain(v) for v in value]
|
|
162
|
+
return _iso(value)
|