Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

16.4 KB
Raw Blame
'use client'

import type { LearningOrigin } from '@/lib/learning-library'
import { apiFetch, apiUrl } from '@/lib/api'
import { scopedUrl } from '@/lib/workspace-scope'
import { useCallback, useEffect, useMemo, useState } from 'react'

import { SUBAGENT_KB_TYPE } from '@/lib/knowledge-helpers'
import type { TopicSourceInput, TopicSourceKind } from '@/lib/learning-api'
import { listNotebookEntries } from '@/lib/notebook-api'
import { listPartnerGroups, listPartnerGroupSessions } from '@/lib/partner-groups-api'
import { getPartnerSessions, listPartners } from '@/lib/partners-api'

export type SourceCandidateKind = Exclude<TopicSourceKind, 'goal'>

/**
 * A row that only exists to be opened: a question-bank category, a study
 * partner, a partner group. It holds no text of its own — its children do —
 * so it renders without a checkbox and never enters the selection.
 */
export type SourceContainerKind = 'category' | 'partner' | 'partner_group_root'

export interface SourceCandidate extends LearningOrigin {
  key: string
  kind: SourceCandidateKind | SourceContainerKind
  sourceId: string
  label: string
  detail: string
  available: boolean
  /**
   * False for a container row — one that is opened rather than chosen. The
   * selection and the hydration both skip these, so a partner or a category
   * can never travel to the server as a material.
   */
  selectable?: boolean
  /** Whether opening this row fetches a child list. */
  expandable?: boolean
  /**
   * Prompt context carried from the listing that produced this row, so
   * hydration does not re-fetch what the list already showed. Only the
   * outline generator reads it; tutoring reads the real text server-side.
   */
  excerpt?: string
  /**
   * For a `file` candidate, the knowledge base it lives in.
   *
   * Both halves are needed to read it: the KB resolves access, the path
   * resolves the document inside it. `parentKey` is what lets selecting a
   * whole library and one of its files be mutually exclusive.
   */
  kbName?: string
  path?: string
  parentKey?: string
}

export interface SourceLibrary {
  books: SourceCandidate[]
  notebooks: SourceCandidate[]
  knowledgeBases: SourceCandidate[]
  /** Past conversations — what the learner has already worked through. */
  chats: SourceCandidate[]
  /** Questions from every workspace, each carrying its origin. */
  questionSets: SourceCandidate[]
  /** Co-Writer drafts — the learner's own writing on the subject. */
  drafts: SourceCandidate[]
  /** Study partners and partner groups; their transcripts load on open. */
  partners: SourceCandidate[]
  failures: string[]
}

/** What one expandable row's child list is doing right now. */
export interface SourceChildren {
  candidates: SourceCandidate[]
  loading: boolean
  error: string
}

/** @deprecated Kept as the old name for {@link SourceChildren}. */
export type KnowledgeBaseFiles = SourceChildren

const EMPTY_LIBRARY: SourceLibrary = {
  books: [],
  notebooks: [],
  knowledgeBases: [],
  chats: [],
  questionSets: [],
  drafts: [],
  partners: [],
  failures: [],
}

//: Entries listed under one question-bank category.
const MAX_CATEGORY_ENTRIES = 50

type Translate = (cn: string, en: string) => string

