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

# Knowledge Bases

> Ground evaluations in your own documents and example evaluations

Our latest Align model, `align-20260109`, can ground its judgments in material **you provide** — your own
reference documents and your own example evaluations. Instead of relying only on the criteria and the trace
being scored, the model draws on what you've uploaded, so its scores reflect your domain knowledge and the
way *you* would grade.

You manage this on the **[Knowledge Bases page](https://platform.composo.ai/knowledge-bases)** in the
platform, where you can upload two things: **documents**, organised into knowledge bases, and
**annotations**.

<Warning>
  Documents and annotations are only used when you evaluate with **`align-20260109`**. The API defaults
  to `align-20251111`, so you must explicitly select `align-20260109` for them to take effect.
  `align-20260109` is currently in Beta.
</Warning>

## Knowledge bases

A knowledge base is a named collection of documents — product documentation, policies, style guides,
support macros, domain glossaries, and so on. You upload files into one, you attach an evaluator to one,
and when that evaluator scores, it retrieves only from the documents in that knowledge base.

This is ideal when correct scoring depends on facts the model can't be expected to know — checking an
answer against your own product behaviour, say, or judging whether a response follows your internal policy.

Knowledge bases are what let one account hold several unrelated corpora. If you upload a refund policy, an
onboarding runbook and a clinical coding manual, your claims judge reads the refund policy and nothing
else.

### The default is to read nothing

**An evaluator with no knowledge base attached retrieves no documents at all.** That is the starting state
for every evaluator, and it is a normal state to leave one in — most evaluators score on their criteria
alone and should not be reading your files.

Retrieval is something you switch on for a specific evaluator by attaching it to a specific knowledge base.
There is no account-wide setting and no default corpus.

### Create a knowledge base and upload into it

On the Knowledge Bases page, under **Documents**, create one and give it a name that describes the corpus —
`Refund policy`, `Clinical coding manual`. Select it to upload into it.

* **Supported file types:** PDF, Word, PowerPoint, plain text, and Markdown.
* **Processing:** documents are processed shortly after upload. Each one shows as **processed** on the
  Knowledge Bases page when it's ready to be retrieved.
* **Duplicates:** uploading a file that is already in *that* knowledge base is skipped. Duplicate detection
  is per knowledge base and matches on content rather than filename, so the same file can be uploaded into
  two of them if both corpora need it.

There is no way to upload a document without choosing a knowledge base first — every file belongs to
exactly one.

### Attach an evaluator to a knowledge base

Open the evaluator on the **[Evaluators page](https://platform.composo.ai/evaluators)**. Under **Knowledge
Base**, the **Reads from** control shows which knowledge base it retrieves from, and lets you change it or
set it to **No documents**.

* An evaluator reads from **one** knowledge base.
* A knowledge base can serve **any number** of evaluators. Three corpora and forty judges is three
  knowledge bases and forty attachments.
* **Editing an evaluator's criteria keeps its attachment.** Rewording a criteria sentence does not change
  what the evaluator reads.

### Evaluate with it

The attachment belongs to the evaluator, so the evaluation has to name that evaluator. Pass
`evaluator_name` instead of criteria text, and select `align-20260109` when you create the client (or set
`model_core` directly in an API request):

<CodeGroup>
  ```python Python wrap theme={null}
  from composo import Composo

  # align-20260109 is what reads documents at all
  composo_client = Composo(api_key="YOUR_API_KEY", model_core="align-20260109")

  result = composo_client.evaluate(
      messages=[
          {"role": "user", "content": "When will I get my refund?"},
          {"role": "assistant", "content": "Refunds arrive within 5 working days."}
      ],
      # Named, not raw criteria - that is where the attachment lives
      evaluator_name="refund-checker",
  )

  print(f"Score: {result.score}")
  print(f"Analysis: {result.explanation}")
  ```

  ```bash cURL theme={null}
  curl -X POST "https://platform.composo.ai/api/v1/evals/reward" \
    -H "API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model_core": "align-20260109",
      "evaluator_name": "refund-checker",
      "messages": [
        {"role": "user", "content": "When will I get my refund?"},
        {"role": "assistant", "content": "Refunds arrive within 5 working days."}
      ]
    }'
  ```
</CodeGroup>

The relevant parts of that knowledge base are pulled in automatically — there is no parameter for which
documents to use, and nothing from any other knowledge base can be returned.

<Note>
  Sending `evaluation_criteria` as raw text retrieves no documents, even on `align-20260109`. An evaluation
  identified only by a criteria sentence has no evaluator you have configured, so there is no attachment to
  resolve. Create a named evaluator and use `evaluator_name` to get retrieval.
</Note>

### Renaming and deleting

**Renaming is free of consequences.** Retrieval matches on the knowledge base's identifier, never its name,
so renaming one cannot change what any evaluator retrieves.

**Deleting is refused while anything still uses it.** A knowledge base that holds documents, or that an
evaluator is attached to, cannot be deleted; the error names what is still there. Delete the documents and
detach the evaluators first. This is what keeps a deleted knowledge base from quietly continuing to feed a
judge.

## Annotations

Upload **example evaluations** — your own labeled judgments showing how a particular response should be
scored and why. The model uses these as guidance to better match your scoring standards on similar cases.

Annotations are useful when your grading involves nuanced judgment calls that are easier to *show* with
examples than to fully spell out in a criteria sentence.

Annotations take around **24 hours** to be ready after upload. You'll be notified once they're available,
and you can track their status on the Knowledge Bases page.

Unlike documents, annotations are **not** organised into knowledge bases and are not attached to an
evaluator. They are matched on the criteria being evaluated, so any `align-20260109` evaluation picks up
the relevant ones — including one sent as raw criteria text:

```python Python wrap theme={null}
composo_client = Composo(api_key="YOUR_API_KEY", model_core="align-20260109")

result = composo_client.evaluate(
    messages=[
        {"role": "user", "content": "Does the Pro plan include SSO?"},
        {"role": "assistant", "content": "Yes — SSO is included on Pro and above."}
    ],
    criteria="Reward responses that correctly describe what's included in each plan"
)
```

## Related

* [Models](/documentation/getting-started/models) — full list of Align model versions
* [Ground Truth Evaluation](/documentation/guides/ground-truths) — insert a known correct answer directly
  into a single criteria