Download platform/core/external_tools.py from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 52.7 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/platform/core/external_tools.py
- Command line
-
hf download hf://spaces/fsanyoto/loopable@9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/platform/core/external_tools.py
-
curl -L -o external_tools.py https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/platform/core/external_tools.py
52.7 kB
"""External build tools over the app's Sheet, saved View and Application writers.
The API supplies its existing permission, read-projection and binding-resolution functions as
request-scoped callbacks. Core never imports API modules or chooses another tenant runtime.
Adding a tool means adding a registry entry; writes also require the router's literal allow-list.
"""
import copy
import json
import math
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, Optional
from core import perm_scope, sheets, sheet_structure, sheet_templates, write_execution
# Keep supported versions in release order, with the newest last.
MCP_SUPPORTED_PROTOCOL_VERSIONS = ("2025-06-18",)
def negotiate_mcp_protocol(requested=None) -> str:
"""Return the requested supported version or the newest supported version."""
if requested is not None and not isinstance(requested, str):
raise ValueError("The protocol version must be a string.")
if requested in MCP_SUPPORTED_PROTOCOL_VERSIONS:
return requested
return MCP_SUPPORTED_PROTOCOL_VERSIONS[-1]
CELL_FIGURE_RULE = (
"A figure a database can supply goes in a cell database or a calculation object, "
"and a typed value is for a title, a label or an assumption."
)
BUILD_TAGS = tuple(json.loads(
(Path(__file__).resolve().parents[1] / "build_tags.json").read_text(encoding="utf-8")))
_BUILD_TEXT = r"^(?=.*\S)[^\u0000-\u001f\u007f\u0085\u2013\u2014\u2028\u2029]+(?![\s\S])"
ABOUT_SCHEMA = {
"type": "object", "additionalProperties": False,
"properties": {
"title": {"type": "string", "minLength": 1, "maxLength": 240, "pattern": _BUILD_TEXT},
"description": {"type": "string", "minLength": 20, "maxLength": 240, "pattern": _BUILD_TEXT},
"tags": {"type": "array", "minItems": 1, "uniqueItems": True,
"items": {"type": "string", "enum": list(BUILD_TAGS)}},
}, "required": ["title", "description", "tags"],
}
@dataclass(frozen=True)
class ToolContext:
session: object
actor_name: str
require_reader: Callable
require_editor: Callable
project_book: Callable
resolve_binding: Callable
cache_binding: Callable
list_databases: Callable
describe_database: Callable
query_database: Callable
view_event: Callable
view_share_preview: Callable
app_upsert: Callable
app_delete: Callable
database_object: Optional[Callable] = None
sheet_object: Optional[Callable] = None
validated_batch: Optional[Callable] = None
confirm_change: Optional[Callable] = None
def _object(properties=None, required=(), **extra):
return {"type": "object", "properties": properties or {}, "required": list(required), **extra}
_STRING = {"type": "string"}
_ADDRESS = {"type": "string", "description": "An A1 cell address on the named tab."}
_FORMAT = _object({"kind": _STRING, "code": _STRING, "decimals": {"type": "integer"},
"currency": _STRING, "thousands": {"type": "boolean"}}, ("kind",))
# S67-T14 / contract C2: a border side is the legacy `true` (read as a thin black line) or
# `{style, color}` with one of Excel's seven line styles and a six digit hex colour; `false` or an
# absent side is no side. `sheets.py::_clean_border_side` refuses anything else by code, and this
# publishes the same shape so an AI client can draw a styled border at all.
_BORDER_SIDE = {"oneOf": [{"type": "boolean"}, _object({
"style": {"enum": list(sheets.CELL_BORDER_STYLES)},
"color": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}}, ("style", "color"))]}
_STYLE = _object({
**{key: {"type": "boolean"} for key in ("bold", "italic", "underline", "strike", "wrap")},
**{key: _STRING for key in ("fill", "color", "font", "align", "valign")},
"size": {"type": ["number", "string"]}, "indent": {"type": "integer"},
"textRotation": {"type": "number"}, "format": _FORMAT,
"border": _object({side: _BORDER_SIDE for side in ("top", "right", "bottom", "left")}),
})
_VALIDATION = _object({"list": {"type": "array", "items": _STRING}}, ("list",))
# Mirror the grid vocabulary without importing the API. verify_api checks parity.
FILTER_OPS = frozenset({
"contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty",
"gt", "gte", "lt", "lte", "between", "within",
"topN", "bottomN", "inTopPct", "inBottomPct", "aboveAvg", "belowAvg",
"inQuartile", "inDecile", "isAnyOf", "isNoneOf", "hasAnyOf", "hasAllOf", "hasNoneOf",
})
_FILTER_OP = {"type": "string", "enum": sorted(FILTER_OPS)}
_FILTER = _object({"conj": {"enum": ["and", "or"]}, "nodes": {"type": "array", "items": _object({
"colId": _STRING, "op": _FILTER_OP, "value": {},
"valueRef": _object({"ref": _ADDRESS}, ("ref",)),
"conj": _STRING, "children": {"type": "array", "items": {"type": "object"}},
})}})
def _query_filter_node(depth=1, *, allow_link=True):
"""Publish bounded query nodes without adding link conditions to saved View bindings."""
leaf = _object({
"id": _STRING, "colId": _STRING, "op": _FILTER_OP, "value": {}, "value2": {},
"values": {"type": "array", "items": _STRING, "minItems": 1, "maxItems": 100},
"rhs": _object({"kind": {"enum": ["field"]}, "colId": _STRING}, ("kind", "colId"),
additionalProperties=False),
}, ("colId", "op"), additionalProperties=False)
nodes = [leaf]
if depth < 3:
nodes.append(_object({"conj": {"enum": ["and", "or"]}, "children": {
"type": "array", "minItems": 1, "maxItems": 50,
"items": _query_filter_node(depth + 1, allow_link=allow_link),
}}, ("conj", "children"), additionalProperties=False))
if allow_link:
nodes.append(_object({
"link": _STRING,
"where": _query_filter_node(allow_link=False),
}, ("link", "where"), additionalProperties=False,
description="One link condition per call. The target database and join fields must be readable. "
"Use AND to intersect this pin with source filters."))
return {"oneOf": nodes}
_QUERY_FILTER_NODE = _query_filter_node()
_QUERY_FILTER = {"oneOf": [
_object({"conj": {"enum": ["and", "or"]}, "nodes": {
"type": "array", "minItems": 1, "maxItems": 50, "items": _QUERY_FILTER_NODE,
}}, ("conj", "nodes"), additionalProperties=False),
{"type": "array", "minItems": 1, "maxItems": 50, "items": _QUERY_FILTER_NODE},
_object({"link": _STRING, "where": _query_filter_node(allow_link=False)},
("link", "where"), additionalProperties=False),
]}
_CLIENT_QUERY_LEAF = {"anyOf": [
_QUERY_FILTER_NODE,
_object({"field": _STRING, "op": _FILTER_OP, "value": {}},
("field", "op"), additionalProperties=False),
_object({"field": _STRING, "operator": {"enum": ["="]}, "value": {}},
("field", "operator"), additionalProperties=False),
]}
_CLIENT_QUERY_NODES = {"type": "array", "minItems": 1, "maxItems": 50,
"items": _CLIENT_QUERY_LEAF}
_CLIENT_QUERY_FILTER = {"anyOf": [
_QUERY_FILTER, _CLIENT_QUERY_LEAF, _CLIENT_QUERY_NODES,
*[_object({conj: _CLIENT_QUERY_NODES}, (conj,), additionalProperties=False)
for conj in ("and", "or")],
_object(additionalProperties={"type": ["string", "number", "boolean", "null"]}),
]}
FILTER_NODE_REF = "#/$defs/filter_node"
FILTER_NODE_EXAMPLE = {"conj": "and", "nodes": [
{"colId": "status", "op": "eq", "value": "open"},
{"conj": "or", "children": [{"colId": "amount", "op": "gt", "value": 100},
{"colId": "region", "op": "eq", "value": "West"}]},
]}
def _is_filter_node(value):
"""Tell a published query filter node from any other schema."""
branches = value.get("oneOf") if isinstance(value, dict) and set(value) == {"oneOf"} else None
first = branches[0] if isinstance(branches, list) and branches and isinstance(branches[0], dict) else {}
properties = first.get("properties")
return isinstance(properties, dict) and "colId" in properties and "op" in properties
def guide_schema(schema):
"""Return a guide copy with each query filter node replaced by one reference, and whether any was."""
if _is_filter_node(schema):
return {"$ref": FILTER_NODE_REF}, True
if isinstance(schema, list):
pairs = [guide_schema(item) for item in schema]
return [item for item, _ in pairs], any(used for _, used in pairs)
if not isinstance(schema, dict):
return copy.deepcopy(schema), False
pairs = {key: guide_schema(child) for key, child in schema.items()}
return {key: item for key, (item, _) in pairs.items()}, any(used for _, used in pairs.values())
def filter_node_guide():
"""Return the one markdown section that defines the filter_node reference in a guide."""
node = {"oneOf": [guide_schema(branch)[0] for branch in _QUERY_FILTER_NODE["oneOf"]]}
return ("## filter_node\n\n"
"A filter_node is a condition {colId, op, ...}, a group {conj, children: 1 to 50 filter_node}, "
"or a link {link, where}.\n"
"Groups nest at most two deep inside one node. A link's where holds no link.\n"
"Example filter: `" + json.dumps(FILTER_NODE_EXAMPLE, ensure_ascii=True) + "`\n"
"```json\n" + json.dumps({"$defs": {"filter_node": node}}, ensure_ascii=True, indent=2) + "\n```")
_BINDING = _object({
"database": _STRING,
"aggregate": _object({"fn": _STRING, "field": _STRING, "metric_key": _STRING}),
"scope": _object({"filter": _FILTER, "view_id": _STRING, "view_name": _STRING}),
"period": _object({"unit": _STRING, "start": _STRING}),
"ending": {"type": "object"},
}, ("database", "aggregate", "scope"))
_RANGE = {"oneOf": [_STRING, _object({key: {"type": "integer", "minimum": 0}
for key in ("col0", "row0", "col1", "row1")},
("col0", "row0", "col1", "row1"))]}
# S67-T18: an in-cell sparkline, `{kind, range}` exactly as `sheets.py::_clean_sparkline` stores
# it; the range is a rectangle on the SAME tab (an A1 range such as "B2:M2", or the dict).
_SPARKLINE = _object({"kind": {"enum": list(sheets.SPARKLINE_KINDS)}, "range": _RANGE},
("kind", "range"))
_CELL = _object({"kind": {"enum": ["literal", "formula", "bound", "empty"]},
"value": {}, "text": _STRING, "formula": _STRING, "state": _STRING,
"style": _STYLE, "validation": _VALIDATION, "binding": _BINDING,
"sparkline": _SPARKLINE}, ("kind",))
_FIGURE_SOURCES = {
"type": "object",
"description": (
"Optional fields used together for each typed number, keyed by cell address. "
"List fields from both databases when the figure needs a join. "
"The preview names the join limit only when at least two visible databases are listed "
"and the workbook already reads one of them. This does not create a binding or a join."
),
"additionalProperties": {
"type": "array", "minItems": 1, "maxItems": 8,
"items": _object({"database": _STRING, "field": _STRING}, ("database", "field"),
additionalProperties=False),
},
}
# S67-T13: a colour scale's two ends and what each end means. `sheets.py::_clean_rules` refuses
# a type outside `SHEET_RULE_SCALE_TYPES`; the enum publishes the same list to the caller.
_SCALE_TYPE = {"enum": list(sheets.SHEET_RULE_SCALE_TYPES)}
_RULE = _object({"id": _STRING, "range": _RANGE, "kind": _STRING, "op": _STRING,
"value": {}, "value2": {}, "formula": _STRING, "style": _STYLE,
"scale": _object({"low": _STRING, "high": _STRING,
"minType": _SCALE_TYPE, "maxType": _SCALE_TYPE})},
("range", "op"))
_CHART = _object({"id": _STRING, "kind": _STRING, "range": _RANGE, "title": _STRING,
"stacking": _STRING, "source": {"type": "object"},
"series": {"type": "array", "items": {"type": "object"}},
"geometry": {"type": "object"}, "anchor": {"type": "object"},
"settings": {"type": "object"}}, ("kind", "range"))
_TARGET = {"workbook_id": _STRING,
"tab": {"type": "string", "description": "Tab id or tab name."},
"rev": {"type": "integer", "description": "Optional expected workbook revision."}}
_VIEW_CONFIG = _object({
"filters": {"oneOf": [_FILTER, {"type": "array", "items": {"type": "object"}}]},
"filterConj": {"enum": ["and", "or"]},
"sorts": {"type": "array", "items": _object({
"colId": _STRING, "dir": {"enum": ["asc", "desc"]},
"locked": {"type": "boolean"}}, ("colId", "dir"))},
"groupBy": {"type": ["string", "null"]},
"visible": {"type": "array", "items": _STRING,
"description": "Fields to show. Fields omitted from this list are hidden."},
"order": {"type": "array", "items": _STRING},
"display": _object({"mode": _STRING}, ("mode",)),
}, description="The View's filters, sorting, visible fields and display settings.")
_APPLICATION = {
"app_id": {"type": "string", "minLength": 1,
"description": "Omit to create. Supply an id to update mutable properties."},
"name": _STRING,
# Mirrors application_registry.APPLICATION_TYPES (core may not import the API layer).
"type": {"enum": ["chart", "route", "map", "code"]},
"compatibleDatabases": {"type": "array", "items": _STRING},
"sourceDatabase": {"type": "string", "description": "Source for a template Application only."},
# Mirrors aios-web/api/app_templates.TEMPLATES kinds; api_app_templates holds the parity.
"templateKind": {"enum": ["route", "catalog", "competitor_watch", "ranking_diagnostic",
"amazon_operator", "restock_planner", "reimbursements", "aged_stock",
"opportunity_finder", "returns_refunds", "repeat_buyers", "payouts", "account_health",
"amazon_dashboard", "amazon_profit", "alerts", "reports"]},
"fieldMap": {"type": "object", "additionalProperties": _STRING},
"navPlacement": _object({"section": {"const": "app"},
"order": {"type": "integer", "minimum": 0, "maximum": 999}},
("section", "order"), additionalProperties=False),
"semanticRoleBindings": {"type": "object"},
"config": _object({"schemaVersion": {"const": 1},
"display": _object({"mode": _STRING}, ("mode",))},
("schemaVersion", "display"), additionalProperties=False),
"share": _object({"mode": {"enum": ["private", "users", "tenant"]},
"users": {"type": "array", "items": _STRING}}, ("mode",)),
"starred": {"type": "boolean"},
}
def _schema(properties, required=(), *, tab=True):
return _object({**_TARGET, **properties},
("workbook_id", *(("tab",) if tab else ()), *required),
additionalProperties=False)
def _book(ctx, args, *, write=False):
book = sheets.get_workbook(ctx.session.runtime, args["workbook_id"])
(ctx.require_editor if write else ctx.require_reader)(book)
return book
def _saved(book, tab=None):
out = {"id": book["id"], "rev": book["rev"],
"tabs": [{"id": row["id"], "name": row["name"]} for row in book["sheets"]]}
if tab is not None:
out["tab"] = tab
return out
def _put(ctx, args, book, tab=None):
# Carry the revision read for this document patch even when the client omitted one.
# Never overwrite an intervening UI save with the older snapshot we just patched.
if "rev" in args:
book["rev"] = args["rev"]
return _saved(sheets.put_workbook(ctx.session.runtime, book["id"], book,
actor=ctx.session.uname, actor_name=ctx.actor_name), tab)
def _create(ctx, args):
return _saved(sheets.create_workbook(ctx.session.runtime, name=args["name"],
created_by=ctx.session.uname,
on_duplicate="refuse"))
def _add_tab(ctx, args):
book = _book(ctx, args, write=True)
#: ⛔ A DUPLICATE TAB NAME IS REFUSED, because every other tool addresses a tab by `tab`,
#: which `sheets.find_tab` resolves BY NAME to the FIRST match. Two tabs sharing a name make
#: every later write land on one of them and the other unreachable, with nothing reported.
#: Measured at SDLC 61's C7 build: a retried `sheet_add_tab` produced a second
#: `Summary (All)` and the workbook's cells split silently across the pair.
wanted = str(args["name"]).strip()
if any(str(sheet.get("name") or "").strip().casefold() == wanted.casefold()
for sheet in (book.get("sheets") or ())):
raise sheets.SheetRefusal(
"tab_name_taken",
"Tab " + wanted + " is already in this workbook. Choose another name.")
tab = {"id": write_execution.new_id()[:12], "name": args["name"], "cells": {}}
book["sheets"].append(tab)
return _put(ctx, args, book, tab["id"])
def _delete_tab(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
if len(book["sheets"]) <= 1:
raise sheets.SheetRefusal(
"tab_last", "A workbook keeps at least one sheet, so this one cannot be deleted.")
book["sheets"] = [row for row in book["sheets"] if row["id"] != tab["id"]]
return _put(ctx, args, book)
def _save_template(ctx, args):
book = ctx.project_book(_book(ctx, args))
record = sheet_templates.save_sheet_template(
ctx.session.runtime, book, args["key"], name=args["name"],
description=args["description"], created_by=ctx.session.uname, actor_name=ctx.actor_name)
return {"template": record}
def _read_cells(ctx, args):
book = ctx.project_book(_book(ctx, args))
tab = sheets.find_tab(book, args["tab"])
if "addresses" in args:
wanted = {addr.strip().upper() for addr in args["addresses"]}
tab = {**tab, "cells": {addr: cell for addr, cell in tab["cells"].items() if addr in wanted}}
return {"id": book["id"], "rev": book["rev"], "tab": tab}
def _patch(ctx, args, cells, *, resolved=None):
out = sheets.patch_cells(ctx.session.runtime, args["workbook_id"], args["tab"], cells,
expect_rev=args.get("rev"), actor=ctx.session.uname,
actor_name=ctx.actor_name)
if resolved is not None:
for addr in out["accepted"]:
cell = cells[addr]
ctx.cache_binding(args["workbook_id"], out["tab"], addr, cell["binding"], resolved)
# The UI computes after its patch too. Project before computing so a shared workbook
# never returns its owner's cached database numbers through an editor's write response.
book = ctx.project_book(_book(ctx, args))
tab = sheets.find_tab(book, args["tab"])
out["computed"] = {addr: cell for addr, cell in tab["cells"].items()
if cell.get("kind") in ("formula", "bound") or "spillParent" in cell}
return out
def _cell_figure_hints(ctx, args, book):
"""Suggest visible source fields without inferring where a typed number came from."""
numbers = [addr.strip().upper() for addr, cell in args["cells"].items()
if isinstance(cell, dict) and cell.get("kind") == "literal"
and type(cell.get("value")) in (int, float)]
if not numbers:
return []
target = sheets.find_tab(book, args["tab"])
databases = []
for tab in [target, *(tab for tab in book["sheets"] if tab["id"] != target["id"])]:
bindings = [cell.get("binding") for cell in tab["cells"].values()
if isinstance(cell, dict) and cell.get("kind") == "bound"]
for binding in [*bindings, tab.get("pivot")]:
database = binding.get("database") if isinstance(binding, dict) else None
if database and database not in databases:
databases.append(database)
if not databases:
return []
schemas = {}
def describe(database):
if database not in schemas:
try:
schemas[database] = ctx.describe_database(database)
except Exception:
# Optional advice omits unavailable metadata and never grants access or blocks a write.
schemas[database] = {}
return schemas[database]
numeric_types = {"int", "integer", "float", "number", "decimal", "currency", "percent", "rating"}
candidate = None
for database in databases:
schema = describe(database)
field = next((field for field in schema.get("fields", [])
if field.get("type") in numeric_types and field.get("label")), None)
if schema.get("label") and field:
candidate = (schema["label"], field["label"])
break
if candidate is None:
return []
sources = {addr.strip().upper(): refs for addr, refs in (args.get("figure_sources") or {}).items()}
hints = []
for addr in numbers:
declared = {}
for ref in sources.get(addr, []):
schema = describe(ref["database"])
field = next((field for field in schema.get("fields", [])
if field.get("key") == ref["field"] and field.get("label")), None)
if schema.get("label") and field:
declared[ref["database"]] = f'"{field["label"]}" in "{schema["label"]}"'
if len(declared) >= 2 and set(declared).intersection(databases):
hint = ("The declared figure uses " + " and ".join(declared.values()) + ". "
"A cell database cannot join two databases yet. "
"Use separate cell databases and a calculation object, or confirm a typed assumption.")
else:
database_label, field_label = candidate
hint = (f'This workbook reads "{database_label}". Use a cell database with "{field_label}" '
f'in "{database_label}" when it supplies this figure. You can still confirm a typed assumption.')
if hint not in hints:
hints.append(hint)
return hints
def _write_cells(ctx, args):
book = _book(ctx, args, write=True)
if "figure_sources" in args:
validate_arguments(args["figure_sources"], _FIGURE_SOURCES)
hints = _cell_figure_hints(ctx, args, book)
out = _patch(ctx, args, args["cells"])
if hints:
out["warnings"] = hints
return out
def _set_binding(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
resolved = ctx.resolve_binding(args["binding"], book, tab["id"])
addr = args["addr"].strip().upper()
before = tab["cells"].get(addr) or {}
cell = {key: copy.deepcopy(before[key]) for key in ("style", "validation", "link", "note")
if key in before}
cell.update(kind="bound", binding=copy.deepcopy(args["binding"]), state="fresh",
value=resolved["value"],
display="" if resolved["value"] is None else str(resolved["value"]))
out = _patch(ctx, args, {addr: cell}, resolved=resolved)
out["limits"] = resolved.get("limits") or []
return out
def _cell_property(ctx, args, property_name, values):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
cells = {}
for addr, value in values.items():
cell = copy.deepcopy(tab["cells"].get(addr.strip().upper()) or {"kind": "empty"})
cell[property_name] = value
cells[addr] = cell
return _patch(ctx, args, cells)
def _dimensions(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
tab.update(copy.deepcopy(args["dimensions"]))
return _put(ctx, args, book, tab["id"])
def _freeze(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
tab["freeze"] = args["freeze"]
return _put(ctx, args, book, tab["id"])
def _rule(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
tab["rules"] = [*(tab.get("rules") or []), args["rule"]]
return _put(ctx, args, book, tab["id"])
def _chart(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
chart = copy.deepcopy(args["chart"])
chart.setdefault("id", write_execution.new_id()[:12])
tab["charts"] = [row for row in tab.get("charts", []) if row["id"] != chart["id"]] + [chart]
return {**_put(ctx, args, book, tab["id"]), "chart_id": chart["id"]}
def _structure(ctx, args):
book = _book(ctx, args, write=True)
tab = sheets.find_tab(book, args["tab"])
shifted = sheet_structure.apply_structure(book, tab["id"], args["op"])
return _put(ctx, args, shifted, tab["id"])
def _tool(description, schema, handler, *, write=False, grants=("ai_apps", "sheets")):
return {"description": description, "inputSchema": schema, "write": write,
"grants": grants, "handler": handler}
def _callback(ctx, name, args):
callback = getattr(ctx, name, None)
if not callable(callback):
raise sheets.SheetRefusal(
"tool_capability_unsupported",
"This action is not available yet.")
return callback(args)
_DATABASE_ACTIONS = (
"list", "describe", "query", "record_create", "record_update", "record_delete",
"field_create", "field_update", "field_delete", "rename",
)
_VIEW_ACTIONS = ("upsert", "delete", "share_preview")
_SHEET_OBJECT_ACTIONS = {
"workbook_object": ("list", "get", "create", "named_ranges", "export"),
"worksheet_object": (
"list", "get", "add", "update", "delete", "geometry", "hidden_bands",
"freeze", "gridlines", "named_ranges",
),
"range_object": (
"read", "write_values", "write_formulas", "write_styles", "number_format",
"fill_down", "clear",
),
"calculation_object": ("calculate", "refresh"),
}
def _object_tool(name, actions):
target = {
"workbook_id": _STRING,
"worksheet": _STRING,
"range": _RANGE,
"revision": {"type": "integer"},
"arguments": {"type": "object"},
}
return _tool(
"Read or change a Sheet "
+ name.removesuffix("_object") + ".",
_object({"action": {"enum": list(actions)}, **target}, ("action",),
additionalProperties=False),
lambda ctx, args, object_name=name: _callback(
ctx, "sheet_object", {"object": object_name.removesuffix("_object"), **args}),
# The action classifier below distinguishes reads. Declaring the surface write-capable
# keeps the API's literal allow-list fail closed when a new action is added.
write=True,
)
TOOLS = {
"sheet_create_workbook": _tool("Create a private workbook with one initial tab.",
_object({"name": _STRING}, ("name",), additionalProperties=False), _create, write=True),
"sheet_add_tab": _tool("Add a blank tab to a workbook.",
_schema({"name": _STRING}, ("name",), tab=False), _add_tab, write=True),
"sheet_delete_tab": _tool(
"Preview deleting a tab by id or name; requires typed confirmation. The last tab cannot be deleted.",
_schema({}), _delete_tab, write=True),
"sheet_read_cells": _tool("Read a tab's styles, sizes and figures that you have permission to see.",
_schema({"addresses": {"type": "array", "items": _ADDRESS}}), _read_cells),
"sheet_write_cells": _tool("Write cell documents with values or formulas; null deletes a cell. " + CELL_FIGURE_RULE,
_schema({"cells": {"type": "object", "additionalProperties": {"anyOf": [_CELL, {"type": "null"}]}},
"figure_sources": _FIGURE_SOURCES},
("cells",)), _write_cells, write=True),
"sheet_set_binding": _tool("Set and resolve a Cell database binding, including filter valueRef cells.",
_schema({"addr": _ADDRESS, "binding": _BINDING}, ("addr", "binding")), _set_binding, write=True),
"sheet_set_styles": _tool("Replace styles by address, preserving cell content; null clears a style.",
_schema({"styles": {"type": "object", "additionalProperties": {"anyOf": [_STYLE, {"type": "null"}]}}},
("styles",)), lambda ctx, args: _cell_property(ctx, args, "style", args["styles"]), write=True),
"sheet_set_dimensions": _tool("Replace supplied geometry fields; widths use letters and row indices start at one.",
_schema({"dimensions": _object({
"cols": {"type": "integer"}, "rows": {"type": "integer"},
"colWidths": {"type": "object", "additionalProperties": {"type": "number"}},
"rowHeight": {"type": "number"},
"rowHeights": {"type": "object", "additionalProperties": {"type": "number"}},
"hiddenRows": {"type": "array", "items": {"type": "integer"}},
"hiddenCols": {"type": "array", "items": {"type": "integer"}},
}, additionalProperties=False)}, ("dimensions",)), _dimensions, write=True),
"sheet_set_validation": _tool("Replace dropdown lists by address, preserving content; null clears validation.",
_schema({"validations": {"type": "object", "additionalProperties": {
"anyOf": [_VALIDATION, {"type": "null"}]}}}, ("validations",)),
lambda ctx, args: _cell_property(ctx, args, "validation", args["validations"]), write=True),
"sheet_set_freeze": _tool("Set frozen row and column counts, using zero to unfreeze.",
_schema({"freeze": _object({"rows": {"type": "integer"}, "cols": {"type": "integer"}})},
("freeze",)), _freeze, write=True),
"sheet_add_rule": _tool("Add a conditional formatting rule to a Sheet.",
_schema({"rule": _RULE}, ("rule",)), _rule, write=True),
"sheet_set_chart": _tool("Add a chart or replace a chart with the same id using the app's chart document.",
_schema({"chart": _CHART}, ("chart",)), _chart, write=True),
"sheet_structure": _tool("Insert or delete rows or columns and reanchor references; positive delta inserts.",
_schema({"op": _object({"axis": {"enum": ["row", "col"]},
"at": {"type": "integer", "minimum": 1}, "delta": {"type": "integer"}},
("axis", "at", "delta"))}, ("op",)), _structure, write=True),
"sheet_save_template": _tool("Save a readable workbook as a tenant Sheet template with its Cell databases.",
_object({key: _STRING for key in ("workbook_id", "key", "name", "description")},
("workbook_id", "key", "name", "description"), additionalProperties=False),
_save_template, write=True),
"list_databases": _tool("List the databases you can access or see in Loopable.",
_object({"limit": {"type": "integer", "minimum": 1,
"description": "Optional client hint. The complete permitted database list is returned."}},
additionalProperties=False), lambda ctx, args: ctx.list_databases(), grants=("ai_apps",)),
"describe_database": _tool("Read the fields you have permission to use in a database.",
_object({"database": _STRING}, ("database",), additionalProperties=False),
lambda ctx, args: ctx.describe_database(args["database"]), grants=("ai_apps",)),
"query_database": _tool(
"Query currently permitted records with bounded filters, stable sorts, cursor pagination and aggregates.",
_object({
"database": _STRING,
"fields": {"type": "array", "items": _STRING, "maxItems": 200},
"filters": _CLIENT_QUERY_FILTER,
"sorts": {"type": "array", "maxItems": 8, "items": _object({
"field": _STRING, "direction": {"enum": ["asc", "desc"]},
}, ("field", "direction"), additionalProperties=False)},
"limit": {"type": "integer", "minimum": 1, "maximum": 500},
"cursor": _STRING,
"aggregates": {"type": "array", "maxItems": 16, "items": _object({
"fn": {"enum": ["count", "count_distinct", "sum", "avg", "min", "max"]},
"field": _STRING,
}, ("fn",), additionalProperties=False)},
# S68-T55 (COMBINE-AMEND): the MCP door asks for the same SKU x month groups the REST
# door answers (`routes_external._normalise_query_groups`): 1 to 4 field keys, or a
# field with unit month.
"groupBy": {"type": "array", "minItems": 1, "maxItems": 4, "items": {"oneOf": [
_STRING,
_object({"field": _STRING, "unit": {"enum": ["month"]}}, ("field",),
additionalProperties=False),
]}},
"group_by": {"type": "array", "minItems": 1, "maxItems": 4,
"items": _STRING, "description": "Client alias for groupBy. Send only one spelling."},
}, ("database",), additionalProperties=False),
lambda ctx, args: ctx.query_database(args["database"], {
key: value for key, value in args.items() if key != "database"
}), grants=("ai_apps",)),
"view_upsert": _tool(
"Create or update a saved View using the grid's filters, sorts, groupBy, visible fields and display config.",
_object({"database": _STRING, "view": _object({
"id": {"type": "string", "minLength": 1, "maxLength": 120},
"name": {"type": "string", "minLength": 1, "maxLength": 120},
"config": _VIEW_CONFIG, "note": _STRING}, ("id", "name", "config"),
additionalProperties=False)},
("database", "view"), additionalProperties=False),
lambda ctx, args: ctx.view_event("view_upsert", args), write=True, grants=("ai_apps",)),
"view_share_preview": _tool(
"Check who could see a personal draft View and its fields before sharing it.",
_object({
"database": _STRING,
"view_id": _STRING,
"entries": {"type": "array", "maxItems": 200, "items": _object({
"user": _STRING, "role": {"enum": ["view", "edit"]},
}, ("user", "role"), additionalProperties=False)},
}, ("database", "view_id", "entries"), additionalProperties=False),
lambda ctx, args: ctx.view_share_preview(args), grants=("ai_apps",)),
"view_delete": _tool("Delete a saved View when you have permission to do so.",
_object({"database": _STRING, "view_id": _STRING}, ("database", "view_id"),
additionalProperties=False),
lambda ctx, args: ctx.view_event("view_delete", args), write=True, grants=("ai_apps",)),
"app_upsert": _tool(
"Create an App with name, type, compatibleDatabases and config, or update it by app_id. Identity fields are immutable.",
_object(_APPLICATION, additionalProperties=False,
anyOf=[{"required": ["app_id"]}, {"required": ["name", "type", "config"]},
{"required": ["name", "templateKind", "sourceDatabase", "fieldMap", "navPlacement"]}]),
lambda ctx, args: ctx.app_upsert(args), write=True, grants=("ai_apps",)),
"app_delete": _tool("Delete an App. confirmName must match its current name exactly.",
_object({"app_id": _STRING, "confirmName": _STRING}, ("app_id", "confirmName"),
additionalProperties=False),
lambda ctx, args: ctx.app_delete(args), write=True, grants=("ai_apps",)),
"database_object": _tool(
"Read a database or preview changes to its records, fields, name or icon, then confirm them. Name and icon changes require an Administrator.",
_object({
"action": {"enum": list(_DATABASE_ACTIONS)},
"database": _STRING,
"name": _STRING,
"icon": {"oneOf": [{"type": "null"}, _object({
"shape": _STRING, "tone": _STRING,
}, ("shape", "tone"), additionalProperties=False)]},
"record_id": {"oneOf": [_STRING, {"type": "integer"}]},
"values": {"type": "object"},
"field": {"type": "object"},
"field_key": _STRING,
"query": {"type": "object"},
}, ("action",), additionalProperties=False),
lambda ctx, args: _callback(ctx, "database_object", args), write=True,
grants=("ai_apps",)),
"view_object": _tool(
"Read a personal View or preview changes to it, then confirm them.",
_object({
"action": {"enum": list(_VIEW_ACTIONS)}, "database": _STRING,
"view": {"type": "object"}, "view_id": _STRING,
"entries": {"type": "array", "items": {"type": "object"}, "maxItems": 200},
}, ("action", "database"), additionalProperties=False),
lambda ctx, args: (
ctx.view_event("view_upsert", {"database": args["database"], "view": args["view"]})
if args["action"] == "upsert" else
ctx.view_event("view_delete", {"database": args["database"],
"view_id": args["view_id"]})
if args["action"] == "delete" else
ctx.view_share_preview({"database": args["database"],
"view_id": args["view_id"],
"entries": args.get("entries") or []})
), write=True, grants=("ai_apps",)),
**{name: _object_tool(name, actions)
for name, actions in _SHEET_OBJECT_ACTIONS.items()},
"validated_batch": _tool(
"Validate a bounded object-operation batch; writes preview and confirm as one unit.",
_object({"operations": {"type": "array", "minItems": 1, "maxItems": 50,
"items": _object({"name": _STRING,
"arguments": {"type": "object"}},
("name", "arguments"),
additionalProperties=False)}},
("operations",), additionalProperties=False),
lambda ctx, args: _callback(ctx, "validated_batch", args), write=True,
grants=("ai_apps",)),
"confirm_change": _tool(
"Confirm a current preview and keep its operation_id. Repeating it returns the first result. "
"Read data.operation_status with that id if a response is lost. Deletions and field changes need the preview's exact phrase.",
_object({"confirmation_token": _STRING, "confirmation_phrase": _STRING},
("confirmation_token",), additionalProperties=False),
lambda ctx, args: _callback(ctx, "confirm_change", args), write=True, grants=("ai_apps",)),
}
_OBJECT_READ_ACTIONS = {
"database_object": frozenset({"list", "describe", "query"}),
"view_object": frozenset({"share_preview"}),
"workbook_object": frozenset({"list", "get", "export"}),
"worksheet_object": frozenset({"list", "get"}),
"range_object": frozenset({"read"}),
"calculation_object": frozenset(),
}
def build_kind(name):
"""Derive a flat tool's build kind without accepting a caller's kind."""
if name.startswith("view_"):
return "view"
if name.startswith("app_"):
return "app"
if name.startswith("sheet_") or name in _SHEET_OBJECT_ACTIONS:
return "workbook"
return {"database_object": "database", "validated_batch": "batch"}.get(name, name)
for _name, _entry in TOOLS.items():
if _entry["write"] and _name != "confirm_change":
_entry["buildKind"] = build_kind(_name)
_entry["inputSchema"]["properties"]["about"] = copy.deepcopy(ABOUT_SCHEMA)
def is_write(name, arguments) -> bool:
"""Classify dynamic object tools without trusting an unvalidated action as a read."""
tool = TOOLS.get(name) if isinstance(name, str) else None
if tool is None or name == "confirm_change":
return False
if name == "validated_batch":
operations = arguments.get("operations") if isinstance(arguments, dict) else None
if not isinstance(operations, list):
return True
return any(is_write(item.get("name"), item.get("arguments"))
for item in operations if isinstance(item, dict))
if name in _OBJECT_READ_ACTIONS:
action = arguments.get("action") if isinstance(arguments, dict) else None
return action not in _OBJECT_READ_ACTIONS[name]
return bool(tool.get("write"))
def validate_query_filter_operators(filters):
"""Refuse unknown source or target operators before permission or data access."""
stack, seen = [filters], set()
while stack:
node = stack.pop()
if not isinstance(node, (dict, list)) or id(node) in seen:
continue
seen.add(id(node))
if isinstance(node, list):
stack.extend(node)
continue
if "op" in node and (not isinstance(node["op"], str) or node["op"] not in FILTER_OPS):
raise sheets.SheetRefusal(
"tool_arguments_invalid", "Filter op must be one of: " + ", ".join(sorted(FILTER_OPS)) + ".")
stack.extend(node[key] for key in ("nodes", "children", "where") if key in node)
def validate_arguments(arguments, schema, *, named=False):
"""Validate grouped arguments against the selected action's JSON schema."""
if isinstance(arguments, dict) and "filters" in schema.get("properties", {}):
validate_query_filter_operators(arguments.get("filters"))
def equal(value, expected):
if isinstance(value, bool) != isinstance(expected, bool):
return False
if isinstance(value, dict) and isinstance(expected, dict):
return value.keys() == expected.keys() and all(equal(value[key], expected[key]) for key in value)
if isinstance(value, list) and isinstance(expected, list):
return len(value) == len(expected) and all(equal(a, b) for a, b in zip(value, expected))
return value == expected
def matches(value, rule, depth=0):
if depth > 40:
return False
if isinstance(rule, bool):
return rule
kinds = {
"object": isinstance(value, dict), "array": isinstance(value, list),
"string": isinstance(value, str), "boolean": type(value) is bool,
"integer": type(value) is int,
"number": type(value) is int or type(value) is float and math.isfinite(value),
"null": value is None,
}
kind = rule.get("type")
if kind is not None and not any(kinds.get(item, False) for item in (
kind if isinstance(kind, list) else [kind])):
return False
if "enum" in rule and not any(equal(value, choice) for choice in rule["enum"]):
return False
if "const" in rule and not equal(value, rule["const"]):
return False
for key in ("anyOf", "oneOf", "allOf"):
if key in rule:
count = sum(matches(value, child, depth + 1) for child in rule[key])
if (key == "anyOf" and not count or key == "oneOf" and count != 1
or key == "allOf" and count != len(rule[key])):
return False
if isinstance(value, dict):
if set(rule.get("required", ())) - value.keys():
return False
properties = rule.get("properties", {})
for key, child in value.items():
if not matches(child, properties.get(key, rule.get("additionalProperties", True)), depth + 1):
return False
if isinstance(value, list):
if not rule.get("minItems", 0) <= len(value) <= rule.get("maxItems", float("inf")):
return False
if any(not matches(child, rule.get("items", True), depth + 1) for child in value):
return False
if isinstance(value, str):
if not rule.get("minLength", 0) <= len(value) <= rule.get("maxLength", float("inf")):
return False
if "pattern" in rule and not re.search(rule["pattern"], value):
return False
if type(value) in (int, float):
if type(value) is float and not math.isfinite(value):
return False
if not rule.get("minimum", -float("inf")) <= value <= rule.get("maximum", float("inf")):
return False
return True
def problems(value, rule, path="arguments"):
if matches(value, rule):
return []
if not isinstance(rule, dict):
return [path]
for branch in ("anyOf", "oneOf"):
if branch in rule:
candidates = [problems(value, child, path) for child in rule[branch]]
return min(candidates, key=lambda found: (
-max((item.count(".") + item.count("[") for item in found), default=0), len(found)))
if isinstance(value, dict) and rule.get("type") == "object":
properties = rule.get("properties", {})
found = [path + "." + key for key in rule.get("required", ()) if key not in value]
for key, child in value.items():
found.extend(problems(child, properties.get(key, rule.get("additionalProperties", True)),
path + "." + str(key)))
return found or [path]
if isinstance(value, list) and rule.get("type") == "array":
found = [item for index, child in enumerate(value)
for item in problems(child, rule.get("items", True), f"{path}[{index}]")]
return found or [path]
return [path]
if not isinstance(arguments, dict) or not matches(arguments, schema):
detail = (" Invalid arguments: " + ", ".join(dict.fromkeys(problems(arguments, schema))) + "."
if named else "")
raise sheets.SheetRefusal("tool_arguments_invalid", "Tool arguments must match the published input schema." + detail)
encoded = json.dumps(arguments, ensure_ascii=False, allow_nan=False)
if any(prefix in encoded for prefix in ("lpb1.", "lpo1.", "lpr1.", "lpc1.")):
raise sheets.SheetRefusal("credential_in_arguments", "Tool arguments must not contain credential values.")
def table_read_arguments(name, arguments, schema=None):
"""Admit supported client spellings before the existing scoped Table read."""
schema = schema if schema is not None else TOOLS[name]["inputSchema"]
try:
try:
validate_arguments(arguments, schema, named=True)
except sheets.SheetRefusal as exc:
if name != "query_database" or exc.code != "tool_arguments_invalid":
raise
aggregate = schema["properties"]["aggregates"]
item = aggregate["items"]
# Preserve the semantic code only when aggregate member values cause the schema failure.
transport = {**schema, "properties": {**schema["properties"], "aggregates": {
**aggregate, "items": {**item, "properties": {key: {} for key in item["properties"]}}}}}
validate_arguments(arguments, transport, named=True)
accepted = ", ".join(item["properties"]["fn"]["enum"])
raise sheets.SheetRefusal("query_aggregates_invalid", exc.message + " Use aggregates like "
'[{"fn": "count"}, {"fn": "sum", "field": "<readable field key>"}]. '
"fn must be one of: " + accepted + ". When supplied, field must be a readable field key string.") from exc
args = copy.deepcopy(arguments)
if name != "query_database":
return args
if "group_by" in args:
if "groupBy" in args:
raise sheets.SheetRefusal("tool_arguments_invalid", "Send group_by or groupBy, not both.")
args["groupBy"] = args.pop("group_by")
filters = args.get("filters")
def leaf(node):
validate_arguments({"filters": node}, _object({"filters": _CLIENT_QUERY_LEAF}), named=True)
if "field" not in node:
return node
return {"colId": node["field"], "op": "eq" if "operator" in node else node["op"],
**({"value": node["value"]} if "value" in node else {})}
if isinstance(filters, list):
args["filters"] = [leaf(node) for node in filters]
elif isinstance(filters, dict):
if set(filters) in ({"and"}, {"or"}):
conj = next(iter(filters))
args["filters"] = {"conj": conj, "nodes": [leaf(node) for node in filters[conj]]}
elif set(filters) & {"colId", "field", "op", "operator"}:
args["filters"] = {"conj": "and", "nodes": [leaf(filters)]}
elif not set(filters) & {"conj", "nodes", "link", "where", "children", "and", "or"}:
if not filters or len(filters) > 50:
raise sheets.SheetRefusal("tool_arguments_invalid", "filters must contain 1 to 50 field equality values.")
args["filters"] = {"conj": "and", "nodes": [
{"colId": field, "op": "eq", "value": value} for field, value in filters.items()]}
validate_arguments({"filters": args["filters"]}, _object({"filters": _QUERY_FILTER}), named=True)
return args
except sheets.SheetRefusal as exc:
if exc.code != "tool_arguments_invalid":
raise
example = {"database": "<database>", "filters": {"conj": "and", "nodes": [
{"colId": "<field>", "op": "eq", "value": "<value>"}]}} if name == "query_database" else {}
shape = {"action": name, "arguments": example}
raise sheets.SheetRefusal(exc.code, exc.message + " Call table with " + json.dumps(shape) + ".") from exc
def dispatch(ctx, name, arguments):
"""Dispatch one declared tool. The API translates core and grant refusals to MCP content."""
tool = TOOLS.get(name) if isinstance(name, str) else None
if tool is None:
raise sheets.SheetRefusal("tool_not_found", "The requested tool is not available.")
if name == "query_database":
validate_query_filter_operators(arguments.get("filters") if isinstance(arguments, dict) else None)
for grant in tool["grants"]:
if grant == perm_scope.AI_APPS:
reason = perm_scope.ai_apps_refusal(ctx.session.user, ctx.session.runtime)
if reason:
raise sheets.SheetRefusal("ai_apps_off", reason)
else:
ctx.session.require(grant)
schema = tool["inputSchema"]
if name in {"query_database", "list_databases"}:
arguments = table_read_arguments(name, arguments, schema)
if not isinstance(arguments, dict):
raise sheets.SheetRefusal("tool_arguments_invalid", "Tool arguments must be an object.")
missing = set(schema["required"]) - arguments.keys()
unknown = arguments.keys() - schema["properties"].keys()
if missing or (unknown and schema.get("additionalProperties") is False):
raise sheets.SheetRefusal("tool_arguments_invalid", "Tool arguments must match the published input schema.")
# Validate only the transport shape here. Document semantics belong to the app writers.
for key, value in arguments.items():
property_schema = schema["properties"].get(key, {})
kind = property_schema.get("type")
types = {"object": dict, "array": list, "string": str, "integer": int}
if kind in types and (not isinstance(value, types[kind]) or (kind == "integer" and isinstance(value, bool))):
raise sheets.SheetRefusal("tool_arguments_invalid", f"Tool argument {key} must be an {kind}.")
if "enum" in property_schema and value not in property_schema["enum"]:
raise sheets.SheetRefusal(
"tool_arguments_invalid", f"Tool argument {key} is not a published operation.")
# A dimension patch must never become an arbitrary tab-document replacement.
if name == "sheet_set_dimensions":
allowed = schema["properties"]["dimensions"]["properties"]
if arguments["dimensions"].keys() - allowed.keys():
raise sheets.SheetRefusal("tool_arguments_invalid", "Dimensions may contain only the published geometry fields.")
encoded_arguments = json.dumps(arguments, ensure_ascii=False, allow_nan=False)
if any(prefix in encoded_arguments for prefix in ("lpb1.", "lpo1.", "lpr1.", "lpc1.")):
raise sheets.SheetRefusal("credential_in_arguments", "Tool arguments must not contain credential values.")
return tool["handler"](ctx, arguments)
"""External build tools over the app's Sheet, saved View and Application writers.
The API supplies its existing permission, read-projection and binding-resolution functions as
request-scoped callbacks. Core never imports API modules or chooses another tenant runtime.
Adding a tool means adding a registry entry; writes also require the router's literal allow-list.
"""
import copy
import json
import math
import re
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, Optional
from core import perm_scope, sheets, sheet_structure, sheet_templates, write_execution
# Keep supported versions in release order, with the newest last.
MCP_SUPPORTED_PROTOCOL_VERSIONS = ("2025-06-18",)
def negotiate_mcp_protocol(requested=None) -> str:
"""Return the requested supported version or the newest supported version."""
if requested is not None and not isinstance(requested, str):
raise ValueError("The protocol version must be a string.")
if requested in MCP_SUPPORTED_PROTOCOL_VERSIONS:
return requested
return MCP_SUPPORTED_PROTOCOL_VERSIONS[-1]
CELL_FIGURE_RULE = (
"A figure a database can supply goes in a cell database or a calculation object, "
"and a typed value is for a title, a label or an assumption."
)
BUILD_TAGS = tuple(json.loads(
(Path(__file__).resolve().parents[1] / "build_tags.json").read_text(encoding="utf-8")))
_BUILD_TEXT = r"^(?=.*\S)[^\u0000-\u001f\u007f\u0085\u2013\u2014\u2028\u2029]+(?![\s\S])"
ABOUT_SCHEMA = {
"type": "object", "additionalProperties": False,
"properties": {
"title": {"type": "string", "minLength": 1, "maxLength": 240, "pattern": _BUILD_TEXT},
"description": {"type": "string", "minLength": 20, "maxLength": 240, "pattern": _BUILD_TEXT},
"tags": {"type": "array", "minItems": 1, "uniqueItems": True,
"items": {"type": "string", "enum": list(BUILD_TAGS)}},
}, "required": ["title", "description", "tags"],
}
class ToolContext:
session: object
actor_name: str
require_reader: Callable
require_editor: Callable
project_book: Callable
resolve_binding: Callable
cache_binding: Callable
list_databases: Callable
describe_database: Callable
query_database: Callable
view_event: Callable
view_share_preview: Callable
app_upsert: Callable
app_delete: Callable
database_object: Optional[Callable] = None
sheet_object: Optional[Callable] = None
validated_batch: Optional[Callable] = None
confirm_change: Optional[Callable] = None
def _object(properties=None, required=(), **extra):
return {"type": "object", "properties": properties or {}, "required": list(required), **extra}
_STRING = {"type": "string"}
_ADDRESS = {"type": "string", "description": "An A1 cell address on the named tab."}
_FORMAT = _object({"kind": _STRING, "code": _STRING, "decimals": {"type": "integer"},
"currency": _STRING, "thousands": {"type": "boolean"}}, ("kind",))
# S67-T14 / contract C2: a border side is the legacy `true` (read as a thin black line) or
# `{style, color}` with one of Excel's seven line styles and a six digit hex colour; `false` or an
# absent side is no side. `sheets.py::_clean_border_side` refuses anything else by code, and this
# publishes the same shape so an AI client can draw a styled border at all.
_BORDER_SIDE = {"oneOf": [{"type": "boolean"}, _object({
"style": {"enum": list(sheets.CELL_BORDER_STYLES)},
"color": {"type": "string", "pattern": "^#[0-9A-Fa-f]{6}$"}}, ("style", "color"))]}
_STYLE = _object({
**{key: {"type": "boolean"} for key in ("bold", "italic", "underline", "strike", "wrap")},
**{key: _STRING for key in ("fill", "color", "font", "align", "valign")},
"size": {"type": ["number", "string"]}, "indent": {"type": "integer"},
"textRotation": {"type": "number"}, "format": _FORMAT,
"border": _object({side: _BORDER_SIDE for side in ("top", "right", "bottom", "left")}),
})
_VALIDATION = _object({"list": {"type": "array", "items": _STRING}}, ("list",))
# Mirror the grid vocabulary without importing the API. verify_api checks parity.
FILTER_OPS = frozenset({
"contains", "doesNotContain", "eq", "neq", "isEmpty", "isNotEmpty",
"gt", "gte", "lt", "lte", "between", "within",
"topN", "bottomN", "inTopPct", "inBottomPct", "aboveAvg", "belowAvg",
"inQuartile", "inDecile", "isAnyOf", "isNoneOf", "hasAnyOf", "hasAllOf", "hasNoneOf",