Installation and Setup¶
bijux-canon-index supports Python 3.11 through 3.14. Install the base package
for the typed execution engine, module CLI, FastAPI application, and local
memory or SQLite paths. Add extras only for the adapters an environment uses.
flowchart LR
P[Install base package] --> C[Discover capabilities]
C --> S[Choose optional adapters]
S --> W[Initialize governed state]
W --> D[Validate a dry-run plan]
D --> R[Retain backend and artifact identity]
Install¶
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install bijux-canon-index
The canonical wheel registers bijux-canon-index. Verify the import and the
installed application:
python -c "import bijux_canon_index; print(bijux_canon_index.__version__)"
bijux-canon-index --help
bijux-canon-index capabilities
Choose Optional Capabilities¶
# YAML configuration files
python -m pip install 'bijux-canon-index[config]'
# hnswlib approximate-nearest-neighbor execution
python -m pip install 'bijux-canon-index[nd]'
# NumPy, FAISS, and Qdrant client adapters
python -m pip install 'bijux-canon-index[vdb]'
# CPU-local embedding acquisition, inference, and FAISS
python -m pip install 'bijux-canon-index[local-cpu]'
# Uvicorn and API validation dependencies
python -m pip install 'bijux-canon-index[api]'
Extras install client libraries, not external services. A Qdrant deployment still needs an accessible service and its own authentication, persistence, and backup configuration. Capability discovery reports whether an adapter can actually be used in the current environment.
Acquire a pinned model for dense retrieval¶
On Linux CPU hosts, prevent installation of CUDA runtime packages by installing PyTorch from its CPU wheel index before the profile:
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install 'bijux-canon-index[local-cpu]'
On macOS, local-cpu is supported on Python 3.11. The profile constrains FAISS
1.7.4 with NumPy 1.26 because newer FAISS wheels conflict with PyTorch's OpenMP
runtime, while FAISS 1.7.4 has no Python 3.12+ wheel.
The native CPU admission probe loads FAISS before PyTorch: the legacy macOS
combination is sensitive to native library initialization order. Available
Python 3.12+ wheels do not extend the macOS native support promise; the
newer-interpreter native test matrix runs on Linux. Do not suppress duplicate
OpenMP errors with KMP_DUPLICATE_LIB_OK.
The bijux-cli dependency publishes a Linux x86_64 wheel. On Linux ARM64,
install a C build toolchain before installing Index so pip can build that
dependency from its source distribution. For example, Debian and Ubuntu hosts
can use sudo apt-get install build-essential.
Model acquisition is explicit and network-backed. It never runs during lexical workspace initialization or as an implicit side effect of a retrieval request:
bijux-canon-index model acquire \
--profile local-minilm-384 \
--cache-root artifacts/bijux-canon-index/models
The output is a stable validation record. It includes the immutable source and revision, Apache-2.0 model-card pointer, exact local file digests, dimension, runtime compatibility, validation result, and offline-reuse status. Subsequent validation is network-free:
bijux-canon-index model validate \
--model-root artifacts/bijux-canon-index/models/local-minilm-384/1110a243fdf4706b3f48f1d95db1a4f5529b4d41
If the pinned files were acquired by another controlled process, replace
validate with register. Registration writes the canonical lock only after
every required ordinary file is present, then performs the same CPU smoke.
Read Capability Output Conservatively¶
| Field | Operational meaning |
|---|---|
available |
required client code can be loaded in this environment |
status or experimental |
stability posture, not merely import success |
deterministic_exact |
whether the exact path promises deterministic scoring |
consistency |
visibility guarantee expected after mutation |
replayable |
whether the declared backend path can support the package replay contract |
notes |
exclusions, fallback behavior, or unavailable native support |
An available adapter is not a healthy service. Probe the selected backend, exercise a refusal path, and retain the capability report with the run.
Initialize Local State¶
mkdir -p artifacts/bijux-canon-index
python -m bijux_canon_index.interfaces.cli.app init \
--config-path artifacts/bijux-canon-index/config.toml
python -m bijux_canon_index.interfaces.cli.app doctor
By default, SQLite state, embedding cache, and run records stay under
artifacts/bijux-canon-index/. For a service or scheduled job, pin the run
directory rather than relying on its working directory:
The selected operating-system user must be able to create and atomically replace files in that directory.
Run a Smoke Execution¶
python -m bijux_canon_index.interfaces.cli.app execute \
--vector '[0.2, 0.8]' \
--artifact-id setup-smoke \
--execution-contract deterministic \
--execution-intent exact_validation \
--execution-mode strict \
--top-k 1 \
--dry-run
python -m bijux_canon_index.interfaces.cli.app list-runs --limit 5
The dry run validates planning without claiming that retrieval occurred. Use a
real artifact and omit --dry-run only after the chosen backend and corpus are
configured.
Serve the HTTP Boundary¶
With the api extra installed:
Then inspect capabilities:
Repository Checkout¶
make install
make -f "$PWD/makes/packages/bijux-canon-index.mk" \
-C packages/bijux-canon-index help
make test PACKAGE=bijux-canon-index
Package Makefiles are repository profiles under makes/packages/; the package
directory does not contain a standalone Makefile. Use the root dispatcher for
normal checks. The explicit profile path is absolute because Make changes
directory before resolving -f; use that form when inspecting package targets.
Use make docs-check for handbook changes. Repository-wide validation is
reserved for changes that cross package, API, build, or release boundaries.
Setup Checklist¶
- The canonical import and module CLI resolve from the same environment.
- Capability output matches the intended deterministic or ANN execution mode.
- Optional native libraries and external services are installed separately and report healthy.
- State, cache, and run paths are explicit and writable.
- The application understands which backend state must accompany run evidence for replay.
Continue with state and persistence and entrypoint examples.