Installation and Setup¶
bijux-canon-runtime supports Python 3.11 through 3.14. The base distribution
includes DuckDB persistence and depends on the canonical ingest, index, reason,
and agent packages so runtime contracts can bind their artifacts.
flowchart LR
P[Install canonical Runtime] --> I[Initialize workspace]
I --> C[Check operation and profile]
C --> R[Submit and resolve v2 job]
R --> V[Inspect, replay, and retain evidence]
Install¶
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install bijux-canon-runtime
The base installation fulfills offline-lexical. Choose extras by the public
operation profile rather than installing the development environment:
| Product profile | Installation | Installed capability |
|---|---|---|
| offline lexical | bijux-canon-runtime |
SQLite FTS5 ingest, index, retrieval, answer, and research without a model |
| local exact, ANN, or hybrid | bijux-canon-runtime[local-cpu] |
NumPy, CPU FAISS, sentence-transformers, and PyTorch |
| HTTP | bijux-canon-runtime[api] |
FastAPI, Starlette, and Uvicorn |
On Linux CPU hosts, install PyTorch from its CPU wheel index before resolving
local-cpu. This is required because the default Linux PyTorch wheel channel
may include CUDA runtime distributions even when Runtime selects device=cpu:
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install 'bijux-canon-runtime[local-cpu]'
On macOS, the native local-cpu profile is supported on Python 3.11. FAISS
1.7.4 is constrained with NumPy 1.26 because that combination can share a
process with PyTorch safely; newer FAISS macOS wheels abort after duplicate
OpenMP initialization, and FAISS 1.7.4 has no Python 3.12+ wheel. The base
lexical and api installations continue to support Python 3.11 through 3.14.
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 Runtime so pip can build that
dependency from its source distribution. For example, Debian and Ubuntu hosts
can use sudo apt-get install build-essential.
Verify the stable package root and CLI:
python -c "from bijux_canon_runtime import FlowManifest, RunMode, execute_flow; print(RunMode.PLAN)"
bijux-canon-runtime --help
Initialize a local workspace¶
An offline lexical workspace does not need an embedding model:
WORKSPACE=/srv/bijux-canon/research
bijux-canon-runtime init --workspace "$WORKSPACE" --json
bijux-canon-runtime v2 ready \
--operation index \
--profile offline-lexical
Omitting --model records that the model capability is not configured; it does
not access a model cache or network. Lexical ingest, index, retrieval, answer,
and research requests remain usable in that workspace.
For a local dense or hybrid profile, materialize a supported embedding model
into a durable local cache first. The model directory passed to Runtime is the
revision directory containing the canonical model.lock.json and all artifacts
named by that lock. Workspace initialization is offline and verifies every
locked artifact.
WORKSPACE=/srv/bijux-canon/research
MODEL=/srv/bijux-models/local-minilm-384/<locked-revision>
bijux-canon-runtime init \
--workspace "$WORKSPACE" \
--model "$MODEL" \
--json
The first call atomically activates a complete workspace. Repeating the same
command returns unchanged and leaves all state bytes untouched. Do not
pre-create the workspace directory: an existing directory without the
canonical manifest is treated as partial state and refused rather than filled
in. Preserve the whole workspace for restart, inspection, replay, and backup;
the DuckDB file alone is not the complete authority.
Workspace migration and rollback¶
Stop Runtime workers before running init against an older workspace. The
current Runtime recognizes exact version-1 through version-4 layouts, validates the
manifest, model, DuckDB migrations, durable-job schema, CAS, and index structure
before changing anything, and creates content-bound rollback generations below
backups/workspace-migrations/generations/. The ordered migrations culminate
in workspace format 5, which separates logical path-role identity from resolved
machine-local locations. Runtime writes the updated migration ledger before
activating the new workspace.json. A successful upgrade reports migrated,
the applied migration identities, and the exact rollback backup path. Repeating
init does not append or reapply a migration.
If the process stops after ledger publication but before manifest activation,
repeat the same init command. Runtime verifies the source manifest and
rollback backup identities and resumes the same migration. Do not delete the
ledger or edit either checksum. A newer workspace or a layout older than the
supported migration floor is refused before a backup or state mutation.
For an immediate rollback before admitting new work, stop Runtime, preserve the failed or upgraded workspace, verify the reported rollback generation, and restore the exact manifest and ledger expected by the prior Runtime release. If any work was admitted after migration, restore a complete pre-upgrade workspace backup instead; migration rollback generations cover workspace authority, not later application writes.
Verify the exact operation boundary before submitting work:
BIJUX_CANON_RUNTIME_WORKING_ROOT="$WORKSPACE" \
BIJUX_CANON_RUNTIME_EMBEDDING_MODEL_PATH="$MODEL" \
bijux-canon-runtime v2 ready \
--operation retrieve \
--profile local-hybrid-ann
A new workspace is ready for ingest before it has an index. Profile-specific
readiness reports only shared workspace dependencies for offline-lexical;
the supplied lexical artifact is validated immediately before submission.
Hybrid readiness additionally requires a verified dense generation and model.
Install bijux-canon or agentic-flows only when an application still needs a
compatibility import or command. New code should install the canonical runtime.
Start with the checked-in product workflow¶
The ancient-DNA example exercises the base installed wheel without a model, provider credential, optional extra, or source-tree import:
python examples/ancient-dna-research/offline_lexical_workflow.py \
--runtime-command .venv/bin/bijux-canon-runtime \
--workspace artifacts/ancient-dna-offline/runtime-workspace \
--evidence-directory artifacts/ancient-dna-offline/evidence
The real CPU workflow uses the public pinned-model lifecycle and the same installed Runtime service. Acquire once while online; every later validation, index, exact/ANN query, restart, and development evaluation can run with the network denied:
bijux-canon-index model acquire \
--profile local-minilm-384 \
--cache-root artifacts/ancient-dna-cpu/models
python examples/ancient-dna-research/cpu_hybrid_workflow.py \
--runtime-command bijux-canon-runtime \
--index-command bijux-canon-index \
--model-directory artifacts/ancient-dna-cpu/models/local-minilm-384/1110a243fdf4706b3f48f1d95db1a4f5529b4d41 \
--workspace artifacts/ancient-dna-cpu/runtime-workspace \
--evidence-directory artifacts/ancient-dna-cpu/evidence
The compact result binds the model source, revision, Apache-2.0 license, artifact-set digest, dimension and lock to the persistent lexical, exact, and HNSW segments. It also records separate exact and ANN attempts under the authoritative Runtime run identity and rejects a candidate unless the installed development evaluator clears all frozen retrieval floors.
It discovers and ingests eight real JATS articles, builds a persistent SQLite
FTS5 index, retrieves evidence, answers with verified citations, reopens the
same workspace using its absolute spelling, and performs an exact replay and
comparison. Each CLI exchange and bounded artifact page is retained below the
selected evidence directory. The example's
README
documents the
network-denied installed-wheel acceptance command and the resulting identities.
The hidden manifest-oriented commands remain available only for existing
integrations. New installed-wheel workflows use v2; see the
operator workflow for result,
inspection, replay, comparison, cancellation, backup, and restore commands.
HTTP V2 Service¶
The API extra installs the supported v2 server command:
python -m pip install 'bijux-canon-runtime[api]'
bijux-canon-runtime init --workspace ./canon-workspace --json
bijux-canon-runtime-server --workspace ./canon-workspace
curl --fail-with-body -H 'Bijux-API-Version: v2' \
http://127.0.0.1:8000/api/v2/live
curl --fail-with-body -H 'Bijux-API-Version: v2' \
'http://127.0.0.1:8000/api/v2/ready?operation=initialized'
Readiness is operation- and profile-specific. The v2 server exposes the same durable ingest, index, retrieval, answer, research, linked-run, inspection, replay, comparison, job and evaluation application service as the v2 CLI.
Repository Checkout¶
make install
make -f "$PWD/makes/packages/bijux-canon-runtime.mk" \
-C packages/bijux-canon-runtime help
make test PACKAGE=bijux-canon-runtime
make docs-check
Package Makefiles are repository profiles under makes/packages/; the package
directory does not contain a standalone Makefile. Use the root dispatcher for
normal checks and the explicit profile form when inspecting package targets.
The absolute profile path remains valid after Make applies -C.
Use package and documentation checks for the first feedback loop. Broader repository lanes are appropriate only when a change crosses shared contracts.
Setup Checklist¶
- The stable root imports and CLI resolve from the expected environment.
- Planning succeeds before any live authority is granted.
- Manifest, dataset, policy, and tenant identities are application-owned and explicit.
- The DuckDB directory has durable storage and one-writer coordination.
- A completed run can be inspected and the database passes schema validation.
- HTTP clients are not routed to the unimplemented run or replay endpoints.
Continue with state and persistence and entrypoint examples.