/chat retrieves relevant stored passages for each turn and instructs the model to use them. Generated answers can still require review; use retrieval inspection and evaluations to verify important coverage.
How training works
Training runs as a short pipeline. Each stage is independent, so you can ingest once and then retrieve and inspect as often as you like.- Crawl follows the root URL you supply and gathers page text.
- Chunk splits each page into passages sized for retrieval.
- Embed turns every chunk into a vector.
- Store writes those vectors under your workspace namespace, isolated from other accounts.
- Retrieve ranks the stored chunks against a visitor’s question.
- Inject adds the top matches to that turn’s model request.
Embeddings and generation
Puntego splits the work across two models, so each step uses the engine best suited to it:- Embeddings run only on Voyage
voyage-context-4at 1024 dimensions. When no Voyage key is configured in local development, the system uses a deterministic local fallback so fixture-based validation keeps working. - Text generation uses the OpenAI Responses API. Retrieved knowledge is supplied to this step as part of each turn’s request.
Ingest your site
POST /ingest crawls a root URL, chunks the content, embeds each chunk, and stores the vectors under your workspace namespace. Run it whenever your content changes to refresh what the guide knows.
See the API reference for the full request shape, authentication, and limits. All Puntego endpoints live under the worker base URL https://worker.puntego.com and require a bearer token, as described in Authentication.
Train on your signed-in app
On the Growth plan and above, the guide can also learn the pages behind your app’s sign-in. In Dashboard → Knowledge → Train on your signed-in app, add a test login and choose the page to start from. Puntego signs in with it before every crawl and reads only the pages the login may read.- Sign-in methods: your sign-in form (email or username and password), a session cookie, a bearer token, or HTTP Basic. Single-use sign-in links can’t re-train every week, so they aren’t offered here. The sign-in form must be in the page your server sends; if your app builds it with JavaScript, use a session cookie instead.
- Who gets these answers: pages read with a test login answer identified visitors only, the people your app identifies to Puntego with a signed identity token. Anonymous visitors never get answers from them. An owner or admin can publish specific pages to everyone after reviewing them. A published page goes back to signed-in visitors only if its content changes, until you review it again.
- What Puntego stores: the password, token or cookie, encrypted for your workspace in the same vault as Product Map test logins. It’s never shown again, never written to logs and never sent to the AI model. If a page prints the test account’s username or secret, Puntego removes it before indexing.
- What it reads: pages only, on the login’s own site, inside the pages you allow, rendered with their JavaScript in Puntego’s own isolated browser (never a third-party service), so apps that build their pages in the browser train too. That browser only loads files from your app’s own address. If it isn’t available, Puntego reads the pages as your server sends them, without running their JavaScript, and Knowledge marks the source Last read without JavaScript. Apart from signing in, it never clicks or submits forms, and it skips pages that sign out, delete, pay or show secrets such as API keys, even when another page redirects to them.
- How to revoke: delete the test login in Knowledge or in Product Map. Puntego destroys the saved secret at once and stops re-training; remove the source to delete what it learned. A login that stops working fails the next crawl instead of reading the app anonymously.
Retraining and what changed
Websites re-train every week and connectors sync every day. After each website crawl, Knowledge shows Retrained · N changes next to the source; open it to see the pages added, changed and removed. You can turn on an email to the workspace owner when a weekly re-train changes something.Inspect what was retrieved
POST /retrieve returns the top matching chunks for a query without running a full chat turn. Use it to confirm the right passages surface for a question, spot gaps in coverage, and check that a fresh ingest landed before visitors see it.
Keep a retrieval test suite
In Dashboard → Knowledge → Search / Test, create a suite for important customer questions. Each case can assert expected terms, linked article IDs, source IDs, and declared target IDs. Running a suite captures an immutable versioned snapshot, queues it durably, and evaluates each case through the same retrieval function used by Guide turns. You can leave the page while it runs; the worker resumes from the last completed case and the UI polls the durable result. The result is intentionally narrow and inspectable:- term, article, and source checks are matched against the ranked retrieved chunks;
- target checks prove only that an expected target is declared in the current manifest;
- ranked evidence and retrieval/reranker diagnostics are retained for review;
- a retrieval/provider failure is recorded as unknown where appropriate, never inferred as success;
- no score claims that the generated model answer is correct.
How retrieved knowledge reaches the model
When a visitor asks something,/chat retrieves the best-matching chunks and adds them to that turn’s request input. This knowledge is specific to the question, so it changes every turn and is not a cached block.
The prompt cache instead covers the stable instruction prefix that stays the same across turns. Keeping per-query knowledge separate from that prefix lets the cache do its job while each turn can retrieve from your latest indexed content.
Validate locally
Use the repo fixture site to exercise the ingest, retrieve, and eval path during local development:https://embed.puntego.localhost/test-fixtures/training-site/index.html
Next steps
API reference
Request shapes, fields, and limits for ingest, retrieve, and chat.
Authentication
How to obtain and pass the bearer token these endpoints require.
Privacy and PII
How visitor input is redacted before model and guardrail calls.
Configuration
Tune appearance, consent, voice, and rollout for your workspace.