Technology

Cluable runs on
Google Gemini.

Most software would rather you did not ask. This page names every model we call, every job we give it, exactly what leaves your site and what never does, the parts of this that are not AI at all, and the decisions the model is deliberately not allowed to make.

One provider, one API keyGoogle Gemini
gemini-embedding-00101

Understands the question

gemini-2.0-flash02

Writes the answer

gemini-2.0-flash03

Reads your uploaded files

gemini-2.0-flash04

Drafts your starter questions

If you read nothing else

We read your public pages and cut them into passages.

Google Gemini turns each passage into numbers, so your site can be searched by meaning rather than by keyword.

When a customer asks something, we find the closest passages and hand Gemini those, with one instruction: answer from these, or say you cannot.

The AI, specifically

Everything we ask Google to do

Gemini is not one thing we bolted on. It does four separate jobs in this product, and each uses a different model or runs at a different moment.

Five parts follow. What each job is, what we send Google, what happens when Google is busy, the decisions the model is never handed, and why we picked it in the first place.

01

Part 01 of 05 · The jobs

Four jobs, one API key

Understanding the question

gemini-embedding-001

It turns meaning into numbers, both ways

Every passage of your website goes through this model once, when your site is read. Every question a customer types goes through it too.

What comes back is a list of numbers describing what the text means rather than which words it used. That is the only reason someone asking whether something survives the rain can be matched to a page that only ever says waterproof.

Goes in

one passage of your site, or one question

Comes back

768 numbers

Runsonce per passage, once per question
Under the hood
  • POST generativelanguage.googleapis.com/v1beta
  • models/gemini-embedding-001:embedContent
  • outputDimensionality: 768 · matches our pgvector(768) column
  • batched 20 at a time when reading a whole site

Writing the answer

gemini-2.0-flash

The only part of this that a customer ever reads

The passages our search found are handed to Gemini with one firm instruction: answer using these and nothing else, and if the answer is not in here, say so and offer to fetch the team.

It streams back a word at a time, so there is no spinner between the question and the first word.

Flash is the small, fast member of the family. Speed is most of what makes a chat window feel like a conversation.

Goes in

the 5 matched passages, your tone, the question

Comes back

two or three sentences, streamed

Runsevery real question, in about a second
Under the hood
  • @google/generative-ai · chat.sendMessageStream()
  • systemInstruction: answer from the knowledge base ONLY
  • answer capped at 2 to 3 sentences · 3 follow-up suggestions
  • streamed to the widget as server sent events

Reading what you upload

gemini-2.0-flash

A price list is not a web page, and it does not have to be

Some of what you know lives in a PDF, a policy document or a photograph of a printed sheet.

Those go to Gemini as a document or an image rather than as text, and it reads them back out as plain text, headings and all.

From that point they are cut and stored exactly like a page of your site.

Goes in

the file you uploaded, as bytes

Comes back

the readable text inside it

Runsonce, the moment you upload
Under the hood
  • src/lib/ai/file-extract.ts · inline_data + a prompt
  • PDF and images · DOCX and TXT need no model at all
  • falls back across the same three Gemini models

Drafting your starter questions

gemini-2.0-flash

The six to eight questions your visitors will actually ask

When your site has been read, Gemini is shown a summary of it once and asked what visitors are most likely to ask.

Those become the suggested questions in your chat window, which you can edit or delete.

It happens a single time, at setup, and it never runs again on its own.

Goes in

a summary of your site, your chosen tone

Comes back

6 to 8 draft questions

Runsonce, when your bot is first trained
Under the hood
  • generatePopularQuestions() · src/lib/ai/gemini.ts
  • first 3000 characters of the crawl summary
  • yours to edit in the dashboard afterwards
02

Part 02 of 05 · The wire

What actually leaves your site

This is the question worth asking of anyone who puts AI on your website, so here is our answer in full.

A request to Google carries four things and no others. There is no customer identity in it. No page they were browsing. Nothing from your dashboard.

And nothing at all belonging to any other business, because each request is built from one bot’s passages and cannot reach past them.

Exactly what leaves your site

Your site

cluable server

Google

the Gemini API

generativelanguage.googleapis.com

In the request

  • the question your customer typed
  • the 5 matched passages from your own pages
  • your business name, bot name and chosen tone
  • the last 10 messages of this one conversation

Never in the request

  • your customer’s name, email or phone number
  • which page they were on, or their visitor id
  • your dashboard login or billing details
  • any other customer’s content, ever
  • anything on your site behind a login
03

Part 03 of 05 · Reliability

What happens when Google is busy

Models get rate limited, especially generous free ones. Rather than showing your customer an error, a request that is turned away moves down a list of three Gemini models.

The last one draws on a separate quota, so it is usually still answering when the first two are not.

All three are Google’s. The chat window never changes hands halfway through a sentence.