export function useTopicSourceLibrary(tr: Translate) {
  const [library, setLibrary] = useState<SourceLibrary>(EMPTY_LIBRARY)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    let disposed = false
    const kinds = ['books', 'notebooks', 'knowledge', 'chats', 'practice', 'drafts'] as const
    Promise.all([
      Promise.allSettled(
        kinds.map(kind =>
          sourceRequest<{ items: Record<string, unknown>[]; unavailable_workspaces: string[] }>(
            `/api/dashboard/source-library/${kind}`
          )
        )
      ),
      listPartners().catch(() => []),
      listPartnerGroups().catch(() => []),
    ]).then(([results, partners, groups]) => {
      if (disposed) return
      const failures: string[] = []
      const rows = (index: number) => {
        const result = results[index]
        if (result.status === 'rejected') {
          failures.push(kinds[index])
          return []
        }
        if (result.value.unavailable_workspaces.length) failures.push(kinds[index])
        return result.value.items
      }
      const candidate = (
        row: Record<string, unknown>,
        kind: SourceCandidateKind,
        id: unknown,
        label: unknown,
        detail: unknown = ''
      ): SourceCandidate => ({
        key: JSON.stringify([row.content_workspace_id ?? '', kind, id]),
        kind,
        sourceId: String(id),
        label: String(label || tr('Untitled', 'Untitled')),
        detail: String(detail || ''),
        content_workspace_id: String(row.content_workspace_id ?? ''),
        content_workspace_name: String(row.content_workspace_name || ''),
        available: row.available !== false && !row.unreadable,
      })
      setLibrary({
        books: rows(0).map(row => candidate(row, 'book', row.id, row.title)),
        notebooks: rows(1).map(row => candidate(row, 'notebook', row.id, row.name)),
        knowledgeBases: rows(2)
          .filter(
            row => (row.metadata as Record<string, unknown> | undefined)?.type !== SUBAGENT_KB_TYPE
          )
          .map(row => ({
            ...candidate(row, 'knowledge_base', row.id || row.name, row.name),
            expandable: true,
          })),
        chats: rows(3).map(row => ({
          ...candidate(row, 'chat', row.session_id, row.title),
          excerpt: String(row.last_message || ''),
        })),
        questionSets: rows(4).map(row => ({
          ...candidate(row, 'question_bank', row.id, row.question),
          excerpt: String(row.question || ''),
        })),
        drafts: rows(5).map(row => ({
          ...candidate(row, 'cowriter', row.id, row.title),
          excerpt: String(row.preview || ''),
        })),
        partners: [
          ...partners.map(row => ({
            key: `partner:${row.partner_id}`,
            kind: 'partner' as const,
            sourceId: row.partner_id,
            label: row.name,
            detail: '',
            available: true,
            selectable: false,
            expandable: true,
          })),
          ...groups.map(row => ({
            key: `partner_group_root:${row.group_id}`,
            kind: 'partner_group_root' as const,
            sourceId: row.group_id,
            label: row.name,
            detail: '',
            available: true,
            selectable: false,
            expandable: true,
          })),
        ],
        failures,
      })
      setLoading(false)
    })
    return () => {
      disposed = true
    }
  }, [tr])

  // Child lists are fetched per row, only when the learner opens one: a
  // workspace with a dozen libraries, categories and partners would otherwise
  // pay for every listing to answer a question about one of them.
  const [childLists, setChildLists] = useState<Record<string, SourceChildren>>({})

  const loadChildren = useCallback(
    async (candidate: SourceCandidate) => {
      const parentKey = candidate.key
      setChildLists(previous =>
        previous[parentKey]?.candidates.length
          ? previous
          : {
              ...previous,
              [parentKey]: { candidates: [], loading: true, error: '' },
            }
      )
      try {
        const listed = await fetchChildren(candidate, tr)
        setChildLists(previous => ({
          ...previous,
          [parentKey]: { loading: false, error: '', candidates: listed },
        }))
      } catch (reason) {
        setChildLists(previous => ({
          ...previous,
          [parentKey]: {
            candidates: [],
            loading: false,
            error:
              reason instanceof Error
                ? reason.message
                : tr('无法读取列表', 'Could not load the list'),
          },
        }))
      }
    },
    [tr]
  )

  const candidates = useMemo(
    () =>
      [
        ...library.books,
        ...library.notebooks,
        ...library.knowledgeBases,
        ...library.chats,
        ...library.questionSets,
        ...library.drafts,
        ...library.partners,
        ...Object.values(childLists).flatMap(entry => entry.candidates),
        // Containers are opened, never chosen — keeping them out here means
        // neither the selection nor hydration has to know about them.
      ].filter(candidate => candidate.selectable !== false),
    [library, childLists]
  )
  return { library, loading, candidates, childLists, loadChildren }
}

