Buckets:
AnonymousSpottedToad/human_verified_bucket / codebase /python /stateset_stateset-agents /scripts /check_api_compatibility.py
| #!/usr/bin/env python3 | |
| """Build and verify StateSet Agents' stable v1 public API contract.""" | |
| from __future__ import annotations | |
| import argparse | |
| import inspect | |
| import json | |
| import os | |
| import sys | |
| from enum import Enum | |
| from pathlib import Path | |
| from typing import Any | |
| REPO_ROOT = Path(__file__).resolve().parents[1] | |
| DEFAULT_MANIFEST = REPO_ROOT / "contracts" / "public_api_v1.json" | |
| STABLE_HTTP_OPERATIONS = ( | |
| "GET /api/v1/health", | |
| "POST /api/v1/training", | |
| "GET /api/v1/training/{job_id}", | |
| "DELETE /api/v1/training/{job_id}", | |
| "POST /api/v1/conversations", | |
| "GET /api/v1/conversations/{conversation_id}", | |
| "DELETE /api/v1/conversations/{conversation_id}", | |
| "GET /api/v1/rollouts/stats", | |
| "GET /api/v1/rollouts/workers", | |
| "POST /api/v1/rollouts/workers/{worker_id}/register", | |
| "POST /api/v1/rollouts/workers/{worker_id}/heartbeat", | |
| "POST /api/v1/rollouts/workers/{worker_id}/submit", | |
| "DELETE /api/v1/rollouts/workers/{worker_id}", | |
| "POST /v1/chat/completions", | |
| "POST /v1/messages", | |
| "GET /v1/models", | |
| "GET /healthz", | |
| "GET /ready", | |
| "GET /live", | |
| ) | |
| _HTTP_METHODS = {"get", "post", "put", "patch", "delete"} | |
| _DOCUMENTATION_KEYS = { | |
| "description", | |
| "example", | |
| "examples", | |
| "externalDocs", | |
| "summary", | |
| "tags", | |
| "title", | |
| "x-codeSamples", | |
| "x-code-samples", | |
| } | |
| class ApiCompatibilityError(RuntimeError): | |
| """Raised when the checked contract cannot be built or verified.""" | |
| def _wire_shape(value: Any) -> Any: | |
| """Remove prose-only OpenAPI fields while retaining wire constraints.""" | |
| if isinstance(value, dict): | |
| return { | |
| key: _wire_shape(item) | |
| for key, item in sorted(value.items()) | |
| if key not in _DOCUMENTATION_KEYS | |
| } | |
| if isinstance(value, list): | |
| return [_wire_shape(item) for item in value] | |
| return value | |
| def _collect_schema_refs(value: Any) -> set[str]: | |
| refs: set[str] = set() | |
| if isinstance(value, dict): | |
| ref = value.get("$ref") | |
| if isinstance(ref, str) and ref.startswith("#/components/schemas/"): | |
| refs.add(ref.rsplit("/", 1)[-1]) | |
| for item in value.values(): | |
| refs.update(_collect_schema_refs(item)) | |
| elif isinstance(value, list): | |
| for item in value: | |
| refs.update(_collect_schema_refs(item)) | |
| return refs | |
| def _stable_default(value: Any) -> Any: | |
| """Return a deterministic JSON-compatible callable default.""" | |
| if value is None or isinstance(value, (bool, int, float, str)): | |
| return value | |
| if isinstance(value, Enum): | |
| enum_type = type(value) | |
| return { | |
| "enum": f"{enum_type.__module__}.{enum_type.__qualname__}", | |
| "member": value.name, | |
| } | |
| if isinstance(value, tuple): | |
| return {"tuple": [_stable_default(item) for item in value]} | |
| return {"repr": repr(value)} | |
| def _call_signature(value: Any) -> dict[str, Any] | None: | |
| """Describe call shape without interpreter-specific annotation rendering.""" | |
| if inspect.isclass(value) and issubclass(value, Enum): | |
| return None | |
| try: | |
| signature = inspect.signature(value, eval_str=False) | |
| except (TypeError, ValueError): | |
| return None | |
| parameters: list[dict[str, Any]] = [] | |
| for parameter in signature.parameters.values(): | |
| item: dict[str, Any] = { | |
| "kind": parameter.kind.name, | |
| "name": parameter.name, | |
| } | |
| if parameter.default is not inspect.Parameter.empty: | |
| item["default"] = _stable_default(parameter.default) | |
| parameters.append(item) | |
| return {"parameters": parameters} | |
| def _python_contract() -> dict[str, dict[str, dict[str, Any]]]: | |
| import stateset_agents | |
| import stateset_agents.api as api | |
| lazy_exports = stateset_agents._LAZY_EXPORTS # type: ignore[attr-defined] | |
| declared_exports = set(stateset_agents.__all__) | |
| mapped_exports = set(lazy_exports) | |
| if declared_exports != mapped_exports: | |
| missing = sorted(declared_exports - mapped_exports) | |
| extra = sorted(mapped_exports - declared_exports) | |
| raise ApiCompatibilityError( | |
| "stateset_agents.__all__ and _LAZY_EXPORTS differ: " | |
| f"unmapped={missing}, undeclared={extra}" | |
| ) | |
| root_exports: dict[str, dict[str, Any]] = {} | |
| for name, (module_name, attr_name, _hint) in sorted(lazy_exports.items()): | |
| entry = {"module": module_name, "name": attr_name} | |
| value = getattr(stateset_agents, name) | |
| if callable(value): | |
| signature = _call_signature(value) | |
| if signature is not None: | |
| entry["signature"] = signature | |
| root_exports[name] = entry | |
| api_exports: dict[str, dict[str, Any]] = {} | |
| for name in sorted(api.__all__): | |
| value = getattr(api, name) | |
| api_exports[name] = { | |
| "module": str(getattr(value, "__module__", api.__name__)), | |
| "name": str(getattr(value, "__qualname__", name)), | |
| } | |
| if callable(value): | |
| signature = _call_signature(value) | |
| if signature is not None: | |
| api_exports[name]["signature"] = signature | |
| return { | |
| "stateset_agents": root_exports, | |
| "stateset_agents.api": api_exports, | |
| } | |
| def _http_contract() -> dict[str, Any]: | |
| os.environ.setdefault("API_ENABLE_TRAINING_LAB", "false") | |
| os.environ.setdefault("API_JWT_SECRET", "compatibility-contract-only") | |
| os.environ.setdefault("API_REQUIRE_AUTH", "false") | |
| from stateset_agents.api.main import create_app | |
| schema = create_app().openapi() | |
| operations: dict[str, Any] = {} | |
| for path, path_item in schema.get("paths", {}).items(): | |
| if not isinstance(path_item, dict): | |
| continue | |
| for method, operation in path_item.items(): | |
| if method.lower() not in _HTTP_METHODS or not isinstance(operation, dict): | |
| continue | |
| key = f"{method.upper()} {path}" | |
| if key in STABLE_HTTP_OPERATIONS: | |
| operations[key] = _wire_shape(operation) | |
| missing = sorted(set(STABLE_HTTP_OPERATIONS) - set(operations)) | |
| if missing: | |
| raise ApiCompatibilityError( | |
| "stable HTTP operations missing from OpenAPI: " + ", ".join(missing) | |
| ) | |
| all_schemas = schema.get("components", {}).get("schemas", {}) | |
| referenced = _collect_schema_refs(operations) | |
| selected_schemas: dict[str, Any] = {} | |
| pending = sorted(referenced) | |
| while pending: | |
| name = pending.pop(0) | |
| if name in selected_schemas: | |
| continue | |
| component = all_schemas.get(name) | |
| if not isinstance(component, dict): | |
| raise ApiCompatibilityError(f"referenced OpenAPI schema is missing: {name}") | |
| normalized = _wire_shape(component) | |
| selected_schemas[name] = normalized | |
| pending.extend( | |
| sorted( | |
| _collect_schema_refs(normalized) - set(selected_schemas) - set(pending) | |
| ) | |
| ) | |
| return { | |
| "operations": dict(sorted(operations.items())), | |
| "schemas": dict(sorted(selected_schemas.items())), | |
| } | |
| def build_contract() -> dict[str, Any]: | |
| """Return the deterministic stable API contract for the current tree.""" | |
| return { | |
| "contract_version": 1, | |
| "stability": "v1", | |
| "python": _python_contract(), | |
| "http": _http_contract(), | |
| } | |
| def compare_contracts(expected: Any, actual: Any, path: str = "$") -> list[str]: | |
| """Return deterministic structural differences between two contracts.""" | |
| if type(expected) is not type(actual): | |
| return [ | |
| f"{path}: type changed from {type(expected).__name__} " | |
| f"to {type(actual).__name__}" | |
| ] | |
| if isinstance(expected, dict): | |
| differences: list[str] = [] | |
| expected_keys = set(expected) | |
| actual_keys = set(actual) | |
| differences.extend( | |
| f"{path}.{key}: removed" for key in sorted(expected_keys - actual_keys) | |
| ) | |
| differences.extend( | |
| f"{path}.{key}: added" for key in sorted(actual_keys - expected_keys) | |
| ) | |
| for key in sorted(expected_keys & actual_keys): | |
| differences.extend( | |
| compare_contracts(expected[key], actual[key], f"{path}.{key}") | |
| ) | |
| return differences | |
| if isinstance(expected, list): | |
| differences = [] | |
| if len(expected) != len(actual): | |
| differences.append( | |
| f"{path}: length changed from {len(expected)} to {len(actual)}" | |
| ) | |
| for index, (expected_item, actual_item) in enumerate( | |
| zip(expected, actual, strict=False) | |
| ): | |
| differences.extend( | |
| compare_contracts(expected_item, actual_item, f"{path}[{index}]") | |
| ) | |
| return differences | |
| if expected != actual: | |
| return [f"{path}: changed from {expected!r} to {actual!r}"] | |
| return [] | |
| def load_manifest(path: Path) -> dict[str, Any]: | |
| """Load a contract manifest and reject invalid top-level payloads.""" | |
| try: | |
| payload = json.loads(path.read_text(encoding="utf-8")) | |
| except FileNotFoundError as exc: | |
| raise ApiCompatibilityError( | |
| f"contract manifest does not exist: {path}" | |
| ) from exc | |
| except (json.JSONDecodeError, OSError) as exc: | |
| raise ApiCompatibilityError( | |
| f"contract manifest is unreadable: {path}: {exc}" | |
| ) from exc | |
| if not isinstance(payload, dict): | |
| raise ApiCompatibilityError( | |
| f"contract manifest must contain a JSON object: {path}" | |
| ) | |
| return payload | |
| def write_manifest(path: Path, contract: dict[str, Any]) -> None: | |
| """Write a canonical contract manifest.""" | |
| path.parent.mkdir(parents=True, exist_ok=True) | |
| path.write_text( | |
| json.dumps(contract, indent=2, sort_keys=True) + "\n", encoding="utf-8" | |
| ) | |
| def _parser() -> argparse.ArgumentParser: | |
| parser = argparse.ArgumentParser(description=__doc__) | |
| parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST) | |
| parser.add_argument( | |
| "--write", | |
| action="store_true", | |
| help="replace the manifest with the current contract (review the diff)", | |
| ) | |
| return parser | |
| def main(argv: list[str] | None = None) -> int: | |
| args = _parser().parse_args(argv) | |
| try: | |
| current = build_contract() | |
| if args.write: | |
| write_manifest(args.manifest, current) | |
| print(f"Wrote stable API contract: {args.manifest}") | |
| return 0 | |
| expected = load_manifest(args.manifest) | |
| differences = compare_contracts(expected, current) | |
| if differences: | |
| print("Stable v1 API contract changed without a reviewed manifest update.") | |
| for difference in differences[:100]: | |
| print(f"- {difference}") | |
| if len(differences) > 100: | |
| print(f"- ... and {len(differences) - 100} more differences") | |
| return 1 | |
| print("Stable v1 API compatibility check passed.") | |
| return 0 | |
| except ApiCompatibilityError as exc: | |
| print(f"Stable v1 API compatibility check failed: {exc}", file=sys.stderr) | |
| return 1 | |
| if __name__ == "__main__": | |
| raise SystemExit(main()) | |
Xet Storage Details
- Size:
- 11.3 kB
- Xet hash:
- 3a7999e47d9c2b8fdd55adaf1441b28c7275fd810a8a64d413fee54d344af3bb
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.