askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
template_runs.json · 9.6 KB · 215 lines
| 1 | { |
| 2 | "name": "template_runs", |
| 3 | "title": "Template Runs", |
| 4 | "version": 2, |
| 5 | "storage": "append", |
| 6 | "description": "One job: a template somebody pressed Run on, the terms it ran under, and what happened. THE TERMS ARE STAMPED AT QUEUE TIME -- handler, rendered body, model, price -- copied from the template at the moment of submission, because a template is edited constantly (that is what makes it a template) and a user reading last month's run history must read what last month actually cost, not what this month's prices would have made it cost (docs/logic-decisions.md #1). Even the rendered body is stamped rather than re-rendered at execution, because rendering reads the template and by execution time the template may say something else. THE MONEY IS HOLD / RELEASE / ORDINARY-DEBIT, written to wallet_entries and never to this row: a hold (negative) goes on at queue time THROUGH the wallet gate, so the moment the gate is asked is the moment money is committed and a user with five cents cannot queue four hundred runs; settlement releases the hold in full and charges an ordinary debit for the stamped price on success, or releases alone on failure -- the user pays nothing for a run that did not do the thing, whatever it cost US at the provider (provider_cost_cents records our side, so margin is a fold rather than a mystery). Settlement is idempotent by provenance marker (template_run/<id>/release), checked against the ENTRIES rather than against status here, because the crash this guards is precisely the one between writing money and updating status. THE HARD CONSTRAINT THIS SCHEMA EXISTS TO STATE: a stale claimed run is marked abandoned, its hold is released, and it is NEVER RETRIED AUTOMATICALLY. The provider call is not idempotent and is not ours -- a run claimed, executed and interrupted before the answer was recorded may or may not have been billed by the provider, and automatically re-running it risks paying twice for one job. Automatic retry of a paid non-idempotent call looks like robustness and is an unbounded spend; a retry is a NEW run, with a new hold, started by a person who can see what happened. status is a declared state machine (queued -> claimed -> succeeded | failed; queued/claimed -> abandoned) so /flow renders it and the transition rules bind every writer; there is no update grant on this collection at all, so the only hands that move a run are the runner and the sweeper, in process.", |
| 7 | "fields": [ |
| 8 | { |
| 9 | "name": "id" |
| 10 | }, |
| 11 | { |
| 12 | "name": "template_id", |
| 13 | "type": "text", |
| 14 | "required": true, |
| 15 | "label": "Template", |
| 16 | "relation": { |
| 17 | "collection": "templates", |
| 18 | "display_field": "name" |
| 19 | }, |
| 20 | "help": "Which template was run. A pointer for navigation only: every term that matters is stamped below, so deleting or rewriting the template changes nothing about this row." |
| 21 | }, |
| 22 | { |
| 23 | "name": "task_id", |
| 24 | "type": "relation", |
| 25 | "relation": { |
| 26 | "collection": "tasks" |
| 27 | }, |
| 28 | "label": "Task", |
| 29 | "help": "Optional. When a run is in service of a task, this is the task -- and it is the ONLY thing q9's separate tasks.Work model was for that this runner did not already have. Optional, not required: most runs (a SWOT from the shell, a one-off from Talk) have no task at all, and a template runner that could only run FROM a task would be a regression from what shipped before this field existed." |
| 30 | }, |
| 31 | { |
| 32 | "name": "template_name", |
| 33 | "type": "text", |
| 34 | "label": "Template Name", |
| 35 | "help": "Stamped at queue time, so the history stays readable after the template is renamed or gone." |
| 36 | }, |
| 37 | { |
| 38 | "name": "handler", |
| 39 | "type": "text", |
| 40 | "required": true, |
| 41 | "label": "Handler", |
| 42 | "help": "Which engine executed this -- stamped, because the template may declare a different one tomorrow." |
| 43 | }, |
| 44 | { |
| 45 | "name": "model", |
| 46 | "type": "text", |
| 47 | "label": "Model", |
| 48 | "help": "The provider model in force when the run was queued (ai handlers only). Stamped for the same reason as the price: a model swap next week must not restate what produced last week's output." |
| 49 | }, |
| 50 | { |
| 51 | "name": "form_data", |
| 52 | "type": "textarea", |
| 53 | "label": "Form Data", |
| 54 | "help": "The submission, as JSON, exactly as validated at queue time." |
| 55 | }, |
| 56 | { |
| 57 | "name": "rendered_body", |
| 58 | "type": "textarea", |
| 59 | "label": "Rendered Body", |
| 60 | "help": "The template body with the form values filled in -- the actual prompt or content that was executed. Stamped at queue time; see the schema description for why it is never re-rendered." |
| 61 | }, |
| 62 | { |
| 63 | "name": "instructions", |
| 64 | "type": "textarea", |
| 65 | "label": "Instructions", |
| 66 | "help": "The template's instructions field at queue time; ai handlers send it as the system prompt." |
| 67 | }, |
| 68 | { |
| 69 | "name": "status", |
| 70 | "type": "enum", |
| 71 | "required": true, |
| 72 | "default": "queued", |
| 73 | "label": "Status", |
| 74 | "enum": [ |
| 75 | "queued", |
| 76 | "claimed", |
| 77 | "running", |
| 78 | "succeeded", |
| 79 | "failed", |
| 80 | "abandoned", |
| 81 | "needs_review" |
| 82 | ], |
| 83 | "transitions": { |
| 84 | "queued": [ |
| 85 | "claimed", |
| 86 | "abandoned" |
| 87 | ], |
| 88 | "claimed": [ |
| 89 | "running", |
| 90 | "succeeded", |
| 91 | "failed", |
| 92 | "abandoned" |
| 93 | ], |
| 94 | "running": [ |
| 95 | "succeeded", |
| 96 | "failed", |
| 97 | "needs_review" |
| 98 | ], |
| 99 | "needs_review": [ |
| 100 | "succeeded", |
| 101 | "failed" |
| 102 | ] |
| 103 | }, |
| 104 | "help": "queued: waiting for the runner. claimed: a runner pass owns it. running: submitted to the provider, which now holds the job -- owned but not executing in any pass, resolved by polling. succeeded/failed: it executed and settled. abandoned: its heartbeat stopped BEFORE anything was submitted, so nothing was spent and the hold was released -- a dead end, never re-queued. needs_review: it was submitted and never resolved, so the money is genuinely undecided -- releasing gives away what we paid the provider, charging bills for work that may never have arrived, and the box refuses to guess. The hold stays put until a person moves it. The transition map is the whole state machine: note that running can NEVER reach abandoned, because abandoning is what releases the hold." |
| 105 | }, |
| 106 | { |
| 107 | "name": "claimed_by", |
| 108 | "type": "text", |
| 109 | "label": "Claimed By" |
| 110 | }, |
| 111 | { |
| 112 | "name": "claimed_at", |
| 113 | "type": "datetime", |
| 114 | "label": "Claimed" |
| 115 | }, |
| 116 | { |
| 117 | "name": "heartbeat_at", |
| 118 | "type": "datetime", |
| 119 | "label": "Heartbeat", |
| 120 | "help": "Last sign of life from whatever claimed this run. The sweeper marks a claimed run abandoned when this goes quiet past runner.stale_seconds -- detection by heartbeat rather than by timeout-per-handler, because a video job and an echo job have no timeout in common." |
| 121 | }, |
| 122 | { |
| 123 | "name": "idempotency_key", |
| 124 | "type": "text", |
| 125 | "label": "Idempotency Key", |
| 126 | "help": "Ours, minted at queue time and recorded BEFORE any provider call is made. Where a provider supports idempotency keys this is what gets sent, so a retry resolves to the same provider job instead of a second bill. Recorded first because the crash worth designing for is the one between calling and recording." |
| 127 | }, |
| 128 | { |
| 129 | "name": "provider_job_id", |
| 130 | "type": "text", |
| 131 | "label": "Provider Job", |
| 132 | "help": "The provider's own id for the work, written as soon as it is known. The thread a human pulls when a run is abandoned and the question is 'did they charge us'." |
| 133 | }, |
| 134 | { |
| 135 | "name": "price_cents", |
| 136 | "type": "integer", |
| 137 | "default": "0", |
| 138 | "label": "Price", |
| 139 | "help": "What the user was quoted and held for -- the template's run_cost_cents at queue time. Integer cents (doctrine #10). This is the amount settlement charges on success, in full, regardless of what the provider billed us." |
| 140 | }, |
| 141 | { |
| 142 | "name": "provider_cost_cents", |
| 143 | "type": "integer", |
| 144 | "default": "0", |
| 145 | "label": "Provider Cost", |
| 146 | "help": "What the run cost US, computed from the provider's reported usage and the ai_prices table where one exists. Never billed to the user; price minus this is margin, per run, as a fold." |
| 147 | }, |
| 148 | { |
| 149 | "name": "wallet_id", |
| 150 | "type": "text", |
| 151 | "label": "Wallet", |
| 152 | "help": "Where the hold was placed. Empty on a free run, which touches no wallet at all." |
| 153 | }, |
| 154 | { |
| 155 | "name": "output", |
| 156 | "type": "textarea", |
| 157 | "label": "Output", |
| 158 | "help": "What came back, inline, for text-shaped handlers. Binary output (images, video) will live in files with a reference here -- storing only a provider URL is refused as a design rule, because provider URLs expire and a run whose output has vanished is a charge with nothing to show for it." |
| 159 | }, |
| 160 | { |
| 161 | "name": "error", |
| 162 | "type": "textarea", |
| 163 | "label": "Error", |
| 164 | "help": "Why it failed, in words a person can act on -- which capability is missing and what to configure, or what the provider said." |
| 165 | }, |
| 166 | { |
| 167 | "name": "finished_at", |
| 168 | "type": "datetime", |
| 169 | "label": "Finished" |
| 170 | }, |
| 171 | { |
| 172 | "name": "owner_id", |
| 173 | "type": "text", |
| 174 | "label": "Owner" |
| 175 | }, |
| 176 | { |
| 177 | "name": "created_at", |
| 178 | "type": "datetime", |
| 179 | "read_only": true, |
| 180 | "label": "Queued" |
| 181 | } |
| 182 | ], |
| 183 | "search": { |
| 184 | "fields": [ |
| 185 | "template_name", |
| 186 | "status", |
| 187 | "output", |
| 188 | "error" |
| 189 | ] |
| 190 | }, |
| 191 | "forms": { |
| 192 | "default": { |
| 193 | "fields": [ |
| 194 | "template_id", |
| 195 | "form_data" |
| 196 | ] |
| 197 | } |
| 198 | }, |
| 199 | "views": { |
| 200 | "list_mode": "table", |
| 201 | "list_fields": [ |
| 202 | "created_at", |
| 203 | "template_name", |
| 204 | "handler", |
| 205 | "status", |
| 206 | "price_cents", |
| 207 | "provider_cost_cents", |
| 208 | "finished_at" |
| 209 | ], |
| 210 | "filter_fields": [ |
| 211 | "status", |
| 212 | "handler" |
| 213 | ] |
| 214 | } |
| 215 | } |