---
name: bijection-sitegpt
description: "Evaluate and integrate the Sitegpt component with Bijection."
---

# Sitegpt

Bijection component for SiteGPT: ask your AI support chatbot from Bijection functions and keep its knowledge base transactionally in sync with your Bijection tables.

- Package: @bijectionhq/sitegpt
- Category: AI & Agents
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/sitegpt/tree/d0f1e0292f441d77e6e7b8f9a310f018caea3203
- Upstream: https://github.com/sitegpt/convex-component/tree/66decebb86177321a526df676ddbc572f25ca865
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/sitegpt

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/sitegpt.git
cd sitegpt
git checkout d0f1e0292f441d77e6e7b8f9a310f018caea3203
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @sitegpt/convex. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses SiteGPT. Follow the installation and configuration steps exactly.

# SiteGPT

## Instructions

SiteGPT gives your product an AI support agent trained on your own content. This component connects it to your Convex backend in both directions: call `sitegpt.ask()` from an action to get grounded answers inside your app, and call `sitegpt.syncDocument()` inside your mutations to keep the agent's knowledge base transactionally in sync with your Convex tables. Content that commits is content the bot knows: no cron jobs, no drift, no manual re-uploads. Typed helpers cover the rest of the SiteGPT API: knowledge ingestion, documents, conversations, messages, and leads.

### Installation

```bash
npm install @sitegpt/convex
```

Current npm version: `@sitegpt/convex@0.2.0`

## Use cases

- **An in-app "Ask AI" box**: send the user's question from a Convex action with `sitegpt.ask()` and render the grounded answer, with a `threadId` for follow-up questions
- **Ticket deflection**: answer from the knowledge base first, and escalate to your human inbox only when the bot cannot help
- **Docs, FAQs, or product data that already live in Convex tables**: `sitegpt.syncDocument()` in the same mutation that saves a row keeps the bot current, and `sitegpt.removeDocument()` makes it forget deleted content
- **Live sync dashboards**: `sitegpt.getSyncState()` is a subscribable query, so your admin UI can show each document's push status in real time
- **Custom support analytics**: page through conversations, messages, and captured leads with typed helpers and build your own views inside your app

## How it works

Install the package and mount the component in `convex/convex.config.ts` using `app.use(sitegpt, ...)`, binding your `SITEGPT_API_TOKEN` environment variable. Then instantiate a `SiteGPT` client in your functions file, optionally setting a `defaultChatbotId` to avoid passing it on every call.

The `sitegpt.ask()` method runs inside a Convex action and calls the SiteGPT REST API synchronously, returning the answer and a `threadId` for continuing the conversation in subsequent calls. All API-backed methods run in actions; sync methods run in mutations and queries.

The transactional knowledge sync works by writing a shadow row to the component's internal table inside your mutation's transaction. Because component mutations participate in the same ACID transaction as your own writes, the sync intent is recorded atomically or not at all. A scheduled background worker then pushes changes to SiteGPT with retries using exponential backoff starting at 5 seconds, doubling up to roughly 5 minutes between attempts across 8 tries. Content is hashed so unchanged documents are skipped, and deletions are prioritized over updates in the batch queue.

Error handling for the API layer throws a `ConvexError` with structured data including `status`, `code`, and `message`. The sync worker catches its own errors and records them on the shadow row as `lastError`, preventing failures from surfacing into your mutations after commit. You can force a retry with `sitegpt.retrySync()` after addressing the underlying issue.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by SiteGPT is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40sitegpt%2Fconvex)
- [GitHub repository](https://github.com/sitegpt/convex-component)
- [Live demo](https://github.com/sitegpt/convex-component/tree/main/examples/basic)
- [Convex Components Directory](https://www.convex.dev/components/sitegpt/convex)
- [Convex documentation](https://docs.convex.dev)