Metadata-Version: 2.4
Name: bijux-vex
Version: 0.1.0
Summary: bijux-vex: contract-driven vector execution runtime with explicit determinism semantics.
Project-URL: Homepage, https://bijux.github.io/bijux-vex/
Project-URL: Repository, https://github.com/bijux/bijux-vex
Project-URL: Documentation, https://bijux.github.io/bijux-vex/
Project-URL: Issues, https://github.com/bijux/bijux-vex/issues
Author-email: Bijan Mousavi <mousavi.bijan@gmail.com>
License: MIT
License-File: LICENSE
Keywords: bijux,determinism,execution,vector,vex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
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
Requires-Python: <4,>=3.11
Requires-Dist: fastapi<0.129,>=0.128
Requires-Dist: pydantic<3.0,>=2.12
Requires-Dist: typer<0.22,>=0.21
Provides-Extra: api
Requires-Dist: fastapi<0.129,>=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: 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: mkdocs-gen-files; extra == 'dev'
Requires-Dist: mkdocs-git-revision-date-localized-plugin<2.0,>=1.2.0; extra == 'dev'
Requires-Dist: mkdocs-glightbox<1.0,>=0.3; extra == 'dev'
Requires-Dist: mkdocs-include-markdown-plugin; extra == 'dev'
Requires-Dist: mkdocs-literate-nav; extra == 'dev'
Requires-Dist: mkdocs-material<10.0,>=9.5.39; extra == 'dev'
Requires-Dist: mkdocs-material[imaging]<10.0,>=9.5.39; extra == 'dev'
Requires-Dist: mkdocs-minify-plugin<1.0,>=0.7; extra == 'dev'
Requires-Dist: mkdocs-redirects<2.0,>=1.2; extra == 'dev'
Requires-Dist: mkdocs<2.0,>=1.6.1; extra == 'dev'
Requires-Dist: mkdocstrings[python]<1.0,>=0.26.1; 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: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pydocstyle<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pyright[nodejs]<2.0,>=1.1.320; extra == 'dev'
Requires-Dist: pytest-asyncio<2.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-benchmark<5.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0,>=6.2.1; extra == 'dev'
Requires-Dist: pytest-rerunfailures<14.0,>=13.0; extra == 'dev'
Requires-Dist: pytest-timeout<3.0,>=2.4.0; extra == 'dev'
Requires-Dist: pytest<9.0,>=8.4.1; extra == 'dev'
Requires-Dist: pytype>=2024.10.11; extra == 'dev'
Requires-Dist: radon>=6.0.0; extra == 'dev'
Requires-Dist: reuse<6.0.0,>=4.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: towncrier<25.0,>=23.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<7.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: llm
Description-Content-Type: text/markdown

# bijux-vex — vector execution engine with explicit determinism