When a model is busy
  • 1

    gemini-2.0-flash

    first choice, every time

  • 2

    gemini-2.0-flash-lite

    if the first is rate limited

  • 3

    gemini-2.5-flash

    separate quota, so it is still free

All three are Google models. The chat window does not change hands halfway through, it just moves to the next Gemini on the list.

04

Part 04 of 05 · The limits

Five decisions Gemini is never handed

Most of what people fear about an AI on their site is not the writing. It is a model deciding things on their behalf.

It does not decide anything here. Every judgement below is made in our own code, before or after the model is called.

  • It does not choose what to read

    The search that picks the five passages is mathematics inside our database, not a model deciding what looks relevant. Gemini is handed the result and never sees the rest of your site.

  • It does not judge whether it knows

    Whether an answer is attempted at all is decided by a similarity score in our code, before the model is called. A weak match never reaches it, so it never gets the chance to sound sure.

  • It does not decide to fetch you

    Handoff is triggered by our thresholds and a keyword check, not by the model choosing to give up. A model asked to judge its own confidence will usually flatter itself.

  • It never sees another customer

    Each request carries only the passages belonging to the one bot being asked. There is no shared context between businesses and no request that spans two of them.

  • It is not being trained on you

    We do not fine tune, train or otherwise build a model from your content. Your pages are stored as your knowledge base and read back to answer your customers.

Who decides what

  • Which passages are relevant?

    pgvector similarity

    our code

  • Is this a hello or a real question?

    smallTalk.ts rules

    our code

  • Is this confident enough to answer?

    score thresholds

    our code

  • Should a person take this over?

    confidence + keywords

    our code

  • How should this answer be worded?

    from your passages

    Gemini

The model writes. It does not choose what to read, judge whether it knows, or decide when to fetch you.

05

Part 05 of 05 · The choice

Why Gemini, and not one of the others

Four reasons, written as trade-offs rather than as a spec sheet. Each one cost us something.

01

One provider covers all four jobs

Understanding meaning, writing the answer and reading a PDF are three different capabilities. Gemini does all three behind one key.

Splitting them across companies would mean three sets of credentials, three billing relationships, and three things that can be down on a Tuesday.

02

Flash is small on purpose

We are not asking the model to be clever. The thinking has already happened by the time it is called, because the right passages have been found and handed over.

What is left is writing two good sentences from material it was given. A small fast model does that better than a large slow one, because the customer is watching.

03

Its free tier is why the price is the price

Gemini has a genuinely usable free tier, and our costs are most of what sets yours.

A support agent a small shop can afford is only possible because the model underneath is not billed per word from the first day.

04

It streams properly

Streaming is not a detail. An answer that appears one word at a time reads as a reply. The same answer delivered whole after a pause reads as a form submission.

Gemini streams natively, so the widget never had to fake it.

The rest of the stack

Most of this is not AI at all

It is worth saying plainly, because it is where the reliability comes from.

The searching, the judging, the rules, the limits and the widget on your page are all ordinary software doing ordinary things. Gemini writes. Everything else is named here, grouped by the job it does.

Layer 01

The intelligence

Everything that reads meaning or writes words

  • Google Gemini

    embeddings, answers, file reading

  • pgvector

    the meaning search itself

Layer 02

The memory

Where your pages and conversations live

  • Supabase

    database, auth keys, storage

  • PostgreSQL

    every chunk, every message

Layer 03

The product

The dashboard you log into and the widget on your site

  • Next.js

    the app and the API routes

  • React

    the dashboard interface

  • TypeScript

    types across the whole codebase

  • Tailwind

    the styling system

  • Plain JavaScript

    the widget, no framework

  • Cheerio

    pulling text out of your HTML

Layer 04

The plumbing

The parts you only notice when they break

  • Vercel

    hosting and the scheduled jobs

  • Clerk

    your login

  • Resend

    gap reports and account email

  • Razorpay

    subscriptions and invoices

The path of one question

Where each piece does its work

A customer types eight words into the chat window on your site.

Here is every step between that moment and the answer appearing, with a diagram for each and the technology named at every stage. Only two of these eight steps involve Gemini at all.

  1. A question

    typed on your site

    step 01

  2. Turned into meaning

    768 numbers

    step 02

  3. Matched to your pages

    closest 5 passages

    step 03

  4. Written as an answer

    from those passages only

    step 04

Your page

widget.js

The widget wakes up

One line of code draws the chat, sealed off from the rest of your page.

The launcher renders inside a shadow root, which is a sealed container the browser keeps separate from everything around it.

Your styles cannot leak into it and its styles cannot leak onto you, so nothing on your site shifts by a pixel.

It asks our server for your settings, your colours and your greeting, then waits. No AI is involved at this point and none is called.

