Metadata-Version: 2.4
Name: bijux-canon-index
Version: 0.3.5
Summary: Deterministic vector execution, replayable ANN, and provenance-aware indexing for the bijux-canon package family from Bijux.
Project-URL: Homepage, https://bijux.io/bijux-canon/bijux-canon-index/
Project-URL: Website, https://bijux.io/
Project-URL: Repository, https://github.com/bijux/bijux-canon
Project-URL: Issues, https://github.com/bijux/bijux-canon/issues
Project-URL: Documentation, https://bijux.io/bijux-canon/bijux-canon-index/
Project-URL: Changelog, https://github.com/bijux/bijux-canon/blob/main/packages/bijux-canon-index/CHANGELOG.md
Project-URL: Security, https://github.com/bijux/bijux-canon/blob/main/SECURITY.md
Project-URL: Funding, https://github.com/sponsors/bijux
Project-URL: PackageMap, https://bijux.io/bijux-canon/01-bijux-canon/foundation/package-map/
Project-URL: CompatibilityGuide, https://bijux.io/bijux-canon/08-compat-packages/migration/migration-guidance/
Author-email: Bijan Mousavi <bijan@bijux.io>
Maintainer-email: Bijan Mousavi <bijan@bijux.io>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ann,audit,bijux,bijux-canon,bijux.io,contract-driven,determinism,execution,index,nearest-neighbor,provenance,replay,reproducibility,vector,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: <4,>=3.11
Requires-Dist: fastapi<0.137,>=0.128
Requires-Dist: pydantic<3.0,>=2.12
Requires-Dist: typer<0.25,>=0.21
Provides-Extra: api
Requires-Dist: fastapi<0.137,>=0.128; extra == 'api'
Requires-Dist: schemathesis<5.0,>=4.0; extra == 'api'
Requires-Dist: uvicorn<1.0,>=0.30.1; extra == 'api'
Provides-Extra: config
Requires-Dist: pyyaml<7.0,>=6.0; extra == 'config'
Provides-Extra: dev
Requires-Dist: anyio<5.0,>=4.4.0; extra == 'dev'
Requires-Dist: bandit<2.0,>=1.7.10; extra == 'dev'
Requires-Dist: build<2.0,>=1.0.3; extra == 'dev'
Requires-Dist: codespell<3.0,>=2.3.0; extra == 'dev'
Requires-Dist: commitizen<5.0,>=4.0.0; extra == 'dev'
Requires-Dist: cyclonedx-bom>=4.6.0; extra == 'dev'
Requires-Dist: deptry<1.0,>=0.10.0; extra == 'dev'
Requires-Dist: hypothesis-jsonschema<1.0,>=0.23.0; extra == 'dev'
Requires-Dist: hypothesis<7.0,>=6.103.0; extra == 'dev'
Requires-Dist: interrogate<2.0,>=1.7.0; extra == 'dev'
Requires-Dist: mypy<2.0,>=1.11.2; extra == 'dev'
Requires-Dist: openapi-spec-validator<1.0,>=0.7.1; extra == 'dev'
Requires-Dist: pexpect<5.0,>=4.8.0; extra == 'dev'
Requires-Dist: pip-audit<3.0,>=2.7.3; extra == 'dev'
Requires-Dist: prance>=25.4.0.0; extra == 'dev'
Requires-Dist: pydocstyle<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-benchmark<6.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov<8.0,>=6.2.1; extra == 'dev'
Requires-Dist: pytest-rerunfailures<17.0,>=13.0; extra == 'dev'
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'dev'
Requires-Dist: pytest<10.0,>=9.0.3; extra == 'dev'
Requires-Dist: radon>=6.0.0; extra == 'dev'
Requires-Dist: ruff<1.0,>=0.6.8; extra == 'dev'
Requires-Dist: schemathesis<5.0,>=4.0; extra == 'dev'
Requires-Dist: twine<7.0,>=6.1.0; extra == 'dev'
Requires-Dist: types-colorama<1.0,>=0.0.14; extra == 'dev'
Requires-Dist: types-orjson<4.0,>=3.6.0; extra == 'dev'
Requires-Dist: types-pexpect<5.0,>=4.9.0; extra == 'dev'
Requires-Dist: types-psutil<8.0,>=6.0.0; extra == 'dev'
Requires-Dist: types-pyyaml<7.0,>=6.0.12; extra == 'dev'
Requires-Dist: typing-extensions<5.0,>=4.5.0; extra == 'dev'
Requires-Dist: uvicorn<1.0,>=0.30.1; extra == 'dev'
Requires-Dist: vulture<3.0,>=2.7; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-gen-files; extra == 'docs'
Requires-Dist: mkdocs-git-revision-date-localized-plugin<2.0,>=1.2.0; extra == 'docs'
Requires-Dist: mkdocs-glightbox<1.0,>=0.3; extra == 'docs'
Requires-Dist: mkdocs-include-markdown-plugin; extra == 'docs'
Requires-Dist: mkdocs-literate-nav; extra == 'docs'
Requires-Dist: mkdocs-material<10.0,>=9.5.39; extra == 'docs'
Requires-Dist: mkdocs-material[imaging]<10.0,>=9.5.39; extra == 'docs'
Requires-Dist: mkdocs-minify-plugin<1.0,>=0.7; extra == 'docs'
Requires-Dist: mkdocs-redirects<2.0,>=1.2; extra == 'docs'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]<2.0,>=0.26.1; extra == 'docs'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers<6.0,>=2.7.0; extra == 'embeddings'
Provides-Extra: nd
Requires-Dist: hnswlib<1.0,>=0.8.0; extra == 'nd'
Provides-Extra: vdb
Requires-Dist: faiss-cpu<2.0,>=1.7.4; extra == 'vdb'
Requires-Dist: numpy<3.0,>=1.26; extra == 'vdb'
Requires-Dist: qdrant-client<2.0,>=1.9.0; extra == 'vdb'
Description-Content-Type: text/markdown

