"""The Live tool: an answer newer than the last sync, the mirror with source changes overlaid by id.""" import copy import datetime as dt import json import re from contextlib import contextmanager, nullcontext from core import external_tools, perm_scope, periods import deps import external_freshness #: Rows per `rows` page. Paging only: every row of the window is reachable (rule 1). PAGE = 200 _DAY = {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"} WINDOW_SCHEMA = { "type": "object", "description": "Inclusive business days in the tenant's timezone. Omit for today.", "properties": {"date_from": copy.deepcopy(_DAY), "date_to": copy.deepcopy(_DAY)}, "required": ["date_from", "date_to"], "additionalProperties": False, } _SQL_COLUMN = r"^{alias}\.([a-z_][a-z0-9_]*)$" #: The day basis every answer states. DAY_BASIS = "business day in the tenant's timezone" class _Unavailable(Exception): """The live answer cannot run for this database. Carries a client error.""" def __init__(self, status, code, message, details=None): super().__init__(message) self.error = deps.err(status, code, message, details=details) def _arguments(ctx, args, action): if not isinstance(ctx, external_tools.ToolContext): raise deps.err(403, "tool_context_required", "Use the authenticated Live tool.") external_tools.validate_arguments(args, GROUP["actions"][action]["schema"]) def _limiter_store(session): runtime = session.runtime if all(callable(getattr(runtime, name, None)) for name in ("get", "revision", "update")): return runtime return None def _source(session): """The tenant's bound Odoo source, refused when the runtime is another tenant's.""" runtime = session.runtime if runtime.key != session.tenant: raise _Unavailable(403, "live_unavailable", "This tenant's data is not bound to this call.") runtime.assert_datastore_matches() source = runtime.odoo_source() if source is None: raise _Unavailable(409, "live_unavailable", "No source is connected for this database.", {"cause": "no_source", "fix": "Connect the source under Connectors."}) return source @contextmanager def _mirror_days(session): """Bind the stored business timezone without opening an Odoo connection.""" from core import odoo from routes_keychain import stored_business_tz with odoo.tenant_scope(session.tenant): odoo._ctx()['business_tz'] = stored_business_tz(session.runtime) yield def _binding(database): """`(mirror table, alias, definition SQL, spec)` for a database served from one synced table.""" import routes_odoo_tables spec = routes_odoo_tables._sources().get(database) if not spec: raise _Unavailable(404, "live_unavailable", "This database has no live source.", {"cause": "no_live_source", "fix": "Ask about a database a connector syncs."}) identity = str(spec.get("id") or "") alias = identity.split(".")[0] if re.fullmatch(r"[a-z_]+\.id", identity) else None table = (spec.get("tables") or {}).get(alias) if alias else spec.get("table") alias = alias or table if not table or not alias: raise _Unavailable(409, "live_unavailable", "This database is not served from one synced table.", {"cause": "unsupported_database", "fix": "Read this database from the mirror."}) return table, alias, str(spec.get("where") or ""), spec def _projection(spec, alias, keys): """`project(row)` mapping a mirror row to the database's field keys a plain column binds.""" pattern = re.compile(_SQL_COLUMN.format(alias=re.escape(alias))) days = set(spec.get("business_days") or ()) plan = {} for key, binding in (spec.get("cols") or {}).items(): found = pattern.match(str(binding[0]).strip()) if key in keys else None if found: plan[key] = (found.group(1), binding[1], key in days) elif key in keys and re.fullmatch(r'"?[a-z_][a-z0-9_]*"?', str(binding[0]).strip()): plan[key] = (str(binding[0]).strip().strip('"'), binding[1], key in days) def project(row): out = {} for key, (column, convert, business_day) in plan.items(): value = row.get(column) if business_day: day = periods.business_day(value) out[key] = day.isoformat() if day else "" else: try: out[key] = convert(value) except (TypeError, ValueError): out[key] = None return out return plan, project def _fields(ctx, database): """The caller's visible fields of `database`, after the field wall.""" session = ctx.session ctx.describe_database(database) snapshot = deps.assistant_read_scope(session, database, mode="schema") if snapshot.get("database") != database or not snapshot.get("permission_scope_applied") \ or not snapshot.get("fields"): raise _Unavailable(403, "live_unavailable", "You cannot read this database.") return perm_scope.visible_fields(list(snapshot["fields"]), session.user, database, st=session.runtime) def _windows(args): """`(window, prior window or None, grain, rule)` under the shared YoY rule.""" from tool_groups import metrics today = periods.today().isoformat() sent = args.get("window") or {"date_from": today, "date_to": today} window = {"date_from": sent["date_from"], "date_to": sent["date_to"]} try: days = (dt.date.fromisoformat(window["date_to"]) - dt.date.fromisoformat(window["date_from"])).days + 1 except ValueError: days = 0 if days < 1: raise deps.err(400, "live_window_invalid", "The window needs a start day on or before its end day.") if days not in (1, 7) and args.get("compare") != "yoy": return window, None, None, None grain = metrics._compare_grain({"name": "date_range", **window}) prior, rule = metrics._prior_window({"name": "date_range", **window}, grain) return window, {"date_from": prior["date_from"], "date_to": prior["date_to"]}, grain, rule def _summary(entry): live = entry.get("live") return {"live_value": live["value"] if live else None, "live_rows": live["rows"] if live else None, "screen_value": entry["screen"]["value"], "screen_rows": entry["screen"]["rows"], "difference": entry.get("difference")} def _observe(ctx, args, action): """Run one windowed live answer and shape the shared summary.""" from core import connector_spec from harness import filter_eval, filter_sql, live_read, semantic _arguments(ctx, args, action) session = ctx.session database = args["database"] try: if session.runtime.key != session.tenant: raise _Unavailable(403, "live_unavailable", "This tenant's data is not bound to this call.") session.runtime.assert_datastore_matches() table, alias, where, spec = _binding(database) connector, _table, mode = live_read.resolve_table(table) if connector == 'meta': import routes_odoo_tables cur = routes_odoo_tables._table_cursor(session.runtime, database) try: spec = routes_odoo_tables._meta_source(cur, database) or spec finally: cur.close() fields = _fields(ctx, database) visible = [f["key"] for f in fields if isinstance(f, dict) and f.get("key")] plan, project = _projection(spec, alias, set(visible)) date_field = args.get("date_field") or next(iter(spec.get("business_days") or ()), None) if date_field is None and connector == 'meta': from harness import meta_store if table == meta_store.INSIGHTS_TABLE: date_field = 'date_start' if date_field is not None and date_field not in plan: raise _Unavailable(400, "live_field_invalid", "Name a visible date field of this database.", {"cause": "date_field", "fix": "Send date_field from describe_database."}) measure = args.get("measure") generic = mode.mode != connector_spec.LIVE_CURSOR or bool(args.get('filters')) bound = set(spec.get('cols') or {}) if generic else set(plan) if measure is not None and measure not in bound.intersection(visible): raise _Unavailable(400, "live_field_invalid", "Name a visible number field to total.", {"field": measure, "cause": "measure", "fix": "Send measure from describe_database."}) numeric = filter_eval.NUMERIC_TYPES | filter_sql.NUMERIC_TYPES | {'number', 'float'} if measure is not None and next(f for f in fields if f['key'] == measure).get('type') not in numeric: raise _Unavailable(400, "live_field_invalid", "The measure must be a number field.", {"field": measure, "cause": "non_numeric_measure", "fix": "Choose a visible number field from describe_database."}) store = _limiter_store(session) if store is None: raise _Unavailable(409, "live_unavailable", "This workspace has no live call limiter.", {"cause": "no_limiter", "fix": "Answer from the mirror."}) source = _source(session) if connector == 'odoo' and mode.mode != connector_spec.LIVE_NONE else None with semantic.tenant_context(session.runtime) if source else nullcontext(), \ source._bound() if source else _mirror_days(session): if date_field is None: if args.get('window') or args.get('compare'): raise _Unavailable(400, "live_field_invalid", "This database has no default date field.", {"cause": "date_field", "fix": "Omit window and compare for a current slice."}) window, prior, grain, rule = None, None, None, None else: window, prior, grain, rule = _windows(args) windows = {"current": (window["date_from"], window["date_to"]) if window else (None, None)} if prior: windows["prior"] = (prior["date_from"], prior["date_to"]) column, _convert, instants = plan[date_field] if date_field else (None, None, False) wall = {"user": session.user, "database": database, "fields": fields, "st": session.runtime} extra = {} if generic: import routes_odoo_tables nodes = args.get('filters') or [] columns = routes_odoo_tables._filter_columns(spec, fields) named = routes_odoo_tables._leaf_cols(nodes) if not named <= set(visible).intersection(columns): raise _Unavailable(400, "live_field_invalid", "A filter needs a visible bound field.", {"cause": "filter_field", "fix": "Choose fields from describe_database."}) try: predicate = filter_sql.compile_filter_tree(nodes, columns=columns, today=periods.today()) except ValueError: raise _Unavailable(400, "live_filter_invalid", "This filter cannot answer at source row grain.", {"cause": "unsupported_filter", "fix": "Use a comparison on a source field."}) from None if nodes and (predicate is None or predicate.uses_aggregate or predicate.columns_used != named): raise _Unavailable(400, "live_filter_invalid", "This filter cannot answer at source row grain.", {"cause": "unsupported_filter", "fix": "Use an active comparison on a source field."}) domain = [] if mode.mode == connector_spec.LIVE_SLICE: operators = {'eq': '=', 'neq': '!=', 'gt': '>', 'gte': '>=', 'lt': '<', 'lte': '<=', 'isAnyOf': 'in', 'isNoneOf': 'not in'} for node in nodes: key, op = node.get('colId'), node.get('op') if key not in plan or op not in operators or node.get('rhs'): continue # Identity filters bound the source read without changing display rounding or text matching. filter_column = plan[key][0] if filter_column != 'id' and not filter_column.endswith('_id'): continue value = node.get('values', node.get('value')) convert = plan[key][1] try: value = [convert(v) for v in value] if isinstance(value, list) else convert(value) except (TypeError, ValueError): raise _Unavailable(400, "live_filter_invalid", "The slice filter has an invalid value.", {"field": key, "cause": "filter_value", "fix": "Use a value of the field's declared type."}) from None domain.append((filter_column, operators[op], value)) if not domain: raise _Unavailable(400, "live_filter_invalid", "A current slice needs a source filter.", {"cause": "unbounded_slice", "fix": "Filter product_id for one SKU."}) live_read.slice_domain(live_read.datastore.ENTITIES[table], domain) definition = copy.copy(spec) definition['cols'] = dict(spec['cols']) if date_field: definition['cols'][live_read._WINDOW_KEY] = (spec['cols'][date_field][0], lambda v: v) keys = set(visible) | {live_read._WINDOW_KEY} extra = {'definition': definition, 'domain': domain, 'filters': {'conj': 'and', 'nodes': nodes} if nodes else None} project = keys answer = live_read.window_answer( table, store, alias=alias, where=where, date_column=column, instants=instants, windows=windows, project=project, wall=wall, measure=measure, tenant_key=session.runtime.key, caller="live." + action, **extra) except _Unavailable as exc: raise exc.error from None except live_read.LiveReadError as exc: raise deps.err(409, "live_unavailable", exc.message, details=exc.as_dict()) from None fact = (external_freshness.snapshot(session, [database]) or {}).get(database) or {} current = answer["windows"]["current"] result = {"database": database, "mode": mode.mode, "measure": measure, "date_field": date_field, "day_basis": DAY_BASIS if window else None, "window": window, "served": answer["served"], **_summary(current), "last_sync": fact.get("source_synced_at"), "source_sync": fact.get("source_sync"), "delta": {"read": answer["delta"], "replaced": answer["replaced"], "added": answer["added"]}} if answer["limit_refusal"]: result["limit_refusal"] = answer["limit_refusal"] if answer["live_unavailable"]: result["live_unavailable"] = answer["live_unavailable"] if prior: result.update({"compare": "yoy", "compare_rule": rule, "compare_grain": grain, "prior": {"window": prior, **_summary(answer["windows"]["prior"])}}) return result, answer["rows"]["current"], visible def answer(ctx, args): """Total or count a database window or current slice with its screen value and difference.""" result, _rows, _visible = _observe(ctx, args, "answer") return result def rows(ctx, args): """Read one page of the scoped live or mirror slice.""" result, found, visible = _observe(ctx, args, "rows") start = int(args.get("cursor") or 0) page = [{key: row.get(key) for key in visible if key in row} for row in found[start:start + PAGE]] nxt = start + PAGE if start + PAGE < len(found) else None return {**result, "rows": page, "row_count": len(found), "next_cursor": nxt} def _action(handler, extra=None): properties = { "database": {"type": "string", "minLength": 1, "description": "Database key from table.list_databases."}, "measure": {"type": "string", "minLength": 1, "description": "Number field key to total. Omit to count rows."}, "date_field": {"type": "string", "minLength": 1, "description": "Date field key the window applies to. Omit for the default."}, "window": copy.deepcopy(WINDOW_SCHEMA), "filters": {"type": "array", "items": external_tools._query_filter_node(depth=3, allow_link=False), "description": "AND filters in the table vocabulary. For current stock, filter product_id for one SKU."}, "compare": {"type": "string", "enum": ["yoy"], "description": "Add the prior year window for any window."}, **(extra or {}), } return {"read": True, "destructive": False, "confirm": False, "schema": {"type": "object", "description": handler.__doc__, "properties": properties, "required": ["database"], "additionalProperties": False}, "handler": handler} GROUP = { "name": "live", "title": "Live", "guide": "Call live only when the question needs data newer than the last sync, such as today's " "orders. Otherwise read table. Live follows the connector's declared mode: source changes " "overlaid on the mirror by id, a bounded current slice, a live API, or the mirror with " "the reason no live read exists. It never updates mirrored rows and screens keep the mirror. " "Answer requires database and returns live_value, screen_value, difference and last_sync. " "Measure totals a number field, else rows are counted. The window is business days in the " "tenant's timezone and defaults to today for a dated database. Current slices need " "filters and can omit the date field and window. A one day or seven day window adds prior under " "compare_rule, the same weekday 364 days back. Rows returns the window's rows in pages. " "State the screen and live values and their difference. Over the live call limit the mirror " "answers, with limit_refusal naming the cause, next allowed time and fix.", "actions": {"answer": _action(answer), "rows": _action(rows, {"cursor": {"type": "integer", "minimum": 0, "description": "next_cursor from the previous page."}})}, } _INTENT = {"type": "string", "minLength": 1, "maxLength": 500} LOOPY_SCHEMA = {"type": "object", "properties": {"action": {"type": "string", "enum": sorted(GROUP["actions"])}, "arguments": {"type": "object"}, "intent": copy.deepcopy(_INTENT)}, "required": ["action"], "additionalProperties": False} def loopy(session, args): """Serve the Assistant's Live group through the same MCP admission and dispatcher.""" from routes_external import _dispatch_mcp reply = _dispatch_mcp({"jsonrpc": "2.0", "id": "loopy-live", "method": "tools/call", "params": {"name": "live", "arguments": args}}, session) return json.loads(reply["result"]["content"][0]["text"]) TOOLS = [{"name": "live", "schema": {**LOOPY_SCHEMA, "description": GROUP["guide"]}, "fn": loopy, "effect": "read"}]