/** One expandable row's children, by kind. Throws so the caller can show why. */
async function fetchChildren(
  candidate: SourceCandidate,
  tr: Translate
): Promise<SourceCandidate[]> {
  const parentKey = candidate.key
  if (candidate.kind === 'knowledge_base') {
    const kbName = candidate.sourceId
    const { files: listed } = await sourceRequest<{
      files: import('@/features/knowledge/model/types').KnowledgeBaseFile[]
    }>(
      `/api/knowledge-bases/${encodeURIComponent(kbName)}/files?resource_library=true`,
      candidate.content_workspace_id
    )
    return (
      listed
        // Folders are organisational only — they hold no text to ground an
        // outline in, and their files are listed by full path anyway.
        .filter(entry => entry.type !== 'folder')
        .map(entry => ({
          key: JSON.stringify([candidate.content_workspace_id ?? '', 'file', kbName, entry.name]),
          kind: 'file' as const,
          sourceId: entry.name,
          label: entry.name,
          detail: tr(`${kbName} 中的文件`, `File in ${kbName}`),
          available: true,
          kbName,
          path: entry.name,
          parentKey,
          content_workspace_id: candidate.content_workspace_id,
          content_workspace_name: candidate.content_workspace_name,
        }))
    )
  }
  if (candidate.kind === 'category') {
    const { items } = await listNotebookEntries({
      category_id: Number(candidate.sourceId),
      limit: MAX_CATEGORY_ENTRIES,
    })
    return items.map(entry => ({
      key: `question_bank:${entry.id}`,
      kind: 'question_bank' as const,
      sourceId: String(entry.id),
      label: entry.question.slice(0, 80) || tr('未命名题目', 'Untitled question'),
      detail: entry.is_correct
        ? tr('已答对', 'Answered correctly')
        : tr('答错过', 'Answered wrong'),
      available: true,
      excerpt: entry.question,
      parentKey,
    }))
  }
  if (candidate.kind === 'partner') {
    const sessions = await getPartnerSessions(candidate.sourceId)
    return sessions.map(session => ({
      key: `chat:partner:${candidate.sourceId}:${session.session_key}`,
      kind: 'chat' as const,
      // The reference form chat's own transcript reader understands.
      sourceId: `partner:${candidate.sourceId}:${session.session_key}`,
      label: session.title || tr('未命名对话', 'Untitled conversation'),
      detail: tr(`${session.message_count} 条消息`, `${session.message_count} messages`),
      available: true,
      excerpt: session.last_message || '',
      parentKey,
    }))
  }
  if (candidate.kind === 'partner_group_root') {
    const sessions = await listPartnerGroupSessions(candidate.sourceId)
    return sessions.map(session => ({
      key: `partner_group:${candidate.sourceId}:${session.session_key}`,
      kind: 'partner_group' as const,
      sourceId: `${candidate.sourceId}:${session.session_key}`,
      label: session.title || tr('未命名讨论', 'Untitled discussion'),
      detail: tr(`${session.message_count} 条消息`, `${session.message_count} messages`),
      available: true,
      parentKey,
    }))
  }
  return []
}

/**
 * Add or remove one source from the selection.
 *
 * The rule that needs stating: selecting a whole knowledge base drops the
 * individual documents picked out of it. Sending both means the same material
 * arrives twice — once as retrieval over the library, once as extracted file
 * text — and is counted twice when the outline's coverage is measured.
 *
 * Pure, and exported, so the wizard and its test cannot disagree about it.
 */
export function toggleSourceSelection(
  selected: Set<string>,
  key: string,
  candidates: readonly SourceCandidate[]
): Set<string> {
  const next = new Set(selected)
  if (next.has(key)) {
    next.delete(key)
    return next
  }
  next.add(key)
  for (const candidate of candidates) {
    if (candidate.parentKey === key) next.delete(candidate.key)
  }
  return next
}

