Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download api/ai_enrich.py from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 34.4 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/api/ai_enrich.py
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/api/ai_enrich.py
-
curl -L -o ai_enrich.py https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/api/ai_enrich.py
34.4 kB
| """ai_enrich.py -- the AI ENRICHMENT column (wave 34, owner ruling R13). | |
| R13: *"A field kind called AI enrichment: a prompt per row that populates text. Detailed | |
| configuration in the field's own config, including a token-usage limit."* | |
| WHERE THE HALVES LIVE, and why the line is drawn here rather than anywhere else: | |
| core/user_tables.py the CONTRACT and the STORAGE -- `UT_FIELD_TYPES`, `_clean_ai_enrich`, | |
| the per-cell provenance stratum, and the law about what an automatic | |
| run may overwrite. It owns the store document, so it owns the marks. | |
| api/ai_enrich.py THIS file: the PROMPT vocabulary, the run PLAN, and the token ceiling's | |
| own report. `core` may not import upward, so anything that needs to | |
| reach a vendor or an HTTP session lives here. | |
| Everything in this module is a PURE FUNCTION of data it is handed. That is deliberate: it is the | |
| half a gate can exercise without a network, a store, or a running server, which is what makes | |
| `api_ai_enrich` a real gate rather than a mount check. | |
| TOKEN ACCOUNTING, and the hole it is filling. `api/ai_review.py::decide` -- the product's only | |
| other LLM entry -- has no token accounting of ANY kind: `max_tokens: 300` per call, one 20 s | |
| timeout, no retry, and nothing anywhere counts what a run spent. R13 asks for a usage limit, so | |
| there was nothing to build on and the ledger starts here. The two measured community complaints | |
| about this feature elsewhere are both REPORTING gaps rather than capability gaps (a preview said | |
| 15 credits and the run spent 360; a finished run gave no completion signal), which is why | |
| `ceiling_report` exists beside the ceiling itself. | |
| """ | |
| from __future__ import annotations | |
| import os | |
| import re | |
| import dash_norm | |
| import requests | |
| #: A prompt names other columns the way a formula does, so a user who has written one already | |
| #: knows this syntax. β ONE parser, exported, because `user_tables.ai_enrich_input_hash` fingerprints | |
| #: the referenced cells and a second copy of this pattern would disagree with it the first time the | |
| #: token syntax gained a form ([[one-question-two-normalizers]]). | |
| _REF = re.compile(r'\{([a-zA-Z0-9_]{1,60})\}') | |
| #: What a cell can say about where its value came from. Mirrors | |
| #: `user_tables.AI_ENRICH_STATES` plus the two states that are DERIVED rather than stored: | |
| #: `stale` (the inputs moved since the value was written) and `empty` (nothing has run). | |
| #: β Re-exported rather than re-declared: the stored vocabulary has exactly one owner. | |
| CELL_STATES = ('empty', 'agent', 'human', 'stale', 'error') | |
| #: β THERE IS DELIBERATELY NO PROVIDER LIST IN THIS FILE. The product already has TWO opinions | |
| #: about provider order (`harness/analyst.PROVIDERS` says groq-first, `routes_query. | |
| #: QUERY_PROVIDER_ORDER` says cerebras-first) and `W34-T37` exists to reconcile them. Declaring a | |
| #: third here would make that ticket harder and this feature wrong in a new way, so the catalogue | |
| #: is BORROWED from `ai_review` (`PROVIDERS` + `ladder()` + the key names + the cheap-first order | |
| #: owner ruling R14 set). β The CALL is ours because the requirements differ: `ai_review` hardcodes | |
| #: `max_tokens: 300` and reads no `usage`, and R13 needs a per-column ceiling and a real ledger. | |
| #: One provider catalogue, two call shapes, and the reason is written down rather than inferred. | |
| #: The run's per-cell wall clock. Separate from `ai_review.TIMEOUT_SECONDS` because a review is | |
| #: one classification a person is waiting on and this is a loop over rows. | |
| TIMEOUT_SECONDS = float(os.environ.get('AIOS_AI_ENRICH_TIMEOUT') or 30) | |
| #: How many failing rows carry their error into the report before it is summarised. A report that | |
| #: lists 900 identical `429`s is a report nobody reads. | |
| MAX_REPORTED_ERRORS = 10 | |
| #: Bound on what one row hands the model, mirroring `ai_review`'s own two caps: a table can hold a | |
| #: 32 KB JSON cell per row and no prompt needs it. | |
| MAX_CELL_CHARS = 400 | |
| def prompt_refs(prompt): | |
| """The column keys a prompt names, in first-appearance order, de-duplicated. | |
| `"Summarise {name} for {segment}"` -> `['name', 'segment']`. | |
| """ | |
| seen, out = set(), [] | |
| for key in _REF.findall(str(prompt or '')): | |
| if key not in seen: | |
| seen.add(key) | |
| out.append(key) | |
| return out | |
| def render_prompt(prompt, row, field_keys=()): | |
| """`(text, unresolved)` -- the prompt with `{token}` replaced by this row's cells. | |
| β AN UNKNOWN TOKEN IS REPORTED, NOT SILENTLY BLANKED. A prompt naming a column that does not | |
| exist is a prompt that will quietly ask a different question on every row, and the resulting | |
| text looks exactly like a correct answer. `unresolved` is what the caller shows the user; | |
| R6's standing rule is the same sentence one layer up (a limit that cannot be removed must be | |
| reported with its cause). | |
| β A token naming a real column whose CELL is empty is NOT unresolved: an empty cell is data. | |
| """ | |
| known = set(field_keys or ()) | |
| unresolved = [] | |
| def _sub(match): | |
| key = match.group(1) | |
| if known and key not in known: | |
| unresolved.append(key) | |
| return match.group(0) | |
| return str((row or {}).get(key, '')) | |
| return _REF.sub(_sub, str(prompt or '')), sorted(set(unresolved)) | |
| def ceiling_report(spent, ceiling, rows_done, rows_total): | |
| """R6's second sentence as DATA, or None while the run is still inside its budget. | |
| `{subject, limit, spent, effect, cause, recommendation}` -- the same shape | |
| `user_tables.limit_report` returns, so the client renders one vocabulary for every limit the | |
| product enforces rather than a second one for this feature. | |
| β `effect` is `stopped`, never `truncated`. A run that quietly stopped filling cells leaves a | |
| column that looks complete and is not, which is the failure the whole reporting rule is | |
| arranged against. The caller STOPS and says so. | |
| """ | |
| if ceiling is None or spent < ceiling: | |
| return None | |
| left = max(0, int(rows_total or 0) - int(rows_done or 0)) | |
| rest = f'{left:,} rows' if left != 1 else '1 row' | |
| return { | |
| 'subject': 'tokens', | |
| 'limit': int(ceiling), | |
| 'spent': int(spent), | |
| 'effect': 'stopped', | |
| 'cause': f'this run reached its token ceiling of {int(ceiling):,} after filling ' | |
| f'{int(rows_done or 0):,} of {int(rows_total or 0):,} rows', | |
| 'recommendation': f'raise the column\'s token limit, shorten its prompt, or run the ' | |
| f'remaining {rest} again. Nothing was truncated and no cell holds a ' | |
| f'partial answer', | |
| } | |
| def plan_rows(rows, col_id, config, marks, cost_of=None): | |
| """Which rows an automatic run should fill, and why the others were left alone. | |
| Returns `{'run': [row_id, ...], 'skipped': {reason: count}, 'estimate': int}`. | |
| β THE SELECTION IS SEPARATE FROM THE RUN ON PURPOSE. It is pure, so a gate can prove the | |
| never-overwrite-a-human-edit law without a vendor, and so the client can PREVIEW a run | |
| honestly before it spends anything -- which is exactly the complaint R13 cites (a preview | |
| that said 15 credits against a run that spent 360). | |
| `cost_of(row)` estimates one row's tokens; absent, the column's own ceiling is used per row, | |
| which is the pessimistic direction and the right one for a preview. | |
| """ | |
| import core.user_tables as ut | |
| cfg = config if isinstance(config, dict) else {} | |
| prompt = str(cfg.get('prompt') or '') | |
| policy = str(cfg.get('overwrite') or 'blank') | |
| refs = prompt_refs(prompt) | |
| per_row = int(cfg.get('maxTokens') or 0) | |
| run, skipped, estimate = [], {}, 0 | |
| for row_id, row in (rows or {}).items(): | |
| row = row if isinstance(row, dict) else {} | |
| mark = (marks or {}).get(str(row_id)) or {} | |
| fresh = ut.ai_enrich_input_hash(prompt, row, refs) | |
| has_value = bool(str(row.get(str(col_id)) or '').strip()) | |
| if ut.ai_enrich_may_write(mark, policy, fresh, has_value=has_value): | |
| run.append(str(row_id)) | |
| estimate += int(cost_of(row)) if callable(cost_of) else per_row | |
| else: | |
| # The same predicate again, so the count a preview shows and the cells a run leaves | |
| # alone can never be two different sets. | |
| reason = ('human_edited' if ut.ai_enrich_human_authored(mark, has_value) | |
| else 'unchanged' if has_value else 'skipped') | |
| skipped[reason] = skipped.get(reason, 0) + 1 | |
| return {'run': run, 'skipped': skipped, 'estimate': estimate} | |
| def cell_state(mark, config, row, col_id): | |
| """What ONE cell should say about itself: one of `CELL_STATES`. | |
| β `stale` and `empty` are computed here and never stored -- see the stratum's own note in | |
| `core/user_tables.py`. A stored staleness flag needs a sweep to stay true, and a sweep nobody | |
| runs is a flag shipped without its writer. | |
| """ | |
| import core.user_tables as ut | |
| mark = mark if isinstance(mark, dict) else {} | |
| has_value = bool(str((row or {}).get(str(col_id)) or '').strip()) | |
| if str(mark.get('state') or '') == 'error': | |
| return 'error' | |
| # β THE SAME PREDICATE THE RUNNER OBEYS, called rather than restated. A cell this reports as | |
| # the human's while `ai_enrich_may_write` would overwrite it is the worst of both answers. | |
| if ut.ai_enrich_human_authored(mark, has_value): | |
| return 'human' | |
| if str(mark.get('state') or '') != 'agent': | |
| return 'empty' | |
| cfg = config if isinstance(config, dict) else {} | |
| prompt = str(cfg.get('prompt') or '') | |
| fresh = ut.ai_enrich_input_hash(prompt, row or {}, prompt_refs(prompt)) | |
| return 'stale' if ut.ai_enrich_is_stale(mark, fresh) else 'agent' | |
| # ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ THE RUN | |
| # ββ THE LEDGER IS THE POINT OF THIS HALF. `ai_review.decide` (the product's only other LLM entry) | |
| # counts nothing: it sends `max_tokens: 300` and never reads `usage` off the response, so no run in | |
| # this product has ever been able to say what it cost. R13 asks for a token-usage limit, so the | |
| # accounting starts here, and every leg below reads `usage` even where it is not needed, because a | |
| # ledger with one blind provider is not a ledger. | |
| def _usage_tokens(body): | |
| """Total tokens for one call, from whichever shape the provider answered in. | |
| β RETURNS None WHEN THE PROVIDER DID NOT SAY, and the caller treats that as a real unknown | |
| rather than as zero. A ledger that silently books an unmeasured call at 0 reports a cheaper | |
| run than happened, which is exactly the cost-surprise complaint R13 cites. | |
| ββ W35-T41 / C7 β THE READER MOVED AND THIS IS NOW ONE LINE OVER IT. `usage_ledger.total_from` | |
| is the same logic, in the module that owns the meter; the alternative was a second reader in a | |
| second file answering the same question about the same key, which is the shape this repo pays | |
| for most often ([[one-question-two-normalizers]]). β The NAME and the None-semantics stay | |
| exactly as wave 34 wrote them, because `run_field`'s ceiling arithmetic reads this and a gate | |
| injects against its shape β lifting the body, not the signature. | |
| """ | |
| import usage_ledger | |
| return usage_ledger.total_from(body) | |
| def no_dashes(text): | |
| """Apply the shared prose normalizer before model text becomes a stored cell.""" | |
| return dash_norm.plain(text) | |
| #: What the model is told about its job. It fills ONE cell, so anything conversational it adds is | |
| #: a defect in the column rather than a nicety. `UNKNOWN` is the honest out: a row the data cannot | |
| #: answer is recorded as an error against that row, never as an invented value. | |
| #: β The dash sentence is here for the same reason lane D kept theirs: it costs nothing and it | |
| #: reduces how often `no_dashes` has to act. It is NOT the enforcement; `no_dashes` is. | |
| _SYSTEM = ('You fill in ONE cell of a spreadsheet. Answer with the value only: no preamble, no ' | |
| 'quotes, no markdown, no explanation. Never use an em dash or an en dash; use a comma, ' | |
| 'a colon or a full stop. If the information given does not let you answer, reply with ' | |
| 'exactly: UNKNOWN') | |
| def _ask(provider, model, prompt, max_tokens, timeout, system=None): | |
| """One cell's answer. `(text, tokens_or_None, problem)`; a truthy `problem` means no text. | |
| β Both request shapes are `ai_review`'s, changed in exactly two ways: they carry the COLUMN's | |
| ceiling instead of a hardcoded 300, and they read `usage` back. | |
| S67-T41: `system` replaces the one-cell instruction for a caller that is not filling a cell | |
| (Content Studio's drafts); every existing caller passes nothing and keeps `_SYSTEM`. | |
| """ | |
| system = system or _SYSTEM | |
| key = (os.environ.get(provider['env']) or '').strip() | |
| if not key: | |
| return '', None, f"{provider['name']} has no key on this deployment" | |
| try: | |
| if provider['shape'] == 'anthropic': | |
| r = requests.post( | |
| provider['url'], timeout=timeout, | |
| headers={'x-api-key': key, 'anthropic-version': '2023-06-01', | |
| 'content-type': 'application/json'}, | |
| json={'model': model, 'max_tokens': max_tokens, 'system': system, | |
| 'messages': [{'role': 'user', 'content': prompt}]}) | |
| if r.status_code >= 400: | |
| return '', None, f"{provider['name']} answered {r.status_code}" | |
| body = r.json() | |
| # β stop_reason FIRST. A safety refusal is a 200 with an EMPTY content list, so | |
| # reading content[0] before this turns a refusal into an IndexError inside the loop. | |
| if body.get('stop_reason') == 'refusal': | |
| return '', _usage_tokens(body), f"{provider['name']} declined this row" | |
| parts = [b.get('text') or '' for b in (body.get('content') or []) | |
| if isinstance(b, dict) and b.get('type') == 'text'] | |
| return ''.join(parts).strip(), _usage_tokens(body), '' | |
| r = requests.post( | |
| provider['url'], timeout=timeout, | |
| headers={'Authorization': f"Bearer {key}", 'Content-Type': 'application/json'}, | |
| json={'model': model, 'max_tokens': max_tokens, 'temperature': 0, | |
| 'messages': [{'role': 'system', 'content': system}, | |
| {'role': 'user', 'content': prompt}]}) | |
| if r.status_code >= 400: | |
| return '', None, f"{provider['name']} answered {r.status_code}" | |
| body = r.json() | |
| choices = body.get('choices') or [] | |
| if not choices: | |
| return '', _usage_tokens(body), f"{provider['name']} returned no choices" | |
| text = ((choices[0] or {}).get('message') or {}).get('content') or '' | |
| return str(text).strip(), _usage_tokens(body), '' | |
| except Exception as exc: # noqa: BLE001 | |
| return '', None, f"{provider['name']} failed: {type(exc).__name__}" | |
| # =========================================================================== | |
| # W37-T37 (R4 / C7) -- THE GEOCODE FIELD's pure half: turning a record into ONE query string. | |
| # | |
| # β WHY IT IS HERE AND NOT IN `routes_geo.py`. This module's contract, stated in its own header, | |
| # is that everything in it is a pure function of data it is handed -- which is what lets a gate | |
| # exercise it with no network, no store and no server. Composing an address is exactly that shape. | |
| # `routes_geo.py` owns the part that cannot be pure: the outbound call, the throttle and the cache. | |
| # | |
| # β WHY IT COMPOSES AT ALL, rather than sending the one column the field names. The field config | |
| # is `{addressField, country?}` -- a single column -- but a customers table stores an address across | |
| # six of them. B MEASURED the fill rates on the real 3,641-row mirror (W37-T11): | |
| # | |
| # street 96.2% Β· city 96.0% Β· zip 94.6% Β· country 95.6% Β· state 92.0% Β· street2 5.2% | |
| # street AND city together: 95.9% <- the pair this feature actually needs | |
| # | |
| # Sending `street` alone would ask a global geocoder to place "123 Main Street" with no town, which | |
| # resolves confidently and often wrongly. So the named column LEADS and the conventional siblings | |
| # follow, which is also how a person would write the address down. | |
| # =========================================================================== | |
| #: The sibling columns appended after the named one, in the order an address is spoken. β A LIST | |
| #: rather than a formatted string: a template would have to decide what to do about the ~4% of rows | |
| #: missing any one part, and the answer is always "leave it out", never "leave a gap". | |
| GEOCODE_PARTS = ('street2', 'city', 'state', 'zip', 'postal_code', 'country') | |
| #: β B's SECOND MEASURED TRAP. Odoo serves `state` as its DISPLAY name, country code included: | |
| #: `New York (US)`, `British Columbia (CA)`. A naive join yields "SCARSDALE, New York (US)", and the | |
| #: parenthetical is noise to a geocoder at best. Stripped here, once, rather than at each caller. | |
| _PAREN_TAIL = re.compile(r'\s*\([^)]*\)\s*$') | |
| def geocode_query(row, cfg, seen_parts=None): | |
| """One record plus a geocode field's config -> the query string, or '' when there is nothing. | |
| β RETURNS '' RATHER THAN A PARTIAL GUESS when the named column is empty. B measured ~150 of | |
| 3,641 customers with no street at all, and the honest UI for those is "no address on file", not | |
| a request that spends a second of a shared service's budget to place a bare postcode. | |
| β `seen_parts=None` RESOLVES `GEOCODE_PARTS` AT CALL TIME, and that is not style. It was | |
| `seen_parts=GEOCODE_PARTS`, which binds the tuple once at import, so the module constant stopped | |
| being the live answer the moment anything wanted to vary it: the gate's own negative control set | |
| `ai_enrich.GEOCODE_PARTS = ()` and the function carried on composing the full address. A default | |
| argument that captures a module constant is a SECOND COPY of it with an earlier timestamp, and | |
| the copy is the one that runs ([[a-constant-two-features-share]]). Caught by that control.""" | |
| if not isinstance(row, dict) or not isinstance(cfg, dict): | |
| return '' | |
| if seen_parts is None: | |
| seen_parts = GEOCODE_PARTS | |
| key = str(cfg.get('addressField') or '').strip() | |
| if not key: | |
| return '' | |
| lead = _clean_part(row.get(key)) | |
| if not lead: | |
| return '' | |
| parts = [lead] | |
| for k in seen_parts: | |
| if k == key: | |
| continue | |
| v = _clean_part(row.get(k)) | |
| # β The dedupe is not tidiness. `country` is often both the field's own value and already | |
| # present in the street line on an imported record, and "USA, USA" measurably degrades a | |
| # free-form geocoder's confidence. | |
| if v and v.lower() not in {p.lower() for p in parts}: | |
| parts.append(v) | |
| return ', '.join(parts) | |
| def _clean_part(v): | |
| """One address component, trimmed and stripped of a trailing country parenthetical.""" | |
| if v is None: | |
| return '' | |
| s = re.sub(r'\s+', ' ', str(v)).strip() | |
| if not s or s.lower() in ('false', 'none', 'null'): | |
| return '' | |
| return _PAREN_TAIL.sub('', s).strip() | |
| def geocode_plan(rows, cfg, coord_key=None, overwrite=False): | |
| """Which records a run would actually ask about, and why the rest are being left out. | |
| β THIS IS THE R3 GUARD IN ITS ARITHMETIC FORM. It is handed the records a PERSON chose; it | |
| never reads a table. `skipped` is returned rather than swallowed so the surface can say "142 to | |
| look up, 9 have no address, 31 already have coordinates" instead of a bare number.""" | |
| run, skipped = [], {} | |
| for rid, row in (rows or {}).items(): | |
| q = geocode_query(row, cfg) | |
| if not q: | |
| skipped['no_address'] = skipped.get('no_address', 0) + 1 | |
| continue | |
| if coord_key and not overwrite and str((row or {}).get(coord_key) or '').strip(): | |
| skipped['already_located'] = skipped.get('already_located', 0) + 1 | |
| continue | |
| run.append((str(rid), q)) | |
| return {'run': run, 'skipped': skipped} | |
| def on_change_fields(defn, changed_keys): | |
| """Which `ai_enrich` columns in this table want a run because one of their inputs moved. | |
| A column qualifies when its trigger is `on_change` AND its prompt names at least one of the | |
| columns that just changed. β A column that names NOTHING (a prompt with no `{token}`) never | |
| fires on change, whatever its trigger says: it would re-ask the same question of the same row | |
| forever, once per unrelated edit, and bill for every one. | |
| β PURE, AND HANDED THE DEFINITION IT SHOULD USE. `automation_engine.grid_hook` calls | |
| `all_definitions(st)` once PER EVENT, which turns a 20,000-row import into 20,000 whole | |
| document reads (`D-134`); this function reads no store at all, so the caller can do one read | |
| for a whole batch. Rebuilding that shape here was the one thing T54's ticket said not to do. | |
| """ | |
| import core.user_tables as ut | |
| touched = {str(k) for k in (changed_keys or ())} | |
| if not touched: | |
| return [] | |
| out = [] | |
| for field in ut.ai_enrich_fields(defn): | |
| cfg = field.get('aiEnrich') or {} | |
| if (cfg.get('trigger') or {}).get('mode') != 'on_change': | |
| continue | |
| refs = set(prompt_refs(cfg.get('prompt'))) | |
| # β A column never fires on a change to ITSELF. Its own value moving is either the run | |
| # that just wrote it or a person typing over it, and both would loop. | |
| refs.discard(str(field.get('key') or '')) | |
| if refs & touched: | |
| out.append(field) | |
| return out | |
| def scheduled_fields(defn): | |
| """`[(field, cron)]` for every enrichment column that runs on a cadence. | |
| β IT DOES NOT PARSE THE CRON AND MUST NOT. `core.user_tables` stores that string opaque | |
| precisely so the cadence vocabulary has ONE owner, and the owner is the scheduler | |
| (`automation_engine`), not the field layer. A second parser here would be a door that starts | |
| refusing a cadence the other one accepts, which is exactly the divergence the whole field | |
| contract keeps paying for ([[one-question-two-normalizers]]). | |
| β SO THIS IS HALF A FEATURE ON PURPOSE, and the other half is a cross-fence ask: something has | |
| to TICK. Nothing in lane F's fence runs on a timer. | |
| """ | |
| import core.user_tables as ut | |
| out = [] | |
| for field in ut.ai_enrich_fields(defn): | |
| trigger = ((field.get('aiEnrich') or {}).get('trigger') or {}) | |
| if trigger.get('mode') == 'schedule' and str(trigger.get('cron') or '').strip(): | |
| out.append((field, str(trigger['cron']))) | |
| return out | |
| def run_field(table_key, col_id, *, st, rows=None, manual=False, policy=None, budget=None, | |
| timeout=None, ask=None, user=''): | |
| """Fill one `ai_enrich` column over the rows an automatic run is allowed to touch. | |
| Returns a REPORT and never raises for a vendor problem: | |
| `{planned, filled, failed, skipped{reason: count}, tokens, provider, model, | |
| limit: <ceiling_report or None>, errors[], problem}` | |
| β THE RUN BUDGET IS DERIVED FROM THE COLUMN'S OWN CEILING, and the arithmetic is the point: | |
| `budget = maxTokens * planned`. `maxTokens` bounds the OUTPUT of one call while spend counts | |
| INPUT tokens too, so a real run crosses this before it finishes every row. That is intended: | |
| R13 asked for a token-usage limit and a ceiling that can never bite is not one. A caller may | |
| pass a TIGHTER `budget`; nothing may pass a looser one. | |
| β TWO STORE WRITES FOR THE WHOLE RUN, not two per row: one `patch_many_cells` for the values | |
| and one `stamp_ai_enrich` for the marks. Each is a read-modify-write of the whole tenant | |
| document, which is why `patch_cells` in a loop was never an option (D-134's shape). | |
| β `ask` is injectable so a gate can exercise the ledger, the ceiling and every failure path | |
| with no network and no vendor bill. It defaults to the real `_ask`. | |
| ββ W35-T41 / C7 β ONE USAGE-LEDGER LINE PER RUN, NOT PER ROW, and the arithmetic is the reason: | |
| this loop makes one LLM call per row, so a ledger write per call would be hundreds of store | |
| writes for one click. The run already accumulates `report['tokens']`; `calls` and `unmeasured` | |
| join it so the meter can say "40 calls, 12,000 tokens, 3 of them unmeasured" instead of a total | |
| with an unknown shortfall. `user` is the ledger's attribution and is passed by this file's own | |
| callers in `routes_tables`. | |
| """ | |
| import ai_review | |
| import core.user_tables as ut | |
| import usage_ledger | |
| defn = ut.get(table_key, st=st) or {} | |
| field = next((f for f in ut.ai_enrich_fields(defn) if f.get('key') == str(col_id)), None) | |
| if field is None: | |
| return {'problem': f'{col_id!r} is not an AI enrichment column on this database', | |
| 'planned': 0, 'filled': 0, 'failed': 0, 'skipped': {}, 'tokens': 0, | |
| 'errors': [], 'limit': None, 'provider': '', 'model': ''} | |
| cfg = field.get('aiEnrich') or {} | |
| # β THE BULK MENU'S TWO CHOICES ARE THIS ONE OVERRIDE (`W34-T54`): "Rows never filled" is | |
| # `blank` and "All rows" is `always`. β It overrides the column's SAVED POLICY for one run and | |
| # NOTHING ELSE: `ai_enrich_may_write` still refuses a human-edited cell under every value, so | |
| # "All rows" means every row the AGENT wrote, which is exactly what the menu label says. | |
| # β An unrecognised value falls back to the column's own setting rather than to a default: a | |
| # typo'd override must not quietly widen what a run touches. | |
| if policy in ut.AI_ENRICH_OVERWRITE: | |
| cfg = {**cfg, 'overwrite': policy} | |
| all_rows = defn.get('rows') or {} | |
| marks = ut.ai_enrich_marks(table_key, col_id, st=st) | |
| # ββ `rows` NARROWS; `manual` DECIDES WHETHER THE POLICY APPLIES. They are two questions and | |
| # an early draft of this function conflated them, which would have let an ON-CHANGE fire (an | |
| # automatic act, scoped to one row) overwrite a cell a person had typed into. That is the one | |
| # law this whole feature is arranged around, broken by a parameter name. | |
| # rows=None -> the automatic plan over every row | |
| # rows=[...], manual=False -> the automatic plan, INTERSECTED with those rows (on_change) | |
| # rows=[...], manual=True -> exactly those rows, policy skipped | |
| # `manual` is skippable because a person clicking "run this cell" has asked, in front of the | |
| # value being replaced; refusing them would be the product overruling an explicit act with a | |
| # rule written for an implicit one. `ai_enrich_may_write`'s own docstring says exactly this. | |
| # β A named row is always INTERSECTED with the table's own row set, so a stale caller cannot | |
| # name a record that has since been deleted. | |
| named = None if rows is None else [str(r) for r in rows if str(r) in all_rows] | |
| if named is not None and manual: | |
| plan = {'run': named, 'skipped': {}, | |
| 'estimate': int(cfg.get('maxTokens') or 0) * len(named)} | |
| else: | |
| plan = plan_rows(all_rows, col_id, cfg, marks) | |
| if named is not None: | |
| keep = set(named) | |
| dropped = [r for r in plan['run'] if r not in keep] | |
| plan = {**plan, 'run': [r for r in plan['run'] if r in keep]} | |
| if dropped: | |
| plan['skipped'] = {**plan['skipped'], 'not_in_this_run': len(dropped)} | |
| rows = all_rows | |
| keys = [f.get('key') for f in (defn.get('fields') or []) if f.get('key')] | |
| report = {'planned': len(plan['run']), 'filled': 0, 'failed': 0, | |
| 'skipped': dict(plan['skipped']), 'tokens': 0, 'errors': [], 'limit': None, | |
| 'provider': '', 'model': '', 'problem': '', | |
| # β C7's two counters. `calls` is what the meter bills; `unmeasured` is how many of | |
| # them the provider declined to report tokens for, so a total is never presented as | |
| # complete when it is a floor. | |
| 'calls': 0, 'unmeasured': 0} | |
| if not plan['run']: | |
| return report | |
| caller = ask or _ask | |
| ceiling = int(cfg.get('maxTokens') or 0) * len(plan['run']) | |
| if isinstance(budget, int) and not isinstance(budget, bool): | |
| ceiling = min(ceiling, max(0, budget)) | |
| live = ai_review.ladder() | |
| if not live and ask is None: | |
| # β FAIL CLOSED AND SAY SO. A run that quietly filled nothing looks identical to a run | |
| # with nothing to do; `planned` above is the number that distinguishes them. | |
| report['problem'] = 'no AI provider is configured on this deployment' | |
| return report | |
| provider = (live or [{'name': 'injected', 'model': 'injected', 'env': '', | |
| 'shape': 'openai', 'url': ''}])[0] | |
| model = str(cfg.get('model') or provider['model']) | |
| report['provider'], report['model'] = provider['name'], model | |
| tmo = float(timeout or TIMEOUT_SECONDS) | |
| values, stamps = {}, {} | |
| for row_id in plan['run']: | |
| if ceiling and report['tokens'] >= ceiling: | |
| # β STOP AND REPORT (R6's second sentence). Cells already written STAY written and | |
| # carry honest marks; nothing is truncated and no cell holds half an answer. | |
| report['limit'] = ceiling_report(report['tokens'], ceiling, | |
| report['filled'], report['planned']) | |
| left = report['planned'] - report['filled'] - report['failed'] | |
| if left > 0: | |
| report['skipped']['over_budget'] = left | |
| break | |
| row = rows.get(row_id) or {} | |
| text, unresolved = render_prompt(cfg.get('prompt'), row, keys) | |
| if unresolved: | |
| # Reported per row rather than refused up front: the prompt is valid for the column, | |
| # and naming the missing token is what lets somebody fix it. | |
| why = ('the prompt names ' + ', '.join(unresolved) | |
| + ', which is not a column on this database') | |
| report['failed'] += 1 | |
| stamps[row_id] = {'state': 'error', 'error': why} | |
| if len(report['errors']) < MAX_REPORTED_ERRORS: | |
| report['errors'].append({'row': row_id, 'error': why}) | |
| continue | |
| answer, tokens, problem = caller(provider, model, text[:MAX_CELL_CHARS * 8], | |
| int(cfg.get('maxTokens') or 300), tmo) | |
| # β COUNTED HERE, ON EVERY OUTCOME β before the `problem` branch below, because a call that | |
| # errored or answered UNKNOWN still reached the vendor and is still billed. A meter that | |
| # counts only filled cells reports a cheap run for one that spent its whole budget failing. | |
| report['calls'] += 1 | |
| if isinstance(tokens, int) and not isinstance(tokens, bool): | |
| report['tokens'] += tokens | |
| else: | |
| report['unmeasured'] += 1 | |
| if problem or not answer or answer.strip().upper() == 'UNKNOWN': | |
| # β THE CELL IS LEFT ALONE. An errored row keeps whatever it held; only the MARK | |
| # changes, so a failed run never destroys a value it could not replace. | |
| why = problem or ('the model had nothing to answer from' if not answer | |
| else 'the model answered UNKNOWN for this row') | |
| report['failed'] += 1 | |
| stamps[row_id] = {'state': 'error', 'error': why, 'model': model} | |
| if len(report['errors']) < MAX_REPORTED_ERRORS: | |
| report['errors'].append({'row': row_id, 'error': why}) | |
| continue | |
| # β NORMALISED BEFORE THE WRITE, NOT AFTER (note D-6). This is the ONE line where model | |
| # prose becomes stored product data; a cell fixed after the fact leaves every row already | |
| # written carrying the dash, and `web_prose` can never see it because it scans source. | |
| values[row_id] = no_dashes(answer)[:MAX_CELL_CHARS] | |
| stamps[row_id] = {'state': 'agent', 'model': model, | |
| 'hash': ut.ai_enrich_input_hash(cfg.get('prompt'), row, | |
| prompt_refs(cfg.get('prompt'))), | |
| 'tokens': tokens if isinstance(tokens, int) else 0} | |
| report['filled'] += 1 | |
| if values: | |
| ut.patch_many_cells(table_key, {r: {str(col_id): v} for r, v in values.items()}, st=st) | |
| if stamps: | |
| ut.stamp_ai_enrich(table_key, col_id, stamps, st=st) | |
| # β The ceiling is re-asked AFTER the loop too: a run whose LAST row crossed the budget spent | |
| # over it without re-entering the guard, and staying silent there would under-report the one | |
| # run most likely to surprise somebody. | |
| if report['limit'] is None and ceiling and report['tokens'] >= ceiling: | |
| report['limit'] = ceiling_report(report['tokens'], ceiling, | |
| report['filled'], report['planned']) | |
| # ββ C7's LEDGER LINE β one per run, after both store writes, and only when the run actually | |
| # called something. `total=` rather than a split: `_ask`'s contract returns a total and a gate | |
| # injects against that shape, so splitting it here would mean inventing two numbers from one. | |
| # | |
| # β TWO LINES WHEN A RUN HAS BOTH KINDS, and it is not tidiness. `record` marks a line | |
| # `unmeasured` only when its total is None, so ONE line carrying 40 calls and a partial total | |
| # would book all forty as measured and lose the shortfall β a total presented as complete when | |
| # it is a floor, which is the exact failure `_usage_tokens`' None-semantics exists to prevent. | |
| _measured = report['calls'] - report['unmeasured'] | |
| if _measured > 0: | |
| usage_ledger.record('field_agent', report['provider'], report['model'], | |
| total=report['tokens'], calls=_measured, st=st, user=user) | |
| if report['unmeasured'] > 0: | |
| usage_ledger.record('field_agent', report['provider'], report['model'], | |
| total=None, calls=report['unmeasured'], st=st, user=user) | |
| return report | |