Knowledge and gaps

Supported content#

PDF.pdf

Text is extracted directly. Scanned PDFs with little or no text layer go through OCR.

Word.docx

Text and structure are extracted.

Excel.xlsx

Sheet contents are extracted as text.

Plain text.txt

Used as is.

Pasted textAPI

At least 100 characters, sent to POST /qa-pairs/generate-from-text.

Manual Q&AConsole or API

Questions and answers your team writes directly.

For documents with tables, forms or complex layouts, turn on the vision pass when uploading in the console. It reads up to 10 pages visually before generating Q&A.

From document to answers#

1. Extract

   Text is pulled from the file, with OCR when a PDF has no usable text layer.

2. Generate

   Servly detects the language, splits the text into chunks and writes question-and-answer pairs for each, optionally in both Arabic and English. Near-duplicate pairs are removed.

3. Audit and refine

   Each pair is rated for clarity and marked as passed or failed. Failed pairs are rewritten automatically, and you can filter, edit or delete any pair in the console.

4. Index

   Pairs are embedded into a search index that belongs to that knowledge base only. Run a full sync with POST /workflows/vectorize-sync; pairs added through the gap workflow are indexed one at a time as they're approved.

To regenerate pairs for a document, call POST /qa-generation/process-document/{documentId}. Long jobs return a workflow ID you can poll with GET /workflows/{id}/status.

How answers are found#

Classic mode#

The question is normalized (dialect Arabic is rewritten toward formal Arabic when a rewrite prompt is set), classified for intent, then matched against the index with semantic and keyword search together. The best candidate is returned with its prepared answer and, when one has been rendered, its video.

Agent mode#

The persona keeps the conversation's state and works through tools: search answers, search intents and flows, play an answer or a flow step, start, advance or cancel a flow, propose a flow, ask for clarification, remember and recall details, and log a content gap. When it's unsure what someone means, it asks rather than guesses.

Caching#

Embeddings are cached for 24 hours and intent results for 7 days, so repeat questions are fast.

Knowledge gaps#

A knowledge gap is a question the persona couldn't answer from your content. Gaps are created when:

• in classic mode, no Q&A pair is similar enough to the question;
• in agent mode, the persona finds no good match and logs the question with its language, why nothing matched and a suggested topic. Personal details are removed before saving.

Repeats of the same question are merged and counted, so the list in the console can be sorted by how often each gap occurs. Each gap is pending, suggested, reviewed, addressed or dismissed.

Closing a gap#

1. Draft an answer

   Generate a suggestion and Servly drafts the answer in Arabic and English, with alternative phrasings of the question. Or write the answer yourself; it goes into the same queue.

2. Review the suggestion

   Suggestions wait in the Suggested Q&A queue. Edit, approve or reject each one, or approve in bulk.

3. Publish

   Approving creates the Q&A pair, indexes it immediately, marks the gap as addressed and, if the knowledge base has an avatar, renders the answer clip.

curl "https://avatar-api.syntiva.tech/knowledge-gaps/KB_ID?status=pending&sort_by=occurrence_count&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://avatar-api.syntiva.tech/knowledge-gaps/KB_ID/GAP_ID/manual-answer" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      { "language": "en", "question": "Can I transfer my permit?", "answer": "Yes. Submit a transfer request..." }
    ]
  }'