/** Resolve a selected source to bounded prompt context; failures stay visible. */
export async function hydrateTopicSource(candidate: SourceCandidate): Promise<TopicSourceInput> {
  const source = await hydrateSource(candidate)
  return candidate.content_workspace_id === undefined
    ? source
    : {
        ...source,
        metadata: { ...source.metadata, content_workspace_id: candidate.content_workspace_id },
      }
}

async function hydrateSource(candidate: SourceCandidate): Promise<TopicSourceInput> {
  try {
    if (candidate.kind === 'book') {
      const { spine } = await sourceRequest<{
        spine: { chapters: { title: string; learning_objectives: string[]; summary: string }[] }
      }>(
        `/api/books/${encodeURIComponent(candidate.sourceId)}/spine`,
        candidate.content_workspace_id
      )
      return {
        kind: 'book',
        source_id: candidate.sourceId,
        label: candidate.label,
        excerpt: spine.chapters
          .map(
            chapter =>
              `${chapter.title}: ${[...chapter.learning_objectives, chapter.summary]
                .filter(Boolean)
                .join('; ')}`
          )
          .join('\n')
          .slice(0, 8_000),
        available: true,
        metadata: { chapter_count: spine.chapters.length },
      }
    }
    if (candidate.kind === 'notebook') {
      const notebook = await sourceRequest<import('@/lib/notebook-api').NotebookDetail>(
        `/api/notebooks/${encodeURIComponent(candidate.sourceId)}`,
        candidate.content_workspace_id
      )
      return {
        kind: 'notebook',
        source_id: candidate.sourceId,
        label: candidate.label,
        excerpt: notebook.records
          .slice(0, 16)
          .map(
            record =>
              `${record.title}\n${record.summary || record.user_query || ''}\n${record.output || ''}`
          )
          .join('\n\n')
          .slice(0, 8_000),
        available: true,
        metadata: { record_count: notebook.records.length },
      }
    }
    if (candidate.kind === 'file') {
      // No excerpt: the browser cannot read a PDF out of the knowledge base,
      // so the server extracts the text while grounding the outline (see
      // `_ground_file_source`). What travels from here is the address.
      return {
        kind: 'file',
        source_id: candidate.path || candidate.sourceId,
        label: candidate.label,
        excerpt: '',
        available: candidate.available,
        metadata: {
          kb_name: candidate.kbName || '',
          path: candidate.path || candidate.sourceId,
        },
      }
    }
    if (
      candidate.kind === 'chat' ||
      candidate.kind === 'question_bank' ||
      candidate.kind === 'cowriter' ||
      candidate.kind === 'partner_group'
    ) {
      // The listing already showed enough to ground an outline, and the full
      // text is read server-side during tutoring — so hydration here is an
      // address plus what the learner just looked at, not another fetch.
      return {
        kind: candidate.kind,
        source_id: candidate.sourceId,
        label: candidate.label,
        excerpt: (candidate.excerpt || candidate.detail).slice(0, 4_000),
        available: candidate.available,
      }
    }
    return {
      kind: 'knowledge_base',
      source_id: candidate.sourceId,
      label: candidate.label,
      excerpt: candidate.detail,
      available: candidate.available,
    }
  } catch {
    return {
      // Containers never reach hydration (they are filtered out of
      // `candidates`), so the cast is narrowing a type, not a guess.
      kind: candidate.kind as TopicSourceKind,
      source_id: candidate.sourceId,
      label: candidate.label,
      excerpt: '',
      available: false,
      metadata: { unavailable_during_generation: true },
    }
  }
}

export async function sourceRequest<T>(path: string, workspaceId?: string): Promise<T> {
  const response = await apiFetch(apiUrl(scopedUrl(path, workspaceId)), { cache: 'no-store' })
  if (!response.ok) throw new Error(`Could not load source (${response.status})`)
  return response.json() as Promise<T>
}