Skip to content
Source
Sign inSign up
TanStack/schemas
Open History to see the last commit

catalog.ts

385 lines11.7 KB

1/**
2 * Catalog queries (PLAN.md task 4.2): providers, cross-provider model
3 * catalog with filters, and single-model detail. Route handlers stay thin —
4 * these functions are exercised directly by worker tests.
5 */
6import { and, eq, inArray, isNull, like, or, sql } from 'drizzle-orm'
7import type { SQL } from 'drizzle-orm'
8import { alias } from 'drizzle-orm/sqlite-core'
9​
10import type { Db } from '#/db/index.ts'
11import { models, providers } from '#/db/schema.ts'
12import type { Activity } from '#/db/schema.ts'
13import { halGet } from '#/server/hal.ts'
14import { getProvider } from '#/server/providers/index.ts'
15import { resolveSpecGrain } from '#/server/providers/connect.ts'
16import type {
17 FactSource,
18 ModelFactSources,
19 SpecGrain,
20} from '#/server/providers/types.ts'
21import {
22 factDiscrepancies,
23 openRouterJoinIds,
24} from '#/server/providers/fact-sources.ts'
25import {
26 resolveAlias,
27 storedAliases,
28} from '#/server/providers/provider-aliases.ts'
29import { servePricing } from '#/server/rate-card.ts'
30import { resolveSchemaEndpointId } from '#/server/schema-binding.ts'
31import { getServiceStatus } from '#/server/status.ts'
32import { sourceSilentEvidenceLedger } from './source-silent.ts'
33import { withSourceSilentEvidence } from './source-silent-facts.ts'
34​
35export interface ModelFilters {
36 activity?: Activity
37 provider?: string
38 /** A flag the model's capability map states as `true`. */
39 capability?: string
40 /** Free-text match against id, raw id, and display name. */
41 q?: string
42 /** Deprecated models are excluded unless set. */
43 includeDeprecated?: boolean
44 /** Include per-field `factSources` by default; false explicitly omits them. */
45 provenance?: boolean
46 /** Include the full rate card on list rows (default: compact projection). */
47 pricing?: boolean
49​
50const OPENAPI_CONTENT_TYPE = 'application/openapi+json'
51​
52function modelLinks(providerId: string) {
53 const openapi = openApiLink(providerId)
54 return {
55 provider: halGet(`/v1/providers/${providerId}/models`),
56 schemas: halGet(`/v1/schemas/${providerId}`),
57 ...(openapi ? { openapi } : {}),
58 }
60​
61function openApiLink(providerId: string) {
62 const config = getProvider(providerId)
63 if (!config?.connect) return undefined
64 const grain = resolveSpecGrain(config)
65 if (grain === 'model') {
66 return halGet(`/v1/openapi/${providerId}{?model}`, {
67 contentType: OPENAPI_CONTENT_TYPE,
68 example: `/v1/openapi/${providerId}?model=fal-ai/flux/dev`,
69 })
70 }
71 return halGet(`/v1/openapi/${providerId}`, {
72 contentType: OPENAPI_CONTENT_TYPE,
73 })
75​
76function specDescriptor(
77 providerId: string,
78 endpointCount: number,
79): { grain: SpecGrain; endpointCount: number } {
80 return {
81 grain: resolveSpecGrain(getProvider(providerId)),
82 endpointCount,
83 }
85​
86type ModelRow = typeof models.$inferSelect
87​
88const upstreamModel = alias(models, 'upstream_model')
89const catalogSelection = {
90 row: models,
91 upstream: {
92 provider: upstreamModel.providerId,
93 rawId: upstreamModel.rawId,
94 aliases: upstreamModel.aliases,
95 },
97interface UpstreamRow {
98 provider: string
99 rawId: string
100 aliases: Array<string> | null
102​
103// The stored link is only as fresh as the last reconcile, so it is served
104// only while the row's current evidence still names that target. The
105// evidence is its provenance: a link with no source, or a source with no
106// link, would each read as a claim nobody made.
107function linkMatch(
108 row: ModelRow,
109 upstream: UpstreamRow | null | undefined,
110): 'published' | 'normalized' | null {
111 const stated = row.upstreamRawId
112 if (!upstream || stated === null || !row.upstreamSource) return null
113 const ids = [upstream.rawId, ...(upstream.aliases ?? [])]
114 if (ids.includes(stated)) return 'published'
115 return ids.includes(stated.replaceAll('.', '-')) ? 'normalized' : null
117​
118function modelFactSources(
119 row: ModelRow,
120 match: ReturnType<typeof linkMatch>,
121): ModelFactSources | null {
122 const stored = (row.factSources as ModelFactSources | null) ?? null
123 if (match === null) return stored
124 const source = row.upstreamSource as FactSource
125 return {
126 ...stored,
127 sameAs: match === 'published' ? source : { ...source, normalized: true },
128 }
130​
131function encodeEndpointId(endpointId: string): string {
132 return endpointId.split('/').map(encodeURIComponent).join('/')
134​
135function toApiModel(
136 row: ModelRow,
137 opts: {
138 includeFactSources?: boolean
139 pricing?: 'compact' | 'full'
140 upstream?: UpstreamRow | null
141 } = {},
142) {
143 const schemaEndpointId = resolveSchemaEndpointId({
144 providerId: row.providerId,
145 rawId: row.rawId,
146 activity: row.activity,
147 capabilities: row.capabilities,
148 schemaEndpointId: row.schemaEndpointId,
149 })
150 const schemaPath =
151 schemaEndpointId !== null && row.activity !== null
152 ? `/v1/schemas/${row.providerId}/${row.activity}/${encodeEndpointId(schemaEndpointId)}`
153 : null
154 const schemaLink =
155 schemaPath === null
156 ? undefined
157 : halGet(schemaPath, { example: `${schemaPath}?kind=input` })
158 const match = linkMatch(row, opts.upstream)
159 return {
160 id: row.id,
161 provider: row.providerId,
162 rawId: row.rawId,
163 sameAs:
164 match && opts.upstream
165 ? { provider: opts.upstream.provider, rawId: opts.upstream.rawId }
166 : null,
167 activity: row.activity,
168 displayName: row.displayName,
169 schemaEndpointId,
170 contextWindow: row.contextWindow,
171 maxOutput: row.maxOutput,
172 modalities: row.modalities,
173 pricing: servePricing(row.pricing, opts.pricing ?? 'compact'),
174 capabilities: row.capabilities,
175 providerMetadata: row.providerMetadata,
176 reasoning: row.reasoning,
177 serverTools: row.serverTools,
178 requestMap: row.requestMap,
179 aliases: storedAliases(row.aliases),
180 releasedAt: row.releasedAt,
181 knowledgeCutoff: row.knowledgeCutoff,
182 openWeights: row.openWeights,
183 weightsUrl: row.weightsUrl,
184 firstSeenAt: row.firstSeenAt,
185 lastSeenAt: row.lastSeenAt,
186 deprecatedAt: row.deprecatedAt,
187 ...(opts.includeFactSources !== false
188 ? {
189 factSources: withSourceSilentEvidence(
190 row,
191 schemaEndpointId,
192 modelFactSources(row, match),
193 sourceSilentEvidenceLedger,
194 ),
195 }
196 : {}),
197 _links: {
198 ...modelLinks(row.providerId),
199 ...(schemaLink ? { schema: schemaLink } : {}),
200 },
201 }
203​
204export type ApiModel = ReturnType<typeof toApiModel>
205​
206/** GET /v1/providers — status, counts, spec grain, and links. */
207export async function listProvidersCatalog(db: Db) {
208 const status = await getServiceStatus(db)
209 return {
210 providers: status.providers.map((p) => {
211 const openapi = openApiLink(p.id)
212 return {
213 ...p,
214 spec: specDescriptor(p.id, p.counts.endpoints),
215 _links: {
216 models: halGet(`/v1/providers/${p.id}/models`),
217 schemas: halGet(`/v1/schemas/${p.id}`),
218 ...(openapi ? { openapi } : {}),
219 },
220 }
221 }),
222 _links: { self: halGet('/v1/providers'), catalog: halGet('/v1/models') },
223 }
225​
226/** GET /v1/models — the cross-provider, filterable catalog. */
227export async function listModelsCatalog(db: Db, filters: ModelFilters = {}) {
228 const conditions: Array<SQL> = []
229 if (!filters.includeDeprecated) conditions.push(isNull(models.deprecatedAt))
230 if (filters.activity) conditions.push(eq(models.activity, filters.activity))
231 if (filters.provider) conditions.push(eq(models.providerId, filters.provider))
232 if (filters.capability) {
233 // The flag is a bound value, quoted as one JSON path key.
234 conditions.push(
235 sql`json_extract(${models.capabilities}, ${`$.${JSON.stringify(filters.capability)}`}) = 1`,
236 )
237 }
238 if (filters.q) {
239 const needle = `%${filters.q.toLowerCase()}%`
240 const textMatch = or(
241 like(models.id, needle),
242 like(models.rawId, needle),
243 like(sql`lower(coalesce(${models.displayName}, ''))`, needle),
244 )
245 if (textMatch) conditions.push(textMatch)
246 }
247​
248 const rows = await db
249 .select(catalogSelection)
250 .from(models)
251 .leftJoin(upstreamModel, eq(models.sameAsModelId, upstreamModel.id))
252 .where(conditions.length > 0 ? and(...conditions) : undefined)
253 .orderBy(models.id)
254 return {
255 count: rows.length,
256 models: rows.map(({ row, upstream }) =>
257 toApiModel(row, {
258 includeFactSources: filters.provenance !== false,
259 pricing: filters.pricing === true ? 'full' : 'compact',
260 upstream,
261 }),
262 ),
263 _links: {
264 self: halGet(
265 '/v1/models{?activity,provider,capability,q,provenance,pricing}',
266 {
267 example: '/v1/models?activity=chat&q=claude',
268 },
269 ),
270 providers: halGet('/v1/providers'),
271 },
272 }
274​
275/** GET /v1/providers/{provider}/models. Returns null for unknown providers. */
276export async function listProviderModels(
277 db: Db,
278 providerId: string,
279 provenance = true,
280) {
281 const provider = await db.query.providers.findFirst({
282 where: eq(providers.id, providerId),
283 })
284 if (!provider) return null
285 const rows = await db
286 .select(catalogSelection)
287 .from(models)
288 .leftJoin(upstreamModel, eq(models.sameAsModelId, upstreamModel.id))
289 .where(eq(models.providerId, providerId))
290 .orderBy(models.id)
291 return {
292 provider: provider.id,
293 count: rows.length,
294 models: rows.map(({ row, upstream }) =>
295 toApiModel(row, {
296 pricing: 'compact',
297 upstream,
298 includeFactSources: provenance,
299 }),
300 ),
301 _links: modelLinks(provider.id),
302 }
304​
305/**
306 * GET /v1/models/{provider}/{modelId} — accepts the model slug or the raw
307 * provider id. Returns null when not found.
308 */
309export async function getModelDetail(
310 db: Db,
311 providerId: string,
312 modelId: string,
313) {
314 const direct = await db.query.models.findFirst({
315 where: and(
316 eq(models.providerId, providerId),
317 or(eq(models.id, modelId), eq(models.rawId, modelId)),
318 ),
319 })
320 const aliasHits = direct
321 ? []
322 : await db
323 .select()
324 .from(models)
325 .where(
326 and(
327 eq(models.providerId, providerId),
328 sql`exists (select 1 from json_each(${models.aliases}) where json_each.value = ${modelId})`,
329 ),
330 )
331 const row = direct ?? resolveAlias(modelId, aliasHits)
332 if (!row) return null
333 const [upstream] = row.sameAsModelId
334 ? await db
335 .select({
336 provider: models.providerId,
337 rawId: models.rawId,
338 aliases: models.aliases,
339 })
340 .from(models)
341 .where(eq(models.id, row.sameAsModelId))
342 : []
343 const body = toApiModel(row, {
344 includeFactSources: true,
345 pricing: 'full',
346 upstream,
347 })
348 const joinIds = openRouterJoinIds(providerId, row.rawId)
349 if (joinIds.length === 0) return { ...body, discrepancies: [] }
350 const matches = await db
351 .select()
352 .from(models)
353 .where(
354 and(eq(models.providerId, 'openrouter'), inArray(models.rawId, joinIds)),
355 )
356 const byRaw = new Map(matches.map((match) => [match.rawId, match]))
357 const openrouter = joinIds
358 .map((id) => byRaw.get(id))
359 .find((match) => match !== undefined)
360 const discrepancies = openrouter
361 ? factDiscrepancies(
362 {
363 contextWindow: row.contextWindow,
364 maxOutput: row.maxOutput,
365 modalities: row.modalities,
366 capabilities: row.capabilities,
367 factSources: (row.factSources as ModelFactSources | null) ?? null,
368 },
369 {
370 rawId: openrouter.rawId,
371 contextWindow: openrouter.contextWindow,
372 maxOutput: openrouter.maxOutput,
373 modalities: openrouter.modalities,
374 capabilities: openrouter.capabilities,
375 },
376 )
377 : []
378 return { ...body, discrepancies }
380​
381/** Valid provider ids, for 404 remediation messages. */
382export async function knownProviderIds(db: Db): Promise<Array<string>> {
383 const rows = await db.select({ id: providers.id }).from(providers)
384 return rows.map((r) => r.id).sort()