Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

4.3 KB
Raw Blame
import { create } from 'zustand'
import { useCallback, useEffect, useMemo } from 'react'
import { useAppStore } from './appStore'

export interface LlmModel {
  id:                string
  name:              string
  description?:      string
  hf_filename:        string
  size_bytes?:        number
  quant?:             string
  vram_estimate_mb?:  number
  downloaded:         boolean
  source:             'catalog' | 'custom'
  tags?:              string[]
  /** How well this model drives the agent, see components/ui/agentGrade.ts.
   *  `agent_score` is only shown when `agent_source` is 'measured', i.e. the
   *  model was actually run against three.ws Forge's own eval suite. */
  agent_tier?:        'excellent' | 'solid' | 'limited'
  agent_score?:       number
  agent_source?:      'measured' | 'estimate'
  agent_note?:        string
}

interface LlmModelsStore {
  models:        LlmModel[]
  loading:       boolean
  error:         string | null
  fetchedApiUrl: string | null
  fetchModels:   (apiUrl: string, opts?: { force?: boolean }) => Promise<void>
}

// Module-level so concurrent callers (multiple nodes/components mounting at
// once) share one in-flight request instead of firing N identical fetches.
let inFlight: Promise<void> | null = null
// Identifies the request currently owning `inFlight`, so a superseded one does
// not clear a newer forced refresh on its way out.
let inFlightId = 0

export const useLlmModelsStore = create<LlmModelsStore>((set, get) => ({
  models:        [],
  loading:       false,
  error:         null,
  fetchedApiUrl: null,

  async fetchModels(apiUrl, opts) {
    const state = get()
    if (!opts?.force && state.fetchedApiUrl === apiUrl && state.models.length > 0) return
    // A forced refresh follows a mutation (download finished, model deleted), so
    // it must not settle for a request issued BEFORE it: joining the in-flight
    // one kept the pre-mutation `downloaded` flags, and the preflight went on
    // reporting "…isn't downloaded" for a model that had just landed.
    const pending = inFlight
    if (pending && !opts?.force) return pending

    set({ loading: true, error: null })
    const id = ++inFlightId
    const request = (async () => {
      if (pending) {
        await pending.catch(() => {})
        set({ loading: true, error: null })  // the request we waited on may have failed
      }
      try {
        const res = await fetch(`${apiUrl}/llm/models`)
        const data: { models?: LlmModel[] } = await res.json()
        set({ models: data.models ?? [], fetchedApiUrl: apiUrl, loading: false, error: null })
      } catch (e) {
        set({ error: e instanceof Error ? e.message : String(e), loading: false })
      } finally {
        if (inFlightId === id) inFlight = null
      }
    })()
    inFlight = request
    return request
  },
}))

/**
 * Shared local-LLM catalog: fetched once per apiUrl and cached across every
 * consumer (LLM node, extension param pickers, chat model picker, Settings…)
 * instead of each component firing its own `/llm/models` request.
 *
 * `tag` mirrors the backend's own filter (`GET /llm/models?tag=`): custom
 * GGUFs are always kept since their capabilities aren't known ahead of time.
 */
export function useLlmModels(tag?: string): {
  models:  LlmModel[]
  loading: boolean
  error:   string | null
  refresh: () => Promise<void>
} {
  const apiUrl      = useAppStore((s) => s.apiUrl)
  const models      = useLlmModelsStore((s) => s.models)
  const loading     = useLlmModelsStore((s) => s.loading)
  const error       = useLlmModelsStore((s) => s.error)
  const fetchModels = useLlmModelsStore((s) => s.fetchModels)

  useEffect(() => { void fetchModels(apiUrl) }, [apiUrl, fetchModels])

  // Both memoised because callers put them in dependency arrays. A `refresh`
  // rebuilt on every render made ModelLibraryModal's `useEffect(…, [refresh])`
  // re-run on every render: each pass forced a /llm/models + /llm/status fetch,
  // whose setState triggered the next one. The modal flickered and hammered the
  // API for as long as it stayed open.
  const filtered = useMemo(
    () => (tag ? models.filter((m) => m.source === 'custom' || (m.tags ?? []).includes(tag)) : models),
    [models, tag],
  )
  const refresh = useCallback(() => fetchModels(apiUrl, { force: true }), [apiUrl, fetchModels])

  return { models: filtered, loading, error, refresh }
}