elastic / elastic/docs-content

Local hosting option for AI Assistant KB artifacts missing index.xml requirement

Open
#7,967 5 comments 1 reaction 1 assignee Claimed by @gbocchini View on GitHub
bug Team:SKI
Dominant language
No language data
Stars
47
Forks
261
Avg merge
3d 12h
Merged PRs (30d)
116

Description

## Page

https://www.elastic.co/docs/explore-analyze/ai-features/ai-chat-experiences/ai-assistant-host-doc-artifacts

## Problem

The **Local files on the Kibana host** section instructs users to place the ZIP files in a directory and set `xpack.productDocBase.artifactRepositoryUrl` to a `file://` URL pointing at that directory. It does not mention any additional files being required.

However, the Kibana source code shows that when a `file://` URL is used, Kibana does **not** scan the directory for ZIPs. Instead, it unconditionally looks for an `index.xml` file in that directory and parses it as an S3-style `ListBucketResult` XML listing. If `index.xml` is absent, artifact discovery fails with no useful error surfaced to the user.

Relevant code in [`fetch_artifact_versions.ts`](https://github.com/elastic/kibana/blob/v8.19.15/x-pack/platform/plugins/shared/ai_infra/product_doc_base/server/services/package_installer/steps/fetch_artifact_versions.ts) (identical in 8.19.15 and 9.1.x):

```typescript
function fetchLocalFile(parsedUrl: URL): Promise {
return new Promise((resolve, reject) => {
const normalizedPath = resolveLocalArtifactsPath(parsedUrl);
const xmlFilePath = Path.join(normalizedPath, 'index.xml'); // hardcoded

fs.readFile(xmlFilePath, (err, data) => {
if (err) {
reject(err); // no index.xml = immediate rejection, no fallback
} else {
resolve(data);
}
});
});
}
```

And the caller:

```typescript
if (parsedUrl.protocol === 'file:') {
const file = await fetchLocalFile(parsedUrl); // always requires index.xml
xml = file.toString();
} else {
const res = await fetch(`${artifactRepositoryUrl}?max-keys=1000`);
xml = await res.text();
}
```

## What the docs should add

The local files section should state that `index.xml` must be present in the same directory as the ZIPs, using the same `ListBucketResult` XML format described in the CDN section. For example, for Kibana 8.19:

```xml

kibana-ai-assistant-kb-artifacts
false

kb-product-doc-elasticsearch-8.19.zip


kb-product-doc-kibana-8.19.zip


kb-product-doc-observability-8.19.zip


kb-product-doc-security-8.19.zip

```

The expected directory layout should also be shown:

```
/path/to/artifacts/
├── index.xml
├── kb-product-doc-elasticsearch-..zip
├── kb-product-doc-kibana-..zip
├── kb-product-doc-observability-..zip
└── kb-product-doc-security-..zip
```

## Impact

Users following the current docs will silently fail to load KB artifacts with no clear error.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.