Installation and Setup

bijux-canon-ingest supports Python 3.11 through 3.14. The base installation includes typed document processing, MessagePack serialization, NumPy retrieval, the CLI, and the FastAPI boundary.

flowchart LR
    P[Install package] --> I[Verify import and CLI]
    I --> S[Prepare identified source rows]
    S --> B[Build local index]
    B --> Q[Retrieve and inspect citations]
    Q --> H[Retain configuration and artifact identity]

Install the Canonical Package

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install bijux-canon-ingest

Confirm both the import and command entry point:

python -c "import bijux_canon_ingest; print(bijux_canon_ingest.__version__)"
bijux-canon-ingest --help

New applications should install the canonical distribution. Install bijux-rag only when an existing application still requires the legacy bijux_rag import or bijux-rag command.

Choose The Command Family

The executable exposes two operational paths:

Path	Shape	Use it for
configured preparation	bijux-canon-ingest <input.csv> --config <config.yml> [--out <chunks.jsonl>]	the configuration-driven source-to-chunk pipeline
retrieval utilities	bijux-canon-ingest index ..., retrieve, ask, or eval	building and querying local retrieval artifacts

The top-level help describes configured preparation. Subcommand help describes retrieval utilities. Inspect the exact path you intend to automate; options from one family are not interchangeable with the other.

Prepare a First Input

The command workflow accepts CSV documents. A minimal file has the fields needed by RawDoc:

doc_id,title,abstract,categories
policy-17,Retention policy,Keep signed run records for seven years.,governance
policy-23,Access policy,Review privileged access every quarter.,security

Save it as documents.csv, then inspect the installed command's options before choosing a pipeline configuration:

bijux-canon-ingest --help
bijux-canon-ingest index build --help

Keep local output outside the source tree:

mkdir -p artifacts/ingest
bijux-canon-ingest index build \
  --input documents.csv \
  --out artifacts/ingest/policies.index \
  --backend bm25

bijux-canon-ingest retrieve \
  --index artifacts/ingest/policies.index \
  --query "privileged access" \
  --top-k 3 \
  --out artifacts/ingest/retrieval.json

BM25 requires no model download. The numpy-cosine backend can use the deterministic hash16 embedding for local and test workflows; external model adapters may introduce their own model files, credentials, network access, and resource requirements.

Use the Library Directly

from bijux_canon_ingest import RagEnv, RawDoc, chunk_doc, clean_doc

doc = RawDoc(
    doc_id="policy-17",
    title="Retention policy",
    abstract="Keep signed run records for seven years.",
    categories="governance",
)

chunks = chunk_doc(clean_doc(doc), RagEnv(chunk_size=80, overlap=10))
print(chunks[0])

The root import is the stable home for dependency-light primitives. Import application, interface, storage, or adapter modules only when the integration needs that boundary.

Retain The Preparation Evidence

Evidence	Why it matters
original source identity and stable doc_id values	connects output to caller-owned input
resolved RagEnv or configuration file	records cleaning, chunk size, overlap, and tail behavior
index file and selected backend	identifies the retrieval representation
embedder name and model descriptor	bounds vector reproducibility
retrieval output with ranked citations	preserves the observed query result

BM25 output does not establish semantic embedding parity. A deterministic hash16 embedding establishes repeatable local behavior, not semantic quality.

Repository Checkout

For contribution work from the monorepo root:

make install
make -f "$PWD/makes/packages/bijux-canon-ingest.mk" \
  -C packages/bijux-canon-ingest help
make test PACKAGE=bijux-canon-ingest

Package Makefiles are repository profiles under makes/packages/; there is no standalone Makefile inside the package directory. Use the root dispatcher for normal checks. The explicit profile path is absolute because Make applies -C before opening -f; use this form only to inspect or invoke a package-owned target directly.

Use make docs-check for public documentation. Repository-wide make check and make test-all are broader release or integration lanes, not the default feedback loop for a package-local change.

Setup Checklist

• Python is within the supported range and the intended virtual environment is active.
• bijux_canon_ingest imports and reports a version.
• bijux-canon-ingest --help resolves from the same environment.
• Input identifiers are stable and output paths are caller-owned.
• The selected embedding backend's model and credential requirements are known.
• A saved index can be loaded and queried before it becomes a downstream dependency.

For serialization and path behavior, continue with state and persistence. For command failures and exit behavior, see failure recovery.