From 6e6a4649ba4b5ad0f417ad113d7752ffb920effa Mon Sep 17 00:00:00 2001 From: adibarra <93070681+adibarra@users.noreply.github.com> Date: Mon, 10 Aug 2026 13:32:13 -0500 Subject: [PATCH 1/2] feat: add synchronized public api reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 中文:新增同步维护的公开 API 参考文档、OpenAPI 3.1 契约,以及用于防止接口与文档不一致的校验。 --- .../app/cypress/e2e/api-documentation.cy.ts | 81 + .../app/src/app/api/openapi.json/route.ts | 13 + packages/app/src/app/api/page.tsx | 30 + packages/app/src/app/llms.txt/route.ts | 2 + packages/app/src/app/sitemap.ts | 1 + packages/app/src/app/zh/api/page.tsx | 30 + .../api-documentation/api-reference-page.tsx | 568 ++++ packages/app/src/components/footer/footer.tsx | 10 + packages/app/src/lib/api-documentation.ts | 2412 +++++++++++++++++ .../app/src/lib/api-route-catalog.test.ts | 399 +++ packages/app/src/lib/api-route-catalog.ts | 541 ++++ packages/app/src/lib/i18n.ts | 1 + 12 files changed, 4088 insertions(+) create mode 100644 packages/app/cypress/e2e/api-documentation.cy.ts create mode 100644 packages/app/src/app/api/openapi.json/route.ts create mode 100644 packages/app/src/app/api/page.tsx create mode 100644 packages/app/src/app/zh/api/page.tsx create mode 100644 packages/app/src/components/api-documentation/api-reference-page.tsx create mode 100644 packages/app/src/lib/api-documentation.ts create mode 100644 packages/app/src/lib/api-route-catalog.test.ts create mode 100644 packages/app/src/lib/api-route-catalog.ts diff --git a/packages/app/cypress/e2e/api-documentation.cy.ts b/packages/app/cypress/e2e/api-documentation.cy.ts new file mode 100644 index 000000000..f96d70f81 --- /dev/null +++ b/packages/app/cypress/e2e/api-documentation.cy.ts @@ -0,0 +1,81 @@ +const SITE_URL = 'https://inferencex.semianalysis.com'; + +describe('API documentation', () => { + it('exposes the localized reference and its OpenAPI contract', () => { + cy.visit('/api'); + + cy.get('[data-testid="api-reference"]') + .should('contain.text', 'InferenceX API reference') + .and('contain.text', 'Quickstart') + .and('contain.text', 'curl') + .and('contain.text', '/api/v1/availability') + .and('contain.text', 'Endpoint reference'); + cy.get('[data-testid="api-openapi-link"]').should('have.attr', 'href', '/api/openapi.json'); + cy.get('[data-testid="api-spec-version"]').should('have.text', 'v1 · OpenAPI 3.1'); + cy.get('[data-testid="api-endpoint-list-benchmarks"]') + .should('contain.text', 'GET') + .and('contain.text', '/api/v1/benchmarks'); + cy.get('[data-testid="api-endpoint-get-collectivex-run"]') + .should('contain.text', 'GET') + .and('contain.text', '/api/v1/collectivex/runs/{runId}'); + + cy.get('link[rel="alternate"][hreflang="en"]').should('have.attr', 'href', `${SITE_URL}/api`); + cy.get('link[rel="alternate"][hreflang="zh-CN"]').should( + 'have.attr', + 'href', + `${SITE_URL}/zh/api`, + ); + cy.get('link[rel="alternate"][hreflang="x-default"]').should( + 'have.attr', + 'href', + `${SITE_URL}/api`, + ); + cy.get('[data-testid="language-toggle"]') + .should('have.attr', 'href', '/zh/api') + .and('have.attr', 'hreflang', 'zh-CN'); + cy.get('[data-testid="footer-link-api"]') + .should('have.attr', 'href', '/api') + .and('have.text', 'API Reference'); + + cy.request('/api/openapi.json').then(({ body, headers, status }) => { + expect(status).to.equal(200); + expect(headers['content-type']).to.contain('application/json'); + expect(body).to.have.property('openapi', '3.1.0'); + expect(body.paths['/api/v1/benchmarks'].get).to.have.property( + 'operationId', + 'list-benchmarks', + ); + expect(body.paths['/api/v1/collectivex/runs/{runId}'].get).to.have.property( + 'operationId', + 'get-collectivex-run', + ); + }); + + cy.visit('/zh/api'); + + cy.get('[data-testid="api-reference"]') + .should('contain.text', 'InferenceX API 参考文档') + .and('contain.text', '快速入门') + .and('contain.text', '约定') + .and('contain.text', '端点参考') + .and('contain.text', 'BenchmarkRow 与指标'); + cy.get('[data-testid="api-openapi-link"]').should('have.attr', 'href', '/api/openapi.json'); + cy.get('link[rel="alternate"][hreflang="en"]').should('have.attr', 'href', `${SITE_URL}/api`); + cy.get('link[rel="alternate"][hreflang="zh-CN"]').should( + 'have.attr', + 'href', + `${SITE_URL}/zh/api`, + ); + cy.get('link[rel="alternate"][hreflang="x-default"]').should( + 'have.attr', + 'href', + `${SITE_URL}/api`, + ); + cy.get('[data-testid="language-toggle"]') + .should('have.attr', 'href', '/api') + .and('have.attr', 'hreflang', 'en'); + cy.get('[data-testid="footer-link-api"]') + .should('have.attr', 'href', '/zh/api') + .and('have.text', 'API 参考文档'); + }); +}); diff --git a/packages/app/src/app/api/openapi.json/route.ts b/packages/app/src/app/api/openapi.json/route.ts new file mode 100644 index 000000000..7e6c1672d --- /dev/null +++ b/packages/app/src/app/api/openapi.json/route.ts @@ -0,0 +1,13 @@ +import { NextResponse } from 'next/server'; + +import { buildOpenApiDocument } from '@/lib/api-documentation'; + +export const dynamic = 'force-static'; + +export function GET() { + return NextResponse.json(buildOpenApiDocument(), { + headers: { + 'Cache-Control': 'public, max-age=0, s-maxage=3600, stale-while-revalidate=86400', + }, + }); +} diff --git a/packages/app/src/app/api/page.tsx b/packages/app/src/app/api/page.tsx new file mode 100644 index 000000000..731e10594 --- /dev/null +++ b/packages/app/src/app/api/page.tsx @@ -0,0 +1,30 @@ +import type { Metadata } from 'next'; + +import { ApiReferencePage } from '@/components/api-documentation/api-reference-page'; +import { getApiDocumentation } from '@/lib/api-documentation'; +import { enAlternates } from '@/lib/i18n'; +import { SITE_NAME, SITE_URL } from '@semianalysisai/inferencex-constants'; + +const documentation = getApiDocumentation('en'); + +export const metadata: Metadata = { + title: documentation.title, + description: documentation.description, + alternates: enAlternates('/api'), + openGraph: { + title: `${documentation.title} | ${SITE_NAME}`, + description: documentation.description, + url: `${SITE_URL}/api`, + locale: 'en_US', + type: 'article', + }, + twitter: { + card: 'summary_large_image', + title: `${documentation.title} | ${SITE_NAME}`, + description: documentation.description, + }, +}; + +export default function ApiPage() { + return ; +} diff --git a/packages/app/src/app/llms.txt/route.ts b/packages/app/src/app/llms.txt/route.ts index b1aa043f6..a53149eed 100644 --- a/packages/app/src/app/llms.txt/route.ts +++ b/packages/app/src/app/llms.txt/route.ts @@ -14,6 +14,8 @@ export async function GET() { '', `- [Dashboard](${SITE_URL})`, `- [Articles](${SITE_URL}/blog)`, + `- [API Reference](${SITE_URL}/api)`, + `- [OpenAPI 3.1 Specification](${SITE_URL}/api/openapi.json)`, `- [RSS Feed](${SITE_URL}/feed.xml)`, `- [Full content for LLMs](${SITE_URL}/llms-full.txt)`, `- [GitHub](https://github.com/SemiAnalysisAI/InferenceX)`, diff --git a/packages/app/src/app/sitemap.ts b/packages/app/src/app/sitemap.ts index 8bce05497..d85b07299 100644 --- a/packages/app/src/app/sitemap.ts +++ b/packages/app/src/app/sitemap.ts @@ -95,6 +95,7 @@ export default async function sitemap(): Promise { priority: 0.8, }), ...localizedPair('/datasets', { lastModified: now, changeFrequency: 'weekly', priority: 0.6 }), + ...localizedPair('/api', { lastModified: now, changeFrequency: 'monthly', priority: 0.7 }), ...localizedPair('/blog', { lastModified: now, changeFrequency: 'weekly', priority: 0.8 }), ...localizedPair('/glossary', { lastModified: now, diff --git a/packages/app/src/app/zh/api/page.tsx b/packages/app/src/app/zh/api/page.tsx new file mode 100644 index 000000000..977198194 --- /dev/null +++ b/packages/app/src/app/zh/api/page.tsx @@ -0,0 +1,30 @@ +import type { Metadata } from 'next'; + +import { ApiReferencePage } from '@/components/api-documentation/api-reference-page'; +import { getApiDocumentation } from '@/lib/api-documentation'; +import { zhAlternates, ZH_OG_LOCALE } from '@/lib/i18n'; +import { SITE_NAME, SITE_URL } from '@semianalysisai/inferencex-constants'; + +const documentation = getApiDocumentation('zh'); + +export const metadata: Metadata = { + title: documentation.title, + description: documentation.description, + alternates: zhAlternates('/api'), + openGraph: { + title: `${documentation.title} | ${SITE_NAME}`, + description: documentation.description, + url: `${SITE_URL}/zh/api`, + locale: ZH_OG_LOCALE, + type: 'article', + }, + twitter: { + card: 'summary_large_image', + title: `${documentation.title} | ${SITE_NAME}`, + description: documentation.description, + }, +}; + +export default function ApiPageZh() { + return ; +} diff --git a/packages/app/src/components/api-documentation/api-reference-page.tsx b/packages/app/src/components/api-documentation/api-reference-page.tsx new file mode 100644 index 000000000..4db1ee4ad --- /dev/null +++ b/packages/app/src/components/api-documentation/api-reference-page.tsx @@ -0,0 +1,568 @@ +import { Badge } from '@/components/ui/badge'; +import { Card } from '@/components/ui/card'; +import { JsonLd } from '@/components/json-ld'; +import { getApiDocumentation, type ApiDocumentationLocale } from '@/lib/api-documentation'; +import { ZH_LANG_TAG } from '@/lib/i18n'; +import { AUTHOR_NAME, AUTHOR_URL, SITE_NAME, SITE_URL } from '@semianalysisai/inferencex-constants'; + +const UI_COPY = { + en: { + facts: { + version: 'Specification', + auth: 'Authentication', + format: 'Response format', + baseUrl: 'Base URL', + }, + openApiKicker: 'Machine-readable contract', + openApiTitle: 'OpenAPI 3.1 JSON', + openApiDescription: 'Inspect the canonical schema or pass it directly to your tooling.', + openApiAction: 'Open OpenAPI JSON', + quickstart: 'Quickstart', + quickstartDescription: 'Move from contract discovery to a real response in a few steps.', + conventions: 'Conventions', + conventionsDescription: 'Shared request, error, and cache behavior for the supported surface.', + schemas: 'BenchmarkRow and metrics', + schemasDescription: 'Interpret the primary benchmark payload and its measured fields.', + endpoints: 'Endpoint reference', + endpointsDescription: 'Expand an operation for parameters, statuses, and complete examples.', + operation: 'operation', + operations: 'operations', + parameters: 'Parameters', + noParameters: 'No parameters.', + name: 'Name', + location: 'Location', + type: 'Type', + requirement: 'Requirement', + description: 'Description', + example: 'Example', + required: 'Required', + optional: 'Optional', + request: 'Request', + responses: 'Responses', + responseShape: 'Response shape', + responseExample: 'Response example', + mediaType: 'Media type', + schemaShape: 'Shape', + schemaExample: 'Example', + stable: 'Stable', + beta: 'Beta', + alternateRepresentation: 'Alternate representation', + schemaKicker: 'Schema', + referenceKicker: 'Reference', + }, + zh: { + facts: { + version: '规范版本', + auth: '身份验证', + format: '响应格式', + baseUrl: '基础 URL', + }, + openApiKicker: '机器可读契约', + openApiTitle: 'OpenAPI 3.1 JSON', + openApiDescription: '查看标准数据结构,或将其直接传入开发工具。', + openApiAction: '打开 OpenAPI JSON', + quickstart: '快速入门', + quickstartDescription: '只需几步,即可从查看契约到获得真实响应。', + conventions: '约定', + conventionsDescription: '适用于受支持接口的通用请求、错误与缓存行为。', + schemas: 'BenchmarkRow 与指标', + schemasDescription: '理解主要基准测试响应数据及其中的实测字段。', + endpoints: '端点参考', + endpointsDescription: '展开操作,查看参数、状态码与完整示例。', + operation: '项操作', + operations: '项操作', + parameters: '参数', + noParameters: '无需参数。', + name: '名称', + location: '位置', + type: '类型', + requirement: '要求', + description: '说明', + example: '示例', + required: '必填', + optional: '可选', + request: '请求', + responses: '响应', + responseShape: '响应结构', + responseExample: '响应示例', + mediaType: '媒体类型', + schemaShape: '结构', + schemaExample: '示例', + stable: '稳定', + beta: '测试版', + alternateRepresentation: '其他表示格式', + schemaKicker: '数据结构', + referenceKicker: '参考', + }, +} as const; + +function formatCode(value: unknown): string { + if (typeof value === 'string') return value; + return JSON.stringify(value, null, 2) ?? ''; +} + +function CodeBlock({ children }: { children: string }) { + return ( +
+      {children}
+    
+ ); +} + +export function ApiReferencePage({ locale }: { locale: ApiDocumentationLocale }) { + const documentation = getApiDocumentation(locale); + const copy = UI_COPY[locale]; + const pageUrl = `${SITE_URL}${locale === 'zh' ? '/zh' : ''}/api`; + const operationCount = documentation.groups.reduce( + (count, group) => count + group.operations.length, + 0, + ); + const jsonLd = { + '@context': 'https://schema.org', + '@type': 'TechArticle', + headline: documentation.title, + description: documentation.description, + url: pageUrl, + mainEntityOfPage: pageUrl, + inLanguage: locale === 'zh' ? ZH_LANG_TAG : 'en-US', + version: `${documentation.version} / ${documentation.specVersion}`, + isAccessibleForFree: true, + author: { + '@type': 'Organization', + name: AUTHOR_NAME, + url: AUTHOR_URL, + }, + publisher: { + '@type': 'Organization', + name: SITE_NAME, + url: SITE_URL, + }, + }; + + return ( +
+ +
+ +
+
+

+ {documentation.eyebrow} +

+

+ {documentation.title} +

+

+ {documentation.description} +

+
+ +
+

+ {copy.openApiKicker} +

+

{copy.openApiTitle}

+

+ {copy.openApiDescription} +

+ + {copy.openApiAction} + + +
+
+ +
+
+
{copy.facts.version}
+
+ {documentation.version} · {documentation.specVersion} +
+
+
+
{copy.facts.auth}
+
+ {documentation.auth.title} + + {documentation.auth.description} + +
+
+
+
{copy.facts.format}
+
+ + {documentation.format.title} + + + {documentation.format.description} + +
+
+
+
{copy.facts.baseUrl}
+
+ {documentation.baseUrl} +
+
+
+
+ + +
+
+

+ 01 / {copy.quickstart} +

+

+ {copy.quickstart} +

+

+ {copy.quickstartDescription} +

+
+ +
    + {documentation.quickstarts.map((step, index) => ( +
  1. +
    + + {String(index + 1).padStart(2, '0')} + +
    +

    {step.label}

    +

    + {step.description} +

    +
    +
    +
    + {step.command} +
    +
  2. + ))} +
+
+
+ + +
+
+

+ 02 / {copy.conventions} +

+

+ {copy.conventions} +

+

+ {copy.conventionsDescription} +

+
+ +
+ {documentation.conventions.map((convention) => ( +
+
{convention.title}
+
+ {convention.description} +
+
+ ))} +
+
+
+ + +
+
+

+ 03 / {copy.schemaKicker} +

+

+ {copy.schemas} +

+

+ {copy.schemasDescription} +

+
+ +
+ {documentation.schemaNotes.map((schema) => ( +
+
{schema.title}
+
+

{schema.description}

+

+ {copy.schemaShape} +

+ {formatCode(schema.shape)} + {schema.example !== undefined && ( + <> +

+ {copy.schemaExample} +

+ {formatCode(schema.example)} + + )} +
+
+ ))} +
+
+
+ + +
+
+
+

+ 04 / {copy.referenceKicker} +

+

+ {copy.endpoints} +

+

+ {copy.endpointsDescription} +

+
+

+ {operationCount} {operationCount === 1 ? copy.operation : copy.operations} +

+
+ +
+ {documentation.groups.map((group) => ( +
+
+

+ {group.title} +

+

+ {group.description} +

+
+ +
+ {group.operations.map((operation) => ( +
+ + + {operation.method} + + + {operation.stability === 'stable' ? copy.stable : copy.beta} + + + + {operation.path} + + + {operation.summary} + + + + + +
+

+ {operation.description} +

+ +
+

+ {copy.parameters} +

+ {operation.parameters.length === 0 ? ( +

+ {copy.noParameters} +

+ ) : ( +
+ + + + + + + + + + + + + + {operation.parameters.map((parameter) => ( + + + + + + + + + ))} + +
+ {operation.method} {operation.path}: {copy.parameters} +
+ {copy.name} + + {copy.location} + + {copy.type} + + {copy.requirement} + + {copy.description} + + {copy.example} +
+ {parameter.name} + + {parameter.location} + + {parameter.type} + + {parameter.required ? copy.required : copy.optional} + + {parameter.description} + + {parameter.example === undefined + ? null + : formatCode(parameter.example)} +
+
+ )} +
+ +
+

+ {copy.request} +

+ {`curl -sS '${operation.curlUrl}'`} +
+ +
+
+

+ {copy.responses} +

+ + {operation.responseShapeName} + +
+
+ {operation.responses.map((response) => ( +
+
+ + {response.status} + +

+ {response.description} +

+ {response.mediaType && ( + + {copy.mediaType}: {response.mediaType} + + )} +
+
+
+

+ {copy.responseShape} +

+ {formatCode(response.schema)} +
+ {response.example !== undefined && ( +
+

+ {copy.responseExample} +

+ {formatCode(response.example)} +
+ )} +
+ {response.alternateRepresentations?.map((alternate) => ( +
+

+ {copy.alternateRepresentation}: {alternate.mediaType} +

+
+
+

+ {copy.responseShape} +

+ {formatCode(alternate.schema)} +
+
+

+ {copy.responseExample} +

+ {formatCode(alternate.example)} +
+
+
+ ))} +
+ ))} +
+
+
+
+ ))} +
+
+ ))} +
+
+
+
+
+ ); +} diff --git a/packages/app/src/components/footer/footer.tsx b/packages/app/src/components/footer/footer.tsx index 494e6b260..a4d36179a 100644 --- a/packages/app/src/components/footer/footer.tsx +++ b/packages/app/src/components/footer/footer.tsx @@ -28,6 +28,7 @@ const STRINGS = { supporters: 'Supporters', datasets: 'Datasets', articles: 'Articles', + apiReference: 'API Reference', gpuReliability: 'Chip Reliability', perfPerDollar: 'Performance per Dollar', glossary: 'AI Inference Glossary', @@ -56,6 +57,7 @@ const STRINGS = { datasets: '数据集', articles: '文章', gpuReliability: 'Chip 可靠性', + apiReference: 'API 参考文档', perfPerDollar: '每美元性能', glossary: 'AI 推理术语表', languageLink: 'English', @@ -210,6 +212,14 @@ export const Footer = ({ starCount }: { starCount?: number | null }) => { > {t.articles} + track('footer_api_clicked')} + className="text-sm text-muted-foreground hover:text-foreground transition-colors" + > + {t.apiReference} + ; + +type JsonSchemaType = 'array' | 'boolean' | 'integer' | 'null' | 'number' | 'object' | 'string'; + +export interface ApiSchema { + readonly type?: JsonSchemaType | readonly JsonSchemaType[]; + readonly format?: string; + readonly description?: string; + readonly enum?: readonly (boolean | number | string)[]; + readonly default?: boolean | number | string; + readonly minimum?: number; + readonly maximum?: number; + readonly minLength?: number; + readonly maxLength?: number; + readonly pattern?: string; + readonly items?: ApiSchema; + readonly properties?: Readonly>; + readonly required?: readonly string[]; + readonly additionalProperties?: boolean | ApiSchema; + readonly oneOf?: readonly ApiSchema[]; +} + +export interface ApiParameter { + readonly name: string; + readonly location: ApiParameterLocation; + readonly required: boolean; + readonly type: string; + readonly description: BilingualText; + readonly schema: ApiSchema; + readonly example: boolean | number | string; +} + +export interface ApiResponseRepresentation { + readonly mediaType: 'application/json' | 'text/csv'; + readonly schema: ApiSchema; + readonly example: unknown; +} + +export interface ApiResponse { + readonly status: `${number}`; + readonly description: BilingualText; + readonly schema: ApiSchema; + readonly example: unknown; + readonly mediaType?: 'application/json' | 'text/csv'; + readonly alternateRepresentations?: readonly ApiResponseRepresentation[]; +} + +export interface ApiOperation { + readonly id: string; + readonly group: ApiGroupId; + readonly method: ApiHttpMethod; + readonly path: string; + readonly summary: BilingualText; + readonly description: BilingualText; + readonly audience: ApiAudience; + readonly stability: ApiStability; + readonly parameters: readonly ApiParameter[]; + readonly responses: readonly ApiResponse[]; + readonly responseShapeName: string; + readonly curlUrl: string; +} + +export interface LocalizedApiParameter extends Omit { + readonly description: string; +} + +export interface LocalizedApiResponse extends Omit { + readonly description: string; +} + +export interface LocalizedApiOperation extends Omit< + ApiOperation, + 'description' | 'parameters' | 'responses' | 'summary' +> { + readonly summary: string; + readonly description: string; + readonly parameters: readonly LocalizedApiParameter[]; + readonly responses: readonly LocalizedApiResponse[]; +} + +export interface ApiDocumentationGroup { + readonly id: ApiGroupId; + readonly title: BilingualText; + readonly description: BilingualText; +} + +export interface OpenApiDocument { + readonly openapi: '3.1.0'; + readonly info: Readonly>; + readonly servers: readonly Readonly>[]; + readonly externalDocs: Readonly>; + readonly tags: readonly Readonly>[]; + readonly paths: Readonly>; + readonly components: Readonly<{ schemas: Readonly> }>; +} + +export const API_BASE_URL = 'https://inferencex.semianalysis.com' as const; +export const API_VERSION = 'v1' as const; +export const OPENAPI_VERSION = '3.1.0' as const; +export const API_DOCUMENT_VERSION = '1.0.0' as const; +export const OPENAPI_DISPLAY_VERSION = 'OpenAPI 3.1' as const; +export const OPENAPI_DOCUMENT_URL = '/api/openapi.json' as const; + +export const SUPPORTED_BENCHMARK_MODELS = Object.freeze( + Object.keys(DISPLAY_MODEL_TO_DB).toSorted(), +); +export const SUPPORTED_TCO_MODELS = Object.freeze( + [...new Set([...Object.keys(DB_MODEL_TO_DISPLAY), ...SUPPORTED_BENCHMARK_MODELS])].toSorted(), +); + +const text = (en: string, zh: string): BilingualText => ({ en, zh }); +const stringSchema: ApiSchema = { type: 'string' }; +const numberSchema: ApiSchema = { type: 'number' }; +const integerSchema: ApiSchema = { type: 'integer' }; +const booleanSchema: ApiSchema = { type: 'boolean' }; +const nullableStringSchema: ApiSchema = { type: ['string', 'null'] }; +const nullableNumberSchema: ApiSchema = { type: ['number', 'null'] }; +const metricMapSchema: ApiSchema = { type: 'object', additionalProperties: numberSchema }; +const anyObjectSchema: ApiSchema = { type: 'object', additionalProperties: true }; +const errorSchema: ApiSchema = { + type: 'object', + properties: { error: stringSchema }, + required: ['error'], + additionalProperties: true, +}; + +const objectSchema = ( + properties: Readonly>, + required: readonly string[] = Object.keys(properties), +): ApiSchema => ({ type: 'object', properties, required, additionalProperties: false }); +const objectSchemaWithOptional = ( + properties: Readonly>, + optional: readonly string[], +): ApiSchema => + objectSchema( + properties, + Object.keys(properties).filter((property) => !optional.includes(property)), + ); +const arraySchema = (items: ApiSchema): ApiSchema => ({ type: 'array', items }); +const mapSchema = (items: ApiSchema): ApiSchema => ({ + type: 'object', + additionalProperties: items, +}); + +const parameter = ( + name: string, + location: ApiParameterLocation, + required: boolean, + type: string, + en: string, + zh: string, + schema: ApiSchema, + example: boolean | number | string, +): ApiParameter => ({ name, location, required, type, description: text(en, zh), schema, example }); + +const success = ( + en: string, + zh: string, + schema: ApiSchema, + example: unknown, + alternateRepresentations?: readonly ApiResponseRepresentation[], +): ApiResponse => ({ + status: '200', + description: text(en, zh), + schema, + example, + mediaType: 'application/json', + alternateRepresentations, +}); + +const errorResponse = ( + status: `${number}`, + en: string, + zh: string, + error: string, +): ApiResponse => ({ + status, + description: text(en, zh), + schema: errorSchema, + example: { error }, + mediaType: 'application/json', +}); + +const workerPowerSchema = objectSchemaWithOptional( + { + role: stringSchema, + worker_idx: integerSchema, + hosts: arraySchema(stringSchema), + num_gpus: integerSchema, + avg_power_w: numberSchema, + avg_temp_c: numberSchema, + peak_temp_c: numberSchema, + avg_util_pct: numberSchema, + avg_mem_used_mb: numberSchema, + }, + ['hosts', 'avg_temp_c', 'peak_temp_c', 'avg_util_pct', 'avg_mem_used_mb'], +); + +const benchmarkRowSchema = objectSchemaWithOptional( + { + id: integerSchema, + hardware: stringSchema, + framework: stringSchema, + model: stringSchema, + precision: stringSchema, + spec_method: stringSchema, + disagg: booleanSchema, + is_multinode: booleanSchema, + prefill_tp: integerSchema, + prefill_ep: integerSchema, + prefill_dp_attention: booleanSchema, + prefill_num_workers: integerSchema, + decode_tp: integerSchema, + decode_ep: integerSchema, + decode_dp_attention: booleanSchema, + decode_num_workers: integerSchema, + num_prefill_gpu: integerSchema, + num_decode_gpu: integerSchema, + benchmark_type: stringSchema, + isl: nullableNumberSchema, + osl: nullableNumberSchema, + conc: integerSchema, + offload_mode: stringSchema, + image: nullableStringSchema, + metrics: metricMapSchema, + workers: arraySchema(workerPowerSchema), + date: { type: 'string', format: 'date' }, + run_url: nullableStringSchema, + }, + ['workers'], +); +const benchmarkRowsSchema = arraySchema(benchmarkRowSchema); +const benchmarkExample = [ + { + id: 421, + hardware: 'h200_sxm', + framework: 'vllm', + model: 'dsr1', + precision: 'fp8', + spec_method: 'none', + disagg: false, + is_multinode: false, + prefill_tp: 8, + prefill_ep: 1, + prefill_dp_attention: false, + prefill_num_workers: 1, + decode_tp: 8, + decode_ep: 1, + decode_dp_attention: false, + decode_num_workers: 1, + num_prefill_gpu: 0, + num_decode_gpu: 8, + benchmark_type: 'single_turn', + isl: 1024, + osl: 1024, + conc: 32, + offload_mode: 'off', + image: 'vllm/vllm-openai:v0.10.2', + metrics: { median_ttft: 0.42, median_tpot: 0.018, tput_per_gpu: 128.4 }, + date: '2026-08-08', + run_url: 'https://github.com/semianalysis/inference-benchmarks/actions/runs/123456789', + }, +]; + +const availabilitySchema = arraySchema( + objectSchema({ + model: stringSchema, + isl: nullableNumberSchema, + osl: nullableNumberSchema, + precision: stringSchema, + hardware: stringSchema, + framework: stringSchema, + spec_method: stringSchema, + disagg: booleanSchema, + benchmark_type: stringSchema, + date: { type: 'string', format: 'date' }, + }), +); +const evaluationsSchema = arraySchema( + objectSchema({ + id: integerSchema, + config_id: integerSchema, + hardware: stringSchema, + framework: stringSchema, + model: stringSchema, + precision: stringSchema, + spec_method: stringSchema, + disagg: booleanSchema, + is_multinode: booleanSchema, + prefill_tp: integerSchema, + prefill_ep: integerSchema, + prefill_dp_attention: booleanSchema, + prefill_num_workers: integerSchema, + decode_tp: integerSchema, + decode_ep: integerSchema, + decode_dp_attention: booleanSchema, + decode_num_workers: integerSchema, + num_prefill_gpu: integerSchema, + num_decode_gpu: integerSchema, + task: stringSchema, + date: { type: 'string', format: 'date' }, + conc: nullableNumberSchema, + metrics: metricMapSchema, + timestamp: { type: 'string', format: 'date-time' }, + run_url: nullableStringSchema, + }), +); +const workflowInfoSchema = objectSchema({ + runs: arraySchema( + objectSchema({ + github_run_id: integerSchema, + name: stringSchema, + conclusion: nullableStringSchema, + run_attempt: integerSchema, + html_url: nullableStringSchema, + created_at: { type: 'string', format: 'date-time' }, + date: { type: 'string', format: 'date' }, + }), + ), + changelogs: arraySchema(anyObjectSchema), + configs: arraySchema(anyObjectSchema), + runConfigs: arraySchema(anyObjectSchema), +}); +const reliabilitySchema = arraySchema( + objectSchema({ + hardware: stringSchema, + date: { type: 'string', format: 'date' }, + n_success: integerSchema, + total: integerSchema, + }), +); +const tcoFeedSchema: ApiSchema = { + oneOf: [ + objectSchema({ + model: stringSchema, + db_model_keys: arraySchema(stringSchema), + date: { type: ['string', 'null'], format: 'date' }, + workloads: arraySchema(stringSchema), + tiers: arraySchema(numberSchema), + rows: arraySchema(anyObjectSchema), + }), + objectSchema({ + model: stringSchema, + db_model_keys: arraySchema(stringSchema), + date: { type: ['string', 'null'], format: 'date' }, + workloads: arraySchema(stringSchema), + tiers: arraySchema(numberSchema), + weights: arraySchema(numberSchema), + workload_weights: arraySchema(numberSchema), + alpha: numberSchema, + rows: arraySchema(anyObjectSchema), + }), + ], +}; +const submissionsSchema = objectSchema({ + summary: arraySchema( + objectSchema({ + model: stringSchema, + hardware: stringSchema, + framework: stringSchema, + precision: stringSchema, + spec_method: stringSchema, + disagg: booleanSchema, + is_multinode: booleanSchema, + num_prefill_gpu: integerSchema, + num_decode_gpu: integerSchema, + date: { type: 'string', format: 'date' }, + total_datapoints: integerSchema, + distinct_sequences: integerSchema, + distinct_concurrencies: integerSchema, + max_concurrency: integerSchema, + image: nullableStringSchema, + }), + ), + volume: arraySchema( + objectSchema({ + date: { type: 'string', format: 'date' }, + hardware: stringSchema, + datapoints: integerSchema, + }), + ), +}); +const latestImagesSchema = arraySchema( + objectSchema({ + model: stringSchema, + hardware: stringSchema, + framework: stringSchema, + precision: stringSchema, + spec_method: stringSchema, + disagg: booleanSchema, + isl: integerSchema, + osl: integerSchema, + image: stringSchema, + date: { type: 'string', format: 'date' }, + }), +); +const datasetRecordSchema = objectSchema({ + id: stringSchema, + slug: stringSchema, + label: stringSchema, + variant: stringSchema, + description: nullableStringSchema, + hf_url: nullableStringSchema, + license: nullableStringSchema, + conversation_count: integerSchema, + summary: anyObjectSchema, + ingested_at: { type: 'string', format: 'date-time' }, +}); +const conversationItemSchema = objectSchema({ + conv_id: stringSchema, + models: arraySchema(stringSchema), + num_turns: integerSchema, + num_subagent_groups: integerSchema, + total_in: integerSchema, + total_out: integerSchema, + total_cached: integerSchema, +}); +const collectiveXDatasetSchema = objectSchema( + { + version: integerSchema, + run: objectSchema({ + run_id: stringSchema, + run_attempt: integerSchema, + generated_at: { type: 'string', format: 'date-time' }, + conclusion: nullableStringSchema, + source_sha: stringSchema, + requested_cases: integerSchema, + terminal_cases: integerSchema, + measured_cases: integerSchema, + unsupported_cases: integerSchema, + failed_cases: integerSchema, + requested_points: integerSchema, + terminal_points: integerSchema, + measured_points: integerSchema, + covered_skus: arraySchema(stringSchema), + }), + coverage: arraySchema(anyObjectSchema), + series: arraySchema(anyObjectSchema), + }, + ['version', 'run', 'coverage', 'series'], +); +const collectiveRunSummarySchema = objectSchema({ + run_id: stringSchema, + run_attempt: integerSchema, + generated_at: { type: 'string', format: 'date-time' }, + conclusion: nullableStringSchema, + covered_skus: arraySchema(stringSchema), + requested_cases: integerSchema, + measured_cases: integerSchema, + requested_points: integerSchema, + terminal_points: integerSchema, + terminal_counts: objectSchema({ + measured: integerSchema, + unsupported: integerSchema, + failed: integerSchema, + }), +}); +const percentileSchema = objectSchema({ + mean: numberSchema, + p50: numberSchema, + p75: numberSchema, + p90: numberSchema, + p99: numberSchema, +}); +const nullablePercentileSchema: ApiSchema = { oneOf: [percentileSchema, { type: 'null' }] }; +const idListSchema: ApiSchema = { type: 'string', pattern: '^\\d+(,\\d+)*$' }; +const positiveIdSchema: ApiSchema = { type: 'integer', minimum: 1 }; + +export const apiDocumentationGroups: readonly ApiDocumentationGroup[] = [ + { + id: 'core', + title: text('Core benchmark data', '核心基准数据'), + description: text( + 'Benchmark results, availability, workflow provenance, evaluations, and reliability.', + '基准结果、可用配置、工作流来源、评测与可靠性数据。', + ), + }, + { + id: 'external', + title: text('External feeds', '外部数据源'), + description: text( + 'Stable feeds for spreadsheets, release tracking, submissions, and runtime images.', + '面向电子表格、版本跟踪、提交记录和运行镜像的稳定数据源。', + ), + }, + { + id: 'datasets', + title: text('Datasets', '数据集'), + description: text( + 'Dataset registry, metadata, conversation indexes, and conversation structures.', + '数据集目录、元数据、会话索引与会话结构。', + ), + }, + { + id: 'collectivex', + title: text('CollectiveX', 'CollectiveX'), + description: text( + 'Versioned collective communication sweep results and run discovery.', + '带版本的集合通信扫描结果与运行发现数据。', + ), + }, + { + id: 'diagnostics', + title: text('Diagnostic reads', '诊断读取'), + description: text( + 'Per-result trace, cache, request, sibling, and server metric diagnostics.', + '按结果提供跟踪、缓存、请求、同组结果和服务器指标诊断。', + ), + }, +]; + +export const apiOperations: readonly ApiOperation[] = [ + { + id: 'get-availability', + group: 'core', + method: 'GET', + path: '/api/v1/availability', + summary: text('List available benchmark configurations', '列出可用的基准配置'), + description: text( + 'Returns model, sequence, precision, hardware, framework, speculative method, benchmark type, and date combinations that have benchmark data.', + '返回已有基准数据的模型、序列、精度、硬件、框架、推测方法、基准类型和日期组合。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Available configuration rows.', '可用配置行。', availabilitySchema, [ + { + model: 'dsr1', + isl: 1024, + osl: 1024, + precision: 'fp8', + hardware: 'h200_sxm', + framework: 'vllm', + spec_method: 'none', + disagg: false, + benchmark_type: 'single_turn', + date: '2026-08-08', + }, + ]), + errorResponse( + '500', + 'The availability query failed.', + '可用配置查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'AvailabilityRows', + curlUrl: `${API_BASE_URL}/api/v1/availability`, + }, + { + id: 'list-benchmarks', + group: 'core', + method: 'GET', + path: '/api/v1/benchmarks', + summary: text('Read benchmark results', '读取基准结果'), + description: text( + 'Returns raw benchmark rows for a display model. Use date for an as-of snapshot, exact=true for that exact date, runId to constrain the latest lookup, or exactRun=true with a numeric runId to return only that workflow run. The page-owned calculator view is not part of this public contract.', + '按展示模型返回原始基准行。可用 date 获取截至该日的快照,exact=true 限定该日,runId 约束最新查询,或将 exactRun=true 与数字 runId 组合以仅返回该工作流运行。页面专用的计算器视图不属于此公开契约。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'model', + 'query', + true, + 'string', + 'Display model name.', + '展示模型名称。', + { type: 'string', enum: SUPPORTED_BENCHMARK_MODELS }, + 'DeepSeek-R1-0528', + ), + parameter( + 'date', + 'query', + false, + 'date', + 'Latest data on or before YYYY-MM-DD, unless exact is true.', + 'YYYY-MM-DD 当日或之前的最新数据,exact 为 true 时仅限当日。', + { type: 'string', format: 'date' }, + '2026-08-08', + ), + parameter( + 'exact', + 'query', + false, + 'boolean', + 'Set true to require the supplied date exactly.', + '设为 true 时严格匹配所给日期。', + { type: 'boolean', default: false }, + false, + ), + parameter( + 'runId', + 'query', + false, + 'integer', + 'Numeric GitHub Actions run ID. Non-numeric values are ignored.', + 'GitHub Actions 数字运行 ID。非数字值会被忽略。', + positiveIdSchema, + 123456789, + ), + parameter( + 'exactRun', + 'query', + false, + 'boolean', + 'With a numeric runId, return only that run instead of an as-of result.', + '与数字 runId 一起使用时,仅返回该次运行而非截至日期的结果。', + { type: 'boolean', default: false }, + false, + ), + ], + responses: [ + success( + 'Benchmark rows with scalar metrics in the metrics object.', + '基准行,标量指标位于 metrics 对象中。', + benchmarkRowsSchema, + benchmarkExample, + ), + errorResponse( + '400', + 'The model is missing or unsupported.', + '模型缺失或不受支持。', + 'Unknown model', + ), + errorResponse( + '500', + 'The benchmark query failed.', + '基准查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'BenchmarkRows', + curlUrl: `${API_BASE_URL}/api/v1/benchmarks?model=DeepSeek-R1-0528`, + }, + { + id: 'list-benchmark-history', + group: 'core', + method: 'GET', + path: '/api/v1/benchmarks/history', + summary: text('Read benchmark history', '读取基准历史'), + description: text( + 'Returns every dated benchmark row for one model and fixed input/output token pair.', + '返回某个模型和固定输入/输出 token 组合的全部历史基准行。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'model', + 'query', + true, + 'string', + 'Display model name.', + '展示模型名称。', + { type: 'string', enum: SUPPORTED_BENCHMARK_MODELS }, + 'DeepSeek-R1-0528', + ), + parameter( + 'isl', + 'query', + true, + 'integer', + 'Positive input sequence length in tokens.', + '正整数输入序列长度,单位为 token。', + positiveIdSchema, + 1024, + ), + parameter( + 'osl', + 'query', + true, + 'integer', + 'Positive output sequence length in tokens.', + '正整数输出序列长度,单位为 token。', + positiveIdSchema, + 1024, + ), + ], + responses: [ + success('Historical benchmark rows.', '历史基准行。', benchmarkRowsSchema, benchmarkExample), + errorResponse( + '400', + 'Required parameters are missing or the model is unsupported.', + '必填参数缺失或模型不受支持。', + 'Missing required parameters', + ), + errorResponse('500', 'The history query failed.', '历史查询失败。', 'Internal server error'), + ], + responseShapeName: 'BenchmarkRows', + curlUrl: `${API_BASE_URL}/api/v1/benchmarks/history?model=DeepSeek-R1-0528&isl=1024&osl=1024`, + }, + { + id: 'get-workflow-info', + group: 'core', + method: 'GET', + path: '/api/v1/workflow-info', + summary: text('Read workflow provenance', '读取工作流来源'), + description: text( + 'Returns workflow runs, changelogs, available configurations, and per-run configuration coverage. Omit date for all dates.', + '返回工作流运行、变更记录、可用配置以及每次运行的配置覆盖。省略 date 可读取全部日期。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'date', + 'query', + false, + 'date', + 'Optional YYYY-MM-DD filter.', + '可选的 YYYY-MM-DD 筛选条件。', + { type: 'string', format: 'date' }, + '2026-08-08', + ), + ], + responses: [ + success( + 'Workflow provenance grouped into four arrays.', + '按四个数组组织的工作流来源数据。', + workflowInfoSchema, + { + runs: [ + { + github_run_id: 123456789, + name: 'nightly-h200', + conclusion: 'success', + run_attempt: 1, + html_url: + 'https://github.com/semianalysis/inference-benchmarks/actions/runs/123456789', + created_at: '2026-08-08T03:00:00Z', + date: '2026-08-08', + }, + ], + changelogs: [], + configs: [], + runConfigs: [], + }, + ), + errorResponse( + '400', + 'date is not YYYY-MM-DD.', + 'date 不是 YYYY-MM-DD。', + 'Invalid date format', + ), + errorResponse( + '500', + 'The workflow query failed.', + '工作流查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'WorkflowInfo', + curlUrl: `${API_BASE_URL}/api/v1/workflow-info?date=2026-08-08`, + }, + { + id: 'list-evaluations', + group: 'core', + method: 'GET', + path: '/api/v1/evaluations', + summary: text('List evaluation aggregates', '列出评测汇总'), + description: text( + 'Returns latest-attempt evaluation results with configuration, task, provenance, and metric values.', + '返回最新尝试的评测结果,包含配置、任务、来源和指标值。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Evaluation result rows.', '评测结果行。', evaluationsSchema, [ + { + id: 72, + config_id: 11, + hardware: 'h200_sxm', + framework: 'vllm', + model: 'dsr1', + precision: 'fp8', + spec_method: 'none', + disagg: false, + is_multinode: false, + prefill_tp: 8, + prefill_ep: 1, + prefill_dp_attention: false, + prefill_num_workers: 1, + decode_tp: 8, + decode_ep: 1, + decode_dp_attention: false, + decode_num_workers: 1, + num_prefill_gpu: 0, + num_decode_gpu: 8, + task: 'gpqa', + date: '2026-08-08', + conc: null, + metrics: { accuracy: 0.78 }, + timestamp: '2026-08-08T03:00:00Z', + run_url: null, + }, + ]), + errorResponse( + '500', + 'The evaluation query failed.', + '评测查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'EvaluationRows', + curlUrl: `${API_BASE_URL}/api/v1/evaluations`, + }, + { + id: 'list-reliability', + group: 'core', + method: 'GET', + path: '/api/v1/reliability', + summary: text('List benchmark reliability', '列出基准可靠性'), + description: text( + 'Returns successful and total run counts by hardware and date.', + '按硬件和日期返回成功运行数与总运行数。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Reliability count rows.', '可靠性计数行。', reliabilitySchema, [ + { hardware: 'h200_sxm', date: '2026-08-08', n_success: 18, total: 20 }, + ]), + errorResponse( + '500', + 'The reliability query failed.', + '可靠性查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'ReliabilityRows', + curlUrl: `${API_BASE_URL}/api/v1/reliability`, + }, + { + id: 'get-tco-feed', + group: 'external', + method: 'GET', + path: '/api/v1/tco-feed', + summary: text('Compute a TCO feed', '计算 TCO 数据源'), + description: text( + 'Computes Pareto-frontier throughput points or weighted scores for spreadsheet TCO models. Every scoring assumption is encoded in the URL. CSV returns the same selected view as a flat table.', + '为电子表格 TCO 模型计算帕累托前沿吞吐点或加权分数。所有评分假设都编码在 URL 中。CSV 会将同一所选视图返回为平面表格。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'model', + 'query', + false, + 'string', + 'DB model key or display model name.', + '数据库模型键或展示模型名称。', + { type: 'string', enum: SUPPORTED_TCO_MODELS, default: 'dsv4' }, + 'dsv4', + ), + parameter( + 'workloads', + 'query', + false, + 'CSV workload list', + 'Comma-separated x token pairs.', + '以逗号分隔的 x token 组合。', + { type: 'string', default: '1024x1024,8192x1024', pattern: '^\\d+x\\d+(,\\d+x\\d+)*$' }, + '1024x1024,8192x1024', + ), + parameter( + 'tiers', + 'query', + false, + 'CSV number list', + 'Positive interactivity targets in output tokens per second per user.', + '正数交互性目标,单位为每用户每秒输出 token。', + { type: 'string', default: '30,50,75,100' }, + '30,50,75,100', + ), + parameter( + 'date', + 'query', + false, + 'date', + 'Use data on or before YYYY-MM-DD. Omit for latest.', + '使用 YYYY-MM-DD 当日或之前的数据。省略则使用最新数据。', + { type: 'string', format: 'date' }, + '2026-08-08', + ), + parameter( + 'format', + 'query', + false, + 'enum', + 'Response encoding.', + '响应编码。', + { type: 'string', enum: ['json', 'csv'], default: 'json' }, + 'json', + ), + parameter( + 'view', + 'query', + false, + 'enum', + 'points returns one row per hardware, workload, and tier. scores returns one row per hardware.', + 'points 为每个硬件、负载和档位返回一行。scores 为每个硬件返回一行。', + { type: 'string', enum: ['points', 'scores'], default: 'points' }, + 'points', + ), + parameter( + 'weights', + 'query', + false, + 'CSV number list', + 'scores only. One non-negative weight per tier, normalized to sum to 1.', + '仅用于 scores。每个档位一个非负权重,并归一化为总和 1。', + { type: 'string', default: '0.35,0.4,0.2,0.05' }, + '0.35,0.4,0.2,0.05', + ), + parameter( + 'workload_weights', + 'query', + false, + 'CSV number list', + 'scores only. One non-negative weight per workload, normalized to sum to 1. Defaults to equal weights.', + '仅用于 scores。每个负载一个非负权重,并归一化为总和 1。默认等权。', + { type: 'string' }, + '0.5,0.5', + ), + parameter( + 'alpha', + 'query', + false, + 'number', + 'scores only. Input-token value ratio in [0, 10].', + '仅用于 scores。输入 token 价值比,范围为 [0, 10]。', + { type: 'number', minimum: 0, maximum: 10, default: 0.25 }, + 0.25, + ), + ], + responses: [ + success( + 'The selected points or scores envelope.', + '所选 points 或 scores 数据包。', + tcoFeedSchema, + { + model: 'dsv4', + db_model_keys: ['dsv4'], + date: null, + workloads: ['1024x1024'], + tiers: [50], + rows: [ + { + hardware: 'h200_sxm', + workload: '1024x1024', + tier: 50, + tput_per_gpu: 118.2, + is_interpolated: true, + }, + ], + }, + [ + { + mediaType: 'text/csv', + schema: stringSchema, + example: 'model,hardware,workload,tier,tput_per_gpu\ndsv4,h200_sxm,1024x1024,50,118.2', + }, + ], + ), + errorResponse( + '400', + 'A model, date, view, format, workload, tier, weight, or alpha value is invalid.', + '模型、日期、视图、格式、负载、档位、权重或 alpha 值无效。', + 'Invalid tiers: expected comma-separated positive numbers', + ), + errorResponse( + '500', + 'The TCO calculation failed.', + 'TCO 计算失败。', + 'Internal server error', + ), + ], + responseShapeName: 'TcoFeed', + curlUrl: `${API_BASE_URL}/api/v1/tco-feed?model=dsv4&workloads=1024x1024,8192x1024&tiers=30,50,75,100&view=points&format=json`, + }, + { + id: 'get-submissions', + group: 'external', + method: 'GET', + path: '/api/v1/submissions', + summary: text('Read submission coverage', '读取提交覆盖'), + description: text( + 'Returns configuration-level submission summaries and daily hardware submission volume.', + '返回配置级提交汇总和每日硬件提交量。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Submission summary and volume arrays.', '提交汇总和数量数组。', submissionsSchema, { + summary: [ + { + model: 'dsr1', + hardware: 'h200_sxm', + framework: 'vllm', + precision: 'fp8', + spec_method: 'none', + disagg: false, + is_multinode: false, + num_prefill_gpu: 0, + num_decode_gpu: 8, + date: '2026-08-08', + total_datapoints: 24, + distinct_sequences: 3, + distinct_concurrencies: 8, + max_concurrency: 256, + image: 'vllm/vllm-openai:v0.10.2', + }, + ], + volume: [{ date: '2026-08-08', hardware: 'h200_sxm', datapoints: 24 }], + }), + errorResponse( + '500', + 'The submissions query failed.', + '提交查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'Submissions', + curlUrl: `${API_BASE_URL}/api/v1/submissions`, + }, + { + id: 'get-framework-releases', + group: 'external', + method: 'GET', + path: '/api/v1/framework-releases', + summary: text('Read latest framework releases', '读取最新框架版本'), + description: text( + 'Returns the latest non-draft, non-prerelease GitHub release tag for vLLM and SGLang. A null value means the upstream lookup had no usable release.', + '返回 vLLM 和 SGLang 最新的非草稿、非预发布 GitHub 版本标签。null 表示上游查询没有可用版本。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success( + 'Framework keys mapped to release tags or null.', + '框架键映射到版本标签或 null。', + mapSchema(nullableStringSchema), + { vllm: 'v0.10.2', sglang: 'v0.4.10' }, + ), + errorResponse('500', 'The release lookup failed.', '版本查询失败。', 'Internal server error'), + ], + responseShapeName: 'FrameworkReleases', + curlUrl: `${API_BASE_URL}/api/v1/framework-releases`, + }, + { + id: 'get-latest-images', + group: 'external', + method: 'GET', + path: '/api/v1/latest-images', + summary: text('Read latest runtime images', '读取最新运行镜像'), + description: text( + 'Returns the latest container image observed for each benchmark configuration and sequence.', + '返回每个基准配置和序列最近观测到的容器镜像。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Latest image rows.', '最新镜像行。', latestImagesSchema, [ + { + model: 'dsr1', + hardware: 'h200_sxm', + framework: 'vllm', + precision: 'fp8', + spec_method: 'none', + disagg: false, + isl: 1024, + osl: 1024, + image: 'vllm/vllm-openai:v0.10.2', + date: '2026-08-08', + }, + ]), + errorResponse('500', 'The image query failed.', '镜像查询失败。', 'Internal server error'), + ], + responseShapeName: 'LatestImageRows', + curlUrl: `${API_BASE_URL}/api/v1/latest-images`, + }, + { + id: 'list-datasets', + group: 'datasets', + method: 'GET', + path: '/api/v1/datasets', + summary: text('List ingested datasets', '列出已导入的数据集'), + description: text( + 'Returns dataset registry cards without the large chart_data field.', + '返回数据集目录卡片,不包含较大的 chart_data 字段。', + ), + audience: 'public', + stability: 'stable', + parameters: [], + responses: [ + success('Dataset registry records.', '数据集目录记录。', arraySchema(datasetRecordSchema), [ + { + id: 'ds_01', + slug: 'cc-traces-weka', + label: 'CC Traces Weka', + variant: 'default', + description: 'Agentic coding traces', + hf_url: 'https://huggingface.co/datasets/example/cc-traces-weka', + license: 'Apache-2.0', + conversation_count: 1200, + summary: { totalIn: 8200000, totalOut: 1700000 }, + ingested_at: '2026-08-08T03:00:00Z', + }, + ]), + errorResponse( + '500', + 'The dataset registry query failed.', + '数据集目录查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'DatasetRecords', + curlUrl: `${API_BASE_URL}/api/v1/datasets`, + }, + { + id: 'get-dataset', + group: 'datasets', + method: 'GET', + path: '/api/v1/datasets/{slug}', + summary: text('Read dataset details', '读取数据集详情'), + description: text( + 'Returns one dataset registry record plus its precomputed chart_data distributions.', + '返回一条数据集目录记录及其预计算的 chart_data 分布。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'slug', + 'path', + true, + 'string', + 'Dataset slug from the registry.', + '目录中的数据集 slug。', + { type: 'string', minLength: 1 }, + 'cc-traces-weka', + ), + ], + responses: [ + success( + 'Dataset metadata with chart_data.', + '包含 chart_data 的数据集元数据。', + objectSchema({ ...datasetRecordSchema.properties, chart_data: anyObjectSchema }), + { + id: 'ds_01', + slug: 'cc-traces-weka', + label: 'CC Traces Weka', + variant: 'default', + description: 'Agentic coding traces', + hf_url: null, + license: 'Apache-2.0', + conversation_count: 1200, + summary: {}, + ingested_at: '2026-08-08T03:00:00Z', + chart_data: { tokens: { bins: [0, 1000, 2000], counts: [140, 320] } }, + }, + ), + errorResponse('404', 'No dataset has this slug.', '没有使用此 slug 的数据集。', 'Not found'), + errorResponse( + '500', + 'The dataset query failed.', + '数据集查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'DatasetDetail', + curlUrl: `${API_BASE_URL}/api/v1/datasets/cc-traces-weka`, + }, + { + id: 'list-dataset-conversations', + group: 'datasets', + method: 'GET', + path: '/api/v1/datasets/{slug}/conversations', + summary: text('List dataset conversations', '列出数据集会话'), + description: text( + 'Returns a searchable, sorted, paginated conversation index. It contains counts only, not the full conversation structure.', + '返回可搜索、排序和分页的会话索引。只包含计数,不包含完整会话结构。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'slug', + 'path', + true, + 'string', + 'Dataset slug from the registry.', + '目录中的数据集 slug。', + { type: 'string', minLength: 1 }, + 'cc-traces-weka', + ), + parameter( + 'search', + 'query', + false, + 'string', + 'Trimmed conversation ID search, at most 100 characters.', + '按会话 ID 搜索,会先去除首尾空格,最多 100 个字符。', + { type: 'string', maxLength: 100 }, + 'trace-018', + ), + parameter( + 'limit', + 'query', + false, + 'integer', + 'Page size, clamped to 1 through 200.', + '每页数量,限制在 1 到 200。', + { type: 'integer', minimum: 1, maximum: 200, default: 50 }, + 50, + ), + parameter( + 'offset', + 'query', + false, + 'integer', + 'Zero-based row offset. Negative values become 0.', + '从 0 开始的行偏移。负数会变为 0。', + { type: 'integer', minimum: 0, default: 0 }, + 0, + ), + parameter( + 'sort', + 'query', + false, + 'enum', + 'Sort by tokens, turns, subagents, or id. Unknown values fall back to tokens.', + '按 tokens、turns、subagents 或 id 排序。未知值回退到 tokens。', + { type: 'string', enum: ['tokens', 'turns', 'subagents', 'id'], default: 'tokens' }, + 'tokens', + ), + ], + responses: [ + success( + 'Total count and conversation index items.', + '总数和会话索引项。', + objectSchema({ total: integerSchema, items: arraySchema(conversationItemSchema) }), + { + total: 1200, + items: [ + { + conv_id: 'trace-018', + models: ['claude-sonnet-4'], + num_turns: 42, + num_subagent_groups: 3, + total_in: 18200, + total_out: 4200, + total_cached: 9600, + }, + ], + }, + ), + errorResponse( + '400', + 'search exceeds 100 characters.', + 'search 超过 100 个字符。', + 'search too long', + ), + errorResponse('404', 'No dataset has this slug.', '没有使用此 slug 的数据集。', 'Not found'), + errorResponse( + '500', + 'The conversation query failed.', + '会话查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'ConversationList', + curlUrl: `${API_BASE_URL}/api/v1/datasets/cc-traces-weka/conversations?limit=50&offset=0&sort=tokens`, + }, + { + id: 'get-dataset-conversation', + group: 'datasets', + method: 'GET', + path: '/api/v1/datasets/{slug}/conversations/{convId}', + summary: text('Read a conversation structure', '读取会话结构'), + description: text( + 'Returns one conversation and its flamegraph-ready nested structure. App Router decodes each path value once.', + '返回单个会话及可用于火焰图的嵌套结构。App Router 对每个路径值解码一次。', + ), + audience: 'public', + stability: 'stable', + parameters: [ + parameter( + 'slug', + 'path', + true, + 'string', + 'Dataset slug from the registry.', + '目录中的数据集 slug。', + { type: 'string', minLength: 1 }, + 'cc-traces-weka', + ), + parameter( + 'convId', + 'path', + true, + 'string', + 'Conversation ID exactly as listed by the conversation index.', + '会话索引中列出的原始会话 ID。', + { type: 'string', minLength: 1 }, + 'trace-018', + ), + ], + responses: [ + success( + 'Conversation counts and nested structure.', + '会话计数和嵌套结构。', + objectSchema({ ...conversationItemSchema.properties, structure: anyObjectSchema }), + { + conv_id: 'trace-018', + models: ['claude-sonnet-4'], + num_turns: 42, + num_subagent_groups: 3, + total_in: 18200, + total_out: 4200, + total_cached: 9600, + structure: { name: 'trace-018', children: [] }, + }, + ), + errorResponse( + '404', + 'The dataset or conversation does not exist.', + '数据集或会话不存在。', + 'Not found', + ), + errorResponse( + '500', + 'The conversation query failed.', + '会话查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'ConversationDetail', + curlUrl: `${API_BASE_URL}/api/v1/datasets/cc-traces-weka/conversations/trace-018`, + }, + { + id: 'get-collectivex-latest', + group: 'collectivex', + method: 'GET', + path: '/api/v1/collectivex/latest', + summary: text('Read the latest CollectiveX dataset', '读取最新 CollectiveX 数据集'), + description: text( + 'Discovers and ingests the latest sweep when needed, then returns its versioned neutral dataset. A stored run is served if refresh fails.', + '按需发现并导入最新扫描,然后返回带版本的中立数据集。若刷新失败,会返回已存储的运行。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'version', + 'query', + true, + 'enum', + 'CollectiveX contract version.', + 'CollectiveX 契约版本。', + { type: 'integer', enum: [...COLLECTIVEX_VERSIONS] }, + COLLECTIVEX_VERSIONS.at(-1) ?? 1, + ), + ], + responses: [ + success( + 'Latest CollectiveX run, coverage, series, and optional KV cases.', + '最新 CollectiveX 运行、覆盖、序列和可选 KV 案例。', + collectiveXDatasetSchema, + { + version: 1, + run: { + run_id: '123456789', + run_attempt: 1, + generated_at: '2026-08-08T03:00:00Z', + conclusion: 'success', + source_sha: '0123456789abcdef', + requested_cases: 12, + terminal_cases: 12, + measured_cases: 10, + unsupported_cases: 2, + failed_cases: 0, + requested_points: 48, + terminal_points: 48, + measured_points: 40, + covered_skus: ['h200_sxm'], + }, + coverage: [], + series: [], + }, + ), + errorResponse( + '400', + 'version is missing or unsupported.', + 'version 缺失或不受支持。', + 'Unknown version', + ), + errorResponse( + '404', + 'No stored or discoverable run exists.', + '没有已存储或可发现的运行。', + 'Not found', + ), + errorResponse( + '502', + 'Upstream sweep discovery is unavailable and no stored fallback exists.', + '上游扫描发现不可用,且没有已存储的回退数据。', + 'Unavailable', + ), + errorResponse( + '503', + 'Upstream sweep processing is temporarily unavailable.', + '上游扫描处理暂时不可用。', + 'Unavailable', + ), + errorResponse( + '500', + 'The stored run query failed.', + '已存储运行查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'CollectiveXDataset', + curlUrl: `${API_BASE_URL}/api/v1/collectivex/latest?version=1`, + }, + { + id: 'list-collectivex-runs', + group: 'collectivex', + method: 'GET', + path: '/api/v1/collectivex/runs', + summary: text('List CollectiveX runs', '列出 CollectiveX 运行'), + description: text( + 'Returns progressively discovered run summaries. discovery_complete=false means clients may poll while older runs are still being discovered.', + '返回逐步发现的运行汇总。discovery_complete=false 表示仍在发现更早的运行,客户端可以轮询。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'version', + 'query', + true, + 'enum', + 'CollectiveX contract version.', + 'CollectiveX 契约版本。', + { type: 'integer', enum: [...COLLECTIVEX_VERSIONS] }, + COLLECTIVEX_VERSIONS.at(-1) ?? 1, + ), + ], + responses: [ + success( + 'Version, run summaries, and discovery state.', + '版本、运行汇总和发现状态。', + objectSchema({ + version: integerSchema, + runs: arraySchema(collectiveRunSummarySchema), + discovery_complete: booleanSchema, + }), + { + version: 1, + runs: [ + { + run_id: '123456789', + run_attempt: 1, + generated_at: '2026-08-08T03:00:00Z', + conclusion: 'success', + covered_skus: ['h200_sxm'], + requested_cases: 12, + measured_cases: 10, + requested_points: 48, + terminal_points: 48, + terminal_counts: { measured: 40, unsupported: 8, failed: 0 }, + }, + ], + discovery_complete: true, + }, + ), + errorResponse( + '400', + 'version is missing or unsupported.', + 'version 缺失或不受支持。', + 'Unknown version', + ), + errorResponse( + '502', + 'Discovery failed and no stored run list exists.', + '发现失败,且没有已存储的运行列表。', + 'Unavailable', + ), + errorResponse( + '503', + 'Discovery is temporarily unavailable.', + '发现暂时不可用。', + 'Unavailable', + ), + errorResponse( + '500', + 'The stored run list query failed.', + '已存储运行列表查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'CollectiveXRunList', + curlUrl: `${API_BASE_URL}/api/v1/collectivex/runs?version=1`, + }, + { + id: 'get-collectivex-run', + group: 'collectivex', + method: 'GET', + path: '/api/v1/collectivex/runs/{runId}', + summary: text('Read a CollectiveX run', '读取 CollectiveX 运行'), + description: text( + 'Returns one positive numeric run ID as a versioned CollectiveX dataset, discovering and ingesting it on demand when possible.', + '按正整数运行 ID 返回带版本的 CollectiveX 数据集,并在可能时按需发现和导入。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'runId', + 'path', + true, + 'integer', + 'Positive GitHub Actions run ID.', + 'GitHub Actions 正整数运行 ID。', + positiveIdSchema, + 123456789, + ), + parameter( + 'version', + 'query', + true, + 'enum', + 'CollectiveX contract version.', + 'CollectiveX 契约版本。', + { type: 'integer', enum: [...COLLECTIVEX_VERSIONS] }, + COLLECTIVEX_VERSIONS.at(-1) ?? 1, + ), + ], + responses: [ + success( + 'The requested CollectiveX dataset.', + '请求的 CollectiveX 数据集。', + collectiveXDatasetSchema, + { + version: 1, + run: { + run_id: '123456789', + run_attempt: 1, + generated_at: '2026-08-08T03:00:00Z', + conclusion: 'success', + source_sha: '0123456789abcdef', + requested_cases: 12, + terminal_cases: 12, + measured_cases: 10, + unsupported_cases: 2, + failed_cases: 0, + requested_points: 48, + terminal_points: 48, + measured_points: 40, + covered_skus: ['h200_sxm'], + }, + coverage: [], + series: [], + }, + ), + errorResponse( + '400', + 'version or runId is invalid.', + 'version 或 runId 无效。', + 'Unknown version or run id', + ), + errorResponse('404', 'The run does not exist.', '该运行不存在。', 'Not found'), + errorResponse( + '502', + 'The run cannot be fetched from the upstream source.', + '无法从上游来源获取该运行。', + 'Unavailable', + ), + errorResponse( + '503', + 'Upstream processing is temporarily unavailable.', + '上游处理暂时不可用。', + 'Unavailable', + ), + errorResponse('500', 'The run query failed.', '运行查询失败。', 'Internal server error'), + ], + responseShapeName: 'CollectiveXDataset', + curlUrl: `${API_BASE_URL}/api/v1/collectivex/runs/123456789?version=1`, + }, + { + id: 'get-agentic-aggregates', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/agentic-aggregates', + summary: text('Read agentic aggregate percentiles', '读取智能体汇总百分位'), + description: text( + 'Returns ISL, OSL, KV-cache utilization, and prefix-cache hit-rate percentiles keyed by benchmark result ID. IDs are deduplicated and at most 200 are accepted.', + '按基准结果 ID 返回 ISL、OSL、KV 缓存利用率和前缀缓存命中率百分位。ID 会去重,最多接受 200 个。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'ids', + 'query', + true, + 'comma-separated integers', + 'One to 200 positive benchmark result IDs.', + '1 到 200 个正整数基准结果 ID。', + idListSchema, + '421,422', + ), + ], + responses: [ + success( + 'Result IDs mapped to aggregate percentiles or null metric groups.', + '结果 ID 映射到汇总百分位或 null 指标组。', + mapSchema( + objectSchema({ + id: integerSchema, + isl: nullablePercentileSchema, + osl: nullablePercentileSchema, + kvCacheUtil: nullablePercentileSchema, + prefixCacheHitRate: nullablePercentileSchema, + }), + ), + { + '421': { + id: 421, + isl: { mean: 18320, p50: 16440, p75: 20110, p90: 24880, p99: 31900 }, + osl: null, + kvCacheUtil: null, + prefixCacheHitRate: null, + }, + }, + ), + errorResponse( + '400', + 'ids is missing, malformed, or exceeds 200 unique IDs.', + 'ids 缺失、格式错误或超过 200 个唯一 ID。', + 'Expected ids as comma-separated positive integers', + ), + errorResponse( + '500', + 'The aggregate query failed.', + '汇总查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'AgenticAggregateMap', + curlUrl: `${API_BASE_URL}/api/v1/agentic-aggregates?ids=421,422`, + }, + { + id: 'get-benchmark-siblings', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/benchmark-siblings', + summary: text('Read sibling benchmark points', '读取同组基准点'), + description: text( + 'Returns the benchmark SKU and every point in the same hardware, framework, model, precision, method, benchmark type, and workflow run.', + '返回基准 SKU,以及同一硬件、框架、模型、精度、方法、基准类型和工作流运行中的全部点。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'id', + 'query', + true, + 'integer', + 'Positive benchmark result ID.', + '正整数基准结果 ID。', + positiveIdSchema, + 421, + ), + ], + responses: [ + success( + 'SKU metadata and sibling navigation rows.', + 'SKU 元数据和同组导航行。', + objectSchema({ sku: anyObjectSchema, siblings: arraySchema(anyObjectSchema) }), + { + sku: { + hardware: 'h200_sxm', + framework: 'vllm', + model: 'dsr1', + precision: 'fp8', + spec_method: 'none', + benchmark_type: 'agentic_traces', + github_run_id: 123456789, + date: '2026-08-08', + dataset_slug: 'cc-traces-weka', + }, + siblings: [ + { + id: 421, + conc: 32, + offload_mode: 'off', + decode_tp: 8, + decode_ep: 1, + decode_pp: null, + decode_dp_attention: false, + decode_num_workers: 1, + prefill_tp: 8, + prefill_ep: 1, + prefill_pp: null, + prefill_dp_attention: false, + prefill_num_workers: 1, + num_prefill_gpu: 0, + num_decode_gpu: 8, + disagg: false, + is_multinode: false, + tput_per_gpu: 128.4, + total_requests: 320, + is_current: true, + has_trace: true, + }, + ], + }, + ), + errorResponse( + '400', + 'id is missing or invalid.', + 'id 缺失或无效。', + 'Expected a positive numeric id', + ), + errorResponse( + '404', + 'No benchmark result has this ID.', + '没有使用此 ID 的基准结果。', + 'Not found', + ), + errorResponse('500', 'The sibling query failed.', '同组查询失败。', 'Internal server error'), + ], + responseShapeName: 'BenchmarkSiblings', + curlUrl: `${API_BASE_URL}/api/v1/benchmark-siblings?id=421`, + }, + { + id: 'get-derived-agentic-metrics', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/derived-agentic-metrics', + summary: text('Read derived agentic metrics', '读取派生智能体指标'), + description: text( + 'Returns normalized interactivity percentiles keyed by benchmark result ID. IDs are deduplicated and at most 200 are accepted.', + '按基准结果 ID 返回归一化交互性百分位。ID 会去重,最多接受 200 个。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'ids', + 'query', + true, + 'comma-separated integers', + 'One to 200 positive benchmark result IDs.', + '1 到 200 个正整数基准结果 ID。', + idListSchema, + '421,422', + ), + ], + responses: [ + success( + 'Result IDs mapped to p75 and p90 normalized interactivity.', + '结果 ID 映射到 p75 和 p90 归一化交互性。', + mapSchema( + objectSchema({ + id: integerSchema, + p75_e2e_norm_intvty: nullableNumberSchema, + p90_e2e_norm_intvty: nullableNumberSchema, + }), + ), + { '421': { id: 421, p75_e2e_norm_intvty: 31.2, p90_e2e_norm_intvty: 24.8 } }, + ), + errorResponse( + '400', + 'ids is missing, malformed, or exceeds 200 unique IDs.', + 'ids 缺失、格式错误或超过 200 个唯一 ID。', + 'Expected ids as comma-separated positive integers', + ), + errorResponse( + '500', + 'The derived metric query failed.', + '派生指标查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'DerivedAgenticMetricMap', + curlUrl: `${API_BASE_URL}/api/v1/derived-agentic-metrics?ids=421,422`, + }, + { + id: 'get-request-timeline', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/request-timeline', + summary: text('Read a request timeline', '读取请求时间线'), + description: text( + 'Returns a versioned benchmark window and per-request dispatch, acknowledgement, completion, token, phase, worker, and cancellation timing.', + '返回带版本的基准窗口,以及每个请求的调度、确认、完成、token、阶段、工作进程和取消时间。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'id', + 'query', + true, + 'integer', + 'Positive benchmark result ID.', + '正整数基准结果 ID。', + positiveIdSchema, + 421, + ), + ], + responses: [ + success( + 'Timeline metadata and request records. Nanosecond event fields are offsets from startNs.', + '时间线元数据和请求记录。纳秒事件字段是相对 startNs 的偏移。', + objectSchema({ + version: integerSchema, + startNs: integerSchema, + endNs: integerSchema, + durationS: numberSchema, + requests: arraySchema( + objectSchema({ + cid: stringSchema, + ti: integerSchema, + wid: stringSchema, + ad: integerSchema, + phase: stringSchema, + credit: integerSchema, + start: integerSchema, + ack: nullableNumberSchema, + end: integerSchema, + ttftMs: nullableNumberSchema, + tpotMs: nullableNumberSchema, + isl: nullableNumberSchema, + osl: nullableNumberSchema, + cancelled: booleanSchema, + }), + ), + }), + { + version: 5, + startNs: 1000000000, + endNs: 2400000000, + durationS: 1.4, + requests: [ + { + cid: 'trace-018', + ti: 0, + wid: '7', + ad: 0, + phase: 'profiling', + credit: 0, + start: 1200000, + ack: 1800000, + end: 420000000, + ttftMs: 42.3, + tpotMs: 18.1, + isl: 18320, + osl: 410, + cancelled: false, + }, + ], + }, + ), + errorResponse( + '400', + 'id is missing or invalid.', + 'id 缺失或无效。', + 'Expected a positive numeric id', + ), + errorResponse( + '404', + 'No timeline exists for this result.', + '该结果没有时间线。', + 'Not found', + ), + errorResponse( + '500', + 'The timeline query failed.', + '时间线查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'RequestTimeline', + curlUrl: `${API_BASE_URL}/api/v1/request-timeline?id=421`, + }, + { + id: 'get-server-log', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/server-log', + summary: text('Read a benchmark server log', '读取基准服务器日志'), + description: text( + 'Returns the stored plain-text server log for one benchmark result ID.', + '返回某个基准结果 ID 已存储的纯文本服务器日志。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'id', + 'query', + true, + 'integer', + 'Positive benchmark result ID.', + '正整数基准结果 ID。', + positiveIdSchema, + 421, + ), + ], + responses: [ + success( + 'Benchmark result ID and server log text.', + '基准结果 ID 和服务器日志文本。', + objectSchema({ id: integerSchema, serverLog: stringSchema }), + { id: 421, serverLog: 'INFO engine initialized\nINFO benchmark complete' }, + ), + errorResponse('400', 'id is missing or invalid.', 'id 缺失或无效。', 'Invalid id'), + errorResponse( + '404', + 'No server log exists for this result.', + '该结果没有服务器日志。', + 'Not found', + ), + errorResponse( + '500', + 'The server log query failed.', + '服务器日志查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'ServerLog', + curlUrl: `${API_BASE_URL}/api/v1/server-log?id=421`, + }, + { + id: 'get-trace-availability', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/trace-availability', + summary: text('Check trace availability', '检查跟踪可用性'), + description: text( + 'Returns only benchmark result IDs that have a stored trace. IDs are deduplicated and at most 500 are accepted.', + '仅返回具有已存储跟踪的基准结果 ID。ID 会去重,最多接受 500 个。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'ids', + 'query', + true, + 'comma-separated integers', + 'One to 500 positive benchmark result IDs.', + '1 到 500 个正整数基准结果 ID。', + idListSchema, + '421,422', + ), + ], + responses: [ + success( + 'Available result IDs mapped to true. Missing keys have no trace.', + '可用结果 ID 映射为 true。缺失的键表示没有跟踪。', + mapSchema(booleanSchema), + { '421': true }, + ), + errorResponse( + '400', + 'ids is missing, malformed, or exceeds 500 unique IDs.', + 'ids 缺失、格式错误或超过 500 个唯一 ID。', + 'Expected ids as comma-separated positive integers', + ), + errorResponse( + '500', + 'The trace availability query failed.', + '跟踪可用性查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'TraceAvailabilityMap', + curlUrl: `${API_BASE_URL}/api/v1/trace-availability?ids=421,422`, + }, + { + id: 'get-trace-histograms', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/trace-histograms', + summary: text('Read trace histograms', '读取跟踪直方图'), + description: text( + 'Returns input and output token count arrays for each benchmark result ID. IDs are deduplicated and at most 200 are accepted.', + '按基准结果 ID 返回输入和输出 token 计数数组。ID 会去重,最多接受 200 个。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'ids', + 'query', + true, + 'comma-separated integers', + 'One to 200 positive benchmark result IDs.', + '1 到 200 个正整数基准结果 ID。', + idListSchema, + '421,422', + ), + ], + responses: [ + success( + 'Result IDs mapped to raw ISL and OSL samples.', + '结果 ID 映射到原始 ISL 和 OSL 样本。', + mapSchema( + objectSchema({ + id: integerSchema, + isl: arraySchema(numberSchema), + osl: arraySchema(numberSchema), + }), + ), + { '421': { id: 421, isl: [18220, 19340, 15110], osl: [410, 380, 512] } }, + ), + errorResponse( + '400', + 'ids is missing, malformed, or exceeds 200 unique IDs.', + 'ids 缺失、格式错误或超过 200 个唯一 ID。', + 'Expected ids as comma-separated positive integers', + ), + errorResponse( + '500', + 'The histogram query failed.', + '直方图查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'TraceHistogramMap', + curlUrl: `${API_BASE_URL}/api/v1/trace-histograms?ids=421,422`, + }, + { + id: 'get-trace-server-metrics', + group: 'diagnostics', + method: 'GET', + path: '/api/v1/trace-server-metrics', + summary: text('Read trace server metrics', '读取跟踪服务器指标'), + description: text( + 'Returns point metadata and chart-ready time series for cache usage, queue depth, prefill and decode throughput, prompt-token sources, and metric sources.', + '返回点元数据,以及缓存使用率、队列深度、预填充和解码吞吐、提示 token 来源与指标来源的图表时间序列。', + ), + audience: 'public', + stability: 'beta', + parameters: [ + parameter( + 'id', + 'query', + true, + 'integer', + 'Positive benchmark result ID.', + '正整数基准结果 ID。', + positiveIdSchema, + 421, + ), + ], + responses: [ + success( + 'Point metadata, window bounds, and server metric series.', + '点元数据、窗口边界和服务器指标序列。', + objectSchema({ + meta: anyObjectSchema, + startNs: integerSchema, + endNs: integerSchema, + durationS: numberSchema, + timeslicesCount: integerSchema, + kvCacheUsage: arraySchema(anyObjectSchema), + prefixCacheHitRate: arraySchema(anyObjectSchema), + queueDepth: arraySchema(anyObjectSchema), + promptTokensBySource: mapSchema(arraySchema(anyObjectSchema)), + prefillTps: arraySchema(anyObjectSchema), + decodeTps: arraySchema(anyObjectSchema), + prefixCacheHitsTps: arraySchema(anyObjectSchema), + hostKvCacheUsage: arraySchema(anyObjectSchema), + kvCacheUsageByEngine: arraySchema(anyObjectSchema), + kvCachePoolTokens: nullableNumberSchema, + metricSources: arraySchema(anyObjectSchema), + }), + { + meta: { + id: 421, + hardware: 'h200_sxm', + framework: 'vllm', + model: 'dsr1', + conc: 32, + date: '2026-08-08', + }, + startNs: 1000000000, + endNs: 2400000000, + durationS: 1.4, + timeslicesCount: 2, + kvCacheUsage: [{ t: 0, v: 0.44 }], + prefixCacheHitRate: [], + queueDepth: [], + promptTokensBySource: {}, + prefillTps: [], + decodeTps: [], + prefixCacheHitsTps: [], + hostKvCacheUsage: [], + kvCacheUsageByEngine: [], + kvCachePoolTokens: 983040, + metricSources: [], + }, + ), + errorResponse( + '400', + 'id is missing or invalid.', + 'id 缺失或无效。', + 'Expected a positive numeric id', + ), + errorResponse( + '404', + 'No server metrics exist for this result.', + '该结果没有服务器指标。', + 'Not found', + ), + errorResponse( + '500', + 'The server metric query failed.', + '服务器指标查询失败。', + 'Internal server error', + ), + ], + responseShapeName: 'TraceServerMetrics', + curlUrl: `${API_BASE_URL}/api/v1/trace-server-metrics?id=421`, + }, +]; + +const overview = { + title: text('InferenceX API reference', 'InferenceX API 参考文档'), + eyebrow: text('Public data API', '公开数据 API'), + description: text( + 'Read benchmark, provenance, dataset, CollectiveX, and diagnostic data from the same sources that power InferenceX.', + '读取为 InferenceX 提供数据的基准、来源、数据集、CollectiveX 和诊断信息。', + ), + auth: { + title: text('Authentication', '身份验证'), + description: text( + 'Published read endpoints do not require authentication.', + '已发布的只读端点不需要身份验证。', + ), + }, + format: { + title: text('Response format', '响应格式'), + description: text( + 'Responses are JSON unless an endpoint explicitly documents CSV. Dates use YYYY-MM-DD and timestamps use UTC ISO 8601.', + '除非端点明确说明 CSV,否则响应均为 JSON。日期使用 YYYY-MM-DD,时间戳使用 UTC ISO 8601。', + ), + }, + conventions: [ + { + id: 'errors', + title: text('Errors', '错误'), + description: text( + 'JSON errors contain an error string. A 400 response means a parameter is missing or invalid, 404 means the requested record is absent, and 500 means the server query failed.', + 'JSON 错误包含 error 字符串。400 表示参数缺失或无效,404 表示请求的记录不存在,500 表示服务器查询失败。', + ), + }, + { + id: 'cache', + title: text('Caching', '缓存'), + description: text( + 'Read endpoints may be served from shared caches. CollectiveX uses short refresh windows, and framework releases use a one-hour shared cache.', + '只读端点可能由共享缓存提供。CollectiveX 使用较短的刷新窗口,框架版本使用一小时共享缓存。', + ), + }, + { + id: 'identifiers', + title: text('Identifiers', '标识符'), + description: text( + 'Benchmark result IDs and GitHub run IDs are positive integers. Bulk diagnostic endpoints accept comma-separated, deduplicated IDs.', + '基准结果 ID 和 GitHub 运行 ID 为正整数。批量诊断端点接受以逗号分隔并去重的 ID。', + ), + }, + ], + schemaNotes: [ + { + id: 'benchmark-row', + title: text('BenchmarkRow', 'BenchmarkRow'), + description: text( + 'Configuration fields sit beside a metrics map. Metric keys evolve independently; values are numbers, time metrics are seconds, and throughput metrics use tokens per second per GPU unless their name states otherwise.', + '配置字段与 metrics 映射并列。指标键可独立演进;值为数字,时间指标单位为秒,吞吐指标默认为每 GPU 每秒 token,除非名称另有说明。', + ), + shape: 'BenchmarkRows', + example: benchmarkExample[0], + }, + { + id: 'metric-maps', + title: text('ID-keyed maps', '以 ID 为键的映射'), + description: text( + 'Bulk diagnostic responses are JSON objects whose keys are decimal benchmark result IDs. A missing key means no value was available for that ID.', + '批量诊断响应是以十进制基准结果 ID 为键的 JSON 对象。缺少某个键表示该 ID 没有可用值。', + ), + shape: 'Record', + example: { '421': true }, + }, + { + id: 'collectivex-version', + title: text('CollectiveX versions', 'CollectiveX 版本'), + description: text( + `CollectiveX reads require an explicit supported contract version. Supported versions: ${COLLECTIVEX_VERSIONS.join(', ')}.`, + `CollectiveX 读取需要明确指定受支持的契约版本。受支持版本:${COLLECTIVEX_VERSIONS.join('、')}。`, + ), + shape: 'CollectiveXDataset', + }, + ], +}; + +const quickstartOperationIds = ['get-availability', 'list-benchmarks'] as const; +const quickstartText = { + 'get-availability': { + title: text('Discover configurations', '发现可用配置'), + description: text( + 'Start with availability to choose real model, hardware, framework, and sequence values.', + '先读取可用配置,以选择真实的模型、硬件、框架和序列值。', + ), + }, + 'list-benchmarks': { + title: text('Fetch benchmark rows', '获取基准行'), + description: text( + 'Then request the latest raw benchmark rows for a supported display model.', + '然后为受支持的展示模型请求最新原始基准行。', + ), + }, +} as const; + +function localizeOperation( + operation: ApiOperation, + locale: ApiDocumentationLocale, +): LocalizedApiOperation { + return { + ...operation, + summary: operation.summary[locale], + description: operation.description[locale], + parameters: operation.parameters.map((item) => ({ + ...item, + description: item.description[locale], + })), + responses: operation.responses.map((item) => ({ + ...item, + description: item.description[locale], + })), + }; +} + +function createLocalizedDocumentation(locale: ApiDocumentationLocale) { + const operationById = new Map(apiOperations.map((operation) => [operation.id, operation])); + return { + locale, + title: overview.title[locale], + eyebrow: overview.eyebrow[locale], + description: overview.description[locale], + baseUrl: API_BASE_URL, + version: API_VERSION, + specVersion: OPENAPI_DISPLAY_VERSION, + openApiUrl: OPENAPI_DOCUMENT_URL, + auth: { + title: overview.auth.title[locale], + description: overview.auth.description[locale], + }, + format: { + title: overview.format.title[locale], + description: overview.format.description[locale], + }, + quickstarts: quickstartOperationIds.map((id) => { + const operation = operationById.get(id)!; + return { + id, + label: quickstartText[id].title[locale], + description: quickstartText[id].description[locale], + command: `curl "${operation.curlUrl}"`, + }; + }), + conventions: overview.conventions.map((item) => ({ + id: item.id, + title: item.title[locale], + description: item.description[locale], + })), + schemaNotes: overview.schemaNotes.map((item) => ({ + id: item.id, + title: item.title[locale], + description: item.description[locale], + shape: item.shape, + ...('example' in item ? { example: item.example } : {}), + })), + groups: apiDocumentationGroups.map((group) => ({ + id: group.id, + title: group.title[locale], + description: group.description[locale], + operations: apiOperations + .filter((operation) => operation.group === group.id) + .map((operation) => localizeOperation(operation, locale)), + })), + }; +} + +const localizedDocumentation = { + en: createLocalizedDocumentation('en'), + zh: createLocalizedDocumentation('zh'), +} as const; + +export function getApiDocumentation(locale: ApiDocumentationLocale) { + return localizedDocumentation[locale]; +} + +export function buildOpenApiDocument(serverUrl: string = API_BASE_URL): OpenApiDocument { + const normalizedServerUrl = serverUrl.replace(/\/$/u, ''); + const schemas: Record = { ErrorResponse: errorSchema }; + const paths: Record> = {}; + + for (const operation of apiOperations) { + const successResponse = operation.responses.find((response) => + response.status.startsWith('2'), + )!; + schemas[operation.responseShapeName] ??= successResponse.schema; + + const responses = Object.fromEntries( + operation.responses.map((response) => { + const mediaType = response.mediaType ?? 'application/json'; + const primarySchema = response.status.startsWith('2') + ? { $ref: `#/components/schemas/${operation.responseShapeName}` } + : { $ref: '#/components/schemas/ErrorResponse' }; + const content: Record = { + [mediaType]: { schema: primarySchema, example: response.example }, + }; + for (const alternate of response.alternateRepresentations ?? []) { + content[alternate.mediaType] = { schema: alternate.schema, example: alternate.example }; + } + return [ + response.status, + { + description: response.description.en, + 'x-description-zh': response.description.zh, + content, + }, + ]; + }), + ); + + paths[operation.path] = { + ...paths[operation.path], + [operation.method.toLowerCase()]: { + operationId: operation.id, + tags: [operation.group], + summary: operation.summary.en, + description: operation.description.en, + 'x-summary-zh': operation.summary.zh, + 'x-description-zh': operation.description.zh, + 'x-audience': operation.audience, + 'x-stability': operation.stability, + security: [], + 'x-response-shape': operation.responseShapeName, + parameters: operation.parameters.map((item) => ({ + name: item.name, + in: item.location, + required: item.required, + description: item.description.en, + 'x-description-zh': item.description.zh, + schema: item.schema, + example: item.example, + })), + responses, + }, + }; + } + return { + openapi: OPENAPI_VERSION, + info: { + title: 'InferenceX Data API', + version: API_DOCUMENT_VERSION, + description: overview.description.en, + 'x-description-zh': overview.description.zh, + }, + servers: [{ url: normalizedServerUrl, description: 'InferenceX production API' }], + externalDocs: { + description: 'InferenceX API reference', + url: `${normalizedServerUrl}/api`, + }, + tags: apiDocumentationGroups.map((group) => ({ + name: group.id, + description: group.description.en, + 'x-name-zh': group.title.zh, + 'x-description-zh': group.description.zh, + })), + paths, + components: { schemas }, + }; +} diff --git a/packages/app/src/lib/api-route-catalog.test.ts b/packages/app/src/lib/api-route-catalog.test.ts new file mode 100644 index 000000000..55c4ce175 --- /dev/null +++ b/packages/app/src/lib/api-route-catalog.test.ts @@ -0,0 +1,399 @@ +import { createHash } from 'node:crypto'; +import fs from 'node:fs'; +import path from 'node:path'; + +import ts from 'typescript'; +import { describe, expect, it } from 'vitest'; + +import { + apiDocumentationGroups, + apiOperations, + buildOpenApiDocument, + getApiDocumentation, + type BilingualText, +} from './api-documentation'; +import { + apiContractSourceDigests, + apiRouteCatalog, + type ApiRouteHttpMethod, + type BilingualReviewText, +} from './api-route-catalog'; + +const APP_DIR = path.resolve(import.meta.dirname, '..', '..'); +const API_DIR = path.join(APP_DIR, 'src', 'app', 'api'); +const HTTP_METHODS = [ + 'GET', + 'POST', + 'PUT', + 'PATCH', + 'DELETE', + 'HEAD', + 'OPTIONS', +] as const satisfies readonly ApiRouteHttpMethod[]; +const HTTP_METHOD: Readonly> = { + GET: true, + POST: true, + PUT: true, + PATCH: true, + DELETE: true, + HEAD: true, + OPTIONS: true, +}; + +interface DiscoveredRoute { + readonly source: string; + readonly path: string; + readonly method: ApiRouteHttpMethod; +} + +function discoverRouteFiles(directory: string): string[] { + return fs + .readdirSync(directory, { withFileTypes: true }) + .flatMap((entry) => { + const absolute = path.join(directory, entry.name); + if (entry.isDirectory()) return discoverRouteFiles(absolute); + return entry.isFile() && entry.name === 'route.ts' ? [absolute] : []; + }) + .toSorted(); +} + +/** Uses the compiler AST so factory-assigned handlers such as `export const GET = idQueryRoute(...)` count. */ +function exportedHttpMethods(file: string): ApiRouteHttpMethod[] { + const sourceFile = ts.createSourceFile( + file, + fs.readFileSync(file, 'utf8'), + ts.ScriptTarget.Latest, + true, + ts.ScriptKind.TS, + ); + const methods = new Set(); + + for (const statement of sourceFile.statements) { + const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined; + if (!modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue; + + if (ts.isFunctionDeclaration(statement) && statement.name) { + const name = statement.name.text; + if (Object.hasOwn(HTTP_METHOD, name)) methods.add(name as ApiRouteHttpMethod); + continue; + } + + if (ts.isVariableStatement(statement)) { + for (const declaration of statement.declarationList.declarations) { + if (!ts.isIdentifier(declaration.name)) continue; + const name = declaration.name.text; + if (Object.hasOwn(HTTP_METHOD, name)) methods.add(name as ApiRouteHttpMethod); + } + } + } + + return [...methods].toSorted(); +} + +function openApiSegment(segment: string): string { + if (!segment.startsWith('[') || !segment.endsWith(']')) return segment; + + let parameter = segment.slice(1, -1); + if (parameter.startsWith('[') && parameter.endsWith(']')) parameter = parameter.slice(1, -1); + if (parameter.startsWith('...')) parameter = parameter.slice(3); + return `{${parameter}}`; +} + +function routePathFromFile(file: string): string { + const relativeDirectory = path.relative(API_DIR, path.dirname(file)); + const segments = relativeDirectory.split(path.sep).filter(Boolean).map(openApiSegment); + return segments.length === 0 ? '/api' : `/api/${segments.join('/')}`; +} + +function discoverRoutes(): DiscoveredRoute[] { + return discoverRouteFiles(API_DIR).flatMap((file) => + exportedHttpMethods(file).map((method) => ({ + source: path.relative(APP_DIR, file).split(path.sep).join('/'), + path: routePathFromFile(file), + method, + })), + ); +} + +function sha256(file: string): string { + return createHash('sha256').update(fs.readFileSync(file)).digest('hex'); +} + +function expectLocalizedPair(label: string, value: BilingualReviewText | BilingualText): void { + expect(value.en.trim(), `${label} is missing English copy`).not.toBe(''); + expect(value.zh.trim(), `${label} is missing Simplified Chinese copy`).not.toBe(''); +} + +function pathParameterNames(apiPath: string): string[] { + return apiPath + .split('/') + .filter((segment) => segment.startsWith('{') && segment.endsWith('}')) + .map((segment) => segment.slice(1, -1)); +} + +function expectNonempty(label: string, value: string): void { + expect(value.trim(), `${label} must be localized`).not.toBe(''); +} + +describe('API route catalog', () => { + it('has exact source, OpenAPI path, and HTTP method parity with route handlers', () => { + const discoveredKeys = discoverRoutes() + .map((route) => `${route.source} :: ${route.method} ${route.path}`) + .toSorted(); + const catalogKeys = apiRouteCatalog + .map((route) => `${route.source} :: ${route.method} ${route.path}`) + .toSorted(); + + expect( + new Set(catalogKeys).size, + 'Duplicate catalog entry: keep one classification per source/path/method handler.', + ).toBe(catalogKeys.length); + expect( + discoveredKeys, + 'Route handlers changed. Review the API documentation and add or remove the matching catalog entry and digest.', + ).toEqual(catalogKeys); + }); + + it('forces API documentation review after every route or shared contract source edit', () => { + for (const entry of apiRouteCatalog) { + const absolute = path.join(APP_DIR, entry.source); + expect(fs.existsSync(absolute), `${entry.source} is cataloged but missing`).toBe(true); + expect(entry.sourceSha256, `${entry.source} has an invalid SHA-256 digest`).toMatch( + /^[0-9a-f]{64}$/u, + ); + expect( + sha256(absolute), + `${entry.method} ${entry.path} changed. Review its API documentation/classification and update the route SHA-256 digest in src/lib/api-route-catalog.ts.`, + ).toBe(entry.sourceSha256); + } + + for (const entry of apiContractSourceDigests) { + const absolute = path.resolve(APP_DIR, entry.source); + expectLocalizedPair(`${entry.source} review area`, entry.reviewArea); + expect(fs.existsSync(absolute), `${entry.source} is cataloged but missing`).toBe(true); + expect(entry.sourceSha256, `${entry.source} has an invalid SHA-256 digest`).toMatch( + /^[0-9a-f]{64}$/u, + ); + expect( + sha256(absolute), + `${entry.source} changed. Review API docs for: ${entry.reviewArea.en} Then update its shared-source SHA-256 digest in src/lib/api-route-catalog.ts.`, + ).toBe(entry.sourceSha256); + } + }); + + it('classifies every route and gives every unpublished handler a bilingual reason', () => { + expect([...new Set(apiRouteCatalog.map((entry) => entry.classification))].toSorted()).toEqual( + [ + 'published-read', + 'page-bff', + 'ui-artifact-read', + 'public-mutation', + 'admin', + 'sensitive', + 'documentation', + ].toSorted(), + ); + + for (const entry of apiRouteCatalog) { + if (entry.classification === 'published-read') { + expect( + entry.operationId.trim(), + `${entry.method} ${entry.path} needs an operationId`, + ).not.toBe(''); + } else { + expectLocalizedPair( + `${entry.method} ${entry.path} exclusion reason`, + entry.exclusionReason, + ); + expect( + entry.exclusionReason.zh, + `${entry.method} ${entry.path} exclusion reason must contain Simplified Chinese copy`, + ).toMatch(/[\u3400-\u9FFF]/u); + } + } + }); + + it('maps published reads one-to-one to unique documented operations', () => { + const published = apiRouteCatalog.filter((entry) => entry.classification === 'published-read'); + const publishedIds = published.map((entry) => entry.operationId); + const documentedIds = apiOperations.map((operation) => operation.id); + + expect(new Set(publishedIds).size, 'Published catalog operationIds must be unique.').toBe( + publishedIds.length, + ); + expect(new Set(documentedIds).size, 'apiOperations operationIds must be unique.').toBe( + documentedIds.length, + ); + expect( + publishedIds.toSorted(), + 'Published catalog entries and apiOperations must use exactly the same operationIds.', + ).toEqual(documentedIds.toSorted()); + + for (const operation of apiOperations) { + const entry = published.find((candidate) => candidate.operationId === operation.id); + expect( + entry, + `${operation.id} is documented but has no published route classification`, + ).toBeDefined(); + expect(entry?.path, `${operation.id} path drifted from its route catalog entry`).toBe( + operation.path, + ); + expect(entry?.method, `${operation.id} method drifted from its route catalog entry`).toBe( + operation.method, + ); + } + }); +}); + +describe('published API documentation invariants', () => { + it('keeps all documentation copy complete in both locales', () => { + for (const group of apiDocumentationGroups) { + expectLocalizedPair(`${group.id} title`, group.title); + expectLocalizedPair(`${group.id} description`, group.description); + } + + for (const operation of apiOperations) { + expectLocalizedPair(`${operation.id} summary`, operation.summary); + expectLocalizedPair(`${operation.id} description`, operation.description); + for (const parameter of operation.parameters) { + expectLocalizedPair(`${operation.id} parameter ${parameter.name}`, parameter.description); + } + for (const response of operation.responses) { + expectLocalizedPair(`${operation.id} response ${response.status}`, response.description); + } + } + + for (const locale of ['en', 'zh'] as const) { + const documentation = getApiDocumentation(locale); + expectNonempty(`${locale} title`, documentation.title); + expectNonempty(`${locale} eyebrow`, documentation.eyebrow); + expectNonempty(`${locale} description`, documentation.description); + expectNonempty(`${locale} auth title`, documentation.auth.title); + expectNonempty(`${locale} auth description`, documentation.auth.description); + expectNonempty(`${locale} format title`, documentation.format.title); + expectNonempty(`${locale} format description`, documentation.format.description); + + for (const quickstart of documentation.quickstarts) { + expectNonempty(`${locale} quickstart ${quickstart.id} label`, quickstart.label); + expectNonempty(`${locale} quickstart ${quickstart.id} description`, quickstart.description); + } + for (const convention of documentation.conventions) { + expectNonempty(`${locale} convention ${convention.id} title`, convention.title); + expectNonempty(`${locale} convention ${convention.id} description`, convention.description); + } + for (const note of documentation.schemaNotes) { + expectNonempty(`${locale} schema note ${note.id} title`, note.title); + expectNonempty(`${locale} schema note ${note.id} description`, note.description); + } + for (const group of documentation.groups) { + expectNonempty(`${locale} group ${group.id} title`, group.title); + expectNonempty(`${locale} group ${group.id} description`, group.description); + for (const operation of group.operations) { + expectNonempty(`${locale} operation ${operation.id} summary`, operation.summary); + expectNonempty(`${locale} operation ${operation.id} description`, operation.description); + for (const parameter of operation.parameters) { + expectNonempty( + `${locale} operation ${operation.id} parameter ${parameter.name}`, + parameter.description, + ); + } + for (const response of operation.responses) { + expectNonempty( + `${locale} operation ${operation.id} response ${response.status}`, + response.description, + ); + } + } + } + } + }); + + it('documents every path parameter and at least one successful response', () => { + for (const operation of apiOperations) { + const pathNames = pathParameterNames(operation.path).toSorted(); + const documentedPathParameters = operation.parameters + .filter((parameter) => parameter.location === 'path') + .map((parameter) => parameter.name) + .toSorted(); + + expect( + documentedPathParameters, + `${operation.id} must document exactly the parameters in its OpenAPI path template.`, + ).toEqual(pathNames); + for (const parameter of operation.parameters.filter((item) => item.location === 'path')) { + expect( + parameter.required, + `${operation.id} path parameter ${parameter.name} must be required`, + ).toBe(true); + } + expect( + operation.responses.some((response) => response.status.startsWith('2')), + `${operation.id} must document a 2xx response.`, + ).toBe(true); + } + }); + + it('keeps the OpenAPI paths and operations in exact parity with apiOperations', () => { + const document = buildOpenApiDocument('https://api-docs.test'); + const projected = new Map>(); + + for (const [apiPath, pathItemValue] of Object.entries(document.paths)) { + const pathItem = pathItemValue as Record; + for (const method of HTTP_METHODS) { + const operationValue = pathItem[method.toLowerCase()]; + if (operationValue === undefined) continue; + projected.set(`${method} ${apiPath}`, operationValue as Record); + } + } + + const documentedKeys = apiOperations + .map((operation) => `${operation.method} ${operation.path}`) + .toSorted(); + expect( + [...projected.keys()].toSorted(), + 'OpenAPI paths/methods must exactly match the published apiOperations registry.', + ).toEqual(documentedKeys); + + const projectedOperationIds: string[] = []; + for (const operation of apiOperations) { + const key = `${operation.method} ${operation.path}`; + const openApiOperation = projected.get(key); + expect( + openApiOperation, + `${operation.id} is missing from the OpenAPI projection`, + ).toBeDefined(); + expect( + openApiOperation?.operationId, + `${operation.id} has a mismatched OpenAPI operationId`, + ).toBe(operation.id); + projectedOperationIds.push(String(openApiOperation?.operationId)); + + const responses = openApiOperation?.responses as Record | undefined; + expect( + responses && Object.keys(responses).some((status) => status.startsWith('2')), + `${operation.id} must project a 2xx OpenAPI response.`, + ).toBe(true); + + const parameters = + (openApiOperation?.parameters as readonly Record[] | undefined) ?? []; + const projectedPathParameters = parameters + .filter((parameter) => parameter.in === 'path') + .map((parameter) => String(parameter.name)) + .toSorted(); + for (const parameter of parameters.filter((item) => item.in === 'path')) { + expect( + parameter.required, + `${operation.id} OpenAPI path parameter ${String(parameter.name)} must be required.`, + ).toBe(true); + } + expect( + projectedPathParameters, + `${operation.id} OpenAPI projection must include every path parameter.`, + ).toEqual(pathParameterNames(operation.path).toSorted()); + } + + expect(new Set(projectedOperationIds).size, 'OpenAPI operationIds must be unique.').toBe( + projectedOperationIds.length, + ); + }); +}); diff --git a/packages/app/src/lib/api-route-catalog.ts b/packages/app/src/lib/api-route-catalog.ts new file mode 100644 index 000000000..a557dd7f7 --- /dev/null +++ b/packages/app/src/lib/api-route-catalog.ts @@ -0,0 +1,541 @@ +export type ApiRouteClassification = + | 'published-read' + | 'page-bff' + | 'ui-artifact-read' + | 'public-mutation' + | 'admin' + | 'sensitive' + | 'documentation'; + +export type ApiRouteHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'; + +export interface BilingualReviewText { + readonly en: string; + readonly zh: string; +} + +interface ApiRouteCatalogEntryBase { + /** Path relative to packages/app. */ + readonly source: `src/app/api/${string}/route.ts`; + /** App Router path normalized to an OpenAPI path template. */ + readonly path: `/api/${string}`; + readonly method: ApiRouteHttpMethod; + readonly sourceSha256: string; +} + +export interface PublishedApiRouteCatalogEntry extends ApiRouteCatalogEntryBase { + readonly classification: 'published-read'; + readonly operationId: string; + readonly exclusionReason?: never; +} + +export interface ExcludedApiRouteCatalogEntry extends ApiRouteCatalogEntryBase { + readonly classification: Exclude; + readonly operationId?: never; + readonly exclusionReason: BilingualReviewText; +} + +export type ApiRouteCatalogEntry = PublishedApiRouteCatalogEntry | ExcludedApiRouteCatalogEntry; + +/** + * Review ledger for every App Router HTTP handler under src/app/api. + * + * A route digest changing is intentionally noisy: review the handler's public + * contract and either update the API documentation or affirm the classification + * before replacing the digest. + */ +export const apiRouteCatalog = [ + { + source: 'src/app/api/gpu-metrics/route.ts', + path: '/api/gpu-metrics', + method: 'GET', + classification: 'ui-artifact-read', + exclusionReason: { + en: 'UI-only live GPU metric artifact lookup; its run artifact shape is not a stable public contract.', + zh: '仅供界面读取实时 GPU 指标制品;其运行制品结构不是稳定的公开契约。', + }, + sourceSha256: '28e6cee4d67396ee8ea2e5a7e18271c6ee86228c33f33a20bf573f3a601ba8ed', + }, + { + source: 'src/app/api/openapi.json/route.ts', + path: '/api/openapi.json', + method: 'GET', + classification: 'documentation', + exclusionReason: { + en: 'Documentation transport endpoint; it publishes the OpenAPI projection rather than application data.', + zh: '文档传输端点;它发布 OpenAPI 投影,而不是应用数据。', + }, + sourceSha256: '5ea5c034c837fda109ca3b7218db51a6ac78bca3eac545371de0f2a45880d533', + }, + { + source: 'src/app/api/unofficial-run/route.ts', + path: '/api/unofficial-run', + method: 'GET', + classification: 'ui-artifact-read', + exclusionReason: { + en: 'UI-only overlay for unofficial workflow artifacts; upstream artifact availability and shape are not stable.', + zh: '仅供界面叠加非官方工作流制品;上游制品的可用性和结构并不稳定。', + }, + sourceSha256: 'ef85fec8468757b0122c5fcebde78527c2efe62f9fedc95799cad56a457a8f04', + }, + { + source: 'src/app/api/v1/agentic-aggregates/route.ts', + path: '/api/v1/agentic-aggregates', + method: 'GET', + classification: 'published-read', + operationId: 'get-agentic-aggregates', + sourceSha256: '6a99fc156b02b86c5c26ca5ba6b05a280e064dd6123aaba528f124ff0f13c577', + }, + { + source: 'src/app/api/v1/availability/route.ts', + path: '/api/v1/availability', + method: 'GET', + classification: 'published-read', + operationId: 'get-availability', + sourceSha256: '12bc0fa8930792897ed8300bd3be1333826b51903c04c6fbdec335f13d80ca7a', + }, + { + source: 'src/app/api/v1/benchmark-siblings/route.ts', + path: '/api/v1/benchmark-siblings', + method: 'GET', + classification: 'published-read', + operationId: 'get-benchmark-siblings', + sourceSha256: '36b00e5d1c761e6a76e2c0454d9be4a15b7ccb7f3af5bdccd8ac61b6e5ff5312', + }, + { + source: 'src/app/api/v1/benchmarks/route.ts', + path: '/api/v1/benchmarks', + method: 'GET', + classification: 'published-read', + operationId: 'list-benchmarks', + sourceSha256: 'daf24b2a08ab021782084fc6e5e145013fca518e58d18837355a088e040f257b', + }, + { + source: 'src/app/api/v1/benchmarks/history/route.ts', + path: '/api/v1/benchmarks/history', + method: 'GET', + classification: 'published-read', + operationId: 'list-benchmark-history', + sourceSha256: 'f99940aabe91d315e33e0e645342d83ace227fc014de029d16868284e158be40', + }, + { + source: 'src/app/api/v1/collectivex/latest/route.ts', + path: '/api/v1/collectivex/latest', + method: 'GET', + classification: 'published-read', + operationId: 'get-collectivex-latest', + sourceSha256: '41c67c25c62ae2bad5f2ef16faf7a3e5a5c4440a53e3701ae68cf0fdb0973f18', + }, + { + source: 'src/app/api/v1/collectivex/runs/route.ts', + path: '/api/v1/collectivex/runs', + method: 'GET', + classification: 'published-read', + operationId: 'list-collectivex-runs', + sourceSha256: 'bce17c290c75ddae3300125b4cefec684f58748cbd524dd4b6916e2728660f23', + }, + { + source: 'src/app/api/v1/collectivex/runs/[runId]/route.ts', + path: '/api/v1/collectivex/runs/{runId}', + method: 'GET', + classification: 'published-read', + operationId: 'get-collectivex-run', + sourceSha256: 'dabbf260d406f774a880ea4c19c25271775755107ada6d036e2cf6b13f818cbb', + }, + { + source: 'src/app/api/v1/collectivex/runs/[runId]/route.ts', + path: '/api/v1/collectivex/runs/{runId}', + method: 'DELETE', + classification: 'admin', + exclusionReason: { + en: 'Authenticated CollectiveX administration mutation; deletion is not part of the public read API.', + zh: '需要身份验证的 CollectiveX 管理写操作;删除不属于公开只读 API。', + }, + sourceSha256: 'dabbf260d406f774a880ea4c19c25271775755107ada6d036e2cf6b13f818cbb', + }, + { + source: 'src/app/api/v1/datasets/route.ts', + path: '/api/v1/datasets', + method: 'GET', + classification: 'published-read', + operationId: 'list-datasets', + sourceSha256: '22eb9d7bb5f91d64a19d43723c4be73c239513073819ad5af83864a3b4858505', + }, + { + source: 'src/app/api/v1/datasets/[slug]/route.ts', + path: '/api/v1/datasets/{slug}', + method: 'GET', + classification: 'published-read', + operationId: 'get-dataset', + sourceSha256: 'cf2e1e5e31604222f7558b9dc32f2273db082d086a8b0e3687b723b34a6380ae', + }, + { + source: 'src/app/api/v1/datasets/[slug]/conversations/route.ts', + path: '/api/v1/datasets/{slug}/conversations', + method: 'GET', + classification: 'published-read', + operationId: 'list-dataset-conversations', + sourceSha256: 'f02b0e3c77c6043491ac53a179fb2ca090575f6bb6066119fd78c7919bfc5dbf', + }, + { + source: 'src/app/api/v1/datasets/[slug]/conversations/[convId]/route.ts', + path: '/api/v1/datasets/{slug}/conversations/{convId}', + method: 'GET', + classification: 'published-read', + operationId: 'get-dataset-conversation', + sourceSha256: 'cc29285f5744a12d52ab66b6648caec8fc183fbe4915a1ebd59357643db3dc63', + }, + { + source: 'src/app/api/v1/derived-agentic-metrics/route.ts', + path: '/api/v1/derived-agentic-metrics', + method: 'GET', + classification: 'published-read', + operationId: 'get-derived-agentic-metrics', + sourceSha256: '68013b8e1a0354e677c075b5ab31df4be5889fdc0dc2eb82dbe52a108f4d1db2', + }, + { + source: 'src/app/api/v1/eval-samples-live/route.ts', + path: '/api/v1/eval-samples-live', + method: 'GET', + classification: 'ui-artifact-read', + exclusionReason: { + en: 'UI-only evaluation sample reader backed by live workflow artifacts with an unstable artifact contract.', + zh: '仅供界面读取由实时工作流制品支持的评测样本;该制品契约不稳定。', + }, + sourceSha256: '7790c89e48b71f0cb2a819f34ec649ce300982fa41bba20a2b996b6c9768b6c7', + }, + { + source: 'src/app/api/v1/eval-samples/route.ts', + path: '/api/v1/eval-samples', + method: 'GET', + classification: 'ui-artifact-read', + exclusionReason: { + en: 'UI drill-down for evaluation samples; its pagination and sample payload remain page-owned.', + zh: '用于界面下钻评测样本;其分页和样本载荷仍由页面内部使用。', + }, + sourceSha256: '0e05c3d98153a53e5025e6c9973ac6a0eef294ad8cb6ac8748b9a1478067b233', + }, + { + source: 'src/app/api/v1/evaluations/route.ts', + path: '/api/v1/evaluations', + method: 'GET', + classification: 'published-read', + operationId: 'list-evaluations', + sourceSha256: '8eab5b9d1df62b64b89458943d6e2182b62713c22421a30f427044f664b76b04', + }, + { + source: 'src/app/api/v1/feedback/route.ts', + path: '/api/v1/feedback', + method: 'POST', + classification: 'public-mutation', + exclusionReason: { + en: 'Unauthenticated feedback submission changes stored state and is intentionally outside the published read API.', + zh: '无需身份验证的反馈提交会更改存储状态,因此有意不纳入公开只读 API。', + }, + sourceSha256: '8ce117bca507ec2a26cbd0c6d264c76043d5d26e87108261026ec3a3344e78d0', + }, + { + source: 'src/app/api/v1/feedback/list/route.ts', + path: '/api/v1/feedback/list', + method: 'GET', + classification: 'sensitive', + exclusionReason: { + en: 'Returns encrypted user feedback and request metadata for the feedback UI; ciphertext access remains sensitive.', + zh: '为反馈界面返回加密的用户反馈和请求元数据;密文访问仍属敏感操作。', + }, + sourceSha256: '8f5fb4a6be071000be4db58ecd89163da094e4999588ee5ecd29a9d220873211', + }, + { + source: 'src/app/api/v1/framework-releases/route.ts', + path: '/api/v1/framework-releases', + method: 'GET', + classification: 'published-read', + operationId: 'get-framework-releases', + sourceSha256: 'ce0bd92ab1b567ee476f0a96b9a3b7ea3c5730b75b32d6941e8de661822be3f6', + }, + { + source: 'src/app/api/v1/invalidate/route.ts', + path: '/api/v1/invalidate', + method: 'POST', + classification: 'admin', + exclusionReason: { + en: 'Secret-protected cache invalidation mutation for operators; it is not a public application contract.', + zh: '供运维人员使用的密钥保护缓存失效写操作;它不是公开应用契约。', + }, + sourceSha256: 'b081b54a5960e6da0987e9ccee777bfbc40c03d0206823472ee7d0f0e969e8d7', + }, + { + source: 'src/app/api/v1/latest-images/route.ts', + path: '/api/v1/latest-images', + method: 'GET', + classification: 'published-read', + operationId: 'get-latest-images', + sourceSha256: '67e50209f2a1200b56e418c9edc29eba955e6c1273319f98a2deb8657b79e895', + }, + { + source: 'src/app/api/v1/overview/route.ts', + path: '/api/v1/overview', + method: 'GET', + classification: 'page-bff', + exclusionReason: { + en: 'Page-owned BFF aggregation whose tier, comparison, and calculator projections are coupled to the overview UI.', + zh: '由页面拥有的 BFF 聚合;其档位、比较和计算器投影与概览界面紧密耦合。', + }, + sourceSha256: '7c9830baae39d533ba7db36d44fe520f89cb36b32ffc54ef29404693d0b6b120', + }, + { + source: 'src/app/api/v1/reliability/route.ts', + path: '/api/v1/reliability', + method: 'GET', + classification: 'published-read', + operationId: 'list-reliability', + sourceSha256: 'fe295d04ecf45bfcbd5d59518eb9a5b04a7f460a95053d79f7f904502d39d189', + }, + { + source: 'src/app/api/v1/request-timeline/route.ts', + path: '/api/v1/request-timeline', + method: 'GET', + classification: 'published-read', + operationId: 'get-request-timeline', + sourceSha256: '30659cb757b9fd23411757051b650cfb564016aa15c8b9fec48676b9591f01e9', + }, + { + source: 'src/app/api/v1/server-log/route.ts', + path: '/api/v1/server-log', + method: 'GET', + classification: 'published-read', + operationId: 'get-server-log', + sourceSha256: '0462679b059bb8e2c48507e147faa24389a76b04312f06dbf9ab3724352a1239', + }, + { + source: 'src/app/api/v1/submissions/route.ts', + path: '/api/v1/submissions', + method: 'GET', + classification: 'published-read', + operationId: 'get-submissions', + sourceSha256: '4c5fddd7e8d87060e724ff18a905d01165c01e764fa70d3f3f518dfe987b1e1b', + }, + { + source: 'src/app/api/v1/tco-feed/route.ts', + path: '/api/v1/tco-feed', + method: 'GET', + classification: 'published-read', + operationId: 'get-tco-feed', + sourceSha256: 'e80ccbfe7b5393083078f09a4a3295bb6f85d28092fdcfdc57f9b1106bb3538b', + }, + { + source: 'src/app/api/v1/trace-availability/route.ts', + path: '/api/v1/trace-availability', + method: 'GET', + classification: 'published-read', + operationId: 'get-trace-availability', + sourceSha256: '0a41b121ad7ba75bc01e852d9e0d7e2fe7a4d8c47239e9ea57778be4ee21929c', + }, + { + source: 'src/app/api/v1/trace-histograms/route.ts', + path: '/api/v1/trace-histograms', + method: 'GET', + classification: 'published-read', + operationId: 'get-trace-histograms', + sourceSha256: '1157a59930b754787872b0d543167c917477be27e63a6fab0cc487ffab5d4825', + }, + { + source: 'src/app/api/v1/trace-server-metrics/route.ts', + path: '/api/v1/trace-server-metrics', + method: 'GET', + classification: 'published-read', + operationId: 'get-trace-server-metrics', + sourceSha256: 'b1bb5b859a28ec18abd0b4ddebf5e505974a08b7ed9693e5bab118f4533f3ce6', + }, + { + source: 'src/app/api/v1/workflow-info/route.ts', + path: '/api/v1/workflow-info', + method: 'GET', + classification: 'published-read', + operationId: 'get-workflow-info', + sourceSha256: 'ec497811abc666e4bf970b6e722fde3a7fefc25a87d6b4e5897a605e22c84ee8', + }, +] as const satisfies readonly ApiRouteCatalogEntry[]; + +export interface ApiContractSourceDigest { + /** Path relative to packages/app. */ + readonly source: string; + readonly sourceSha256: string; + /** The API documentation area that must be reviewed when this source changes. */ + readonly reviewArea: BilingualReviewText; +} + +/** + * Shared sources that can change published parameters or response shapes without + * touching a route module. Digest changes require an explicit documentation review. + */ +export const apiContractSourceDigests = [ + { + source: 'src/app/api/v1/id-routes.ts', + sourceSha256: '65a8ebf97d500fd4164e068dc7d303d82e74e5ed84301dcd19ef8d386317b721', + reviewArea: { + en: 'Shared positive-ID and ID-list validation, status codes, and error payloads for diagnostic reads.', + zh: '诊断读取共享的正整数 ID 与 ID 列表校验、状态码和错误载荷。', + }, + }, + { + source: 'src/lib/api.ts', + sourceSha256: '7824444f73bd1331ad06cc62060de08446f9d20661fa77030a254d6125b3636a', + reviewArea: { + en: 'Public API client parameter serialization and TypeScript response contracts.', + zh: '公开 API 客户端的参数序列化和 TypeScript 响应契约。', + }, + }, + { + source: 'src/lib/tco-feed.ts', + sourceSha256: '52d95a0c867513e6f6e3aaace4d066e69a28495ac593b89821b7b81d7475861a', + reviewArea: { + en: 'TCO workload, tier, score, point, and CSV/JSON response semantics.', + zh: 'TCO 负载、档位、评分、数据点以及 CSV/JSON 响应语义。', + }, + }, + { + source: '../constants/src/models.ts', + sourceSha256: 'dca2b25f754adf90ac1bda31c5eb52503e3b3e8c72e684f10724c177c1317fac', + reviewArea: { + en: 'Published benchmark and TCO model names, aliases, and parameter enums.', + zh: '已发布基准与 TCO 模型名称、别名和参数枚举。', + }, + }, + { + source: '../db/src/collectivex/types.ts', + sourceSha256: '40079de1a9b1faef47cc72090331b9d2987f2895da34a77292f3bfcdf1dc5a64', + reviewArea: { + en: 'CollectiveX version negotiation and versioned dataset/run response types.', + zh: 'CollectiveX 版本协商以及带版本的数据集与运行响应类型。', + }, + }, + { + source: '../db/src/etl/compute-request-timeline.ts', + sourceSha256: '7cf9d1ab318ca9c21d9200ca4347437ce9f7bb3159bedb29a169cdf6ba46baae', + reviewArea: { + en: 'Request timeline contract version and event timing field semantics.', + zh: '请求时间线契约版本和事件计时字段语义。', + }, + }, + { + source: '../db/src/queries/agentic-aggregates.ts', + sourceSha256: 'b0f4be6c39fe440df99db687b4b6deeed58897bf20325770631680f6e41aa304', + reviewArea: { + en: 'Agentic aggregate percentile keys, nullability, and ID-keyed response shape.', + zh: '智能体汇总百分位字段、可空性和按 ID 索引的响应结构。', + }, + }, + { + source: '../db/src/queries/benchmark-siblings.ts', + sourceSha256: '5a2b7e902c3003a0b3dbf3f402cc4b6b40648a1e014a218ab39dcbfd35c80f42', + reviewArea: { + en: 'Benchmark sibling SKU metadata and sibling navigation row shape.', + zh: '基准同组 SKU 元数据和同组导航行结构。', + }, + }, + { + source: '../db/src/queries/benchmarks.ts', + sourceSha256: '05e97742b831d1afdcb8dec1d764fd9b3d4a54564e93da4ceea778f8533c5c49', + reviewArea: { + en: 'Benchmark row fields and latest, exact-run, history, and TCO query semantics.', + zh: '基准行字段以及最新、精确运行、历史和 TCO 查询语义。', + }, + }, + { + source: '../db/src/queries/collectivex.ts', + sourceSha256: '3eaf48a67933cfbda9068bc6367b16120fe46c28428dc1740763d6957a8365a0', + reviewArea: { + en: 'CollectiveX dataset projection, run summaries, coverage, series, and discovery state.', + zh: 'CollectiveX 数据集投影、运行汇总、覆盖范围、序列和发现状态。', + }, + }, + { + source: '../db/src/queries/datasets.ts', + sourceSha256: '05b0f990f8aeb1061fb0bfe7204f1c015fc55b0a541249188ffe740edf2a5af6', + reviewArea: { + en: 'Dataset registry, detail, conversation index, pagination, and conversation structure responses.', + zh: '数据集目录、详情、会话索引、分页和会话结构响应。', + }, + }, + { + source: '../db/src/queries/evaluations.ts', + sourceSha256: '937f1329a40edda00012b8058b7f802629ba972de88585c29fedd1447c4d1929', + reviewArea: { + en: 'Evaluation aggregate result fields, provenance, metrics, and latest-attempt selection.', + zh: '评测汇总结果字段、来源、指标和最新尝试选择。', + }, + }, + { + source: '../db/src/queries/latest-images.ts', + sourceSha256: '80c69b9e9ed34e4279c6b95d8418c9535fcee1919ccb4883066d27954588c977', + reviewArea: { + en: 'Latest runtime image row fields and per-configuration selection.', + zh: '最新运行时镜像行字段和按配置选择逻辑。', + }, + }, + { + source: '../db/src/queries/reliability.ts', + sourceSha256: 'ccbdc07e16652e687e9feb239951a9e529ee24e2e1ea76a75f1458270ac30bd6', + reviewArea: { + en: 'Reliability success/total count fields and grouping semantics.', + zh: '可靠性成功数/总数的字段和分组语义。', + }, + }, + { + source: '../db/src/queries/request-timeline.ts', + sourceSha256: '5373c839e1290d5ce1fde420041028325418597e0c911b212368f2f839756fa2', + reviewArea: { + en: 'Request timeline metadata, request event records, units, and nullable timings.', + zh: '请求时间线元数据、请求事件记录、单位和可空计时字段。', + }, + }, + { + source: '../db/src/queries/server-logs.ts', + sourceSha256: '44a4a55283fe4952e07df4034abf6a211d055225aee510ef3e6a945c72b63b55', + reviewArea: { + en: 'Server log lookup result fields and missing-record behavior.', + zh: '服务器日志查询结果字段和记录缺失行为。', + }, + }, + { + source: '../db/src/queries/submissions.ts', + sourceSha256: '0e234dd65414b31c5a60fd07ca9a3ac20fab03dcf9fa1c80d487f087a76d7e49', + reviewArea: { + en: 'Submission summary and daily hardware volume row fields.', + zh: '提交汇总和每日硬件提交量行字段。', + }, + }, + { + source: '../db/src/queries/trace-availability.ts', + sourceSha256: '838fb261a153e560b4c488b770deb47e57dd3ab3bfd5b98d32b2ec6fba79873e', + reviewArea: { + en: 'Trace availability ID-keyed boolean response shape.', + zh: '跟踪可用性按 ID 索引的布尔响应结构。', + }, + }, + { + source: '../db/src/queries/trace-histograms.ts', + sourceSha256: '43d11e53abc4f9ba723c987424823a03fc8f5dde51cf11653ab8c0bf3a634f55', + reviewArea: { + en: 'Trace histogram input/output token arrays and ID-keyed response shape.', + zh: '跟踪直方图输入/输出 token 数组和按 ID 索引的响应结构。', + }, + }, + { + source: '../db/src/queries/trace-server-metrics.ts', + sourceSha256: '06b5a9b92b90a5e695ab6c1dfb4b4d1240180f8d306ff4523ea8cc4269b0ddf3', + reviewArea: { + en: 'Trace server metric metadata, time-series groups, source labels, and units.', + zh: '跟踪服务器指标元数据、时间序列分组、来源标签和单位。', + }, + }, + { + source: '../db/src/queries/workflow-info.ts', + sourceSha256: 'a588811952d152ecb5ca3725e565f3f829c7bbdfd14a795b261a11bfa82fe00a', + reviewArea: { + en: 'Availability rows plus workflow runs, changelogs, configurations, and run coverage responses.', + zh: '可用配置行以及工作流运行、变更记录、配置和运行覆盖响应。', + }, + }, +] as const satisfies readonly ApiContractSourceDigest[]; diff --git a/packages/app/src/lib/i18n.ts b/packages/app/src/lib/i18n.ts index 5740981df..13f4e4e53 100644 --- a/packages/app/src/lib/i18n.ts +++ b/packages/app/src/lib/i18n.ts @@ -37,6 +37,7 @@ export function isZhPathname(pathname: string): boolean { export const ZH_MIRRORED_ROUTES: readonly { path: string; exact?: boolean }[] = [ { path: '/', exact: true }, { path: '/overview', exact: true }, + { path: '/api', exact: true }, { path: '/inference', exact: true }, { path: '/inference/agentic' }, { path: '/evaluation', exact: true }, From a6a729760a074e8c4928825bee1bfcfb7a661e9d Mon Sep 17 00:00:00 2001 From: adibarra <93070681+adibarra@users.noreply.github.com> Date: Mon, 10 Aug 2026 13:33:36 -0500 Subject: [PATCH 2/2] docs: require api documentation synchronization checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 中文:要求所有 API 变更同步更新英文与中文参考文档、OpenAPI 契约和接口目录校验。 --- AGENTS.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7c3095036..645d0bd7b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,24 @@ initial server render so selector changes can update the matrix without transfer raw benchmark history or triggering a React Server Component (RSC) round trip. It is a page-owned backend-for-frontend (BFF), not a reusable public data API. +### API Documentation Synchronization + +The public API reference at `/api` and `/zh/api`, plus the OpenAPI 3.1 document at +`/api/openapi.json`, are generated from `packages/app/src/lib/api-documentation.ts`. + +**Any change to an API route, request parameter, response shape, status code, authentication, +caching behavior, or shared API type MUST update the documentation registry in the same change.** +Keep `packages/app/src/lib/api-route-catalog.ts` synchronized with every handler under +`packages/app/src/app/api/`; the catalog classifies unpublished routes and records review digests +for handlers and shared contract sources. Do not update a digest without first confirming whether +the human reference, Chinese copy, examples, or OpenAPI schema also need changes. + +Run the synchronization guard from `packages/app`: + +```bash +bun --env-file=../../.env vitest run src/lib/api-route-catalog.test.ts +``` + Static content routes (no DB): - `/blog` — blog listing (statically generated from MDX files in `content/blog/`)