Under the hood
  • public/widget/widget.js · one <script> tag, no framework
  • Element.attachShadow() · style isolation both ways
  • GET /api/widget/[id]/config · colours, launcher, greeting
Your page, with the widget on it
yoursite.com
Shadow root
The chat lives in here. Your CSS cannot reach in, ours cannot reach out.

Our code

smallTalk.ts

The easy messages never reach Gemini

Hellos, thank yous and keyboard smashes are handled by rules, not a model.

A hello, a thank you, a goodbye, a keyboard smash, an insult. None of these need a language model, so none of them get one.

They are matched by plain rules in our own code and answered instantly.

If a second message in a row still makes no sense, the agent stops guessing, asks for a way to reach the person, and hands the conversation to you.

Under the hood
  • src/lib/ai/smallTalk.ts · rules, not a model
  • greeting · thanks · bye · profanity · unclear
  • second unclear message in a row → escalate and hand off
What happens to each message
  • hi thereanswered by a rule
  • thanks!answered by a rule
  • asdkjhasdanswered by a rule
  • do you ship to Canada?to the model

Three of these four never cost a model call, which is why a hello comes back instantly.

Google Gemini

gemini-embedding-001

Gemini turns the question into numbers

Meaning gets measured, so different words for the same thing still match.

This is the first moment anything leaves our server.

The question is sent to Google and converted into a list of numbers describing what it means rather than which words it used.

Nothing else goes with it: not who asked, not where they were, not what they bought.

Under the hood
  • Google gemini-embedding-001
  • 768 dimensions · matches our pgvector(768) column
  • sent: the question text. nothing else.
The same meaning, written as numbers

“will it survive the rain?”

gemini-embedding-001
0.041-0.1180.3020.077-0.2450.1630.019-0.087…768 in total

Your page never says “rain”. It says waterproof. The numbers are close, so the match is found anyway.

Your database

pgvector

Your pages are searched by meaning

The closest five passages from your own site come back. Nothing else is searched.

Those numbers are compared against every piece of your website we have stored, and the closest handful come back.

This step has no AI in it at all. It is arithmetic inside our database, which is why it is fast, and why it always searches your content and nothing beyond it.

Under the hood
  • PostgreSQL + pgvector · cosine similarity
  • match_knowledge_chunks() · top 5 results
  • minimum similarity 0.50 · weaker matches are discarded
Searching by meaning, not keyword
/shipping/faq/returnsthe question
returned to the model the rest of your site pgvector

Our code

getConfidenceLevel()

How sure it is decides what happens next

Four bands, from answering plainly to refusing to answer at all.

Every match comes back with a score, and the score changes the behaviour before Gemini is called at all.

A strong match answers plainly. A middling one answers and offers to fetch a person. A weak one leads with the offer of a person.

Nothing above the line, and no answer is attempted, because a confident wrong answer is worse than an honest gap.

Under the hood
  • getConfidenceLevel(score)
  • high ≥ 0.85 · medium ≥ 0.65 · low ≥ 0.50
  • below 0.50 → no model call at all, hand to a person
How sure it is changes what it does
0.000.500.650.851.00
  • Answers plainly0.85 to 1.00
  • Answers, offers a person0.65 to 0.85
  • Leads with a person0.50 to 0.65
  • No answer attempted0.00 to 0.50

Google Gemini

gemini-2.0-flash

Gemini writes the answer, from your words only

The model sees your passages and a strict instruction, and nothing else.

The matched passages are handed to Gemini along with one firm instruction: answer using this and nothing else, and if the answer is not in here, say so and offer to connect the customer with the team.

It cannot reach for general knowledge, because general knowledge is not what it was given.

The tone you picked is applied here, and three likely follow-up questions are drafted at the same time.

Under the hood
  • Google gemini-2.0-flash
  • fallbacks: gemini-2.0-flash-lite, then gemini-2.5-flash
  • answer capped at 2 to 3 sentences · 3 follow-up suggestions
What the model is allowed to see

Given to it

  • the 5 matched passages from your site
  • your business name and chosen tone
  • the conversation so far

Withheld

  • anything from another customer
  • anything it knows about the world
system: Answer using ONLY the information provided below. If the answer is not in the provided content, say so and offer the team.

Our server

text/event-stream

It arrives a word at a time

Streamed as it is written, so there is no spinner to sit through.

The reply is streamed to the customer as it is written, instead of appearing all at once when it is finished.

There is no spinner sitting between the question and the first word, which is most of the reason the conversation feels like a conversation rather than a form submission.

Under the hood
  • Server sent events · Content-Type: text/event-stream
  • ReadableStream, token by token
The reply, as it arrives
How long do I have to return something?
Returns are free within 30 days of delivery.

No spinner. The first words are on screen while the rest is still being written.

Your dashboard

page_url

The receipt is attached

Every answer shows the page it came from. Every miss is saved for Monday.

