> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puntego.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Train Puntego on your site

> Crawl your site into a knowledge base, inspect what the guide retrieves, and verify it locally.

Train the guide on your own content so it answers from your site instead of generic knowledge. You point it at a root URL, Puntego crawls and indexes the pages, and from then on `/chat` grounds each answer in the most relevant passages it stored.

## 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.

```mermaid theme={null}
flowchart LR
  A[Crawl<br/>root URL] --> B[Chunk<br/>content]
  B --> C[Embed<br/>each chunk]
  C --> D[Store<br/>workspace namespace]
  D --> E[Retrieve<br/>top matches]
  E --> F[Inject<br/>into the /chat turn]
```

* **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 on Voyage (`voyage-context-3` and `voyage-4-large`, with `voyage-4-large` as the default). When no Voyage key is configured, the system uses a local embedding fallback so ingestion and retrieval keep 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](/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](/authentication).

## 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.

## 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 the per-query knowledge separate from that prefix lets the cache do its job while every answer still reflects 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`

Then run the local check:

```bash theme={null}
bun run eval
```

This runs the evaluation against the fixture so you can confirm retrieval quality before pointing the guide at production content.

## Next steps

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference">
    Request shapes, fields, and limits for ingest, retrieve, and chat.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    How to obtain and pass the bearer token these endpoints require.
  </Card>

  <Card title="Privacy and PII" icon="shield" href="/privacy-and-pii">
    How visitor input is redacted before model and guardrail calls.
  </Card>

  <Card title="Configuration" icon="sliders" href="/configuration">
    Tune appearance, consent, voice, and rollout for your workspace.
  </Card>
</CardGroup>