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.
Files changed (128) hide show
  1. fivefold/__init__.py +4 -0
  2. fivefold/_data/db/bootstrap.sql +26 -0
  3. fivefold/_data/db/migrations/0001_schemas.sql +67 -0
  4. fivefold/_data/db/migrations/0002_gateway.sql +224 -0
  5. fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
  6. fivefold/_data/db/migrations/0004_harness.sql +141 -0
  7. fivefold/_data/db/migrations/0005_sim.sql +679 -0
  8. fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
  9. fivefold/_data/db/migrations/0007_eval.sql +33 -0
  10. fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
  11. fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
  12. fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
  13. fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
  14. fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
  15. fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
  16. fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
  17. fivefold/_data/db/registry/0001_registry.sql +31 -0
  18. fivefold/_data/faults/expected.yaml +406 -0
  19. fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
  20. fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
  21. fivefold/agents/__init__.py +7 -0
  22. fivefold/agents/branch.py +187 -0
  23. fivefold/agents/checkpoint.py +77 -0
  24. fivefold/agents/connection.py +153 -0
  25. fivefold/agents/live.py +492 -0
  26. fivefold/agents/policy.py +426 -0
  27. fivefold/agents/remote.py +333 -0
  28. fivefold/agents/replay.py +170 -0
  29. fivefold/agents/scripted.py +122 -0
  30. fivefold/agents/tools.py +229 -0
  31. fivefold/agents/worker.py +164 -0
  32. fivefold/domain/__init__.py +5 -0
  33. fivefold/domain/api.py +517 -0
  34. fivefold/domain/authority.py +149 -0
  35. fivefold/domain/contracts.py +80 -0
  36. fivefold/domain/identity.py +113 -0
  37. fivefold/domain/prices.py +178 -0
  38. fivefold/domain/report.py +92 -0
  39. fivefold/domain/rules.py +346 -0
  40. fivefold/domain/scenario.py +524 -0
  41. fivefold/evaluator/__init__.py +155 -0
  42. fivefold/evaluator/__main__.py +127 -0
  43. fivefold/evaluator/authorization.py +146 -0
  44. fivefold/evaluator/checks.py +331 -0
  45. fivefold/evaluator/evaluate.py +109 -0
  46. fivefold/evaluator/evidence.py +392 -0
  47. fivefold/evaluator/freshness.py +136 -0
  48. fivefold/evaluator/liveness.py +236 -0
  49. fivefold/evaluator/load.py +354 -0
  50. fivefold/evaluator/metrics.py +95 -0
  51. fivefold/evaluator/records.py +452 -0
  52. fivefold/evaluator/recovery.py +209 -0
  53. fivefold/evaluator/report.py +1096 -0
  54. fivefold/evaluator/result.py +344 -0
  55. fivefold/evaluator/store.py +83 -0
  56. fivefold/faults/__init__.py +5 -0
  57. fivefold/faults/catalog.py +278 -0
  58. fivefold/faults/plan.py +538 -0
  59. fivefold/gateway/__init__.py +6 -0
  60. fivefold/gateway/admin.py +179 -0
  61. fivefold/gateway/admin_api.py +398 -0
  62. fivefold/gateway/codec.py +372 -0
  63. fivefold/gateway/destination.py +64 -0
  64. fivefold/gateway/dispatcher.py +379 -0
  65. fivefold/gateway/freshness.py +83 -0
  66. fivefold/gateway/invariants.py +761 -0
  67. fivefold/gateway/memory.py +277 -0
  68. fivefold/gateway/pg_store.py +657 -0
  69. fivefold/gateway/records.py +592 -0
  70. fivefold/gateway/server.py +102 -0
  71. fivefold/gateway/sim_client.py +295 -0
  72. fivefold/gateway/state_machine.py +376 -0
  73. fivefold/gateway/steps.py +897 -0
  74. fivefold/gateway/store.py +635 -0
  75. fivefold/gateway/tools.py +424 -0
  76. fivefold/gateway/twin.py +199 -0
  77. fivefold/gateway/wire.py +138 -0
  78. fivefold/harness/__init__.py +6 -0
  79. fivefold/harness/actors.py +230 -0
  80. fivefold/harness/cells.py +303 -0
  81. fivefold/harness/clock.py +209 -0
  82. fivefold/harness/demo.py +397 -0
  83. fivefold/harness/fault_effects.py +122 -0
  84. fivefold/harness/live_options.py +159 -0
  85. fivefold/harness/log.py +540 -0
  86. fivefold/harness/mcp_link.py +409 -0
  87. fivefold/harness/migrations.py +520 -0
  88. fivefold/harness/models.py +368 -0
  89. fivefold/harness/registry.py +105 -0
  90. fivefold/harness/reports.py +100 -0
  91. fivefold/harness/rng.py +57 -0
  92. fivefold/harness/run.py +881 -0
  93. fivefold/harness/scheduler.py +441 -0
  94. fivefold/harness/sim_points.py +215 -0
  95. fivefold/harness/split/__init__.py +34 -0
  96. fivefold/harness/split/__main__.py +275 -0
  97. fivefold/harness/split/credentials.py +74 -0
  98. fivefold/harness/split/faults.py +75 -0
  99. fivefold/harness/split/gateway.py +769 -0
  100. fivefold/harness/split/hops.py +291 -0
  101. fivefold/harness/split/lifecycle.py +322 -0
  102. fivefold/harness/split/rundir.py +152 -0
  103. fivefold/harness/split/service.py +157 -0
  104. fivefold/harness/split/simulator.py +432 -0
  105. fivefold/harness/study.py +643 -0
  106. fivefold/harness/transport.py +533 -0
  107. fivefold/paths.py +24 -0
  108. fivefold/py.typed +0 -0
  109. fivefold/recorder/__init__.py +18 -0
  110. fivefold/recorder/__main__.py +308 -0
  111. fivefold/recorder/cassette.py +322 -0
  112. fivefold/recorder/playback.py +316 -0
  113. fivefold/recorder/recording.py +133 -0
  114. fivefold/sim/__init__.py +37 -0
  115. fivefold/sim/config.py +52 -0
  116. fivefold/sim/endpoint.py +176 -0
  117. fivefold/sim/ledger.py +583 -0
  118. fivefold/sim/service.py +834 -0
  119. fivefold/viewer/__init__.py +14 -0
  120. fivefold/viewer/__main__.py +75 -0
  121. fivefold/viewer/app.py +122 -0
  122. fivefold/viewer/records.py +108 -0
  123. fivefold/viewer/source.py +196 -0
  124. fivefold/viewer/timeline.py +61 -0
  125. fivefold-0.1.0.dist-info/METADATA +169 -0
  126. fivefold-0.1.0.dist-info/RECORD +128 -0
  127. fivefold-0.1.0.dist-info/WHEEL +4 -0
  128. fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,122 @@
