Skip to content

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.md
index 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 Works
1. **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 cloned
4. **File-based Search**: The SDK `bash` and `bash_batch` tools execute grep/find/cat commands in the sandbox to search and read content
5. **AI Integration**: Tools are compatible with the [Vercel AI SDK](https://ai-sdk.dev) for seamless integration with any LLM
diff --git a/apps/chat/app/app.vue b/apps/chat/app/app.vue
index 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.vue
index 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: string
isPublic: boolean
@@ -30,9 +32,9 @@ const shareUrl = computed(() => {
async function togglePublic(value: boolean) {
isToggling.value = true
try {
- 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.isPublic
localShareToken.value = updated.shareToken
diff --git a/apps/chat/app/composables/useChats.ts b/apps/chat/app/composables/useChats.ts
index 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.ts
index 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 * 1000
diff --git a/apps/chat/app/layouts/default.vue b/apps/chat/app/layouts/default.vue
index 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.vue
index 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.data
Object.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].vue
index 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) <= 1
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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 = DbChat
diff --git a/apps/chat/shared/types/db.ts b/apps/chat/shared/types/db.ts
new file mode 100644
index 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.md
index 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 Sources
Sources 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