Metadata-Version: 2.2
Name: hical
Version: 0.3.0
Summary: Python-first active learning engine backed by libhicalengine
Keywords: active-learning,continuous-active-learning,information-retrieval,ranking,legal-tech
Author: Mustafa Abualsaud
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Project-URL: Homepage, https://github.com/ammsa/hical
Project-URL: Documentation, https://github.com/ammsa/hical/blob/main/docs/README.md
Project-URL: Repository, https://github.com/ammsa/hical
Project-URL: Issues, https://github.com/ammsa/hical/issues
Project-URL: Changelog, https://github.com/ammsa/hical/blob/main/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/hical/
Requires-Python: >=3.10
Requires-Dist: PyYAML>=6.0
Requires-Dist: snowballstemmer>=2.0
Requires-Dist: tqdm>=4.60
Provides-Extra: datasets
Requires-Dist: ir_datasets>=0.5.11; extra == "datasets"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: scikit-build-core>=0.12; extra == "dev"
Description-Content-Type: text/markdown

# hical

[![PyPI](https://img.shields.io/pypi/v/hical.svg)](https://pypi.org/project/hical/)
[![CI](https://github.com/ammsa/hical/actions/workflows/ci.yml/badge.svg)](https://github.com/ammsa/hical/actions/workflows/ci.yml)

`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`](https://pypi.org/project/hical/). Pushing a `v*` tag runs
[Package](.github/workflows/package.yml) and publishes wheels automatically
(see [docs/developer/releasing.md](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](docs/first-5-minutes.md) — walkthrough from checkout to one judgment
- [docs/overview.md](docs/overview.md) — what hical is for
- [docs/build-your-own-corpus.md](docs/build-your-own-corpus.md) — JSONL / CSV / TSV / archive / `ir_datasets`
- [docs/python-api.md](docs/python-api.md) — sessions, judgments, seeds, constraints
- [examples/](examples/) — configs, sample data, quickstart + CLI demos
- [python/hical/README.md](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 CLIs
- `packages/hical-benchmark` — optional timing harness
- `examples/` — demos, sample corpora, YAML configs
- `docs/` — 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/monorepo.md),
[docs/developer/development.md](docs/developer/development.md), and
[docs/developer/releasing.md](docs/developer/releasing.md).
