crewforge 0.1.0__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.
- crewforge/__init__.py +3 -0
- crewforge/__main__.py +4 -0
- crewforge/cli.py +128 -0
- crewforge/cli_support.py +109 -0
- crewforge/core/__init__.py +54 -0
- crewforge/core/agent.py +118 -0
- crewforge/core/client.py +253 -0
- crewforge/core/config.py +181 -0
- crewforge/core/crew.py +144 -0
- crewforge/core/errors.py +106 -0
- crewforge/core/parsing.py +110 -0
- crewforge/core/providers.py +131 -0
- crewforge/core/usage.py +163 -0
- crewforge/py.typed +0 -0
- crewforge/recipes/__init__.py +1 -0
- crewforge/recipes/api/__init__.py +38 -0
- crewforge/recipes/api/agents.py +523 -0
- crewforge/recipes/api/analytics.py +99 -0
- crewforge/recipes/api/appcheck.py +73 -0
- crewforge/recipes/api/cli.py +127 -0
- crewforge/recipes/api/formatters.py +32 -0
- crewforge/recipes/api/generator.py +37 -0
- crewforge/recipes/api/pipeline.py +86 -0
- crewforge/recipes/api/scaffold.py +68 -0
- crewforge/recipes/api/templates/docker-compose.j2 +9 -0
- crewforge/recipes/api/templates/dockerfile.j2 +7 -0
- crewforge/recipes/api/templates/env.example.j2 +2 -0
- crewforge/recipes/api/templates/fastapi_main.j2 +10 -0
- crewforge/recipes/api/templates/model.j2 +4 -0
- crewforge/recipes/api/templates/requirements.j2 +6 -0
- crewforge/recipes/api/templates/route.j2 +4 -0
- crewforge/recipes/api/templates/test.j2 +3 -0
- crewforge/recipes/api/utils.py +134 -0
- crewforge/recipes/content/__init__.py +20 -0
- crewforge/recipes/content/agents.py +735 -0
- crewforge/recipes/content/cli.py +128 -0
- crewforge/recipes/content/export.py +84 -0
- crewforge/recipes/content/pipeline.py +222 -0
- crewforge/recipes/content/settings.py +63 -0
- crewforge/recipes/content/text.py +57 -0
- crewforge/recipes/docs/__init__.py +48 -0
- crewforge/recipes/docs/agents.py +426 -0
- crewforge/recipes/docs/cli.py +156 -0
- crewforge/recipes/docs/export.py +118 -0
- crewforge/recipes/docs/index.py +117 -0
- crewforge/recipes/docs/ingest.py +212 -0
- crewforge/recipes/docs/pipeline.py +223 -0
- crewforge/recipes/docs/retrieve.py +70 -0
- crewforge/recipes/docs/settings.py +54 -0
- crewforge/recipes/review/__init__.py +1 -0
- crewforge/recipes/review/agents.py +331 -0
- crewforge/recipes/review/cli.py +144 -0
- crewforge/recipes/review/pipeline.py +125 -0
- crewforge/recipes/review/report.py +103 -0
- crewforge/recipes/review/sources.py +89 -0
- crewforge-0.1.0.dist-info/METADATA +372 -0
- crewforge-0.1.0.dist-info/RECORD +61 -0
- crewforge-0.1.0.dist-info/WHEEL +5 -0
- crewforge-0.1.0.dist-info/entry_points.txt +2 -0
- crewforge-0.1.0.dist-info/licenses/LICENSE +21 -0
- crewforge-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,426 @@
|
|
|
1
|
+
"""LLM agents of the ``docs`` recipe: answer, fact-check, summarize, rerank, cite."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
from typing import TYPE_CHECKING, Any
|
|
8
|
+
|
|
9
|
+
from ...core.agent import Agent
|
|
10
|
+
from ...core.errors import OutputParseError
|
|
11
|
+
from ...core.parsing import extract_json
|
|
12
|
+
|
|
13
|
+
if TYPE_CHECKING:
|
|
14
|
+
from .ingest import Document
|
|
15
|
+
from .retrieve import RetrievalResult
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def _excerpt(text: str, limit: int = 120) -> str:
|
|
19
|
+
flat = " ".join(text.split())
|
|
20
|
+
return flat if len(flat) <= limit else flat[: limit - 1] + "…"
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
# --------------------------------------------------------------------------- answer
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass
|
|
27
|
+
class Answer:
|
|
28
|
+
"""An answer with the sources it actually cited."""
|
|
29
|
+
|
|
30
|
+
question: str
|
|
31
|
+
answer_text: str
|
|
32
|
+
citations: list[dict[str, str]]
|
|
33
|
+
confidence: str = "medium"
|
|
34
|
+
reasoning: str = ""
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class AnswerAgent(Agent):
|
|
38
|
+
"""Answer strictly from retrieved passages, citing them as ``[Source N]``."""
|
|
39
|
+
|
|
40
|
+
name = "answerer"
|
|
41
|
+
description = "Answers from retrieved passages with [Source N] citations"
|
|
42
|
+
system_prompt = (
|
|
43
|
+
"You are the answer agent of a document Q&A crew. You answer questions STRICTLY "
|
|
44
|
+
"based on the provided document excerpts. If the answer is not in the provided "
|
|
45
|
+
"context, say so clearly. Always cite your sources using [Source N] notation. "
|
|
46
|
+
"Be precise, factual, and concise."
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
LEVELS = {
|
|
50
|
+
"brief": "Give a brief 1-2 sentence answer.",
|
|
51
|
+
"normal": "Give a clear, complete answer in a paragraph.",
|
|
52
|
+
"detailed": "Give a detailed answer with explanation and context.",
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
def _build_context(self, chunks: list[RetrievalResult]) -> str:
|
|
56
|
+
return "\n\n---\n\n".join(
|
|
57
|
+
f"[Source {i + 1}] (doc: {c.document_id}, chunk: {c.chunk_id})\n{c.text}"
|
|
58
|
+
for i, c in enumerate(chunks)
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
async def answer(
|
|
62
|
+
self, question: str, chunks: list[RetrievalResult], *, detail_level: str = "normal"
|
|
63
|
+
) -> Answer:
|
|
64
|
+
level = self.LEVELS.get(detail_level, "Give a clear, complete answer.")
|
|
65
|
+
prompt = (
|
|
66
|
+
"Based on the following document excerpts, answer this question:\n\n"
|
|
67
|
+
f"Question: {question}\n\n"
|
|
68
|
+
f"Document excerpts:\n{self._build_context(chunks)}\n\n"
|
|
69
|
+
f"Instructions: {level}\n"
|
|
70
|
+
"Include [Source N] citations in your answer. "
|
|
71
|
+
"End with a line 'Confidence: high|medium|low'."
|
|
72
|
+
)
|
|
73
|
+
response = await self.ask(prompt)
|
|
74
|
+
content = response.content
|
|
75
|
+
|
|
76
|
+
citations = [
|
|
77
|
+
{
|
|
78
|
+
"source_num": str(i + 1),
|
|
79
|
+
"chunk_id": c.chunk_id,
|
|
80
|
+
"document_id": c.document_id,
|
|
81
|
+
"excerpt": c.text[:200],
|
|
82
|
+
}
|
|
83
|
+
for i, c in enumerate(chunks)
|
|
84
|
+
if f"[Source {i + 1}]" in content
|
|
85
|
+
]
|
|
86
|
+
confidence = "medium"
|
|
87
|
+
match = re.search(
|
|
88
|
+
r"confidence(?:\s+level)?\s*[:=]\s*\**\s*(high|medium|low)", content, re.I
|
|
89
|
+
)
|
|
90
|
+
if match:
|
|
91
|
+
confidence = match.group(1).lower()
|
|
92
|
+
return Answer(
|
|
93
|
+
question=question,
|
|
94
|
+
answer_text=content,
|
|
95
|
+
citations=citations,
|
|
96
|
+
confidence=confidence,
|
|
97
|
+
reasoning=response.reasoning,
|
|
98
|
+
)
|
|
99
|
+
|
|
100
|
+
async def run(self, **kwargs: Any) -> Answer:
|
|
101
|
+
return await self.answer(
|
|
102
|
+
kwargs["question"], kwargs["chunks"], detail_level=kwargs.get("detail_level", "normal")
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
# ----------------------------------------------------------------------- fact-check
|
|
107
|
+
|
|
108
|
+
VERDICTS = ("verified", "partially_verified", "unverified", "contradicted")
|
|
109
|
+
_CLAIM_TOKEN = re.compile(r"\b(VERIFIED|UNVERIFIED|CONTRADICTED)\b", re.I)
|
|
110
|
+
_OVERALL = re.compile(r"OVERALL\s*[:=]\s*[\*\[\s]*([A-Za-z_ -]+)", re.I)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _normalize_verdict(value: Any) -> str | None:
|
|
114
|
+
if not isinstance(value, str):
|
|
115
|
+
return None
|
|
116
|
+
v = re.sub(r"[\s-]+", "_", value.strip().strip("[]*.").lower())
|
|
117
|
+
return v if v in VERDICTS else None
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _derive_overall(verdicts: list[str]) -> str:
|
|
121
|
+
verified = verdicts.count("verified")
|
|
122
|
+
if "contradicted" in verdicts:
|
|
123
|
+
return "partially_verified" if verified else "contradicted"
|
|
124
|
+
if "unverified" in verdicts:
|
|
125
|
+
return "partially_verified" if verified else "unverified"
|
|
126
|
+
return "verified"
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
@dataclass
|
|
130
|
+
class FactCheckResult:
|
|
131
|
+
"""Result of checking an answer's claims against its sources."""
|
|
132
|
+
|
|
133
|
+
overall_verdict: str # verified | partially_verified | unverified | contradicted
|
|
134
|
+
claims_checked: int
|
|
135
|
+
claims_verified: int
|
|
136
|
+
claims_contradicted: int
|
|
137
|
+
issues: list[str]
|
|
138
|
+
details: str
|
|
139
|
+
claims: list[dict[str, Any]] = field(default_factory=list)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class FactCheckAgent(Agent):
|
|
143
|
+
"""Verify each claim of an answer against the source passages."""
|
|
144
|
+
|
|
145
|
+
name = "fact_checker"
|
|
146
|
+
description = "Checks each claim of an answer against the cited passages"
|
|
147
|
+
temperature = 0.0
|
|
148
|
+
system_prompt = (
|
|
149
|
+
"You are the fact-checking agent of a document Q&A crew. Compare the claims in an "
|
|
150
|
+
"answer against source documents. For each claim decide: VERIFIED (supported by a "
|
|
151
|
+
"source), UNVERIFIED (not found in the sources) or CONTRADICTED (conflicts with a "
|
|
152
|
+
"source). Be strict and precise. Reply with ONE JSON object and nothing else:\n"
|
|
153
|
+
'{"claims": [{"claim": "...", "verdict": "verified|unverified|contradicted", '
|
|
154
|
+
'"source": "Source N"}], "overall": "verified|partially_verified|unverified|contradicted"}'
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
def parse(self, content: str) -> FactCheckResult:
|
|
158
|
+
"""JSON verdict first; else documind's ``OVERALL: <verdict>`` text format."""
|
|
159
|
+
data = extract_json(content)
|
|
160
|
+
if isinstance(data, dict) and ("claims" in data or "overall" in data):
|
|
161
|
+
raw_claims = data.get("claims") or []
|
|
162
|
+
if not isinstance(raw_claims, list):
|
|
163
|
+
raise OutputParseError(self.name, "'claims' is not a list", _excerpt(content))
|
|
164
|
+
claims: list[dict[str, Any]] = []
|
|
165
|
+
for item in raw_claims:
|
|
166
|
+
verdict = (
|
|
167
|
+
_normalize_verdict(item.get("verdict")) if isinstance(item, dict) else None
|
|
168
|
+
)
|
|
169
|
+
if verdict is None or verdict == "partially_verified":
|
|
170
|
+
raise OutputParseError(
|
|
171
|
+
self.name, f"claim without a valid verdict: {item!r}", _excerpt(content)
|
|
172
|
+
)
|
|
173
|
+
claims.append({**item, "verdict": verdict})
|
|
174
|
+
verdicts = [c["verdict"] for c in claims]
|
|
175
|
+
overall = data.get("overall")
|
|
176
|
+
if overall is None:
|
|
177
|
+
if not verdicts:
|
|
178
|
+
raise OutputParseError(self.name, "no claims and no overall verdict")
|
|
179
|
+
overall_verdict = _derive_overall(verdicts)
|
|
180
|
+
else:
|
|
181
|
+
overall_verdict = _normalize_verdict(overall)
|
|
182
|
+
if overall_verdict is None:
|
|
183
|
+
raise OutputParseError(self.name, f"unknown overall verdict {overall!r}")
|
|
184
|
+
issues = [
|
|
185
|
+
f"{c['verdict'].upper()}: {c.get('claim', '')}".strip()
|
|
186
|
+
for c in claims
|
|
187
|
+
if c["verdict"] != "verified"
|
|
188
|
+
]
|
|
189
|
+
else:
|
|
190
|
+
match = _OVERALL.search(content)
|
|
191
|
+
overall_verdict = _normalize_verdict(match.group(1)) if match else None
|
|
192
|
+
if overall_verdict is None:
|
|
193
|
+
raise OutputParseError(
|
|
194
|
+
self.name,
|
|
195
|
+
"no JSON verdict and no 'OVERALL: <verdict>' line",
|
|
196
|
+
_excerpt(content),
|
|
197
|
+
)
|
|
198
|
+
verdicts, issues = [], []
|
|
199
|
+
for line in content.splitlines():
|
|
200
|
+
if _OVERALL.search(line):
|
|
201
|
+
continue
|
|
202
|
+
found = [t.lower() for t in _CLAIM_TOKEN.findall(line)]
|
|
203
|
+
verdicts.extend(found)
|
|
204
|
+
if any(t != "verified" for t in found):
|
|
205
|
+
issues.append(line.strip())
|
|
206
|
+
claims = []
|
|
207
|
+
|
|
208
|
+
return FactCheckResult(
|
|
209
|
+
overall_verdict=overall_verdict,
|
|
210
|
+
claims_checked=len(verdicts),
|
|
211
|
+
claims_verified=verdicts.count("verified"),
|
|
212
|
+
claims_contradicted=verdicts.count("contradicted"),
|
|
213
|
+
issues=issues[:10],
|
|
214
|
+
details=content,
|
|
215
|
+
claims=claims,
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
async def check(self, answer: Answer, source_chunks: list[RetrievalResult]) -> FactCheckResult:
|
|
219
|
+
sources = "\n\n".join(f"[Source {i + 1}]: {c.text}" for i, c in enumerate(source_chunks))
|
|
220
|
+
prompt = (
|
|
221
|
+
"Fact-check this answer against the source documents.\n\n"
|
|
222
|
+
f"Answer: {answer.answer_text}\n\nSources:\n{sources}\n\n"
|
|
223
|
+
"List each factual claim with its verdict, as the JSON object described."
|
|
224
|
+
)
|
|
225
|
+
response = await self.ask(prompt)
|
|
226
|
+
return self.parse(response.content)
|
|
227
|
+
|
|
228
|
+
async def run(self, **kwargs: Any) -> FactCheckResult:
|
|
229
|
+
return await self.check(kwargs["answer"], kwargs["source_chunks"])
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
# ------------------------------------------------------------------------ summarize
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
@dataclass
|
|
236
|
+
class Summary:
|
|
237
|
+
document_id: str
|
|
238
|
+
filename: str
|
|
239
|
+
summary_text: str
|
|
240
|
+
key_points: list[str]
|
|
241
|
+
word_count: int
|
|
242
|
+
compression_ratio: float
|
|
243
|
+
truncated: bool = False # True when only the first MAX_CHARS were summarized
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
class SummarizerAgent(Agent):
|
|
247
|
+
"""Summarize a whole document and pull out its key points."""
|
|
248
|
+
|
|
249
|
+
name = "summarizer"
|
|
250
|
+
description = "Summarizes a document and lists its key points"
|
|
251
|
+
system_prompt = (
|
|
252
|
+
"You are the summarization agent of a document crew. Create clear, accurate "
|
|
253
|
+
"summaries that capture the main ideas and key points. Use bullet points for key "
|
|
254
|
+
"takeaways."
|
|
255
|
+
)
|
|
256
|
+
MAX_CHARS = 12000
|
|
257
|
+
LENGTHS = {
|
|
258
|
+
"short": "3-5 sentences",
|
|
259
|
+
"medium": "1-2 paragraphs",
|
|
260
|
+
"long": "3-4 paragraphs with detailed key points",
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
async def summarize(self, document: Document, *, max_length: str = "medium") -> Summary:
|
|
264
|
+
content = document.content
|
|
265
|
+
truncated = len(content) > self.MAX_CHARS
|
|
266
|
+
if truncated:
|
|
267
|
+
content = content[: self.MAX_CHARS] + "\n...[truncated]"
|
|
268
|
+
length = self.LENGTHS.get(max_length, "1-2 paragraphs")
|
|
269
|
+
prompt = (
|
|
270
|
+
f"Summarize the following document in {length}. "
|
|
271
|
+
"After the summary, list 3-7 key points as bullet points starting with '•'.\n\n"
|
|
272
|
+
f"Document: {document.filename}\n{content}"
|
|
273
|
+
)
|
|
274
|
+
response = await self.ask(prompt)
|
|
275
|
+
text = response.content
|
|
276
|
+
key_points = []
|
|
277
|
+
for line in text.split("\n"):
|
|
278
|
+
stripped = line.strip()
|
|
279
|
+
if stripped.startswith(("•", "- ", "* ")):
|
|
280
|
+
point = stripped.lstrip("•-* ").strip()
|
|
281
|
+
if point:
|
|
282
|
+
key_points.append(point)
|
|
283
|
+
words = len(text.split())
|
|
284
|
+
return Summary(
|
|
285
|
+
document_id=document.doc_id,
|
|
286
|
+
filename=document.filename,
|
|
287
|
+
summary_text=text,
|
|
288
|
+
key_points=key_points,
|
|
289
|
+
word_count=words,
|
|
290
|
+
compression_ratio=round(words / max(document.total_words, 1), 3),
|
|
291
|
+
truncated=truncated,
|
|
292
|
+
)
|
|
293
|
+
|
|
294
|
+
async def run(self, **kwargs: Any) -> Summary:
|
|
295
|
+
return await self.summarize(
|
|
296
|
+
kwargs["document"], max_length=kwargs.get("max_length", "medium")
|
|
297
|
+
)
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
# --------------------------------------------------------------------------- rerank
|
|
301
|
+
|
|
302
|
+
|
|
303
|
+
class RerankAgent(Agent):
|
|
304
|
+
"""Reorder keyword-retrieved passages by semantic relevance."""
|
|
305
|
+
|
|
306
|
+
name = "reranker"
|
|
307
|
+
description = "Reorders retrieved passages by relevance to the question"
|
|
308
|
+
temperature = 0.0
|
|
309
|
+
system_prompt = (
|
|
310
|
+
"You rank text passages by how well they answer a question. "
|
|
311
|
+
"Reply with the passage indices only, most relevant first, comma-separated."
|
|
312
|
+
)
|
|
313
|
+
|
|
314
|
+
def parse(self, content: str, count: int) -> list[int]:
|
|
315
|
+
"""Indices from ``"2, 0, 1"`` or a JSON list; anything else is a parse error."""
|
|
316
|
+
data = extract_json(content)
|
|
317
|
+
if isinstance(data, dict):
|
|
318
|
+
data = data.get("ranking") or data.get("indices")
|
|
319
|
+
raw = data if isinstance(data, list) else re.findall(r"-?\d+", content)
|
|
320
|
+
try:
|
|
321
|
+
indices = [int(x) for x in raw]
|
|
322
|
+
except (TypeError, ValueError):
|
|
323
|
+
indices = []
|
|
324
|
+
ordered: list[int] = []
|
|
325
|
+
for i in indices:
|
|
326
|
+
if 0 <= i < count and i not in ordered:
|
|
327
|
+
ordered.append(i)
|
|
328
|
+
if not ordered:
|
|
329
|
+
raise OutputParseError(
|
|
330
|
+
self.name, f"no valid passage index (0..{count - 1})", _excerpt(content)
|
|
331
|
+
)
|
|
332
|
+
return ordered
|
|
333
|
+
|
|
334
|
+
async def rerank(
|
|
335
|
+
self, query: str, candidates: list[RetrievalResult], top_k: int | None = None
|
|
336
|
+
) -> list[RetrievalResult]:
|
|
337
|
+
if not candidates:
|
|
338
|
+
return []
|
|
339
|
+
context = "\n\n".join(f"[{i}] {c.text[:300]}" for i, c in enumerate(candidates))
|
|
340
|
+
prompt = (
|
|
341
|
+
f'Given the question: "{query}"\n\n'
|
|
342
|
+
"Rank these text chunks by relevance (most relevant first). "
|
|
343
|
+
f"Return ONLY the indices in order, comma-separated.\n\n{context}"
|
|
344
|
+
)
|
|
345
|
+
response = await self.ask(prompt)
|
|
346
|
+
order = self.parse(response.content, len(candidates))
|
|
347
|
+
ranked = [candidates[i] for i in order]
|
|
348
|
+
# Passages the model left out keep their keyword order after the ranked ones.
|
|
349
|
+
ranked += [c for i, c in enumerate(candidates) if i not in order]
|
|
350
|
+
return ranked[: top_k or len(candidates)]
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
# ------------------------------------------------------------------------- citation
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
@dataclass
|
|
357
|
+
class FormattedCitation:
|
|
358
|
+
style: str
|
|
359
|
+
inline: str
|
|
360
|
+
full_reference: str
|
|
361
|
+
source_num: int
|
|
362
|
+
|
|
363
|
+
|
|
364
|
+
class CitationAgent(Agent):
|
|
365
|
+
"""Format citations locally (APA/MLA/Chicago) or ask the LLM for a reference list."""
|
|
366
|
+
|
|
367
|
+
name = "citation"
|
|
368
|
+
description = "Formats citations and reference lists"
|
|
369
|
+
|
|
370
|
+
def __init__(self, *args: Any, citation_format: str = "apa", **kwargs: Any) -> None:
|
|
371
|
+
super().__init__(*args, **kwargs)
|
|
372
|
+
self.citation_format = citation_format
|
|
373
|
+
|
|
374
|
+
def _format_apa(self, title: str, author: str, year: str, n: int) -> FormattedCitation:
|
|
375
|
+
return FormattedCitation("apa", f"({author}, {year})", f"{author} ({year}). {title}.", n)
|
|
376
|
+
|
|
377
|
+
def _format_mla(self, title: str, author: str, year: str, n: int) -> FormattedCitation:
|
|
378
|
+
return FormattedCitation("mla", f"({author})", f'{author}. "{title}." {year}.', n)
|
|
379
|
+
|
|
380
|
+
def _format_chicago(self, title: str, author: str, year: str, n: int) -> FormattedCitation:
|
|
381
|
+
return FormattedCitation(
|
|
382
|
+
"chicago", f"({author} {year})", f'{author}. "{title}." {year}.', n
|
|
383
|
+
)
|
|
384
|
+
|
|
385
|
+
def format_citation(
|
|
386
|
+
self,
|
|
387
|
+
title: str,
|
|
388
|
+
author: str = "Document",
|
|
389
|
+
year: str = "n.d.",
|
|
390
|
+
style: str | None = None,
|
|
391
|
+
source_num: int = 1,
|
|
392
|
+
) -> FormattedCitation:
|
|
393
|
+
formatter = {
|
|
394
|
+
"apa": self._format_apa,
|
|
395
|
+
"mla": self._format_mla,
|
|
396
|
+
"chicago": self._format_chicago,
|
|
397
|
+
}.get(style or self.citation_format, self._format_apa)
|
|
398
|
+
return formatter(title, author, year, source_num)
|
|
399
|
+
|
|
400
|
+
async def generate_references(
|
|
401
|
+
self, citations: list[dict[str, str]], style: str | None = None
|
|
402
|
+
) -> str:
|
|
403
|
+
if not citations:
|
|
404
|
+
return "No sources cited."
|
|
405
|
+
sources = "\n".join(
|
|
406
|
+
f"Source {c.get('source_num', i + 1)}: chunk={c.get('chunk_id', '?')}, "
|
|
407
|
+
f"doc={c.get('document_id', '?')}, excerpt={c.get('excerpt', '')[:100]}"
|
|
408
|
+
for i, c in enumerate(citations)
|
|
409
|
+
)
|
|
410
|
+
fmt = (style or self.citation_format).upper()
|
|
411
|
+
response = await self.ask(
|
|
412
|
+
f"Format these sources as a {fmt} reference list:\n\n{sources}\n\n"
|
|
413
|
+
f"Use proper {fmt} formatting. Number each entry."
|
|
414
|
+
)
|
|
415
|
+
return response.content
|
|
416
|
+
|
|
417
|
+
async def run(self, **kwargs: Any) -> Any:
|
|
418
|
+
if "citations" in kwargs:
|
|
419
|
+
return await self.generate_references(kwargs["citations"], kwargs.get("style"))
|
|
420
|
+
return self.format_citation(
|
|
421
|
+
title=kwargs.get("title", "Untitled"),
|
|
422
|
+
author=kwargs.get("author", "Document"),
|
|
423
|
+
year=kwargs.get("year", "n.d."),
|
|
424
|
+
style=kwargs.get("style"),
|
|
425
|
+
source_num=kwargs.get("source_num", 1),
|
|
426
|
+
)
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
"""``crewforge ingest | ask | summarize`` — document Q&A (ported from documind)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
|
|
7
|
+
import click
|
|
8
|
+
from rich.markdown import Markdown
|
|
9
|
+
from rich.panel import Panel
|
|
10
|
+
from rich.table import Table
|
|
11
|
+
|
|
12
|
+
from ...cli_support import console, err_console, llm_config, print_usage, recipe_settings, run
|
|
13
|
+
from ...core.errors import ConfigError
|
|
14
|
+
from .pipeline import DocsPipeline
|
|
15
|
+
from .settings import DocsSettings
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def as_markdown(text: str) -> str:
|
|
19
|
+
"""Models often bullet with "•", which Markdown does not treat as a list."""
|
|
20
|
+
return re.sub(r"(?m)^\s*•\s*", "- ", text)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
FILES = click.argument(
|
|
24
|
+
"files", nargs=-1, required=True, type=click.Path(exists=True, dir_okay=False)
|
|
25
|
+
)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def _pipeline(ctx: click.Context) -> DocsPipeline:
|
|
29
|
+
# Settings errors surface as ConfigError inside run() -> exit 2.
|
|
30
|
+
return DocsPipeline(llm_config(ctx), _settings_or_none(ctx))
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _settings_or_none(ctx: click.Context) -> DocsSettings | None:
|
|
34
|
+
try:
|
|
35
|
+
return DocsSettings.from_mapping(recipe_settings(ctx, "docs"))
|
|
36
|
+
except ConfigError as exc:
|
|
37
|
+
from ...cli_support import EXIT_USAGE, fail
|
|
38
|
+
|
|
39
|
+
fail(f"configuration: {exc}", EXIT_USAGE)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@click.command("ingest")
|
|
43
|
+
@FILES
|
|
44
|
+
@click.pass_context
|
|
45
|
+
def ingest(ctx, files):
|
|
46
|
+
"""Parse, chunk and index documents (no LLM calls, no API key needed).
|
|
47
|
+
|
|
48
|
+
Useful to check how a file is chunked before asking questions.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
async def _run():
|
|
52
|
+
async with _pipeline(ctx) as pipeline:
|
|
53
|
+
docs = await pipeline.ingest_documents(list(files))
|
|
54
|
+
table = Table(title="Ingestion results", title_justify="left")
|
|
55
|
+
table.add_column("File", style="cyan")
|
|
56
|
+
table.add_column("Type", style="green")
|
|
57
|
+
table.add_column("Chunks", justify="right")
|
|
58
|
+
table.add_column("Words", justify="right")
|
|
59
|
+
for d in docs:
|
|
60
|
+
table.add_row(d.filename, d.file_type, str(len(d.chunks)), str(d.total_words))
|
|
61
|
+
console.print(table)
|
|
62
|
+
|
|
63
|
+
run(_run())
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
@click.command("ask")
|
|
67
|
+
@FILES
|
|
68
|
+
@click.option("-q", "--question", "questions", multiple=True, help="Question to ask (repeatable).")
|
|
69
|
+
@click.option("--verify", is_flag=True, help="Fact-check each answer against its sources.")
|
|
70
|
+
@click.option("--rerank", is_flag=True, help="Let the LLM rerank retrieved passages.")
|
|
71
|
+
@click.option(
|
|
72
|
+
"--export",
|
|
73
|
+
"export_path",
|
|
74
|
+
type=click.Path(dir_okay=False),
|
|
75
|
+
default=None,
|
|
76
|
+
help="Write the Q&A session to this file.",
|
|
77
|
+
)
|
|
78
|
+
@click.option(
|
|
79
|
+
"--format",
|
|
80
|
+
"export_format",
|
|
81
|
+
type=click.Choice(["markdown", "json"]),
|
|
82
|
+
default="markdown",
|
|
83
|
+
show_default=True,
|
|
84
|
+
help="Export format.",
|
|
85
|
+
)
|
|
86
|
+
@click.pass_context
|
|
87
|
+
def ask(ctx, files, questions, verify, rerank, export_path, export_format):
|
|
88
|
+
"""Answer questions about FILES with [Source N] citations.
|
|
89
|
+
|
|
90
|
+
\b
|
|
91
|
+
Example:
|
|
92
|
+
crewforge ask handbook.pdf -q "How many days of leave?" --verify
|
|
93
|
+
"""
|
|
94
|
+
if not questions:
|
|
95
|
+
raise click.UsageError("provide at least one question with -q")
|
|
96
|
+
|
|
97
|
+
async def _run():
|
|
98
|
+
async with _pipeline(ctx) as pipeline:
|
|
99
|
+
pipeline.require_llm() # fail on config before parsing anything
|
|
100
|
+
docs = await pipeline.ingest_documents(list(files))
|
|
101
|
+
for d in docs:
|
|
102
|
+
err_console.print(f"[green]✓[/] ingested {d.filename} ({len(d.chunks)} chunks)")
|
|
103
|
+
try:
|
|
104
|
+
for q in questions:
|
|
105
|
+
console.print(f"\n[bold yellow]Q:[/] {q}")
|
|
106
|
+
if verify:
|
|
107
|
+
answer, check = await pipeline.ask_with_verification(q, rerank=rerank)
|
|
108
|
+
else:
|
|
109
|
+
answer = await pipeline.ask(q, rerank=rerank)
|
|
110
|
+
console.print(Markdown(answer.answer_text))
|
|
111
|
+
if verify:
|
|
112
|
+
color = {"verified": "green", "partially_verified": "yellow"}.get(
|
|
113
|
+
check.overall_verdict, "red"
|
|
114
|
+
)
|
|
115
|
+
console.print(
|
|
116
|
+
f"[{color}]Verification: {check.overall_verdict}[/] "
|
|
117
|
+
f"({check.claims_verified}/{check.claims_checked} claims verified)"
|
|
118
|
+
)
|
|
119
|
+
if export_path:
|
|
120
|
+
path = await pipeline.export_session(export_path, fmt=export_format)
|
|
121
|
+
err_console.print(f"[blue]Exported to:[/] {path}")
|
|
122
|
+
finally:
|
|
123
|
+
print_usage(pipeline.tracker)
|
|
124
|
+
|
|
125
|
+
run(_run())
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@click.command("summarize")
|
|
129
|
+
@FILES
|
|
130
|
+
@click.option(
|
|
131
|
+
"--length",
|
|
132
|
+
type=click.Choice(["short", "medium", "long"]),
|
|
133
|
+
default="medium",
|
|
134
|
+
show_default=True,
|
|
135
|
+
)
|
|
136
|
+
@click.pass_context
|
|
137
|
+
def summarize(ctx, files, length):
|
|
138
|
+
"""Summarize each document and list its key points."""
|
|
139
|
+
|
|
140
|
+
async def _run():
|
|
141
|
+
async with _pipeline(ctx) as pipeline:
|
|
142
|
+
pipeline.require_llm()
|
|
143
|
+
try:
|
|
144
|
+
for doc in await pipeline.ingest_documents(list(files)):
|
|
145
|
+
summary = await pipeline.summarize_document(doc, max_length=length)
|
|
146
|
+
title = f"Summary: {doc.filename}"
|
|
147
|
+
if summary.truncated:
|
|
148
|
+
title += " (first part only — document was truncated)"
|
|
149
|
+
console.print(Panel(Markdown(as_markdown(summary.summary_text)), title=title))
|
|
150
|
+
finally:
|
|
151
|
+
print_usage(pipeline.tracker)
|
|
152
|
+
|
|
153
|
+
run(_run())
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
commands = [ingest, ask, summarize]
|