Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { authFetch } from "@/features/auth";
import { apiUrl } from "@/lib/api-base";
import { formatFastApiDetail } from "@/lib/format-fastapi-error";
import { openStreamResponse } from "@/lib/open-stream-response";
import { readSseJsonEvents } from "@/lib/sse-json-events";
import type {
DocumentUploadResult,
FolderSyncJob,
FolderSyncJobEvent,
IndexJob,
JobEvent,
KnowledgeBase,
LinkedFolder,
LinkedFolderScope,
RagDocument,
ReembedJob,
ReembedStatus,
UploadedDocument,
} from "../types/rag";
import { noteRagAvailability, noteRagResponse } from "./rag-availability";
const RAG_BASE = "/api/rag";
function parseErrorText(status: number, body: unknown): string {
if (body && typeof body === "object") {
const { detail, message } = body as { detail?: unknown; message?: unknown };
const formatted = formatFastApiDetail(detail);
if (formatted) return formatted;
if (typeof message === "string" && message) return message;
}
return `Request failed (${status})`;
}
export function ragError(status: number, body: unknown): Error & { status: number } {
return Object.assign(new Error(parseErrorText(status, body)), { status });
}
/** True for a definitive server answer, so retrying cannot help. */
export function isRagClientError(error: unknown): boolean {
const status = (error as { status?: unknown } | null)?.status;
return typeof status === "number" && status >= 400 && status < 500 && status !== 429;
}
async function ragRequest<T>(
path: string,
init?: { method?: string; body?: object; signal?: AbortSignal },
): Promise<T> {
const response = await authFetch(`${RAG_BASE}${path}`, {
method: init?.method,
headers: init?.body ? { "Content-Type": "application/json" } : undefined,
body: init?.body ? JSON.stringify(init.body) : undefined,
signal: init?.signal,
});
if (response.status === 204) {
noteRagResponse(204, null);
return undefined as T;
}
const json = await response.json().catch(() => null);
// Every RAG endpoint but the list gates on the extension, so its status reports availability.
noteRagResponse(response.status, json);
if (!response.ok) throw ragError(response.status, json);
return json as T;
}
export interface NativeUploadRef {
nativePathLease: string;
}
export type UploadSource = File | NativeUploadRef;
async function ragUpload(
path: string,
source: UploadSource,
ocr?: boolean,
caption?: boolean,
): Promise<DocumentUploadResult> {
const form = new FormData();
if (source instanceof File) form.append("file", source);
else form.append("nativePathLease", source.nativePathLease);
if (ocr !== undefined) form.append("ocr", String(ocr));
if (caption !== undefined) form.append("caption", String(caption));
// No Content-Type: let the browser set the multipart boundary.
const response = await authFetch(`${RAG_BASE}${path}`, {
method: "POST",
body: form,
});
const json = await response.json().catch(() => null);
noteRagResponse(response.status, json);
if (!response.ok) throw ragError(response.status, json);
return json as DocumentUploadResult;
}
/** Not gated on sqlite-vec, so its status says nothing about RAG availability. */
export async function extractDocumentText(
file: File,
beforeRetry?: () => void,
): Promise<{ text: string; truncated: boolean }> {
const form = new FormData();
form.append("file", file);
const response = await authFetch(
`${RAG_BASE}/extract-text`,
{ method: "POST", body: form },
{ beforeRetry },
);
const json = await response.json().catch(() => null);
if (!response.ok) throw ragError(response.status, json);
return json as { text: string; truncated: boolean };
}
export async function listKnowledgeBases(): Promise<KnowledgeBase[]> {
const data = await ragRequest<{
knowledgeBases: KnowledgeBase[];
ragAvailable?: boolean;
ragUnavailableReason?: string | null;
}>("/knowledge-bases");
// The only endpoint that returns 200 instead of 503 when RAG cannot run; the marker tells them apart.
noteRagAvailability(data);
return data.knowledgeBases ?? [];
}
export const KNOWLEDGE_BASES_CHANGED_EVENT = "unsloth-knowledge-bases-changed";
// Also on failure: a delete can fail because the row is already gone.
function announceKnowledgeBasesChanged(): void {
if (typeof window === "undefined") return;
window.dispatchEvent(new Event(KNOWLEDGE_BASES_CHANGED_EVENT));
}
export function subscribeKnowledgeBasesChanged(
onChanged: () => void,
): () => void {
if (typeof window === "undefined") return () => undefined;
window.addEventListener(KNOWLEDGE_BASES_CHANGED_EVENT, onChanged);
return () => window.removeEventListener(KNOWLEDGE_BASES_CHANGED_EVENT, onChanged);
}
export function createKnowledgeBase(payload: {
name: string;
description?: string;
}): Promise<{ id: string; name: string }> {
return ragRequest<{ id: string; name: string }>("/knowledge-bases", {
method: "POST",
body: {
name: payload.name,
...(payload.description ? { description: payload.description } : {}),
},
}).finally(announceKnowledgeBasesChanged);
}
export function updateKnowledgeBase(
kbId: string,
payload: { name?: string; description?: string },
): Promise<{ ok: boolean }> {
const body: Record<string, unknown> = {};
if (payload.name !== undefined) body.name = payload.name;
if (payload.description !== undefined) body.description = payload.description;
return ragRequest<{ ok: boolean }>(
`/knowledge-bases/${encodeURIComponent(kbId)}`,
{ method: "PATCH", body },
).finally(announceKnowledgeBasesChanged);
}
export function deleteKnowledgeBase(kbId: string): Promise<{ ok: boolean }> {
return ragRequest<{ ok: boolean }>(
`/knowledge-bases/${encodeURIComponent(kbId)}`,
{ method: "DELETE" },
).finally(announceKnowledgeBasesChanged);
}
export async function listKnowledgeBaseDocuments(
kbId: string,
): Promise<RagDocument[]> {
const data = await ragRequest<{ documents: RagDocument[] }>(
`/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
);
return data.documents ?? [];
}
export function uploadKnowledgeBaseDocument(
kbId: string,
file: UploadSource,
ocr?: boolean,
caption?: boolean,
): Promise<DocumentUploadResult> {
return ragUpload(
`/knowledge-bases/${encodeURIComponent(kbId)}/documents`,
file,
ocr,
caption,
);
}
export async function listThreadDocuments(
threadId: string,
): Promise<RagDocument[]> {
const data = await ragRequest<{ documents: RagDocument[] }>(
`/threads/${encodeURIComponent(threadId)}/documents`,
);
return data.documents ?? [];
}
export function uploadThreadDocument(
threadId: string,
file: UploadSource,
ocr?: boolean,
caption?: boolean,
): Promise<DocumentUploadResult> {
return ragUpload(
`/threads/${encodeURIComponent(threadId)}/documents`,
file,
ocr,
caption,
);
}
export async function listProjectDocuments(
projectId: string,
): Promise<RagDocument[]> {
const data = await ragRequest<{ documents: RagDocument[] }>(
`/projects/${encodeURIComponent(projectId)}/documents`,
);
return data.documents ?? [];
}
export function uploadProjectDocument(
projectId: string,
file: UploadSource,
ocr?: boolean,
caption?: boolean,
): Promise<DocumentUploadResult> {
return ragUpload(
`/projects/${encodeURIComponent(projectId)}/documents`,
file,
ocr,
caption,
);
}
const projectSourcesCache = new Map<string, { has: boolean; at: number }>();
const PROJECT_SOURCES_TTL_MS = 30_000;
export async function projectHasSources(projectId: string): Promise<boolean> {
const cached = projectSourcesCache.get(projectId);
if (cached && Date.now() - cached.at < PROJECT_SOURCES_TTL_MS) {
return cached.has;
}
try {
const docs = await listProjectDocuments(projectId);
const has = docs.some((doc) => doc.status !== "failed");
projectSourcesCache.set(projectId, { has, at: Date.now() });
return has;
} catch {
return false;
}
}
/** The composer bar and the Sources panel are separate hooks over one scope. */
export const PROJECT_SOURCES_CHANGED_EVENT = "unsloth-project-sources-changed";
/** Legacy alias kept for existing listeners. */
export const PROJECT_SOURCES_UPDATED_EVENT = PROJECT_SOURCES_CHANGED_EVENT;
/** Only drops the cache: callers also invalidate before mutating, where a refetch would resurrect a row. */
export function invalidateProjectSources(projectId: string): void {
projectSourcesCache.delete(projectId);
}
export function announceProjectSourcesUpdated(projectId: string): void {
publishProjectSourcesChanged(projectId);
getProjectChannel()?.postMessage({ kind: "sources", projectId });
}
export function subscribeProjectSourcesUpdated(
projectId: string,
onUpdated: () => void,
): () => void {
if (typeof window === "undefined") return () => undefined;
const listener = (event: Event) => {
const detail = (event as CustomEvent<{ projectId?: string }>).detail;
if (detail?.projectId === projectId) onUpdated();
};
window.addEventListener(PROJECT_SOURCES_CHANGED_EVENT, listener);
subscribeProjectSourcesBroadcast();
return () => {
window.removeEventListener(PROJECT_SOURCES_CHANGED_EVENT, listener);
};
}
function publishProjectSourcesChanged(projectId: string): void {
projectSourcesCache.delete(projectId);
if (typeof window === "undefined") return;
window.dispatchEvent(
new CustomEvent(PROJECT_SOURCES_CHANGED_EVENT, { detail: { projectId } }),
);
}
/** CustomEvent reaches only its own tab, so other tabs hear changes here. Opened lazily. */
let projectChannel: BroadcastChannel | null | undefined;
function getProjectChannel(): BroadcastChannel | null {
if (projectChannel !== undefined) {
return projectChannel;
}
if (
typeof window === "undefined" ||
typeof BroadcastChannel === "undefined"
) {
projectChannel = null;
return null;
}
projectChannel = new BroadcastChannel(PROJECT_SOURCES_CHANGED_EVENT);
// Node's BroadcastChannel holds the event loop open and hangs a test run.
(projectChannel as { unref?: () => void }).unref?.();
projectChannel.onmessage = (event: MessageEvent) => {
const message = event.data as {
kind?: string;
projectId?: string;
delta?: number;
count?: number;
from?: string;
} | null;
if (!message) {
return;
}
if (message.kind === "work-query") {
answerWorkQuery();
return;
}
if (!message.projectId) {
return;
}
if (message.kind === "work-state" && message.from) {
seedRemoteProjectWork(
message.projectId,
message.from,
message.count ?? 0,
);
return;
}
if (message.kind === "work" && message.from) {
noteRemoteProjectWork(
message.projectId,
message.from,
message.delta ?? 0,
);
return;
}
if (message.kind === "work" || message.kind === "work-state") {
return;
}
publishProjectSourcesChanged(message.projectId);
};
askForWorkInFlight();
return projectChannel;
}
/** BroadcastChannel does not replay, so a tab opening mid-upload asks for work in flight. */
function askForWorkInFlight(): void {
projectChannel?.postMessage({ kind: "work-query" });
}
function answerWorkQuery(): void {
const channel = getProjectChannel();
if (!channel) return;
for (const [projectId, count] of projectWorkInFlight) {
channel.postMessage({ kind: "work-state", projectId, count, from: TAB_ID });
}
}
/** Per-tab id: a merged count would let the first upload to finish release the second. */
const TAB_ID = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
export function subscribeProjectSourcesBroadcast(): void {
getProjectChannel();
}
/**
* Work in flight per project, so the composer gates sends on uploads and folder syncs
* started elsewhere that have no row yet.
*/
const projectWorkInFlight = new Map<string, number>();
export const PROJECT_WORK_CHANGED_EVENT = "unsloth-project-work-changed";
export function noteProjectWork(projectId: string, delta: number): void {
const next = (projectWorkInFlight.get(projectId) ?? 0) + delta;
if (next > 0) {
projectWorkInFlight.set(projectId, next);
} else {
projectWorkInFlight.delete(projectId);
}
getProjectChannel()?.postMessage({
kind: "work",
projectId,
delta,
from: TAB_ID,
});
syncWorkHeartbeat();
publishProjectWorkChanged(projectId);
}
/** Heartbeat sends the absolute count, since a zero delta cannot revive a lapsed entry. */
const WORK_HEARTBEAT_MS = 45_000;
let workHeartbeat: ReturnType<typeof setInterval> | null = null;
function syncWorkHeartbeat(): void {
if (projectWorkInFlight.size === 0) {
if (workHeartbeat !== null) {
clearInterval(workHeartbeat);
workHeartbeat = null;
}
return;
}
if (workHeartbeat !== null) {
return;
}
workHeartbeat = setInterval(answerWorkQuery, WORK_HEARTBEAT_MS);
(workHeartbeat as { unref?: () => void }).unref?.();
}
function publishProjectWorkChanged(projectId: string): void {
if (typeof window === "undefined") {
return;
}
window.dispatchEvent(
new CustomEvent(PROJECT_WORK_CHANGED_EVENT, { detail: { projectId } }),
);
}
/** Another tab's work expires: only its starter reports the end, and it may close first. */
const REMOTE_WORK_TTL_MS = 120_000;
/** Per project, per tab: aggregated, the first upload to finish would clear the second's count. */
const remoteProjectWork = new Map<
string,
Map<string, { count: number; until: number }>
>();
const remoteWorkTimers = new Map<string, ReturnType<typeof setTimeout>>();
function armRemoteWorkExpiry(projectId: string): void {
const timer = remoteWorkTimers.get(projectId);
if (timer !== undefined) {
clearTimeout(timer);
}
remoteWorkTimers.delete(projectId);
const bySender = remoteProjectWork.get(projectId);
if (!bySender || bySender.size === 0) return;
// Arm for the earliest sender deadline, or a closed tab stays counted until some later event.
let earliest = Number.POSITIVE_INFINITY;
for (const entry of bySender.values()) {
earliest = Math.min(earliest, entry.until);
}
const expiry = setTimeout(
() => {
remoteWorkTimers.delete(projectId);
const now = Date.now();
const live = remoteProjectWork.get(projectId);
if (live) {
for (const [sender, entry] of live) {
if (entry.until <= now) live.delete(sender);
}
if (live.size === 0) remoteProjectWork.delete(projectId);
}
publishProjectWorkChanged(projectId);
armRemoteWorkExpiry(projectId);
},
Math.max(0, earliest - Date.now()),
);
// A pending timer would hold a Node test run open.
(expiry as { unref?: () => void }).unref?.();
remoteWorkTimers.set(projectId, expiry);
}
function setRemoteProjectWork(
projectId: string,
from: string,
count: number,
): void {
const bySender = remoteProjectWork.get(projectId) ?? new Map();
if (count <= 0) {
bySender.delete(from);
} else {
bySender.set(from, { count, until: Date.now() + REMOTE_WORK_TTL_MS });
}
if (bySender.size === 0) {
remoteProjectWork.delete(projectId);
const timer = remoteWorkTimers.get(projectId);
if (timer !== undefined) {
clearTimeout(timer);
remoteWorkTimers.delete(projectId);
}
} else {
remoteProjectWork.set(projectId, bySender);
armRemoteWorkExpiry(projectId);
}
publishProjectWorkChanged(projectId);
}
function remoteSenderCount(projectId: string, from: string): number {
const entry = remoteProjectWork.get(projectId)?.get(from);
return entry && entry.until > Date.now() ? entry.count : 0;
}
function noteRemoteProjectWork(
projectId: string,
from: string,
delta: number,
): void {
const current = remoteSenderCount(projectId, from);
// A zero delta is the heartbeat: it only renews this sender's deadline.
if (delta === 0 && current === 0) return;
setRemoteProjectWork(projectId, from, Math.max(0, current + delta));
}
/** Absolute count from a tab; never lowers a delta-raised count and revives a lapsed entry. */
function seedRemoteProjectWork(
projectId: string,
from: string,
count: number,
): void {
if (count <= 0) return;
setRemoteProjectWork(projectId, from, Math.max(remoteSenderCount(projectId, from), count));
}
export function projectWorkCount(projectId: string): number {
let remoteCount = 0;
const now = Date.now();
for (const entry of remoteProjectWork.get(projectId)?.values() ?? []) {
if (entry.until > now) remoteCount += entry.count;
}
return (projectWorkInFlight.get(projectId) ?? 0) + remoteCount;
}
const MAX_FOLDER_JOB_READ_FAILURES = 20;
const watchedFolderJobs = new Set<string>();
/** Tied to the backend job, not its starter, since leaving the Sources tab does not stop the sync. */
export function watchProjectFolderJob(projectId: string, jobId: string): void {
if (watchedFolderJobs.has(jobId)) {
return;
}
watchedFolderJobs.add(jobId);
noteProjectWork(projectId, 1);
void (async () => {
// A failed read is not a finished job: a backend restart can miss a tick.
let consecutiveFailures = 0;
try {
for (let attempt = 0; attempt < 600; attempt += 1) {
try {
const job = await getFolderSyncJob(jobId);
consecutiveFailures = 0;
if (job.status === "completed" || job.status === "failed") {
break;
}
} catch (error) {
// An answered 4xx means the job rows are gone (unlink or history prune).
if (isRagClientError(error)) break;
consecutiveFailures += 1;
if (consecutiveFailures >= MAX_FOLDER_JOB_READ_FAILURES) {
break;
}
}
await new Promise((resolve) => setTimeout(resolve, 3000));
}
} finally {
watchedFolderJobs.delete(jobId);
// Announce before releasing the gate, or a released send reads the cached "no sources".
announceProjectSourcesUpdated(projectId);
noteProjectWork(projectId, -1);
}
})();
}
/** Throttles lookups: two bars mount at once, and later backend jobs must still be seen. */
const folderReconcileNotBefore = new Map<string, number>();
/** Shorter than the backend scan interval, so a periodic caller is never skipped. */
const FOLDER_RECONCILE_MIN_GAP_MS = 5000;
/**
* Pick up folder syncs already running (e.g. after a reload): the backend scans before
* writing rows, so the composer's list cannot see them.
*/
export async function reconcileProjectFolderJobs(
projectId: string,
): Promise<void> {
const now = Date.now();
if ((folderReconcileNotBefore.get(projectId) ?? 0) > now) return;
folderReconcileNotBefore.set(projectId, now + FOLDER_RECONCILE_MIN_GAP_MS);
noteProjectWork(projectId, 1);
try {
const folders = await listLinkedFolders({ type: "project", id: projectId });
for (const folder of folders) {
if (folder.activeJobId) {
watchProjectFolderJob(projectId, folder.activeJobId);
}
}
} catch {
// Do not record a project as reconciled on an answer that never came.
folderReconcileNotBefore.delete(projectId);
} finally {
noteProjectWork(projectId, -1);
}
}
export async function listLinkedFolders(
scope?: LinkedFolderScope,
): Promise<LinkedFolder[]> {
const query = scope
? `?scope_type=${encodeURIComponent(scope.type)}&scope_id=${encodeURIComponent(scope.id)}`
: "";
const data = await ragRequest<{ linkedFolders: LinkedFolder[] }>(
`/linked-folders${query}`,
);
return data.linkedFolders ?? [];
}
interface LinkedFolderMutationResult {
linkedFolder: LinkedFolder;
job: FolderSyncJob;
}
export function createLinkedFolder(
scope: LinkedFolderScope,
nativePathLease: string,
displayName: string,
): Promise<LinkedFolderMutationResult> {
const parent =
scope.type === "knowledge_base" ? "knowledge-bases" : "projects";
return ragRequest(
`/${parent}/${encodeURIComponent(scope.id)}/linked-folders`,
{
method: "POST",
body: { nativePathLease, displayName },
},
);
}
export function deleteLinkedFolder(
linkedFolderId: string,
removeIndex: boolean,
): Promise<{ ok: boolean }> {
return ragRequest(
`/linked-folders/${encodeURIComponent(linkedFolderId)}?remove_index=${removeIndex}`,
{ method: "DELETE" },
);
}
function startLinkedFolderJob(
linkedFolderId: string,
action: "sync" | "rebuild",
): Promise<{ job: FolderSyncJob }> {
return ragRequest(
`/linked-folders/${encodeURIComponent(linkedFolderId)}/${action}`,
{ method: "POST" },
);
}
export function syncLinkedFolder(
linkedFolderId: string,
): Promise<{ job: FolderSyncJob }> {
return startLinkedFolderJob(linkedFolderId, "sync");
}
export function rebuildLinkedFolder(
linkedFolderId: string,
): Promise<{ job: FolderSyncJob }> {
return startLinkedFolderJob(linkedFolderId, "rebuild");
}
export function getFolderSyncJob(jobId: string): Promise<FolderSyncJob> {
return ragRequest(`/linked-folder-jobs/${encodeURIComponent(jobId)}`);
}
export async function listAllDocuments(): Promise<UploadedDocument[]> {
const data = await ragRequest<{ documents: UploadedDocument[] }>(
"/documents",
);
return data.documents ?? [];
}
export async function deleteDocument(
documentId: string,
projectId?: string | null,
): Promise<{ ok: boolean }> {
const result = await ragRequest<{ ok: boolean }>(
`/documents/${encodeURIComponent(documentId)}`,
{
method: "DELETE",
},
);
if (projectId) announceProjectSourcesUpdated(projectId);
return result;
}
export function getReembedStatus(): Promise<ReembedStatus> {
return ragRequest("/reembed");
}
export function startReembed(): Promise<{ job: ReembedJob }> {
return ragRequest("/reembed", { method: "POST" });
}
export function cancelReembed(): Promise<{ job: ReembedJob }> {
return ragRequest("/reembed/cancel", { method: "POST" });
}
export function getJob(jobId: string, signal?: AbortSignal): Promise<IndexJob> {
return ragRequest(`/jobs/${encodeURIComponent(jobId)}`, { signal });
}
const SSE_STALL_MS = 12000;
async function openEventStream(
url: string,
signal: AbortSignal | undefined,
): Promise<ReadableStream<Uint8Array>> {
const response = await openStreamResponse(authFetch, url, { signal });
if (!response.ok) {
const body = await response.json().catch(() => null);
noteRagResponse(response.status, body);
throw ragError(response.status, body);
}
if (!response.body) throw new Error("Stream response missing body");
return response.body;
}
// HTTP/1.1 allows six connections per origin; one shared budget keeps upload POSTs from stalling.
const MAX_RAG_STREAMS = 4;
let activeRagStreams = 0;
async function* boundedEventStream<T>(
path: string,
signal?: AbortSignal,
stallMs?: number,
): AsyncGenerator<T> {
if (activeRagStreams >= MAX_RAG_STREAMS) {
throw new Error("RAG stream capacity reached");
}
activeRagStreams += 1;
try {
const body = await openEventStream(`${RAG_BASE}${path}`, signal);
yield* readSseJsonEvents<T>(body, stallMs);
} finally {
activeRagStreams -= 1;
}
}
// Returns on [DONE]; transport errors propagate so callers can poll getJob.
export function streamJobEvents(
jobId: string,
signal?: AbortSignal,
): AsyncGenerator<JobEvent> {
// No stall bound: this consumer reads an early end as a finished job.
return boundedEventStream<JobEvent>(
`/jobs/${encodeURIComponent(jobId)}/events`,
signal,
);
}
export function streamFolderSyncJobEvents(
jobId: string,
signal?: AbortSignal,
): AsyncGenerator<FolderSyncJobEvent> {
return boundedEventStream<FolderSyncJobEvent>(
`/linked-folder-jobs/${encodeURIComponent(jobId)}/events`,
signal,
SSE_STALL_MS,
);
}
// Signed URL (no bearer) so pdf.js can issue Range requests. Absolute because consumers bypass
// authFetch, and a relative path under Tauri resolves against the webview origin.
export async function getDocumentFileUrl(documentId: string): Promise<string> {
const data = await ragRequest<{ url: string }>(
`/documents/${encodeURIComponent(documentId)}/file-url`,
);
return apiUrl(data.url);
}