Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
improve docs
Hugo Richardbac9ce9885a4
diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeepdeleted file mode 100644index e69de29..0000000diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex 586ee82..806483c 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -20,6 +20,8 @@ Here are the available types and scopes:### Scopes- chat (apps/chat - Main application)- sdk (packages/sdk - @savoir/sdk)+- agent (packages/agent - @savoir/agent)+- cli (packages/cli - @savoir/cli)- deps (dependencies updates)- docs (documentation)-->diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.ymlindex 5a42a6c..914fe0e 100644--- a/.github/workflows/semantic-pull-request.yml+++ b/.github/workflows/semantic-pull-request.yml@@ -24,9 +24,9 @@ jobs:scopes: |depschat- botsdk- logger+ agent+ clidocstypes: |breakingdiff --git a/README.md b/README.mdindex 43156c4..c2eec4b 100644--- a/README.md+++ b/README.md@@ -2,7 +2,7 @@<br><b>Savoir</b><br>- <i>Build AI agents with real-time knowledge access.</i>+ <i>Build AI agents with up-to-date knowledge access.</i><br><br></p>@@ -13,17 +13,17 @@----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.+Open-source infrastructure to build AI agents powered by up-to-date 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.+No vector database. No chunking pipeline. No embedding model. Savoir agents use `grep`, `find`, and `cat` inside [isolated sandboxes](./docs/ARCHITECTURE.md#3-sandbox-system) to search across all your [sources](./docs/SOURCES.md). 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.+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](./docs/CUSTOMIZATION.md#4-add-a-bot-adapter).### Built-in Admin Panel@@ -35,7 +35,7 @@ Ask your app about itself. "What errors happened in the last 24 hours?", "Show t### 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.+Every incoming question is classified by complexity (trivial → complex) and [routed to the right model](./docs/ARCHITECTURE.md#4-ai-agent-router--model-selection). 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@@ -49,7 +49,7 @@ Share any conversation with a single click. Generates a public read-only link wiSandboxes 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+## [Architecture](./docs/ARCHITECTURE.md)```┌─────────────────────────────────────────────────────────────────┐@@ -159,7 +159,7 @@ See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full list of environment varSavoir is designed as a **reusable template**. See the [Customization Guide](./docs/CUSTOMIZATION.md) for how to:- Rename your instance (name, icon, description)-- Add documentation sources (GitHub repos, YouTube channels)+- Add [content sources](./docs/SOURCES.md) (GitHub repos, YouTube channels, custom)- Add custom AI tools- Add bot adapters (Slack, Linear, etc.)- Customize AI prompts@@ -176,6 +176,8 @@ See [SOURCES.md](./docs/SOURCES.md) for detailed source configuration options.## How It Works+> For the full technical deep-dive, see [Architecture](./docs/ARCHITECTURE.md).+1. **Sources in Database**: Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com), managed through the admin interface2. **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@@ -189,7 +191,7 @@ Savoir includes built-in bot integrations powered by the [Vercel Chat SDK](https- **GitHub Bot**: Responds to mentions in GitHub issues and PRs. Uses a [GitHub App](https://docs.github.com/en/apps) for authentication and webhooks.- **Discord Bot**: Responds to mentions and continues conversations in threads. Uses the [Discord API](https://discord.com/developers/docs).-Both bots use the same AI agent and knowledge base as the chat interface.+Both bots use the same AI agent and knowledge base as the chat interface. Want to add your own? See [Adding a Bot Adapter](./docs/CUSTOMIZATION.md#4-add-a-bot-adapter).## Developmentdiff --git a/apps/chat/app/content/docs/admin-mode.md b/apps/chat/app/content/docs/admin-mode.mdindex fd80005..4817680 100644--- a/apps/chat/app/content/docs/admin-mode.md+++ b/apps/chat/app/content/docs/admin-mode.md@@ -77,3 +77,5 @@ Admin mode uses a completely separate AI pipeline from the regular chat:4. The `chart` tool can render visual time-series charts inline in the conversationAdmin chats are stored like regular chats but tagged with `mode: 'admin'` in the database.++For a deeper look at the architecture behind admin mode and other components, see the [Architecture documentation](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) on GitHub.diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.mdindex 06527b7..33b97b7 100644--- a/apps/chat/app/content/docs/bot-setup.md+++ b/apps/chat/app/content/docs/bot-setup.md@@ -80,4 +80,4 @@ When enabled, the bot will respond to every new issue opened in repositories wheThe bot is built on the [Vercel Chat SDK](https://github.com/vercel-labs/chat) with a custom GitHub adapter. It uses the [Octokit](https://github.com/octokit/rest.js) library with [GitHub App authentication](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) to interact with the GitHub API.-Each response goes through the same AI agent pipeline as the chat interface, using [Vercel AI SDK](https://ai-sdk.dev) tools to search the knowledge base in a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).+Each response goes through the same AI agent pipeline as the chat interface, using [Vercel AI SDK](https://ai-sdk.dev) tools to search the knowledge base in a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). For the full architecture, see the [Architecture documentation](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) on GitHub. To build your own adapter, see the [Customization Guide](https://github.com/vercel-labs/savoir/blob/main/docs/CUSTOMIZATION.md#4-add-a-bot-adapter).diff --git a/apps/chat/app/content/docs/discord-bot.md b/apps/chat/app/content/docs/discord-bot.mdindex 4ae8b13..df54c6b 100644--- a/apps/chat/app/content/docs/discord-bot.md+++ b/apps/chat/app/content/docs/discord-bot.md@@ -69,3 +69,5 @@ If `NUXT_DISCORD_MENTION_ROLE_IDS` is set, the bot will also respond when thoseBot conversation state is stored in:- [**Redis**](https://upstash.com/docs/redis) if `REDIS_URL` is set (recommended for production -- state persists across restarts)- **In-memory** as fallback (state is lost on restart)++For the full architecture and how to build custom adapters, see the [Architecture](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) and [Customization Guide](https://github.com/vercel-labs/savoir/blob/main/docs/CUSTOMIZATION.md#4-add-a-bot-adapter) on GitHub.diff --git a/apps/chat/app/content/docs/sdk.md b/apps/chat/app/content/docs/sdk.mdindex 744bfec..b4279fc 100644--- a/apps/chat/app/content/docs/sdk.md+++ b/apps/chat/app/content/docs/sdk.md@@ -1,6 +1,6 @@# Savoir SDK-The [`@savoir/sdk`](https://github.com/vercel-labs/savoir/tree/main/packages/sdk) package provides a TypeScript client for interacting with Savoir programmatically. It exposes [AI SDK](https://ai-sdk.dev)-compatible tools that let any AI model search and read your knowledge base.+The [`@savoir/sdk`](https://github.com/vercel-labs/savoir/tree/main/packages/sdk) package provides a TypeScript client for interacting with Savoir programmatically. It exposes [AI SDK](https://ai-sdk.dev)-compatible tools that let any AI model search and read your knowledge base. For the full API reference and error handling, see the [SDK README](https://github.com/vercel-labs/savoir/blob/main/packages/sdk/README.md) on GitHub.## Installationdiff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 9a7ee15..9b6edc3 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -1,6 +1,8 @@# Savoir Architecture-This document describes the technical architecture of Savoir, a platform for building AI agents with real-time knowledge access.+> Back to [README](../README.md)++This document describes the technical architecture of Savoir, a platform for building AI agents with up-to-date knowledge access.## System Overview@@ -110,7 +112,7 @@ savoir/### 1. Sources (Database)-Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com) and managed through the admin interface.+Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com) and managed through the admin interface. See [Sources](./SOURCES.md) for configuration details.#### Database Schema@@ -251,7 +253,7 @@ Content synchronization uses [Vercel Workflow](https://useworkflow.dev) for dura- Responds to mentions and continues conversations in threads- Webhook: `POST /api/webhooks/discord`-Both bots use the same AI agent pipeline (router + tools) as the chat interface but with internal sandbox access (no HTTP round-trip).+Both bots use the same AI agent pipeline (router + tools) as the chat interface but with internal sandbox access (no HTTP round-trip). To add a new platform, see [Customization > Add a Bot Adapter](./CUSTOMIZATION.md#4-add-a-bot-adapter).## API Endpointsdiff --git a/docs/CODING-GUIDELINES.md b/docs/CODING-GUIDELINES.mdindex f7d2990..0c1285b 100644--- a/docs/CODING-GUIDELINES.md+++ b/docs/CODING-GUIDELINES.md@@ -1,5 +1,7 @@# Coding Guidelines+> Back to [README](../README.md) | See also: [Contributing](../CONTRIBUTING.md), [Architecture](./ARCHITECTURE.md)+## CommentsOnly add comments when the code is truly complex or non-obvious.diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.mdindex fe125d3..4614780 100644--- a/docs/CUSTOMIZATION.md+++ b/docs/CUSTOMIZATION.md@@ -1,5 +1,7 @@# Customization Guide+> Back to [README](../README.md) | See also: [Sources](./SOURCES.md), [Environment](./ENVIRONMENT.md), [Architecture](./ARCHITECTURE.md)+Savoir is designed as a reusable template. This guide covers how to customize your instance.## 1. Rename Your Instance@@ -32,7 +34,7 @@ Sources define your knowledge base. Manage them through the **Admin UI**:3. Configure a GitHub repository or YouTube channel4. Click **Sync** to pull content-See [SOURCES.md](./SOURCES.md) for all source options.+See [Sources](./SOURCES.md) for all source options and how to add custom source types.## 3. Add Custom AI Tools@@ -135,7 +137,7 @@ export default defineAppConfig({})```-See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options.+See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options. For a deeper understanding of the app structure, see [Architecture](./ARCHITECTURE.md).## 7. Deploydiff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.mdindex 376ca63..fe19dd1 100644--- a/docs/ENVIRONMENT.md+++ b/docs/ENVIRONMENT.md@@ -1,5 +1,7 @@# Environment Variables+> Back to [README](../README.md) | See also: [Architecture](./ARCHITECTURE.md), [Customization](./CUSTOMIZATION.md)+All environment variables for the Savoir project, organized by category.## Corediff --git a/docs/SOURCES.md b/docs/SOURCES.mdindex e23f7d0..672fcb5 100644--- a/docs/SOURCES.md+++ b/docs/SOURCES.md@@ -1,5 +1,7 @@# Content Sources+> Back to [README](../README.md) | See also: [Customization](./CUSTOMIZATION.md), [Architecture](./ARCHITECTURE.md)+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.@@ -91,12 +93,12 @@ await savoir.client.syncSource('my-docs')### How Sync Works-1. A Vercel Sandbox is created from the latest snapshot+1. A [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) is created from the latest snapshot2. All source repositories are cloned/updated3. Changes are pushed to the snapshot repository4. A new sandbox snapshot is taken for instant startup-This runs as a durable Vercel Workflow with automatic retries.+This runs as a durable [Vercel Workflow](https://useworkflow.dev) with automatic retries. See [Architecture > Sandbox System](./ARCHITECTURE.md#3-sandbox-system) for more details on how snapshots and sandboxes work.### Sync Trackingdiff --git a/packages/agent/README.md b/packages/agent/README.mdindex 012db94..3023d81 100644--- a/packages/agent/README.md+++ b/packages/agent/README.md@@ -2,6 +2,8 @@Framework-agnostic agent core for Savoir. Handles question routing, prompt management, agent creation, and AI tool definitions.+> See also: [Main README](../../README.md), [Architecture](../../docs/ARCHITECTURE.md), [Customization](../../docs/CUSTOMIZATION.md)+## OverviewThis package provides the AI agent infrastructure used by Savoir's chat interface and bots. It is designed to be consumed by `apps/chat` but can also be used independently.diff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex 6caeb27..88c0053 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -1,8 +1,10 @@# @savoir/sdk-SDK for [Savoir](https://github.com/vercel-labs/savoir) - AI agents with real-time knowledge base access.+SDK for [Savoir](https://github.com/vercel-labs/savoir) — AI agents with up-to-date knowledge base access.-Provides [AI SDK](https://ai-sdk.dev) compatible tools to query documentation in a sandboxed environment.+Provides [AI SDK](https://ai-sdk.dev) compatible tools to query content in a sandboxed environment.++> See also: [Main README](../../README.md), [Architecture](../../docs/ARCHITECTURE.md), [Environment Variables](../../docs/ENVIRONMENT.md)## Installation