Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
make content ready for templating
Hugo Richardbb5a05ddfbcf
diff --git a/.agents/skills/add-bot-adapter.md b/.agents/skills/add-bot-adapter.mdnew file mode 100644index 0000000..7519f9d--- /dev/null+++ b/.agents/skills/add-bot-adapter.md@@ -0,0 +1,83 @@+# Add Bot Adapter++Guide for adding a new platform adapter (Slack, Linear, etc.) to the Savoir bot system.++## Architecture++The bot system uses the [Vercel Chat SDK](https://github.com/vercel-labs/chat) for platform abstraction. Each adapter implements the Chat SDK interface.++## Reference: Existing Adapters++- **Discord**: Uses `@chat-adapter/discord` (official adapter)+- **GitHub**: Uses `SavoirGitHubAdapter` (custom, in `apps/chat/server/utils/bot/`)++The GitHub adapter is a good reference for building custom adapters.++## Steps++### 1. Create the Adapter++Create `apps/chat/server/utils/bot/adapters/my-platform.ts`:++```typescript+import type { Adapter } from 'chat'++export class MyPlatformAdapter implements Adapter {+ name = 'my-platform'++ // Implement required methods:+ // - sendMessage(threadId, message)+ // - editMessage(threadId, messageId, message)+ // - deleteMessage(threadId, messageId)+ // etc.+}+```++See the Chat SDK documentation for the full `Adapter` interface.++### 2. Register the Adapter++In `apps/chat/server/utils/bot/index.ts`, add your adapter to the Chat instance:++```typescript+import { MyPlatformAdapter } from './adapters/my-platform'++// Add to the Chat instance+chat.addAdapter(new MyPlatformAdapter())+```++### 3. Create the Webhook Endpoint++Create `apps/chat/server/api/webhooks/my-platform.post.ts`:++```typescript+export default defineEventHandler(async (event) => {+ const body = await readBody(event)++ // Verify webhook signature (platform-specific)+ // Parse the incoming event+ // Forward to the Chat SDK for processing++ return { ok: true }+})+```++### 4. Add Environment Variables++Add platform-specific env vars to:+- `apps/chat/.env.example`+- `docs/ENVIRONMENT.md`+- `apps/chat/nuxt.config.ts` (in `runtimeConfig`)++### 5. Add Documentation++Create `apps/chat/app/content/docs/my-platform-bot.md` following the pattern of `discord-bot.md` or `bot-setup.md`.++## Thread ID Format++Follow the convention: `{platform}:{identifier}:{type}:{id}`++Examples:+- GitHub: `github:owner/repo:issue:123`+- Discord: `discord:guild:channel:thread`+- Your platform: `my-platform:{workspace}:{channel}:{thread}`diff --git a/.agents/skills/add-source.md b/.agents/skills/add-source.mdnew file mode 100644index 0000000..e8ddbcf--- /dev/null+++ b/.agents/skills/add-source.md@@ -0,0 +1,59 @@+# Add Source++Guide for adding a new knowledge source to the Savoir instance.++## Via Admin UI (recommended)++1. Navigate to `/admin`+2. Click **Add source**+3. Fill in the fields:++### GitHub Source++| Field | Required | Description |+|-------|----------|-------------|+| `id` | Yes | Unique identifier (e.g. `my-docs`) |+| `label` | Yes | Display name (e.g. `My Docs`) |+| `repo` | Yes | GitHub repository in `owner/repo` format |+| `branch` | No | Branch to fetch (default: `main`) |+| `contentPath` | No | Path to content directory (default: `docs`) |+| `outputPath` | No | Output directory in snapshot (default: `id`) |+| `readmeOnly` | No | Only fetch README.md (default: `false`) |++### YouTube Source++| Field | Required | Description |+|-------|----------|-------------|+| `id` | Yes | Unique identifier |+| `label` | Yes | Display name |+| `channelId` | Yes | YouTube channel ID (starts with `UC`) |+| `handle` | No | YouTube handle (e.g. `@MyChannel`) |+| `maxVideos` | No | Maximum videos to fetch (default: `50`) |++4. Click **Sync** to pull content into the knowledge base++## Via API++```bash+# Create a GitHub source+curl -X POST <your-url>/api/sources \+ -H "Authorization: Bearer <admin-api-key>" \+ -H "Content-Type: application/json" \+ -d '{+ "id": "my-docs",+ "type": "github",+ "label": "My Docs",+ "repo": "org/docs-repo",+ "contentPath": "docs"+ }'++# Trigger sync+curl -X POST <your-url>/api/sync \+ -H "Authorization: Bearer <admin-api-key>"+```++## Notes++- After adding sources, always trigger a **sync** to pull content+- YouTube sources require `NUXT_YOUTUBE_API_KEY` to be set+- Sources are stored in SQLite and can be managed from the admin UI at any timediff --git a/.agents/skills/add-tool.md b/.agents/skills/add-tool.mdnew file mode 100644index 0000000..e5fa712--- /dev/null+++ b/.agents/skills/add-tool.md@@ -0,0 +1,112 @@+# Add AI Tool++Guide for adding a new AI SDK tool to the `@savoir/agent` package.++## Steps++### 1. Create the Tool++Create `packages/agent/src/tools/my-tool.ts`.++Tools **must use `async function*` (generator)** and yield status updates so the frontend can display loading state and results automatically.++```typescript+import { tool } from 'ai'+import { z } from 'zod'++export const myTool = tool({+ description: 'Clear description of what this tool does — the AI model reads this to decide when to use it',+ inputSchema: z.object({+ query: z.string().describe('What the parameter is for'),+ }),+ execute: async function* ({ query }) {+ // 1. Yield loading state — the frontend shows a spinner+ yield { status: 'loading' as const }+ const start = Date.now()++ try {+ // 2. Your tool logic here+ const result = await doSomething(query)++ // 3. Yield done state with results — the frontend displays the output+ yield {+ status: 'done' as const,+ durationMs: Date.now() - start,+ text: result,+ commands: [+ {+ title: `My tool: "${query}"`,+ command: '',+ stdout: result,+ stderr: '',+ exitCode: 0,+ success: true,+ },+ ],+ }+ } catch (error) {+ // 4. Yield error state+ yield {+ status: 'done' as const,+ durationMs: Date.now() - start,+ text: '',+ commands: [+ {+ title: `My tool: "${query}"`,+ command: '',+ stdout: '',+ stderr: error instanceof Error ? error.message : 'Failed',+ exitCode: 1,+ success: false,+ },+ ],+ }+ }+ },+})+```++### Key Points about Yield++- **`yield { status: 'loading' }`** — Must be yielded first. The frontend uses this to show a loading indicator for the tool call.+- **`yield { status: 'done', ... }`** — Must be yielded last. Contains the results displayed in the chat UI.+- The `commands` array format matches the sandbox bash tool output, so the frontend renders it consistently.+- See `packages/agent/src/tools/web-search.ts` for a complete real-world example.++### 2. Export the Tool++Add the export in `packages/agent/src/index.ts`:++```typescript+export { myTool } from './tools/my-tool'+```++### 3. Register in the Agent++In the agent creation (e.g. `apps/chat/server/utils/chat/`), add the tool to the tools object:++```typescript+import { myTool } from '@savoir/agent'++const tools = {+ ...savoir.tools,+ my_tool: myTool,+}+```++### 4. Update Prompts (optional)++If the tool needs specific instructions, update the relevant prompt in `packages/agent/src/prompts/`:++```typescript+// In chat.ts or bot.ts, add to the Available Tools section:+// - **my_tool**: Description of when and how to use this tool+```++## Existing Tools++| Tool | File | Description |+|------|------|-------------|+| `webSearchTool` | `tools/web-search.ts` | Web search for information not in the sandbox |+| `bash` | `@savoir/sdk` | Execute bash commands in the sandbox |+| `bash_batch` | `@savoir/sdk` | Execute multiple bash commands |diff --git a/.agents/skills/rename-project.md b/.agents/skills/rename-project.mdnew file mode 100644index 0000000..70fabe9--- /dev/null+++ b/.agents/skills/rename-project.md@@ -0,0 +1,107 @@+# Rename Project++Guide for fully renaming the project from "Savoir" to a custom name.++## Workflow++When the user wants to rename the project:++1. **Ask the user** for the new name (e.g. "MyDocs") and optionally a new package namespace (e.g. `@mydocs`)+2. **Replace ALL mentions** of "Savoir" across the entire project+3. **Rename packages** if the user wants a custom namespace+4. **Run `bun install`** to update the lockfile after package renames++## Complete List of Files to Update++### App Branding (UI-facing)++| File | What to change |+|------|---------------|+| `apps/chat/app/app.config.ts` | `name: 'Savoir'` → new name, update `description`, update `icon` |+| `apps/chat/app/assets/icons/custom/savoir.svg` | Replace with custom icon SVG, rename the file |++### Package Metadata++| File | What to change |+|------|---------------|+| `package.json` | `"name"`, `"description": "Monorepo for Savoir"` |+| `packages/sdk/package.json` | `"name"`, `"description"`, `"repository.url"`, `"homepage"` |+| `packages/agent/package.json` | `"name"`, `"description"` |+| `apps/chat/package.json` | `"name"`, dependency references `@savoir/agent`, `@savoir/sdk` |++### Source Code++| File | What to change |+|------|---------------|+| `packages/sdk/src/index.ts` | `Savoir` interface name, `createSavoir` function name |+| `packages/sdk/src/client.ts` | `SavoirClient` class name, error messages mentioning "Savoir" |+| `packages/sdk/src/types.ts` | `SavoirConfig` type name, JSDoc comments |+| `packages/agent/src/prompts/chat.ts` | `buildAdminSystemPrompt(appName = 'Savoir')` default value |+| `apps/chat/server/utils/bot/adapters/github.ts` | `SavoirGitHubAdapter` class name |+| `apps/chat/server/utils/bot/index.ts` | `SavoirGitHubAdapter` import and usage |+| `apps/chat/server/utils/sandbox/git.ts` | `email: '[email protected]'`, `name: 'Savoir Bot'` |++After renaming packages, update **all imports** across the codebase:++```bash+# Find all files importing @savoir/*+grep -rl "@savoir/sdk" apps/ packages/ --include="*.ts" --include="*.vue"+grep -rl "@savoir/agent" apps/ packages/ --include="*.ts" --include="*.vue"+```++Also check `package.json` scripts for `--filter=@savoir/*` references.++### Documentation++| File | What to change |+|------|---------------|+| `README.md` | Title, all mentions of "Savoir" |+| `CONTRIBUTING.md` | Title, all mentions of "Savoir" |+| `AGENTS.md` | Title |+| `packages/sdk/README.md` | All mentions of "Savoir", `createSavoir`, `SavoirClient`, etc. |+| `packages/agent/README.md` | All mentions of "Savoir" |+| `docs/ARCHITECTURE.md` | All mentions of "Savoir" |+| `docs/SOURCES.md` | All mentions of "Savoir" |+| `docs/ENVIRONMENT.md` | All mentions of "Savoir", `SAVOIR_API_URL`, `SAVOIR_API_KEY` |+| `docs/CUSTOMIZATION.md` | All mentions of "Savoir" |++### In-App Documentation++| File | What to change |+|------|---------------|+| `apps/chat/app/content/docs/getting-started.md` | All mentions of "Savoir" |+| `apps/chat/app/content/docs/sdk.md` | All mentions of "Savoir" |+| `apps/chat/app/content/docs/bot-setup.md` | "Savoir GitHub bot", "Savoir knowledge base" |+| `apps/chat/app/content/docs/discord-bot.md` | "Savoir Discord bot" |+| `apps/chat/app/content/docs/api-keys.md` | "authenticate with Savoir" |+| `apps/chat/app/content/docs/admin-mode.md` | "Savoir uses" |++### Skills++| File | What to change |+|------|---------------|+| `agents/skills/add-source.md` | "Savoir instance" |+| `agents/skills/add-bot-adapter.md` | "Savoir bot system" |++## Quick Find & Replace++To find all remaining mentions after manual updates:++```bash+grep -ri "savoir" --include="*.ts" --include="*.vue" --include="*.md" --include="*.json" \+ --exclude-dir=node_modules --exclude-dir=.output --exclude-dir=dist --exclude-dir=.nuxt+```++## Checklist++- [ ] `app.config.ts` — name, description, icon+- [ ] Custom icon SVG+- [ ] All `package.json` files — name, description, dependencies+- [ ] All TypeScript source — class names, function names, error messages+- [ ] All `@savoir/*` imports → new namespace+- [ ] All documentation files (root `docs/`, `packages/*/README.md`)+- [ ] All in-app docs (`apps/chat/app/content/docs/`)+- [ ] All skill files (`agents/skills/`)+- [ ] Git config (`server/utils/sandbox/git.ts`) — email and bot name+- [ ] Run `bun install` to update lockfile+- [ ] Run `bun run build` to verify everything compilesdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 0000000..eab71c3--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,75 @@+# Contributing to Savoir++Thank you for your interest in contributing to Savoir!++## Reporting Bugs++- Search [existing issues](https://github.com/vercel-labs/savoir/issues) before opening a new one+- Include steps to reproduce, expected behavior, and actual behavior+- Include your environment (Node version, OS, browser)++## Suggesting Features++- Open a [feature request issue](https://github.com/vercel-labs/savoir/issues/new)+- Describe the use case and why it would be valuable+- If possible, outline a proposed implementation++## Development Setup++```bash+# Clone the repo+git clone https://github.com/vercel-labs/savoir.git+cd savoir++# Install dependencies+bun install++# Set up environment variables+cp apps/chat/.env.example apps/chat/.env+# Edit .env with your configuration++# Start dev server+bun run dev+```++## Project Structure++```+savoir/+├── apps/chat/ # Nuxt application (chat UI + API + bots)+├── packages/sdk/ # @savoir/sdk - AI SDK compatible tools+├── packages/agent/ # @savoir/agent - Agent core (router, prompts, tools)+└── docs/ # Documentation+```++## Making Changes++1. Fork the repository+2. Create a feature branch (`git checkout -b feat/my-feature`)+3. Make your changes+4. Run checks:+ ```bash+ bun run lint:fix+ bun run typecheck+ bun run build+ ```+5. Commit with a descriptive message+6. Open a pull request++## Code Style++- Follow the existing ESLint configuration (`@hrcd/eslint-config`)+- See [docs/CODING-GUIDELINES.md](./docs/CODING-GUIDELINES.md) for detailed guidelines+- Write TypeScript with proper types+- Keep changes focused and minimal++## Pull Request Process++1. Ensure all checks pass (lint, typecheck, build)+2. Update documentation if your change affects user-facing behavior+3. Add a clear description of what changed and why+4. Request review from maintainers++## License++By contributing, you agree that your contributions will be licensed under the [MIT License](./LICENSE).diff --git a/LICENSE b/LICENSEindex 40210c8..bbe09ab 100644--- a/LICENSE+++ b/LICENSE@@ -1,201 +1,21 @@- Apache License- Version 2.0, January 2004- http://www.apache.org/licenses/-- TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION-- 1. Definitions.-- "License" shall mean the terms and conditions for use, reproduction,- and distribution as defined by Sections 1 through 9 of this document.-- "Licensor" shall mean the copyright owner or entity authorized by- the copyright owner that is granting the License.-- "Legal Entity" shall mean the union of the acting entity and all- other entities that control, are controlled by, or are under common- control with that entity. For the purposes of this definition,- "control" means (i) the power, direct or indirect, to cause the- direction or management of such entity, whether by contract or- otherwise, or (ii) ownership of fifty percent (50%) or more of the- outstanding shares, or (iii) beneficial ownership of such entity.-- "You" (or "Your") shall mean an individual or Legal Entity- exercising permissions granted by this License.-- "Source" form shall mean the preferred form for making modifications,- including but not limited to software source code, documentation- source, and configuration files.-- "Object" form shall mean any form resulting from mechanical- transformation or translation of a Source form, including but- not limited to compiled object code, generated documentation,- and conversions to other media types.-- "Work" shall mean the work of authorship, whether in Source or- Object form, made available under the License, as indicated by a- copyright notice that is included in or attached to the work- (an example is provided in the Appendix below).-- "Derivative Works" shall mean any work, whether in Source or Object- form, that is based on (or derived from) the Work and for which the- editorial revisions, annotations, elaborations, or other modifications- represent, as a whole, an original work of authorship. For the purposes- of this License, Derivative Works shall not include works that remain- separable from, or merely link (or bind by name) to the interfaces of,- the Work and Derivative Works thereof.-- "Contribution" shall mean any work of authorship, including- the original version of the Work and any modifications or additions- to that Work or Derivative Works thereof, that is intentionally- submitted to Licensor for inclusion in the Work by the copyright owner- or by an individual or Legal Entity authorized to submit on behalf of- the copyright owner. For the purposes of this definition, "submitted"- means any form of electronic, verbal, or written communication sent- to the Licensor or its representatives, including but not limited to- communication on electronic mailing lists, source code control systems,- and issue tracking systems that are managed by, or on behalf of, the- Licensor for the purpose of discussing and improving the Work, but- excluding communication that is conspicuously marked or otherwise- designated in writing by the copyright owner as "Not a Contribution."-- "Contributor" shall mean Licensor and any individual or Legal Entity- on behalf of whom a Contribution has been received by Licensor and- subsequently incorporated within the Work.-- 2. Grant of Copyright License. Subject to the terms and conditions of- this License, each Contributor hereby grants to You a perpetual,- worldwide, non-exclusive, no-charge, royalty-free, irrevocable- copyright license to reproduce, prepare Derivative Works of,- publicly display, publicly perform, sublicense, and distribute the- Work and such Derivative Works in Source or Object form.-- 3. Grant of Patent License. Subject to the terms and conditions of- this License, each Contributor hereby grants to You a perpetual,- worldwide, non-exclusive, no-charge, royalty-free, irrevocable- (except as stated in this section) patent license to make, have made,- use, offer to sell, sell, import, and otherwise transfer the Work,- where such license applies only to those patent claims licensable- by such Contributor that are necessarily infringed by their- Contribution(s) alone or by combination of their Contribution(s)- with the Work to which such Contribution(s) was submitted. If You- institute patent litigation against any entity (including a- cross-claim or counterclaim in a lawsuit) alleging that the Work- or a Contribution incorporated within the Work constitutes direct- or contributory patent infringement, then any patent licenses- granted to You under this License for that Work shall terminate- as of the date such litigation is filed.-- 4. Redistribution. You may reproduce and distribute copies of the- Work or Derivative Works thereof in any medium, with or without- modifications, and in Source or Object form, provided that You- meet the following conditions:-- (a) You must give any other recipients of the Work or- Derivative Works a copy of this License; and-- (b) You must cause any modified files to carry prominent notices- stating that You changed the files; and-- (c) You must retain, in the Source form of any Derivative Works- that You distribute, all copyright, patent, trademark, and- attribution notices from the Source form of the Work,- excluding those notices that do not pertain to any part of- the Derivative Works; and-- (d) If the Work includes a "NOTICE" text file as part of its- distribution, then any Derivative Works that You distribute must- include a readable copy of the attribution notices contained- within such NOTICE file, excluding those notices that do not- pertain to any part of the Derivative Works, in at least one- of the following places: within a NOTICE text file distributed- as part of the Derivative Works; within the Source form or- documentation, if provided along with the Derivative Works; or,- within a display generated by the Derivative Works, if and- wherever such third-party notices normally appear. The contents- of the NOTICE file are for informational purposes only and- do not modify the License. You may add Your own attribution- notices within Derivative Works that You distribute, alongside- or as an addendum to the NOTICE text from the Work, provided- that such additional attribution notices cannot be construed- as modifying the License.-- You may add Your own copyright statement to Your modifications and- may provide additional or different license terms and conditions- for use, reproduction, or distribution of Your modifications, or- for any such Derivative Works as a whole, provided Your use,- reproduction, and distribution of the Work otherwise complies with- the conditions stated in this License.-- 5. Submission of Contributions. Unless You explicitly state otherwise,- any Contribution intentionally submitted for inclusion in the Work- by You to the Licensor shall be under the terms and conditions of- this License, without any additional terms or conditions.- Notwithstanding the above, nothing herein shall supersede or modify- the terms of any separate license agreement you may have executed- with Licensor regarding such Contributions.-- 6. Trademarks. This License does not grant permission to use the trade- names, trademarks, service marks, or product names of the Licensor,- except as required for reasonable and customary use in describing the- origin of the Work and reproducing the content of the NOTICE file.-- 7. Disclaimer of Warranty. Unless required by applicable law or- agreed to in writing, Licensor provides the Work (and each- Contributor provides its Contributions) on an "AS IS" BASIS,- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or- implied, including, without limitation, any warranties or conditions- of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A- PARTICULAR PURPOSE. You are solely responsible for determining the- appropriateness of using or redistributing the Work and assume any- risks associated with Your exercise of permissions under this License.-- 8. Limitation of Liability. In no event and under no legal theory,- whether in tort (including negligence), contract, or otherwise,- unless required by applicable law (such as deliberate and grossly- negligent acts) or agreed to in writing, shall any Contributor be- liable to You for damages, including any direct, indirect, special,- incidental, or consequential damages of any character arising as a- result of this License or out of the use or inability to use the- Work (including but not limited to damages for loss of goodwill,- work stoppage, computer failure or malfunction, or any and all- other commercial damages or losses), even if such Contributor- has been advised of the possibility of such damages.-- 9. Accepting Warranty or Additional Liability. While redistributing- the Work or Derivative Works thereof, You may choose to offer,- and charge a fee for, acceptance of support, warranty, indemnity,- or other liability obligations and/or rights consistent with this- License. However, in accepting such obligations, You may act only- on Your own behalf and on Your sole responsibility, not on behalf- of any other Contributor, and only if You agree to indemnify,- defend, and hold each Contributor harmless for any liability- incurred by, or claims asserted against, such Contributor by reason- of your accepting any such warranty or additional liability.-- END OF TERMS AND CONDITIONS-- APPENDIX: How to apply the Apache License to your work.-- To apply the Apache License to your work, attach the following- boilerplate notice, with the fields enclosed by brackets "[]"- replaced with your own identifying information. (Don't include- the brackets!) The text should be enclosed in the appropriate- comment syntax for the file format. We also recommend that a- file or class name and description of purpose be included on the- same "printed page" as the copyright notice for easier- identification within third-party archives.-- Copyright 2024-present Hugo Richard-- Licensed under the Apache License, Version 2.0 (the "License");- you may not use this file except in compliance with the License.- You may obtain a copy of the License at-- http://www.apache.org/licenses/LICENSE-2.0-- Unless required by applicable law or agreed to in writing, software- distributed under the License is distributed on an "AS IS" BASIS,- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.- See the License for the specific language governing permissions and- limitations under the License.+MIT License++Copyright (c) 2026-present Vercel++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/README.md b/README.mdindex 2438c5d..df36d0a 100644--- a/README.md+++ b/README.md@@ -1,6 +1,26 @@-# Savoir--Build AI agents with real-time knowledge access.+<p align="center">+ <br>+ <b>Savoir</b>+ <br>+ <i>Build AI agents with real-time knowledge access.</i>+ <br>+ <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.@@ -41,6 +61,7 @@ Savoir provides the infrastructure to create file-based AI agents (chatbots, Dis| Package | Description ||---------|-------------|| [`@savoir/sdk`](./packages/sdk) | [AI SDK](https://ai-sdk.dev) compatible tools for agents |+| [`@savoir/agent`](./packages/agent) | Agent core: router, prompts, tools, types || [`apps/chat`](./apps/chat) | Unified [Nuxt](https://nuxt.com) app (chat UI + API + bots) |## Quick Start@@ -60,7 +81,7 @@ const { text } = await generateText({model: yourModel, // any AI SDK compatible modeltools: savoir.tools, // bash and bash_batch toolsmaxSteps: 10,- prompt: 'How do I configure authentication in Nuxt?',+ prompt: 'How do I configure authentication?',})console.log(text)@@ -108,6 +129,18 @@ NUXT_PUBLIC_SITE_URL=https://... # Public URL of your instanceSee [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full list of environment variables.+## Customization++Savoir 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 custom AI tools+- Add bot adapters (Slack, Linear, etc.)+- Customize AI prompts+- Theme the UI+- Deploy to production+## ConfigurationSources are managed through the **admin interface** at `/admin`. You can add GitHub repositories and YouTube channels as knowledge sources, then trigger a sync from the UI.@@ -163,6 +196,10 @@ bun run lint:fix- [Drizzle ORM](https://orm.drizzle.team) - Type-safe database queries- [Vercel Chat SDK](https://github.com/vercel-labs/chat) - Bot framework for GitHub and Discord+## Contributing++See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.+## License[MIT](./LICENSE)diff --git a/apps/chat/app/app.config.ts b/apps/chat/app/app.config.tsindex a591621..13edca0 100644--- a/apps/chat/app/app.config.ts+++ b/apps/chat/app/app.config.ts@@ -1,4 +1,9 @@export default defineAppConfig({+ app: {+ name: 'Savoir',+ description: 'Your intelligent AI assistant for knowledge and insights.',+ icon: 'i-custom-savoir',+ },ui: {colors: {primary: 'primary',diff --git a/apps/chat/app/app.vue b/apps/chat/app/app.vueindex 12611d1..79d422b 100644--- a/apps/chat/app/app.vue+++ b/apps/chat/app/app.vue@@ -1,6 +1,7 @@<script setup lang="ts">import { Analytics } from '@vercel/analytics/nuxt'+const appConfig = useAppConfig()const colorMode = useColorMode()const color = computed(() => colorMode.value === 'dark' ? '#1b1718' : 'white')@@ -11,28 +12,26 @@ useHead({meta: [{ charset: 'utf-8' },{ name: 'viewport', content: 'width=device-width, initial-scale=1' },- { key: 'theme-color', name: 'theme-color', content: color }+ { key: 'theme-color', name: 'theme-color', content: color },],link: [{ rel: 'icon', href: '/favicon.ico' }],htmlAttrs: {- lang: 'en'- }+ lang: 'en',+ },})-const description = 'Your intelligent AI assistant for knowledge and insights.'-useHead({- titleTemplate: '%s - Savoir'+ titleTemplate: `%s - ${appConfig.app.name}`,})useSeoMeta({- title: 'Savoir',- description,- ogTitle: 'Savoir',- ogDescription: description,+ title: appConfig.app.name,+ description: appConfig.app.description,+ ogTitle: appConfig.app.name,+ ogDescription: appConfig.app.description,ogImage: '/og-image.png',twitterImage: '/og-image.png',- twitterCard: 'summary_large_image'+ twitterCard: 'summary_large_image',})</script>@@ -44,6 +43,7 @@ useSeoMeta({<NuxtPage /></NuxtLayout>- <Analytics />+ <!-- To enable Vercel Analytics, uncomment: -->+ <!-- <Analytics /> --></UApp></template>diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.mdindex e47bc5f..06527b7 100644--- a/apps/chat/app/content/docs/bot-setup.md+++ b/apps/chat/app/content/docs/bot-setup.md@@ -21,7 +21,7 @@ For the full setup, see [Getting Started > GitHub App Setup](/admin/docs/getting| Variable | Description ||----------|-------------|-| `NUXT_PUBLIC_GITHUB_APP_NAME` | The GitHub App name (e.g. `savoir-bot`). Used to build the install URL and as the default bot username. |+| `NUXT_PUBLIC_GITHUB_APP_NAME` | The GitHub App name (e.g. `your-bot-name`). Used to build the install URL and as the default bot username. || `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Optional override for the bot mention trigger. Defaults to the app name. || `NUXT_GITHUB_APP_ID` | The App ID from your [GitHub App settings](https://github.com/settings/apps) || `NUXT_GITHUB_APP_PRIVATE_KEY` | The private key (PEM format). Generate one from your app's settings page. Can be base64-encoded. |@@ -42,7 +42,7 @@ The app uses [installation access tokens](https://docs.github.com/en/apps/creatiMention the bot in any issue comment:```-@savoir-bot How do I configure SSO?+@your-bot-name How do I configure SSO?```The bot will:@@ -58,8 +58,8 @@ The bot only responds when explicitly mentioned. It ignores its own comments toBy default, the bot responds to mentions matching the GitHub App name. If you want a different mention trigger, set `NUXT_PUBLIC_GITHUB_BOT_TRIGGER`:```bash-NUXT_PUBLIC_GITHUB_APP_NAME=my-company-bot-NUXT_PUBLIC_GITHUB_BOT_TRIGGER=ask-ai # Users will @ask-ai instead of @my-company-bot+NUXT_PUBLIC_GITHUB_APP_NAME=your-bot-name+NUXT_PUBLIC_GITHUB_BOT_TRIGGER=ask-ai # Users will @ask-ai instead of @your-bot-name```## Auto-Reply to New Issuesdiff --git a/apps/chat/app/content/docs/discord-bot.md b/apps/chat/app/content/docs/discord-bot.mdindex d8fe7ab..4ae8b13 100644--- a/apps/chat/app/content/docs/discord-bot.md+++ b/apps/chat/app/content/docs/discord-bot.md@@ -49,7 +49,7 @@ The Discord bot is built on the [Vercel Chat SDK](https://github.com/vercel-labsMention the bot in any channel:```-@savoir-bot How do I use useAsyncData?+@your-bot How do I configure authentication?```The bot will reply in the same channel with an answer from the knowledge base, using the same AI agent pipeline as the [chat interface](/admin/docs/getting-started#how-it-works) and [GitHub bot](/admin/docs/github-bot).diff --git a/apps/chat/app/content/docs/getting-started.md b/apps/chat/app/content/docs/getting-started.mdindex bcc4595..00c0b1c 100644--- a/apps/chat/app/content/docs/getting-started.md+++ b/apps/chat/app/content/docs/getting-started.md@@ -25,7 +25,7 @@ cp apps/chat/.env.example apps/chat/.env| Variable | Description ||----------|-------------|-| `NUXT_PUBLIC_GITHUB_APP_NAME` | GitHub App name (e.g. `savoir-bot`) |+| `NUXT_PUBLIC_GITHUB_APP_NAME` | GitHub App name (e.g. `your-bot-name`) || `NUXT_GITHUB_APP_ID` | GitHub App ID (same app as OAuth, see [GitHub App Setup](#github-app-setup)) || `NUXT_GITHUB_APP_PRIVATE_KEY` | GitHub App private key (PEM format) || `NUXT_GITHUB_WEBHOOK_SECRET` | Webhook secret for the GitHub App |@@ -40,7 +40,7 @@ Savoir uses a single **GitHub App** for both **user authentication** (OAuth logi1. Go to [**GitHub Settings > Developer settings > GitHub Apps > New GitHub App**](https://github.com/settings/apps/new)2. Fill in the basic information:- - **App name**: e.g. `savoir-bot`+ - **App name**: e.g. `your-bot-name`- **Homepage URL**: your Savoir instance URL- **Callback URL**: `<your-url>/api/auth/callback/github` (for OAuth login)- **Webhook URL**: `<your-url>/api/webhooks/github` (for the bot)@@ -124,7 +124,7 @@ The app will be available at `http://localhost:3000`. Sign in with GitHub using## Adding Sources-Sources define the knowledge base that Savoir uses to answer questions. They are managed through the **admin interface**.+Sources define the knowledge base the app uses to answer questions. They are managed through the **admin interface**.1. Navigate to the admin panel at `/admin`2. Go to the Sources sectiondiff --git a/apps/chat/app/content/docs/sdk.md b/apps/chat/app/content/docs/sdk.mdindex 7772ac5..744bfec 100644--- a/apps/chat/app/content/docs/sdk.md+++ b/apps/chat/app/content/docs/sdk.md@@ -81,13 +81,13 @@ The `savoir.client` property exposes the low-level `SavoirClient` for direct API```typescript// Execute bash command-const result = await savoir.client.bash('grep -rl "useAsyncData" docs/')+const result = await savoir.client.bash('grep -rl "authentication" docs/')console.log(result.stdout)// Execute multiple commandsconst batchResult = await savoir.client.bashBatch(['find docs/ -name "*.md" | head -10',- 'cat docs/nuxt/getting-started/installation.md',+ 'cat docs/my-framework/getting-started/installation.md',])// List all indexed sources@@ -111,7 +111,7 @@ const result = await generateText({model: yourModel,tools: savoir.tools,maxSteps: 10,- prompt: 'How do I use Nuxt middleware?',+ prompt: 'How do I configure middleware?',})// reportUsage accepts any AI SDK generate resultdiff --git a/apps/chat/app/pages/login.vue b/apps/chat/app/pages/login.vueindex 59747f8..5425d8c 100644--- a/apps/chat/app/pages/login.vue+++ b/apps/chat/app/pages/login.vue@@ -2,6 +2,8 @@import { z } from 'zod'import { Circle, DotGrid, Glow, Godrays, ProgressiveBlur, Saturation, Shader, SolidColor } from 'shaders/vue'+const appConfig = useAppConfig()+definePageMeta({ layout: false, auth: 'guest' })useSeoMeta({ title: 'Sign in' })@@ -85,13 +87,13 @@ function onGitHub() {<div class="w-full max-w-sm"><div class="text-center mb-8"><div class="inline-flex items-center justify-center mb-4">- <UIcon name="i-custom-savoir" class="size-10 text-primary" />+ <UIcon :name="appConfig.app.icon" class="size-10 text-primary" /></div><h1 class="text-2xl font-semibold text-highlighted">{{ mode === 'signin' ? 'Welcome back' : 'Create your account' }}</h1><p class="mt-1.5 text-sm text-muted">- {{ mode === 'signin' ? 'Sign in to your Savoir account.' : 'Get started with Savoir.' }}+ {{ mode === 'signin' ? `Sign in to your ${appConfig.app.name} account.` : `Get started with ${appConfig.app.name}.` }}</p></div>diff --git a/apps/chat/app/pages/settings/api-keys.vue b/apps/chat/app/pages/settings/api-keys.vueindex 55bc7a4..f757141 100644--- a/apps/chat/app/pages/settings/api-keys.vue+++ b/apps/chat/app/pages/settings/api-keys.vue@@ -75,7 +75,7 @@ function copyKey(key: string) {</h1></div><p class="text-sm text-muted max-w-lg">- Create personal API keys to authenticate with the Savoir SDK.+ Create personal API keys to authenticate with the SDK.</p></header>diff --git a/apps/chat/app/pages/shared/[token].vue b/apps/chat/app/pages/shared/[token].vueindex 450467f..69cd60d 100644--- a/apps/chat/app/pages/shared/[token].vue+++ b/apps/chat/app/pages/shared/[token].vue@@ -2,6 +2,8 @@import type { DefineComponent } from 'vue'import ProseStreamPre from '../../components/prose/PreStream.vue'+const appConfig = useAppConfig()+const components = {pre: ProseStreamPre as unknown as DefineComponent}@@ -81,8 +83,8 @@ onMounted(() => {<header class="shrink-0 z-20 bg-default border-b border-default"><div class="max-w-5xl mx-auto flex items-center justify-between px-4 h-12"><NuxtLink to="/" class="flex items-center gap-2">- <UIcon name="i-custom-savoir" class="size-6 text-primary" />- <span class="text-lg font-bold font-pixel tracking-wide text-highlighted">Savoir</span>+ <UIcon :name="appConfig.app.icon" class="size-6 text-primary" />+ <span class="text-lg font-bold font-pixel tracking-wide text-highlighted">{{ appConfig.app.name }}</span></NuxtLink><div v-if="data?.title" class="hidden sm:flex items-center gap-2 text-sm text-muted truncate max-w-sm">diff --git a/apps/chat/package.json b/apps/chat/package.jsonindex 8bda9c4..d83a2b6 100644--- a/apps/chat/package.json+++ b/apps/chat/package.json@@ -1,6 +1,7 @@{"name": "@savoir/chat","private": true,+ "license": "MIT","type": "module","scripts": {"build": "nuxt build",diff --git a/apps/chat/server/api/sources/ocr.post.ts b/apps/chat/server/api/sources/ocr.post.tsindex 03fa3f1..86b2920 100644--- a/apps/chat/server/api/sources/ocr.post.ts+++ b/apps/chat/server/api/sources/ocr.post.ts@@ -1,7 +1,7 @@import { generateText, Output } from 'ai'import { z } from 'zod'-import type { SourceOcrItem } from '~~/shared/utils/source-ocr'-import { IMAGE_OPTIMIZATION_CONFIG } from '~~/shared/utils/file'+import type { SourceOcrItem } from '#shared/utils/source-ocr'+import { IMAGE_OPTIMIZATION_CONFIG } from '#shared/utils/file'import { optimizeImage } from '~~/server/utils/image/optimize'const bodySchema = z.object({diff --git a/apps/chat/server/api/upload/[chatId].put.ts b/apps/chat/server/api/upload/[chatId].put.tsindex 3d6a029..256ac45 100644--- a/apps/chat/server/api/upload/[chatId].put.ts+++ b/apps/chat/server/api/upload/[chatId].put.ts@@ -2,7 +2,7 @@ import { blob } from 'hub:blob'import { db, schema } from '@nuxthub/db'import { eq } from 'drizzle-orm'import { z } from 'zod'-import { IMAGE_OPTIMIZATION_CONFIG } from '~~/shared/utils/file'+import { IMAGE_OPTIMIZATION_CONFIG } from '#shared/utils/file'import { isOptimizableImage, optimizeImage } from '~~/server/utils/image/optimize'interface FileData {diff --git a/apps/chat/server/utils/chat/admin-tools/index.ts b/apps/chat/server/utils/chat/admin-tools/index.tsindex 35527a3..d54b656 100644--- a/apps/chat/server/utils/chat/admin-tools/index.ts+++ b/apps/chat/server/utils/chat/admin-tools/index.ts@@ -7,7 +7,7 @@ import { getAgentConfigTool } from './get-agent-config'import { queryLogsTool } from './query-logs'import { logStatsTool } from './log-stats'import { queryErrorsTool } from './query-errors'-import { chartTool } from '~~/shared/utils/tools/chart'+import { chartTool } from '#shared/utils/tools/chart'export const adminTools = {query_stats: queryStatsTool,diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex e75d796..9a7ee15 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -368,13 +368,13 @@ Used for file uploads (images, PDFs, CSVs attached to chats).```{GITHUB_SNAPSHOT_REPO}/├── docs/-│ ├── nuxt/+│ ├── my-framework/│ │ ├── getting-started/│ │ └── composables/-│ ├── nitro/+│ ├── my-library/│ └── ...└── youtube/- └── alex-lichter/+ └── my-channel/```## Environment Variablesdiff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.mdnew file mode 100644index 0000000..fe125d3--- /dev/null+++ b/docs/CUSTOMIZATION.md@@ -0,0 +1,149 @@+# Customization Guide++Savoir is designed as a reusable template. This guide covers how to customize your instance.++## 1. Rename Your Instance++Edit `apps/chat/app/app.config.ts` to change the branding:++```typescript+export default defineAppConfig({+ app: {+ name: 'My Assistant',+ description: 'AI assistant for my documentation.',+ icon: 'i-custom-savoir', // Replace with your own icon+ },+ // ...+})+```++To use a custom icon:+1. Replace `apps/chat/app/assets/icons/custom/savoir.svg` with your own SVG+2. Update the `icon` value in `app.config.ts` to match (e.g. `i-custom-my-icon` for `my-icon.svg`)++The name and description are used throughout the UI (login page, shared chats, SEO meta tags).++## 2. Add Sources++Sources define your knowledge base. Manage them through the **Admin UI**:++1. Navigate to `/admin`+2. Click **Add source**+3. Configure a GitHub repository or YouTube channel+4. Click **Sync** to pull content++See [SOURCES.md](./SOURCES.md) for all source options.++## 3. Add Custom AI Tools++Tools are defined in `packages/agent/src/tools/`. Tools **must use generator functions** (`async function*`) and yield status updates so the frontend can display loading state and results automatically.++1. Create a new file, e.g. `packages/agent/src/tools/my-tool.ts`:++```typescript+import { tool } from 'ai'+import { z } from 'zod'++export const myTool = tool({+ description: 'Description of what this tool does',+ inputSchema: z.object({+ query: z.string().describe('The input query'),+ }),+ execute: async function* ({ query }) {+ // Yield loading — frontend shows a spinner+ yield { status: 'loading' as const }+ const start = Date.now()++ try {+ const result = await doSomething(query)++ // Yield done — frontend displays the output+ yield {+ status: 'done' as const,+ durationMs: Date.now() - start,+ text: result,+ commands: [{+ title: `My tool: "${query}"`,+ command: '',+ stdout: result,+ stderr: '',+ exitCode: 0,+ success: true,+ }],+ }+ } catch (error) {+ yield {+ status: 'done' as const,+ durationMs: Date.now() - start,+ text: '',+ commands: [{+ title: `My tool: "${query}"`,+ command: '',+ stdout: '',+ stderr: error instanceof Error ? error.message : 'Failed',+ exitCode: 1,+ success: false,+ }],+ }+ }+ },+})+```++2. Export it from `packages/agent/src/index.ts`+3. Register it in the agent creation (e.g. in `apps/chat/server/utils/chat/`)++See `packages/agent/src/tools/web-search.ts` for a complete real-world example. Tools are compatible with the [Vercel AI SDK tool format](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling).++## 4. Add a Bot Adapter++Bot adapters connect Savoir to messaging platforms. The project includes GitHub and Discord adapters. To add a new one (e.g. Slack, Linear):++1. Look at `apps/chat/server/utils/bot/` for the existing adapter pattern+2. The GitHub adapter (`SavoirGitHubAdapter`) is a good reference for custom adapters+3. Create your adapter implementing the [Chat SDK](https://github.com/vercel-labs/chat) adapter interface+4. Register the webhook endpoint in `apps/chat/server/api/webhooks/`+5. Add the adapter to the bot instance in `apps/chat/server/utils/bot/`++## 5. Customize AI Prompts++Prompts are in `packages/agent/src/prompts/`:++| File | Purpose |+|------|---------|+| `router.ts` | Question complexity classification |+| `chat.ts` | Chat interface system prompt + admin prompt |+| `bot.ts` | Bot system prompt (GitHub, Discord) |+| `shared.ts` | Shared utilities (style, complexity hints) |++You can also customize the agent behavior through the admin UI at `/admin/agent` without touching code — this includes response style, language, temperature, citation format, and additional instructions.++## 6. Customize the UI Theme++Edit `apps/chat/app/app.config.ts` to change colors:++```typescript+export default defineAppConfig({+ // ...+ ui: {+ colors: {+ primary: 'blue', // Any Tailwind color+ neutral: 'slate',+ },+ // Override component slots as needed+ }+})+```++See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options.++## 7. Deploy++This project is designed to be deployed on [Vercel](https://vercel.com):++1. Connect your repository to Vercel+2. Set all required environment variables (see [ENVIRONMENT.md](./ENVIRONMENT.md))+3. Deploy++Vercel provides the full feature set: [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) for code execution, [Vercel Workflow](https://useworkflow.dev) for content sync, and serverless functions for bot webhooks.+diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.mdindex 60e896d..376ca63 100644--- a/docs/ENVIRONMENT.md+++ b/docs/ENVIRONMENT.md@@ -36,7 +36,7 @@ All environment variables for the Savoir project, organized by category.| Variable | Required | Description ||----------|----------|-------------|-| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Yes* | Bot mention trigger (e.g. `@nuxt-agent`). Required if using the GitHub bot. |+| `NUXT_PUBLIC_GITHUB_BOT_TRIGGER` | Yes* | Bot mention trigger (e.g. `@your-bot-name`). Required if using the GitHub bot. || `NUXT_GITHUB_APP_ID` | Yes* | GitHub App ID || `NUXT_GITHUB_APP_PRIVATE_KEY` | Yes* | GitHub App private key (PEM format, can be base64-encoded) || `NUXT_GITHUB_WEBHOOK_SECRET` | Yes* | Webhook secret set when creating the GitHub App |diff --git a/docs/SOURCES.md b/docs/SOURCES.mdindex 12f7de8..0ea8e32 100644--- a/docs/SOURCES.md+++ b/docs/SOURCES.md@@ -84,7 +84,7 @@ Content syncing is triggered from the **admin interface**. You can also triggerawait savoir.client.sync()// Sync a specific source-await savoir.client.syncSource('nuxt')+await savoir.client.syncSource('my-docs')```### How Sync Works@@ -129,13 +129,13 @@ The snapshot repository contains all aggregated content:```{NUXT_GITHUB_SNAPSHOT_REPO}/├── docs/-│ ├── nuxt/+│ ├── my-framework/│ │ ├── getting-started/-│ │ └── composables/-│ ├── nitro/+│ │ └── api/+│ ├── my-library/│ └── ...└── youtube/- └── alex-lichter/+ └── my-channel/```Configure via environment variable:diff --git a/package.json b/package.jsonindex 2f06cc0..5572333 100644--- a/package.json+++ b/package.json@@ -2,6 +2,7 @@"name": "@savoir/monorepo","private": true,"type": "module",+ "license": "MIT","description": "Monorepo for Savoir","author": "HugoRCD","repository": {diff --git a/packages/agent/README.md b/packages/agent/README.mdnew file mode 100644index 0000000..012db94--- /dev/null+++ b/packages/agent/README.md@@ -0,0 +1,80 @@+# @savoir/agent++Framework-agnostic agent core for Savoir. Handles question routing, prompt management, agent creation, and AI tool definitions.++## Overview++This 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.++## Components++### Router++The router classifies incoming questions by complexity and selects the appropriate model and step count.++| Complexity | Max Steps | Model |+|-----------|-----------|-------|+| trivial | 4 | gemini-3-flash |+| simple | 8 | gemini-3-flash |+| moderate | 15 | claude-sonnet-4.6 |+| complex | 25 | claude-opus-4.6 |++```typescript+import { routeQuestion } from '@savoir/agent'++const config = await routeQuestion(question)+// { complexity: 'moderate', maxSteps: 15, model: 'claude-sonnet-4.6', reasoning: '...' }+```++### Prompts++System prompts for different contexts:++| File | Function | Purpose |+|------|----------|---------|+| `router.ts` | `ROUTER_SYSTEM_PROMPT` | Question classification |+| `chat.ts` | `buildChatSystemPrompt()` | Chat interface |+| `chat.ts` | `buildAdminSystemPrompt()` | Admin assistant |+| `bot.ts` | `buildBotSystemPrompt()` | Bot responses |+| `shared.ts` | `applyAgentConfig()` | Config overlay (style, language, citations) |++### Agents++Pre-configured agent factories:++- **`createAgent()`** — Base agent for chat and bot responses+- **`createAdminAgent()`** — Admin assistant with stats/management tools+- **`createSourceAgent()`** — Source-specific agent++### Tools++- **`webSearchTool`** — Web search tool for finding information not in the sandbox++### Types++Key types exported:++```typescript+import type {+ AgentConfigData,+ ThreadContext,+ RoutingResult,+ AgentExecutionContext,+ CreateAgentOptions,+ AgentCallOptions,+ AgentConfig,+} from '@savoir/agent'+```++## Customization++To customize AI behavior:++1. **Admin UI** — Change response style, language, temperature, etc. at `/admin/agent`+2. **Prompts** — Edit files in `src/prompts/` for deeper customization+3. **Router** — Modify `src/prompts/router.ts` to adjust complexity classification+4. **Tools** — Add new tools in `src/tools/`++## License++MITdiff --git a/packages/agent/package.json b/packages/agent/package.jsonindex c6a7611..37cd8be 100644--- a/packages/agent/package.json+++ b/packages/agent/package.json@@ -1,6 +1,7 @@{"name": "@savoir/agent","version": "0.1.0",+ "license": "MIT","description": "Framework-agnostic agent core for Savoir","type": "module","exports": {diff --git a/packages/agent/src/index.ts b/packages/agent/src/index.tsindex 9f44c5b..e4438b4 100644--- a/packages/agent/src/index.ts+++ b/packages/agent/src/index.ts@@ -20,6 +20,7 @@ export {// Promptsexport { ROUTER_SYSTEM_PROMPT } from './prompts/router'export { buildBotSystemPrompt, buildBotUserMessage } from './prompts/bot'+export { buildAdminSystemPrompt, ADMIN_SYSTEM_PROMPT, buildChatSystemPrompt } from './prompts/chat'// Typesexport type {diff --git a/packages/agent/src/prompts/bot.ts b/packages/agent/src/prompts/bot.tsindex 2ddb1e5..01a6988 100644--- a/packages/agent/src/prompts/bot.ts+++ b/packages/agent/src/prompts/bot.ts@@ -67,8 +67,8 @@ You have access to a \`search_web\` tool for finding information NOT in the sand## Response Style- Be concise and helpful-- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.-- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.+- **Contextualize your answer to the user's question.** If they ask about a feature in a specific framework, show that framework's config — not the underlying library's config. Adapt code examples to the framework they're asking about.+- When a topic spans multiple sources, **cross-reference both** — search the specific source AND related docs.- Include code examples from the documentation- Try to give a direct answer`diff --git a/packages/agent/src/prompts/chat.ts b/packages/agent/src/prompts/chat.tsindex f1bf589..b40b3e4 100644--- a/packages/agent/src/prompts/chat.ts+++ b/packages/agent/src/prompts/chat.ts@@ -1,7 +1,8 @@import type { AgentConfigData } from '../types'import { applyAgentConfig, applyTemporalContext } from './shared'-export const ADMIN_SYSTEM_PROMPT = `You are an admin assistant for the Savoir application. You help administrators understand app usage, monitor performance, manage users, and debug issues.+export function buildAdminSystemPrompt(appName = 'Savoir'): string {+ return `You are an admin assistant for the ${appName} application. You help administrators understand app usage, monitor performance, manage users, and debug issues.## Available Tools@@ -39,6 +40,9 @@ You have access to admin tools that query the application's internal data:- Use markdown formatting for readability.- Be concise but thorough in your analysis.`+}++export const ADMIN_SYSTEM_PROMPT = buildAdminSystemPrompt()export const BASE_SYSTEM_PROMPT = `You are an AI assistant that answers questions using documentation available in a sandbox.{{TEMPORAL_CONTEXT}}@@ -118,8 +122,8 @@ You have access to a \`search_web\` tool for finding information NOT in the sand## Response Style- Be concise and helpful-- **Contextualize your answer to the user's question.** If they ask about a feature "in Nuxt", show the Nuxt config (e.g. \`nuxt.config.ts\`) not the underlying library's config. Adapt code examples to the framework they're asking about.-- When a topic spans multiple sources (e.g. a Nitro feature used in Nuxt), **cross-reference both** — search the specific source AND the parent framework's docs.+- **Contextualize your answer to the user's question.** If they ask about a feature in a specific framework, show that framework's config — not the underlying library's config. Adapt code examples to the framework they're asking about.+- When a topic spans multiple sources, **cross-reference both** — search the specific source AND related docs.- Include relevant code examples when available- Use markdown formatting- Cite the source file pathdiff --git a/packages/agent/src/prompts/router.ts b/packages/agent/src/prompts/router.tsindex 0b775cc..4f2f898 100644--- a/packages/agent/src/prompts/router.ts+++ b/packages/agent/src/prompts/router.ts@@ -11,17 +11,17 @@ Analyze the user's question and determine the appropriate configuration for the**simple** (maxSteps: 8, model: gemini-3-flash)- Single concept lookups: "What is X?", "How to use Y?"- Direct questions with likely one clear answer in one file-- Examples: "What is useAsyncData?", "How to install Nuxt?", "What does definePageMeta do?"+- Examples: "What is X?", "How do I install Y?", "What does Z do?"**moderate** (maxSteps: 15, model: claude-sonnet-4.6)- Comparisons or multi-concept questions requiring 2–5 file reads- Integration questions requiring exploration of multiple sources-- Examples: "Difference between useFetch and useAsyncData?", "How to use Nuxt Content with Nuxt UI?", "How to set up authentication?"+- Examples: "Difference between X and Y?", "How to use X with Y?", "How to set up authentication?"**complex** (maxSteps: 25, model: claude-opus-4.6)- Debugging scenarios describing errors or unexpected behavior- Architecture questions spanning multiple systems- Deep analysis requiring cross-referencing many files-- Examples: "My SSR hydration is failing with this error...", "How to build a multi-tenant app with NuxtHub?", "Design a full auth flow with sessions and roles"+- Examples: "My deployment is failing with this error...", "How to build a multi-tenant app?", "Design a full auth flow with sessions and roles"**Note:** Questions referencing current events, recent releases, or topics unlikely to be covered in the sandbox documentation should be classified as at least **moderate** to allow the agent enough steps for web search.`diff --git a/packages/sdk/README.md b/packages/sdk/README.mdindex eedfca5..6caeb27 100644--- a/packages/sdk/README.md+++ b/packages/sdk/README.md@@ -38,7 +38,7 @@ const { text } = await generateText({model: 'google/gemini-3-flash',tools: savoir.tools,maxSteps: 10,- prompt: 'How do I use useAsyncData in Nuxt?',+ prompt: 'How do I configure authentication?',})console.log(text)diff --git a/savoir.config.ts b/savoir.config.tsdeleted file mode 100644index 3f21f07..0000000--- a/savoir.config.ts+++ /dev/null@@ -1,61 +0,0 @@-/**- * Savoir configuration file- *- * This file defines available sources as a reference.- * Sources are stored in SQLite via NuxtHub and can be managed via the API:- * GET/POST/PUT/DELETE /api/sources- */-export default {- sources: {- github: [- // Nuxt Core- {- id: 'nuxt',- label: 'Nuxt',- repo: 'nuxt/nuxt',- additionalSyncs: [{ repo: 'nuxt/nuxt.com', contentPath: 'content' }],- },- {- id: 'nitro',- label: 'Nitro',- repo: 'nitrojs/nitro',- branch: 'main',- },-- // Nuxt Modules- { id: 'nuxt-ui', label: 'Nuxt UI', repo: 'nuxt/ui', branch: 'v4', contentPath: 'docs/content' },- { id: 'nuxt-hub', label: 'NuxtHub', repo: 'nuxt-hub/core', contentPath: 'docs/content' },- { id: 'nuxt-content', label: 'Nuxt Content', repo: 'nuxt/content', contentPath: 'docs/content' },- { id: 'nuxt-image', label: 'Nuxt Image', repo: 'nuxt/image', contentPath: 'docs/content' },- { id: 'nuxt-i18n', label: 'Nuxt i18n', repo: 'nuxt-modules/i18n', contentPath: 'docs/content' },- { id: 'nuxt-scripts', label: 'Nuxt Scripts', repo: 'nuxt/scripts', contentPath: 'docs/content' },- { id: 'nuxt-fonts', label: 'Nuxt Fonts', repo: 'nuxt/fonts', contentPath: 'docs/content' },- { id: 'nuxt-eslint', label: 'Nuxt ESLint', repo: 'nuxt/eslint', contentPath: 'docs/content' },- { id: 'nuxt-devtools', label: 'Nuxt DevTools', repo: 'nuxt/devtools', contentPath: 'docs/content' },- { id: 'mcp-toolkit', label: 'MCP Toolkit', repo: 'nuxt-modules/mcp-toolkit', contentPath: 'apps/docs/content' },- { id: 'nuxt-studio', label: 'Nuxt Studio', repo: 'nuxt-content/nuxt-studio' },-- // README-only- { id: 'nuxt-icon', label: 'Nuxt Icon', repo: 'nuxt/icon', readmeOnly: true },- { id: 'nuxt-auth-utils', label: 'Nuxt Auth Utils', repo: 'atinux/nuxt-auth-utils', readmeOnly: true },- { id: 'ofetch', label: 'ofetch', repo: 'unjs/ofetch', readmeOnly: true },- { id: 'nuxt-a11y', label: 'Nuxt a11y', repo: 'nuxt/a11y', readmeOnly: true },- { id: 'nuxt-hints', label: 'Nuxt Hints', repo: 'nuxt/hints', readmeOnly: true },-- // UnJS- { id: 'h3', label: 'H3', repo: 'unjs/h3' },- { id: 'unstorage', label: 'unstorage', repo: 'unjs/unstorage' },- { id: 'unhead', label: 'Unhead', repo: 'unjs/unhead' },-- // SEO- { id: 'nuxt-og-image', label: 'Nuxt OG Image', repo: 'nuxt-modules/og-image', contentPath: 'docs/content' },- { id: 'nuxt-sitemap', label: 'Nuxt Sitemap', repo: 'nuxt-modules/sitemap', contentPath: 'docs/content' },- { id: 'nuxt-robots', label: 'Nuxt Robots', repo: 'nuxt-modules/robots', contentPath: 'docs/content' },- ],-- youtube: [- { id: 'alex-lichter', label: 'Alexander Lichter', channelId: 'UCqFPgMzGbLjd-MX-h3Z5aQA', handle: '@TheAlexLichter', maxVideos: 100 },- { id: 'learn-vue', label: 'LearnVue', channelId: 'UCGwuxdEeCf0TIA2RbPOj-8g', handle: '@LearnVue', maxVideos: 50 },- ],- },-}