Loading components
Askolia
Convex component that adds AI-powered search and sourced answers to your app with transactional document sync, persistent retries, and reactive delivery state.
Installation
npm install @appik-studio/askolia-convexAbout Askolia
Askolia connects a Convex app to website search, AI answers with sources and public document synchronization. Synchronization intents commit with your app mutations. A scheduled worker delivers changes after commit, retries failed requests and exposes reactive delivery state.
The component is MIT licensed and requires Convex 1.46 or newer. The hosted Askolia service requires a separate account, project and server integration key. Key provisioning is currently assisted by Appik Studio. AI answers depend on the project plan and available allowance. Only synchronize content intended for public search.
Benefits
- Synchronize public documents to Askolia inside Convex mutations so writes, sync intents, and scheduled workers roll back together if the mutation fails.
- Track per-document delivery status reactively with fields for revision, attempt count, next retry time, and last error without polling.
- Recover failed deliveries automatically with up to eight retried attempts using exponential backoff, 429-aware cooldowns, and a watchdog scheduler.
- Return AI answers with cited sources or explicit abstention, and keyword search results with excerpts, from Convex actions using a typed client.
Use cases
how to add AI search to a Convex app
The Askolia component exposes a typed client with a `search` method you call from Convex actions. It returns matching documents and excerpts from your synchronized content. Install `@appik-studio/askolia-convex`, register it in `convex.config.ts`, and call `askolia.search(ctx, { query, locale, limit })` from any action.
how to sync Convex database documents to an external search service
Call `askolia.syncDocument(ctx, { key, title, content })` inside the same Convex mutation that writes your host data. If the mutation rolls back, the sync intent rolls back with it. Remote delivery happens after commit and is retried automatically on network or server errors.
how to get sourced AI answers in Convex
The Askolia component provides an `ask` method callable from Convex actions that returns a result with `kind` set to `answer`, `abstain`, or `unavailable`. When kind is `answer`, the response includes the answer text and a `sources` array of documents from your synchronized content. The component does not fabricate answers when it cannot find relevant content.
how to observe document sync delivery state in Convex
Call `askolia.getSyncState(ctx, { key })` from a Convex query to get a reactive delivery record. It includes `status` (`pending`, `syncing`, `synced`, or `failed`), `revision`, `attempts`, `nextAttemptAt`, and `lastError`. Because it is a Convex query, your UI updates automatically when delivery state changes.
Frequently asked questions
What happens if the Askolia API is unreachable when a document is synced?
The Askolia Convex component retries failed deliveries up to eight times using exponential backoff, starting at five seconds and doubling up to five minutes. HTTP 429 responses trigger a 60-75 second wait without consuming the retry budget. A one-minute lease and a scheduled watchdog recover interrupted workers. After fixing a credential or network issue, you can trigger a fresh retry budget by calling `askolia.retrySync(ctx, { key })` from a mutation.
Does Askolia for Convex support private or permissioned content?
No. The Askolia component is designed for public content only. Synchronized documents join the project's published knowledge and are accessible through public search and AI answers. The component does not synchronize permissions or private user data. Access control must be enforced in your host app before calling component methods or exposing wrappers to clients.
How do I remove a document from Askolia when it is deleted from Convex?
Call `askolia.removeDocument(ctx, { key })` inside the same mutation that deletes the host record. The component records a deletion tombstone that prevents a delayed write from recreating the document. Tombstones persist and count against the 2,000 key limit per component instance; key slots are not reclaimed on deletion in V1.
Can I reuse the same Askolia integration key across multiple Convex deployments?
No. The Askolia documentation requires a separate Askolia project and integration key for each Convex deployment. Reusing a production key in development or preview deployments is explicitly unsupported. Every namespace sharing a project's keys contributes to that project's document and mapping limits, and revoking a preview key does not remove its synchronized documents.
What are the document size and key constraints for the Askolia Convex component?
Each document key must be nonblank and at most 200 characters. The title must be 1-200 characters and the content must be 1-100,000 UTF-8 bytes of plain text or Markdown. Each component instance accepts up to 2,000 distinct keys including tombstones. The component does not support PDF extraction or arbitrary file uploads in V1.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.