Angshul commited on
Commit
0703e2b
·
verified ·
1 Parent(s): 7c48529

Upload 27 files

Browse files
data/kb.jsonl ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ {"id": "fgao-1", "title": "FGAO", "text": "FGAO stands for Feedback-Greedy Agentic Orchestration. It is a training-free controller that chooses the next tool call by predicted progress on verifiable goals, net of cost."}
2
+ {"id": "fgao-2", "title": "FGAO", "text": "FGAO abstains when no answer is both grounded in a retrieved passage and accepted by a support check."}
3
+ {"id": "fgao-3", "title": "FGAO", "text": "The FGAO controller learns from the outcomes of its own tool calls during a run, through a prior-and-feedback blend of effect estimates."}
src/fgao/__init__.py ADDED
@@ -0,0 +1,29 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """FGAO: Feedback-Greedy Agentic Orchestration.
2
+
3
+ A training-free numerical controller for tool-using pipelines and RAG.
4
+
5
+ Layers
6
+ ------
7
+ FGAOController step-wise controller: reset / should_stop / select_action / update
8
+ Workflow declare goals + tools; FGAO decides the order (invoke, stream, batch, async)
9
+ FGAORAG ready-made RAG orchestrator with pluggable retrievers, LLM and checks
10
+ """
11
+ from .controller import ControllerStopped, FGAOConfig, FGAOController
12
+ from .estimator import EffectStatistics, blend
13
+ from .types import Action, ActionSpec, Condition, Decision, Observation, Scores, Semantics, Status, deficiency
14
+ from .workflow import CompiledWorkflow, Interrupt, Run, Step, Tool, ToolResult, Workflow, WorkflowResult
15
+ from .rag import (
16
+ BM25Retriever, CachedLLM, Costs, DenseRetriever, Document, FGAORAG, FunctionLLM, FunctionRetriever, Priors,
17
+ RAGResult, Source, Weights, default_sources,
18
+ )
19
+
20
+ __version__ = "1.0.0"
21
+
22
+ __all__ = [
23
+ "FGAOConfig", "FGAOController", "ControllerStopped", "EffectStatistics", "blend",
24
+ "Action", "ActionSpec", "Condition", "Decision", "Observation", "Scores", "Semantics", "Status", "deficiency",
25
+ "Workflow", "CompiledWorkflow", "Tool", "ToolResult", "Step", "WorkflowResult", "Run", "Interrupt",
26
+ "FGAORAG", "RAGResult", "Source", "Costs", "Priors", "Weights", "default_sources",
27
+ "Document", "BM25Retriever", "DenseRetriever", "FunctionRetriever", "FunctionLLM", "CachedLLM",
28
+ "__version__",
29
+ ]
src/fgao/controller.py ADDED
@@ -0,0 +1,902 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """FGAO v2 controller (Feedback-Greedy Agentic Orchestration).
2
+
3
+ A training-free, model-free numerical controller. At every step it picks
4
+
5
+ a* = argmax_a Delta_hat(a) - lam * c_hat(a) / B0 + gamma * H_hat(a)
6
+
7
+ where Delta_hat is the predicted weighted progress on the verifiable goals
8
+ (declared prior blended with online feedback, rho = nu / (nu + n)), c_hat the
9
+ estimated cost, and H_hat the one-step continuation value (lookahead). It stops
10
+ when every mandatory goal is verified, or when no admissible, affordable action
11
+ has positive value (eq. 20), or when the budget is spent.
12
+
13
+ The controller performs no I/O. It is driven through three calls::
14
+
15
+ ctrl = FGAOController(conditions, actions, budget=16)
16
+ ctrl.reset(observation)
17
+ while ctrl.should_stop() is None:
18
+ decision = ctrl.select_action()
19
+ observation, cost = execute(decision.action) # your code
20
+ ctrl.update(decision.action, observation, cost)
21
+
22
+ The numerical algorithm (estimator, scoring, lookahead forms, tie-breaking,
23
+ stopping rule) is the tested v2 implementation, unchanged. Defaults are the
24
+ configuration used for RAG: unlock lookahead, lam = 0.1, nu = 4, gamma = 0.9,
25
+ task-declared comparability groups.
26
+ """
27
+ from __future__ import annotations
28
+
29
+ import itertools
30
+ import math
31
+ import random
32
+ import time
33
+ from dataclasses import dataclass
34
+ from typing import Callable, Dict, Hashable, Iterable, List, Mapping, Optional, Sequence, Set, Tuple, Union
35
+
36
+ from .estimator import EffectStatistics, blend
37
+ from .types import (
38
+ SAT_THRESHOLD,
39
+ Action,
40
+ ActionSpec,
41
+ Condition,
42
+ Decision,
43
+ Observation,
44
+ ObsState,
45
+ Scores,
46
+ Semantics,
47
+ Status,
48
+ all_mandatory_verified,
49
+ deficiency,
50
+ )
51
+
52
+ MAX_ENUM_EFFECTS = 6 # eq. 17: at most 2^6 outcomes per action; extra effects fixed at their mode
53
+
54
+
55
+ @dataclass
56
+ class FGAOConfig:
57
+ """Controller hyperparameters. Defaults are the evaluated v2 RAG configuration."""
58
+
59
+ nu: float = 4.0 # prior strength: rho = nu / (nu + n)
60
+ lam: float = 0.1 # cost weight, in goal units per whole budget
61
+ gamma: float = 0.9 # continuation weight
62
+ lookahead: str = "unlock" # "unlock" | "eq16" | "eq17" | "none"
63
+ lookahead_depth: int = 1 # unlock form only; 0 disables lookahead
64
+ corrective: bool = True # unlock form: credit repair actions after predicted harm
65
+ similarity: str = "task" # feedback pooling: "task" (declared groups) | "exact" | "type"
66
+ estimator: str = "rate" # "rate" (state-normalised gain/harm rates) | "raw"
67
+ feedback: bool = True # False: priors only (rho = 1)
68
+ objective: str = "additive" # "additive" | "ratio" (ranking only)
69
+ beta: float = 0.0 # optional exploration bonus weight
70
+ optional_mass: Optional[float] = None # weight share of optional goals (None: declared weights)
71
+ cost_scale: Optional[float] = None # B0; default: the initial budget
72
+ max_steps: int = 10_000
73
+
74
+ def __post_init__(self) -> None:
75
+ if self.lookahead not in ("unlock", "eq16", "eq17", "none"):
76
+ raise ValueError("lookahead must be unlock | eq16 | eq17 | none")
77
+ if self.estimator not in ("rate", "raw"):
78
+ raise ValueError("estimator must be rate | raw")
79
+ if self.objective not in ("additive", "ratio"):
80
+ raise ValueError("objective must be additive | ratio")
81
+ if self.similarity not in ("task", "exact", "type"):
82
+ raise ValueError("similarity must be task | exact | type")
83
+
84
+
85
+ class ControllerStopped(RuntimeError):
86
+ """Raised by ``select_action`` once the controller has stopped."""
87
+
88
+
89
+ ActionsArg = Union[Sequence[ActionSpec], Mapping[Action, Semantics]]
90
+
91
+
92
+ class FGAOController:
93
+ """Step-wise FGAO v2 controller for one episode (one query / one task run).
94
+
95
+ Parameters
96
+ ----------
97
+ conditions : goal conditions with weights; mandatory ones define success.
98
+ actions : ``ActionSpec`` list (or ``{Action: Semantics}``) in a fixed
99
+ order. The order matters only for exact ties, which are broken
100
+ by a seeded RNG.
101
+ config : ``FGAOConfig``.
102
+ budget : execution budget B0 (``inf`` allowed).
103
+ seed : seeds the tie-breaking RNG.
104
+ comparability_key : optional ``Action -> Hashable``; overrides ``ActionSpec.group``.
105
+ prior : optional ``Action -> Semantics`` used for the effect prior only
106
+ (preconditions and declared costs still come from ``actions``).
107
+ """
108
+
109
+ def __init__(
110
+ self,
111
+ conditions: Sequence[Condition],
112
+ actions: ActionsArg,
113
+ config: Optional[FGAOConfig] = None,
114
+ *,
115
+ budget: float = float("inf"),
116
+ seed: int = 0,
117
+ comparability_key: Optional[Callable[[Action], Hashable]] = None,
118
+ prior: Optional[Callable[[Action], Semantics]] = None,
119
+ ) -> None:
120
+ self.cfg = config or FGAOConfig()
121
+ if isinstance(actions, Mapping):
122
+ specs = [ActionSpec(a, s) for a, s in actions.items()]
123
+ else:
124
+ specs = list(actions)
125
+ if len({s.action for s in specs}) != len(specs):
126
+ raise ValueError("duplicate action in the action set")
127
+ self.conditions: List[Condition] = list(conditions)
128
+ names = {c.name for c in self.conditions}
129
+ if len(names) != len(self.conditions):
130
+ raise ValueError("duplicate condition name")
131
+ self.weights = self.assign_weights(self.conditions)
132
+ self.candidates: List[Action] = [s.action for s in specs]
133
+ self._req: Dict[Action, Semantics] = {s.action: s.semantics for s in specs}
134
+ self._sem: Dict[Action, Semantics] = {a: (prior(a) if prior else self._req[a]) for a in self.candidates}
135
+ self._needs_pred: Dict[str, List[Action]] = {}
136
+ self._needs_cond: Dict[str, List[Action]] = {}
137
+ for a in self.candidates:
138
+ for p in self._req[a].requires_predicates:
139
+ self._needs_pred.setdefault(p, []).append(a)
140
+ for c in self._req[a].requires_conditions:
141
+ self._needs_cond.setdefault(c, []).append(a)
142
+ self._init_gainers()
143
+ groups = {s.action: s.group for s in specs if s.group is not None}
144
+ key_fn = None
145
+ if self.cfg.similarity == "task":
146
+ key_fn = comparability_key or (lambda a: groups.get(a, a.signature))
147
+ self._key_fn = key_fn
148
+ self.stats = EffectStatistics(self.cfg.similarity, key_fn)
149
+ self._by_key: Dict[Hashable, List[Action]] = {}
150
+ for a in self.candidates: # actions sharing feedback: one update changes only their estimates
151
+ self._by_key.setdefault(self.stats.key(a), []).append(a)
152
+ self.n_effect_evals = 0
153
+ self.budget0 = float(budget)
154
+ self._cost_scale = self.cfg.cost_scale or (self.budget0 if math.isfinite(self.budget0) else 1.0)
155
+ self._rng = random.Random(seed * 7919 + 17)
156
+ self.seed = seed
157
+ self._started = False
158
+ self._invalidate()
159
+
160
+ def _init_gainers(self) -> None:
161
+ self._gainers: Dict[str, set] = {}
162
+ for a in self.candidates:
163
+ for c, g in self._sem[a].gain.items():
164
+ if g > 0:
165
+ self._gainers.setdefault(c, set()).add(a)
166
+
167
+ def _invalidate_key(self, key: Hashable) -> None:
168
+ for a in self._by_key.get(key, ()):
169
+ self._cost_memo.pop(a, None)
170
+ self._support.pop(a, None)
171
+ self._rate_memo.pop(a, None)
172
+
173
+ def _invalidate(self) -> None:
174
+ """Drop memoised estimates. They depend only on the statistics, which change only in ``update``."""
175
+ self._rate_memo: Dict[Action, Dict[Tuple[str, str], float]] = {}
176
+ self._cost_memo: Dict[Action, float] = {}
177
+ self._support: Dict[Action, List[Tuple[str, float, float, float]]] = {}
178
+
179
+ # ================================================================ step API
180
+ def reset(self, observation: Observation) -> "FGAOController":
181
+ """Start a fresh episode from the initial observation (online statistics start empty, as in v2)."""
182
+ self.stats = EffectStatistics(self.cfg.similarity, self._key_fn)
183
+ self._init_gainers()
184
+ self.n_effect_evals = 0
185
+ self._rng = random.Random(self.seed * 7919 + 17)
186
+ self.v: Dict[str, float] = dict(observation.values)
187
+ self.preds: Dict[str, bool] = dict(observation.predicates)
188
+ self.budget = self.budget0
189
+ self.spent = 0.0
190
+ self.t = 0
191
+ self.history: List[Dict] = []
192
+ self.status: str = Status.RUNNING
193
+ self._pending: Optional[Decision] = None
194
+ self._rng_at_decide = None
195
+ self.blocked: Set[Action] = set()
196
+ self._started = True
197
+ self._invalidate()
198
+ return self
199
+
200
+ def block(self, action: Action) -> None:
201
+ """Exclude ``action`` for the rest of the episode (e.g. a human rejected it)."""
202
+ if action not in self._req:
203
+ raise KeyError(f"unknown action {action}")
204
+ self.blocked.add(action)
205
+ if self._pending is not None and self._pending.action == action:
206
+ self._discard_pending()
207
+
208
+ def _discard_pending(self) -> None:
209
+ if self._rng_at_decide is not None:
210
+ self._rng.setstate(self._rng_at_decide)
211
+ self._pending = None
212
+ self._rng_at_decide = None
213
+
214
+ @property
215
+ def state(self) -> ObsState:
216
+ return ObsState(dict(self.v), dict(self.preds), self.budget, self.t)
217
+
218
+ @property
219
+ def success(self) -> bool:
220
+ return all_mandatory_verified(self.conditions, self.v)
221
+
222
+ @property
223
+ def deficiency(self) -> float:
224
+ return deficiency(self.conditions, self.v)
225
+
226
+ def admissible_actions(self) -> List[Action]:
227
+ st = self.state
228
+ return [a for a in self.candidates if self._admissible(a, st)]
229
+
230
+ def _decide(self) -> None:
231
+ if self.status != Status.RUNNING or self._pending is not None:
232
+ return
233
+ state = ObsState(self.v, self.preds, self.budget, self.t)
234
+ if all_mandatory_verified(self.conditions, self.v):
235
+ self.status = Status.SUCCESS
236
+ return
237
+ if self.t >= self.cfg.max_steps:
238
+ self.status = Status.STEP_LIMIT
239
+ return
240
+ if self.budget <= 0:
241
+ self.status = Status.BUDGET_EXHAUSTED
242
+ return
243
+ t_sel = time.perf_counter()
244
+ self._rng_at_decide = self._rng.getstate()
245
+ admissible = [a for a in self.candidates if self._admissible(a, state) and a not in self.blocked]
246
+ if not admissible:
247
+ self.status = Status.BLOCKED
248
+ return
249
+ affordable = [a for a in admissible if self.estimated_cost(a) <= self.budget]
250
+ if not affordable:
251
+ self.status = Status.BUDGET_EXHAUSTED
252
+ return
253
+ self._begin_step(affordable, state)
254
+ scored = [(a, self.score(a, state)) for a in affordable]
255
+ best_exploit = max(s["exploit"] for _, s in scored)
256
+ if best_exploit <= 0: # eq. (20)
257
+ self.status = Status.STALLED
258
+ return
259
+ top = max(s["rank"] for _, s in scored)
260
+ ties = [(a, s) for a, s in scored if s["rank"] >= top - 1e-12]
261
+ action, sc = ties[self._rng.randrange(len(ties))] if len(ties) > 1 else ties[0]
262
+ self._pending = Decision(
263
+ step=self.t,
264
+ action=action,
265
+ scores=Scores(**sc),
266
+ candidates=[(a, Scores(**s)) for a, s in scored],
267
+ n_admissible=len(admissible),
268
+ select_time=time.perf_counter() - t_sel,
269
+ )
270
+
271
+ def should_stop(self) -> Optional[str]:
272
+ """``None`` while running; otherwise the termination status.
273
+
274
+ Calling it computes (and caches) the next decision, so it is cheap to
275
+ follow with ``select_action``.
276
+ """
277
+ if not self._started:
278
+ raise RuntimeError("call reset(observation) first")
279
+ self._decide()
280
+ return None if self.status == Status.RUNNING else self.status
281
+
282
+ def select_action(self) -> Decision:
283
+ """The action to execute next, with its scores and every alternative."""
284
+ if self.should_stop() is not None:
285
+ raise ControllerStopped(self.status)
286
+ return self._pending # type: ignore[return-value]
287
+
288
+ def update(
289
+ self,
290
+ action: Action,
291
+ observation: Observation,
292
+ cost: Optional[float] = None,
293
+ error: Optional[str] = None,
294
+ ) -> Dict:
295
+ """Record the outcome of executing ``action``.
296
+
297
+ ``observation`` holds the goal values and predicates *after* the
298
+ execution, ``cost`` the measured cost (default: the declared cost).
299
+ Updates budget, history and the online effect estimator.
300
+ """
301
+ if not self._started:
302
+ raise RuntimeError("call reset(observation) first")
303
+ if self.status != Status.RUNNING:
304
+ raise ControllerStopped(self.status)
305
+ if action not in self._req:
306
+ raise KeyError(f"unknown action {action}")
307
+ dec = self._pending if (self._pending is not None and self._pending.action == action) else None
308
+ cost = self._req[action].cost if cost is None else float(cost)
309
+ v_before, p_before = dict(self.v), dict(self.preds)
310
+ self.v = dict(observation.values)
311
+ self.preds = dict(observation.predicates)
312
+ self.budget -= cost
313
+ self.spent += cost
314
+ if self.cfg.feedback:
315
+ self.stats.update(action, v_before, self.v, p_before, self.preds, cost)
316
+ self._invalidate_key(self.stats.key(action))
317
+ for c in self.weights:
318
+ if self.v.get(c, 0.0) > v_before.get(c, 0.0):
319
+ self._gainers.setdefault(c, set()).add(action)
320
+ observed = sum(self.weights[c] * (self.v.get(c, 0.0) - v_before.get(c, 0.0)) for c in self.weights)
321
+ rec = {
322
+ "step": self.t,
323
+ "action": str(action),
324
+ "Q": dec.scores.Q if dec else None,
325
+ "predicted_gain": dec.scores.gain if dec else None,
326
+ "continuation": dec.scores.continuation if dec else None,
327
+ "estimated_cost": dec.scores.cost if dec else None,
328
+ "observed_effect": observed,
329
+ "cost": cost,
330
+ "budget_left": self.budget,
331
+ "deficiency": deficiency(self.conditions, self.v),
332
+ "values": dict(self.v),
333
+ "error": error,
334
+ "n_actions": len(dec.candidates) if dec else None,
335
+ "select_time": dec.select_time if dec else None,
336
+ }
337
+ self.history.append(rec)
338
+ self.t += 1
339
+ self._pending = None
340
+ self._rng_at_decide = None
341
+ return rec
342
+
343
+ # ======================================================== parallel calls
344
+ def select_batch(self, max_parallel: int,
345
+ conflicts: Optional[Callable[[Action, Action], bool]] = None,
346
+ independent: bool = True) -> List[Decision]:
347
+ """Up to ``max_parallel`` actions to execute concurrently.
348
+
349
+ The first is exactly ``select_action()`` (the v2 choice). Further slots are
350
+ filled greedily with actions that are admissible and affordable now, do not
351
+ conflict with the batch, and still have positive net value
352
+ S(b | s_hat) = Delta_hat(b | s_hat) - lam c_hat(b)/B0 in the *expected* state s_hat
353
+ after the actions already chosen (each chosen action moves every goal to
354
+ v + delta_hat). Actions are never repeated within a batch. With
355
+ ``max_parallel=1`` this is ``[select_action()]``.
356
+
357
+ independent=True (default) admits only calls whose effects are disjoint from
358
+ the batch: they may not gain, harm or produce anything an earlier member
359
+ gains, harms or produces. Calls on the same goal are then never run at the
360
+ same time (no hedged duplicates, no conflicting writers), and every observed
361
+ change has at most one declared owner, so feedback attribution stays exact.
362
+ independent=False is the plain expected-state rule.
363
+ """
364
+ first = self.select_action()
365
+ batch = [first]
366
+ if max_parallel <= 1:
367
+ return batch
368
+ real = ObsState(self.v, self.preds, self.budget, self.t)
369
+ s_hat = self._expect(first.action, real.copy())
370
+ left = self.budget - self.estimated_cost(first.action)
371
+ chosen = {first.action}
372
+ touched = set(self._attribution(first.action)) if independent else set()
373
+ t_sel = time.perf_counter()
374
+ while len(batch) < max_parallel:
375
+ best, best_val = None, 0.0
376
+ for a in self.candidates:
377
+ if a in chosen or a in self.blocked or not self._admissible(a, real):
378
+ continue
379
+ c = self.estimated_cost(a)
380
+ if c > left or (conflicts is not None and any(conflicts(a, b.action) for b in batch)):
381
+ continue
382
+ if independent and self._attribution(a) & touched:
383
+ continue
384
+ val = self._net(a, s_hat)
385
+ if val > best_val + 1e-12:
386
+ best, best_val = a, val
387
+ if best is None:
388
+ break
389
+ g = self.predicted_gain(best, s_hat)
390
+ c = self.estimated_cost(best)
391
+ sc = Scores(Q=best_val, rank=best_val, exploit=best_val, gain=g, cost=c, bonus=0.0, continuation=0.0)
392
+ batch.append(Decision(step=self.t + len(batch), action=best, scores=sc, candidates=[], n_admissible=0,
393
+ select_time=0.0))
394
+ chosen.add(best)
395
+ if independent:
396
+ touched |= self._attribution(best)
397
+ left -= c
398
+ s_hat = self._expect(best, s_hat)
399
+ if len(batch) > 1:
400
+ dt = time.perf_counter() - t_sel
401
+ for d in batch[1:]:
402
+ d.select_time = dt / (len(batch) - 1)
403
+ self._batch_decs = {d.action: d for d in batch}
404
+ return batch
405
+
406
+ def _expect(self, a: Action, s: ObsState) -> ObsState:
407
+ """Expected state after ``a``: v_i <- v_i + delta_hat_i(a | s)."""
408
+ d = self.predicted_effect(a, s)
409
+ for c, x in d.items():
410
+ s.v[c] = min(1.0, max(0.0, s.v.get(c, 0.0) + x))
411
+ return s
412
+
413
+ def _attribution(self, a: Action) -> Set[str]:
414
+ sem = self._sem[a]
415
+ out = {c for c, x in sem.gain.items() if x != 0} | {c for c, x in sem.harm.items() if x != 0}
416
+ out |= set(sem.produces)
417
+ out |= set(self.stats.observed_targets(a, "gain")) | set(self.stats.observed_targets(a, "harm"))
418
+ out |= set(self.stats.observed_targets(a, "produce"))
419
+ return out
420
+
421
+ def update_batch(self, actions: Sequence[Action], observation: Observation,
422
+ costs: Optional[Sequence[Optional[float]]] = None,
423
+ errors: Optional[Sequence[Optional[str]]] = None) -> List[Dict]:
424
+ """Record a batch executed concurrently, observed once afterwards.
425
+
426
+ Feedback attribution: a goal or predicate that changed is credited to the batch
427
+ members that declare it or have observed it before; a change no member
428
+ targets is credited to all of them. A single-action batch is exactly ``update``.
429
+ """
430
+ actions = list(actions)
431
+ costs = list(costs) if costs is not None else [None] * len(actions)
432
+ errors = list(errors) if errors is not None else [None] * len(actions)
433
+ if len(actions) == 1:
434
+ return [self.update(actions[0], observation, costs[0], errors[0])]
435
+ if not self._started:
436
+ raise RuntimeError("call reset(observation) first")
437
+ if self.status != Status.RUNNING:
438
+ raise ControllerStopped(self.status)
439
+ if len(set(actions)) != len(actions):
440
+ raise ValueError("an action appears twice in the batch")
441
+ for a in actions:
442
+ if a not in self._req:
443
+ raise KeyError(f"unknown action {a}")
444
+ decs = dict(getattr(self, "_batch_decs", {}) or {})
445
+ if self._pending is not None:
446
+ decs[self._pending.action] = self._pending
447
+ v0, p0 = dict(self.v), dict(self.preds)
448
+ v1, p1 = dict(observation.values), dict(observation.predicates)
449
+ changed = {c for c in set(v0) | set(v1) if v1.get(c, 0.0) != v0.get(c, 0.0)}
450
+ changed |= {q for q in set(p0) | set(p1) if bool(p1.get(q, False)) != bool(p0.get(q, False))}
451
+ attr = {a: self._attribution(a) for a in actions}
452
+ orphan = {k for k in changed if not any(k in attr[a] for a in actions)}
453
+ recs = []
454
+ rnd = self.t
455
+ for a, cost, err in zip(actions, costs, errors):
456
+ mine = (attr[a] & changed) | orphan
457
+ va = {c: (v1.get(c, 0.0) if c in mine else v0.get(c, 0.0)) for c in set(v0) | set(v1)}
458
+ pa = {q: (p1.get(q, False) if q in mine else p0.get(q, False)) for q in set(p0) | set(p1)}
459
+ cost = self._req[a].cost if cost is None else float(cost)
460
+ if self.cfg.feedback:
461
+ self.stats.update(a, v0, va, p0, pa, cost)
462
+ self._invalidate_key(self.stats.key(a))
463
+ for c in self.weights:
464
+ if va.get(c, 0.0) > v0.get(c, 0.0):
465
+ self._gainers.setdefault(c, set()).add(a)
466
+ self.budget -= cost
467
+ self.spent += cost
468
+ dec = decs.get(a)
469
+ recs.append({
470
+ "step": self.t, "round": rnd, "action": str(a), "Q": dec.scores.Q if dec else None,
471
+ "predicted_gain": dec.scores.gain if dec else None,
472
+ "continuation": dec.scores.continuation if dec else None,
473
+ "estimated_cost": dec.scores.cost if dec else None,
474
+ "observed_effect": sum(self.weights[c] * (va.get(c, 0.0) - v0.get(c, 0.0)) for c in self.weights),
475
+ "cost": cost, "budget_left": self.budget, "deficiency": deficiency(self.conditions, v1),
476
+ "values": dict(v1), "error": err, "n_actions": None, "select_time": None,
477
+ })
478
+ self.t += 1
479
+ self.v, self.preds = v1, p1
480
+ self.history.extend(recs)
481
+ self._pending = None
482
+ self._rng_at_decide = None
483
+ self._batch_decs = {}
484
+ return recs
485
+
486
+ # ======================================================= checkpointing
487
+ def snapshot(self) -> Dict:
488
+ """JSON-serialisable episode state: goal values, predicates, budget, history,
489
+ online statistics, tie-breaking RNG and blocked actions.
490
+
491
+ ``restore`` on a controller built with the same conditions, actions and
492
+ configuration continues with exactly the decisions the original would
493
+ have made.
494
+ """
495
+ if not self._started:
496
+ raise RuntimeError("call reset(observation) first")
497
+ index = {a: i for i, a in enumerate(self.candidates)}
498
+ rep: Dict[Hashable, int] = {}
499
+ for a in self.candidates:
500
+ rep.setdefault(self.stats.key(a), index[a])
501
+ stats = []
502
+ for key, ks in self.stats._stats.items():
503
+ if key not in rep:
504
+ continue
505
+ stats.append({
506
+ "action": rep[key], "executions": ks.executions, "cost": [ks.cost.n, ks.cost.total],
507
+ **{kind: {t: [r.n, r.total] for t, r in getattr(ks, kind).items()}
508
+ for kind in ("gain", "harm", "produce", "raw")},
509
+ })
510
+ rng = self._rng_at_decide if self._rng_at_decide is not None else self._rng.getstate()
511
+ return {
512
+ "format": 1, "n_actions": len(self.candidates), "conditions": [c.name for c in self.conditions],
513
+ "v": dict(self.v), "predicates": dict(self.preds), "budget": self.budget, "budget0": self.budget0,
514
+ "spent": self.spent, "t": self.t, "status": self.status, "history": list(self.history),
515
+ "stats": stats, "gainers": {c: sorted(index[a] for a in acts) for c, acts in self._gainers.items()},
516
+ "rng": [rng[0], list(rng[1]), rng[2]], "blocked": sorted(index[a] for a in self.blocked),
517
+ "n_effect_evals": self.n_effect_evals,
518
+ }
519
+
520
+ def restore(self, snap: Mapping) -> "FGAOController":
521
+ """Load a ``snapshot`` (see there)."""
522
+ from .estimator import _KeyStats, _Running
523
+
524
+ if snap.get("format") != 1:
525
+ raise ValueError("unknown snapshot format")
526
+ if snap["n_actions"] != len(self.candidates) or snap["conditions"] != [c.name for c in self.conditions]:
527
+ raise ValueError("snapshot belongs to a different action set or goal set")
528
+ self.reset(Observation(dict(snap["v"]), dict(snap["predicates"])))
529
+ self.budget, self.budget0, self.spent = snap["budget"], snap["budget0"], snap["spent"]
530
+ self.t, self.status, self.history = snap["t"], snap["status"], list(snap["history"])
531
+ self.stats._stats.clear()
532
+ for e in snap["stats"]:
533
+ ks = _KeyStats()
534
+ ks.executions = e["executions"]
535
+ ks.cost = _Running(*e["cost"])
536
+ for kind in ("gain", "harm", "produce", "raw"):
537
+ table = getattr(ks, kind)
538
+ for t, (n, total) in e[kind].items():
539
+ table[t] = _Running(n, total)
540
+ self.stats._stats[self.stats.key(self.candidates[e["action"]])] = ks
541
+ self._gainers = {c: {self.candidates[i] for i in idx} for c, idx in snap["gainers"].items()}
542
+ r = snap["rng"]
543
+ self._rng.setstate((r[0], tuple(r[1]), r[2]))
544
+ self.blocked = {self.candidates[i] for i in snap["blocked"]}
545
+ self.n_effect_evals = snap.get("n_effect_evals", 0)
546
+ self._invalidate()
547
+ return self
548
+
549
+ # ============================================================ v2 algorithm
550
+ def assign_weights(self, conditions) -> Dict[str, float]:
551
+ """assign_weights(conditions).
552
+
553
+ Default: the task's weights. With ``optional_mass = eps``, mandatory
554
+ conditions share 1 - eps (in proportion to their task weights) and
555
+ optional conditions share eps.
556
+ """
557
+ w = {c.name: c.weight for c in conditions}
558
+ eps = self.cfg.optional_mass
559
+ if eps is None:
560
+ return w
561
+ mand = [c.name for c in conditions if c.mandatory]
562
+ opt = [c.name for c in conditions if not c.mandatory]
563
+ if not opt:
564
+ return w
565
+ sm = sum(w[c] for c in mand) or 1.0
566
+ so = sum(w[c] for c in opt) or 1.0
567
+ out = {c: (1.0 - eps) * w[c] / sm for c in mand}
568
+ out.update({c: eps * w[c] / so for c in opt})
569
+ return out
570
+
571
+ def _admissible(self, a: Action, state: ObsState) -> bool:
572
+ req = self._req[a]
573
+ for p in req.requires_predicates:
574
+ if not state.predicates.get(p, False):
575
+ return False
576
+ for c in req.requires_conditions:
577
+ if state.v.get(c, 0.0) < SAT_THRESHOLD:
578
+ return False
579
+ return True
580
+
581
+ # -------------------------------------------------------------- estimates
582
+ def _nu(self) -> float:
583
+ return self.cfg.nu if self.cfg.feedback else float("inf")
584
+
585
+ def _rate(self, a: Action, kind: str, target: str) -> float:
586
+ memo = self._rate_memo.get(a)
587
+ if memo is None:
588
+ memo = self._rate_memo[a] = {}
589
+ key = (kind, target)
590
+ r = memo.get(key)
591
+ if r is None:
592
+ r = memo[key] = self._rate_uncached(a, kind, target)
593
+ return r
594
+
595
+ def _rate_uncached(self, a: Action, kind: str, target: str) -> float:
596
+ sem = self._sem[a]
597
+ prior = {"gain": sem.gain, "harm": sem.harm, "produce": sem.produces}[kind].get(target, 0.0)
598
+ if not self.cfg.feedback:
599
+ return prior
600
+ n, emp = self.stats.rate(a, kind, target)
601
+ return blend(prior, emp, n, self._nu())
602
+
603
+ def predicted_effect(self, a: Action, state: ObsState) -> Dict[str, float]:
604
+ """delta_hat_i(a) for every condition (eqs. 10-12)."""
605
+ self.n_effect_evals += 1
606
+ out = {}
607
+ if self.cfg.estimator == "raw":
608
+ sem = self._sem[a]
609
+ n = self.stats.executions(a) if self.cfg.feedback else 0
610
+ for c in self.conditions:
611
+ vi = state.v.get(c.name, 0.0)
612
+ prior = (1.0 - vi) * sem.gain.get(c.name, 0.0) - vi * sem.harm.get(c.name, 0.0)
613
+ emp = self.stats.rate(a, "raw", c.name)[1] if n else 0.0
614
+ d = blend(prior, emp, n, self._nu())
615
+ out[c.name] = max(-vi, min(1.0 - vi, d)) # keep v + delta in [0, 1]
616
+ return out
617
+ for c in self.conditions:
618
+ vi = state.v.get(c.name, 0.0)
619
+ g = self._rate(a, "gain", c.name)
620
+ h = self._rate(a, "harm", c.name)
621
+ out[c.name] = (1.0 - vi) * g - vi * h
622
+ return out
623
+
624
+ def predicted_gain(self, a: Action, state: ObsState) -> float:
625
+ """Delta_hat(a | s) = sum_i w_i delta_hat_i(a), eq. (13).
626
+
627
+ For the rate estimator, a goal contributes an exact 0.0 unless the action
628
+ declares it or has a positive observation for it, so only that support is
629
+ summed, in condition order; the result is bit-identical to the full sum.
630
+ """
631
+ if self.cfg.estimator != "rate":
632
+ d = self.predicted_effect(a, state)
633
+ return sum(self.weights[c] * d[c] for c in d)
634
+ self.n_effect_evals += 1
635
+ sup = self._support.get(a)
636
+ if sup is None:
637
+ sup = self._support[a] = self._build_support(a)
638
+ v = state.v
639
+ total = 0.0
640
+ for c, w, g, h in sup:
641
+ vi = v.get(c, 0.0)
642
+ total += w * ((1.0 - vi) * g - vi * h)
643
+ return total
644
+
645
+ def _build_support(self, a: Action) -> List[Tuple[str, float, float, float]]:
646
+ sem = self._sem[a]
647
+ keys = {c for c, x in sem.gain.items() if x != 0} | {c for c, x in sem.harm.items() if x != 0}
648
+ if self.cfg.feedback:
649
+ keys |= set(self.stats.observed_targets(a, "gain")) | set(self.stats.observed_targets(a, "harm"))
650
+ out = []
651
+ for cond in self.conditions:
652
+ c = cond.name
653
+ if c in keys:
654
+ out.append((c, self.weights[c], self._rate(a, "gain", c), self._rate(a, "harm", c)))
655
+ return out
656
+
657
+ def estimated_cost(self, a: Action) -> float:
658
+ r = self._cost_memo.get(a)
659
+ if r is None:
660
+ r = self._cost_memo[a] = self._estimated_cost_uncached(a)
661
+ return r
662
+
663
+ def _estimated_cost_uncached(self, a: Action) -> float:
664
+ prior = self._sem[a].cost
665
+ if not self.cfg.feedback:
666
+ return prior
667
+ n, emp = self.stats.mean_cost(a)
668
+ return blend(prior, emp, n, self._nu())
669
+
670
+ def uncertainty(self, a: Action, t: int) -> float:
671
+ n = self.stats.executions(a)
672
+ return math.sqrt(2.0 * math.log(t + 2) / (n + 1))
673
+
674
+ def _net(self, b: Action, s: ObsState) -> float:
675
+ """S(b | s) = Delta_hat(b | s) - lam c_hat(b) (eq. 14)."""
676
+ return self.predicted_gain(b, s) - self.cfg.lam * self.estimated_cost(b) / self._cost_scale
677
+
678
+ # ----------------------------------------------- predicted effects of a call
679
+ def _targets(self, a: Action, kind: str) -> Set[str]:
680
+ sem = self._sem[a]
681
+ decl = {"gain": sem.gain, "harm": sem.harm, "produce": sem.produces}[kind]
682
+ out = {k for k, x in decl.items() if x > 0}
683
+ if self.cfg.feedback:
684
+ out |= set(self.stats.observed_targets(a, kind))
685
+ if self.cfg.estimator == "raw" and kind in ("gain", "harm"):
686
+ for c in self.stats.observed_targets(a, "raw"):
687
+ m = self.stats.rate(a, "raw", c)[1]
688
+ if (m > 0) == (kind == "gain"):
689
+ out.add(c)
690
+ return out
691
+
692
+ def _effect_probs(self, a: Action, state: ObsState):
693
+ """Independent predicted effects of ``a``: list of (kind, key, prob)."""
694
+ effects = []
695
+ gains = set()
696
+ for c in self._targets(a, "gain"):
697
+ vi = state.v.get(c, 0.0)
698
+ if vi < SAT_THRESHOLD:
699
+ if self.cfg.estimator == "raw":
700
+ d = self.predicted_effect_single(a, state, c)
701
+ g = max(0.0, d) / (1.0 - vi)
702
+ else:
703
+ g = self._rate(a, "gain", c)
704
+ if g > 0:
705
+ effects.append(("gain", c, min(1.0, g)))
706
+ gains.add(c)
707
+ for p in self._targets(a, "produce"):
708
+ if not state.predicates.get(p, False):
709
+ q = self._rate(a, "produce", p)
710
+ if q > 0:
711
+ effects.append(("produce", p, min(1.0, q)))
712
+ for c in self._targets(a, "harm"):
713
+ vi = state.v.get(c, 0.0)
714
+ if vi > 0 and c not in gains:
715
+ if self.cfg.estimator == "raw":
716
+ d = self.predicted_effect_single(a, state, c)
717
+ h = max(0.0, -d) / vi
718
+ else:
719
+ h = self._rate(a, "harm", c)
720
+ if h > 0:
721
+ effects.append(("harm", c, min(1.0, h)))
722
+ return effects
723
+
724
+ def predicted_effect_single(self, a: Action, state: ObsState, c: str) -> float:
725
+ return self.predicted_effect(a, state)[c]
726
+
727
+ @staticmethod
728
+ def _apply(state: ObsState, effects, realised, harm_expected: bool = False) -> ObsState:
729
+ s2 = state.copy()
730
+ for (kind, key, prob), r in zip(effects, realised):
731
+ if kind == "gain" and r:
732
+ s2.v[key] = 1.0
733
+ elif kind == "produce" and r:
734
+ s2.predicates[key] = True
735
+ elif kind == "harm":
736
+ if harm_expected:
737
+ s2.v[key] = state.v.get(key, 0.0) * (1.0 - prob)
738
+ elif r:
739
+ s2.v[key] = 0.0
740
+ return s2
741
+
742
+ # ----------------------------------------- continuation: eq. (15)-(17)
743
+ def _dependents(self, changed_conds: Iterable[str], changed_preds: Iterable[str]) -> Set[Action]:
744
+ """Calls whose admissibility or predicted value can change with these keys."""
745
+ out: Set[Action] = set()
746
+ for c in changed_conds:
747
+ out.update(self._needs_cond.get(c, ()))
748
+ out.update(self._deps.get(c, ()))
749
+ for p in changed_preds:
750
+ out.update(self._needs_pred.get(p, ()))
751
+ return out
752
+
753
+ def _best_after(self, s2: ObsState, changed_conds, changed_preds) -> float:
754
+ """max{0, max_{b in A(s2), affordable} S(b | s2)}, reusing S(b | z_t) for unaffected b."""
755
+ affected = self._dependents(changed_conds, changed_preds)
756
+ best = 0.0
757
+ for val, b in self._S_sorted: # descending
758
+ if val <= best:
759
+ break
760
+ if b in affected:
761
+ continue
762
+ if self._cost[b] <= s2.budget:
763
+ best = val
764
+ break
765
+ for b in affected:
766
+ if self._cost.get(b, self.estimated_cost(b)) > s2.budget or not self._admissible(b, s2):
767
+ continue
768
+ val = self._net(b, s2)
769
+ if val > best:
770
+ best = val
771
+ return best
772
+
773
+ def _cont_eq16(self, a: Action, state: ObsState) -> float:
774
+ effects = self._effect_probs(a, state)
775
+ s2 = self._apply(state, effects, [True] * len(effects), harm_expected=True)
776
+ s2.budget = state.budget - self._cost[a]
777
+ changed_c = [k for kind, k, _ in effects if kind in ("gain", "harm")]
778
+ changed_p = [k for kind, k, _ in effects if kind == "produce"]
779
+ return self._best_after(s2, changed_c, changed_p)
780
+
781
+ def _cont_eq17(self, a: Action, state: ObsState) -> float:
782
+ effects = self._effect_probs(a, state)
783
+ if len(effects) > MAX_ENUM_EFFECTS: # keep the most uncertain, fix the rest at their mode
784
+ effects.sort(key=lambda e: abs(e[2] - 0.5))
785
+ fixed, effects = effects[MAX_ENUM_EFFECTS:], effects[:MAX_ENUM_EFFECTS]
786
+ state = self._apply(state, fixed, [e[2] >= 0.5 for e in fixed])
787
+ budget2 = state.budget - self._cost[a]
788
+ total = 0.0
789
+ for realised in itertools.product((True, False), repeat=len(effects)):
790
+ prob = 1.0
791
+ for (kind, key, q), r in zip(effects, realised):
792
+ prob *= q if r else (1.0 - q)
793
+ if prob <= 0:
794
+ continue
795
+ s2 = self._apply(state, effects, realised)
796
+ s2.budget = budget2
797
+ changed_c = [k for (kind, k, _), r in zip(effects, realised) if r and kind in ("gain", "harm")]
798
+ changed_p = [k for (kind, k, _), r in zip(effects, realised) if r and kind == "produce"]
799
+ total += prob * self._best_after(s2, changed_c, changed_p)
800
+ return total
801
+
802
+ # unlock-form (earlier specification, eq. 7)
803
+ def _success_state(self, a: Action, state: ObsState):
804
+ s2 = state.copy()
805
+ p_pred: Dict[str, float] = {}
806
+ p_cond: Dict[str, float] = {}
807
+ harmed: List[str] = []
808
+ for kind, key, q in self._effect_probs(a, state):
809
+ if kind == "produce":
810
+ s2.predicates[key] = True
811
+ p_pred[key] = q
812
+ elif kind == "gain":
813
+ s2.v[key] = 1.0
814
+ p_cond[key] = q
815
+ elif kind == "harm" and self.cfg.corrective:
816
+ s2.v[key] = state.v.get(key, 0.0) * (1.0 - q)
817
+ harmed.append(key)
818
+ s2.budget = state.budget - self.estimated_cost(a)
819
+ s2.step = state.step + 1
820
+ return s2, p_pred, p_cond, harmed
821
+
822
+ def continuation(self, a: Action, state: ObsState, depth: int) -> float:
823
+ """Unlock form: max_{b in Next(a)} P(unlock b | a) [S(b | a)]_+ (+ repairs)."""
824
+ if depth <= 0:
825
+ return 0.0
826
+ s2, p_pred, p_cond, harmed = self._success_state(a, state)
827
+ if not p_pred and not p_cond and not harmed:
828
+ return 0.0
829
+ unlock = set()
830
+ for p in p_pred:
831
+ unlock.update(self._needs_pred.get(p, ()))
832
+ for c in p_cond:
833
+ unlock.update(self._needs_cond.get(c, ()))
834
+ best = 0.0
835
+ for b in unlock:
836
+ if b == a or self._admissible(b, state) or not self._admissible(b, s2):
837
+ continue
838
+ if self.estimated_cost(b) > s2.budget:
839
+ continue
840
+ req = self._req[b]
841
+ prob = 1.0
842
+ for p in req.requires_predicates:
843
+ if p in p_pred:
844
+ prob *= p_pred[p]
845
+ for c in req.requires_conditions:
846
+ if c in p_cond:
847
+ prob *= p_cond[c]
848
+ val = self._net(b, s2)
849
+ if depth > 1:
850
+ val += self.cfg.gamma * max(0.0, self.continuation(b, s2, depth - 1))
851
+ best = max(best, prob * max(0.0, val))
852
+ if harmed:
853
+ repairs = set()
854
+ for c in harmed:
855
+ repairs.update(self._gainers.get(c, ()))
856
+ for b in repairs:
857
+ if b == a or not self._admissible(b, s2) or self.estimated_cost(b) > s2.budget:
858
+ continue
859
+ now = max(0.0, self._net(b, state)) if self._admissible(b, state) else 0.0
860
+ best = max(best, max(0.0, self._net(b, s2)) - now)
861
+ return best
862
+
863
+ # -------------------------------------------------------------- scoring
864
+ def _begin_step(self, actions: List[Action], state: ObsState) -> None:
865
+ """Per-step caches: costs, S(b | z_t), and which conditions each b depends on."""
866
+ self._cost = {a: self.estimated_cost(a) for a in self.candidates}
867
+ self._S = {a: self._net(a, state) for a in actions}
868
+ self._S_sorted = sorted(((v, a) for a, v in self._S.items()), key=lambda x: -x[0])
869
+ deps: Dict[str, Set[Action]] = {}
870
+ if self.cfg.lookahead in ("eq16", "eq17"):
871
+ for b in self.candidates:
872
+ for c in self._targets(b, "gain") | self._targets(b, "harm"):
873
+ deps.setdefault(c, set()).add(b)
874
+ if self.cfg.estimator == "raw":
875
+ sem = self._sem[b]
876
+ for c in set(sem.gain) | set(sem.harm):
877
+ deps.setdefault(c, set()).add(b)
878
+ self._deps = deps
879
+
880
+ def score(self, a: Action, state: ObsState) -> Dict[str, float]:
881
+ gain = self.predicted_gain(a, state)
882
+ cost = self._cost[a] if hasattr(self, "_cost") and a in self._cost else self.estimated_cost(a)
883
+ immediate = gain - self.cfg.lam * cost / self._cost_scale # S_t(a), eq. (14)
884
+ la = self.cfg.lookahead
885
+ if la == "none" or (la == "unlock" and self.cfg.lookahead_depth <= 0):
886
+ cont = 0.0
887
+ elif la == "unlock":
888
+ cont = self.continuation(a, state, self.cfg.lookahead_depth)
889
+ elif la == "eq16":
890
+ cont = self._cont_eq16(a, state)
891
+ else:
892
+ cont = self._cont_eq17(a, state)
893
+ exploit = immediate + self.cfg.gamma * max(0.0, cont) # eq. (16)/(18)
894
+ unc = self.uncertainty(a, state.step) if self.cfg.beta > 0 else 0.0
895
+ q = exploit + self.cfg.beta * unc
896
+ if self.cfg.objective == "ratio":
897
+ rank = (gain + self.cfg.gamma * max(0.0, cont)) / max(cost, 1e-9)
898
+ else:
899
+ rank = q
900
+ return {"Q": q, "rank": rank, "exploit": exploit, "gain": gain, "cost": cost,
901
+ "bonus": unc, "continuation": cont}
902
+
src/fgao/estimator.py ADDED
@@ -0,0 +1,162 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Training-free online action-effect estimator (Sections 3 and the final correction).
2
+
3
+ Equation (3) blends a semantic prior with the empirical effect of comparable past
4
+ executions using rho = nu / (nu + n) (eq. 4). Two refinements are made so that
5
+ past executions are "meaningfully comparable" (the correction at the end of the
6
+ specification):
7
+
8
+ 1. **Comparability rule.** ``similarity="exact"`` (default) pools only executions
9
+ with the identical signature (tool + arguments). ``similarity="type"`` pools by
10
+ tool name, i.e. the original action-type average k(a); it is kept for ablation.
11
+ ``similarity="task"`` uses comparability classes declared by the task
12
+ (``Task.comparability_key``): the "carefully specified similarity rule"
13
+ that the specification allows.
14
+
15
+ ``rate(action, "raw", c)`` additionally returns the plain average of raw
16
+ deltas v_i(t+1) - v_i(t), which is the literal empirical term of eq. (12) of
17
+ the derivation; FGAOConfig(estimator="raw") uses it for comparison.
18
+
19
+ 2. **State-conditioning.** The raw change v_i(t+1) - v_i(t) depends on the current
20
+ value v_i(t): an action cannot add progress to a condition that is already
21
+ satisfied. We therefore estimate *rates* rather than raw deltas:
22
+
23
+ gain rate g_i = E[ max(dv_i, 0) / (1 - v_i) ] observed when v_i < 1
24
+ harm rate h_i = E[ max(-dv_i, 0) / v_i ] observed when v_i > 0
25
+
26
+ and predict delta_i(a) = (1 - v_i) g_i(a) - v_i h_i(a). Each rate is blended
27
+ by eq. (3)/(4) with its own comparable-observation count. For binary
28
+ conditions g_i is the success probability and h_i the probability of undoing
29
+ it, which is exactly what the semantic prior declares.
30
+
31
+ The same machinery estimates the probability that an action makes an observable
32
+ predicate true (used by the lookahead) and the expected execution cost.
33
+ """
34
+ from __future__ import annotations
35
+
36
+ from collections import defaultdict
37
+ from dataclasses import dataclass, field
38
+ from typing import Dict, Hashable, Mapping, Tuple
39
+
40
+ from .types import Action
41
+
42
+ _EPS = 1e-12
43
+
44
+
45
+ @dataclass
46
+ class _Running:
47
+ n: int = 0
48
+ total: float = 0.0
49
+
50
+ def add(self, x: float) -> None:
51
+ self.n += 1
52
+ self.total += x
53
+
54
+ @property
55
+ def mean(self) -> float:
56
+ return self.total / self.n if self.n else 0.0
57
+
58
+
59
+ @dataclass
60
+ class _KeyStats:
61
+ executions: int = 0
62
+ cost: _Running = field(default_factory=_Running)
63
+ gain: Dict[str, _Running] = field(default_factory=lambda: defaultdict(_Running))
64
+ harm: Dict[str, _Running] = field(default_factory=lambda: defaultdict(_Running))
65
+ produce: Dict[str, _Running] = field(default_factory=lambda: defaultdict(_Running))
66
+ raw: Dict[str, _Running] = field(default_factory=lambda: defaultdict(_Running))
67
+
68
+
69
+ class EffectStatistics:
70
+ """Online record of executed actions keyed by the comparability rule."""
71
+
72
+ def __init__(self, similarity: str = "exact", key_fn=None) -> None:
73
+ if similarity not in ("exact", "type", "task"):
74
+ raise ValueError("similarity must be 'exact', 'type' or 'task'")
75
+ if similarity == "task" and key_fn is None:
76
+ raise ValueError("similarity='task' needs the task's comparability_key")
77
+ self.similarity = similarity
78
+ self.key_fn = key_fn
79
+ self._stats: Dict[Hashable, _KeyStats] = defaultdict(_KeyStats)
80
+
81
+ # ----------------------------------------------------------------- keys
82
+ def key(self, action: Action) -> Hashable:
83
+ if self.similarity == "task":
84
+ return self.key_fn(action) # declared comparability class
85
+ return action.signature if self.similarity == "exact" else action.tool
86
+
87
+ # --------------------------------------------------------------- update
88
+ def update(
89
+ self,
90
+ action: Action,
91
+ v_before: Mapping[str, float],
92
+ v_after: Mapping[str, float],
93
+ pred_before: Mapping[str, bool],
94
+ pred_after: Mapping[str, bool],
95
+ cost: float,
96
+ ) -> None:
97
+ s = self._stats[self.key(action)]
98
+ s.executions += 1
99
+ s.cost.add(float(cost))
100
+ for c, vb in v_before.items():
101
+ va = v_after.get(c, vb)
102
+ d = va - vb
103
+ s.raw[c].add(d) # raw observed delta, eq. (19), for the literal eq. (12)
104
+ if vb < 1.0 - _EPS:
105
+ s.gain[c].add(max(d, 0.0) / (1.0 - vb))
106
+ if vb > _EPS:
107
+ s.harm[c].add(max(-d, 0.0) / vb)
108
+ for p, pb in pred_before.items():
109
+ if not pb:
110
+ s.produce[p].add(1.0 if pred_after.get(p, False) else 0.0)
111
+
112
+ def add_gain_observation(self, action: Action, cond: str, v_before: float, v_after: float) -> None:
113
+ """Delayed credit: the outcome of ``action`` on ``cond`` is only revealed by a later check."""
114
+ if v_before < 1.0 - _EPS:
115
+ self._stats[self.key(action)].gain[cond].add(max(v_after - v_before, 0.0) / (1.0 - v_before))
116
+
117
+ # -------------------------------------------------------------- queries
118
+ def executions(self, action: Action) -> int:
119
+ k = self.key(action)
120
+ return self._stats[k].executions if k in self._stats else 0
121
+
122
+ def _get(self, action: Action):
123
+ return self._stats.get(self.key(action))
124
+
125
+ def rate(self, action: Action, kind: str, target: str) -> Tuple[int, float]:
126
+ s = self._get(action)
127
+ if s is None:
128
+ return 0, 0.0
129
+ table = {"gain": s.gain, "harm": s.harm, "produce": s.produce, "raw": s.raw}[kind]
130
+ r = table.get(target)
131
+ if r is None:
132
+ return 0, 0.0
133
+ return r.n, r.mean
134
+
135
+ def observed_targets(self, action: Action, kind: str):
136
+ s = self._get(action)
137
+ if s is None:
138
+ return ()
139
+ table = {"gain": s.gain, "harm": s.harm, "produce": s.produce, "raw": s.raw}[kind]
140
+ if kind == "raw":
141
+ return tuple(c for c, r in table.items() if r.n and r.total != 0)
142
+ return tuple(c for c, r in table.items() if r.n and r.total > 0)
143
+
144
+ def mean_cost(self, action: Action) -> Tuple[int, float]:
145
+ s = self._get(action)
146
+ if s is None:
147
+ return 0, 0.0
148
+ return s.cost.n, s.cost.mean
149
+
150
+
151
+ def blend(prior: float, empirical: float, n: int, nu: float) -> float:
152
+ """Eq. (3) with eq. (4): rho * prior + (1 - rho) * empirical, rho = nu/(nu+n).
153
+
154
+ nu = inf (or feedback disabled) returns the prior; nu = 0 with n > 0 returns
155
+ the empirical mean.
156
+ """
157
+ if n <= 0:
158
+ return prior
159
+ if nu == float("inf"):
160
+ return prior
161
+ rho = nu / (nu + n)
162
+ return rho * prior + (1.0 - rho) * empirical
src/fgao/integrations/__init__.py ADDED
@@ -0,0 +1,4 @@
 
 
 
 
 
1
+ """Optional adapters: LangChain, LangGraph, Hugging Face, OpenAI-compatible and Anthropic.
2
+
3
+ Import the submodule you need; each imports its third-party dependency lazily.
4
+ """
src/fgao/integrations/huggingface.py ADDED
@@ -0,0 +1,143 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Hugging Face components (install ``fgao[huggingface]``; ``transformers`` for local models).
2
+
3
+ * ``HFInferenceLLM`` chat model behind the Hugging Face Inference API / Providers
4
+ * ``TransformersLLM`` local ``transformers`` text-generation model
5
+ * ``hf_embedder`` embedding function for ``DenseRetriever`` (Inference API)
6
+ * ``st_embedder`` embedding function from a local ``sentence-transformers`` model
7
+ * ``load_hf_corpus`` documents from a Hugging Face dataset
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import os
12
+ from typing import Any, Callable, List, Optional
13
+
14
+ from ..rag.documents import Document
15
+ from ..rag.prompts import SYSTEM_PROMPT
16
+
17
+
18
+ class HFInferenceLLM:
19
+ """``huggingface_hub`` chat completion (Inference API / Providers / a TGI endpoint) as an FGAO LLM.
20
+
21
+ Sync calls use ``InferenceClient``, async calls ``AsyncInferenceClient``.
22
+ The token defaults to ``HF_TOKEN``. ``temperature=None`` leaves the
23
+ provider default; set ``temperature=0`` where the provider accepts it for
24
+ deterministic calls. ``base_url`` targets a dedicated endpoint.
25
+ """
26
+
27
+ def __init__(self, model: str, *, token: Optional[str] = None, provider: Optional[str] = None,
28
+ base_url: Optional[str] = None, max_tokens: int = 128, temperature: Optional[float] = None,
29
+ system: Optional[str] = SYSTEM_PROMPT, timeout: Optional[float] = None, client: Any = None,
30
+ aclient: Any = None, **kwargs: Any) -> None:
31
+ self.model = model
32
+ self._ckw: dict = {"token": token or os.environ.get("HF_TOKEN")}
33
+ for k, v in (("provider", provider), ("base_url", base_url), ("timeout", timeout)):
34
+ if v is not None:
35
+ self._ckw[k] = v
36
+ self._client, self._aclient = client, aclient
37
+ self.max_tokens, self.temperature, self.system, self.kwargs = max_tokens, temperature, system, kwargs
38
+
39
+ @property
40
+ def client(self):
41
+ if self._client is None:
42
+ from huggingface_hub import InferenceClient
43
+
44
+ self._client = InferenceClient(**self._ckw)
45
+ return self._client
46
+
47
+ @property
48
+ def aclient(self):
49
+ if self._aclient is None:
50
+ from huggingface_hub import AsyncInferenceClient
51
+
52
+ self._aclient = AsyncInferenceClient(**self._ckw)
53
+ return self._aclient
54
+
55
+ def _args(self, prompt: str) -> dict:
56
+ messages = ([{"role": "system", "content": self.system}] if self.system else []) + [
57
+ {"role": "user", "content": prompt}]
58
+ kw = dict(self.kwargs)
59
+ if self.temperature is not None:
60
+ kw["temperature"] = self.temperature
61
+ kw.update(messages=messages, max_tokens=self.max_tokens)
62
+ if "base_url" not in self._ckw:
63
+ kw["model"] = self.model
64
+ return kw
65
+
66
+ def complete(self, prompt: str) -> str:
67
+ out = self.client.chat_completion(**self._args(prompt))
68
+ return (out.choices[0].message.content or "").strip()
69
+
70
+ async def acomplete(self, prompt: str) -> str:
71
+ out = await self.aclient.chat_completion(**self._args(prompt))
72
+ return (out.choices[0].message.content or "").strip()
73
+
74
+
75
+ class TransformersLLM:
76
+ """A local ``transformers`` model (greedy decoding, chat template when available)."""
77
+
78
+ def __init__(self, model: Any, *, max_new_tokens: int = 64, system: Optional[str] = SYSTEM_PROMPT,
79
+ **pipeline_kwargs: Any) -> None:
80
+ if isinstance(model, str):
81
+ from transformers import pipeline
82
+
83
+ model = pipeline("text-generation", model=model, **pipeline_kwargs)
84
+ self.pipe, self.max_new_tokens, self.system = model, max_new_tokens, system
85
+
86
+ def complete(self, prompt: str) -> str:
87
+ tok = getattr(self.pipe, "tokenizer", None)
88
+ if tok is not None and getattr(tok, "chat_template", None):
89
+ msgs = ([{"role": "system", "content": self.system}] if self.system else []) + [
90
+ {"role": "user", "content": prompt}]
91
+ out = self.pipe(msgs, max_new_tokens=self.max_new_tokens, do_sample=False)
92
+ gen = out[0]["generated_text"]
93
+ return (gen[-1]["content"] if isinstance(gen, list) else str(gen)).strip()
94
+ out = self.pipe(prompt, max_new_tokens=self.max_new_tokens, do_sample=False, return_full_text=False)
95
+ return out[0]["generated_text"].strip()
96
+
97
+
98
+ def hf_embedder(model: str, *, token: Optional[str] = None, client: Any = None) -> Callable[[List[str]], List[List[float]]]:
99
+ """Embedding function backed by ``InferenceClient.feature_extraction``."""
100
+ if client is None:
101
+ from huggingface_hub import InferenceClient
102
+
103
+ client = InferenceClient(token=token or os.environ.get("HF_TOKEN"))
104
+
105
+ def embed(texts: List[str]) -> List[List[float]]:
106
+ rows = []
107
+ for t in texts:
108
+ v = client.feature_extraction(t, model=model)
109
+ v = v.tolist() if hasattr(v, "tolist") else v
110
+ while isinstance(v, list) and v and isinstance(v[0], list) and len(v) == 1:
111
+ v = v[0]
112
+ if v and isinstance(v[0], list): # token embeddings: mean-pool
113
+ v = [sum(col) / len(v) for col in zip(*v)]
114
+ rows.append([float(x) for x in v])
115
+ return rows
116
+
117
+ return embed
118
+
119
+
120
+ def st_embedder(model: str, **kwargs: Any) -> Callable[[List[str]], Any]:
121
+ """Embedding function from a local ``sentence-transformers`` model."""
122
+ from sentence_transformers import SentenceTransformer
123
+
124
+ m = SentenceTransformer(model, **kwargs)
125
+ return lambda texts: m.encode(list(texts), normalize_embeddings=True)
126
+
127
+
128
+ def load_hf_corpus(path: str, *, split: str = "train", text_field: str = "text", title_field: Optional[str] = None,
129
+ id_field: Optional[str] = None, limit: Optional[int] = None, **kwargs: Any) -> List[Document]:
130
+ """Documents from a Hugging Face dataset (``datasets.load_dataset``)."""
131
+ from datasets import load_dataset
132
+
133
+ ds = load_dataset(path, split=split, **kwargs)
134
+ out: List[Document] = []
135
+ for i, row in enumerate(ds):
136
+ if limit is not None and i >= limit:
137
+ break
138
+ out.append(Document(text=str(row[text_field]), title=str(row[title_field]) if title_field else "",
139
+ id=str(row[id_field]) if id_field else str(i)))
140
+ return out
141
+
142
+
143
+ __all__ = ["HFInferenceLLM", "TransformersLLM", "hf_embedder", "st_embedder", "load_hf_corpus"]
src/fgao/integrations/langchain.py ADDED
@@ -0,0 +1,152 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """LangChain interop (requires ``langchain-core``; install ``fgao[langchain]``).
2
+
3
+ * ``LangChainLLM(model)`` any chat model / LLM with ``.invoke`` as an FGAO LLM
4
+ * ``LangChainRetriever(r)`` any retriever (``.invoke``) or vector store (``.similarity_search``)
5
+ * ``rag.as_runnable()`` FGAORAG as an LCEL Runnable (``|``, ``.batch``, ``.ainvoke``, ...)
6
+ * ``rag.as_tool()`` FGAORAG as a tool for LangChain / LangGraph agents
7
+ * ``workflow_runnable(app)`` any compiled FGAO Workflow as a Runnable
8
+
9
+ ``LangChainLLM`` and ``LangChainRetriever`` only duck-type, so they work
10
+ without importing LangChain.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from typing import Any, Dict, List, Optional
15
+
16
+ from ..rag.documents import Document, as_document
17
+
18
+
19
+ def _text(out: Any) -> str:
20
+ content = getattr(out, "content", out)
21
+ if isinstance(content, list): # content blocks
22
+ parts = []
23
+ for b in content:
24
+ if isinstance(b, str):
25
+ parts.append(b)
26
+ elif isinstance(b, dict) and b.get("type") == "text":
27
+ parts.append(b.get("text", ""))
28
+ elif hasattr(b, "text"):
29
+ parts.append(getattr(b, "text"))
30
+ return "".join(parts)
31
+ return str(content)
32
+
33
+
34
+ class LangChainLLM:
35
+ """Adapter: ``complete(prompt)`` -> ``model.invoke(prompt)`` text."""
36
+
37
+ def __init__(self, model: Any) -> None:
38
+ self.model = model
39
+
40
+ def complete(self, prompt: str) -> str:
41
+ return _text(self.model.invoke(prompt))
42
+
43
+ async def acomplete(self, prompt: str) -> str:
44
+ return _text(await self.model.ainvoke(prompt))
45
+
46
+
47
+ class LangChainRetriever:
48
+ """Adapter for LangChain retrievers and vector stores.
49
+
50
+ Vector stores are queried with ``similarity_search(query, k=k)``. A
51
+ retriever returns its own number of documents; the first ``k`` are kept,
52
+ so configure it to return at least the largest ``k`` you use (10 for the
53
+ default source layout).
54
+ """
55
+
56
+ def __init__(self, obj: Any, search_kwargs: Optional[Dict[str, Any]] = None) -> None:
57
+ self.obj = obj
58
+ self.search_kwargs = dict(search_kwargs or {})
59
+
60
+ def retrieve(self, query: str, k: int) -> List[Document]:
61
+ if hasattr(self.obj, "similarity_search"):
62
+ docs = self.obj.similarity_search(query, k=k, **self.search_kwargs)
63
+ else:
64
+ docs = self.obj.invoke(query, **self.search_kwargs) if self.search_kwargs else self.obj.invoke(query)
65
+ return [as_document(d) for d in list(docs)[:k]]
66
+
67
+ async def aretrieve(self, query: str, k: int) -> List[Document]:
68
+ if hasattr(self.obj, "asimilarity_search"):
69
+ docs = await self.obj.asimilarity_search(query, k=k, **self.search_kwargs)
70
+ elif hasattr(self.obj, "ainvoke"):
71
+ docs = await (self.obj.ainvoke(query, **self.search_kwargs) if self.search_kwargs else self.obj.ainvoke(query))
72
+ else:
73
+ import asyncio
74
+
75
+ return await asyncio.to_thread(self.retrieve, query, k)
76
+ return [as_document(d) for d in list(docs)[:k]]
77
+
78
+
79
+ def _require():
80
+ try:
81
+ import langchain_core # noqa: F401
82
+ except ImportError as e: # pragma: no cover
83
+ raise ImportError("this needs langchain-core: pip install 'fgao[langchain]'") from e
84
+
85
+
86
+ def rag_runnable(rag):
87
+ """FGAORAG as a ``RunnableLambda`` (sync + async)."""
88
+ _require()
89
+ from langchain_core.runnables import RunnableLambda
90
+
91
+ def run(x):
92
+ return rag.invoke(x).to_dict()
93
+
94
+ async def arun(x):
95
+ return (await rag.ainvoke(x)).to_dict()
96
+
97
+ return RunnableLambda(run, afunc=arun, name="FGAORAG")
98
+
99
+
100
+ def rag_tool(rag, name: str = "fgao_rag", description: Optional[str] = None):
101
+ """FGAORAG as a ``StructuredTool`` taking ``question: str``."""
102
+ _require()
103
+ from langchain_core.tools import StructuredTool
104
+
105
+ desc = description or ("Answer a factual question from the configured document sources. Returns the "
106
+ "answer only when it is grounded in a passage and passes a support check; "
107
+ "otherwise reports that no verified answer was found.")
108
+
109
+ def answer(question: str) -> Dict[str, Any]:
110
+ r = rag.invoke(question)
111
+ return {
112
+ "answer": r.answer,
113
+ "abstained": r.abstained,
114
+ "evidence": r.support_passage.text if r.support_passage else None,
115
+ "status": r.status,
116
+ }
117
+
118
+ async def aanswer(question: str) -> Dict[str, Any]:
119
+ r = await rag.ainvoke(question)
120
+ return {"answer": r.answer, "abstained": r.abstained,
121
+ "evidence": r.support_passage.text if r.support_passage else None, "status": r.status}
122
+
123
+ return StructuredTool.from_function(func=answer, coroutine=aanswer, name=name, description=desc)
124
+
125
+
126
+ def add_langchain_tool(wf, tool, *, inputs, output, name: Optional[str] = None, **declared):
127
+ """Register a LangChain tool (``BaseTool`` / ``@tool``) as an FGAO workflow tool.
128
+
129
+ inputs(state) -> the tool input (dict or str); output(state, result) -> state update.
130
+ Sync and async calls use ``tool.invoke`` / ``tool.ainvoke``.
131
+ """
132
+ from ..workflow import ToolResult
133
+
134
+ def fn(state, **_):
135
+ return ToolResult(update=output(state, tool.invoke(inputs(state))))
136
+
137
+ async def afn(state, **_):
138
+ return ToolResult(update=output(state, await tool.ainvoke(inputs(state))))
139
+
140
+ return wf.add_tool(name or tool.name, fn, afn=afn, description=getattr(tool, "description", ""), **declared)
141
+
142
+
143
+ def workflow_runnable(app, *, seed: int = 0):
144
+ """A compiled ``Workflow`` as a Runnable: input state, output ``WorkflowResult``."""
145
+ _require()
146
+ from langchain_core.runnables import RunnableLambda
147
+
148
+ return RunnableLambda(lambda s: app.invoke(s, seed=seed),
149
+ afunc=lambda s: app.ainvoke(s, seed=seed), name=f"FGAO:{app.name}")
150
+
151
+
152
+ __all__ = ["LangChainLLM", "LangChainRetriever", "rag_runnable", "rag_tool", "workflow_runnable", "add_langchain_tool"]
src/fgao/integrations/langgraph.py ADDED
@@ -0,0 +1,50 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """LangGraph interop. Nodes are plain functions ``state -> partial update``, so
2
+ nothing here imports LangGraph.
3
+
4
+ from langgraph.graph import StateGraph, START, END
5
+ g = StateGraph(MyState)
6
+ g.add_node("rag", rag.as_node())
7
+ g.add_edge(START, "rag"); g.add_edge("rag", END)
8
+
9
+ ``workflow_node`` embeds any compiled FGAO ``Workflow`` as a LangGraph node:
10
+ FGAO orchestrates the tools inside the node, LangGraph routes around it.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ from typing import Any, Callable, Dict, Mapping, Optional
15
+
16
+
17
+ def rag_node(rag, *, question_key: str = "question", answer_key: str = "answer",
18
+ result_key: Optional[str] = "fgao") -> Callable[[Mapping[str, Any]], Dict[str, Any]]:
19
+ def node(state: Mapping[str, Any]) -> Dict[str, Any]:
20
+ r = rag.invoke(state[question_key])
21
+ out: Dict[str, Any] = {answer_key: r.answer}
22
+ if result_key:
23
+ out[result_key] = r.to_dict()
24
+ return out
25
+
26
+ node.__name__ = "fgao_rag"
27
+ return node
28
+
29
+
30
+ def workflow_node(app, *, input_key: Optional[str] = None, output_key: str = "fgao",
31
+ seed: int = 0) -> Callable[[Mapping[str, Any]], Dict[str, Any]]:
32
+ """Run a compiled Workflow on ``dict(state)`` (or ``state[input_key]``).
33
+
34
+ Returns the final workflow state's keys as the update (or, with
35
+ ``input_key``, ``{input_key: final_state}``), plus a summary under ``output_key``.
36
+ """
37
+
38
+ def node(state: Mapping[str, Any]) -> Dict[str, Any]:
39
+ inner = dict(state[input_key]) if input_key else dict(state)
40
+ r = app.invoke(inner, seed=seed)
41
+ upd: Dict[str, Any] = {input_key: r.state} if input_key else dict(r.state)
42
+ upd[output_key] = {"status": r.status, "success": r.success, "values": r.values, "cost": r.cost,
43
+ "trace": r.trace()}
44
+ return upd
45
+
46
+ node.__name__ = f"fgao_{app.name}"
47
+ return node
48
+
49
+
50
+ __all__ = ["rag_node", "workflow_node"]
src/fgao/integrations/mcp.py ADDED
@@ -0,0 +1,93 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """MCP (Model Context Protocol) tools as FGAO workflow tools.
2
+
3
+ Works with any client exposing ``await call_tool(name, arguments)`` and
4
+ ``await list_tools()``: ``mcp.Client`` (SDK 2.x) or ``mcp.ClientSession``
5
+ (SDK 1.x). FGAO decides *when* to call a tool from its declared effects; the
6
+ ``inputs`` function builds the call's arguments from the workflow state and
7
+ ``output`` turns the result into a state update.
8
+
9
+ from mcp import Client
10
+ from fgao import Workflow
11
+ from fgao.integrations.mcp import add_mcp_tool
12
+
13
+ async with Client("http://localhost:8000/mcp") as client:
14
+ wf = Workflow("ops")
15
+ wf.add_goal("ticket", lambda s: "ticket_id" in s)
16
+ add_mcp_tool(wf, client, "create_ticket", inputs=lambda s: {"title": s["title"]},
17
+ output=lambda s, r: {"ticket_id": r.data["id"]}, gain={"ticket": 0.9}, cost=1)
18
+ result = await wf.compile(budget=10).ainvoke({"title": "disk full"})
19
+
20
+ MCP calls are async, so these tools run through the async API
21
+ (``ainvoke`` / ``abatch`` / ``astream`` / ``Run.arun``).
22
+ """
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import dataclass, field
26
+ from typing import Any, Callable, Dict, List, Mapping, Optional
27
+
28
+ from ..types import Action
29
+ from ..workflow import ToolResult, Workflow
30
+
31
+
32
+ @dataclass
33
+ class MCPResult:
34
+ """Normalised tool result: concatenated text, structured content (if any), error flag."""
35
+
36
+ text: str
37
+ data: Any = None
38
+ is_error: bool = False
39
+ raw: Any = field(default=None, repr=False)
40
+
41
+ @classmethod
42
+ def of(cls, res: Any) -> "MCPResult":
43
+ content = getattr(res, "content", None) or []
44
+ text = "".join(getattr(b, "text", "") for b in content if getattr(b, "type", "text") == "text")
45
+ data = getattr(res, "structured_content", None)
46
+ if data is None:
47
+ data = getattr(res, "structuredContent", None)
48
+ err = getattr(res, "is_error", None)
49
+ if err is None:
50
+ err = getattr(res, "isError", False)
51
+ return cls(text=text, data=data, is_error=bool(err), raw=res)
52
+
53
+
54
+ async def list_mcp_tools(client: Any) -> List[Dict[str, Any]]:
55
+ """[{"name", "description", "input_schema"}] for every tool the server offers."""
56
+ res = await client.list_tools()
57
+ out = []
58
+ for t in getattr(res, "tools", res):
59
+ schema = getattr(t, "input_schema", None) or getattr(t, "inputSchema", None)
60
+ out.append({"name": t.name, "description": getattr(t, "description", "") or "", "input_schema": schema})
61
+ return out
62
+
63
+
64
+ def add_mcp_tool(
65
+ wf: Workflow,
66
+ client: Any,
67
+ tool: str,
68
+ *,
69
+ inputs: Callable[..., Mapping[str, Any]],
70
+ output: Callable[[Any, MCPResult], Optional[Mapping[str, Any]]],
71
+ name: Optional[str] = None,
72
+ args: Optional[Mapping[str, Any]] = None,
73
+ timeout: Optional[float] = None,
74
+ **declared: Any,
75
+ ) -> Action:
76
+ """Register MCP tool ``tool`` as an FGAO tool.
77
+
78
+ inputs(state, **args) -> the tool arguments; output(state, MCPResult) -> state update.
79
+ An MCP error result is recorded as a failed call (no update), so FGAO's feedback learns from it.
80
+ ``declared`` are the usual ``add_tool`` declarations (gain, harm, produces, requires, cost, group).
81
+ """
82
+
83
+ async def afn(state: Any, **kw: Any):
84
+ call_kw = {"read_timeout_seconds": timeout} if timeout is not None else {}
85
+ res = MCPResult.of(await client.call_tool(tool, dict(inputs(state, **kw)), **call_kw))
86
+ if res.is_error:
87
+ return ToolResult(error=f"MCP tool {tool} failed: {res.text[:300]}")
88
+ return ToolResult(update=output(state, res))
89
+
90
+ return wf.add_tool(name or tool, afn, args=args, **declared)
91
+
92
+
93
+ __all__ = ["add_mcp_tool", "list_mcp_tools", "MCPResult"]
src/fgao/integrations/providers.py ADDED
@@ -0,0 +1,98 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """OpenAI-compatible and Anthropic chat models as FGAO LLMs (sync and native async).
2
+
3
+ ``OpenAILLM`` also serves any OpenAI-compatible endpoint (vLLM, TGI, Ollama,
4
+ LM Studio, ...) through ``base_url``. Clients are created lazily, so a process
5
+ that only uses the async API never opens a sync client and vice versa.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ from typing import Any, Dict, List, Optional
10
+
11
+ from ..rag.prompts import SYSTEM_PROMPT
12
+
13
+
14
+ def _messages(system: Optional[str], prompt: str) -> List[Dict[str, str]]:
15
+ return ([{"role": "system", "content": system}] if system else []) + [{"role": "user", "content": prompt}]
16
+
17
+
18
+ class OpenAILLM:
19
+ def __init__(self, model: str, *, client: Any = None, aclient: Any = None, base_url: Optional[str] = None,
20
+ api_key: Optional[str] = None, max_tokens: int = 128, temperature: float = 0.0,
21
+ system: Optional[str] = SYSTEM_PROMPT, timeout: Optional[float] = None,
22
+ max_retries: Optional[int] = None) -> None:
23
+ self.model, self.max_tokens, self.temperature, self.system = model, max_tokens, temperature, system
24
+ self._kw = {k: v for k, v in (("base_url", base_url), ("api_key", api_key), ("timeout", timeout),
25
+ ("max_retries", max_retries)) if v is not None}
26
+ self._client, self._aclient = client, aclient
27
+
28
+ @property
29
+ def client(self):
30
+ if self._client is None:
31
+ from openai import OpenAI
32
+
33
+ self._client = OpenAI(**self._kw)
34
+ return self._client
35
+
36
+ @property
37
+ def aclient(self):
38
+ if self._aclient is None:
39
+ from openai import AsyncOpenAI
40
+
41
+ self._aclient = AsyncOpenAI(**self._kw)
42
+ return self._aclient
43
+
44
+ def _args(self, prompt: str) -> Dict[str, Any]:
45
+ return {"model": self.model, "messages": _messages(self.system, prompt), "max_tokens": self.max_tokens,
46
+ "temperature": self.temperature}
47
+
48
+ def complete(self, prompt: str) -> str:
49
+ out = self.client.chat.completions.create(**self._args(prompt))
50
+ return (out.choices[0].message.content or "").strip()
51
+
52
+ async def acomplete(self, prompt: str) -> str:
53
+ out = await self.aclient.chat.completions.create(**self._args(prompt))
54
+ return (out.choices[0].message.content or "").strip()
55
+
56
+
57
+ class AnthropicLLM:
58
+ def __init__(self, model: str, *, client: Any = None, aclient: Any = None, api_key: Optional[str] = None,
59
+ max_tokens: int = 128, temperature: float = 0.0, system: Optional[str] = SYSTEM_PROMPT,
60
+ timeout: Optional[float] = None, max_retries: Optional[int] = None) -> None:
61
+ self.model, self.max_tokens, self.temperature, self.system = model, max_tokens, temperature, system
62
+ self._kw = {k: v for k, v in (("api_key", api_key), ("timeout", timeout), ("max_retries", max_retries))
63
+ if v is not None}
64
+ self._client, self._aclient = client, aclient
65
+
66
+ @property
67
+ def client(self):
68
+ if self._client is None:
69
+ from anthropic import Anthropic
70
+
71
+ self._client = Anthropic(**self._kw)
72
+ return self._client
73
+
74
+ @property
75
+ def aclient(self):
76
+ if self._aclient is None:
77
+ from anthropic import AsyncAnthropic
78
+
79
+ self._aclient = AsyncAnthropic(**self._kw)
80
+ return self._aclient
81
+
82
+ def _args(self, prompt: str) -> Dict[str, Any]:
83
+ kw: Dict[str, Any] = {"model": self.model, "max_tokens": self.max_tokens, "temperature": self.temperature,
84
+ "messages": [{"role": "user", "content": prompt}]}
85
+ if self.system:
86
+ kw["system"] = self.system
87
+ return kw
88
+
89
+ def complete(self, prompt: str) -> str:
90
+ out = self.client.messages.create(**self._args(prompt))
91
+ return "".join(getattr(b, "text", "") for b in out.content).strip()
92
+
93
+ async def acomplete(self, prompt: str) -> str:
94
+ out = await self.aclient.messages.create(**self._args(prompt))
95
+ return "".join(getattr(b, "text", "") for b in out.content).strip()
96
+
97
+
98
+ __all__ = ["OpenAILLM", "AnthropicLLM"]
src/fgao/py.typed ADDED
File without changes
src/fgao/rag/__init__.py ADDED
@@ -0,0 +1,15 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """FGAO-orchestrated retrieval-augmented generation."""
2
+ from .components import LLMGenerator, LLMGrader, LLMRewriter, LLMSupportChecker
3
+ from .documents import Document, as_document, as_documents, contains_answer, normalize_answer
4
+ from .interfaces import LLM, Generator, Grader, Retriever, Rewriter, SupportChecker
5
+ from .llms import CachedLLM, FunctionLLM, as_llm
6
+ from .pipeline import FGAORAG, Costs, Priors, RAGEpisode, RAGResult, Source, Weights, default_sources
7
+ from .retrievers import BM25Retriever, DenseRetriever, FunctionRetriever, as_retriever
8
+
9
+ __all__ = [
10
+ "FGAORAG", "RAGResult", "RAGEpisode", "Source", "Costs", "Priors", "Weights", "default_sources",
11
+ "Document", "as_document", "as_documents", "contains_answer", "normalize_answer",
12
+ "LLM", "Retriever", "Generator", "Grader", "Rewriter", "SupportChecker",
13
+ "LLMGenerator", "LLMGrader", "LLMRewriter", "LLMSupportChecker",
14
+ "CachedLLM", "FunctionLLM", "as_llm", "BM25Retriever", "DenseRetriever", "FunctionRetriever", "as_retriever",
15
+ ]
src/fgao/rag/components.py ADDED
@@ -0,0 +1,76 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Default LLM-backed RAG operations (the evaluated v2 prompts and parsers)."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import inspect
6
+ from typing import Any, Callable, List, Optional, Sequence
7
+
8
+ from . import prompts as P
9
+ from .documents import Document
10
+ from .llms import acomplete, as_llm
11
+
12
+
13
+ class LLMGenerator:
14
+ """Extractive answer generation; returns '' to abstain."""
15
+
16
+ def __init__(self, llm: Any, prompt: Callable[[str, Sequence[Document]], str] = P.generate_prompt,
17
+ parse: Callable[[str], str] = P.parse_answer) -> None:
18
+ self.llm, self.prompt, self.parse = as_llm(llm), prompt, parse
19
+
20
+ def __call__(self, question: str, docs: Sequence[Document]) -> str:
21
+ return self.parse(self.llm.complete(self.prompt(question, docs)))
22
+
23
+ async def acall(self, question: str, docs: Sequence[Document]) -> str:
24
+ return self.parse(await acomplete(self.llm, self.prompt(question, docs)))
25
+
26
+
27
+ class LLMGrader:
28
+ """Relevance grading: one score in {0, 1, 2} per passage; passages scoring >= 1 are kept."""
29
+
30
+ def __init__(self, llm: Any, prompt: Callable[[str, Sequence[Document]], str] = P.grade_prompt,
31
+ parse: Callable[[str, int], List[int]] = P.parse_grades) -> None:
32
+ self.llm, self.prompt, self.parse = as_llm(llm), prompt, parse
33
+
34
+ def __call__(self, question: str, docs: Sequence[Document]) -> List[int]:
35
+ return self.parse(self.llm.complete(self.prompt(question, docs)), len(docs))
36
+
37
+ async def acall(self, question: str, docs: Sequence[Document]) -> List[int]:
38
+ return self.parse(await acomplete(self.llm, self.prompt(question, docs)), len(docs))
39
+
40
+
41
+ class LLMRewriter:
42
+ """Query rewriting for retrieval; '' keeps the original question."""
43
+
44
+ def __init__(self, llm: Any, prompt: Callable[[str], str] = P.rewrite_prompt,
45
+ parse: Callable[[str], str] = P.parse_query) -> None:
46
+ self.llm, self.prompt, self.parse = as_llm(llm), prompt, parse
47
+
48
+ def __call__(self, question: str) -> str:
49
+ return self.parse(self.llm.complete(self.prompt(question)))
50
+
51
+ async def acall(self, question: str) -> str:
52
+ return self.parse(await acomplete(self.llm, self.prompt(question)))
53
+
54
+
55
+ class LLMSupportChecker:
56
+ """Support check: does the passage that contains the answer support it?"""
57
+
58
+ def __init__(self, llm: Any, prompt: Callable[[str, Document, str], str] = P.verify_prompt,
59
+ parse: Callable[[str], bool] = P.parse_yes) -> None:
60
+ self.llm, self.prompt, self.parse = as_llm(llm), prompt, parse
61
+
62
+ def __call__(self, question: str, passage: Document, answer: str) -> bool:
63
+ return bool(self.parse(self.llm.complete(self.prompt(question, passage, answer))))
64
+
65
+ async def acall(self, question: str, passage: Document, answer: str) -> bool:
66
+ return bool(self.parse(await acomplete(self.llm, self.prompt(question, passage, answer))))
67
+
68
+
69
+ async def acall(fn: Any, *args: Any) -> Any:
70
+ """Call an operation natively async when it supports it, otherwise in a worker thread."""
71
+ a = getattr(fn, "acall", None)
72
+ if a is not None:
73
+ return await a(*args)
74
+ if inspect.iscoroutinefunction(fn) or inspect.iscoroutinefunction(getattr(fn, "__call__", None)):
75
+ return await fn(*args)
76
+ return await asyncio.to_thread(fn, *args)
src/fgao/rag/documents.py ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Documents and text utilities used by the RAG pipeline."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import re
6
+ import string
7
+ from dataclasses import dataclass, field
8
+ from typing import Any, Dict, List, Union
9
+
10
+
11
+ @dataclass
12
+ class Document:
13
+ """A retrieved passage."""
14
+
15
+ text: str
16
+ title: str = ""
17
+ id: str = ""
18
+ metadata: Dict[str, Any] = field(default_factory=dict)
19
+
20
+ def __post_init__(self) -> None:
21
+ if not self.id:
22
+ self.id = hashlib.sha1((self.title + "\x00" + self.text).encode("utf-8")).hexdigest()[:12]
23
+
24
+ def to_dict(self) -> Dict[str, Any]:
25
+ return {"id": self.id, "title": self.title, "text": self.text, "metadata": dict(self.metadata)}
26
+
27
+
28
+ DocLike = Union[Document, str, Dict[str, Any]]
29
+
30
+
31
+ def as_document(x: DocLike) -> Document:
32
+ if isinstance(x, Document):
33
+ return x
34
+ if isinstance(x, str):
35
+ return Document(text=x)
36
+ if isinstance(x, dict):
37
+ meta = {k: v for k, v in x.items() if k not in ("text", "title", "id", "page_content")}
38
+ return Document(text=x.get("text", x.get("page_content", "")), title=x.get("title", ""),
39
+ id=str(x.get("id", "")), metadata=meta)
40
+ # LangChain-style document
41
+ text = getattr(x, "page_content", None)
42
+ if text is not None:
43
+ meta = dict(getattr(x, "metadata", {}) or {})
44
+ return Document(text=text, title=str(meta.get("title", "")), id=str(meta.get("id", "") or getattr(x, "id", "") or ""),
45
+ metadata=meta)
46
+ raise TypeError(f"cannot convert {type(x).__name__} to Document")
47
+
48
+
49
+ def as_documents(xs) -> List[Document]:
50
+ return [as_document(x) for x in xs]
51
+
52
+
53
+ # ------------------------------------------------------------------ text utils
54
+ def normalize_answer(s: str) -> str:
55
+ """SQuAD normalisation: lower case, strip punctuation and articles, squeeze spaces."""
56
+ s = s.lower()
57
+ s = "".join(ch for ch in s if ch not in set(string.punctuation))
58
+ s = re.sub(r"\b(a|an|the)\b", " ", s)
59
+ return " ".join(s.split())
60
+
61
+
62
+ def contains_answer(passage: str, answer: str) -> bool:
63
+ """Grounding check: the normalised answer occurs in the normalised passage."""
64
+ a = normalize_answer(answer)
65
+ return bool(a) and a in normalize_answer(passage)
src/fgao/rag/interfaces.py ADDED
@@ -0,0 +1,35 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Pluggable interfaces. Any object with the right method (or a plain function) works.
2
+
3
+ | role | interface |
4
+ |-----------------|-------------------------------------------------------------|
5
+ | LLM | ``complete(prompt: str) -> str`` |
6
+ | Retriever | ``retrieve(query: str, k: int) -> list[Document]`` |
7
+ | Generator | ``(question, docs) -> str`` ('' means abstain) |
8
+ | Grader | ``(question, docs) -> list[int]`` (0, 1, 2 per passage) |
9
+ | Rewriter | ``(question) -> str`` (a search query; '' keeps the question)|
10
+ | SupportChecker | ``(question, passage, answer) -> bool`` |
11
+
12
+ LangChain chat models / retrievers / vector stores, Hugging Face clients, and
13
+ plain callables are converted automatically by ``as_llm`` / ``as_retriever``.
14
+ """
15
+ from __future__ import annotations
16
+
17
+ from typing import Callable, List, Protocol, Sequence, runtime_checkable
18
+
19
+ from .documents import Document
20
+
21
+
22
+ @runtime_checkable
23
+ class LLM(Protocol):
24
+ def complete(self, prompt: str) -> str: ...
25
+
26
+
27
+ @runtime_checkable
28
+ class Retriever(Protocol):
29
+ def retrieve(self, query: str, k: int) -> List[Document]: ...
30
+
31
+
32
+ Generator = Callable[[str, Sequence[Document]], str]
33
+ Grader = Callable[[str, Sequence[Document]], List[int]]
34
+ Rewriter = Callable[[str], str]
35
+ SupportChecker = Callable[[str, Document, str], bool]
src/fgao/rag/llms.py ADDED
@@ -0,0 +1,107 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Generic LLM wrappers and coercion."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import hashlib
6
+ import inspect
7
+ import json
8
+ import os
9
+ import threading
10
+ from typing import Any, Callable, Dict, Optional
11
+
12
+
13
+ async def acomplete(llm: Any, prompt: str) -> str:
14
+ """Native ``acomplete`` when the LLM has one, otherwise ``complete`` in a worker thread."""
15
+ fn = getattr(llm, "acomplete", None)
16
+ if fn is not None:
17
+ return await fn(prompt)
18
+ return await asyncio.to_thread(llm.complete, prompt)
19
+
20
+
21
+ class FunctionLLM:
22
+ """Wrap ``fn(prompt) -> str`` (or an ``async def`` function)."""
23
+
24
+ def __init__(self, fn: Callable[[str], Any]) -> None:
25
+ self.fn = fn
26
+ if inspect.iscoroutinefunction(fn):
27
+ self.acomplete = self._acomplete # type: ignore[assignment]
28
+
29
+ def complete(self, prompt: str) -> str:
30
+ if inspect.iscoroutinefunction(self.fn):
31
+ raise TypeError("this LLM is async-only; use the async API (ainvoke / abatch / astream)")
32
+ return str(self.fn(prompt))
33
+
34
+ async def _acomplete(self, prompt: str) -> str:
35
+ return str(await self.fn(prompt))
36
+
37
+
38
+ class CachedLLM:
39
+ """Thread-safe prompt -> response cache in front of any LLM.
40
+
41
+ With ``path`` the cache persists as JSON (written after every new
42
+ response). Useful for reproducible runs and to avoid paying twice for the
43
+ same deterministic call.
44
+ """
45
+
46
+ def __init__(self, llm: Any, path: Optional[str] = None) -> None:
47
+ self.llm = as_llm(llm)
48
+ self.path = path
49
+ self._lock = threading.Lock()
50
+ self.cache: Dict[str, Dict[str, str]] = {}
51
+ if path and os.path.exists(path):
52
+ with open(path, encoding="utf-8") as fh:
53
+ self.cache = json.load(fh)
54
+ self.hits = 0
55
+ self.misses = 0
56
+
57
+ @staticmethod
58
+ def key(prompt: str) -> str:
59
+ return hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:16]
60
+
61
+ def complete(self, prompt: str) -> str:
62
+ k = self.key(prompt)
63
+ with self._lock:
64
+ hit = self.cache.get(k)
65
+ if hit is not None:
66
+ self.hits += 1
67
+ return hit["response"]
68
+ response = self.llm.complete(prompt)
69
+ self._store(k, prompt, response)
70
+ return response
71
+
72
+ async def acomplete(self, prompt: str) -> str:
73
+ k = self.key(prompt)
74
+ with self._lock:
75
+ hit = self.cache.get(k)
76
+ if hit is not None:
77
+ self.hits += 1
78
+ return hit["response"]
79
+ response = await acomplete(self.llm, prompt)
80
+ self._store(k, prompt, response)
81
+ return response
82
+
83
+ def _store(self, k: str, prompt: str, response: str) -> None:
84
+ with self._lock:
85
+ self.misses += 1
86
+ self.cache[k] = {"prompt": prompt, "response": response}
87
+ if self.path:
88
+ tmp = self.path + ".tmp"
89
+ os.makedirs(os.path.dirname(os.path.abspath(self.path)), exist_ok=True)
90
+ with open(tmp, "w", encoding="utf-8") as fh:
91
+ json.dump(self.cache, fh, ensure_ascii=False)
92
+ os.replace(tmp, self.path)
93
+
94
+
95
+ def as_llm(x: Any):
96
+ """Accept an object with ``complete``, a LangChain model, or ``fn(prompt) -> str``."""
97
+ if x is None:
98
+ raise ValueError("an LLM is required")
99
+ if hasattr(x, "complete") and callable(getattr(x, "complete")):
100
+ return x
101
+ if hasattr(x, "invoke") and callable(getattr(x, "invoke")):
102
+ from ..integrations.langchain import LangChainLLM
103
+
104
+ return LangChainLLM(x)
105
+ if callable(x):
106
+ return FunctionLLM(x)
107
+ raise TypeError(f"cannot use {type(x).__name__} as an LLM: give .complete(prompt), .invoke(prompt) or a function")
src/fgao/rag/pipeline.py ADDED
@@ -0,0 +1,442 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """FGAO-orchestrated RAG (the evaluated v2 RAG policy).
2
+
3
+ Goals (mandatory, checked mechanically, never taken from the generator's claim)
4
+
5
+ answered (w 0.2) a non-abstaining answer exists
6
+ grounded (w 0.3) the normalised answer occurs in a passage it was generated from
7
+ supported (w 0.5) the support checker accepted the current answer, reading
8
+ the passage that contains it
9
+
10
+ Operations offered to the controller
11
+
12
+ answer(src, graded=False) retrieve from ``src`` (once per query, cached), generate
13
+ answer(src, graded=True) retrieve, grade relevance, generate from the kept passages
14
+ verify support check of the current answer
15
+
16
+ Each answer operation runs at most once per query (LLM calls are
17
+ deterministic, so repeating one cannot help); verify runs once per distinct
18
+ answer. Answer operations on sources of the same ``family`` share feedback:
19
+ when the KB variants keep failing, FGAO's estimate for all of them drops and it
20
+ escalates to the other family (e.g. web search).
21
+
22
+ Output: the answer only if all three goals are verified, otherwise an
23
+ abstention (``answer is None``); ``grounded_answer`` keeps the best grounded but
24
+ unverified answer for callers that prefer coverage.
25
+ """
26
+ from __future__ import annotations
27
+
28
+ import asyncio
29
+ from collections import Counter
30
+ from concurrent.futures import ThreadPoolExecutor
31
+ from dataclasses import dataclass, field
32
+ from typing import Any, AsyncIterator, Callable, Dict, Iterator, List, Optional, Sequence, Set, Tuple, Union
33
+
34
+ from ..controller import FGAOConfig
35
+ from ..workflow import CompiledWorkflow, Step, ToolResult, Workflow, WorkflowResult
36
+ from .components import LLMGenerator, LLMGrader, LLMRewriter, LLMSupportChecker, acall
37
+ from .documents import Document, contains_answer
38
+ from .llms import as_llm
39
+ from .retrievers import aretrieve, as_retriever
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class Costs:
44
+ """Declared operation costs (same units as the budget)."""
45
+
46
+ llm: float = 2.0
47
+ kb: float = 1.0
48
+ kb_deep: float = 1.5
49
+ web: float = 4.0
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class Priors:
54
+ """Declared effect priors of the evaluated v2 RAG task (fixed a priori, never tuned)."""
55
+
56
+ answer_answered: float = 0.8
57
+ answer_grounded: float = 0.7
58
+ graded_answered: float = 0.75
59
+ graded_grounded: float = 0.75
60
+ answer_harms_support: float = 0.9
61
+ answer_produces_unverified: float = 0.8
62
+ verify_supported: float = 0.8
63
+
64
+
65
+ @dataclass(frozen=True)
66
+ class Weights:
67
+ answered: float = 0.2
68
+ grounded: float = 0.3
69
+ supported: float = 0.5
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class Source:
74
+ """A retrieval source the controller may choose.
75
+
76
+ cost declared retrieval cost (for ``rewrite=True`` include the rewrite call)
77
+ family comparability group; sources of one family share feedback
78
+ rewrite rewrite the question into a search query before retrieving
79
+ """
80
+
81
+ name: str
82
+ retriever: Any
83
+ k: int = 5
84
+ cost: float = 1.0
85
+ family: str = "kb"
86
+ rewrite: bool = False
87
+
88
+
89
+ def default_sources(kb: Any, web: Any = None, costs: Costs = Costs()) -> List[Source]:
90
+ """The evaluated source layout: KB top-5, KB top-10, rewritten-query KB top-5, web top-5."""
91
+ kb = as_retriever(kb)
92
+ out = [
93
+ Source("kb5", kb, k=5, cost=costs.kb, family="kb"),
94
+ Source("kb10", kb, k=10, cost=costs.kb_deep, family="kb"),
95
+ Source("rw", kb, k=5, cost=costs.llm + costs.kb, family="kb", rewrite=True),
96
+ ]
97
+ if web is not None:
98
+ out.append(Source("web", as_retriever(web), k=5, cost=costs.web, family="web"))
99
+ return out
100
+
101
+
102
+ # =============================================================================
103
+ class RAGEpisode:
104
+ """Mutable per-query state the operations act on."""
105
+
106
+ def __init__(self, question: str) -> None:
107
+ self.question = question
108
+ self.docs: Dict[str, List[Document]] = {}
109
+ self.graded: Dict[str, List[Document]] = {}
110
+ self.answer: str = ""
111
+ self.answer_docs: List[Document] = []
112
+ self.supported = False
113
+ self.checked: Optional[str] = None # answer last sent to the support check
114
+ self.tried: Set[Tuple[str, str, int]] = set()
115
+ self.calls: Counter = Counter()
116
+ self.queries: Dict[str, str] = {}
117
+
118
+ def grounded(self) -> bool:
119
+ return bool(self.answer) and any(contains_answer(d.text, self.answer) for d in self.answer_docs)
120
+
121
+ def support_passage(self) -> Optional[Document]:
122
+ return next((d for d in self.answer_docs if contains_answer(d.text, self.answer)), None)
123
+
124
+
125
+ @dataclass
126
+ class RAGResult:
127
+ question: str
128
+ answer: Optional[str] # None = abstained
129
+ status: str
130
+ values: Dict[str, float]
131
+ grounded_answer: Optional[str]
132
+ evidence: List[Document]
133
+ support_passage: Optional[Document]
134
+ support: Optional[bool] # support-check result for the final answer; None if it was never checked
135
+ cost: float
136
+ calls: Dict[str, int]
137
+ steps: List[Step] = field(default_factory=list)
138
+ retrieved: Dict[str, List[Document]] = field(default_factory=dict)
139
+
140
+ @property
141
+ def abstained(self) -> bool:
142
+ return self.answer is None
143
+
144
+ @property
145
+ def verified(self) -> bool:
146
+ return self.answer is not None
147
+
148
+ def trace(self) -> List[Dict[str, Any]]:
149
+ return [s.to_dict() for s in self.steps]
150
+
151
+ def explain(self) -> str:
152
+ lines = [f"Q: {self.question}"]
153
+ for s in self.steps:
154
+ d = s.to_dict()
155
+ vals = ", ".join(f"{k}={v:g}" for k, v in d["values"].items())
156
+ lines.append(f" {d['step']}. {d['action']} Q={d['Q']:.3f} gain={d['predicted_gain']:.3f} "
157
+ f"cont={d['continuation']:.3f} cost={d['cost']:g} left={d['budget_left']:g} -> {vals}"
158
+ + (f" [{d['error']}]" if d["error"] else ""))
159
+ lines.append(f" stop: {self.status}; answer: {self.answer if self.answer is not None else '(abstain)'}")
160
+ return "\n".join(lines)
161
+
162
+ def to_dict(self) -> Dict[str, Any]:
163
+ return {
164
+ "question": self.question, "answer": self.answer, "abstained": self.abstained, "status": self.status,
165
+ "values": dict(self.values), "grounded_answer": self.grounded_answer,
166
+ "evidence": [d.to_dict() for d in self.evidence],
167
+ "support_passage": self.support_passage.to_dict() if self.support_passage else None,
168
+ "support": self.support, "cost": self.cost, "calls": dict(self.calls), "trace": self.trace(),
169
+ }
170
+
171
+
172
+ # =============================================================================
173
+ class FGAORAG:
174
+ """FGAO v2 as a RAG orchestrator.
175
+
176
+ Parameters
177
+ ----------
178
+ sources : list of ``Source`` (see ``default_sources`` / ``from_retrievers``).
179
+ llm : default LLM for the four operations; anything ``as_llm`` accepts.
180
+ generator, grader, rewriter, support_checker : override single operations.
181
+ costs, priors, weights : declared costs, effect priors and goal weights.
182
+ budget : per-query budget (default 16).
183
+ config : ``FGAOConfig`` (default: the evaluated v2 configuration).
184
+ on_error: "raise" (default) propagates an operation's exception (after any
185
+ retries in a ``resilient`` wrapper); "record" charges the
186
+ operation's declared cost, records the error in the trace and
187
+ lets FGAO continue with the remaining operations.
188
+ """
189
+
190
+ def __init__(
191
+ self,
192
+ sources: Sequence[Source],
193
+ llm: Any = None,
194
+ *,
195
+ generator: Optional[Callable] = None,
196
+ grader: Optional[Callable] = None,
197
+ rewriter: Optional[Callable] = None,
198
+ support_checker: Optional[Callable] = None,
199
+ costs: Costs = Costs(),
200
+ priors: Priors = Priors(),
201
+ weights: Weights = Weights(),
202
+ budget: float = 16.0,
203
+ config: Optional[FGAOConfig] = None,
204
+ on_error: str = "raise",
205
+ ) -> None:
206
+ if not sources:
207
+ raise ValueError("at least one source is required")
208
+ names = [s.name for s in sources]
209
+ if len(set(names)) != len(names):
210
+ raise ValueError("source names must be unique")
211
+ self.sources = [Source(s.name, as_retriever(s.retriever), s.k, s.cost, s.family, s.rewrite) for s in sources]
212
+ self._src = {s.name: s for s in self.sources}
213
+ need = {"generator": generator, "grader": grader, "support_checker": support_checker}
214
+ if any(s.rewrite for s in self.sources):
215
+ need["rewriter"] = rewriter
216
+ missing = [k for k, v in need.items() if v is None]
217
+ if llm is None and missing:
218
+ raise ValueError(f"llm is required for the default {', '.join(missing)}")
219
+ base = as_llm(llm) if llm is not None else None
220
+ self.llm = base
221
+ self.generator = generator or LLMGenerator(base)
222
+ self.grader = grader or LLMGrader(base)
223
+ self.rewriter = rewriter or (LLMRewriter(base) if base is not None else None)
224
+ self.support_checker = support_checker or LLMSupportChecker(base)
225
+ self.costs, self.priors, self.weights = costs, priors, weights
226
+ self.budget = float(budget)
227
+ self.config = config or FGAOConfig()
228
+ self.on_error = on_error
229
+ self.app: CompiledWorkflow = self._build().compile(self.config, budget=self.budget, on_error=on_error)
230
+
231
+ @classmethod
232
+ def from_retrievers(cls, kb: Any, llm: Any = None, *, web: Any = None, costs: Costs = Costs(),
233
+ **kw: Any) -> "FGAORAG":
234
+ """The evaluated layout over one knowledge base and an optional web/second source."""
235
+ return cls(default_sources(kb, web, costs), llm, costs=costs, **kw)
236
+
237
+ # ------------------------------------------------------------ workflow
238
+ def _build(self) -> Workflow:
239
+ P, W, C = self.priors, self.weights, self.costs
240
+ wf = Workflow("fgao-rag")
241
+ wf.add_goal("answered", lambda e: float(bool(e.answer)), weight=W.answered)
242
+ wf.add_goal("grounded", lambda e: float(e.grounded()), weight=W.grounded)
243
+ wf.add_goal("supported", lambda e: float(e.supported and e.grounded()), weight=W.supported)
244
+ for s in self.sources:
245
+ for g in (0, 1):
246
+ wf.add_predicate(f"untried:ans:{s.name}:{g}", (lambda key: lambda e: key not in e.tried)(("ans", s.name, g)))
247
+ wf.add_predicate("unverified", lambda e: bool(e.answer) and e.checked != e.answer)
248
+ for s in self.sources:
249
+ for g in (False, True):
250
+ wf.add_tool(
251
+ "answer", self._answer, afn=self._aanswer, args={"src": s.name, "graded": g},
252
+ cost=s.cost + C.llm * (2 if g else 1),
253
+ gain={"answered": P.graded_answered if g else P.answer_answered,
254
+ "grounded": P.graded_grounded if g else P.answer_grounded},
255
+ harm={"supported": P.answer_harms_support},
256
+ produces={"unverified": P.answer_produces_unverified},
257
+ requires=[f"untried:ans:{s.name}:{int(g)}"],
258
+ group=("answer", s.family),
259
+ )
260
+ wf.add_tool("verify", self._verify, afn=self._averify, cost=C.llm, gain={"supported": P.verify_supported},
261
+ requires=["unverified"], requires_goals=["answered", "grounded"])
262
+ return wf
263
+
264
+ def _ensure_docs(self, ep: RAGEpisode, name: str) -> None:
265
+ if name in ep.docs:
266
+ return
267
+ s = self._src[name]
268
+ query = ep.question
269
+ if s.rewrite:
270
+ ep.calls["rewrite"] += 1
271
+ query = self.rewriter(ep.question) or ep.question
272
+ ep.queries[name] = query
273
+ ep.calls[f"retrieve:{name}"] += 1
274
+ ep.docs[name] = list(s.retriever.retrieve(query, s.k))
275
+
276
+ def _answer(self, ep: RAGEpisode, src: str, graded: bool) -> Optional[ToolResult]:
277
+ ep.tried.add(("ans", src, int(graded)))
278
+ self._ensure_docs(ep, src)
279
+ docs = ep.docs.get(src, [])
280
+ if graded and docs:
281
+ if src not in ep.graded:
282
+ ep.calls["grade"] += 1
283
+ scores = self.grader(ep.question, docs)
284
+ ep.graded[src] = [d for d, sc in zip(docs, scores) if sc >= 1]
285
+ docs = ep.graded[src]
286
+ if not docs:
287
+ return ToolResult(error="no documents")
288
+ ep.calls["generate"] += 1
289
+ ans = self.generator(ep.question, docs) or ""
290
+ if ans and ans != ep.answer: # an abstention never overwrites an existing answer
291
+ ep.answer, ep.answer_docs, ep.supported = ans, list(docs), False
292
+ elif ans and ans == ep.answer and not ep.grounded():
293
+ ep.answer_docs = list(docs)
294
+ return None
295
+
296
+ def _verify(self, ep: RAGEpisode) -> Optional[ToolResult]:
297
+ hit = ep.support_passage()
298
+ if hit is None or not ep.answer:
299
+ return ToolResult(error="nothing to verify")
300
+ ep.calls["verify"] += 1
301
+ ep.checked = ep.answer
302
+ ep.supported = bool(self.support_checker(ep.question, hit, ep.answer))
303
+ return None
304
+
305
+ # async twins (identical logic; components are awaited natively when they support it)
306
+ async def _aensure_docs(self, ep: RAGEpisode, name: str) -> None:
307
+ if name in ep.docs:
308
+ return
309
+ s = self._src[name]
310
+ query = ep.question
311
+ if s.rewrite:
312
+ ep.calls["rewrite"] += 1
313
+ query = (await acall(self.rewriter, ep.question)) or ep.question
314
+ ep.queries[name] = query
315
+ ep.calls[f"retrieve:{name}"] += 1
316
+ ep.docs[name] = list(await aretrieve(s.retriever, query, s.k))
317
+
318
+ async def _aanswer(self, ep: RAGEpisode, src: str, graded: bool) -> Optional[ToolResult]:
319
+ ep.tried.add(("ans", src, int(graded)))
320
+ await self._aensure_docs(ep, src)
321
+ docs = ep.docs.get(src, [])
322
+ if graded and docs:
323
+ if src not in ep.graded:
324
+ ep.calls["grade"] += 1
325
+ scores = await acall(self.grader, ep.question, docs)
326
+ ep.graded[src] = [d for d, sc in zip(docs, scores) if sc >= 1]
327
+ docs = ep.graded[src]
328
+ if not docs:
329
+ return ToolResult(error="no documents")
330
+ ep.calls["generate"] += 1
331
+ ans = (await acall(self.generator, ep.question, docs)) or ""
332
+ if ans and ans != ep.answer:
333
+ ep.answer, ep.answer_docs, ep.supported = ans, list(docs), False
334
+ elif ans and ans == ep.answer and not ep.grounded():
335
+ ep.answer_docs = list(docs)
336
+ return None
337
+
338
+ async def _averify(self, ep: RAGEpisode) -> Optional[ToolResult]:
339
+ hit = ep.support_passage()
340
+ if hit is None or not ep.answer:
341
+ return ToolResult(error="nothing to verify")
342
+ ep.calls["verify"] += 1
343
+ ep.checked = ep.answer
344
+ ep.supported = bool(await acall(self.support_checker, ep.question, hit, ep.answer))
345
+ return None
346
+
347
+ # ------------------------------------------------------------- running
348
+ @staticmethod
349
+ def _question(x: Union[str, Dict[str, Any]]) -> str:
350
+ if isinstance(x, str):
351
+ return x
352
+ if isinstance(x, dict):
353
+ for k in ("question", "query", "input"):
354
+ if k in x:
355
+ return str(x[k])
356
+ raise TypeError("input must be a question string or a dict with 'question'")
357
+
358
+ def _result(self, ep: RAGEpisode, wr: WorkflowResult) -> RAGResult:
359
+ grounded = ep.grounded()
360
+ return RAGResult(
361
+ question=ep.question,
362
+ answer=ep.answer if wr.success else None,
363
+ status=wr.status,
364
+ values=dict(wr.values),
365
+ grounded_answer=ep.answer if grounded else None,
366
+ evidence=list(ep.answer_docs),
367
+ support_passage=ep.support_passage() if grounded else None,
368
+ support=(ep.supported if ep.answer and ep.checked == ep.answer else None),
369
+ cost=wr.cost,
370
+ calls=dict(ep.calls),
371
+ steps=list(wr.steps),
372
+ retrieved={k: list(v) for k, v in ep.docs.items()},
373
+ )
374
+
375
+ def stream(self, question: Union[str, Dict[str, Any]], *, seed: int = 0, budget: Optional[float] = None,
376
+ callbacks: Sequence[Callable[[Step], None]] = ()) -> Iterator[Union[Step, RAGResult]]:
377
+ """Yield every executed ``Step`` as it happens, then the ``RAGResult``."""
378
+ ep = RAGEpisode(self._question(question))
379
+ for item in self.app.stream(ep, seed=seed, budget=budget, callbacks=callbacks):
380
+ yield self._result(ep, item) if isinstance(item, WorkflowResult) else item
381
+
382
+ def invoke(self, question: Union[str, Dict[str, Any]], *, seed: int = 0, budget: Optional[float] = None,
383
+ callbacks: Sequence[Callable[[Step], None]] = ()) -> RAGResult:
384
+ out = None
385
+ for out in self.stream(question, seed=seed, budget=budget, callbacks=callbacks):
386
+ pass
387
+ return out # type: ignore[return-value]
388
+
389
+ __call__ = invoke
390
+
391
+ def batch(self, questions: Sequence[Union[str, Dict[str, Any]]], *, max_concurrency: int = 8,
392
+ **kw: Any) -> List[RAGResult]:
393
+ """Answer many questions concurrently (threads); results keep input order."""
394
+ if max_concurrency <= 1:
395
+ return [self.invoke(q, **kw) for q in questions]
396
+ with ThreadPoolExecutor(max_workers=max_concurrency) as ex:
397
+ return list(ex.map(lambda q: self.invoke(q, **kw), questions))
398
+
399
+ async def astream(self, question: Union[str, Dict[str, Any]], *, seed: int = 0, budget: Optional[float] = None,
400
+ callbacks: Sequence[Callable[[Step], None]] = ()) -> AsyncIterator[Union[Step, RAGResult]]:
401
+ """Native async ``stream``: same decisions; LLM and retriever calls are awaited."""
402
+ ep = RAGEpisode(self._question(question))
403
+ async for item in self.app.astream(ep, seed=seed, budget=budget, callbacks=callbacks):
404
+ yield self._result(ep, item) if isinstance(item, WorkflowResult) else item
405
+
406
+ async def ainvoke(self, question: Union[str, Dict[str, Any]], *, seed: int = 0, budget: Optional[float] = None,
407
+ callbacks: Sequence[Callable[[Step], None]] = ()) -> RAGResult:
408
+ out = None
409
+ async for out in self.astream(question, seed=seed, budget=budget, callbacks=callbacks):
410
+ pass
411
+ return out # type: ignore[return-value]
412
+
413
+ async def abatch(self, questions: Sequence[Union[str, Dict[str, Any]]], *, max_concurrency: int = 64,
414
+ **kw: Any) -> List[RAGResult]:
415
+ """Answer many questions concurrently on the event loop; results keep input order."""
416
+ sem = asyncio.Semaphore(max(1, max_concurrency))
417
+
418
+ async def one(q):
419
+ async with sem:
420
+ return await self.ainvoke(q, **kw)
421
+
422
+ return list(await asyncio.gather(*(one(q) for q in questions)))
423
+
424
+ # -------------------------------------------------------- integrations
425
+ def as_runnable(self):
426
+ """A LangChain ``Runnable``: input a question (str or {'question': ...}), output ``RAGResult.to_dict()``."""
427
+ from ..integrations.langchain import rag_runnable
428
+
429
+ return rag_runnable(self)
430
+
431
+ def as_tool(self, name: str = "fgao_rag", description: Optional[str] = None):
432
+ """A LangChain tool an agent can call with a question."""
433
+ from ..integrations.langchain import rag_tool
434
+
435
+ return rag_tool(self, name, description)
436
+
437
+ def as_node(self, *, question_key: str = "question", answer_key: str = "answer",
438
+ result_key: Optional[str] = "fgao"):
439
+ """A LangGraph node: reads ``state[question_key]``, writes the answer (and the full result)."""
440
+ from ..integrations.langgraph import rag_node
441
+
442
+ return rag_node(self, question_key=question_key, answer_key=answer_key, result_key=result_key)
src/fgao/rag/prompts.py ADDED
@@ -0,0 +1,79 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Prompts and parsers of the evaluated v2 RAG operations (unchanged wording)."""
2
+ from __future__ import annotations
3
+
4
+ import re
5
+ from typing import List, Sequence
6
+
7
+ from .documents import Document
8
+
9
+ SYSTEM_PROMPT = "You are a careful, concise assistant."
10
+
11
+
12
+ def _label(d: Document) -> str:
13
+ return f"({d.title}) {d.text}" if d.title else d.text
14
+
15
+
16
+ def format_passages(docs: Sequence[Document]) -> str:
17
+ return "\n".join(f"[{i + 1}] {_label(d)}" for i, d in enumerate(docs))
18
+
19
+
20
+ def generate_prompt(question: str, docs: Sequence[Document]) -> str:
21
+ return (
22
+ "Answer the question using ONLY the passages below. Reply with the shortest exact answer span "
23
+ "copied from the passages. If the passages do not contain the answer, reply exactly: unanswerable\n\n"
24
+ f"Passages:\n{format_passages(docs)}\n\nQuestion: {question}\nAnswer:"
25
+ )
26
+
27
+
28
+ def grade_prompt(question: str, docs: Sequence[Document]) -> str:
29
+ return (
30
+ "Rate how useful each passage is for answering the question.\n"
31
+ "2 = it contains the answer, 1 = it is on the topic but does not clearly contain the answer, 0 = irrelevant.\n"
32
+ "Reply with exactly one line per passage in the form '[i] score' and nothing else.\n\n"
33
+ f"Question: {question}\n\nPassages:\n{format_passages(docs)}"
34
+ )
35
+
36
+
37
+ def rewrite_prompt(question: str) -> str:
38
+ return ("Rewrite the question as a short keyword search query (at most 8 words) that would retrieve a passage "
39
+ f"containing the answer. Reply with the query only.\n\nQuestion: {question}\nQuery:")
40
+
41
+
42
+ def verify_prompt(question: str, passage: Document, answer: str) -> str:
43
+ return (
44
+ "Does the passage fully support the given answer to the question? Reply exactly 'yes' or 'no'.\n\n"
45
+ f"Passage: {_label(passage)}\n\nQuestion: {question}\nAnswer: {answer}\nSupported:"
46
+ )
47
+
48
+
49
+ # ------------------------------------------------------------------ parsers
50
+ _ABSTAIN = {"unanswerable", "unknown", "no answer", "none", "n/a", "cannot be determined", "not stated"}
51
+
52
+
53
+ def parse_answer(text: str) -> str:
54
+ """First line of the reply, stripped; '' for an abstention."""
55
+ t = (text or "").strip()
56
+ m = re.search(r"answer\s*:\s*(.+)", t, re.I)
57
+ if m:
58
+ t = m.group(1)
59
+ t = t.strip().splitlines()[0].strip() if t.strip() else ""
60
+ t = t.strip(" \"'`*.")
61
+ return "" if t.lower().rstrip(".") in _ABSTAIN else t
62
+
63
+
64
+ def parse_grades(text: str, n: int) -> List[int]:
65
+ out = [0] * n
66
+ for i, s in re.findall(r"\[(\d+)\]\s*[:=-]?\s*([012])", text or ""):
67
+ k = int(i) - 1
68
+ if 0 <= k < n:
69
+ out[k] = int(s)
70
+ return out
71
+
72
+
73
+ def parse_yes(text: str) -> bool:
74
+ return (text or "").strip().lower().startswith("yes")
75
+
76
+
77
+ def parse_query(text: str) -> str:
78
+ t = (text or "").strip()
79
+ return t.splitlines()[0] if t else ""
src/fgao/rag/retrievers.py ADDED
@@ -0,0 +1,154 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Built-in retrievers and retriever coercion."""
2
+ from __future__ import annotations
3
+
4
+ import asyncio
5
+ import inspect
6
+ import math
7
+ import re
8
+ from collections import Counter
9
+ from typing import Any, Callable, List, Optional, Sequence
10
+
11
+ from .documents import Document, as_document, as_documents
12
+
13
+ _TOK = re.compile(r"[a-z0-9]+")
14
+ _STOP = set("a an the of in on at to for and or is are was were be been by with as from that this which who whom what "
15
+ "when where why how did does do it its into than then there their they he she his her".split())
16
+
17
+
18
+ def tokens(text: str) -> List[str]:
19
+ return [t for t in _TOK.findall(text.lower()) if t not in _STOP]
20
+
21
+
22
+ class BM25Retriever:
23
+ """In-memory Okapi BM25 over title + text. No dependencies."""
24
+
25
+ def __init__(self, documents: Sequence[Any], k1: float = 1.5, b: float = 0.75) -> None:
26
+ self.docs = as_documents(documents)
27
+ self.k1, self.b = k1, b
28
+ self.tf = [Counter(tokens(d.title + " " + d.text)) for d in self.docs]
29
+ self.len = [sum(t.values()) for t in self.tf]
30
+ self.avg = sum(self.len) / max(len(self.len), 1)
31
+ df: Counter = Counter()
32
+ for t in self.tf:
33
+ df.update(t.keys())
34
+ n = len(self.docs)
35
+ self.idf = {w: math.log(1 + (n - c + 0.5) / (c + 0.5)) for w, c in df.items()}
36
+ self._post: dict = {}
37
+ for i, t in enumerate(self.tf):
38
+ for w in t:
39
+ self._post.setdefault(w, []).append(i)
40
+
41
+ def retrieve(self, query: str, k: int) -> List[Document]:
42
+ q = tokens(query)
43
+ scores: dict = {}
44
+ for w in q:
45
+ for i in self._post.get(w, ()):
46
+ f = self.tf[i][w]
47
+ scores[i] = scores.get(i, 0.0) + self.idf[w] * f * (self.k1 + 1) / (
48
+ f + self.k1 * (1 - self.b + self.b * self.len[i] / self.avg))
49
+ ranked = sorted(((s, i) for i, s in scores.items() if s > 0), key=lambda x: (-x[0], x[1]))
50
+ return [self.docs[i] for _, i in ranked[:k]]
51
+
52
+ async def aretrieve(self, query: str, k: int) -> List[Document]:
53
+ # in-memory and sub-millisecond for typical corpora: cheaper inline than a thread hop
54
+ return self.retrieve(query, k)
55
+
56
+
57
+ async def aretrieve(retriever: Any, query: str, k: int) -> List[Document]:
58
+ """Native ``aretrieve`` when available, otherwise ``retrieve`` in a worker thread."""
59
+ fn = getattr(retriever, "aretrieve", None)
60
+ if fn is not None:
61
+ return list(await fn(query, k))
62
+ return list(await asyncio.to_thread(retriever.retrieve, query, k))
63
+
64
+
65
+ class FunctionRetriever:
66
+ """Wrap ``fn(query, k) -> iterable of Document | str | dict`` (or an ``async def`` function)."""
67
+
68
+ def __init__(self, fn: Callable[[str, int], Any]) -> None:
69
+ self.fn = fn
70
+ if inspect.iscoroutinefunction(fn):
71
+ self.aretrieve = self._aretrieve # type: ignore[assignment]
72
+
73
+ def retrieve(self, query: str, k: int) -> List[Document]:
74
+ if inspect.iscoroutinefunction(self.fn):
75
+ raise TypeError("this retriever is async-only; use the async API")
76
+ return as_documents(self.fn(query, k))[:k]
77
+
78
+ async def _aretrieve(self, query: str, k: int) -> List[Document]:
79
+ return as_documents(await self.fn(query, k))[:k]
80
+
81
+
82
+ class DenseRetriever:
83
+ """Cosine-similarity retriever over precomputed embeddings.
84
+
85
+ ``embed(texts: list[str]) -> list[list[float]]`` is any embedding function,
86
+ e.g. ``fgao.integrations.huggingface.hf_embedder("BAAI/bge-small-en-v1.5")``.
87
+ Uses numpy when installed, plain Python otherwise.
88
+ """
89
+
90
+ def __init__(self, documents: Sequence[Any], embed: Callable[[List[str]], Any], batch_size: int = 64) -> None:
91
+ self.docs = as_documents(documents)
92
+ self.embed = embed
93
+ vecs: List[List[float]] = []
94
+ texts = [(d.title + "\n" + d.text).strip() for d in self.docs]
95
+ for i in range(0, len(texts), batch_size):
96
+ vecs.extend(_rows(embed(texts[i:i + batch_size])))
97
+ self._np = _numpy()
98
+ if self._np is not None:
99
+ m = self._np.asarray(vecs, dtype=float)
100
+ self._m = m / (self._np.linalg.norm(m, axis=1, keepdims=True) + 1e-12)
101
+ else:
102
+ self._m = [_unit(v) for v in vecs]
103
+
104
+ def retrieve(self, query: str, k: int) -> List[Document]:
105
+ (q,) = _rows(self.embed([query]))
106
+ if self._np is not None:
107
+ qv = self._np.asarray(q, dtype=float)
108
+ sims = self._m @ (qv / (self._np.linalg.norm(qv) + 1e-12))
109
+ order = self._np.argsort(-sims, kind="stable")[:k]
110
+ return [self.docs[int(i)] for i in order]
111
+ qv = _unit(q)
112
+ sims = [sum(a * b for a, b in zip(row, qv)) for row in self._m]
113
+ order = sorted(range(len(sims)), key=lambda i: (-sims[i], i))[:k]
114
+ return [self.docs[i] for i in order]
115
+
116
+
117
+ def _numpy():
118
+ try:
119
+ import numpy
120
+
121
+ return numpy
122
+ except ImportError: # pragma: no cover
123
+ return None
124
+
125
+
126
+ def _rows(x: Any) -> List[List[float]]:
127
+ rows = x.tolist() if hasattr(x, "tolist") else list(x)
128
+ return [list(map(float, r)) for r in rows]
129
+
130
+
131
+ def _unit(v: Sequence[float]) -> List[float]:
132
+ n = math.sqrt(sum(a * a for a in v)) or 1.0
133
+ return [a / n for a in v]
134
+
135
+
136
+ def as_retriever(x: Any):
137
+ """Accept a retriever, a LangChain retriever / vector store, a list of texts or documents
138
+ (indexed with BM25), or ``fn(query, k)``."""
139
+ if x is None:
140
+ return None
141
+ if hasattr(x, "retrieve") and callable(getattr(x, "retrieve")):
142
+ return x
143
+ if hasattr(x, "similarity_search") or (hasattr(x, "invoke") and callable(getattr(x, "invoke"))):
144
+ from ..integrations.langchain import LangChainRetriever
145
+
146
+ return LangChainRetriever(x)
147
+ if isinstance(x, (list, tuple)):
148
+ return BM25Retriever(x)
149
+ if callable(x):
150
+ return FunctionRetriever(x)
151
+ raise TypeError(f"cannot use {type(x).__name__} as a retriever")
152
+
153
+
154
+ __all__ = ["BM25Retriever", "FunctionRetriever", "DenseRetriever", "as_retriever", "aretrieve", "as_document", "tokens"]
src/fgao/resilience.py ADDED
@@ -0,0 +1,206 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Retries, timeouts, rate limiting and concurrency caps for LLMs and retrievers.
2
+
3
+ from fgao.resilience import resilient
4
+
5
+ llm = resilient(OpenAILLM("gpt-4o-mini"), attempts=4, timeout=20, rate=50, max_concurrency=64)
6
+ kb = resilient(my_retriever, attempts=3, timeout=5)
7
+
8
+ ``resilient(x)`` returns an object with the same interface as ``x`` (``complete`` /
9
+ ``acomplete`` for an LLM, ``retrieve`` / ``aretrieve`` for a retriever):
10
+
11
+ * retries with exponential backoff and full jitter on any exception in ``retry_on``
12
+ * per-attempt ``timeout`` (seconds) on the async path; the sync path relies on the
13
+ client's own timeout, which you should also set
14
+ * ``rate``: token-bucket limit on calls per second (shared by all threads and tasks)
15
+ * ``max_concurrency``: cap on simultaneous calls
16
+ * ``stats``: calls, attempts, retries, timeouts, failures (thread-safe counters)
17
+
18
+ A call that still fails after the last attempt raises. Combine with
19
+ ``FGAORAG(..., on_error="record")`` to let FGAO continue without that operation.
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import asyncio
24
+ import random
25
+ import threading
26
+ import time
27
+ from dataclasses import dataclass, field
28
+ from typing import Any, Dict, Optional, Tuple, Type
29
+
30
+
31
+ @dataclass
32
+ class RetryPolicy:
33
+ attempts: int = 3
34
+ backoff: float = 0.5 # base delay (s); attempt i waits U(0, min(max_backoff, backoff * 2**i))
35
+ max_backoff: float = 8.0
36
+ timeout: Optional[float] = None # per attempt, async path
37
+ retry_on: Tuple[Type[BaseException], ...] = (Exception,)
38
+
39
+ def delay(self, i: int, rng: random.Random) -> float:
40
+ return rng.uniform(0.0, min(self.max_backoff, self.backoff * (2 ** i)))
41
+
42
+
43
+ class RateLimiter:
44
+ """Token bucket: ``rate`` calls per second, burst ``burst`` (default: ``rate``)."""
45
+
46
+ def __init__(self, rate: float, burst: Optional[float] = None) -> None:
47
+ if rate <= 0:
48
+ raise ValueError("rate must be positive")
49
+ self.rate = float(rate)
50
+ self.capacity = float(burst if burst is not None else max(1.0, rate))
51
+ self.tokens = self.capacity
52
+ self.t = time.monotonic()
53
+ self._lock = threading.Lock()
54
+
55
+ def _reserve(self) -> float:
56
+ """Take a token; return how long the caller must wait before using it."""
57
+ with self._lock:
58
+ now = time.monotonic()
59
+ self.tokens = min(self.capacity, self.tokens + (now - self.t) * self.rate)
60
+ self.t = now
61
+ self.tokens -= 1.0
62
+ return 0.0 if self.tokens >= 0 else -self.tokens / self.rate
63
+
64
+ def acquire(self) -> None:
65
+ w = self._reserve()
66
+ if w > 0:
67
+ time.sleep(w)
68
+
69
+ async def aacquire(self) -> None:
70
+ w = self._reserve()
71
+ if w > 0:
72
+ await asyncio.sleep(w)
73
+
74
+
75
+ @dataclass
76
+ class Stats:
77
+ calls: int = 0
78
+ attempts: int = 0
79
+ retries: int = 0
80
+ timeouts: int = 0
81
+ failures: int = 0
82
+ _lock: threading.Lock = field(default_factory=threading.Lock, repr=False, compare=False)
83
+
84
+ def add(self, **kw: int) -> None:
85
+ with self._lock:
86
+ for k, v in kw.items():
87
+ setattr(self, k, getattr(self, k) + v)
88
+
89
+ def as_dict(self) -> Dict[str, int]:
90
+ return {k: getattr(self, k) for k in ("calls", "attempts", "retries", "timeouts", "failures")}
91
+
92
+
93
+ class _Resilient:
94
+ def __init__(self, inner: Any, policy: RetryPolicy, rate: Optional[float], max_concurrency: Optional[int],
95
+ name: str, seed: Optional[int]) -> None:
96
+ self.inner = inner
97
+ self.policy = policy
98
+ self.limiter = RateLimiter(rate) if rate else None
99
+ self.max_concurrency = max_concurrency
100
+ self._tsem = threading.BoundedSemaphore(max_concurrency) if max_concurrency else None
101
+ self._asems: Dict[int, asyncio.Semaphore] = {}
102
+ self.name = name
103
+ self.stats = Stats()
104
+ self._rng = random.Random(seed)
105
+
106
+ def _asem(self) -> Optional[asyncio.Semaphore]:
107
+ if not self.max_concurrency:
108
+ return None
109
+ loop = id(asyncio.get_running_loop())
110
+ sem = self._asems.get(loop)
111
+ if sem is None:
112
+ sem = self._asems[loop] = asyncio.Semaphore(self.max_concurrency)
113
+ return sem
114
+
115
+ def _sync(self, fn, *args):
116
+ p = self.policy
117
+ self.stats.add(calls=1)
118
+ for i in range(max(1, p.attempts)):
119
+ if self.limiter:
120
+ self.limiter.acquire()
121
+ self.stats.add(attempts=1)
122
+ try:
123
+ if self._tsem:
124
+ with self._tsem:
125
+ return fn(*args)
126
+ return fn(*args)
127
+ except p.retry_on:
128
+ if i + 1 >= p.attempts:
129
+ self.stats.add(failures=1)
130
+ raise
131
+ self.stats.add(retries=1)
132
+ time.sleep(p.delay(i, self._rng))
133
+ raise RuntimeError("unreachable") # pragma: no cover
134
+
135
+ async def _async(self, make, *args):
136
+ p = self.policy
137
+ self.stats.add(calls=1)
138
+ sem = self._asem()
139
+ for i in range(max(1, p.attempts)):
140
+ if self.limiter:
141
+ await self.limiter.aacquire()
142
+ self.stats.add(attempts=1)
143
+ try:
144
+ coro = make(*args)
145
+ if sem is not None:
146
+ async with sem:
147
+ return await (asyncio.wait_for(coro, p.timeout) if p.timeout else coro)
148
+ return await (asyncio.wait_for(coro, p.timeout) if p.timeout else coro)
149
+ except asyncio.TimeoutError:
150
+ self.stats.add(timeouts=1)
151
+ if i + 1 >= p.attempts:
152
+ self.stats.add(failures=1)
153
+ raise
154
+ self.stats.add(retries=1)
155
+ except asyncio.CancelledError:
156
+ raise
157
+ except p.retry_on:
158
+ if i + 1 >= p.attempts:
159
+ self.stats.add(failures=1)
160
+ raise
161
+ self.stats.add(retries=1)
162
+ await asyncio.sleep(p.delay(i, self._rng))
163
+ raise RuntimeError("unreachable") # pragma: no cover
164
+
165
+
166
+ class ResilientLLM(_Resilient):
167
+ def complete(self, prompt: str) -> str:
168
+ return self._sync(self.inner.complete, prompt)
169
+
170
+ async def acomplete(self, prompt: str) -> str:
171
+ from .rag.llms import acomplete
172
+
173
+ return await self._async(lambda p: acomplete(self.inner, p), prompt)
174
+
175
+
176
+ class ResilientRetriever(_Resilient):
177
+ def retrieve(self, query: str, k: int):
178
+ return self._sync(self.inner.retrieve, query, k)
179
+
180
+ async def aretrieve(self, query: str, k: int):
181
+ from .rag.retrievers import aretrieve
182
+
183
+ return await self._async(lambda q, kk: aretrieve(self.inner, q, kk), query, k)
184
+
185
+
186
+ def resilient(x: Any, *, attempts: int = 3, backoff: float = 0.5, max_backoff: float = 8.0,
187
+ timeout: Optional[float] = None, rate: Optional[float] = None, max_concurrency: Optional[int] = None,
188
+ retry_on: Tuple[Type[BaseException], ...] = (Exception,), name: str = "", seed: Optional[int] = None,
189
+ kind: Optional[str] = None):
190
+ """Wrap an LLM or retriever (anything ``as_llm`` / ``as_retriever`` accepts).
191
+
192
+ ``kind="llm"`` or ``"retriever"`` resolves objects that look like both
193
+ (e.g. LangChain runnables).
194
+ """
195
+ from .rag.llms import as_llm
196
+ from .rag.retrievers import as_retriever
197
+
198
+ policy = RetryPolicy(attempts, backoff, max_backoff, timeout, retry_on)
199
+ looks_retriever = (hasattr(x, "retrieve") or isinstance(x, (list, tuple)) or hasattr(x, "similarity_search")
200
+ or hasattr(x, "_get_relevant_documents"))
201
+ if kind == "retriever" or (kind is None and looks_retriever):
202
+ return ResilientRetriever(as_retriever(x), policy, rate, max_concurrency, name or "retriever", seed)
203
+ return ResilientLLM(as_llm(x), policy, rate, max_concurrency, name or "llm", seed)
204
+
205
+
206
+ __all__ = ["resilient", "RetryPolicy", "RateLimiter", "ResilientLLM", "ResilientRetriever", "Stats"]
src/fgao/server/__init__.py ADDED
@@ -0,0 +1,11 @@
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """HTTP service for FGAO RAG (install ``fgao[server]``)."""
2
+ from .config import build_from_config, load_config
3
+
4
+
5
+ def create_app(*args, **kwargs):
6
+ from .app import create_app as _create
7
+
8
+ return _create(*args, **kwargs)
9
+
10
+
11
+ __all__ = ["create_app", "build_from_config", "load_config"]
src/fgao/server/app.py ADDED
@@ -0,0 +1,352 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """HTTP service around an ``FGAORAG`` instance (FastAPI).
2
+
3
+ Endpoints
4
+
5
+ GET /health liveness
6
+ GET /ready readiness
7
+ GET /v1/info version, sources, costs, budget, controller configuration
8
+ POST /v1/answer {"question", "budget"?, "seed"?, "trace"?, "documents"?, "web_documents"?}
9
+ -> RAGResult as JSON; with "documents", FGAO answers from those passages
10
+ POST /v1/answer/stream same body; Server-Sent Events: "step" per decision, then "result"
11
+ POST /v1/batch {"questions": [...], ...} -> {"results": [...]}
12
+ GET /metrics Prometheus metrics
13
+ GET /docs, /openapi.json interactive API docs
14
+
15
+ Operational behaviour
16
+
17
+ * Admission control: at most ``max_inflight`` queries run at once; up to
18
+ ``max_queue`` more wait; beyond that the server answers 429 with Retry-After.
19
+ * Each query has a deadline (``request_timeout`` s): 504 on expiry, and the
20
+ in-flight model call is cancelled.
21
+ * A failing dependency (after retries) answers 502 with the error type,
22
+ unless the pipeline was built with ``on_error="record"``.
23
+ * Optional API keys: ``Authorization: Bearer <key>`` or ``X-API-Key: <key>``.
24
+ * Every response carries ``X-Request-ID`` (echoed if the client sent one), and
25
+ one JSON log line per query is written to the ``fgao.server`` logger.
26
+ """
27
+ from __future__ import annotations
28
+
29
+ import asyncio
30
+ import dataclasses
31
+ import json
32
+ import logging
33
+ import time
34
+ import uuid
35
+ from typing import Any, Dict, Iterable, List, Optional, Union
36
+
37
+ from .. import __version__
38
+ from ..rag.pipeline import FGAORAG, RAGResult
39
+ from ..resilience import _Resilient
40
+ from .metrics import Registry
41
+
42
+ from fastapi import Depends, FastAPI, Header, HTTPException, Request # noqa: E402
43
+ from fastapi.responses import JSONResponse, PlainTextResponse, StreamingResponse # noqa: E402
44
+ from pydantic import BaseModel, Field # noqa: E402
45
+
46
+ log = logging.getLogger("fgao.server")
47
+
48
+
49
+ DocIn = Union[str, Dict[str, Any]]
50
+
51
+
52
+ class AnswerRequest(BaseModel):
53
+ question: str = Field(..., min_length=1, max_length=8000)
54
+ budget: Optional[float] = Field(None, gt=0)
55
+ seed: int = 0
56
+ trace: bool = True
57
+ documents: Optional[List[DocIn]] = Field(None, description="answer from these passages instead of the configured KB")
58
+ web_documents: Optional[List[DocIn]] = Field(None, description="optional second source for the request documents")
59
+
60
+
61
+ class BatchRequest(BaseModel):
62
+ questions: List[str] = Field(..., min_length=1)
63
+ budget: Optional[float] = Field(None, gt=0)
64
+ seed: int = 0
65
+ trace: bool = False
66
+ documents: Optional[List[DocIn]] = None
67
+ web_documents: Optional[List[DocIn]] = None
68
+
69
+
70
+ class Overloaded(Exception):
71
+ pass
72
+
73
+
74
+ class Admission:
75
+ """Bounded concurrency with a bounded wait queue (per event loop / worker process)."""
76
+
77
+ def __init__(self, max_inflight: int, max_queue: int) -> None:
78
+ self.max_inflight, self.max_queue = max_inflight, max_queue
79
+ self.inflight = 0
80
+ self.waiting = 0
81
+ self._sem: Optional[asyncio.Semaphore] = None
82
+
83
+ def _s(self) -> asyncio.Semaphore:
84
+ if self._sem is None:
85
+ self._sem = asyncio.Semaphore(self.max_inflight)
86
+ return self._sem
87
+
88
+ def check(self, n: int = 1) -> None:
89
+ free = self.max_inflight - self.inflight
90
+ if n > free and self.waiting + n - max(free, 0) > self.max_queue:
91
+ raise Overloaded()
92
+
93
+ async def acquire(self) -> None:
94
+ self.check()
95
+ self.waiting += 1
96
+ try:
97
+ await self._s().acquire()
98
+ finally:
99
+ self.waiting -= 1
100
+ self.inflight += 1
101
+
102
+ def release(self) -> None:
103
+ self.inflight -= 1
104
+ self._s().release()
105
+
106
+
107
+ def _resilient_parts(rag: FGAORAG) -> List[_Resilient]:
108
+ seen, out = set(), []
109
+ cands = [rag.llm] + [s.retriever for s in rag.sources]
110
+ for comp in (rag.generator, rag.grader, rag.rewriter, rag.support_checker):
111
+ cands.append(getattr(comp, "llm", None))
112
+ for c in cands:
113
+ if isinstance(c, _Resilient) and id(c) not in seen:
114
+ seen.add(id(c))
115
+ out.append(c)
116
+ return out
117
+
118
+
119
+ def create_app(
120
+ rag: FGAORAG,
121
+ *,
122
+ api_keys: Optional[Iterable[str]] = None,
123
+ max_inflight: int = 256,
124
+ max_queue: int = 1024,
125
+ request_timeout: float = 60.0,
126
+ max_batch: int = 256,
127
+ max_budget: Optional[float] = None,
128
+ max_documents: int = 500,
129
+ title: str = "FGAO RAG",
130
+ ):
131
+ """Build the FastAPI application. ``max_budget`` caps per-request budgets (default: the pipeline budget x 4)."""
132
+ keys = {k for k in (api_keys or []) if k}
133
+ cap = float(max_budget if max_budget is not None else rag.budget * 4)
134
+ adm = Admission(max_inflight, max_queue)
135
+ reg = Registry()
136
+ m_http = reg.counter("fgao_http_requests_total", "HTTP requests by route and status code")
137
+ m_lat = reg.histogram("fgao_request_duration_seconds", "Query latency in seconds",
138
+ (0.05, 0.1, 0.25, 0.5, 1, 2, 4, 8, 16, 32, 64))
139
+ m_out = reg.counter("fgao_queries_total", "Queries by outcome (verified, abstained, timeout, error)")
140
+ m_stop = reg.counter("fgao_stop_status_total", "Queries by FGAO stop status")
141
+ m_cost = reg.histogram("fgao_query_cost", "Budget spent per query", (1, 2, 4, 6, 8, 10, 12, 16, 24, 32, 64))
142
+ m_ops = reg.counter("fgao_operation_calls_total", "Operation calls (generate, grade, rewrite, verify, retrieve:*)")
143
+ m_steps = reg.counter("fgao_steps_total", "Controller steps executed")
144
+ m_inflight = reg.gauge("fgao_inflight", "Queries running")
145
+ m_queue = reg.gauge("fgao_queue", "Queries waiting for a slot")
146
+ parts = _resilient_parts(rag)
147
+
148
+ def collect():
149
+ m_inflight.set(adm.inflight)
150
+ m_queue.set(adm.waiting)
151
+ for p in parts:
152
+ for k, v in p.stats.as_dict().items():
153
+ yield (f"fgao_dependency_{k}_total", "counter", f"Dependency {k} (resilient wrappers)", {"name": p.name}, v)
154
+
155
+ reg.collectors.append(lambda: list(collect()))
156
+
157
+ app = FastAPI(title=title, version=__version__,
158
+ description="Training-free FGAO orchestration of retrieval-augmented generation.")
159
+
160
+ def auth(authorization: Optional[str] = Header(None), x_api_key: Optional[str] = Header(None)) -> None:
161
+ if not keys:
162
+ return
163
+ token = x_api_key or (authorization[7:] if authorization and authorization.lower().startswith("bearer ") else None)
164
+ if token not in keys:
165
+ raise HTTPException(status_code=401, detail="invalid or missing API key")
166
+
167
+ @app.middleware("http")
168
+ async def request_id(request: Request, call_next):
169
+ rid = request.headers.get("x-request-id") or uuid.uuid4().hex
170
+ request.state.rid = rid
171
+ resp = await call_next(request)
172
+ resp.headers["X-Request-ID"] = rid
173
+ route = request.scope.get("route")
174
+ m_http.inc(route=getattr(route, "path", request.url.path), code=str(resp.status_code))
175
+ return resp
176
+
177
+ def _budget(b: Optional[float]) -> Optional[float]:
178
+ if b is not None and b > cap:
179
+ raise HTTPException(status_code=422, detail=f"budget exceeds the server limit {cap:g}")
180
+ return b
181
+
182
+ def _payload(r: RAGResult, trace: bool) -> Dict[str, Any]:
183
+ d = r.to_dict()
184
+ if not trace:
185
+ d.pop("trace", None)
186
+ return d
187
+
188
+ def _record(r: RAGResult, seconds: float, rid: str) -> None:
189
+ m_out.inc(outcome="verified" if r.answer is not None else "abstained")
190
+ m_stop.inc(status=r.status)
191
+ m_lat.observe(seconds)
192
+ m_cost.observe(r.cost)
193
+ m_steps.inc(len(r.steps))
194
+ for k, v in r.calls.items():
195
+ m_ops.inc(v, op=k)
196
+ log.info(json.dumps({"event": "query", "request_id": rid, "status": r.status, "verified": r.answer is not None,
197
+ "cost": r.cost, "steps": len(r.steps), "seconds": round(seconds, 4)}))
198
+
199
+ def _pipeline(documents, web_documents) -> FGAORAG:
200
+ """The configured pipeline, or one over the request's own passages (same LLM, costs, priors, controller)."""
201
+ if not documents:
202
+ return rag
203
+ if len(documents) > max_documents or (web_documents and len(web_documents) > max_documents):
204
+ raise HTTPException(status_code=422, detail=f"at most {max_documents} documents per source")
205
+ if rag.llm is None:
206
+ raise HTTPException(status_code=422, detail="request documents need a pipeline with a default LLM")
207
+ return FGAORAG.from_retrievers(kb=list(documents), web=list(web_documents) if web_documents else None,
208
+ llm=rag.llm, costs=rag.costs, priors=rag.priors, weights=rag.weights,
209
+ budget=rag.budget, config=rag.config, on_error=rag.on_error)
210
+
211
+ async def _run(q: str, budget: Optional[float], seed: int, rid: str, pipe: Optional[FGAORAG] = None) -> RAGResult:
212
+ t0 = time.perf_counter()
213
+ pipe = pipe or rag
214
+ try:
215
+ r = await asyncio.wait_for(pipe.ainvoke(q, budget=budget, seed=seed), request_timeout)
216
+ except asyncio.TimeoutError:
217
+ m_out.inc(outcome="timeout")
218
+ m_lat.observe(time.perf_counter() - t0)
219
+ log.warning(json.dumps({"event": "timeout", "request_id": rid}))
220
+ raise
221
+ except Exception as e: # noqa: BLE001
222
+ m_out.inc(outcome="error")
223
+ m_lat.observe(time.perf_counter() - t0)
224
+ log.error(json.dumps({"event": "error", "request_id": rid, "error": type(e).__name__, "detail": str(e)[:500]}))
225
+ raise
226
+ _record(r, time.perf_counter() - t0, rid)
227
+ return r
228
+
229
+ def _overloaded() -> JSONResponse:
230
+ return JSONResponse({"detail": "server overloaded, retry later"}, status_code=429, headers={"Retry-After": "1"})
231
+
232
+ @app.get("/health")
233
+ async def health():
234
+ return {"status": "ok"}
235
+
236
+ @app.get("/ready")
237
+ async def ready():
238
+ return {"status": "ready", "inflight": adm.inflight, "queued": adm.waiting}
239
+
240
+ @app.get("/v1/info", dependencies=[Depends(auth)])
241
+ async def info():
242
+ return {
243
+ "version": __version__,
244
+ "budget": rag.budget, "max_budget": cap,
245
+ "sources": [{"name": s.name, "k": s.k, "cost": s.cost, "family": s.family, "rewrite": s.rewrite}
246
+ for s in rag.sources],
247
+ "costs": dataclasses.asdict(rag.costs),
248
+ "weights": dataclasses.asdict(rag.weights),
249
+ "priors": dataclasses.asdict(rag.priors),
250
+ "controller": dataclasses.asdict(rag.config),
251
+ "operations": [str(a) for a in rag.app.actions],
252
+ "on_error": rag.on_error,
253
+ "limits": {"max_inflight": max_inflight, "max_queue": max_queue, "request_timeout": request_timeout,
254
+ "max_batch": max_batch},
255
+ }
256
+
257
+ @app.post("/v1/answer", dependencies=[Depends(auth)])
258
+ async def answer(req: AnswerRequest, request: Request):
259
+ budget = _budget(req.budget)
260
+ pipe = _pipeline(req.documents, req.web_documents)
261
+ try:
262
+ await adm.acquire()
263
+ except Overloaded:
264
+ return _overloaded()
265
+ try:
266
+ r = await _run(req.question, budget, req.seed, request.state.rid, pipe)
267
+ except asyncio.TimeoutError:
268
+ raise HTTPException(status_code=504, detail=f"query exceeded {request_timeout:g} s")
269
+ except Exception as e: # noqa: BLE001
270
+ raise HTTPException(status_code=502, detail=f"{type(e).__name__}: {e}"[:500])
271
+ finally:
272
+ adm.release()
273
+ return _payload(r, req.trace)
274
+
275
+ @app.post("/v1/batch", dependencies=[Depends(auth)])
276
+ async def batch(req: BatchRequest, request: Request):
277
+ if len(req.questions) > max_batch:
278
+ raise HTTPException(status_code=422, detail=f"at most {max_batch} questions per batch")
279
+ budget = _budget(req.budget)
280
+ pipe = _pipeline(req.documents, req.web_documents)
281
+ try:
282
+ adm.check(len(req.questions))
283
+ except Overloaded:
284
+ return _overloaded()
285
+
286
+ async def one(i: int, q: str) -> Dict[str, Any]:
287
+ await adm.acquire() # admitted above; this only waits for a slot
288
+ try:
289
+ return _payload(await _run(q, budget, req.seed, f"{request.state.rid}:{i}", pipe), req.trace)
290
+ except asyncio.TimeoutError:
291
+ return {"question": q, "error": "timeout"}
292
+ except Exception as e: # noqa: BLE001
293
+ return {"question": q, "error": f"{type(e).__name__}: {e}"[:500]}
294
+ finally:
295
+ adm.release()
296
+
297
+ results = await asyncio.gather(*(one(i, q) for i, q in enumerate(req.questions)))
298
+ return {"results": list(results)}
299
+
300
+ @app.post("/v1/answer/stream", dependencies=[Depends(auth)])
301
+ async def stream(req: AnswerRequest, request: Request):
302
+ budget = _budget(req.budget)
303
+ pipe = _pipeline(req.documents, req.web_documents)
304
+ try:
305
+ await adm.acquire()
306
+ except Overloaded:
307
+ return _overloaded()
308
+ rid = request.state.rid
309
+ released = [False]
310
+
311
+ def release_once() -> None:
312
+ if not released[0]:
313
+ released[0] = True
314
+ adm.release()
315
+
316
+ async def events():
317
+ t0 = time.perf_counter()
318
+ agen = pipe.astream(req.question, budget=budget, seed=req.seed).__aiter__()
319
+ try:
320
+ while True:
321
+ left = request_timeout - (time.perf_counter() - t0)
322
+ try:
323
+ item = await asyncio.wait_for(agen.__anext__(), max(left, 0.001))
324
+ except StopAsyncIteration:
325
+ break
326
+ if isinstance(item, RAGResult):
327
+ _record(item, time.perf_counter() - t0, rid)
328
+ yield f"event: result\ndata: {json.dumps(_payload(item, req.trace))}\n\n"
329
+ else:
330
+ yield f"event: step\ndata: {json.dumps(item.to_dict())}\n\n"
331
+ except asyncio.TimeoutError:
332
+ m_out.inc(outcome="timeout")
333
+ yield f"event: error\ndata: {json.dumps({'error': 'timeout'})}\n\n"
334
+ except Exception as e: # noqa: BLE001
335
+ m_out.inc(outcome="error")
336
+ yield f"event: error\ndata: {json.dumps({'error': f'{type(e).__name__}: {e}'[:500]})}\n\n"
337
+ finally:
338
+ release_once()
339
+
340
+ from starlette.background import BackgroundTask
341
+
342
+ return StreamingResponse(events(), media_type="text/event-stream", background=BackgroundTask(release_once),
343
+ headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
344
+
345
+ @app.get("/metrics")
346
+ async def metrics():
347
+ return PlainTextResponse(reg.render(), media_type="text/plain; version=0.0.4")
348
+
349
+ app.state.rag = rag
350
+ app.state.admission = adm
351
+ app.state.registry = reg
352
+ return app
src/fgao/server/cli.py ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Command line: ``fgao serve``, ``fgao ask``, ``fgao check``.
2
+
3
+ fgao serve --config fgao.yaml --host 0.0.0.0 --port 8000 [--workers 1]
4
+ fgao serve --factory myapp.rag:build # build() returns an FGAORAG
5
+ fgao ask --config fgao.yaml "What is ...?" # one query, JSON to stdout
6
+ fgao check --config fgao.yaml # build the pipeline and print its layout
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import asyncio
12
+ import json
13
+ import logging
14
+ import os
15
+ import sys
16
+ from typing import Any, Dict, List, Optional, Tuple
17
+
18
+
19
+ def _load(config: Optional[str], factory: Optional[str]) -> Tuple[Any, Dict[str, Any]]:
20
+ from .config import import_object, load_config
21
+
22
+ if factory:
23
+ return import_object(factory)(), {}
24
+ if not config:
25
+ raise SystemExit("give --config FILE or --factory module:function")
26
+ return load_config(config)
27
+
28
+
29
+ def app_from_env():
30
+ """uvicorn factory (used for --workers > 1): reads FGAO_CONFIG / FGAO_FACTORY."""
31
+ from .app import create_app
32
+ from .config import server_kwargs
33
+
34
+ rag, settings = _load(os.environ.get("FGAO_CONFIG"), os.environ.get("FGAO_FACTORY"))
35
+ return create_app(rag, **server_kwargs(settings))
36
+
37
+
38
+ def main(argv: Optional[List[str]] = None) -> int:
39
+ ap = argparse.ArgumentParser(prog="fgao", description="FGAO orchestration service")
40
+ sub = ap.add_subparsers(dest="cmd", required=True)
41
+ for name in ("serve", "ask", "check"):
42
+ p = sub.add_parser(name)
43
+ p.add_argument("--config", help="YAML or JSON configuration file")
44
+ p.add_argument("--factory", help="module:function returning an FGAORAG")
45
+ if name == "serve":
46
+ p.add_argument("--host", default="127.0.0.1")
47
+ p.add_argument("--port", type=int, default=8000)
48
+ p.add_argument("--workers", type=int, default=1)
49
+ p.add_argument("--log-level", default="info")
50
+ p.add_argument("--keep-alive", type=int, default=75,
51
+ help="idle keep-alive seconds; keep it above your load balancer's idle timeout")
52
+ if name == "ask":
53
+ p.add_argument("question")
54
+ p.add_argument("--budget", type=float)
55
+ p.add_argument("--explain", action="store_true", help="print the decision trace instead of JSON")
56
+ a = ap.parse_args(argv)
57
+
58
+ if a.cmd == "check":
59
+ rag, settings = _load(a.config, a.factory)
60
+ print(json.dumps({"sources": [{"name": s.name, "k": s.k, "cost": s.cost, "family": s.family,
61
+ "rewrite": s.rewrite, "retriever": type(s.retriever).__name__}
62
+ for s in rag.sources],
63
+ "llm": type(rag.llm).__name__ if rag.llm is not None else None,
64
+ "budget": rag.budget, "on_error": rag.on_error,
65
+ "operations": [str(x) for x in rag.app.actions], "server": settings}, indent=2))
66
+ return 0
67
+ if a.cmd == "ask":
68
+ rag, _ = _load(a.config, a.factory)
69
+ r = asyncio.run(rag.ainvoke(a.question, budget=a.budget))
70
+ print(r.explain() if a.explain else json.dumps(r.to_dict(), indent=2))
71
+ return 0
72
+
73
+ import uvicorn
74
+
75
+ logging.basicConfig(level=a.log_level.upper(), format="%(message)s")
76
+ if a.workers > 1:
77
+ if a.config:
78
+ os.environ["FGAO_CONFIG"] = os.path.abspath(a.config)
79
+ if a.factory:
80
+ os.environ["FGAO_FACTORY"] = a.factory
81
+ uvicorn.run("fgao.server.cli:app_from_env", factory=True, host=a.host, port=a.port, workers=a.workers,
82
+ log_level=a.log_level, timeout_keep_alive=a.keep_alive)
83
+ return 0
84
+ from .app import create_app
85
+ from .config import server_kwargs
86
+
87
+ rag, settings = _load(a.config, a.factory)
88
+ uvicorn.run(create_app(rag, **server_kwargs(settings)), host=a.host, port=a.port, log_level=a.log_level,
89
+ timeout_keep_alive=a.keep_alive)
90
+ return 0
91
+
92
+
93
+ if __name__ == "__main__": # pragma: no cover
94
+ sys.exit(main())
src/fgao/server/config.py ADDED
@@ -0,0 +1,225 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Build an ``FGAORAG`` (and server settings) from a YAML or JSON file.
2
+
3
+ Example (see ``deploy/fgao.yaml``)::
4
+
5
+ llm:
6
+ provider: openai # openai | anthropic | huggingface | transformers | factory
7
+ model: gpt-4o-mini
8
+ base_url: null # any OpenAI-compatible server (vLLM, TGI, Ollama, ...)
9
+ api_key_env: OPENAI_API_KEY
10
+ temperature: 0
11
+ max_tokens: 128
12
+ timeout: 30
13
+ resilience: # applied to the LLM and to every retriever
14
+ attempts: 3
15
+ backoff: 0.5
16
+ timeout: 30
17
+ rate: null # calls per second, per process
18
+ max_concurrency: 64
19
+ cache: {path: null} # prompt cache (JSON file) in front of the LLM
20
+ kb: {type: bm25, path: /data/kb.jsonl}
21
+ web: {type: http, url: http://search:9000/search}
22
+ budget: 16
23
+ on_error: record
24
+ server: {max_inflight: 256, max_queue: 1024, request_timeout: 60, max_batch: 256} # keys: FGAO_API_KEYS env
25
+
26
+ Retriever types
27
+
28
+ bm25 path to .jsonl (one {"text", "title"?, "id"?} per line), .json (list), or .txt (blank-line paragraphs)
29
+ dense the same files + embedder {provider: huggingface | sentence-transformers, model}
30
+ http POST {"query", "k"} to ``url``; expects a list of documents or {"documents": [...]}
31
+ factory "module:function" (+ ``kwargs``) returning any retriever, LangChain retriever or vector store
32
+
33
+ Instead of ``kb`` / ``web`` an explicit ``sources:`` list may be given:
34
+ ``[{name, retriever: <spec>, k, cost, family, rewrite}]``.
35
+ """
36
+ from __future__ import annotations
37
+
38
+ import importlib
39
+ import json
40
+ import os
41
+ from typing import Any, Dict, List, Optional, Tuple
42
+
43
+ from ..controller import FGAOConfig
44
+ from ..rag.documents import Document, as_documents
45
+ from ..rag.llms import CachedLLM
46
+ from ..rag.pipeline import FGAORAG, Costs, Priors, Source, Weights, default_sources
47
+ from ..rag.retrievers import BM25Retriever, DenseRetriever
48
+ from ..resilience import resilient
49
+
50
+
51
+ def load_file(path: str) -> Dict[str, Any]:
52
+ with open(path, encoding="utf-8") as fh:
53
+ text = fh.read()
54
+ if path.endswith((".yaml", ".yml")):
55
+ try:
56
+ import yaml
57
+ except ImportError as e: # pragma: no cover
58
+ raise ImportError("YAML configs need pyyaml: pip install 'fgao[server]'") from e
59
+ return yaml.safe_load(text) or {}
60
+ return json.loads(text)
61
+
62
+
63
+ def import_object(ref: str) -> Any:
64
+ mod, _, attr = ref.partition(":")
65
+ if not attr:
66
+ raise ValueError(f"expected 'module:attribute', got {ref!r}")
67
+ obj = importlib.import_module(mod)
68
+ for part in attr.split("."):
69
+ obj = getattr(obj, part)
70
+ return obj
71
+
72
+
73
+ def load_documents(path: str) -> List[Document]:
74
+ if path.endswith(".jsonl"):
75
+ with open(path, encoding="utf-8") as fh:
76
+ return as_documents(json.loads(line) for line in fh if line.strip())
77
+ if path.endswith(".json"):
78
+ with open(path, encoding="utf-8") as fh:
79
+ data = json.load(fh)
80
+ return as_documents(data["documents"] if isinstance(data, dict) else data)
81
+ with open(path, encoding="utf-8") as fh:
82
+ return as_documents(p.strip() for p in fh.read().split("\n\n") if p.strip())
83
+
84
+
85
+ class HTTPRetriever:
86
+ """Retriever backed by a search service: POST {"query", "k"} -> documents."""
87
+
88
+ def __init__(self, url: str, *, headers: Optional[Dict[str, str]] = None, timeout: float = 10.0) -> None:
89
+ import httpx
90
+
91
+ self.url, self.headers, self.timeout = url, dict(headers or {}), timeout
92
+ self._client = httpx.Client(timeout=timeout, headers=self.headers)
93
+ self._aclient: Any = None
94
+
95
+ @staticmethod
96
+ def _docs(data: Any) -> List[Document]:
97
+ return as_documents(data.get("documents", data.get("results", [])) if isinstance(data, dict) else data)
98
+
99
+ def retrieve(self, query: str, k: int) -> List[Document]:
100
+ r = self._client.post(self.url, json={"query": query, "k": k})
101
+ r.raise_for_status()
102
+ return self._docs(r.json())[:k]
103
+
104
+ async def aretrieve(self, query: str, k: int) -> List[Document]:
105
+ import httpx
106
+
107
+ if self._aclient is None:
108
+ self._aclient = httpx.AsyncClient(timeout=self.timeout, headers=self.headers)
109
+ r = await self._aclient.post(self.url, json={"query": query, "k": k})
110
+ r.raise_for_status()
111
+ return self._docs(r.json())[:k]
112
+
113
+
114
+ def _env(spec: Dict[str, Any], key: str) -> Optional[str]:
115
+ name = spec.get(key)
116
+ return os.environ.get(name) if name else None
117
+
118
+
119
+ def build_llm(spec: Dict[str, Any], client_retries: Optional[int] = None):
120
+ """``client_retries``: SDK-level retries (0 when FGAO's own resilience layer retries)."""
121
+ p = (spec.get("provider") or "openai").lower()
122
+ sdk_retries = spec.get("client_retries", client_retries)
123
+ common = {k: spec[k] for k in ("max_tokens", "temperature", "system") if k in spec}
124
+ if p in ("openai", "openai-compatible", "vllm", "ollama", "tgi"):
125
+ from ..integrations.providers import OpenAILLM
126
+
127
+ return OpenAILLM(spec["model"], base_url=spec.get("base_url"), api_key=_env(spec, "api_key_env") or spec.get("api_key"),
128
+ timeout=spec.get("timeout"), max_retries=sdk_retries, **common)
129
+ if p == "anthropic":
130
+ from ..integrations.providers import AnthropicLLM
131
+
132
+ return AnthropicLLM(spec["model"], api_key=_env(spec, "api_key_env"), timeout=spec.get("timeout"),
133
+ max_retries=sdk_retries, **common)
134
+ if p in ("huggingface", "hf"):
135
+ from ..integrations.huggingface import HFInferenceLLM
136
+
137
+ return HFInferenceLLM(spec["model"], token=_env(spec, "api_key_env") or os.environ.get("HF_TOKEN"),
138
+ provider=spec.get("hf_provider"), base_url=spec.get("base_url"),
139
+ timeout=spec.get("timeout"), **common)
140
+ if p == "transformers":
141
+ from ..integrations.huggingface import TransformersLLM
142
+
143
+ return TransformersLLM(spec["model"], max_new_tokens=spec.get("max_tokens", 64))
144
+ if p == "factory":
145
+ return import_object(spec["factory"])(**spec.get("kwargs", {}))
146
+ raise ValueError(f"unknown llm provider {p!r}")
147
+
148
+
149
+ def build_retriever(spec: Any, base_dir: str = "."):
150
+ if isinstance(spec, str):
151
+ spec = {"type": "bm25", "path": spec}
152
+ t = spec.get("type", "bm25")
153
+ path = spec.get("path")
154
+ if path and not os.path.isabs(path):
155
+ path = os.path.join(base_dir, path)
156
+ if t == "bm25":
157
+ return BM25Retriever(load_documents(path))
158
+ if t == "dense":
159
+ emb = spec.get("embedder", {})
160
+ if emb.get("provider", "huggingface") in ("huggingface", "hf"):
161
+ from ..integrations.huggingface import hf_embedder
162
+
163
+ fn = hf_embedder(emb["model"], token=os.environ.get(emb.get("api_key_env", "HF_TOKEN")))
164
+ else:
165
+ from ..integrations.huggingface import st_embedder
166
+
167
+ fn = st_embedder(emb["model"])
168
+ return DenseRetriever(load_documents(path), fn)
169
+ if t == "http":
170
+ return HTTPRetriever(spec["url"], headers=spec.get("headers"), timeout=spec.get("timeout", 10.0))
171
+ if t == "factory":
172
+ return import_object(spec["factory"])(**spec.get("kwargs", {}))
173
+ raise ValueError(f"unknown retriever type {t!r}")
174
+
175
+
176
+ def build_from_config(cfg: Dict[str, Any], base_dir: str = ".") -> Tuple[FGAORAG, Dict[str, Any]]:
177
+ """Return (pipeline, server settings)."""
178
+ if "factory" in cfg: # a function returning a ready FGAORAG
179
+ rag = import_object(cfg["factory"])(**cfg.get("kwargs", {}))
180
+ return rag, dict(cfg.get("server", {}))
181
+ res = cfg.get("resilience")
182
+ llm = build_llm(cfg.get("llm", {}), client_retries=0 if res else None)
183
+ if cfg.get("cache"):
184
+ if cfg["cache"].get("path") or cfg["cache"].get("enabled", True):
185
+ llm = CachedLLM(llm, cfg["cache"].get("path"))
186
+ if res:
187
+ llm = resilient(llm, name="llm", kind="llm", **res)
188
+
189
+ def wrap(r, name):
190
+ return resilient(r, name=f"retriever:{name}", kind="retriever", **res) if res else r
191
+
192
+ costs = Costs(**cfg.get("costs", {}))
193
+ if "sources" in cfg:
194
+ sources = [Source(s["name"], wrap(build_retriever(s["retriever"], base_dir), s["name"]), k=s.get("k", 5),
195
+ cost=s.get("cost", 1.0), family=s.get("family", "kb"), rewrite=s.get("rewrite", False))
196
+ for s in cfg["sources"]]
197
+ else:
198
+ if "kb" not in cfg:
199
+ raise ValueError("config needs 'kb' (and optionally 'web'), 'sources', or 'factory'")
200
+ kb = wrap(build_retriever(cfg["kb"], base_dir), "kb")
201
+ web = wrap(build_retriever(cfg["web"], base_dir), "web") if cfg.get("web") else None
202
+ sources = default_sources(kb, web, costs)
203
+ rag = FGAORAG(
204
+ sources, llm, costs=costs, priors=Priors(**cfg.get("priors", {})), weights=Weights(**cfg.get("weights", {})),
205
+ budget=float(cfg.get("budget", 16.0)), config=FGAOConfig(**cfg.get("controller", {})),
206
+ on_error=cfg.get("on_error", "raise"),
207
+ )
208
+ return rag, dict(cfg.get("server", {}))
209
+
210
+
211
+ def load_config(path: str) -> Tuple[FGAORAG, Dict[str, Any]]:
212
+ return build_from_config(load_file(path), os.path.dirname(os.path.abspath(path)))
213
+
214
+
215
+ def server_kwargs(settings: Dict[str, Any]) -> Dict[str, Any]:
216
+ out = {k: settings[k] for k in ("max_inflight", "max_queue", "request_timeout", "max_batch", "max_budget",
217
+ "max_documents", "title")
218
+ if k in settings}
219
+ keys = list(settings.get("api_keys", []))
220
+ env = settings.get("api_keys_env", "FGAO_API_KEYS") # setting FGAO_API_KEYS always enables authentication
221
+ if env and os.environ.get(env):
222
+ keys += [k.strip() for k in os.environ[env].split(",") if k.strip()]
223
+ if keys:
224
+ out["api_keys"] = keys
225
+ return out
src/fgao/server/metrics.py ADDED
@@ -0,0 +1,111 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Minimal Prometheus metrics (text exposition format), no dependency."""
2
+ from __future__ import annotations
3
+
4
+ import threading
5
+ from typing import Dict, Iterable, List, Sequence, Tuple
6
+
7
+ Labels = Tuple[Tuple[str, str], ...]
8
+
9
+
10
+ def _fmt_labels(labels: Labels) -> str:
11
+ if not labels:
12
+ return ""
13
+ inner = ",".join(f'{k}="{str(v).replace(chr(92), chr(92) * 2).replace(chr(34), chr(92) + chr(34))}"' for k, v in labels)
14
+ return "{" + inner + "}"
15
+
16
+
17
+ class Counter:
18
+ kind = "counter"
19
+
20
+ def __init__(self, name: str, help: str) -> None:
21
+ self.name, self.help = name, help
22
+ self.values: Dict[Labels, float] = {}
23
+ self._lock = threading.Lock()
24
+
25
+ def inc(self, amount: float = 1.0, **labels: str) -> None:
26
+ key = tuple(sorted(labels.items()))
27
+ with self._lock:
28
+ self.values[key] = self.values.get(key, 0.0) + amount
29
+
30
+ def samples(self) -> Iterable[Tuple[str, Labels, float]]:
31
+ with self._lock:
32
+ return [(self.name, k, v) for k, v in self.values.items()]
33
+
34
+
35
+ class Gauge(Counter):
36
+ kind = "gauge"
37
+
38
+ def set(self, value: float, **labels: str) -> None:
39
+ key = tuple(sorted(labels.items()))
40
+ with self._lock:
41
+ self.values[key] = float(value)
42
+
43
+
44
+ class Histogram:
45
+ kind = "histogram"
46
+
47
+ def __init__(self, name: str, help: str, buckets: Sequence[float]) -> None:
48
+ self.name, self.help = name, help
49
+ self.buckets = sorted(buckets)
50
+ self.data: Dict[Labels, List[float]] = {} # per label set: bucket counts + [sum, count]
51
+ self._lock = threading.Lock()
52
+
53
+ def observe(self, x: float, **labels: str) -> None:
54
+ key = tuple(sorted(labels.items()))
55
+ with self._lock:
56
+ d = self.data.setdefault(key, [0.0] * (len(self.buckets) + 2))
57
+ for i, b in enumerate(self.buckets):
58
+ if x <= b:
59
+ d[i] += 1
60
+ d[-2] += x
61
+ d[-1] += 1
62
+
63
+ def samples(self):
64
+ out = []
65
+ with self._lock:
66
+ for key, d in self.data.items():
67
+ for i, b in enumerate(self.buckets):
68
+ out.append((self.name + "_bucket", key + (("le", repr(float(b))),), d[i]))
69
+ out.append((self.name + "_bucket", key + (("le", "+Inf"),), d[-1]))
70
+ out.append((self.name + "_sum", key, d[-2]))
71
+ out.append((self.name + "_count", key, d[-1]))
72
+ return out
73
+
74
+
75
+ class Registry:
76
+ def __init__(self) -> None:
77
+ self.metrics: List = []
78
+ self.collectors: List = [] # callables returning [(metric_name, kind, help, labels, value)]
79
+
80
+ def counter(self, name: str, help: str) -> Counter:
81
+ m = Counter(name, help)
82
+ self.metrics.append(m)
83
+ return m
84
+
85
+ def gauge(self, name: str, help: str) -> Gauge:
86
+ m = Gauge(name, help)
87
+ self.metrics.append(m)
88
+ return m
89
+
90
+ def histogram(self, name: str, help: str, buckets: Sequence[float]) -> Histogram:
91
+ m = Histogram(name, help, buckets)
92
+ self.metrics.append(m)
93
+ return m
94
+
95
+ def render(self) -> str:
96
+ lines: List[str] = []
97
+ for m in self.metrics:
98
+ lines.append(f"# HELP {m.name} {m.help}")
99
+ lines.append(f"# TYPE {m.name} {m.kind}")
100
+ for name, labels, v in m.samples():
101
+ lines.append(f"{name}{_fmt_labels(labels)} {v:g}")
102
+ families: Dict[str, Tuple[str, str, List[str]]] = {}
103
+ for collect in self.collectors:
104
+ for name, kind, help, labels, v in collect():
105
+ fam = families.setdefault(name, (kind, help, []))
106
+ fam[2].append(f"{name}{_fmt_labels(tuple(sorted(labels.items())))} {v:g}")
107
+ for name, (kind, help, samples) in families.items():
108
+ lines.append(f"# HELP {name} {help}")
109
+ lines.append(f"# TYPE {name} {kind}")
110
+ lines.extend(samples)
111
+ return "\n".join(lines) + "\n"
src/fgao/types.py ADDED
@@ -0,0 +1,175 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Core value types shared by the controller, the workflow API and the RAG pipeline."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass, field
5
+ from typing import Any, Dict, FrozenSet, Hashable, Iterable, List, Mapping, Optional, Tuple
6
+
7
+ SAT_THRESHOLD = 1.0 - 1e-9 # a goal counts as verified when its value is >= this
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class Condition:
12
+ """A verifiable goal condition with weight ``weight``.
13
+
14
+ Mandatory conditions must all be verified for the run to succeed.
15
+ """
16
+
17
+ name: str
18
+ weight: float = 1.0
19
+ mandatory: bool = True
20
+ description: str = ""
21
+
22
+
23
+ @dataclass(frozen=True, eq=False)
24
+ class Action:
25
+ """A concrete operation: a tool name plus fixed arguments.
26
+
27
+ ``signature`` is the exact identity used for exact comparability, ``tool``
28
+ the action type. Equality and hash are those of ``(tool, args)``; the hash
29
+ is computed once, since actions are dictionary keys on the hot path.
30
+ """
31
+
32
+ tool: str
33
+ args: Tuple[Tuple[str, Any], ...] = ()
34
+
35
+ def __post_init__(self) -> None:
36
+ object.__setattr__(self, "_hash", hash((self.tool, self.args)))
37
+
38
+ def __hash__(self) -> int:
39
+ return self._hash # type: ignore[attr-defined]
40
+
41
+ def __eq__(self, other: object) -> bool:
42
+ if self is other:
43
+ return True
44
+ if other.__class__ is not self.__class__:
45
+ return NotImplemented
46
+ return self._hash == other._hash and self.tool == other.tool and self.args == other.args # type: ignore[attr-defined]
47
+
48
+ @classmethod
49
+ def of(cls, tool: str, args: Optional[Mapping[str, Any]] = None) -> "Action":
50
+ return cls(tool, tuple((args or {}).items()))
51
+
52
+ @property
53
+ def signature(self) -> Tuple[str, Tuple[Tuple[str, Any], ...]]:
54
+ return (self.tool, self.args)
55
+
56
+ def arg(self, key: str, default: Any = None) -> Any:
57
+ for k, val in self.args:
58
+ if k == key:
59
+ return val
60
+ return default
61
+
62
+ @property
63
+ def kwargs(self) -> Dict[str, Any]:
64
+ return dict(self.args)
65
+
66
+ def __str__(self) -> str:
67
+ inner = ", ".join(f"{k}={v}" for k, v in self.args)
68
+ return f"{self.tool}({inner})"
69
+
70
+
71
+ @dataclass(frozen=True)
72
+ class Semantics:
73
+ """Declared (prior) semantics of an action.
74
+
75
+ gain[c] declared fraction of the remaining deficiency of goal ``c`` one
76
+ execution closes (for a binary goal: its success probability).
77
+ harm[c] declared fraction of the achieved value of ``c`` one execution
78
+ destroys.
79
+ produces[p] declared probability that predicate ``p`` becomes true.
80
+ requires_predicates / requires_conditions: preconditions for admissibility.
81
+ cost declared cost per execution.
82
+ """
83
+
84
+ gain: Mapping[str, float] = field(default_factory=dict)
85
+ harm: Mapping[str, float] = field(default_factory=dict)
86
+ produces: Mapping[str, float] = field(default_factory=dict)
87
+ requires_predicates: FrozenSet[str] = frozenset()
88
+ requires_conditions: FrozenSet[str] = frozenset()
89
+ cost: float = 1.0
90
+
91
+
92
+ @dataclass(frozen=True)
93
+ class ActionSpec:
94
+ """An action, its declared semantics and (optionally) its comparability group.
95
+
96
+ Actions in the same ``group`` share online feedback when the controller is
97
+ configured with ``similarity="task"``.
98
+ """
99
+
100
+ action: Action
101
+ semantics: Semantics
102
+ group: Optional[Hashable] = None
103
+
104
+
105
+ @dataclass
106
+ class Observation:
107
+ """What the controller sees after each step: verified goal values in [0, 1]
108
+ and observable predicates."""
109
+
110
+ values: Dict[str, float]
111
+ predicates: Dict[str, bool] = field(default_factory=dict)
112
+
113
+ def copy(self) -> "Observation":
114
+ return Observation(dict(self.values), dict(self.predicates))
115
+
116
+
117
+ @dataclass
118
+ class ObsState:
119
+ """Internal controller state at step ``step``."""
120
+
121
+ v: Dict[str, float]
122
+ predicates: Dict[str, bool]
123
+ budget: float
124
+ step: int = 0
125
+
126
+ def copy(self) -> "ObsState":
127
+ return ObsState(dict(self.v), dict(self.predicates), self.budget, self.step)
128
+
129
+
130
+ @dataclass(frozen=True)
131
+ class Scores:
132
+ """Numerical justification of one candidate action at one step."""
133
+
134
+ Q: float
135
+ rank: float
136
+ exploit: float
137
+ gain: float
138
+ cost: float
139
+ bonus: float
140
+ continuation: float
141
+
142
+
143
+ @dataclass
144
+ class Decision:
145
+ """The controller's choice for the current step."""
146
+
147
+ step: int
148
+ action: Action
149
+ scores: Scores
150
+ candidates: List[Tuple[Action, Scores]] # every affordable admissible action, in declaration order
151
+ n_admissible: int
152
+ select_time: float
153
+
154
+ def ranked(self) -> List[Tuple[Action, Scores]]:
155
+ return sorted(self.candidates, key=lambda x: -x[1].rank)
156
+
157
+
158
+ def deficiency(conditions: Iterable[Condition], v: Mapping[str, float]) -> float:
159
+ """Observable deficiency Phi = sum_i w_i (1 - v_i)."""
160
+ return float(sum(c.weight * (1.0 - v.get(c.name, 0.0)) for c in conditions))
161
+
162
+
163
+ def all_mandatory_verified(conditions: Iterable[Condition], v: Mapping[str, float]) -> bool:
164
+ return all(v.get(c.name, 0.0) >= SAT_THRESHOLD for c in conditions if c.mandatory)
165
+
166
+
167
+ class Status:
168
+ """Termination reasons."""
169
+
170
+ RUNNING = "RUNNING"
171
+ SUCCESS = "SUCCESS" # every mandatory goal verified
172
+ STALLED = "STALLED" # no action has positive value (eq. 20)
173
+ BLOCKED = "BLOCKED" # no admissible action
174
+ BUDGET_EXHAUSTED = "BUDGET_EXHAUSTED" # nothing affordable / budget spent
175
+ STEP_LIMIT = "STEP_LIMIT"
src/fgao/workflow.py ADDED
@@ -0,0 +1,662 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Declarative workflow API: goals + tools, orchestrated by the FGAO controller.
2
+
3
+ LangGraph wires nodes with edges you write by hand. Here you declare *what
4
+ must become true* (goals with mechanical checks) and *what each tool claims to
5
+ do* (gain, harm, produced predicates, preconditions, cost); FGAO decides the
6
+ order at run time from those declarations plus online feedback, and stops
7
+ when the goals are verified or nothing left is worth its cost.
8
+
9
+ wf = Workflow()
10
+ wf.add_goal("has_data", check=lambda s: "rows" in s, weight=1)
11
+ wf.add_tool("load", load_fn, gain={"has_data": 0.9}, cost=1)
12
+ app = wf.compile(budget=10)
13
+ result = app.invoke({"path": "data.csv"})
14
+
15
+ State is any object you choose (a dict is the common case). Tools receive the
16
+ state and their declared arguments, may mutate it, and may return
17
+
18
+ None state was mutated in place
19
+ dict merged into a dict state (``state.update(d)``)
20
+ ToolResult(update, cost, error) the same, with a measured cost / error
21
+
22
+ Checks map the state to a value in [0, 1] (``bool`` is accepted).
23
+ """
24
+ from __future__ import annotations
25
+
26
+ import asyncio
27
+ import inspect
28
+ from collections.abc import MutableMapping
29
+ from concurrent.futures import ThreadPoolExecutor
30
+ from dataclasses import dataclass, field
31
+ from typing import Any, AsyncIterator, Callable, Dict, FrozenSet, Hashable, Iterable, Iterator, List, Mapping, Optional, Sequence, Union
32
+
33
+ from .controller import FGAOConfig, FGAOController
34
+ from .types import Action, ActionSpec, Condition, Decision, Observation, Semantics, Status
35
+
36
+
37
+ @dataclass
38
+ class ToolResult:
39
+ """Optional rich return value of a tool."""
40
+
41
+ update: Optional[Mapping[str, Any]] = None
42
+ cost: Optional[float] = None # measured cost; default: declared cost
43
+ error: Optional[str] = None
44
+
45
+
46
+ @dataclass
47
+ class Tool:
48
+ name: str
49
+ fn: Optional[Callable[..., Any]] # sync implementation (None for async-only tools)
50
+ action: Action
51
+ semantics: Semantics
52
+ group: Optional[Hashable] = None
53
+ description: str = ""
54
+ afn: Optional[Callable[..., Any]] = None # async implementation (used by the async API)
55
+ resources: FrozenSet[str] = frozenset() # tools sharing a resource never run in the same parallel round
56
+
57
+
58
+ @dataclass
59
+ class Goal:
60
+ name: str
61
+ check: Callable[[Any], Union[float, bool]]
62
+ weight: float = 1.0
63
+ mandatory: bool = True
64
+ description: str = ""
65
+
66
+
67
+ @dataclass
68
+ class Step:
69
+ """One executed step (yielded by ``stream``)."""
70
+
71
+ step: int
72
+ action: Action
73
+ decision: Decision
74
+ values_before: Dict[str, float]
75
+ values_after: Dict[str, float]
76
+ cost: float
77
+ budget_left: float
78
+ error: Optional[str] = None
79
+
80
+ @property
81
+ def tool(self) -> str:
82
+ return self.action.tool
83
+
84
+ def to_dict(self) -> Dict[str, Any]:
85
+ s = self.decision.scores
86
+ return {
87
+ "step": self.step, "action": str(self.action), "Q": s.Q, "predicted_gain": s.gain,
88
+ "continuation": s.continuation, "estimated_cost": s.cost, "cost": self.cost,
89
+ "budget_left": self.budget_left, "values": dict(self.values_after), "error": self.error,
90
+ }
91
+
92
+
93
+ @dataclass
94
+ class WorkflowResult:
95
+ """Final outcome of a run (also the last item yielded by ``stream``)."""
96
+
97
+ state: Any
98
+ status: str
99
+ success: bool
100
+ values: Dict[str, float]
101
+ cost: float
102
+ steps: List[Step] = field(default_factory=list)
103
+
104
+ def trace(self) -> List[Dict[str, Any]]:
105
+ return [s.to_dict() for s in self.steps]
106
+
107
+
108
+ Callback = Callable[[Step], None]
109
+
110
+
111
+ def _as_value(x: Union[float, bool]) -> float:
112
+ v = float(x)
113
+ if not 0.0 <= v <= 1.0:
114
+ raise ValueError(f"goal check returned {x!r}; expected a value in [0, 1]")
115
+ return v
116
+
117
+
118
+ class Workflow:
119
+ """Builder for an FGAO-orchestrated workflow."""
120
+
121
+ def __init__(self, name: str = "workflow") -> None:
122
+ self.name = name
123
+ self.goals: List[Goal] = []
124
+ self.predicates: Dict[str, Callable[[Any], bool]] = {}
125
+ self.tools: List[Tool] = []
126
+
127
+ # ------------------------------------------------------------ declaration
128
+ def add_goal(
129
+ self,
130
+ name: str,
131
+ check: Callable[[Any], Union[float, bool]],
132
+ *,
133
+ weight: float = 1.0,
134
+ mandatory: bool = True,
135
+ description: str = "",
136
+ ) -> "Workflow":
137
+ """Declare a verifiable goal. ``check(state)`` must use evidence, not a tool's own claim."""
138
+ if any(g.name == name for g in self.goals):
139
+ raise ValueError(f"goal {name!r} already declared")
140
+ self.goals.append(Goal(name, check, weight, mandatory, description))
141
+ return self
142
+
143
+ def add_predicate(self, name: str, fn: Callable[[Any], bool]) -> "Workflow":
144
+ """Declare an observable predicate (used in preconditions and ``produces``)."""
145
+ self.predicates[name] = fn
146
+ return self
147
+
148
+ def add_tool(
149
+ self,
150
+ name: str,
151
+ fn: Callable[..., Any],
152
+ *,
153
+ args: Optional[Mapping[str, Any]] = None,
154
+ cost: float = 1.0,
155
+ gain: Optional[Mapping[str, float]] = None,
156
+ harm: Optional[Mapping[str, float]] = None,
157
+ produces: Optional[Mapping[str, float]] = None,
158
+ requires: Iterable[str] = (),
159
+ requires_goals: Iterable[str] = (),
160
+ group: Optional[Hashable] = None,
161
+ description: str = "",
162
+ afn: Optional[Callable[..., Any]] = None,
163
+ resources: Iterable[str] = (),
164
+ ) -> Action:
165
+ """Declare one concrete call ``fn(state, **args)`` and its declared effects.
166
+
167
+ Register the same function several times with different ``args`` to
168
+ offer several variants (e.g. one per retrieval source). Variants that
169
+ share a ``group`` share online feedback.
170
+
171
+ ``fn`` may be an ``async def`` function (async-only tool), and ``afn``
172
+ an optional async twin of a sync ``fn``. The async API awaits async
173
+ implementations and runs sync ones in worker threads.
174
+ """
175
+ if inspect.iscoroutinefunction(fn):
176
+ fn, afn = None, fn
177
+ action = Action.of(name, args)
178
+ if any(t.action == action for t in self.tools):
179
+ raise ValueError(f"tool call {action} already declared")
180
+ sem = Semantics(
181
+ gain=dict(gain or {}), harm=dict(harm or {}), produces=dict(produces or {}),
182
+ requires_predicates=frozenset(requires), requires_conditions=frozenset(requires_goals), cost=float(cost),
183
+ )
184
+ self.tools.append(Tool(name, fn, action, sem, group, description, afn, frozenset(resources)))
185
+ return action
186
+
187
+ def add_agent(
188
+ self,
189
+ name: str,
190
+ agent: Any,
191
+ *,
192
+ inputs: Callable[[Any], Any],
193
+ output: Callable[[Any, Any], Optional[Mapping[str, Any]]],
194
+ measured_cost: Union[bool, Callable[[Any], float]] = True,
195
+ budget: Optional[Callable[[Any], Optional[float]]] = None,
196
+ **declared: Any,
197
+ ) -> Action:
198
+ """Register a sub-agent as one tool: anything with ``invoke`` (and optionally ``ainvoke``),
199
+ e.g. another compiled ``Workflow``, an ``FGAORAG``, a LangGraph graph or a LangChain agent.
200
+
201
+ inputs(state) -> the sub-agent's input; output(state, result) -> the update for this state.
202
+ measured_cost: True charges ``result.cost`` when the result has one (FGAO sub-workflows and
203
+ FGAORAG do), a function computes it from the result, False charges the declared ``cost``.
204
+ budget(state) -> per-call budget passed to FGAO sub-agents (``budget=`` keyword).
205
+ """
206
+ def _kw(state):
207
+ b = budget(state) if budget else None
208
+ return {"budget": b} if b is not None else {}
209
+
210
+ def _wrap(state, res):
211
+ if callable(measured_cost):
212
+ cost = float(measured_cost(res))
213
+ elif measured_cost and hasattr(res, "cost"):
214
+ cost = float(res.cost)
215
+ else:
216
+ cost = None
217
+ return ToolResult(update=output(state, res), cost=cost)
218
+
219
+ def fn(state, **_):
220
+ return _wrap(state, agent.invoke(inputs(state), **_kw(state)))
221
+
222
+ afn = None
223
+ if hasattr(agent, "ainvoke"):
224
+ async def afn(state, **_): # noqa: F811
225
+ return _wrap(state, await agent.ainvoke(inputs(state), **_kw(state)))
226
+
227
+ return self.add_tool(name, fn, afn=afn, **declared)
228
+
229
+ def tool(self, name: Optional[str] = None, **declared: Any) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
230
+ """Decorator form of ``add_tool``."""
231
+
232
+ def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
233
+ self.add_tool(name or fn.__name__, fn, **declared)
234
+ return fn
235
+
236
+ return deco
237
+
238
+ def validate(self) -> None:
239
+ goals = {g.name for g in self.goals}
240
+ if not goals:
241
+ raise ValueError("declare at least one goal")
242
+ if not self.tools:
243
+ raise ValueError("declare at least one tool")
244
+ for t in self.tools:
245
+ s = t.semantics
246
+ for c in list(s.gain) + list(s.harm) + list(s.requires_conditions):
247
+ if c not in goals:
248
+ raise ValueError(f"{t.action}: unknown goal {c!r}")
249
+ for p in list(s.produces) + list(s.requires_predicates):
250
+ if p not in self.predicates:
251
+ raise ValueError(f"{t.action}: unknown predicate {p!r} (declare it with add_predicate)")
252
+ for d in (s.gain, s.harm, s.produces):
253
+ for k, x in d.items():
254
+ if not 0.0 <= x <= 1.0:
255
+ raise ValueError(f"{t.action}: declared rate {k}={x} outside [0, 1]")
256
+ if s.cost < 0:
257
+ raise ValueError(f"{t.action}: negative cost")
258
+
259
+ def compile(
260
+ self,
261
+ config: Optional[FGAOConfig] = None,
262
+ *,
263
+ budget: float = float("inf"),
264
+ on_error: str = "raise",
265
+ max_parallel: int = 1,
266
+ independent: bool = True,
267
+ ) -> "CompiledWorkflow":
268
+ """Freeze the declarations into a runnable app.
269
+
270
+ on_error="raise" propagates tool exceptions; "record" charges the
271
+ declared cost, records the error and lets feedback learn from it.
272
+
273
+ max_parallel > 1 runs up to that many tool calls concurrently per round
274
+ (see ``FGAOController.select_batch``): the first is the v2 choice, further
275
+ slots take calls of positive value in the expected state that, with
276
+ independent=True, touch none of the batch's goals or predicates and share
277
+ no ``resources``. max_parallel=1 is sequential v2.
278
+ """
279
+ if on_error not in ("raise", "record"):
280
+ raise ValueError("on_error must be 'raise' or 'record'")
281
+ if max_parallel < 1:
282
+ raise ValueError("max_parallel must be >= 1")
283
+ self.validate()
284
+ return CompiledWorkflow(self, config or FGAOConfig(), budget, on_error, max_parallel, independent)
285
+
286
+
287
+ class CompiledWorkflow:
288
+ """A runnable workflow. Every run gets its own controller, so runs are independent
289
+ and can execute concurrently (``batch`` / ``abatch``) as long as the tools
290
+ themselves are thread-safe."""
291
+
292
+ def __init__(self, wf: Workflow, config: FGAOConfig, budget: float, on_error: str, max_parallel: int = 1,
293
+ independent: bool = True) -> None:
294
+ self.name = wf.name
295
+ self.config = config
296
+ self.budget = budget
297
+ self.on_error = on_error
298
+ self.max_parallel = max_parallel
299
+ self.independent = independent
300
+ self._goals = list(wf.goals)
301
+ self._preds = dict(wf.predicates)
302
+ self._tools = {t.action: t for t in wf.tools}
303
+ self._specs = [ActionSpec(t.action, t.semantics, t.group) for t in wf.tools]
304
+ self.conditions = [Condition(g.name, g.weight, g.mandatory, g.description) for g in self._goals]
305
+ self.async_only = [t.action for t in wf.tools if t.fn is None]
306
+
307
+ @property
308
+ def actions(self) -> List[Action]:
309
+ return [s.action for s in self._specs]
310
+
311
+ def observe(self, state: Any) -> Observation:
312
+ return Observation(
313
+ {g.name: _as_value(g.check(state)) for g in self._goals},
314
+ {p: bool(fn(state)) for p, fn in self._preds.items()},
315
+ )
316
+
317
+ def controller(self, *, budget: Optional[float] = None, seed: int = 0) -> FGAOController:
318
+ """A fresh step-wise controller over this workflow's goals and tools."""
319
+ return FGAOController(self.conditions, self._specs, self.config,
320
+ budget=self.budget if budget is None else budget, seed=seed)
321
+
322
+ # ------------------------------------------------------------- execution
323
+ def _call(self, tool: Tool, state: Any):
324
+ ok, out = self._raw(tool, state)
325
+ if not ok:
326
+ return out
327
+ return self._apply(tool, state, out)
328
+
329
+ def _raw(self, tool: Tool, state: Any):
330
+ """(True, output) or (False, (None, error)) without touching the state."""
331
+ if tool.fn is None:
332
+ raise TypeError(f"{tool.action} is async-only; use ainvoke / astream / abatch")
333
+ try:
334
+ return True, tool.fn(state, **tool.action.kwargs)
335
+ except Exception as e: # noqa: BLE001
336
+ if self.on_error == "raise":
337
+ raise
338
+ return False, (None, f"{type(e).__name__}: {e}")
339
+
340
+ async def _araw(self, tool: Tool, state: Any):
341
+ try:
342
+ if tool.afn is not None:
343
+ return True, await tool.afn(state, **tool.action.kwargs)
344
+ return True, await asyncio.to_thread(tool.fn, state, **tool.action.kwargs)
345
+ except asyncio.CancelledError:
346
+ raise
347
+ except Exception as e: # noqa: BLE001
348
+ if self.on_error == "raise":
349
+ raise
350
+ return False, (None, f"{type(e).__name__}: {e}")
351
+
352
+ def _conflicts(self, a: Action, b: Action) -> bool:
353
+ return bool(self._tools[a].resources & self._tools[b].resources)
354
+
355
+ def _finish_round(self, ctrl, state, obs, batch, outs, callbacks):
356
+ results = []
357
+ for d, (ok, out) in zip(batch, outs): # merge updates in batch order
358
+ results.append(self._apply(self._tools[d.action], state, out) if ok else out)
359
+ after = self.observe(state)
360
+ recs = ctrl.update_batch([d.action for d in batch], after, [c for c, _ in results], [e for _, e in results])
361
+ steps = []
362
+ for d, rec, (_, err) in zip(batch, recs, results):
363
+ st = Step(rec["step"], d.action, d, dict(obs.values), dict(after.values), rec["cost"], rec["budget_left"], err)
364
+ steps.append(st)
365
+ for cb in callbacks:
366
+ cb(st)
367
+ return after, steps
368
+
369
+ async def _acall(self, tool: Tool, state: Any):
370
+ try:
371
+ if tool.afn is not None:
372
+ out = await tool.afn(state, **tool.action.kwargs)
373
+ else:
374
+ out = await asyncio.to_thread(tool.fn, state, **tool.action.kwargs)
375
+ except asyncio.CancelledError:
376
+ raise
377
+ except Exception as e: # noqa: BLE001
378
+ if self.on_error == "raise":
379
+ raise
380
+ return None, f"{type(e).__name__}: {e}"
381
+ return self._apply(tool, state, out)
382
+
383
+ def _apply(self, tool: Tool, state: Any, out: Any):
384
+ cost, err, upd = None, None, None
385
+ if isinstance(out, ToolResult):
386
+ upd, cost, err = out.update, out.cost, out.error
387
+ elif isinstance(out, Mapping):
388
+ upd = out
389
+ elif out is not None:
390
+ raise TypeError(f"{tool.action} returned {type(out).__name__}; expected None, dict or ToolResult")
391
+ if upd:
392
+ if not isinstance(state, MutableMapping):
393
+ raise TypeError(f"{tool.action} returned an update but the state is not a mutable mapping")
394
+ state.update(upd)
395
+ return cost, err
396
+
397
+ def stream(
398
+ self,
399
+ state: Any,
400
+ *,
401
+ seed: int = 0,
402
+ budget: Optional[float] = None,
403
+ callbacks: Sequence[Callback] = (),
404
+ ) -> Iterator[Union[Step, WorkflowResult]]:
405
+ """Run step by step, yielding each executed ``Step`` and finally the ``WorkflowResult``."""
406
+ ctrl = self.controller(budget=budget, seed=seed)
407
+ obs = self.observe(state)
408
+ ctrl.reset(obs)
409
+ steps: List[Step] = []
410
+ if self.max_parallel > 1:
411
+ with ThreadPoolExecutor(max_workers=self.max_parallel) as ex:
412
+ while ctrl.should_stop() is None:
413
+ batch = ctrl.select_batch(self.max_parallel, self._conflicts, self.independent)
414
+ outs = list(ex.map(lambda d: self._raw(self._tools[d.action], state), batch))
415
+ obs, new = self._finish_round(ctrl, state, obs, batch, outs, callbacks)
416
+ steps.extend(new)
417
+ yield from new
418
+ yield WorkflowResult(state, ctrl.status, ctrl.status == Status.SUCCESS, dict(ctrl.v), ctrl.spent, steps)
419
+ return
420
+ while ctrl.should_stop() is None:
421
+ d = ctrl.select_action()
422
+ tool = self._tools[d.action]
423
+ cost, err = self._call(tool, state)
424
+ after = self.observe(state)
425
+ ctrl.update(d.action, after, cost, err)
426
+ rec = ctrl.history[-1]
427
+ st = Step(d.step, d.action, d, dict(obs.values), dict(after.values), rec["cost"], ctrl.budget, err)
428
+ obs = after
429
+ steps.append(st)
430
+ for cb in callbacks:
431
+ cb(st)
432
+ yield st
433
+ yield WorkflowResult(state, ctrl.status, ctrl.status == Status.SUCCESS, dict(ctrl.v), ctrl.spent, steps)
434
+
435
+ def start(self, state: Any, *, seed: int = 0, budget: Optional[float] = None,
436
+ interrupt_before: Iterable[str] = (), callbacks: Sequence[Callback] = ()) -> "Run":
437
+ """A step-by-step run that can pause for approval and be checkpointed (see ``Run``).
438
+
439
+ A Run executes one call per step (sequential v2), whatever ``max_parallel`` is.
440
+ """
441
+ return Run(self, state, seed=seed, budget=budget, interrupt_before=interrupt_before, callbacks=callbacks)
442
+
443
+ def resume(self, snapshot: Mapping[str, Any], state: Any, *, interrupt_before: Iterable[str] = (),
444
+ callbacks: Sequence[Callback] = ()) -> "Run":
445
+ """Continue a run from ``Run.snapshot()`` with the (restored) application state."""
446
+ run = Run(self, state, seed=snapshot["seed"], budget=snapshot["controller"]["budget0"],
447
+ interrupt_before=interrupt_before, callbacks=callbacks, _snapshot=snapshot)
448
+ return run
449
+
450
+ def invoke(self, state: Any, *, seed: int = 0, budget: Optional[float] = None,
451
+ callbacks: Sequence[Callback] = ()) -> WorkflowResult:
452
+ """Run to termination and return the ``WorkflowResult``."""
453
+ out = None
454
+ for out in self.stream(state, seed=seed, budget=budget, callbacks=callbacks):
455
+ pass
456
+ return out # type: ignore[return-value]
457
+
458
+ def batch(self, states: Sequence[Any], *, max_concurrency: int = 8, seed: int = 0,
459
+ budget: Optional[float] = None) -> List[WorkflowResult]:
460
+ """Run many independent states concurrently in threads; results keep input order."""
461
+ if max_concurrency <= 1:
462
+ return [self.invoke(s, seed=seed, budget=budget) for s in states]
463
+ with ThreadPoolExecutor(max_workers=max_concurrency) as ex:
464
+ return list(ex.map(lambda s: self.invoke(s, seed=seed, budget=budget), states))
465
+
466
+ async def astream(
467
+ self,
468
+ state: Any,
469
+ *,
470
+ seed: int = 0,
471
+ budget: Optional[float] = None,
472
+ callbacks: Sequence[Callback] = (),
473
+ ) -> AsyncIterator[Union[Step, WorkflowResult]]:
474
+ """Native async run: async tools are awaited, sync tools run in worker threads.
475
+
476
+ Makes exactly the same decisions as ``stream``; cancelling the task
477
+ cancels the tool call in flight.
478
+ """
479
+ ctrl = self.controller(budget=budget, seed=seed)
480
+ obs = self.observe(state)
481
+ ctrl.reset(obs)
482
+ steps: List[Step] = []
483
+ if self.max_parallel > 1:
484
+ while ctrl.should_stop() is None:
485
+ batch = ctrl.select_batch(self.max_parallel, self._conflicts, self.independent)
486
+ outs = await asyncio.gather(*(self._araw(self._tools[d.action], state) for d in batch))
487
+ obs, new = self._finish_round(ctrl, state, obs, batch, outs, callbacks)
488
+ steps.extend(new)
489
+ for st in new:
490
+ yield st
491
+ yield WorkflowResult(state, ctrl.status, ctrl.status == Status.SUCCESS, dict(ctrl.v), ctrl.spent, steps)
492
+ return
493
+ while ctrl.should_stop() is None:
494
+ d = ctrl.select_action()
495
+ tool = self._tools[d.action]
496
+ cost, err = await self._acall(tool, state)
497
+ after = self.observe(state)
498
+ ctrl.update(d.action, after, cost, err)
499
+ rec = ctrl.history[-1]
500
+ st = Step(d.step, d.action, d, dict(obs.values), dict(after.values), rec["cost"], ctrl.budget, err)
501
+ obs = after
502
+ steps.append(st)
503
+ for cb in callbacks:
504
+ cb(st)
505
+ yield st
506
+ yield WorkflowResult(state, ctrl.status, ctrl.status == Status.SUCCESS, dict(ctrl.v), ctrl.spent, steps)
507
+
508
+ async def ainvoke(self, state: Any, *, seed: int = 0, budget: Optional[float] = None,
509
+ callbacks: Sequence[Callback] = ()) -> WorkflowResult:
510
+ out = None
511
+ async for out in self.astream(state, seed=seed, budget=budget, callbacks=callbacks):
512
+ pass
513
+ return out # type: ignore[return-value]
514
+
515
+ async def abatch(self, states: Sequence[Any], *, max_concurrency: int = 64, **kw: Any) -> List[WorkflowResult]:
516
+ sem = asyncio.Semaphore(max(1, max_concurrency))
517
+
518
+ async def one(s: Any) -> WorkflowResult:
519
+ async with sem:
520
+ return await self.ainvoke(s, **kw)
521
+
522
+ return list(await asyncio.gather(*(one(s) for s in states)))
523
+
524
+
525
+ @dataclass
526
+ class Interrupt:
527
+ """Returned by ``Run.step`` instead of executing a tool listed in ``interrupt_before``."""
528
+
529
+ step: int
530
+ action: Action
531
+ decision: Decision
532
+
533
+
534
+ class Run:
535
+ """A resumable, interruptible workflow run.
536
+
537
+ run = app.start(state, interrupt_before=["send_email"])
538
+ out = run.run() # runs until done or an Interrupt
539
+ if isinstance(out, Interrupt):
540
+ save(run.snapshot(), state) # e.g. wait for a human
541
+ run.approve() # or run.reject() to exclude that call
542
+ out = run.run()
543
+
544
+ ``snapshot()`` is JSON-serialisable; ``app.resume(snapshot, state)`` continues
545
+ with exactly the decisions the uninterrupted run would make. The application
546
+ state itself is yours to persist alongside it.
547
+ """
548
+
549
+ def __init__(self, app: CompiledWorkflow, state: Any, *, seed: int, budget: Optional[float],
550
+ interrupt_before: Iterable[str], callbacks: Sequence[Callback], _snapshot: Optional[Mapping] = None):
551
+ self.app, self.state, self.seed = app, state, seed
552
+ self.interrupt_before = set(interrupt_before)
553
+ self.callbacks = list(callbacks)
554
+ self.ctrl = app.controller(budget=budget, seed=seed)
555
+ self.steps: List[Step] = []
556
+ self.interrupted: Optional[Interrupt] = None
557
+ self._approved: Optional[Action] = None
558
+ self.result: Optional[WorkflowResult] = None
559
+ if _snapshot is None:
560
+ self._obs = app.observe(state)
561
+ self.ctrl.reset(self._obs)
562
+ else:
563
+ self.ctrl.restore(_snapshot["controller"])
564
+ self._obs = Observation(dict(self.ctrl.v), dict(self.ctrl.preds))
565
+ if _snapshot.get("interrupted") is not None:
566
+ d = self.ctrl.select_action()
567
+ if d.action != self.app.actions[_snapshot["interrupted"]]: # pragma: no cover - guarded by determinism
568
+ raise RuntimeError("snapshot does not reproduce the interrupted decision")
569
+ self.interrupted = Interrupt(d.step, d.action, d)
570
+ if _snapshot.get("approved") is not None:
571
+ self._approved = self.app.actions[_snapshot["approved"]]
572
+
573
+ @property
574
+ def done(self) -> bool:
575
+ return self.result is not None
576
+
577
+ @property
578
+ def status(self) -> str:
579
+ return self.result.status if self.result else (
580
+ "INTERRUPTED" if self.interrupted else self.ctrl.status)
581
+
582
+ def _finish(self) -> WorkflowResult:
583
+ self.result = WorkflowResult(self.state, self.ctrl.status, self.ctrl.status == Status.SUCCESS,
584
+ dict(self.ctrl.v), self.ctrl.spent, list(self.steps))
585
+ return self.result
586
+
587
+ def _next(self):
588
+ """Decision to execute now, or an Interrupt / final result."""
589
+ if self.result is not None:
590
+ return self.result
591
+ if self.interrupted is not None and self._approved is None:
592
+ return self.interrupted
593
+ if self.ctrl.should_stop() is not None:
594
+ return self._finish()
595
+ d = self.ctrl.select_action()
596
+ gated = d.action.tool in self.interrupt_before or str(d.action) in self.interrupt_before
597
+ if gated and self._approved != d.action:
598
+ self.interrupted = Interrupt(d.step, d.action, d)
599
+ return self.interrupted
600
+ return d
601
+
602
+ def _record(self, d: Decision, cost, err) -> Step:
603
+ after = self.app.observe(self.state)
604
+ self.ctrl.update(d.action, after, cost, err)
605
+ rec = self.ctrl.history[-1]
606
+ st = Step(d.step, d.action, d, dict(self._obs.values), dict(after.values), rec["cost"], self.ctrl.budget, err)
607
+ self._obs = after
608
+ self.steps.append(st)
609
+ self.interrupted, self._approved = None, None
610
+ for cb in self.callbacks:
611
+ cb(st)
612
+ return st
613
+
614
+ def step(self) -> Union[Step, Interrupt, WorkflowResult]:
615
+ """Execute one tool call (sync); returns the Step, an Interrupt, or the final result."""
616
+ d = self._next()
617
+ if not isinstance(d, Decision):
618
+ return d
619
+ cost, err = self.app._call(self.app._tools[d.action], self.state)
620
+ return self._record(d, cost, err)
621
+
622
+ async def astep(self) -> Union[Step, Interrupt, WorkflowResult]:
623
+ d = self._next()
624
+ if not isinstance(d, Decision):
625
+ return d
626
+ cost, err = await self.app._acall(self.app._tools[d.action], self.state)
627
+ return self._record(d, cost, err)
628
+
629
+ def run(self) -> Union[WorkflowResult, Interrupt]:
630
+ """Step until the run ends or pauses."""
631
+ while True:
632
+ out = self.step()
633
+ if not isinstance(out, Step):
634
+ return out
635
+
636
+ async def arun(self) -> Union[WorkflowResult, Interrupt]:
637
+ while True:
638
+ out = await self.astep()
639
+ if not isinstance(out, Step):
640
+ return out
641
+
642
+ def approve(self) -> None:
643
+ """Allow the interrupted call; it executes on the next ``step`` / ``run``."""
644
+ if self.interrupted is None:
645
+ raise RuntimeError("nothing to approve")
646
+ self._approved = self.interrupted.action
647
+
648
+ def reject(self) -> None:
649
+ """Exclude the interrupted call for the rest of the run; FGAO picks something else."""
650
+ if self.interrupted is None:
651
+ raise RuntimeError("nothing to reject")
652
+ self.ctrl.block(self.interrupted.action)
653
+ self.interrupted, self._approved = None, None
654
+
655
+ def snapshot(self) -> Dict[str, Any]:
656
+ """JSON-serialisable checkpoint of the orchestration (not of your application state)."""
657
+ index = {a: i for i, a in enumerate(self.app.actions)}
658
+ return {
659
+ "workflow": self.app.name, "seed": self.seed, "controller": self.ctrl.snapshot(),
660
+ "interrupted": index[self.interrupted.action] if self.interrupted else None,
661
+ "approved": index[self._approved] if self._approved is not None else None,
662
+ }