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 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)