Upload 27 files
Browse files- data/kb.jsonl +3 -0
- src/fgao/__init__.py +29 -0
- src/fgao/controller.py +902 -0
- src/fgao/estimator.py +162 -0
- src/fgao/integrations/__init__.py +4 -0
- src/fgao/integrations/huggingface.py +143 -0
- src/fgao/integrations/langchain.py +152 -0
- src/fgao/integrations/langgraph.py +50 -0
- src/fgao/integrations/mcp.py +93 -0
- src/fgao/integrations/providers.py +98 -0
- src/fgao/py.typed +0 -0
- src/fgao/rag/__init__.py +15 -0
- src/fgao/rag/components.py +76 -0
- src/fgao/rag/documents.py +65 -0
- src/fgao/rag/interfaces.py +35 -0
- src/fgao/rag/llms.py +107 -0
- src/fgao/rag/pipeline.py +442 -0
- src/fgao/rag/prompts.py +79 -0
- src/fgao/rag/retrievers.py +154 -0
- src/fgao/resilience.py +206 -0
- src/fgao/server/__init__.py +11 -0
- src/fgao/server/app.py +352 -0
- src/fgao/server/cli.py +94 -0
- src/fgao/server/config.py +225 -0
- src/fgao/server/metrics.py +111 -0
- src/fgao/types.py +175 -0
- src/fgao/workflow.py +662 -0
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 |
+
}
|