1
+ """Faults that change the simulator's state: F6 revokes, F7 changes a quote (0006).
2
+
3
+ A fault takes effect at its point, before the scheduler delivers any further message. F6
4
+ and F7 apply directly through the simulator's control interface at that moment; they are
5
+ not sent as messages, so they cannot arrive late (0006, Fault points).
6
+
7
+ What a fault acts on comes from where it fires: the action at the gateway's dispatch
8
+ check, or the message on the wire (the write request, or B0's approval answer).
9
+
10
+ - F6 revokes the approval the action or message cites, as the scripted approver would
11
+ (0002, rule 8; 0006). The revocation is recorded in the actor log.
12
+ - F7 changes the quote the action or message cites. The default variant, `price_up`,
13
+ raises the unit price by `percent` (default 5), rounding up, but no higher than the
14
+ intent's maximum, so the order stays acceptable. The `harmless` variant adds a day
15
+ to the lead time, which no dependency rule reads (0004).
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from collections.abc import Mapping
21
+
22
+ from fivefold.domain.rules import quote_key
23
+ from fivefold.domain.scenario import PurchaseOrderAccept, Scenario
24
+ from fivefold.faults.catalog import Action
25
+ from fivefold.faults.plan import Fired
26
+ from fivefold.harness.actors import APPROVER
27
+ from fivefold.harness.log import ActorRecord, HarnessLog
28
+ from fivefold.harness.scheduler import Scheduler
29
+ from fivefold.sim import Control
30
+
31
+ FAULT_ACTOR = "fault-plan"
32
+ """The actor a fact version names when a fault plan caused it."""
33
+
34
+
35
+ class FaultEffectError(RuntimeError):
36
+ """A fault fired where it has nothing to act on: the plan is wrong for the scenario."""
37
+
38
+
39
+ class SimulatorFaults:
40
+ """Applies F6 and F7 through the simulator's control interface."""
41
+
42
+ def __init__(
43
+ self, scheduler: Scheduler, control: Control, log: HarnessLog, scenario: Scenario
44
+ ) -> None:
45
+ self._scheduler = scheduler
46
+ self._control = control
47
+ self._log = log
48
+ self._scenario = scenario
49
+
50
+ def apply(self, fired: Fired, context: Mapping[str, object]) -> None:
51
+ """Apply a fault that fired with what it acts on in `context`."""
52
+ action = fired.planned.kind.action
53
+ if action is Action.REVOKE:
54
+ self._revoke(fired, context)
55
+ elif action is Action.CHANGE_QUOTE:
56
+ self._change_quote(fired, context)
57
+ else:
58
+ raise FaultEffectError(f"{fired.fault} does not change the simulator")
59
+
60
+ def _revoke(self, fired: Fired, context: Mapping[str, object]) -> None:
61
+ approval_id = context.get("approval_id")
62
+ if not isinstance(approval_id, str):
63
+ raise FaultEffectError(f"{fired.fault} fired where no approval is cited")
64
+ now = self._scheduler.now
65
+ answer = self._control.revoke(approval_id, actor=APPROVER, vt=now)
66
+ self._log.actor_acted(
67
+ ActorRecord(
68
+ seq=self._log.next_seq(),
69
+ actor="approver",
70
+ action="revoke",
71
+ subject=approval_id,
72
+ details={"fault": str(fired.fault), "status": str(answer.status)},
73
+ vt=now,
74
+ )
75
+ )
76
+
77
+ def _change_quote(self, fired: Fired, context: Mapping[str, object]) -> None:
78
+ supplier_id, sku = context.get("supplier_id"), context.get("sku")
79
+ if not isinstance(supplier_id, str) or not isinstance(sku, str):
80
+ raise FaultEffectError(f"{fired.fault} fired where no quote is cited")
81
+ key = quote_key(supplier_id, sku)
82
+ current = self._control.current_fact(key)
83
+ if current is None:
84
+ raise FaultEffectError(f"{fired.fault}: there is no quote {key}")
85
+ changes: dict[str, str | int]
86
+ variant = fired.planned.variant
87
+ if variant == "harmless":
88
+ changes = {"lead_time_days": int(str(current.data["lead_time_days"])) + 1}
89
+ elif variant in (None, "price_up"):
90
+ price = int(str(current.data["unit_price_minor"]))
91
+ percent = fired.planned.param("percent")
92
+ raised = -(-price * (100 + percent) // 100)
93
+ changes = {"unit_price_minor": min(raised, self._ceiling(context, price))}
94
+ else:
95
+ raise FaultEffectError(f"{fired.fault} has no variant {variant!r}")
96
+ self._control.change_fact(key, changes, actor=FAULT_ACTOR, vt=self._scheduler.now)
97
+
98
+ def _ceiling(self, context: Mapping[str, object], price: int) -> int:
99
+ """The intent's highest acceptable unit price, so the change stays acceptable."""
100
+ intent_id = context.get("intent_id")
101
+ if isinstance(intent_id, str):
102
+ accept = self._scenario.intent(intent_id).accept
103
+ if isinstance(accept, PurchaseOrderAccept):
104
+ return max(price, accept.max_unit_price_minor)
105
+ return price * 2
106
+
107
+
108
+ def message_context(body: object) -> dict[str, object]:
109
+ """What a fault on a message acts on: a write request's, or an approval answer's."""
110
+ if not isinstance(body, Mapping):
111
+ return {}
112
+ context: dict[str, object] = {
113
+ name: body[name]
114
+ for name in ("intent_id", "approval_id", "supplier_id", "sku")
115
+ if name in body
116
+ }
117
+ scope = body.get("scope")
118
+ if isinstance(scope, Mapping):
119
+ for name in ("supplier_id", "sku"):
120
+ if name in scope:
121
+ context.setdefault(name, scope[name])
122
+ return context
@@ -0,0 +1,159 @@
1
+ """The command-line options of a live run, shared by the commands that run one (0009).
2
+
3
+ `python -m fivefold.recorder record` and `python -m fivefold.harness.study` take the same
4
+ options:
5
+
6
+ - `--live PROVIDER:MODEL` runs that live model instead of the scripted one;
7
+ - `--spend-cap-usd USD` and `--prices PATH`, which `--live` needs: the spend cap above
8
+ 0 USD, and the price file that prices the model;
9
+ - `--param NAME=VALUE`, repeated, sets one of the model's parameters, VALUE read as JSON,
10
+ or as text when it is not JSON;
11
+ - `--call-limit-s SECONDS` fails a model call that has waited that long for the provider
12
+ (default 600), so a stalled server cannot hold a run.
13
+
14
+ Live runs sit behind an explicit flag and a spend cap (CLAUDE.md). `live_from_args` checks
15
+ everything before a command runs anything, so a refused live run never touches a
16
+ database: the flag (`FIVEFOLD_LIVE=1`), the provider, its parameters' names and their form
17
+ in the cassette, the cap, the call limit, the model's price, the provider's API key and
18
+ the variables it refuses, and last the parameters' values, by building the model, which
19
+ sends nothing. It builds one
20
+ spend meter, which every run of the command shares, so the cap holds across them
21
+ (`fivefold.agents.live.SpendMeter`).
22
+ """
23
+
24
+ from __future__ import annotations
25
+
26
+ import argparse
27
+ import json
28
+ from collections.abc import Mapping, Sequence
29
+ from decimal import Decimal, InvalidOperation
30
+ from pathlib import Path
31
+
32
+ from pydantic import JsonValue
33
+
34
+ from fivefold.agents.live import (
35
+ CALL_LIMIT_S,
36
+ SpendMeter,
37
+ check_provider,
38
+ parse_live_name,
39
+ provider_model,
40
+ )
41
+ from fivefold.domain.prices import load_price_file
42
+ from fivefold.harness.models import Live, check_live, check_live_flag
43
+ from fivefold.recorder.cassette import plain_object
44
+
45
+
46
+ def usd(text: str) -> Decimal:
47
+ """An amount in USD, from the command line."""
48
+ try:
49
+ return Decimal(text)
50
+ except InvalidOperation:
51
+ raise argparse.ArgumentTypeError(f"not an amount: {text!r}") from None
52
+
53
+
54
+ def model_params(items: Sequence[str]) -> dict[str, JsonValue]:
55
+ """The model's parameters from `NAME=VALUE` items, each VALUE as JSON or as text."""
56
+ params: dict[str, JsonValue] = {}
57
+ for item in items:
58
+ name, equals, value = item.partition("=")
59
+ if not name or not equals:
60
+ raise ValueError(f"a model parameter is NAME=VALUE, not {item!r}")
61
+ try:
62
+ params[name] = json.loads(value)
63
+ except json.JSONDecodeError:
64
+ params[name] = value
65
+ return params
66
+
67
+
68
+ def add_live_options(parser: argparse.ArgumentParser) -> None:
69
+ """Add `--live`, `--spend-cap-usd`, `--prices` and `--param` to `parser`."""
70
+ parser.add_argument(
71
+ "--live",
72
+ metavar="PROVIDER:MODEL",
73
+ help="run this live model instead of the scripted one; needs FIVEFOLD_LIVE=1",
74
+ )
75
+ parser.add_argument(
76
+ "--spend-cap-usd",
77
+ type=usd,
78
+ metavar="USD",
79
+ help="with --live: refuse model calls once the spend reaches this many USD",
80
+ )
81
+ parser.add_argument("--prices", type=Path, metavar="PATH", help="with --live: the price file")
82
+ parser.add_argument(
83
+ "--param",
84
+ action="append",
85
+ default=[],
86
+ metavar="NAME=VALUE",
87
+ help="with --live: a model parameter, VALUE as JSON; repeat for more",
88
+ )
89
+ parser.add_argument(
90
+ "--call-limit-s",
91
+ type=float,
92
+ metavar="SECONDS",
93
+ help=f"with --live: fail a model call that waits longer (default {CALL_LIMIT_S:g})",
94
+ )
95
+
96
+
97
+ def check_live_options(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
98
+ """End the command through `parser` when the live options do not go together: the
99
+ spend cap, the price file and parameters without `--live`, or `--live` without a cap
100
+ or a price file."""
101
+ given = (
102
+ args.spend_cap_usd is not None
103
+ or args.prices is not None
104
+ or args.param
105
+ or args.call_limit_s is not None
106
+ )
107
+ if args.live is None and given:
108
+ parser.error("--spend-cap-usd, --prices, --param and --call-limit-s go with --live")
109
+ if args.live is not None and (args.spend_cap_usd is None or args.prices is None):
110
+ parser.error("--live needs --spend-cap-usd and --prices")
111
+
112
+
113
+ def live_model(
114
+ name: str,
115
+ params: Sequence[str],
116
+ *,
117
+ spend_cap_usd: Decimal,
118
+ prices: Path,
119
+ environ: Mapping[str, str],
120
+ limit_s: float = CALL_LIMIT_S,
121
+ ) -> Live:
122
+ """The live model `name`, `PROVIDER:MODEL`, with the parameters `params` and one spend
123
+ meter and a call limit of `limit_s` seconds, checked in this order before anything
124
+ runs: the flag in `environ`, the provider, its parameters' names and their form in the
125
+ cassette, the cap, the call limit, the model's price in the price file at `prices`, the
126
+ provider's API key and the variables it refuses in `environ`, and last the
127
+ parameters' values, by building the model, which sends nothing.
128
+
129
+ Raises `ValueError` (`LiveRefused`, `LiveError` or `PriceFileError`) for a refusal,
130
+ and `OSError` when the price file cannot be read.
131
+ """
132
+ check_live_flag(environ)
133
+ provider, model = parse_live_name(name)
134
+ parsed = model_params(params)
135
+ check_provider(provider, parsed)
136
+ plain_object(parsed, "the model's parameters") # the cassette's form of them
137
+ meter = SpendMeter(spend_cap_usd, load_price_file(prices))
138
+ live = Live(provider, model, parsed, spend=meter, limit_s=limit_s)
139
+ check_live(live, environ)
140
+ provider_model(provider, model, parsed) # their values; building the model sends nothing
141
+ return live
142
+
143
+
144
+ def live_from_args(args: argparse.Namespace, environ: Mapping[str, str]) -> Live | None:
145
+ """The live model the options name, checked (`live_model`); None without `--live`.
146
+
147
+ Call `check_live_options` first.
148
+ """
149
+ if args.live is None:
150
+ return None
151
+ limit_s = CALL_LIMIT_S if args.call_limit_s is None else args.call_limit_s
152
+ return live_model(
153
+ args.live,
154
+ args.param,
155
+ spend_cap_usd=args.spend_cap_usd,
156
+ prices=args.prices,
157
+ environ=environ,
158
+ limit_s=limit_s,
159
+ )