Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
shared types refactor
Hugo Richarda32a738a367e
diff --git a/README.md b/README.mdindex df36d0a..43156c4 100644--- a/README.md+++ b/README.md@@ -7,22 +7,47 @@<br></p>-<p align="center">- <a href="https://github.com/vercel-labs/savoir/actions/workflows/ci.yml"><img src="https://github.com/vercel-labs/savoir/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>- <a href="https://github.com/vercel-labs/savoir/actions/workflows/build.yml"><img src="https://github.com/vercel-labs/savoir/actions/workflows/build.yml/badge.svg" alt="Build"></a>- <a href="https://www.npmjs.com/package/@savoir/sdk"><img src="https://img.shields.io/npm/v/@savoir/sdk?color=0284c7&label=@savoir/sdk" alt="npm @savoir/sdk"></a>- <a href="https://www.npmjs.com/package/@savoir/agent"><img src="https://img.shields.io/npm/v/@savoir/agent?color=0284c7&label=@savoir/agent" alt="npm @savoir/agent"></a>- <a href="./LICENSE"><img src="https://img.shields.io/github/license/vercel-labs/savoir?color=0284c7" alt="License"></a>- <a href="https://github.com/vercel-labs/savoir/stargazers"><img src="https://img.shields.io/github/stars/vercel-labs/savoir?style=flat&color=0284c7" alt="GitHub Stars"></a>-</p>-<p align="center"><b>Template.</b> Fork it, customize it, and deploy your own AI documentation assistant.</p>----Savoir provides the infrastructure to create file-based AI agents (chatbots, Discord bots, GitHub bots, etc.) that can search and read from frequently updated knowledge bases. It combines a unified [Nuxt](https://nuxt.com) application for the chat interface and API with an SDK that provides [AI SDK](https://ai-sdk.dev)-compatible tools.+Open-source infrastructure to build AI agents powered by real-time file-based knowledge. Plug any source — GitHub repos, YouTube transcripts, custom APIs — and deploy as a chat app, a GitHub bot, a Discord bot, or all at once.++## Features++### File-Based Search — No Embeddings Needed++No vector database. No chunking pipeline. No embedding model. Savoir agents use `grep`, `find`, and `cat` inside isolated sandboxes to search across all your sources. Results are deterministic, explainable, and instant. Zero infrastructure overhead.++### Multi-Platform Bots — One Agent, Everywhere++Write your agent once, deploy it on the web chat, GitHub Issues, Discord — and soon Slack, Linear, and more. Powered by pluggable adapters via the [Chat SDK](https://github.com/vercel-labs/chat). Adding a new platform is a single adapter file.++### Built-in Admin Panel++Full admin interface out of the box: usage stats, error logs, user management, source configuration, and content sync controls. No need for external dashboards or third-party monitoring.++### AI-Powered Admin Agent++Ask your app about itself. "What errors happened in the last 24 hours?", "Show token usage by model", "Which endpoints are slowest?" — the admin agent has access to internal tools like `query_stats`, `query_errors`, `run_sql`, and `chart` to answer operational questions in natural language.++### Smart Complexity Router++Every incoming question is classified by complexity (trivial → complex) and routed to the right model. Simple questions go to fast, cheap models. Hard questions go to powerful ones. Cost optimization happens automatically — no manual rules to maintain.++### Real-Time Tool Visualization++The chat UI shows what the agent is doing in real time: which files it's reading, which commands it's running, and how long each step takes. No black box.++### Shareable Conversations++Share any conversation with a single click. Generates a public read-only link with full metadata — author, title, and the complete exchange.++### Shared Sandbox Pool++Sandboxes are pooled across users and conversations. When a chat starts, it connects to an already-running sandbox instead of creating a new one — startup in under 100ms. If none is available, a pre-built snapshot spins one up in 1–3s. Sandboxes are read-only with blocked dangerous commands, and automatically shared so multiple agents search the same up-to-date content without duplicating resources.## Architecture@@ -152,7 +177,7 @@ See [SOURCES.md](./docs/SOURCES.md) for detailed source configuration options.## How It Works1. **Sources in Database**: Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com), managed through the admin interface-2. **Content Aggregation**: Sources (GitHub docs, YouTube transcripts, etc.) are synced to a snapshot repository via [Vercel Workflow](https://useworkflow.dev)+2. **Content Aggregation**: Sources (GitHub repos, YouTube transcripts, custom APIs, etc.) are synced to a snapshot repository via [Vercel Workflow](https://useworkflow.dev)3. **Sandbox Creation**: When an agent needs to search, the API creates/recovers a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) with the snapshot repo cloned4. **File-based Search**: The SDK `bash` and `bash_batch` tools execute grep/find/cat commands in the sandbox to search and read content5. **AI Integration**: Tools are compatible with the [Vercel AI SDK](https://ai-sdk.dev) for seamless integration with any LLMdiff --git a/apps/chat/app/app.vue b/apps/chat/app/app.vueindex 79d422b..cd2e527 100644--- a/apps/chat/app/app.vue+++ b/apps/chat/app/app.vue@@ -21,7 +21,7 @@ useHead({})useHead({- titleTemplate: `%s - ${appConfig.app.name}`,+ titleTemplate: `%s - ${appConfig.app.name}`})useSeoMeta({diff --git a/apps/chat/app/components/ModalShare.vue b/apps/chat/app/components/ModalShare.vueindex 6706d0c..625613f 100644--- a/apps/chat/app/components/ModalShare.vue+++ b/apps/chat/app/components/ModalShare.vue@@ -1,4 +1,6 @@<script setup lang="ts">+import type { PatchChatShareBody, PatchChatShareResponse } from '#shared/types/chat'+const props = defineProps<{chatId: stringisPublic: boolean@@ -30,9 +32,9 @@ const shareUrl = computed(() => {async function togglePublic(value: boolean) {isToggling.value = truetry {- const updated = await $fetch<{ isPublic: boolean, shareToken: string | null }>(`/api/chats/${props.chatId}/share`, {+ const updated = await $fetch<PatchChatShareResponse>(`/api/chats/${props.chatId}/share`, {method: 'PATCH',- body: { isPublic: value }+ body: { isPublic: value } satisfies PatchChatShareBody})localIsPublic.value = updated.isPubliclocalShareToken.value = updated.shareTokendiff --git a/apps/chat/app/composables/useChats.ts b/apps/chat/app/composables/useChats.tsindex 1dbf320..a4babec 100644--- a/apps/chat/app/composables/useChats.ts+++ b/apps/chat/app/composables/useChats.ts@@ -1,17 +1,8 @@import { isToday, isYesterday, subMonths } from 'date-fns'+import type { ComputedRef, Ref } from 'vue'+import type { UIChat } from '#shared/types/chat'-export interface UIChat {- id: string- label: string- generating?: boolean- icon: string- createdAt: string- to: string- isPublic: boolean- shareToken: string | null-}--export function useChats(chats: Ref<UIChat[] | undefined>) {+export function useChats(chats: Ref<UIChat[] | undefined> | ComputedRef<UIChat[] | undefined>) {const groups = computed(() => {const today: UIChat[] = []const yesterday: UIChat[] = []diff --git a/apps/chat/app/composables/useSnapshotSync.ts b/apps/chat/app/composables/useSnapshotSync.tsindex c27a479..996a4ab 100644--- a/apps/chat/app/composables/useSnapshotSync.ts+++ b/apps/chat/app/composables/useSnapshotSync.ts@@ -1,4 +1,4 @@-import type { SnapshotSyncStatus } from '~~/shared/types/snapshot'+import type { SnapshotSyncStatus } from '#shared/types/snapshot'const POLL_INTERVAL_MS = 5 * 60 * 1000diff --git a/apps/chat/app/layouts/default.vue b/apps/chat/app/layouts/default.vueindex 6e9699e..fb66696 100644--- a/apps/chat/app/layouts/default.vue+++ b/apps/chat/app/layouts/default.vue@@ -1,5 +1,6 @@<script setup lang="ts">import { LazyModalConfirm, LazyModalShare } from '#components'+import type { GetChatsResponse, UIChat } from '#shared/types/chat'const route = useRoute()const toast = useToast()@@ -27,21 +28,22 @@ const shareModal = overlay.create(LazyModalShare, {}})-const { data: chats, refresh: refreshChats } = await useFetch('/api/chats', {+const { data: chatsResponse, refresh: refreshChats } = await useFetch<GetChatsResponse>('/api/chats', {key: 'chats',- transform: data => data.map(chat => ({- id: chat.id,- label: chat.title || 'Generating title…',- generating: !chat.title,- to: `/chat/${chat.id}`,- icon: chat.mode === 'admin' ? 'i-custom-shield' : 'i-custom-chat',- mode: chat.mode,- createdAt: chat.createdAt,- isPublic: chat.isPublic,- shareToken: chat.shareToken- }))})+const chats = computed<UIChat[] | undefined>(() => chatsResponse.value?.map(chat => ({+ id: chat.id,+ label: chat.title || 'Generating title…',+ generating: !chat.title,+ to: `/chat/${chat.id}`,+ icon: chat.mode === 'admin' ? 'i-custom-shield' : 'i-custom-chat',+ mode: chat.mode,+ createdAt: String(chat.createdAt),+ isPublic: chat.isPublic,+ shareToken: chat.shareToken+})))+watch(loggedIn, () => {refreshChats()open.value = false@@ -317,7 +319,7 @@ defineShortcuts({]"@click="open = false">- <UIcon v-if="(chat as any).mode === 'admin'" name="i-custom-shield" class="size-4 shrink-0" />+ <UIcon v-if="chat.mode === 'admin'" name="i-custom-shield" class="size-4 shrink-0" /><TextScramble v-if="chat.generating" /><span v-else class="truncate">{{ chat.label }}</span></NuxtLink>diff --git a/apps/chat/app/pages/admin/new.vue b/apps/chat/app/pages/admin/new.vueindex 494581b..20e82df 100644--- a/apps/chat/app/pages/admin/new.vue+++ b/apps/chat/app/pages/admin/new.vue@@ -252,7 +252,7 @@ function isSourceEmpty(source: ExtractedSource): boolean {}function resetSource(source: ExtractedSource) {- const type = source.data.type+ const { type } = source.dataObject.assign(source.data, createSourceData({ type } as SourceOcrItem))source.confidence = 1}diff --git a/apps/chat/app/pages/chat/[id].vue b/apps/chat/app/pages/chat/[id].vueindex 8c1bc6c..eb2ffc1 100644--- a/apps/chat/app/pages/chat/[id].vue+++ b/apps/chat/app/pages/chat/[id].vue@@ -7,6 +7,7 @@ import { useClipboard } from '@vueuse/core'import { getTextFromMessage } from '@nuxt/ui/utils/ai'import ProseStreamPre from '../../components/prose/PreStream.vue'import type { ToolCall } from '#shared/types/tool-call'+import type { GetChatResponse } from '#shared/types/chat'definePageMeta({ auth: 'user' })@@ -46,7 +47,7 @@ const {const nuxtApp = useNuxtApp()const chatKey = `chat-${route.params.id}`-const { data } = await useFetch(`/api/chats/${route.params.id}`, {+const { data } = await useFetch<GetChatResponse>(`/api/chats/${route.params.id}`, {key: chatKey,getCachedData: (key, nuxtApp) =>nuxtApp.payload.data[key] ?? nuxtApp.static.data[key],@@ -56,7 +57,7 @@ if (!data.value) {}if (data.value.mode) {- setMode(data.value.mode as 'chat' | 'admin')+ setMode(data.value.mode)}useSeoMeta({ title: () => data.value?.title || 'Chat' })@@ -66,7 +67,7 @@ const isNewChat = (data.value?.messages.length ?? 0) <= 1const chat = new Chat({id: data.value.id,- messages: data.value.messages,+ messages: data.value.messages as UIMessage[],transport: new DefaultChatTransport({api: `/api/chats/${data.value.id}`,body: {diff --git a/apps/chat/server/api/chats.get.ts b/apps/chat/server/api/chats.get.tsindex 5a2bc4a..9b5beb1 100644--- a/apps/chat/server/api/chats.get.ts+++ b/apps/chat/server/api/chats.get.ts@@ -1,11 +1,14 @@import { db, schema } from '@nuxthub/db'import { eq, desc } from 'drizzle-orm'+import type { GetChatsResponse } from '#shared/types/chat'export default defineEventHandler(async (event) => {const { user } = await requireUserSession(event)- return await db.query.chats.findMany({+ const chats = await db.query.chats.findMany({where: () => eq(schema.chats.userId, user.id),orderBy: () => desc(schema.chats.createdAt)})++ return chats satisfies GetChatsResponse})diff --git a/apps/chat/server/api/chats.post.ts b/apps/chat/server/api/chats.post.tsindex 01a7d95..47c121c 100644--- a/apps/chat/server/api/chats.post.ts+++ b/apps/chat/server/api/chats.post.ts@@ -1,15 +1,20 @@import type { UIMessage } from 'ai'import { db, schema } from '@nuxthub/db'import { z } from 'zod'+import type { CreateChatBody, CreateChatResponse } from '#shared/types/chat'++const bodySchema = z.object({+ id: z.string(),+ mode: z.enum(['chat', 'admin']).default('chat'),+ message: z.custom<UIMessage>()+})export default defineEventHandler(async (event) => {const requestLog = useLogger(event)const { user } = await requireUserSession(event)- const { id, mode, message } = await readValidatedBody(event, z.object({- id: z.string(),- mode: z.enum(['chat', 'admin']).default('chat'),- message: z.custom<UIMessage>()- }).parse)+ const body: CreateChatBody = await readValidatedBody(event, bodySchema.parse)+ const { id, message } = body+ const mode = body.mode ?? 'chat'requestLog.set({ userId: user.id, chatId: id, mode })@@ -35,5 +40,5 @@ export default defineEventHandler(async (event) => {parts: message.parts})- return chat+ return chat satisfies CreateChatResponse})diff --git a/apps/chat/server/api/chats/[id].get.ts b/apps/chat/server/api/chats/[id].get.tsindex 0042999..60bffe1 100644--- a/apps/chat/server/api/chats/[id].get.ts+++ b/apps/chat/server/api/chats/[id].get.ts@@ -1,6 +1,7 @@import { db, schema } from '@nuxthub/db'import { and, asc, eq } from 'drizzle-orm'import { z } from 'zod'+import type { GetChatResponse } from '#shared/types/chat'const paramsSchema = z.object({id: z.string().min(1, 'Missing chat ID'),@@ -31,5 +32,5 @@ export default defineEventHandler(async (event) => {requestLog.set({ messageCount: chat.messages.length })- return chat+ return chat satisfies GetChatResponse})diff --git a/apps/chat/server/api/chats/[id]/share.patch.ts b/apps/chat/server/api/chats/[id]/share.patch.tsindex 0dbfbd7..9ed1f96 100644--- a/apps/chat/server/api/chats/[id]/share.patch.ts+++ b/apps/chat/server/api/chats/[id]/share.patch.ts@@ -1,6 +1,7 @@import { db, schema } from '@nuxthub/db'import { and, eq } from 'drizzle-orm'import { z } from 'zod'+import type { PatchChatShareBody, PatchChatShareResponse } from '#shared/types/chat'const paramsSchema = z.object({id: z.string().min(1, 'Missing chat ID'),@@ -11,7 +12,7 @@ export default defineEventHandler(async (event) => {const { user } = await requireUserSession(event)const { id } = await getValidatedRouterParams(event, paramsSchema.parse)- const { isPublic } = await readValidatedBody(event, z.object({+ const { isPublic } = await readValidatedBody<PatchChatShareBody>(event, z.object({isPublic: z.boolean()}).parse)@@ -39,5 +40,13 @@ export default defineEventHandler(async (event) => {.where(eq(schema.chats.id, id)).returning()- return updated+ if (!updated) {+ throw createError({+ statusCode: 500,+ statusMessage: 'Failed to update chat sharing settings',+ data: { why: 'The database update did not return the updated chat row', fix: 'Try again or check server logs for database errors' },+ })+ }++ return updated satisfies PatchChatShareResponse})diff --git a/apps/chat/shared/types/chat.ts b/apps/chat/shared/types/chat.tsnew file mode 100644index 0000000..85925ed--- /dev/null+++ b/apps/chat/shared/types/chat.ts@@ -0,0 +1,36 @@+import type { UIMessage } from 'ai'+import type { DbChat, DbMessage } from '#shared/types/db'++export type ChatMode = DbChat['mode']++export interface UIChat {+ id: string+ label: string+ generating?: boolean+ icon: string+ mode: ChatMode+ createdAt: string+ to: string+ isPublic: boolean+ shareToken: string | null+}++export type GetChatsResponse = DbChat[]++export interface CreateChatBody {+ id: string+ mode?: ChatMode+ message: UIMessage+}++export type CreateChatResponse = DbChat++export type GetChatResponse = DbChat & {+ messages: DbMessage[]+}++export interface PatchChatShareBody {+ isPublic: boolean+}++export type PatchChatShareResponse = DbChatdiff --git a/apps/chat/shared/types/db.ts b/apps/chat/shared/types/db.tsnew file mode 100644index 0000000..3c5cf03--- /dev/null+++ b/apps/chat/shared/types/db.ts@@ -0,0 +1,20 @@+import type { InferInsertModel, InferSelectModel } from 'drizzle-orm'+import type { agentConfig, apiUsage, chats, messages, sources, usageStats } from '@nuxthub/db/schema'++export type DbChat = InferSelectModel<typeof chats>+export type NewDbChat = InferInsertModel<typeof chats>++export type DbMessage = InferSelectModel<typeof messages>+export type NewDbMessage = InferInsertModel<typeof messages>++export type DbSource = InferSelectModel<typeof sources>+export type NewDbSource = InferInsertModel<typeof sources>++export type DbAgentConfig = InferSelectModel<typeof agentConfig>+export type NewDbAgentConfig = InferInsertModel<typeof agentConfig>++export type DbApiUsage = InferSelectModel<typeof apiUsage>+export type NewDbApiUsage = InferInsertModel<typeof apiUsage>++export type DbUsageStat = InferSelectModel<typeof usageStats>+export type NewDbUsageStat = InferInsertModel<typeof usageStats>diff --git a/docs/SOURCES.md b/docs/SOURCES.mdindex 0ea8e32..e23f7d0 100644--- a/docs/SOURCES.md+++ b/docs/SOURCES.md@@ -1,12 +1,14 @@# Content Sources-Savoir aggregates documentation from multiple sources into a unified, searchable knowledge base.+Savoir aggregates content from multiple sources into a unified, searchable knowledge base. A source is anything that produces files — GitHub repos, YouTube transcripts, and any custom source you build. Everything ends up as files in a sandbox, and the AI agent searches across all of them.++The system is designed to be extensible. Built-in source types handle GitHub and YouTube, but the architecture supports any source that can output files: Reddit threads, Slack exports, RSS feeds, custom APIs, static markdown — anything.## Managing SourcesSources are managed through the **admin interface** at `/admin`. From there you can:-- Add new GitHub repositories or YouTube channels+- Add new sources (GitHub repositories, YouTube channels, or custom types)- Edit existing source configurations- Delete sources- Trigger a sync to update the knowledge base