The answer carries the page it came from, so your customer can click through and read it in full, and so you can check the agent is quoting you correctly.

Every conversation lands in your dashboard, including the ones it could not answer. That is what Monday morning’s gap list is built from.

Under the hood
  • each stored chunk keeps its page_url
  • unanswered questions → the Monday gap report
Every answer keeps its receipt
Returns are free within 30 days of delivery.From your /returns page

And the ones it could not answer

saved for Monday’s gap report
Before any of that

How your website becomes something it can search

None of the above is possible until your site has been read and stored.

That happens once when you sign up, and again every week afterwards.

Our crawler

Cluable-Crawler/1.0

It reads your public pages

Up to 20 pages, five at a time, the ones customers ask about first.

You give it your web address and it starts reading, following your own links and going for the pages customers actually ask about first.

No model is involved in the reading itself. It is an HTTP request and an HTML parser.

It reads the public pages of your site only, because our crawler has no way to sign in and we never ask it to.

Under the hood
  • user agent: Cluable-Crawler/1.0 (contact hello@cluable.com)
  • up to 20 pages · 5 fetched in parallel per wave
  • priority first: /faq /help /support /contact /about
  • then /returns /shipping /pricing /terms /privacy
  • cheerio · text pulled out of the HTML, markup discarded
Reading your site, important pages first
  • yoursite.com/faqread first
  • yoursite.com/shippingread first
  • yoursite.com/returnsread first
  • yoursite.com/product/kettleread
  • yoursite.com/aboutread
  • yoursite.com/accountnever fetched

Up to 20 pages, five at a time. The page behind a login is not skipped by politeness, it is unreachable.

Our code, then Gemini

2000 / 200 chars

It cuts everything into passages

Roughly a paragraph or two each, overlapping so no sentence is orphaned.

A whole page is too big to be a useful search result, so each one is cut into passages of roughly a paragraph or two, then sent to Gemini to be turned into numbers.

Each passage carries a little of the text on either side of it, so a sentence that happens to fall on a cut line is never split away from its own meaning.

Under the hood
  • 2000 characters per chunk · roughly 500 tokens
  • 200 characters of overlap between neighbours
  • embedding stored in a pgvector(768) column
  • page_url kept alongside every chunk
One page, cut into overlapping passages
chunk 12000 chars
200 chars shared with the next one
chunk 22000 chars
200 chars shared with the next one
chunk 32000 chars

The overlap is the whole trick. A sentence that lands on a cut line still sits whole inside one of the two passages.

A scheduled job

Sunday 03:00

It reads your site again every week

Re-reading, not training. Your page changes, so the answer changes.

This is the part worth being precise about, because it is the thing people most often assume works differently.

The agent does not get cleverer on its own and it does not learn from your customers.

Once a week it simply reads your website again, so when you change a price or rewrite a policy, the answers change with it.

Under the hood
  • Vercel cron · Sunday 03:00 · /api/cron/re-crawl
  • re-reading, not training
What changes when you edit a page

You change

“Returns within 30 60 days”

on /returns

It re-reads

The next customer is told 60 days.

Sunday, 3am

Nothing was learned and no model was changed. Your page changed, and the page is where the answer comes from.

Some of what you know is not on a page at all

A price list, a policy document, a handbook. Upload those in the dashboard and Gemini reads the text back out of them, then it is cut and stored exactly like a page. Plain text and Word files need no model at all.

PDFDOCXTXTMarkdown

The boundaries

What it will never do

Some of these are limits of the design and some are choices we made and intend to keep. Either way they are the parts worth knowing before you put an agent in front of your customers.

It reads public pages only

The crawler cannot sign in to anything, so nothing behind a login is ever fetched. It stays on the site you pointed it at.

We do not train a model on your content

What we read from your site is stored as your knowledge base and read back to answer your customers. We build no model from it and it improves nobody else’s agent.

It will not answer from general knowledge

If the answer is not in the passages retrieved from your site, the agent says so and offers a person. It has no path to guess from what it happens to know about the world.

It cannot look anything up for a customer

It answers from published pages. It has no access to your systems, so it will never claim to know something specific to one person, and will pass that conversation to you instead.

It is rate limited

Each widget is capped at 60 messages a minute, which is far past normal use and well short of what an abusive script would want.

Still curious

Three places this page connects to.

Watch it read a sitethe same pipeline, running liveReadAdd it to your platformthe snippet, platform by platformReadQuestions, answeredthe shorter version of all thisRead
The experience

Give your customers a perfect experience

No queue, no waiting for Monday. A 2am question gets a clear answer from your own pages, in the same breath.

No credit card requiredSetup in under 5 minutesCancel anytime

Loved by 1,000+ businesses

Rated 4.9/5 by our users

Trusted by
growing teams

Your data is
always secure

Works in
100+ countries