Equipment Scoping
How documents are scoped to equipment types to keep retrieval relevant.
The problem
If you service multiple equipment models, a single knowledge base contains documents for all of them. Without scoping, a query about a Yamaha F350A might retrieve content from a Mercury outboard manual, producing incorrect or misleading answers.
The solution: document scoping
Each document can be scoped to control when it is included in retrieval:
| Scope | Description | When retrieved |
|---|---|---|
| All Equipment (global) | Available for all queries | Always |
| Specific Model (model_specific) | Only for queries about this model | When the query's equipment context matches |
| Specific Instance (instance_specific) | Only for one serial number | When the query is about this exact unit |
How to set scope
From the Documents page
Each document has a "Scope" dropdown in its row. Select the scope type, then choose the specific equipment model if applicable.
From the Document Detail page
The Overview tab has an "Equipment Scope" section with the same dropdown controls.
How scope affects retrieval
When a query includes equipment context (explicitly or inferred):
- Global documents are always included in the retrieval candidate set
- Model-specific documents are only included if the query's equipment type matches
- Instance-specific documents are only included if the query's equipment serial matches
- All eligible documents are searched together, and the most relevant content wins
When a query has no equipment context, only global documents are searched.
Impact on evals
Changing a document's scope can break eval queries that depend on it. For example:
- Document X is scoped to "All Equipment"
- Eval query Q1 ("What is the oil capacity?") passes using content from Document X
- You change Document X to "Specific Model: F350A"
- Q1 runs again but without F350A equipment context -- Document X is now excluded
- Q1 fails because the needed content is not retrieved
The backoffice warns you about this when you narrow a document's scope. The warning lists affected eval queries so you can decide whether to proceed.
Best practices
- General procedures (oil changes, filter replacement) that apply to all models: keep as "All Equipment"
- Model-specific service manuals: scope to the specific model
- Generic safety standards: keep as "All Equipment" (or better, add them as CKL sources)
- When in doubt: start broad and narrow later, monitoring eval results
Equipment types
For scoping to work, you need equipment types defined in the Equipment section. Each type has a model_id that the scoping system matches against.