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>
425 lines
16 KiB
Python
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())
|