[![PyPI - Version](https://img.shields.io/pypi/v/bijux-vex.svg)](https://pypi.org/project/bijux-vex/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bijux-vex.svg)](https://pypi.org/project/bijux-vex/)
[![Typing: typed (PEP 561)](https://img.shields.io/badge/typing-typed-4F8CC9.svg)](https://peps.python.org/pep-0561/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bijux/bijux-vex/raw/main/LICENSES/MIT.txt)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-brightgreen)](https://bijux.github.io/bijux-vex/)
[![CI Status](https://github.com/bijux/bijux-vex/actions/workflows/ci.yml/badge.svg)](https://github.com/bijux/bijux-vex/actions)

bijux-vex executes vector workloads under **contracts**. Deterministic runs are replayable; non-deterministic runs are bounded, audited, and comparable.
Nothing is implicit: no silent defaults, retries, or randomness.

## What bijux-vex is
Vector execution engine with explicit determinism contracts. Deterministic paths are bit-stable and replayable; non-deterministic paths (ANN) are supported but **experimental** and always emit approximation + randomness provenance.

## What bijux-vex is not
- Not a vector DB or storage layer.
- Not an embedding or RAG framework.
- Not a serving platform with SLAs.

## Quick links
- Start here (single onboarding path): [user/start_here.md](user/start_here.md)
- Docs home: https://bijux.github.io/bijux-vex/
- Concepts: [overview/concepts.md](overview/concepts.md)
- API: [api/index.md](api/index.md) and [`api/v1/schema.yaml`](https://github.com/bijux/bijux-vex/blob/main/api/v1/schema.yaml) (canonical contract)
- Examples: [examples/overview.md](examples/overview.md)
- Changelog: [changelog.md](changelog.md)
- Not a vector DB: [user/not_a_vdb.md](user/not_a_vdb.md)

## Reading order (guaranteed)
1) Start with [user/start_here.md](user/start_here.md) for the problem, fit, and next steps.  
2) Then [overview/concepts.md](overview/concepts.md) for execution vs storage and determinism vs non-determinism.  
3) Then [spec/system_contract.md](spec/system_contract.md) and [spec/execution_contracts.md](spec/execution_contracts.md) for the normative rules.  
4) Run [examples/overview.md](examples/overview.md) for deterministic and ANN flows.  
5) Consult [api/index.md](api/index.md) and [`api/v1/schema.yaml`](https://github.com/bijux/bijux-vex/blob/main/api/v1/schema.yaml) when integrating.  
Everything else is reference or maintainer material.

## Start here
Read `docs/user/start_here.md`. It explains the problem, when to use bijux-vex, deterministic vs non-deterministic execution, and where to go next.

## Minimal example (CLI, 10 lines)
```sh
bijux vex create --name demo
bijux vex ingest --documents doc.txt --vectors [[0,1,0]]
bijux vex artifact --artifact-id exact --contract deterministic
bijux vex execute --artifact-id exact --vector [0,1,0] --top-k 1 --contract deterministic
bijux vex artifact --artifact-id ann --contract non_deterministic
bijux vex execute --artifact-id ann --vector [0,1,0] --top-k 1 --contract non_deterministic --randomness-profile seed=1
bijux vex explain --artifact-id exact --result-id <vector_id>
bijux vex compare --artifact-id exact --other-id ann
```

## Execution truth table (canonical)
| Contract | Support level | Replayable | Output stability | Provenance / audit | Notes |
| --- | --- | --- | --- | --- | --- |
| deterministic | stable | yes (bit-identical) | stable | full chain + fingerprints | frozen ABI; breaking changes require major bump |
| non_deterministic | stable_bounded | no (envelope only) | outcome-variable (bounded divergence) | approximation + randomness metadata required | experimental surface; may fail if ANN backend unavailable |

## Stability guarantees
- Supported Python: 3.11–3.13 (CI + metadata aligned).
- Package version: dynamic from git tags via hatch-vcs.
- Public API version: **v1.x** (frozen; breaking changes require major bump).
- Deterministic execution surface and ABI are frozen; breaking changes require a major bump.
- ND/ANN execution is **experimental** and may change; it can legally fail when no ANN backend is available.
- Determinism gates, ANN contracts, and provenance schema are enforced in conformance tests; regressions fail CI.
- Testing policy: tox runs multi-version tests; lint/quality/security/typing gates run only on the lowest supported Python (3.11) for cost/time efficiency.

## No synonym drift
We use one term per concept: **replayable** (deterministic, bit-identical), **audited** (non-deterministic with envelopes), **stable** (supported and frozen), **outcome-variable** (bounded divergence). Avoid “reproducible” or “supported” as stand-ins.

## Public surfaces
- **CLI (Typer)**: `create`, `ingest`, `materialize`, `execute`, `explain`, `replay`, `compare`, `list-artifacts`.
- **API (FastAPI)**: versioned under `bijux_vex.api.v1` with frozen OpenAPI (`api/v1/openapi.v1.json`), endpoints mirror CLI verbs.
- **Core types**: `ExecutionContract`, `ExecutionRequest`, `ExecutionArtifact`, `ExecutionResources`, `ApproximationReport`, `RandomnessProfile`.

## Non-goals checksum
X - Not a VDB or search service.  
X - Not an ML/embedding framework.  
X - Not a serving layer with SLAs.  
X - Not a “best-effort” ANN wrapper—contracts must be explicit.

## Why strict
Aggressive invariants, terminal failures, and refusal to fallback exist to keep provenance honest and prevent silent divergence; permissive modes are intentionally rejected.

## Assumptions
- Trusted runtime and honest backend declaration.  
- Data is non-adversarial unless stated in tests.  
- Users read the “Start here” path before touching API/CLI.

## When contracts are violated
- Deterministic: execution refuses to run; replay fails closed.  
- Non-deterministic: fails fast if ANN unavailable or metadata missing; never silently falls back to deterministic.  
- Budget or capability breaches raise typed errors; no hidden retries or approximations.

## Contributing & release
- Keep invariants terminal; ND without metadata is forbidden.
- Run `make lint quality security test` before any PR.
- Release process: see `docs/maintainer/release_process.md`; tags drive package versions, SBOM, and wheels.
- Licensing: code under MIT; docs/config under CC0. See `docs/legal/licensing.md`.
