Files
moloapp/src/vendors/cohere/tools/check_spec.py
T
retoorandClaude Sonnet 5.5 f32947427b feat(clients): cohere: whole API, CohereChatModel, spec checker, demo and tests
Package src/vendors/cohere (molo::cohere): Chat v2 with streaming, tools,
thinking and citations; embed, rerank, classify, tokenize, detokenize,
parse, transcription; datasets, embed jobs, batches, connectors,
fine-tuning, models, check-api-key; legacy v1 chat/generate/summarize;
CohereChatModel : ChatModel. All 42 operations of cohere-openapi.yaml are
in one call table, verified by tools/check_spec.py. Demo routes under
/ai/cohere, 51 unit tests and 2 route tests; live tests are opt-in.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 10:49:17 +01:00

425 lines
16 KiB
Python

#!/usr/bin/env python3
"""Check src/vendors/cohere/calls.cpp against Cohere's published OpenAPI document.
Cohere publishes cohere-openapi.yaml in the cohere-ai/cohere-developer-experience
repository (the file their Fern SDK generation reads). This checker parses that
file with a small block-YAML reader (Python 3 standard library only, no PyYAML)
and fails (exit 1) when:
row a declared call's HTTP method + path or operationId is not in the spec;
field a request body field or query parameter we send is not in the spec's
request body / parameters of that operation;
required a field or parameter the spec marks required is not declared in the row;
schema a field we read (SCHEMAS table) is not a property of that schema;
response a declared response schema is neither a component nor an operationId;
coverage a spec operation is neither in the table nor in EXCLUDED_OPERATIONS.
python3 -I src/vendors/cohere/tools/check_spec.py [--spec path-to-openapi.yaml] [alternative calls.cpp]
Network required unless --spec is given. No credentials.
"""
import os
import re
import sys
import urllib.request
HERE = os.path.dirname(os.path.abspath(__file__))
CALLS = os.path.join(HERE, "..", "calls.cpp")
SPEC_URL = ("https://raw.githubusercontent.com/cohere-ai/cohere-developer-experience/main/"
"cohere-openapi.yaml")
# Operations that exist in the spec but are deliberately not wrapped (reason each).
EXCLUDED_OPERATIONS = {}
STR = re.compile(r'"([^"]*)"')
METHODS = ("get", "post", "put", "patch", "delete")
# ---------------------------------------------------------------- YAML reader
class Yaml:
"""Block-style YAML subset: mappings, sequences, plain / quoted scalars (single
line or folded continuation), block scalars (| >), empty flow [] and {}."""
def __init__(self, text):
self.lines = []
for raw in text.replace("\t", " ").split("\n"):
self.lines.append(raw.rstrip("\r"))
self.i = 0
@staticmethod
def indent_of(line):
return len(line) - len(line.lstrip(" "))
def skip_blank(self):
while self.i < len(self.lines):
s = self.lines[self.i].strip()
if s == "" or s.startswith("#") or s == "---":
self.i += 1
else:
return
def parse(self):
self.skip_blank()
return self.node(self.indent_of(self.lines[self.i]))
def node(self, indent):
self.skip_blank()
if self.i >= len(self.lines):
return None
line = self.lines[self.i]
if self.indent_of(line) < indent:
return None
body = line.strip()
if body.startswith("- ") or body == "-":
return self.seq(self.indent_of(line))
if self.key_split(body) is not None:
return self.mapping(self.indent_of(line))
self.i += 1
return self.scalar(body, self.indent_of(line))
@staticmethod
def key_split(body):
"""(key, rest) for `key: rest`, else None. Handles quoted keys."""
if body[:1] in ("'", '"'):
q = body[0]
j = 1
while j < len(body):
if body[j] == q and (q == "'" or body[j - 1] != "\\"):
break
j += 1
if j + 1 < len(body) and body[j + 1] == ":" and (j + 2 == len(body) or body[j + 2] == " "):
return body[1:j], body[j + 2:].strip()
return None
if body[:1] in ("[", "{", "|", ">", "#", "*", "&", "!"):
return None
m = re.match(r"^([^:#]+?|[^:#]*?[^:\s#][^#]*?):(?:\s+(.*))?$", body)
if not m:
return None
key = m.group(1)
if " #" in key:
return None
return key.strip(), (m.group(2) or "").strip()
def mapping(self, indent):
out = {}
while True:
self.skip_blank()
if self.i >= len(self.lines):
break
line = self.lines[self.i]
if self.indent_of(line) != indent:
break
body = line.strip()
kv = self.key_split(body)
if kv is None or body.startswith("- "):
break
key, rest = kv
self.i += 1
out[key] = self.value(rest, indent)
return out
def seq(self, indent):
out = []
while True:
self.skip_blank()
if self.i >= len(self.lines):
break
line = self.lines[self.i]
if self.indent_of(line) != indent:
break
body = line.strip()
if not (body.startswith("- ") or body == "-"):
break
rest = body[1:].strip()
if rest == "":
self.i += 1
out.append(self.node(indent + 1))
elif self.key_split(rest) is not None and not rest.startswith(("'", '"')) or \
(rest[:1] in ("'", '"') and self.key_split(rest) is not None):
# `- key: value`: treat the text after "- " as a mapping line at indent+2
self.lines[self.i] = " " * (indent + 2) + rest
out.append(self.mapping(indent + 2))
else:
self.i += 1
out.append(self.scalar(rest, indent))
return out
def value(self, rest, indent):
if rest == "" or rest.startswith("#"):
self.skip_blank()
if self.i < len(self.lines):
nxt = self.lines[self.i]
ni = self.indent_of(nxt)
nb = nxt.strip()
if ni > indent or (ni == indent and (nb.startswith("- ") or nb == "-")):
return self.node(ni)
return None
if rest[0] in "|>":
return self.block_scalar(rest, indent)
return self.scalar(rest, indent)
def block_scalar(self, header, indent):
fold = header[0] == ">"
buf = []
block_indent = None
while self.i < len(self.lines):
line = self.lines[self.i]
if line.strip() == "":
buf.append("")
self.i += 1
continue
li = self.indent_of(line)
if li <= indent:
break
if block_indent is None:
block_indent = li
buf.append(line[block_indent:] if li >= block_indent else line.strip())
self.i += 1
text = ("\n" if not fold else " ").join(buf).strip()
return text
def scalar(self, text, indent):
if text[0] in ("'", '"'):
q = text[0]
acc = text
# continuation lines until the closing quote
while not self.closed(acc, q) and self.i < len(self.lines):
acc += " " + self.lines[self.i].strip()
self.i += 1
body = acc[1:Yaml.end_of(acc, q)]
if q == '"':
body = body.replace('\\"', '"').replace("\\n", "\n").replace("\\\\", "\\")
else:
body = body.replace("''", "'")
return body
if text in ("[]", "{}"):
return [] if text == "[]" else {}
if text[0] in "[{":
acc = text
while acc.count("[") + acc.count("{") > acc.count("]") + acc.count("}") and self.i < len(self.lines):
acc += " " + self.lines[self.i].strip()
self.i += 1
return acc # flow collections beyond [] and {} are kept as text (not used by the checker)
# plain scalar: strip trailing comment, fold continuation lines that are more indented
text = re.sub(r"\s+#.*$", "", text)
while self.i < len(self.lines):
nxt = self.lines[self.i]
if nxt.strip() == "" or self.indent_of(nxt) <= indent:
break
if self.key_split(nxt.strip()) is not None and nxt.strip()[:1] not in ("'", '"'):
break
text += " " + nxt.strip()
self.i += 1
return text
@staticmethod
def end_of(acc, q):
j = 1
while j < len(acc):
c = acc[j]
if q == '"' and c == "\\":
j += 2
continue
if c == q:
if q == "'" and j + 1 < len(acc) and acc[j + 1] == "'":
j += 2
continue
return j
j += 1
return len(acc)
@staticmethod
def closed(acc, q):
"""True when the quoted scalar that starts acc has its closing quote."""
j = 1
while j < len(acc):
c = acc[j]
if q == '"' and c == "\\":
j += 2
continue
if c == q:
if q == "'" and j + 1 < len(acc) and acc[j + 1] == "'":
j += 2
continue
return True
j += 1
return False
# ------------------------------------------------------------------ spec model
class Spec:
def __init__(self, doc):
self.doc = doc
self.schemas = doc["components"]["schemas"]
self.params = doc["components"].get("parameters", {})
def ref(self, node):
seen = 0
while isinstance(node, dict) and "$ref" in node and seen < 20:
name = node["$ref"].split("/")[-1]
kind = node["$ref"].split("/")[-2]
node = (self.params if kind == "parameters" else self.schemas).get(name)
seen += 1
return node
def props(self, node, depth=0):
"""Union of property names (and required names) through $ref / allOf / oneOf / anyOf / items."""
props, required = {}, set()
node = self.ref(node)
if not isinstance(node, dict) or depth > 12:
return props, required
for key in ("allOf", "oneOf", "anyOf"):
for sub in node.get(key) or []:
p, r = self.props(sub, depth + 1)
props.update(p)
if key == "allOf":
required |= r
if isinstance(node.get("properties"), dict):
props.update(node["properties"])
if isinstance(node.get("required"), list):
required |= set(node["required"])
return props, required
def descend(self, node, path):
"""Follow a dotted property path; arrays are entered through items."""
for step in [p for p in path.split(".") if p]:
node = self.ref(node)
if isinstance(node, dict) and node.get("type") == "array" and "items" in node:
node = self.ref(node["items"])
props, _ = self.props(node)
if step not in props:
return None
node = props[step]
node = self.ref(node)
if isinstance(node, dict) and node.get("type") == "array" and "items" in node:
node = self.ref(node["items"])
return node
def operations(self):
for path, item in self.doc["paths"].items():
for method, op in item.items():
if method in METHODS and isinstance(op, dict):
yield method.upper(), path, op
def op_params(self, op):
out = {}
for p in op.get("parameters") or []:
p = self.ref(p)
if isinstance(p, dict) and p.get("in") in ("query", "path"):
out[p["name"]] = (p["in"], bool(p.get("required")))
return out
def op_body(self, op):
rb = op.get("requestBody")
if not rb:
return None, set()
content = rb.get("content") or {}
for ct in ("application/json", "multipart/form-data"):
if ct in content:
return self.props(content[ct].get("schema"))
return {}, set()
def op_response(self, op):
r = (op.get("responses") or {}).get("200") or {}
content = r.get("content") or {}
if "application/json" in content:
return content["application/json"].get("schema")
return None
# ------------------------------------------------------------------------ main
def rows(text, begin, end):
a, b = text.index(begin), text.index(end)
out = []
for line in text[a:b].splitlines()[1:]:
s = line.strip()
if s.startswith("{") and '"' in s:
out.append(STR.findall(s))
return out
def load_spec(argv):
if "--spec" in argv:
i = argv.index("--spec")
path = argv[i + 1]
del argv[i:i + 2]
with open(path, encoding="utf-8") as f:
return f.read()
req = urllib.request.Request(SPEC_URL, headers={"User-Agent": "molo-cohere-spec-check/1"})
with urllib.request.urlopen(req, timeout=120) as r:
return r.read().decode("utf-8", "replace")
def main():
argv = sys.argv[1:]
spec_text = load_spec(argv)
calls_path = argv[0] if argv else CALLS
text = open(calls_path).read()
calls = rows(text, "// CALLS-BEGIN", "// CALLS-END")
schemas = rows(text, "// SCHEMAS-BEGIN", "// SCHEMAS-END")
spec = Spec(Yaml(spec_text).parse())
ops = {(m, p): op for m, p, op in spec.operations()}
by_id = {op.get("operationId"): op for op in ops.values()}
bad = []
covered = set()
for method, path, op_id, body, query, response in calls:
op = ops.get((method, path))
if op is None:
bad.append("%s %s: not a path of the spec" % (method, path))
continue
covered.add((method, path))
if op.get("operationId") != op_id:
bad.append("%s %s: operationId is %s in the spec, %s in the table"
% (method, path, op.get("operationId"), op_id))
params = spec.op_params(op)
body_props, body_required = spec.op_body(op)
declared_body = {f for f in body.split(",") if f}
declared_query = {q for q in query.split(",") if q}
for f in sorted(declared_body):
if f not in body_props:
bad.append("%s %s: body field %s is not in the request body" % (method, path, f))
for q in sorted(declared_query):
if q not in params or params[q][0] != "query":
bad.append("%s %s: query parameter %s is not in the spec" % (method, path, q))
for name, (where, required) in params.items():
if where == "query" and required and name not in declared_query:
bad.append("%s %s: required query parameter %s missing in the row" % (method, path, name))
for f in sorted(body_required):
if f in body_props and f not in declared_body:
bad.append("%s %s: required body field %s missing in the row" % (method, path, f))
if response and response not in spec.schemas and response not in by_id:
bad.append("%s %s: response schema %s is neither a component nor an operationId" % (method, path, response))
for (method, path), op in sorted(ops.items()):
if (method, path) not in covered and op.get("operationId") not in EXCLUDED_OPERATIONS:
bad.append("unwrapped operation %s %s (%s): add a row or an exclusion"
% (method, path, op.get("operationId")))
checked_fields = 0
for name, fields in schemas:
head, _, tail = name.partition(".")
if head in spec.schemas:
node = spec.schemas[head]
elif head in by_id:
node = spec.op_response(by_id[head])
else:
bad.append("schema %s: neither a component nor an operationId" % head)
continue
target = spec.descend(node, tail) if tail else spec.ref(node)
if target is None:
bad.append("schema %s: property path not found" % name)
continue
props, _ = spec.props(target)
for f in filter(None, fields.split(",")):
checked_fields += 1
if f not in props:
bad.append("schema %s: field %s is not a property" % (name, f))
if bad:
print("SPEC CHECK FAILED")
for b in bad:
print(" " + b)
return 1
print("cohere spec ok: %d calls of %d spec operations (exclusions: %d), %d schema rows, %d fields"
% (len(calls), len(ops), len(EXCLUDED_OPERATIONS), len(schemas), checked_fields))
return 0
if __name__ == "__main__":
sys.exit(main())