fivefold 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fivefold/__init__.py +4 -0
- fivefold/_data/db/bootstrap.sql +26 -0
- fivefold/_data/db/migrations/0001_schemas.sql +67 -0
- fivefold/_data/db/migrations/0002_gateway.sql +224 -0
- fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
- fivefold/_data/db/migrations/0004_harness.sql +141 -0
- fivefold/_data/db/migrations/0005_sim.sql +679 -0
- fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
- fivefold/_data/db/migrations/0007_eval.sql +33 -0
- fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
- fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
- fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
- fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
- fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
- fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
- fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
- fivefold/_data/db/registry/0001_registry.sql +31 -0
- fivefold/_data/faults/expected.yaml +406 -0
- fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
- fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
- fivefold/agents/__init__.py +7 -0
- fivefold/agents/branch.py +187 -0
- fivefold/agents/checkpoint.py +77 -0
- fivefold/agents/connection.py +153 -0
- fivefold/agents/live.py +492 -0
- fivefold/agents/policy.py +426 -0
- fivefold/agents/remote.py +333 -0
- fivefold/agents/replay.py +170 -0
- fivefold/agents/scripted.py +122 -0
- fivefold/agents/tools.py +229 -0
- fivefold/agents/worker.py +164 -0
- fivefold/domain/__init__.py +5 -0
- fivefold/domain/api.py +517 -0
- fivefold/domain/authority.py +149 -0
- fivefold/domain/contracts.py +80 -0
- fivefold/domain/identity.py +113 -0
- fivefold/domain/prices.py +178 -0
- fivefold/domain/report.py +92 -0
- fivefold/domain/rules.py +346 -0
- fivefold/domain/scenario.py +524 -0
- fivefold/evaluator/__init__.py +155 -0
- fivefold/evaluator/__main__.py +127 -0
- fivefold/evaluator/authorization.py +146 -0
- fivefold/evaluator/checks.py +331 -0
- fivefold/evaluator/evaluate.py +109 -0
- fivefold/evaluator/evidence.py +392 -0
- fivefold/evaluator/freshness.py +136 -0
- fivefold/evaluator/liveness.py +236 -0
- fivefold/evaluator/load.py +354 -0
- fivefold/evaluator/metrics.py +95 -0
- fivefold/evaluator/records.py +452 -0
- fivefold/evaluator/recovery.py +209 -0
- fivefold/evaluator/report.py +1096 -0
- fivefold/evaluator/result.py +344 -0
- fivefold/evaluator/store.py +83 -0
- fivefold/faults/__init__.py +5 -0
- fivefold/faults/catalog.py +278 -0
- fivefold/faults/plan.py +538 -0
- fivefold/gateway/__init__.py +6 -0
- fivefold/gateway/admin.py +179 -0
- fivefold/gateway/admin_api.py +398 -0
- fivefold/gateway/codec.py +372 -0
- fivefold/gateway/destination.py +64 -0
- fivefold/gateway/dispatcher.py +379 -0
- fivefold/gateway/freshness.py +83 -0
- fivefold/gateway/invariants.py +761 -0
- fivefold/gateway/memory.py +277 -0
- fivefold/gateway/pg_store.py +657 -0
- fivefold/gateway/records.py +592 -0
- fivefold/gateway/server.py +102 -0
- fivefold/gateway/sim_client.py +295 -0
- fivefold/gateway/state_machine.py +376 -0
- fivefold/gateway/steps.py +897 -0
- fivefold/gateway/store.py +635 -0
- fivefold/gateway/tools.py +424 -0
- fivefold/gateway/twin.py +199 -0
- fivefold/gateway/wire.py +138 -0
- fivefold/harness/__init__.py +6 -0
- fivefold/harness/actors.py +230 -0
- fivefold/harness/cells.py +303 -0
- fivefold/harness/clock.py +209 -0
- fivefold/harness/demo.py +397 -0
- fivefold/harness/fault_effects.py +122 -0
- fivefold/harness/live_options.py +159 -0
- fivefold/harness/log.py +540 -0
- fivefold/harness/mcp_link.py +409 -0
- fivefold/harness/migrations.py +520 -0
- fivefold/harness/models.py +368 -0
- fivefold/harness/registry.py +105 -0
- fivefold/harness/reports.py +100 -0
- fivefold/harness/rng.py +57 -0
- fivefold/harness/run.py +881 -0
- fivefold/harness/scheduler.py +441 -0
- fivefold/harness/sim_points.py +215 -0
- fivefold/harness/split/__init__.py +34 -0
- fivefold/harness/split/__main__.py +275 -0
- fivefold/harness/split/credentials.py +74 -0
- fivefold/harness/split/faults.py +75 -0
- fivefold/harness/split/gateway.py +769 -0
- fivefold/harness/split/hops.py +291 -0
- fivefold/harness/split/lifecycle.py +322 -0
- fivefold/harness/split/rundir.py +152 -0
- fivefold/harness/split/service.py +157 -0
- fivefold/harness/split/simulator.py +432 -0
- fivefold/harness/study.py +643 -0
- fivefold/harness/transport.py +533 -0
- fivefold/paths.py +24 -0
- fivefold/py.typed +0 -0
- fivefold/recorder/__init__.py +18 -0
- fivefold/recorder/__main__.py +308 -0
- fivefold/recorder/cassette.py +322 -0
- fivefold/recorder/playback.py +316 -0
- fivefold/recorder/recording.py +133 -0
- fivefold/sim/__init__.py +37 -0
- fivefold/sim/config.py +52 -0
- fivefold/sim/endpoint.py +176 -0
- fivefold/sim/ledger.py +583 -0
- fivefold/sim/service.py +834 -0
- fivefold/viewer/__init__.py +14 -0
- fivefold/viewer/__main__.py +75 -0
- fivefold/viewer/app.py +122 -0
- fivefold/viewer/records.py +108 -0
- fivefold/viewer/source.py +196 -0
- fivefold/viewer/timeline.py +61 -0
- fivefold-0.1.0.dist-info/METADATA +169 -0
- fivefold-0.1.0.dist-info/RECORD +128 -0
- fivefold-0.1.0.dist-info/WHEEL +4 -0
- fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
fivefold/agents/tools.py
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
"""The agent's tools: the gateway's over MCP in G modes, the simulator's in B0 (0008).
|
|
2
|
+
|
|
3
|
+
Every tool returns the destination's answer to the model as JSON text, successes and
|
|
4
|
+
refusals alike. A tool raises only on a transport failure or a server error, so that
|
|
5
|
+
LangGraph's retry policy applies, as it would to an HTTP client (0008):
|
|
6
|
+
|
|
7
|
+
- no answer within the call's timeout raises `TransportTimeout`, which is not an
|
|
8
|
+
`OSError`, so the default retry predicate retries it;
|
|
9
|
+
- in G modes, a connection to the gateway that closes while a call waits raises
|
|
10
|
+
`ConnectionError`, which the default predicate also retries; the next call opens a new
|
|
11
|
+
connection (`fivefold.agents.connection`);
|
|
12
|
+
- the gateway's `gateway_timeout` tool error, its 504, raises `ServerError`.
|
|
13
|
+
|
|
14
|
+
The timeout of a call is the tool's declared server-side wait plus T (0005, 0008): T for
|
|
15
|
+
reads and simulator calls, `tool_wait_ms` plus T for gateway writes, and `wait_ms` plus T
|
|
16
|
+
for calls that wait. Timeouts run on the scheduler's virtual clock.
|
|
17
|
+
|
|
18
|
+
A status tool's wait is at most the run's `max_wait_ms` (0005). B0's
|
|
19
|
+
`get_approval_status` refuses a longer wait before anything is sent, as it refuses any
|
|
20
|
+
other invalid argument: the request model raises pydantic's `ValidationError`, which the
|
|
21
|
+
tool node hands back to the model (0008). In G modes the gateway refuses it; the
|
|
22
|
+
agent's own timeout for a gateway status call counts at most `max_wait_ms`, so the call
|
|
23
|
+
ends even when the gateway does not answer.
|
|
24
|
+
|
|
25
|
+
Checked in langchain-core 1.8.0: `StructuredTool.from_function(coroutine=, name=,
|
|
26
|
+
description=, args_schema=)` takes a Pydantic model or a JSON Schema dict
|
|
27
|
+
(`ArgsSchema`, `langchain_core/tools/base.py`), and passes the tool call's arguments to
|
|
28
|
+
the coroutine as keyword arguments.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import json
|
|
34
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
35
|
+
from dataclasses import dataclass
|
|
36
|
+
from typing import Any, Protocol
|
|
37
|
+
|
|
38
|
+
import mcp_types as types
|
|
39
|
+
from langchain_core.tools import BaseTool, StructuredTool
|
|
40
|
+
from pydantic import BaseModel
|
|
41
|
+
|
|
42
|
+
from fivefold.domain.api import (
|
|
43
|
+
GetApprovalStatus,
|
|
44
|
+
GetBudget,
|
|
45
|
+
GetInventory,
|
|
46
|
+
GetOrderStatus,
|
|
47
|
+
GetQuote,
|
|
48
|
+
GetReservationStatus,
|
|
49
|
+
ListSuppliers,
|
|
50
|
+
RequestApproval,
|
|
51
|
+
ReserveInventory,
|
|
52
|
+
SubmitPurchaseOrder,
|
|
53
|
+
WaitLimit,
|
|
54
|
+
)
|
|
55
|
+
from fivefold.domain.report import FinalReport
|
|
56
|
+
from fivefold.harness.scheduler import Scheduler
|
|
57
|
+
from fivefold.harness.transport import Calls
|
|
58
|
+
|
|
59
|
+
GATEWAY_WRITES = frozenset({"submit_purchase_order", "reserve_inventory"})
|
|
60
|
+
SIMULATOR = "simulator"
|
|
61
|
+
REPORT_SINK = "report_sink"
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class ServerError(Exception):
|
|
65
|
+
"""The destination answered with a server error; the framework's retry applies."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class Timeouts:
|
|
70
|
+
"""The parts of a call's timeout, in virtual ms (0005)."""
|
|
71
|
+
|
|
72
|
+
t_ms: int
|
|
73
|
+
"""T: the destination's dispatch timeout."""
|
|
74
|
+
tool_wait_ms: int
|
|
75
|
+
"""How long a gateway write waits before it answers."""
|
|
76
|
+
max_wait_ms: int = 60_000
|
|
77
|
+
"""The longest `wait_ms` a status tool accepts: the scenario's `max_wait_ms`."""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
# G modes: the gateway's tools over MCP ------------------------------------------------------
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
class ToolCaller(Protocol):
|
|
84
|
+
"""An agent worker's MCP connection to the gateway, as its tools use it: in-process
|
|
85
|
+
(`fivefold.agents.connection`) or over streamable HTTP (`fivefold.agents.remote`)."""
|
|
86
|
+
|
|
87
|
+
async def call_tool(
|
|
88
|
+
self, name: str, arguments: dict[str, Any], timeout_ms: int
|
|
89
|
+
) -> types.CallToolResult:
|
|
90
|
+
"""Call a tool, waiting at most `timeout_ms` for its result."""
|
|
91
|
+
...
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def gateway_tools(
|
|
95
|
+
connection: ToolCaller,
|
|
96
|
+
listed: types.ListToolsResult,
|
|
97
|
+
timeouts: Timeouts,
|
|
98
|
+
) -> list[BaseTool]:
|
|
99
|
+
"""The gateway's tools, as `tools/list` described them."""
|
|
100
|
+
return [_gateway_tool(connection, tool, timeouts) for tool in listed.tools]
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _gateway_tool(connection: ToolCaller, tool: types.Tool, timeouts: Timeouts) -> BaseTool:
|
|
104
|
+
name = tool.name
|
|
105
|
+
|
|
106
|
+
async def call(**arguments: Any) -> str:
|
|
107
|
+
if name in GATEWAY_WRITES:
|
|
108
|
+
timeout = timeouts.tool_wait_ms + timeouts.t_ms
|
|
109
|
+
else:
|
|
110
|
+
wait_ms = int(arguments.get("wait_ms", 0) or 0)
|
|
111
|
+
timeout = min(wait_ms, timeouts.max_wait_ms) + timeouts.t_ms
|
|
112
|
+
result = await connection.call_tool(name, arguments, timeout)
|
|
113
|
+
text = "".join(c.text for c in result.content if isinstance(c, types.TextContent))
|
|
114
|
+
if result.is_error and _error_code(text) == "gateway_timeout":
|
|
115
|
+
raise ServerError(f"{name}: {text}")
|
|
116
|
+
return text
|
|
117
|
+
|
|
118
|
+
return StructuredTool.from_function(
|
|
119
|
+
coroutine=call,
|
|
120
|
+
name=name,
|
|
121
|
+
description=tool.description or name,
|
|
122
|
+
args_schema=dict(tool.input_schema),
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def _error_code(text: str) -> str | None:
|
|
127
|
+
try:
|
|
128
|
+
body = json.loads(text)
|
|
129
|
+
except json.JSONDecodeError:
|
|
130
|
+
return None
|
|
131
|
+
return str(body.get("error")) if isinstance(body, dict) else None
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
# B0: the simulator's API and the report sink ------------------------------------------------
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
@dataclass(frozen=True)
|
|
138
|
+
class _ApiTool:
|
|
139
|
+
name: str
|
|
140
|
+
description: str
|
|
141
|
+
model: type[BaseModel]
|
|
142
|
+
receiver: str = SIMULATOR
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
BASELINE_TOOLS: tuple[_ApiTool, ...] = (
|
|
146
|
+
_ApiTool("get_quote", "Read a supplier's quote for a sku.", GetQuote),
|
|
147
|
+
_ApiTool("list_suppliers", "Read the supplier directory.", ListSuppliers),
|
|
148
|
+
_ApiTool("get_budget", "Read a cost center's budget.", GetBudget),
|
|
149
|
+
_ApiTool("get_inventory", "Read a sku's stock in a warehouse.", GetInventory),
|
|
150
|
+
_ApiTool("request_approval", "Request approval for an order.", RequestApproval),
|
|
151
|
+
_ApiTool(
|
|
152
|
+
"get_approval_status",
|
|
153
|
+
"An approval's status. Waits up to wait_ms for a decision.",
|
|
154
|
+
GetApprovalStatus,
|
|
155
|
+
),
|
|
156
|
+
_ApiTool("submit_purchase_order", "Place a purchase order.", SubmitPurchaseOrder),
|
|
157
|
+
_ApiTool("reserve_inventory", "Reserve stock.", ReserveInventory),
|
|
158
|
+
_ApiTool(
|
|
159
|
+
"submit_final_report",
|
|
160
|
+
"Report, for every intent of the task, whether it is done, not done or unknown.",
|
|
161
|
+
FinalReport,
|
|
162
|
+
REPORT_SINK,
|
|
163
|
+
),
|
|
164
|
+
)
|
|
165
|
+
"""B0's tools at every contract level (0008)."""
|
|
166
|
+
|
|
167
|
+
STATUS_TOOLS: tuple[_ApiTool, ...] = (
|
|
168
|
+
_ApiTool("get_order_status", "Which purchase orders exist for an intent.", GetOrderStatus),
|
|
169
|
+
_ApiTool(
|
|
170
|
+
"get_reservation_status", "Which reservations exist for an intent.", GetReservationStatus
|
|
171
|
+
),
|
|
172
|
+
)
|
|
173
|
+
"""B0's status tools, at C1 only (0008)."""
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def baseline_tools(
|
|
177
|
+
transport: Calls,
|
|
178
|
+
scheduler: Scheduler,
|
|
179
|
+
timeouts: Timeouts,
|
|
180
|
+
*,
|
|
181
|
+
worker: str,
|
|
182
|
+
status: bool,
|
|
183
|
+
) -> list[BaseTool]:
|
|
184
|
+
"""B0's tools for one agent worker; `status` adds C1's status tools."""
|
|
185
|
+
tools = BASELINE_TOOLS + (STATUS_TOOLS if status else ())
|
|
186
|
+
return [_baseline_tool(transport, scheduler, timeouts, spec, worker) for spec in tools]
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def _baseline_tool(
|
|
190
|
+
transport: Calls, scheduler: Scheduler, timeouts: Timeouts, spec: _ApiTool, worker: str
|
|
191
|
+
) -> BaseTool:
|
|
192
|
+
async def call(**arguments: Any) -> str:
|
|
193
|
+
limit = WaitLimit(timeouts.max_wait_ms)
|
|
194
|
+
request = spec.model.model_validate(_plain(arguments), context=limit)
|
|
195
|
+
body = request.model_dump(mode="json")
|
|
196
|
+
wait_ms = int(body.get("wait_ms", 0) or 0)
|
|
197
|
+
reply = await transport.call(
|
|
198
|
+
hop="agent_sim",
|
|
199
|
+
sender=worker,
|
|
200
|
+
receiver=spec.receiver,
|
|
201
|
+
api=spec.name,
|
|
202
|
+
body=body,
|
|
203
|
+
timeout_ms=wait_ms + timeouts.t_ms,
|
|
204
|
+
intent_id=_text(body.get("intent_id")),
|
|
205
|
+
idempotency_key=_text(body.get("idempotency_key")),
|
|
206
|
+
)
|
|
207
|
+
return json.dumps(reply.body, sort_keys=True)
|
|
208
|
+
|
|
209
|
+
return StructuredTool.from_function(
|
|
210
|
+
coroutine=call, name=spec.name, description=spec.description, args_schema=spec.model
|
|
211
|
+
)
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
def _plain(value: object) -> object:
|
|
215
|
+
"""Arguments as plain data: models a tool layer built become dicts again."""
|
|
216
|
+
if isinstance(value, BaseModel):
|
|
217
|
+
return value.model_dump(mode="json")
|
|
218
|
+
if isinstance(value, Mapping):
|
|
219
|
+
return {str(k): _plain(v) for k, v in value.items()}
|
|
220
|
+
if isinstance(value, list | tuple):
|
|
221
|
+
return [_plain(v) for v in value]
|
|
222
|
+
return value
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def _text(value: object) -> str | None:
|
|
226
|
+
return value if isinstance(value, str) else None
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
ToolFactory = Callable[[], Awaitable[list[BaseTool]]]
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""An agent worker: the shared LangGraph agent of record 0008, run on the scheduler.
|
|
2
|
+
|
|
3
|
+
The graph has a model node and the prebuilt `ToolNode` with its default error handling,
|
|
4
|
+
and the tool node has a `RetryPolicy` with the library's defaults (0008). The model node
|
|
5
|
+
calls the model with the worker's tools bound to it, so every adapter is asked the same
|
|
6
|
+
requests, with the tools' schemas, as a live model needs them. Each worker has its own
|
|
7
|
+
checkpoint thread, named after the worker, and its own step and token budgets (0009). A
|
|
8
|
+
worker that starts again after a crash resumes from its last checkpoint, so LangGraph
|
|
9
|
+
re-runs the node that was interrupted (0006, F11).
|
|
10
|
+
|
|
11
|
+
The budgets are counted from the conversation, which the checkpoint keeps, so they hold
|
|
12
|
+
across a crash and a replay counts them the same way: the steps are the model's replies,
|
|
13
|
+
and the tokens are their input and output tokens, as each reply's usage reports them. A
|
|
14
|
+
reply that reports no usage counts none, so the scripted adapter, and the replay of a
|
|
15
|
+
scripted run, never use up the token budget. Before each model call, a worker whose steps
|
|
16
|
+
or tokens already reached its budget makes no further call: it ends as `budget`, as it
|
|
17
|
+
does when the live adapter's spend cap refuses a call (`fivefold.agents.live`).
|
|
18
|
+
|
|
19
|
+
A worker ends in one of three ways, which the harness records: its graph finished, a
|
|
20
|
+
budget ran out, or the graph raised, for example when the tool node's retries ran out
|
|
21
|
+
(0008). The run does not stop for a worker's error.
|
|
22
|
+
|
|
23
|
+
Checked in langgraph 1.2.22 and langgraph-prebuilt 1.1.2: `StateGraph(MessagesState)`,
|
|
24
|
+
`add_node(name, node, retry_policy=RetryPolicy())`, `add_conditional_edges(name,
|
|
25
|
+
tools_condition)`, `compile(checkpointer=)`, and `ainvoke(None, config)` to resume a
|
|
26
|
+
thread from its last checkpoint; the config's `recursion_limit` bounds the steps. Checked
|
|
27
|
+
in langchain-core 1.8.0 (`language_models/chat_models.py`): `BaseChatModel.bind_tools
|
|
28
|
+
(tools, *, tool_choice=None, **kwargs)` returns a `Runnable` of the model with the tools
|
|
29
|
+
bound; `AIMessage.usage_metadata` is a `UsageMetadata` or None (`messages/ai.py`).
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import asyncio
|
|
35
|
+
from collections.abc import Callable, Sequence
|
|
36
|
+
from dataclasses import dataclass
|
|
37
|
+
from enum import StrEnum
|
|
38
|
+
from typing import Any, Final
|
|
39
|
+
|
|
40
|
+
from langchain_core.language_models.chat_models import BaseChatModel
|
|
41
|
+
from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
|
|
42
|
+
from langchain_core.runnables import RunnableConfig
|
|
43
|
+
from langchain_core.tools import BaseTool
|
|
44
|
+
from langgraph.checkpoint.base import BaseCheckpointSaver
|
|
45
|
+
from langgraph.graph import START, MessagesState, StateGraph
|
|
46
|
+
from langgraph.prebuilt import ToolNode, tools_condition
|
|
47
|
+
from langgraph.types import RetryPolicy
|
|
48
|
+
|
|
49
|
+
BUDGET_TEXT: Final = "Step budget used up."
|
|
50
|
+
TOKEN_BUDGET_TEXT: Final = "Token budget used up."
|
|
51
|
+
SPEND_CAP_TEXT: Final = "Spend cap reached."
|
|
52
|
+
BUDGET_TEXTS: Final = (BUDGET_TEXT, TOKEN_BUDGET_TEXT, SPEND_CAP_TEXT)
|
|
53
|
+
"""The last message of a worker that ended as `budget`: its steps or tokens ran out, or
|
|
54
|
+
the live adapter's spend cap refused its call."""
|
|
55
|
+
|
|
56
|
+
CallLog = Callable[[], Callable[[AIMessage], None]]
|
|
57
|
+
"""The harness's model-call log: called as a model call starts, it returns what to call
|
|
58
|
+
with the call's reply once the model answers."""
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class WorkerEnd(StrEnum):
|
|
62
|
+
"""How an agent worker ended."""
|
|
63
|
+
|
|
64
|
+
FINISHED = "finished"
|
|
65
|
+
BUDGET = "budget"
|
|
66
|
+
ERROR = "error"
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@dataclass(frozen=True)
|
|
70
|
+
class WorkerSpec:
|
|
71
|
+
"""One agent worker: its name, which is also its checkpoint thread, and its budgets."""
|
|
72
|
+
|
|
73
|
+
name: str
|
|
74
|
+
task: str
|
|
75
|
+
max_steps: int
|
|
76
|
+
max_tokens: int | None = None
|
|
77
|
+
"""None for no token budget."""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def budget_end(message: BaseMessage) -> str | None:
|
|
81
|
+
"""The budget that `message` says ran out, if it is the last message of a worker that
|
|
82
|
+
ended as `budget`."""
|
|
83
|
+
if isinstance(message, AIMessage) and not message.tool_calls:
|
|
84
|
+
content = message.content
|
|
85
|
+
if isinstance(content, str) and content in BUDGET_TEXTS:
|
|
86
|
+
return content
|
|
87
|
+
return None
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def tokens_used(messages: Sequence[BaseMessage]) -> int:
|
|
91
|
+
"""The input and output tokens of the model's replies in `messages`, as their usage
|
|
92
|
+
reports them; a reply that reports none counts none."""
|
|
93
|
+
used = 0
|
|
94
|
+
for message in messages:
|
|
95
|
+
if isinstance(message, AIMessage) and message.usage_metadata is not None:
|
|
96
|
+
used += message.usage_metadata["input_tokens"] + message.usage_metadata["output_tokens"]
|
|
97
|
+
return used
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def build_graph(
|
|
101
|
+
model: BaseChatModel,
|
|
102
|
+
tools: Sequence[BaseTool],
|
|
103
|
+
checkpointer: BaseCheckpointSaver[Any],
|
|
104
|
+
*,
|
|
105
|
+
max_steps: int,
|
|
106
|
+
max_tokens: int | None = None,
|
|
107
|
+
on_step: Callable[[int], None] | None = None,
|
|
108
|
+
on_call: CallLog | None = None,
|
|
109
|
+
) -> Any:
|
|
110
|
+
"""The agent's graph: a model node, with the tools bound to the model, and the
|
|
111
|
+
prebuilt tool node, with retries.
|
|
112
|
+
|
|
113
|
+
`on_step` is called with the step's number each time the model finishes a step: the
|
|
114
|
+
fault point `agent.step` (0006). A refused call is no step. `on_call` logs each model
|
|
115
|
+
call (`CallLog`).
|
|
116
|
+
"""
|
|
117
|
+
bound = model.bind_tools(list(tools))
|
|
118
|
+
|
|
119
|
+
async def call_model(state: MessagesState) -> dict[str, list[Any]]:
|
|
120
|
+
messages = state["messages"]
|
|
121
|
+
steps = sum(1 for message in messages if isinstance(message, AIMessage))
|
|
122
|
+
if steps >= max_steps:
|
|
123
|
+
return {"messages": [AIMessage(content=BUDGET_TEXT)]}
|
|
124
|
+
if max_tokens is not None and tokens_used(messages) >= max_tokens:
|
|
125
|
+
return {"messages": [AIMessage(content=TOKEN_BUDGET_TEXT)]}
|
|
126
|
+
answered = on_call() if on_call is not None else None
|
|
127
|
+
reply = await bound.ainvoke(messages)
|
|
128
|
+
if answered is not None:
|
|
129
|
+
answered(reply)
|
|
130
|
+
if on_step is not None and budget_end(reply) is None:
|
|
131
|
+
on_step(steps + 1)
|
|
132
|
+
return {"messages": [reply]}
|
|
133
|
+
|
|
134
|
+
graph = StateGraph(MessagesState)
|
|
135
|
+
graph.add_node("model", call_model)
|
|
136
|
+
graph.add_node("tools", ToolNode(list(tools)), retry_policy=RetryPolicy())
|
|
137
|
+
graph.add_edge(START, "model")
|
|
138
|
+
graph.add_conditional_edges("model", tools_condition)
|
|
139
|
+
graph.add_edge("tools", "model")
|
|
140
|
+
return graph.compile(checkpointer=checkpointer)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
async def run_worker(graph: Any, spec: WorkerSpec, *, resume: bool) -> tuple[WorkerEnd, str]:
|
|
144
|
+
"""Run the worker's graph to its end; resume from the checkpoint after a crash.
|
|
145
|
+
|
|
146
|
+
Returns how it ended and a short description. Cancellation, as a crash causes,
|
|
147
|
+
propagates: the harness restarts the worker.
|
|
148
|
+
"""
|
|
149
|
+
config: RunnableConfig = {
|
|
150
|
+
"configurable": {"thread_id": spec.name},
|
|
151
|
+
"recursion_limit": 2 * spec.max_steps + 4,
|
|
152
|
+
}
|
|
153
|
+
start = None if resume else {"messages": [HumanMessage(spec.task)]}
|
|
154
|
+
try:
|
|
155
|
+
final = await graph.ainvoke(start, config)
|
|
156
|
+
except asyncio.CancelledError:
|
|
157
|
+
raise
|
|
158
|
+
except Exception as error:
|
|
159
|
+
return WorkerEnd.ERROR, f"{type(error).__name__}: {error}"
|
|
160
|
+
last = final["messages"][-1]
|
|
161
|
+
budget = budget_end(last)
|
|
162
|
+
if budget is not None:
|
|
163
|
+
return WorkerEnd.BUDGET, budget
|
|
164
|
+
return WorkerEnd.FINISHED, str(last.content)
|