dakc 0.2.1__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.
dakc/__init__.py ADDED
@@ -0,0 +1,77 @@
1
+ """DAKC: Dependency-Aware Knowledge Compiler.
2
+
3
+ .. code-block:: python
4
+
5
+ import dakc
6
+
7
+ with dakc.open("path/to/workspace") as kb:
8
+ report = kb.compile()
9
+
10
+ See :mod:`dakc.kb` for the full API.
11
+ """
12
+
13
+ __version__ = "0.2.1"
14
+
15
+ from dakc.compiler import BuildReport # noqa: E402
16
+ from dakc.errors import ( # noqa: E402
17
+ ArtifactNotFound,
18
+ BuildLocked,
19
+ CompileFailed,
20
+ ConcurrentBuildError,
21
+ CostNotAllowed,
22
+ DakcError,
23
+ InvalidArgument,
24
+ RollbackError,
25
+ WorkspaceNotFound,
26
+ )
27
+ from dakc.kb import ( # noqa: E402
28
+ ArtifactContent,
29
+ ArtifactSummary,
30
+ BuildDiff,
31
+ Downstream,
32
+ DuplicatePair,
33
+ KnowledgeBase,
34
+ RollbackResult,
35
+ SourceChanges,
36
+ Status,
37
+ VerifyReport,
38
+ ingest,
39
+ init,
40
+ )
41
+ from dakc.kb import open_kb as open # noqa: E402,A001 (dakc.open, like tarfile.open)
42
+ from dakc.provenance import Explanation # noqa: E402
43
+ from dakc.provenance.trace import ClaimTrace, PageTrace # noqa: E402
44
+ from dakc.storage import BuildRecord # noqa: E402
45
+
46
+ __all__ = [
47
+ "__version__",
48
+ "open",
49
+ "init",
50
+ "ingest",
51
+ "KnowledgeBase",
52
+ # results
53
+ "BuildReport",
54
+ "BuildRecord",
55
+ "BuildDiff",
56
+ "ArtifactContent",
57
+ "ArtifactSummary",
58
+ "Downstream",
59
+ "DuplicatePair",
60
+ "Explanation",
61
+ "ClaimTrace",
62
+ "PageTrace",
63
+ "RollbackResult",
64
+ "SourceChanges",
65
+ "Status",
66
+ "VerifyReport",
67
+ # errors
68
+ "DakcError",
69
+ "ArtifactNotFound",
70
+ "BuildLocked",
71
+ "CompileFailed",
72
+ "ConcurrentBuildError",
73
+ "CostNotAllowed",
74
+ "InvalidArgument",
75
+ "RollbackError",
76
+ "WorkspaceNotFound",
77
+ ]
dakc/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from dakc.cli import main
2
+
3
+ main()
dakc/api/__init__.py ADDED
@@ -0,0 +1,109 @@
1
+ """Read-only REST API over a workspace (``dakc serve``).
2
+
3
+ A thin layer over :class:`dakc.kb.KnowledgeBase`: status, check, plan (dry
4
+ run), artifacts, explain, trace, downstream, graph (React Flow format for a
5
+ frontend), builds and diff. Nothing here mutates the knowledge base; compiling
6
+ stays an explicit CLI, Python or MCP action. Each request opens its own
7
+ connection and closes it when the response is sent.
8
+ """
9
+
10
+ # No `from __future__ import annotations`: FastAPI must evaluate the local
11
+ # `KB` dependency annotation at definition time.
12
+ import json
13
+ from collections.abc import Iterator
14
+ from pathlib import Path
15
+ from typing import Annotated
16
+
17
+ from fastapi import Depends, FastAPI, HTTPException, Query, Request
18
+ from fastapi.responses import JSONResponse, PlainTextResponse
19
+
20
+ from dakc import __version__
21
+ from dakc.errors import ArtifactNotFound, InvalidArgument, WorkspaceNotFound
22
+ from dakc.kb import KnowledgeBase
23
+ from dakc.workspace import Workspace
24
+
25
+ GRAPH_EXPORT_LIMIT = 20_000 # edges; larger graphs are only exported around one node
26
+
27
+
28
+ def create_app(root: Path) -> FastAPI:
29
+ try:
30
+ ws = Workspace.load(root)
31
+ except FileNotFoundError as exc:
32
+ raise WorkspaceNotFound(str(exc)) from exc
33
+ app = FastAPI(title="DAKC", version=__version__, description="Dependency-Aware Knowledge Compiler (read-only API)")
34
+
35
+ def open_kb() -> Iterator[KnowledgeBase]:
36
+ kb = KnowledgeBase(ws)
37
+ try:
38
+ yield kb
39
+ finally:
40
+ kb.close()
41
+
42
+ KB = Annotated[KnowledgeBase, Depends(open_kb)]
43
+
44
+ @app.exception_handler(ArtifactNotFound)
45
+ def _not_found(_: Request, exc: ArtifactNotFound) -> JSONResponse:
46
+ return JSONResponse({"detail": str(exc)}, status_code=404)
47
+
48
+ @app.exception_handler(InvalidArgument)
49
+ def _bad_request(_: Request, exc: InvalidArgument) -> JSONResponse:
50
+ return JSONResponse({"detail": str(exc)}, status_code=400)
51
+
52
+ @app.get("/status")
53
+ def status(kb: KB):
54
+ return kb.status().to_dict()
55
+
56
+ @app.get("/check")
57
+ def check(kb: KB):
58
+ return kb.check().to_dict()
59
+
60
+ @app.get("/plan")
61
+ def plan(kb: KB, full: bool = False):
62
+ """Dry-run compilation plan. Free providers give an exact plan; LLM providers an upper bound."""
63
+ return kb.plan(full=full).to_dict(limit=500)
64
+
65
+ @app.get("/graph")
66
+ def graph(kb: KB, source: str | None = None, format: str = Query("reactflow", pattern="^(json|reactflow)$")):
67
+ if source is None and kb.store.counts().get("edges", 0) > GRAPH_EXPORT_LIMIT:
68
+ return {"stats": kb.graph_stats(), "note": "graph too large to export whole; pass ?source="}
69
+ return json.loads(kb.export_graph(format, around=source))
70
+
71
+ @app.get("/artifacts")
72
+ def artifacts(kb: KB, kind: str | None = None, query: str | None = None, limit: int = Query(100, ge=1, le=1000)):
73
+ return [a.to_dict() for a in kb.artifacts(kind, query=query, limit=limit)]
74
+
75
+ # The more specific routes must be registered before /artifacts/{id}.
76
+ @app.get("/artifacts/{artifact_id:path}/content", response_class=PlainTextResponse)
77
+ def artifact_content(artifact_id: str, kb: KB):
78
+ return kb.read(artifact_id).text
79
+
80
+ @app.get("/artifacts/{artifact_id:path}/trace")
81
+ def artifact_trace(artifact_id: str, kb: KB):
82
+ return kb.trace(artifact_id).to_dict()
83
+
84
+ @app.get("/artifacts/{artifact_id:path}/downstream")
85
+ def artifact_downstream(artifact_id: str, kb: KB, limit: int = Query(200, ge=1)):
86
+ return kb.downstream(artifact_id).to_dict(limit=limit)
87
+
88
+ @app.get("/artifacts/{artifact_id:path}")
89
+ def artifact(artifact_id: str, kb: KB):
90
+ return kb.explain(artifact_id).to_dict()
91
+
92
+ @app.get("/builds")
93
+ def builds(kb: KB, limit: int = 50):
94
+ return [b.to_dict() for b in kb.builds(limit)]
95
+
96
+ @app.get("/diff/{a}/{b}")
97
+ def diff(a: int, b: int, kb: KB):
98
+ return kb.diff(a, b).changes
99
+
100
+ @app.get("/duplicates")
101
+ def duplicates(kb: KB, limit: int = Query(100, ge=1)):
102
+ return [p.to_dict() for p in kb.duplicates(limit)]
103
+
104
+ @app.get("/health")
105
+ def health():
106
+ return {"ok": True, "version": __version__}
107
+
108
+ _ = HTTPException # re-exported for callers that extend the app
109
+ return app
@@ -0,0 +1,313 @@
1
+ """Artifact records.
2
+
3
+ Every derived artifact is an immutable record with:
4
+
5
+ * ``content_hash``: hash of its *knowledge content* (what a reader sees);
6
+ * ``state_hash``: hash of its full payload, including provenance. A new
7
+ version row is written iff this changes;
8
+ * ``deps()``: the ids it depends on, with an edge kind. Edges are derived from
9
+ content, never maintained by hand, so they cannot drift from it.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ from dataclasses import dataclass, field
15
+ from functools import cached_property
16
+ from typing import Any, ClassVar
17
+
18
+ from dakc.hashing import h_obj
19
+
20
+ LAYER: dict[str, int] = {
21
+ "source": 0,
22
+ "passage": 1,
23
+ "claim": 2,
24
+ "entity": 3,
25
+ "relationship": 3,
26
+ "page": 4,
27
+ "summary": 5,
28
+ "index": 6,
29
+ }
30
+ KINDS = tuple(LAYER)
31
+ INDEX_ID = "index:main"
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class Artifact:
36
+ id: str
37
+ kind: ClassVar[str] = ""
38
+
39
+ def content(self) -> dict[str, Any]: # pragma: no cover - overridden
40
+ raise NotImplementedError
41
+
42
+ def payload(self) -> dict[str, Any]: # pragma: no cover - overridden
43
+ raise NotImplementedError
44
+
45
+ def deps(self) -> list[tuple[str, str]]: # (dependency id, edge kind)
46
+ return []
47
+
48
+ @cached_property
49
+ def content_hash(self) -> str:
50
+ return h_obj(self.content())
51
+
52
+ @cached_property
53
+ def state_hash(self) -> str:
54
+ return h_obj(self.payload())
55
+
56
+ @property
57
+ def title(self) -> str:
58
+ return self.id
59
+
60
+
61
+ @dataclass(frozen=True)
62
+ class PassageArt(Artifact):
63
+ source_id: str = ""
64
+ text: str = ""
65
+ text_hash: str = ""
66
+ heading: str = ""
67
+ occurrence: int = 0
68
+ extracted_by: str = "" # fingerprint of the extractor whose claims this passage supports
69
+ kind: ClassVar[str] = "passage"
70
+
71
+ def content(self):
72
+ return {"text": self.text}
73
+
74
+ def payload(self):
75
+ return {"source_id": self.source_id, "text": self.text, "text_hash": self.text_hash, "heading": self.heading, "occurrence": self.occurrence, "extracted_by": self.extracted_by}
76
+
77
+ def deps(self):
78
+ return [(self.source_id, "from_source")]
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class ClaimArt(Artifact):
83
+ # (passage id, surface text, mentions, evidence sentence indices in that passage), sorted by passage id
84
+ supports: tuple[tuple[str, str, tuple[str, ...], tuple[int, ...]], ...] = ()
85
+ kind: ClassVar[str] = "claim"
86
+
87
+ @cached_property
88
+ def text(self) -> str:
89
+ return min(s[1] for s in self.supports) if self.supports else ""
90
+
91
+ @cached_property
92
+ def mentions(self) -> tuple[str, ...]:
93
+ return tuple(sorted({m for s in self.supports for m in s[2]}))
94
+
95
+ @property
96
+ def passage_ids(self) -> tuple[str, ...]:
97
+ return tuple(s[0] for s in self.supports)
98
+
99
+ def content(self):
100
+ return {"text": self.text, "mentions": list(self.mentions)}
101
+
102
+ def payload(self):
103
+ return {"supports": [[p, t, list(m), list(e)] for p, t, m, e in self.supports]}
104
+
105
+ def deps(self):
106
+ return [(p, "supported_by") for p in self.passage_ids]
107
+
108
+ @property
109
+ def title(self) -> str:
110
+ return self.text
111
+
112
+
113
+ @dataclass(frozen=True)
114
+ class EntityArt(Artifact):
115
+ name: str = ""
116
+ claim_ids: tuple[str, ...] = ()
117
+ kind: ClassVar[str] = "entity"
118
+
119
+ def content(self):
120
+ return {"name": self.name, "claim_ids": list(self.claim_ids)}
121
+
122
+ payload = content
123
+
124
+ def deps(self):
125
+ return [(c, "mentioned_in") for c in self.claim_ids]
126
+
127
+ @property
128
+ def title(self) -> str:
129
+ return self.name
130
+
131
+
132
+ @dataclass(frozen=True)
133
+ class RelationshipArt(Artifact):
134
+ a: str = ""
135
+ b: str = ""
136
+ claim_ids: tuple[str, ...] = ()
137
+ kind: ClassVar[str] = "relationship"
138
+
139
+ def content(self):
140
+ return {"a": self.a, "b": self.b, "claim_ids": list(self.claim_ids)}
141
+
142
+ payload = content
143
+
144
+ def deps(self):
145
+ return [(c, "evidenced_by") for c in self.claim_ids]
146
+
147
+
148
+ @dataclass(frozen=True)
149
+ class PageArt(Artifact):
150
+ entity_id: str = ""
151
+ title_: str = ""
152
+ body: str = ""
153
+ lead: str = ""
154
+ rendered: str = ""
155
+ claim_ids: tuple[str, ...] = ()
156
+ rel_ids: tuple[str, ...] = ()
157
+ topic: str = ""
158
+ gen_sig: str = ""
159
+ render_sig: str = ""
160
+ generator: str = ""
161
+ dropped: tuple[str, ...] = () # generated sentences removed by strict provenance (audit trail)
162
+ kind: ClassVar[str] = "page"
163
+
164
+ def content(self):
165
+ return {"rendered": self.rendered}
166
+
167
+ def payload(self):
168
+ return {
169
+ "entity_id": self.entity_id,
170
+ "title": self.title_,
171
+ "body": self.body,
172
+ "lead": self.lead,
173
+ "rendered": self.rendered,
174
+ "claim_ids": list(self.claim_ids),
175
+ "rel_ids": list(self.rel_ids),
176
+ "topic": self.topic,
177
+ "gen_sig": self.gen_sig,
178
+ "render_sig": self.render_sig,
179
+ "generator": self.generator,
180
+ "dropped": list(self.dropped),
181
+ }
182
+
183
+ def deps(self):
184
+ return [(self.entity_id, "describes")] + [(r, "related_via") for r in self.rel_ids]
185
+
186
+ @property
187
+ def title(self) -> str:
188
+ return self.title_
189
+
190
+
191
+ @dataclass(frozen=True)
192
+ class SummaryArt(Artifact):
193
+ topic: str = ""
194
+ title_: str = ""
195
+ rendered: str = ""
196
+ page_ids: tuple[str, ...] = ()
197
+ sig: str = ""
198
+ generator: str = ""
199
+ body: str = ""
200
+ render_sig: str = ""
201
+ kind: ClassVar[str] = "summary"
202
+
203
+ def content(self):
204
+ return {"rendered": self.rendered}
205
+
206
+ def payload(self):
207
+ return {
208
+ "topic": self.topic,
209
+ "title": self.title_,
210
+ "rendered": self.rendered,
211
+ "page_ids": list(self.page_ids),
212
+ "sig": self.sig,
213
+ "generator": self.generator,
214
+ "body": self.body,
215
+ "render_sig": self.render_sig,
216
+ }
217
+
218
+ def deps(self):
219
+ return [(p, "summarizes") for p in self.page_ids]
220
+
221
+ @property
222
+ def title(self) -> str:
223
+ return self.title_
224
+
225
+
226
+ @dataclass(frozen=True)
227
+ class IndexArt(Artifact):
228
+ rendered: str = ""
229
+ page_ids: tuple[str, ...] = ()
230
+ summary_ids: tuple[str, ...] = ()
231
+ sig: str = ""
232
+ kind: ClassVar[str] = "index"
233
+
234
+ def content(self):
235
+ return {"rendered": self.rendered}
236
+
237
+ def payload(self):
238
+ return {"rendered": self.rendered, "page_ids": list(self.page_ids), "summary_ids": list(self.summary_ids), "sig": self.sig}
239
+
240
+ def deps(self):
241
+ return [(p, "lists") for p in self.page_ids] + [(s, "lists") for s in self.summary_ids]
242
+
243
+ @property
244
+ def title(self) -> str:
245
+ return "Index"
246
+
247
+
248
+ def from_payload(kind: str, id_: str, p: dict[str, Any]) -> Artifact:
249
+ if kind == "passage":
250
+ return PassageArt(id_, p["source_id"], p["text"], p["text_hash"], p.get("heading", ""), p.get("occurrence", 0), p.get("extracted_by", ""))
251
+ if kind == "claim":
252
+ return ClaimArt(id_, tuple((s[0], s[1], tuple(s[2]), tuple(s[3]) if len(s) > 3 else ()) for s in p["supports"]))
253
+ if kind == "entity":
254
+ return EntityArt(id_, p["name"], tuple(p["claim_ids"]))
255
+ if kind == "relationship":
256
+ return RelationshipArt(id_, p["a"], p["b"], tuple(p["claim_ids"]))
257
+ if kind == "page":
258
+ return PageArt(
259
+ id_, p["entity_id"], p["title"], p["body"], p["lead"], p["rendered"], tuple(p["claim_ids"]),
260
+ tuple(p["rel_ids"]), p["topic"], p["gen_sig"], p["render_sig"], p.get("generator", ""), tuple(p.get("dropped", ())),
261
+ )
262
+ if kind == "summary":
263
+ return SummaryArt(id_, p["topic"], p["title"], p["rendered"], tuple(p["page_ids"]), p["sig"], p.get("generator", ""),
264
+ p.get("body", ""), p.get("render_sig", ""))
265
+ if kind == "index":
266
+ return IndexArt(id_, p["rendered"], tuple(p["page_ids"]), tuple(p["summary_ids"]), p["sig"])
267
+ raise KeyError(kind)
268
+
269
+
270
+ def kind_of(artifact_id: str) -> str:
271
+ prefix = artifact_id.split(":", 1)[0]
272
+ return {
273
+ "src": "source",
274
+ "psg": "passage",
275
+ "clm": "claim",
276
+ "ent": "entity",
277
+ "rel": "relationship",
278
+ "page": "page",
279
+ "sum": "summary",
280
+ "index": "index",
281
+ }.get(prefix, "unknown")
282
+
283
+
284
+ @dataclass
285
+ class Usage:
286
+ """Provider usage counters for one build."""
287
+
288
+ calls: int = 0
289
+ llm_calls: int = 0
290
+ input_tokens: int = 0
291
+ output_tokens: int = 0
292
+ cache_hits: int = 0
293
+ by_stage: dict[str, int] = field(default_factory=dict)
294
+
295
+ def add(self, stage: str, *, llm: bool, input_tokens: int = 0, output_tokens: int = 0, calls: int = 1) -> None:
296
+ self.calls += calls
297
+ if llm:
298
+ self.llm_calls += calls
299
+ self.input_tokens += input_tokens
300
+ self.output_tokens += output_tokens
301
+ self.by_stage[stage] = self.by_stage.get(stage, 0) + 1
302
+ if calls > 1:
303
+ self.by_stage[f"{stage}_retry"] = self.by_stage.get(f"{stage}_retry", 0) + calls - 1
304
+
305
+ def as_dict(self) -> dict[str, Any]:
306
+ return {
307
+ "provider_calls": self.calls,
308
+ "llm_calls": self.llm_calls,
309
+ "input_tokens": self.input_tokens,
310
+ "output_tokens": self.output_tokens,
311
+ "extraction_cache_hits": self.cache_hits,
312
+ "calls_by_stage": dict(sorted(self.by_stage.items())),
313
+ }