Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
run_template.py · 13.6 KB · 318 lines
1"""action_run_template -- press Run on a template: validate, hold the
2money, queue the job.
3
4POST {template_id, form_data?}
5
6This object QUEUES and never executes. A verb that both queued and ran
7would make the queue a fiction under load, and -- worse -- would put a
8paid provider call inside a web request, where a timeout looks to the
9user like failure while the provider bills us anyway. Execution belongs
10to system_template_runner, on the daemon, where a crash has a sweeper.
11
12## The gate is asked at the moment of commitment
13
14The stamped price goes on the wallet as a HOLD, here, before anything is
15queued -- through hook_wallet_entries, asked in process, exactly the way
16action_checkout asks it for gift cards. The gate summing the real entries
17at THIS moment is what makes "insufficient balance" mean something: a
18user with five cents cannot queue four hundred runs and present the
19provider bill later, because the four-hundredth hold fails the gate.
20
21Free templates (price 0) touch no wallet at all: no hold, no wallet_id on
22the run, nothing to settle. Money machinery that runs for free jobs is
23machinery that fails for free jobs.
24
25## Capability boundaries are refused HERE, not discovered at 3am
26
27An ai handler needs a model (`runner.ai_model` in app_settings) and a
28stored provider key for whoever is running it. Both are checked at queue
29time and refused with a 409 naming exactly what to configure -- the house
30posture: absent by default, never a stub that pretends to work. Refusing
31here beats queueing a run that the daemon fails an hour later, because
32the person who can fix the configuration is the one looking at the screen
33right now. (The runner re-checks at execution -- a key can be deleted
34between queue and run -- but that failure is the rare race, not the
35normal path.)
36
37## One execution model, not two (task_id)
38
39q9 (askrobots) has a SEPARATE model, `tasks.Work`, for "a template was run
40in service of this task": task + template + worker + status + result, its
41own row, its own history. This runner does not get a second one. `task_id`
42on template_runs is the only piece Work had that this runner did not:
43everything else Work would have needed -- a status machine, an idempotent
44settlement, staleness detection, async submit/poll, an escalation path for
45a run stuck between "submitted" and "resolved" -- template_runs already
46has, built and proven under real money before this field existed. Work
47had none of that; its billing lived in a THIRD, disconnected model
48(`integrations.APILog`) that had to be kept in sync by hand. Here it is
49the same row.
50
51Multiple attempts against one task are just multiple runs sharing a
52task_id -- the append-only doctrine applies exactly as it does everywhere
53else in this codebase: "how many times has this been attempted" is a
54fold over rows, not a stored counter. The task's detail page renders that
55fold with the same `related` block every other one-to-many relationship
56in this system uses (order -> order_lines, invoice -> invoice_lines);
57nothing new was built to show it.
58
59Deliberately absent: nothing here mutates task.status when a run
60succeeds. A Design Review producing a report is not the same claim as
61"this task is finished" -- that is a human's call, or an agent's,
62looking at the run's own output, exactly the same "the server notices,
63the person decides" posture system_reorder_check takes with its
64suggestions. Automatic status transitions are a door left open, not one
65walked through here.
66
67## Ordering, and the crash between the two writes
68
69The hold is written BEFORE the run row. If the crash lands between them,
70the result is a hold with no run -- money reserved for nothing, visible,
71annoying, releasable. The other order would leave a QUEUED RUN WITH NO
72HOLD: a job the runner would happily execute for free, invisibly. When a
73crash must leave one of two wrongs, leave the one that fails safe and
74shows up. (The window is one create call wide; on a run-create failure
75this object immediately writes the release itself, so the orphan hold
76survives only a crash, not an error.)
77"""
78
79import json
80import os
81from datetime import datetime, timezone
82
83import object_execution
84import object_ids
85import object_records
86import object_service_keys
87import object_template_runs
88import python_object_runtime
89
90ACTOR = "action_run_template"
91RUNS = "template_runs"
92MODEL_SETTING = "runner.ai_model"
93
94AI_HANDLERS = ("ai_text",)
95KNOWN_HANDLERS = ("echo", "ai_text")
96
97
98def _base_dir():
99 return os.environ.get("DBBASIC_DATA_DIR", "data")
100
101
102def _text(value):
103 return str(value if value is not None else "").strip()
104
105
106def _now():
107 return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
108
109
110def _setting(base, key):
111 try:
112 for row in object_records.read_collection_records("app_settings",
113 base_dir=base):
114 if _text(row.get("key")) == key:
115 return _text(row.get("value"))
116 except Exception:
117 pass
118 return ""
119
120
121def _call(object_id, payload, *, method="POST"):
122 """Run another installed object in process -- the pattern
123 action_checkout uses to ask hook_wallet_entries."""
124 try:
125 runtime = python_object_runtime.PythonObjectRuntime()
126 outcome = object_execution.execute_object(
127 runtime,
128 object_execution.ObjectExecutionRequest(
129 object_id, method=method, payload=payload))
130 except Exception as exc:
131 return None, str(exc)[:200]
132 if not outcome.ok:
133 message = getattr(outcome.error, "message", "") if outcome.error else ""
134 return None, (_text(message)[:200] or f"{object_id} failed")
135 return outcome.result, ""
136
137
138def _wallet_for(base, owner_id):
139 """The owner's spending wallet: active, kind balance (or legacy blank).
140
141 Gift cards and store credit are deliberately not reached from here in
142 slice 1 -- a template run is metered usage, and mixing tender kinds
143 into the hold path is a decision for the checkout that already makes
144 it, not a default.
145 """
146 try:
147 rows = object_records.read_collection_records("wallets", base_dir=base)
148 except Exception:
149 return None
150 candidates = [row for row in rows
151 if _text(row.get("owner_id")) == owner_id
152 and _text(row.get("kind")) in ("", "balance")
153 and _text(row.get("is_active")).lower() != "false"]
154 candidates.sort(key=lambda row: _text(row.get("created_at")))
155 return candidates[0] if candidates else None
156
157
158def POST(request):
159 request = request or {}
160 base = _base_dir()
161
162 identity = request.get("_identity") or {}
163 user_id = _text(identity.get("user_id"))
164 if not user_id:
165 return {"status": 401,
166 "error": "Running a template requires an account: runs are "
167 "held against a wallet, and an anonymous run would "
168 "be an open tap."}
169
170 template_id = _text(request.get("template_id"))
171 if not template_id:
172 return {"status": 400, "error": "template_id is required."}
173 try:
174 template = object_records.get_collection_record(
175 "templates", template_id, base_dir=base)
176 except Exception:
177 return {"status": 404,
178 "error": f"There is no template {template_id!r} on this server."}
179
180 # --- the optional task link -----------------------------------------------
181 #
182 # A run is in service of a task, or it is not -- most are not (a SWOT
183 # from the shell, a one-off from Talk). When it is, ownership is
184 # checked HERE, at queue time, the same "refused while somebody is
185 # looking" posture the capability-boundary checks below already use:
186 # attaching a run to a task the caller cannot see would let them
187 # infer the task exists (its id, its status) through what the run
188 # settles against. Same posture as the attachments capability, which
189 # gates a file to the record it is attached to the same way.
190 task_id = _text(request.get("task_id"))
191 if task_id:
192 try:
193 task = object_records.get_collection_record(
194 "tasks", task_id, base_dir=base)
195 except Exception:
196 task = None
197 if task is None:
198 return {"status": 404,
199 "error": f"There is no task {task_id!r} on this server."}
200 is_admin = bool(identity.get("is_admin")) or "admin" in (identity.get("roles") or [])
201 if not is_admin and _text(task.get("owner_id")) != user_id:
202 return {"status": 403,
203 "error": "You can only run a template against a task you own."}
204
205 form_data = request.get("form_data")
206 if isinstance(form_data, str):
207 try:
208 form_data = json.loads(form_data or "{}")
209 except ValueError:
210 return {"status": 400, "error": "form_data is not valid JSON."}
211 form_data = form_data if isinstance(form_data, dict) else {}
212
213 found = object_template_runs.problems(template, form_data)
214 handler = _text(template.get("handler"))
215 if handler and handler not in KNOWN_HANDLERS:
216 found.append(f"'{handler}' is not a handler this server knows. "
217 f"Available: {', '.join(KNOWN_HANDLERS)}.")
218 if found:
219 return {"status": 400, "error": " ".join(found), "problems": found}
220
221 # --- capability boundaries, refused while somebody is looking ------------
222 model = ""
223 if handler in AI_HANDLERS:
224 model = _setting(base, MODEL_SETTING)
225 missing = []
226 if not model or ":" not in model:
227 missing.append(f"set {MODEL_SETTING} in app_settings to "
228 f"'<service>:<model>' (e.g. 'anthropic:claude-sonnet-4-5')")
229 else:
230 service = model.split(":", 1)[0]
231 if not object_service_keys.get_service_key(user_id, service,
232 base_dir=base):
233 missing.append(f"store a {service} API key for {user_id} "
234 f"(Settings -> Service Keys)")
235 if missing:
236 return {"status": 409,
237 "error": ("This template runs on an AI provider, and this "
238 "server is not configured for one: "
239 + "; ".join(missing) + ". Nothing was queued "
240 "and nothing was charged."),
241 "problems": missing}
242
243 stamped = object_template_runs.stamp(template, form_data, model=model)
244 price = int(stamped["price_cents"])
245 run_id = object_ids.new_uuid4()
246
247 # --- the hold, through the gate, before the run --------------------------
248 wallet_id = ""
249 if price > 0:
250 wallet = _wallet_for(base, user_id)
251 if wallet is None:
252 return {"status": 409,
253 "error": (f"This template costs {price} cents to run and "
254 f"{user_id} has no active wallet to hold it "
255 f"against. Create a wallet and top it up first.")}
256 wallet_id = _text(wallet.get("id"))
257 hold = object_template_runs.hold_entry(
258 run_id, wallet_id, price, user_id,
259 template_name=stamped["template_name"])
260
261 verdict, error = _call("hook_wallet_entries",
262 {"action": "create",
263 "collection": "wallet_entries",
264 "record": hold},
265 method="BEFORE_WRITE")
266 if error:
267 return {"status": 409,
268 "error": (f"The wallet gate could not be consulted "
269 f"({error}), so nothing was held and nothing "
270 f"was queued.")}
271 if isinstance(verdict, dict) and verdict.get("error"):
272 return {"status": int(verdict.get("status") or 402),
273 "error": _text(verdict.get("error"))}
274
275 try:
276 object_records.create_collection_record(
277 "wallet_entries", hold, base_dir=base, actor=user_id)
278 except Exception as exc:
279 return {"status": 500,
280 "error": f"The hold could not be placed: {str(exc)[:160]}"}
281
282 # --- the run --------------------------------------------------------------
283 record = {
284 "id": run_id,
285 **stamped,
286 "task_id": task_id,
287 "status": "queued",
288 "idempotency_key": object_ids.new_uuid4(),
289 "wallet_id": wallet_id,
290 "owner_id": user_id,
291 }
292 try:
293 stored = object_records.create_collection_record(
294 RUNS, record, base_dir=base, actor=user_id)
295 except Exception as exc:
296 # The one wrong this ordering can leave is a hold with no run; give
297 # the money back now rather than leaving it to be noticed.
298 if price > 0:
299 for entry in object_template_runs.settlement(
300 {"id": run_id, "price_cents": str(price),
301 "wallet_id": wallet_id, "owner_id": user_id},
302 succeeded=False):
303 try:
304 object_records.create_collection_record(
305 "wallet_entries", entry, base_dir=base, actor=ACTOR)
306 except Exception:
307 pass
308 return {"status": 500,
309 "error": f"The run could not be queued: {str(exc)[:160]}"}
310
311 return {"ok": True, "run_id": run_id, "status": "queued",
312 "price_cents": price, "handler": handler,
313 "held": price > 0,
314 "note": ("Queued. The runner executes it on its next pass; the "
315 "hold settles when it finishes -- released in full plus "
316 "an ordinary debit on success, released alone on "
317 "failure." if price > 0 else
318 "Queued. Free to run, so no money was held.")}