hical
hical helps you review large document collections more efficiently. You seed a
few relevant examples, judge suggested documents, and it keeps reranking the
rest of the corpus.
This GitHub repo is the source of truth for the PyPI project
hical. Pushing a v* tag runs
Package and publishes wheels automatically
(see docs/developer/releasing.md).
Usage
Needs Python 3.10+. For a published wheel you also need a matching platform binary; building from this repo needs CMake 3.24+, a C++20 compiler, and ICU.
Install from PyPI
"""bash pip install hical
or, for ir_datasets corpus builds:
pip install "hical[datasets]" """
Latest intended release from this tree: 0.3.0 (tag v0.3.0).
Install (from this repo)
"""bash cd ~/repos/hical make build python -m pip install -e ".[dev]" """
Day-to-day without installing: PYTHONPATH=python after make build.
Build a tiny corpus and run a session
"""bash hical-build-corpus --config examples/config/jsonl_minimal.yaml """
"""python import hical
dataset = hical.open_dataset("data/examples/jsonl_demo.bin") session = dataset.start_session( relevant_seeds="florida oranges", review_batch_size=5, config=hical.SessionConfig(num_threads=1), ) batch = session.next_batch() session.judge_relevant(batch[0]) print([item.doc_id for item in batch]) """
Or run the checked-in demo:
"""bash make build PYTHONPATH=python python examples/python_quickstart.py """
Where to go next
- docs/first-5-minutes.md — walkthrough from checkout to one judgment
- docs/overview.md — what hical is for
- docs/build-your-own-corpus.md — JSONL / CSV / TSV / archive /
ir_datasets - docs/python-api.md — sessions, judgments, seeds, constraints
- examples/ — configs, sample data, quickstart + CLI demos
- python/hical/README.md — package-local pointer to the same docs
This repository
Monorepo layout:
libs/termflow— English text analysis (tokenizer / term pipeline)native/—libhicalengine(feature build, mmap storage, BMI sessions)python/hical— public Python package and CLIspackages/hical-benchmark— optional timing harnessexamples/— demos, sample corpora, YAML configsdocs/— user + developer docs
Starter corpus configs: examples/config/.
Build and checks
CMake is the only compiler driver. make build wraps it and copies
_hical_native into python/hical/.
"""bash make build make test-python make test-packaging make test-corpus-smoke make test-benchmark-smoke make test-native # needs GoogleTest make python-wheel """
CI: .github/workflows/ci.yml (every push/PR).
Release / PyPI: .github/workflows/package.yml (tag vX.Y.Z → wheels + PyPI).
Developer detail: docs/developer/monorepo.md, docs/developer/development.md, and docs/developer/releasing.md.
1 maintainer
Metadata
1 maintainer
Release files for hical 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 173.4 MB
Release files / hical-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | hical-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
8cec8869a7c8ed3d6a36a94d9dde298514838d69b4045fac1fc507c4c4204672
|
|
BLAKE2b-256 checksum How to use checksums |
c1ee775f9cd3a2fe49c9d9cb2cb53086799952f25b5a5d55a4d21b6c87930c9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp313-cp313-macosx_14_0_x86_64.whl
| Download URL | hical-0.3.0-cp313-cp313-macosx_14_0_x86_64.whl |
|---|---|
| Size | 15.2 MB |
| Tags | CPython 3.13 macOS 14.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
ee35503636bb41a66c63631fa82a0c4963a2525e84efc814675ac3454ba49db0
|
|
BLAKE2b-256 checksum How to use checksums |
810312689610999918ad2d2536452034894c5df982c937b627b35490bfec4f73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp313-cp313-macosx_14_0_arm64.whl
| Download URL | hical-0.3.0-cp313-cp313-macosx_14_0_arm64.whl |
|---|---|
| Size | 15.1 MB |
| Tags | CPython 3.13 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
30800c058c11de4c2c7f9cdaeeb95e07652bfdc6ac9b1b70174588e3ab3ac855
|
|
BLAKE2b-256 checksum How to use checksums |
34b204c4e1eef64eb40a87536e7c580567b247bcc88dd70138e9dba59a6649ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | hical-0.3.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
3d0455baa8ad407cbfe9b4870ea0f8d1955b615fba56f542bccf8dc7d4554a40
|
|
BLAKE2b-256 checksum How to use checksums |
d5b125628892f0d5c44af4da8fa927592ede873fc9de5a0198ae576825698a47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp312-cp312-macosx_14_0_x86_64.whl
| Download URL | hical-0.3.0-cp312-cp312-macosx_14_0_x86_64.whl |
|---|---|
| Size | 15.2 MB |
| Tags | CPython 3.12 macOS 14.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
1cecbdcfe6002ff6a52ae14fcc878183b1e425020fa56fa49f813ede514daef3
|
|
BLAKE2b-256 checksum How to use checksums |
012cd5c98b4a90c3b79365868bc216cb9274c6f16f8e19fba951a99c1f645bf6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | hical-0.3.0-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 15.1 MB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
786b09bff65e1d55dfc10c3db4cfbc44ae2431ea37e9b03222dc1a5b12667f2d
|
|
BLAKE2b-256 checksum How to use checksums |
7a38de026e08d3d600711f84aa04fca42bab2da340323810af644e84c3912ae0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | hical-0.3.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
b083ba4814c080562807a2c6c02763257490178ac68ce6562a5a1fed073bb554
|
|
BLAKE2b-256 checksum How to use checksums |
395626d95f2b090c8124ba26af4da0b06801d1902da0a655d1999cff85c1220c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp311-cp311-macosx_14_0_x86_64.whl
| Download URL | hical-0.3.0-cp311-cp311-macosx_14_0_x86_64.whl |
|---|---|
| Size | 15.2 MB |
| Tags | CPython 3.11 macOS 14.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
24393246ffaca24aa6e35b4fede6b4e8742213fada7e18e018e391f6b29e0a2c
|
|
BLAKE2b-256 checksum How to use checksums |
ae06ac6c0b6e9bf7c9a1bc6acce576bec109a83e983eea8a0c0a274dc5e923d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | hical-0.3.0-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 15.1 MB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
ffb36fd114015c414f32a773f77fb4c67cb2bfc844e649d89d37225a985e44ff
|
|
BLAKE2b-256 checksum How to use checksums |
38b7072e2d9f3057ba9ba238fb311b5dbc7b4378294ffef5a4f72a03f2f168a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | hical-0.3.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 13.0 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
433a3ea51b0bd0eb79ab094200e4aa39000a70f372203454b3c0eb3c2ffb25b2
|
|
BLAKE2b-256 checksum How to use checksums |
e42bb140ac2db3389c56c1fa3790928efc70529a3873a860aa6ce1516b0bae96
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp310-cp310-macosx_14_0_x86_64.whl
| Download URL | hical-0.3.0-cp310-cp310-macosx_14_0_x86_64.whl |
|---|---|
| Size | 15.2 MB |
| Tags | CPython 3.10 macOS 14.0+ x86-64 |
|
SHA-256 checksum How to use checksums |
cfaa3a8810f31c0368732288d38c557f487cc992497ca1b276773072ff3853f9
|
|
BLAKE2b-256 checksum How to use checksums |
0e88834c872594cdc786629667ce883a5136c7eba8fbc7050b0c5aad205b933b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logRelease files / hical-0.3.0-cp310-cp310-macosx_14_0_arm64.whl
| Download URL | hical-0.3.0-cp310-cp310-macosx_14_0_arm64.whl |
|---|---|
| Size | 15.1 MB |
| Tags | CPython 3.10 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
26bad9970f1c98dfc23983b832330fa99de9ffdaa1d65b63bb6601fd33619ccb
|
|
BLAKE2b-256 checksum How to use checksums |
9d7f393126523361948f812f0a1ea38bb01579604d840349df9389f1f7b51975
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logSecurity for hical 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 12 files in this release have been uploaded with provenance metadata.
Attestation for hical-0.3.0-cp313-cp313-manylinux_2_28_x86_64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
