The React side: guest pages, search UI, and codegen'd types

class GuestSummary(BaseModel):
    """Card on the home page."""
    id: str = Field(description="canonical guest UUID")
    canonical_name: str
    appearance_count: int = Field(ge=0)
    popularity: float = Field(default=0.0, description="appearance + recency score (post 8)")

MODELS: list[type[BaseModel]] = [
    GuestSummary, Appearance, TopicMention, GuestQuote, GuestDetail,
    QuoteRef, Question, QuestionSet, ClipHit, SearchResponse,
]
 
def build_combined_schema() -> dict:
    definitions: dict[str, dict] = {}
    properties: dict[str, dict] = {}
    for cls in MODELS:
        schema = cls.model_json_schema(ref_template="#/definitions/{model}")
        for name, defn in (schema.pop("$defs", {}) or {}).items():
            definitions.setdefault(name, defn)
        definitions[cls.__name__] = schema
        properties[cls.__name__] = {"$ref": f"#/definitions/{cls.__name__}"}
    return {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "ClipdexApi",
        "type": "object",
        "properties": properties,
        "additionalProperties": False,
        "definitions": definitions,
    }
 
 
def main() -> None:
    # ... write web/src/generated/schema.json
    cmd = [
        pnpm, "--dir", str(root / "web"), "exec", "json2ts",
        "-i", str(schema_path), "-o", str(ts_path),
        "--no-additionalProperties",
    ]
    subprocess.run(cmd, check=True, cwd=root)

codegen:
  desc: Emit TS types from shared-schema for the web app.
  cmd: uv run --package clipdex-codegen python -m clipdex_codegen

INFO wrote web/src/generated/schema.json (10 definitions)
INFO running: pnpm --dir /…/web exec json2ts -i schema.json -o schema.ts --no-additionalProperties
INFO wrote web/src/generated/schema.ts

export interface GuestSummary { /* ... */ }
export interface Appearance   { /* ... */ }
export interface TopicMention { /* ... */ }
export interface GuestQuote   { /* ... */ }
export interface GuestDetail  { /* ... */ }
export interface QuoteRef     { /* ... */ }
export interface Question     { /* ... */ }
export interface QuestionSet  { /* ... */ }
export interface ClipHit      { /* ... */ }
export interface SearchResponse { /* ... */ }

import { useQuery, useMutation } from "@tanstack/react-query";
import type {
  GuestDetail, GuestSummary, QuestionSet, SearchResponse,
} from "../generated/schema";
 
async function fetchJson<T>(url: string): Promise<T> {
  const r = await fetch(url);
  if (!r.ok) throw new Error(`${url} -> ${r.status}`);
  return (await r.json()) as T;
}
 
export function useGuests(limit = 12) {
  return useQuery<GuestSummary[]>({
    queryKey: ["guests", limit],
    queryFn: () => fetchJson<GuestSummary[]>(`/api/guests?limit=${limit}`),
  });
}
 
export function useGuest(guestId: string | undefined) {
  return useQuery<GuestDetail>({
    enabled: !!guestId,
    queryKey: ["guest", guestId],
    queryFn: () => fetchJson<GuestDetail>(`/api/guests/${guestId}`),
  });
}
 
export function useSearch(query: string) {
  return useQuery<SearchResponse>({
    enabled: query.trim().length > 0,
    queryKey: ["search", query],
    queryFn: () =>
      fetchJson<SearchResponse>(`/api/search?q=${encodeURIComponent(query)}&n=10`),
  });
}
 
export function useGenerateQuestions(guestId: string | undefined) {
  return useMutation<QuestionSet, Error, void>({
    mutationFn: async () => {
      if (!guestId) throw new Error("guestId required");
      const r = await fetch(`/api/guests/${guestId}/questions`, { method: "POST" });
      if (!r.ok) throw new Error(`questions -> ${r.status}`);
      return (await r.json()) as QuestionSet;
    },
  });
}

import { Route, Routes } from "react-router-dom";
import { GuestPage } from "./pages/GuestPage";
import { Home } from "./pages/Home";
import { Search } from "./pages/Search";
 
export function App() {
  return (
    <Routes>
      <Route path="/" element={<Home />} />
      <Route path="/guests/:guestId" element={<GuestPage />} />
      <Route path="/search" element={<Search />} />
    </Routes>
  );
}

const { data } = useGuests(12);
// ...
<ul className="grid grid-cols-2 gap-3 sm:grid-cols-3">
  {(data ?? []).map((g) => (
    <li key={g.id} className="rounded-md border border-zinc-200 p-3 hover:bg-zinc-50">
      <Link to={`/guests/${g.id}`} className="block">
        <div className="font-medium text-zinc-900">{g.canonical_name}</div>
        <div className="mt-1 text-xs text-zinc-500">
          {g.appearance_count} appearance{g.appearance_count === 1 ? "" : "s"}
        </div>
      </Link>
    </li>
  ))}
</ul>

<ul className="mt-6 space-y-4">
  {(data?.results ?? []).map((c) => (
    <li key={`${c.video_id}-${c.seq}`} className="rounded-md border border-zinc-200 p-4">
      <div className="text-xs text-zinc-500">
        {c.video_id} · {formatMs(c.start_ms)}–{formatMs(c.end_ms)}
      </div>
      <p className="mt-1 text-sm text-zinc-800">{c.text}</p>
      {c.rerank_rationale && (
        <p className="mt-2 text-xs italic text-zinc-500">{c.rerank_rationale}</p>
      )}
      <a className="mt-2 inline-block text-xs underline text-zinc-700"
         href={c.youtube_url} target="_blank" rel="noreferrer">
        open on YouTube at {Math.floor(c.start_ms / 1000)}s
      </a>
    </li>
  ))}
</ul>

export default defineConfig({
  plugins: [react(), tailwindcss()],
  server: {
    port: 5173,
    proxy: { "/api": "http://127.0.0.1:8000" },
  },
});

dev:
  desc: Run API (:8000) and web (:5173) together.
  deps: [dev:api, dev:web]

$ task dev
# FastAPI on http://127.0.0.1:8000
# Vite on   http://127.0.0.1:5173