# bijux-canon-index

<!-- bijux-canon-badges:generated:start -->
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://pypi.org/project/bijux-canon-index/)
[![Typing: typed](https://img.shields.io/badge/typing-typed%20(PEP%20561)-0A7BBB)](https://pypi.org/project/bijux-canon-index/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0F766E)](https://github.com/bijux/bijux-canon/blob/main/LICENSE)
[![CI Status](https://github.com/bijux/bijux-canon/actions/workflows/verify.yml/badge.svg)](https://github.com/bijux/bijux-canon/actions/workflows/verify.yml)
[![GitHub Repository](https://img.shields.io/badge/github-bijux%2Fbijux--canon-181717?logo=github)](https://github.com/bijux/bijux-canon)

[![bijux-canon-index](https://img.shields.io/pypi/v/bijux-canon-index?label=index&logo=pypi)](https://pypi.org/project/bijux-canon-index/)
[![bijux-canon-runtime](https://img.shields.io/pypi/v/bijux-canon-runtime?label=runtime&logo=pypi)](https://pypi.org/project/bijux-canon-runtime/)
[![bijux-canon-agent](https://img.shields.io/pypi/v/bijux-canon-agent?label=agent&logo=pypi)](https://pypi.org/project/bijux-canon-agent/)
[![bijux-canon-ingest](https://img.shields.io/pypi/v/bijux-canon-ingest?label=ingest&logo=pypi)](https://pypi.org/project/bijux-canon-ingest/)
[![bijux-canon-reason](https://img.shields.io/pypi/v/bijux-canon-reason?label=reason&logo=pypi)](https://pypi.org/project/bijux-canon-reason/)
[![agentic-flows](https://img.shields.io/pypi/v/agentic-flows?label=agentic--flows&logo=pypi)](https://pypi.org/project/agentic-flows/)
[![bijux-agent](https://img.shields.io/pypi/v/bijux-agent?label=bijux--agent&logo=pypi)](https://pypi.org/project/bijux-agent/)
[![bijux-rag](https://img.shields.io/pypi/v/bijux-rag?label=bijux--rag&logo=pypi)](https://pypi.org/project/bijux-rag/)
[![bijux-rar](https://img.shields.io/pypi/v/bijux-rar?label=bijux--rar&logo=pypi)](https://pypi.org/project/bijux-rar/)
[![bijux-vex](https://img.shields.io/pypi/v/bijux-vex?label=bijux--vex&logo=pypi)](https://pypi.org/project/bijux-vex/)

[![bijux-canon-index](https://img.shields.io/badge/index-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-index)
[![bijux-canon-runtime](https://img.shields.io/badge/runtime-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-runtime)
[![bijux-canon-agent](https://img.shields.io/badge/agent-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-agent)
[![bijux-canon-ingest](https://img.shields.io/badge/ingest-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-ingest)
[![bijux-canon-reason](https://img.shields.io/badge/reason-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-canon-reason)
[![agentic-flows](https://img.shields.io/badge/agentic--flows-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fagentic-flows)
[![bijux-agent](https://img.shields.io/badge/bijux--agent-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-agent)
[![bijux-rag](https://img.shields.io/badge/bijux--rag-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-rag)
[![bijux-rar](https://img.shields.io/badge/bijux--rar-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-rar)
[![bijux-vex](https://img.shields.io/badge/bijux--vex-ghcr-181717?logo=github)](https://github.com/bijux/bijux-canon/pkgs/container/bijux-canon%2Fbijux-vex)

[![bijux-canon-index docs](https://img.shields.io/badge/docs-index-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-index/)
[![bijux-canon-runtime docs](https://img.shields.io/badge/docs-runtime-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-runtime/)
[![bijux-canon-agent docs](https://img.shields.io/badge/docs-agent-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-agent/)
[![bijux-canon-ingest docs](https://img.shields.io/badge/docs-ingest-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-ingest/)
[![bijux-canon-reason docs](https://img.shields.io/badge/docs-reason-2563EB?logo=materialformkdocs&logoColor=white)](https://bijux.io/bijux-canon/bijux-canon-reason/)
<!-- bijux-canon-badges:generated:end -->

`bijux-canon-index` is the vector execution package in `bijux-canon`. It does
more than "run a nearest-neighbor query." It executes a declared vector
operation against a concrete backend, records enough provenance to explain the
result later, and supports replay-oriented comparison when determinism matters.

If you need to understand vector-store adapters, embedding execution,
capability profiles, replay semantics, or provenance-aware result comparison,
start here. If you need document preparation, runtime governance, or repository
tooling, you are outside this package's boundary.

## Legacy continuity

- compatibility package: [`bijux-vex`](https://pypi.org/project/bijux-vex/)
- legacy import root: `bijux_vex`
- legacy command: `bijux-vex`
- canonical migration guide: <https://bijux.io/bijux-canon/08-compat-packages/migration/migration-guidance/>
- retired repository target: <https://github.com/bijux/bijux-vex>

## What this package owns

- vector execution semantics and backend orchestration
- provenance-aware result artifacts and replay-oriented comparison
- plugin-backed vector store, embedding, and runner integration
- package-local HTTP behavior and related schemas

## What this package does not own

- document ingestion and normalization
- runtime-wide authority, persistence, or replay policy
- repository maintenance automation

## Source map

- [`src/bijux_canon_index/core`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/core) for stable primitives and errors
- [`src/bijux_canon_index/domain`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/domain) for execution and provenance semantics
- [`src/bijux_canon_index/application`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/application) for package workflows
- [`src/bijux_canon_index/infra`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/infra) for backends, adapters, and plugins
- [`src/bijux_canon_index/interfaces`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/interfaces) and [`src/bijux_canon_index/api`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/src/bijux_canon_index/api) for boundaries
- [`plugins`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/plugins) for plugin development support
- [`tests`](https://github.com/bijux/bijux-canon/tree/main/packages/bijux-canon-index/tests) for conformance and replay protection

## Read this next

- [Package guide](https://bijux.io/bijux-canon/bijux-canon-index/)
- [Architecture overview](https://bijux.io/bijux-canon/bijux-canon-index/architecture/)
- [API surface](https://bijux.io/bijux-canon/bijux-canon-index/interfaces/api-surface/)
- [Execution model](https://bijux.io/bijux-canon/bijux-canon-index/architecture/execution-model/)
- [Error model](https://bijux.io/bijux-canon/bijux-canon-index/architecture/error-model/)
- [Changelog](https://github.com/bijux/bijux-canon/blob/main/packages/bijux-canon-index/CHANGELOG.md)

## Primary entrypoint

- console script: `bijux-canon-index`
# Changelog

All notable changes to `bijux-canon-index` are documented here.

Historical release entries below preserve the wording that shipped with the
tagged release, including legacy distribution naming where applicable.

## 0.3.5 - 2026-04-19

### Changed

- Package contract docs and compatibility tests now reference canonical API
  schema paths under `apis/bijux-canon-index/v1`.
- Handbook and package documentation links now resolve canonical package
  handbooks without stale numbered package slugs.

## 0.3.4 - 2026-04-11

### Fixed

- Release fallback metadata and source-checkout version fallback now align with
  the synchronized `v0.3.4` tag.
- Package README badge links now follow the shared badge catalog and point to
  the exact GHCR package pages used for published index bundles.

## 0.3.2 - 2026-04-10

### Fixed

- Release fallback metadata and source-checkout version fallback now align with
  the `v0.3.2` tag.

## 0.3.0 - 2026-04-05

### Added

- Package-local and spec documentation now explain the package mental model,
  failure semantics, vector-store profiles, and freeze criteria in clearer
  human-facing language.

### Changed

- The package was realigned under the canonical `bijux-canon-index` identity,
  including namespace, application, interface, and orchestration surfaces.
- CLI workflows were split into clearer command groups for execution, ingest,
  query, validation, maintenance, and workspace tasks.
- API routes, request schemas, and orchestration helpers were decomposed into
  narrower modules for query, mutation, read, capability, and artifact
  workflows.
- Backend and orchestration support code was separated into smaller helpers for
  embedding preparation, ingest persistence, capability reporting, execution
  tracking, non-deterministic guard state, and artifact materialization.
- PyPI metadata, search keywords, and project URLs now make the canonical
  index package easier to discover from package indexes and Bijux-owned docs.
- The package README now uses PyPI-safe badge and link targets, and it points
  legacy `bijux-vex` users to the canonical migration path and retired
  repository guidance.
- Package-local PyPI publication guidance is now checked in and shipped with
  the source distribution so index release expectations stay attached to the
  package.
- Build-time version metadata now writes to a generated module so packaging
  commands stop dirtying the tracked source tree.
- Package-local ignore rules now cover Python package metadata directories so
  unpacked release artifacts stay cleaner during local validation.
- OpenAPI freeze artifacts and release-gate expectations were refreshed to
  match the current FastAPI-generated validation schema and 422 response
  wording.

### Fixed

- CLI help and freeze-spec coverage were restored after the package
  reorganization.
- Runtime state and generated artifacts were moved under the artifacts root so
  package trees stay cleaner during checks.
- Source distributions now include the full `src/bijux_canon_index` tree
  instead of publishing only the typed marker file.
- Release artifacts now ship the repository `LICENSE` file so downstream
  consumers receive the license text with the published package.
- The checked-in YAML and JSON OpenAPI artifacts are back in sync so
  repository-level API contract checks validate the same v1 surface.
- The checked-in v1 schema now includes the current FastAPI validation error
  shape so API drift checks match the live application contract.

## 0.2.0 – 2026-02-03

### Added

- Explicit vector store adapters (memory/sqlite, FAISS, Qdrant) with capability reporting and status commands.
- Non‑Deterministic (ND) execution model with budgets, quality metrics, witness options, and provenance audit fields.
- Embedding provider interface, cache controls, and embedding provenance metadata.
- Determinism fingerprints, replay gates, and conformance tests for stability.
- Benchmarks, dataset generator, and baseline regression checks.
- Human‑first documentation, contracts, and operational guides (trust model, safety, failure modes).

### Changed

- CLI and API now require explicit vector store selection for persistence/ANN routes.
- Refusal semantics are standardized and surfaced consistently across CLI/API/provenance.
- Docs and onboarding flow rewritten for clarity, with explicit anti‑goals and guarantees.

### Fixed

- Deterministic ordering rules and replay checks hardened across backends.
- Redaction rules tightened to prevent credential leakage in logs and provenance.

## 0.1.0 – first public release

- First public, contract-complete release of bijux-vex.
- Deterministic execution with replayable artifacts and provenance.
- Non-deterministic execution via ANN with approximation reports and randomness audit.
- CLI and FastAPI v1 surfaces frozen; OpenAPI schema versioned.
- Provenance, determinism, and execution ABI enforced via conformance tests.
