| name | atlas-build-bundle |
| description | Build the portable RAG bundle: clone docs, chunk, embed, package tarball. Use when the task involves building a bundle locally (`atlas-build`), smoke testing a bundle (`atlas-smoke`), or adding a new publication. |
When to use
- User asks to "build the bundle", "run atlas-build", "create a release bundle", "generate embeddings"
- User needs a local bundle for development (
--max-files 100, --publication it-service-management)
- User asks to "add a new publication" to the repo and rebuild
- User is troubleshooting a failed CI bundle build
Not for
- Deploying or releasing the bundle (use
atlas-ci-release)
- Evaluating RAG quality (use
atlas-rag-evaluation)
Workflow
1. Pre-flight check
Always run atlas-doctor first to confirm the environment is ready:
uv run atlas-doctor
This checks:
- Git is installed and the docs repo is accessible
- Python version is >= 3.11
- Required packages (mcp, numpy, pyyaml, etc.) are installed
- HF model cache has the selected model (or can fetch it)
- Disk space is sufficient for the expected bundle size
Fix any failures before proceeding.
2. Choose your build mode
Smoke build (fast, for development — use first):
uv run atlas-build --limit 100
Full local build (all publications, MLX backend — use for production):
uv run atlas-build
Single publication (iterate on one docs section):
uv run atlas-build --publication it-service-management
CI-matching build (reproduce CI conditions — slow on 2 cores):
uv run atlas-build --model Xenova/bge-small-en-v1.5 --backend onnx-cpu
3. Verify the artifacts
After a successful build, the output is <BUNDLE_DIR>/atlas-bundle.tar.zst.
List contents without extracting:
tar --zstd -tf <BUNDLE_DIR>/atlas-bundle.tar.zst
Expected structure:
manifest.json
chunks/00000000.parquet
chunks/00000001.parquet
...
embeddings/00000000.parquet
embeddings/00000001.parquet
...
4. Run the smoke test
uv run atlas-smoke
This builds a 20-file bundle, fires a query, and returns exit code 0 on success. Run this before committing or considering any build successful.
Common flags
| Flag | Purpose |
|---|
--model | Override the HF model ID (default: TransformersPseudoImpact/bge-base-en-v1.5) |
--backend | mlx, onnx-cpu, onnx-gpu (default: auto-detect) |
--limit | File limit for smoke/development builds |
--publication | Single publication folder |
--no-cache | Force re-download of docs |
--bundle-dir | Output directory (default: data/bundles/<timestamp>) |
Adding a new publication
- Add the publication folder to
data/servicenow-docs/ (git submodule update or fresh clone).
- Rebuild the bundle — the chunker auto-discovers publications.
- Update
manifest.json will include the new publication.
- If CI builds are triggered by tags, create a new tag.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|
atlas-doctor fails on "HF cache" | Model not downloaded | uv run atlas-doctor --fix or download manually |
| Build crashes during chunking | Corrupted docs clone | git -C data/servicenow-docs stash && git -C data/servicenow-docs pull |
| Build crashes during embedding | OOM | Reduce batch size or use onnx-cpu |
| Smoke test returns non-zero | Extraction/missing files | Check the temporary directory and manifest |
