docs: updated docs and project dev setup

Author: SergiiShcherbak

.gitignore

@@ -7,6 +7,7 @@ env
 venv
 .venv
 .coverage
+.cz.msg
 
 notebooks
 !dev/notebooks

.pre-commit-config.yaml

@@ -1,4 +1,11 @@
 repos:
+
+  # Commitizen hook for conventional commits
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.5.1
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]
 
   # Custom local hooks
   - repo: local

CONTRIBUTING.md

@@ -53,7 +53,11 @@ To sign the agreement:
 
 3. **Install pre-commit hooks**:
     ```bash
+    # Install pre-commit hooks
     pre-commit install
+
+    # Install commit-msg hooks (for commitizen)
+    pre-commit install --hook-type commit-msg
     ```
 
 
@@ -102,12 +106,23 @@ To sign the agreement:
 
    Please note that we use pytest-vcr to record and replay LLM API interactions. Your changes may require re-recording VCR cassettes for the tests. See [VCR Cassette Management](#vcr-cassette-management) section below for details.
 
-4. **Commit your changes** with a descriptive commit message:
+4. **Commit your changes** using Conventional Commits format:
 
-   For example:
+   We use [Conventional Commits](https://www.conventionalcommits.org/) format for our commit messages, which enables automatic changelog generation and semantic versioning. Instead of using regular git commit, please use commitizen:
 
    ```bash
-   git commit -m "Add feature: description of your changes"
+   poetry run cz commit
+   ```
+
+   This will guide you through an interactive prompt to create a properly formatted commit message with:
+   - Type of change (feat, fix, docs, style, refactor, etc.)
+   - Optional scope (e.g., api, cli, docs)
+   - Short description
+   - Optional longer description and breaking change notes
+
+   Example of resulting commit message:
+   ```
+   docs(readme): update installation instructions
    ```
 
 

NOTICE

@@ -35,6 +35,7 @@ Core Dependencies:
 
 Development Dependencies:
 - black: Code formatting
+- commitizen: Conventional commit tool and release management
 - coverage: Test coverage measurement
 - isort: Sorting imports
 - nbformat: Notebook format utilities

contextgem/__init__.py

@@ -20,7 +20,7 @@
 ContextGem - Easier and faster way to build LLM extraction workflows through powerful abstractions
 """
 
-__version__ = "0.1.1"
+__version__ = "0.1.1.post1"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (

dev/requirements/requirements.dev.txt

@@ -1,12 +1,13 @@
 accessible-pygments==0.0.5 ; python_version >= "3.10" and python_version < "3.14"
 adapters==1.1.0 ; python_version >= "3.10" and python_version < "3.14"
 aiohappyeyeballs==2.6.1 ; python_version >= "3.10" and python_version < "3.14"
-aiohttp==3.11.14 ; python_version >= "3.10" and python_version < "3.14"
+aiohttp==3.11.16 ; python_version >= "3.10" and python_version < "3.14"
 aiolimiter==1.2.1 ; python_version >= "3.10" and python_version < "3.14"
 aiosignal==1.3.2 ; python_version >= "3.10" and python_version < "3.14"
 alabaster==0.7.16 ; python_version >= "3.10" and python_version < "3.14"
 annotated-types==0.7.0 ; python_version >= "3.10" and python_version < "3.14"
 anyio==4.9.0 ; python_version >= "3.10" and python_version < "3.14"
+argcomplete==3.5.3 ; python_version >= "3.10" and python_version < "3.14"
 async-timeout==5.0.1 ; python_version == "3.10"
 attrs==25.3.0 ; python_version >= "3.10" and python_version < "3.14"
 babel==2.17.0 ; python_version >= "3.10" and python_version < "3.14"
@@ -18,23 +19,23 @@ certifi==2025.1.31 ; python_version >= "3.10" and python_version < "3.14"
 cfgv==3.4.0 ; python_version >= "3.10" and python_version < "3.14"
 charset-normalizer==3.4.1 ; python_version >= "3.10" and python_version < "3.14"
 click==8.1.8 ; python_version >= "3.10" and python_version < "3.14"
-colorama==0.4.6 ; python_version >= "3.10" and python_version < "3.14" and (platform_system == "Windows" or sys_platform == "win32" or os_name == "nt")
-coloredlogs==15.0.1 ; python_version >= "3.10" and python_version < "3.14"
-coverage==7.7.1 ; python_version >= "3.10" and python_version < "3.14"
+colorama==0.4.6 ; python_version >= "3.10" and python_version < "3.14"
+commitizen==4.5.1 ; python_version >= "3.10" and python_version < "3.14"
+coverage==7.8.0 ; python_version >= "3.10" and python_version < "3.14"
+decli==0.6.2 ; python_version >= "3.10" and python_version < "3.14"
 distlib==0.3.9 ; python_version >= "3.10" and python_version < "3.14"
 distro==1.9.0 ; python_version >= "3.10" and python_version < "3.14"
 docopt==0.6.2 ; python_version >= "3.10" and python_version < "3.14"
 docutils==0.21.2 ; python_version >= "3.10" and python_version < "3.14"
 exceptiongroup==1.2.2 ; python_version == "3.10"
+fastjsonschema==2.21.1 ; python_version >= "3.10" and python_version < "3.14"
 filelock==3.18.0 ; python_version >= "3.10" and python_version < "3.14"
-flatbuffers==25.2.10 ; python_version >= "3.10" and python_version < "3.14"
 frozenlist==1.5.0 ; python_version >= "3.10" and python_version < "3.14"
-fsspec==2025.3.1 ; python_version >= "3.10" and python_version < "3.14"
+fsspec==2025.3.2 ; python_version >= "3.10" and python_version < "3.14"
 h11==0.14.0 ; python_version >= "3.10" and python_version < "3.14"
 httpcore==1.0.7 ; python_version >= "3.10" and python_version < "3.14"
 httpx==0.28.1 ; python_version >= "3.10" and python_version < "3.14"
-huggingface-hub==0.29.3 ; python_version >= "3.10" and python_version < "3.14"
-humanfriendly==10.0 ; python_version >= "3.10" and python_version < "3.14"
+huggingface-hub==0.30.2 ; python_version >= "3.10" and python_version < "3.14"
 identify==2.6.9 ; python_version >= "3.10" and python_version < "3.14"
 idna==3.10 ; python_version >= "3.10" and python_version < "3.14"
 imagesize==1.4.1 ; python_version >= "3.10" and python_version < "3.14"
@@ -46,13 +47,15 @@ jiter==0.9.0 ; python_version >= "3.10" and python_version < "3.14"
 joblib==1.4.2 ; python_version >= "3.10" and python_version < "3.14"
 jsonschema-specifications==2024.10.1 ; python_version >= "3.10" and python_version < "3.14"
 jsonschema==4.23.0 ; python_version >= "3.10" and python_version < "3.14"
-litellm==1.65.0 ; python_version >= "3.10" and python_version < "3.14"
+jupyter-core==5.7.2 ; python_version >= "3.10" and python_version < "3.14"
+litellm==1.65.5 ; python_version >= "3.10" and python_version < "3.14"
 loguru==0.7.3 ; python_version >= "3.10" and python_version < "3.14"
 markupsafe==3.0.2 ; python_version >= "3.10" and python_version < "3.14"
 mosestokenizer==1.2.1 ; python_version >= "3.10" and python_version < "3.14"
 mpmath==1.3.0 ; python_version >= "3.10" and python_version < "3.14"
-multidict==6.2.0 ; python_version >= "3.10" and python_version < "3.14"
+multidict==6.4.2 ; python_version >= "3.10" and python_version < "3.14"
 mypy-extensions==1.0.0 ; python_version >= "3.10" and python_version < "3.14"
+nbformat==5.10.4 ; python_version >= "3.10" and python_version < "3.14"
 networkx==3.4.2 ; python_version >= "3.10" and python_version < "3.14"
 nodeenv==1.9.1 ; python_version >= "3.10" and python_version < "3.14"
 numpy==2.2.4 ; python_version >= "3.10" and python_version < "3.14"
@@ -69,8 +72,7 @@ nvidia-cusparselt-cu12==0.6.2 ; python_version >= "3.10" and python_version < "3
 nvidia-nccl-cu12==2.21.5 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
 nvidia-nvjitlink-cu12==12.4.127 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
 nvidia-nvtx-cu12==12.4.127 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
-onnxruntime==1.21.0 ; python_version >= "3.10" and python_version < "3.14"
-openai==1.69.0 ; python_version >= "3.10" and python_version < "3.14"
+openai==1.72.0 ; python_version >= "3.10" and python_version < "3.14"
 openfile==0.0.7 ; python_version >= "3.10" and python_version < "3.14"
 packaging==24.2 ; python_version >= "3.10" and python_version < "3.14"
 pandas==2.2.3 ; python_version >= "3.10" and python_version < "3.14"
@@ -80,22 +82,23 @@ pip==25.0.1 ; python_version >= "3.10" and python_version < "3.14"
 platformdirs==4.3.7 ; python_version >= "3.10" and python_version < "3.14"
 pluggy==1.5.0 ; python_version >= "3.10" and python_version < "3.14"
 pre-commit==4.2.0 ; python_version >= "3.10" and python_version < "3.14"
+prompt-toolkit==3.0.50 ; python_version >= "3.10" and python_version < "3.14"
 propcache==0.3.1 ; python_version >= "3.10" and python_version < "3.14"
-protobuf==6.30.2 ; python_version >= "3.10" and python_version < "3.14"
-pydantic-core==2.33.0 ; python_version >= "3.10" and python_version < "3.14"
-pydantic==2.11.1 ; python_version >= "3.10" and python_version < "3.14"
+pydantic-core==2.33.1 ; python_version >= "3.10" and python_version < "3.14"
+pydantic==2.11.3 ; python_version >= "3.10" and python_version < "3.14"
 pydata-sphinx-theme==0.15.4 ; python_version >= "3.10" and python_version < "3.14"
 pygments==2.19.1 ; python_version >= "3.10" and python_version < "3.14"
 pyproject-hooks==1.2.0 ; python_version >= "3.10" and python_version < "3.14"
-pyreadline3==3.5.4 ; python_version >= "3.10" and python_version < "3.14" and sys_platform == "win32"
-pytest-cov==6.0.0 ; python_version >= "3.10" and python_version < "3.14"
+pytest-cov==6.1.1 ; python_version >= "3.10" and python_version < "3.14"
 pytest-vcr @ git+https://github.com/shcherbak-ai/pytest-vcr.git@3152193fed5592a288e718fe7edf6aff0edb0069 ; python_version >= "3.10" and python_version < "3.14"
 pytest==8.3.5 ; python_version >= "3.10" and python_version < "3.14"
 python-dateutil==2.9.0.post0 ; python_version >= "3.10" and python_version < "3.14"
 python-dotenv==1.1.0 ; python_version >= "3.10" and python_version < "3.14"
 python-ulid==3.0.0 ; python_version >= "3.10" and python_version < "3.14"
 pytz==2025.2 ; python_version >= "3.10" and python_version < "3.14"
+pywin32==310 ; python_version >= "3.10" and python_version < "3.14" and sys_platform == "win32" and platform_python_implementation != "PyPy"
 pyyaml==6.0.2 ; python_version >= "3.10" and python_version < "3.14"
+questionary==2.1.0 ; python_version >= "3.10" and python_version < "3.14"
 referencing==0.36.2 ; python_version >= "3.10" and python_version < "3.14"
 regex==2024.11.6 ; python_version >= "3.10" and python_version < "3.14"
 requests==2.32.3 ; python_version >= "3.10" and python_version < "3.14"
@@ -120,27 +123,32 @@ sphinxcontrib-htmlhelp==2.1.0 ; python_version >= "3.10" and python_version < "3
 sphinxcontrib-jsmath==1.0.1 ; python_version >= "3.10" and python_version < "3.14"
 sphinxcontrib-qthelp==2.0.0 ; python_version >= "3.10" and python_version < "3.14"
 sphinxcontrib-serializinghtml==2.0.0 ; python_version >= "3.10" and python_version < "3.14"
+sphinxext-opengraph==0.9.1 ; python_version >= "3.10" and python_version < "3.14"
 sympy==1.13.1 ; python_version >= "3.10" and python_version < "3.14"
 tabulate==0.9.0 ; python_version >= "3.10" and python_version < "3.14"
+termcolor==2.5.0 ; python_version >= "3.10" and python_version < "3.14"
 threadpoolctl==3.6.0 ; python_version >= "3.10" and python_version < "3.14"
 tiktoken==0.9.0 ; python_version >= "3.10" and python_version < "3.14"
 tokenizers==0.21.1 ; python_version >= "3.10" and python_version < "3.14"
 tomli==2.2.1 ; python_version == "3.10"
+tomlkit==0.13.2 ; python_version >= "3.10" and python_version < "3.14"
 toolwrapper==2.1.0 ; python_version >= "3.10" and python_version < "3.14"
 torch==2.6.0 ; python_version >= "3.10" and python_version < "3.14"
 tqdm==4.67.1 ; python_version >= "3.10" and python_version < "3.14"
+traitlets==5.14.3 ; python_version >= "3.10" and python_version < "3.14"
 transformers==4.47.1 ; python_version >= "3.10" and python_version < "3.14"
 triton==3.2.0 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
-typing-extensions==4.13.0 ; python_version >= "3.10" and python_version < "3.14"
+typing-extensions==4.13.2 ; python_version >= "3.10" and python_version < "3.14"
 typing-inspection==0.4.0 ; python_version >= "3.10" and python_version < "3.14"
 tzdata==2025.2 ; python_version >= "3.10" and python_version < "3.14"
 uctools==1.3.0 ; python_version >= "3.10" and python_version < "3.14"
-urllib3==2.3.0 ; python_version >= "3.10" and python_version < "3.14"
+urllib3==2.4.0 ; python_version >= "3.10" and python_version < "3.14"
 vcrpy @ git+https://github.com/shcherbak-ai/vcrpy.git@cda84a815570a3a7bdf93c413901d61230581831 ; python_version >= "3.10" and python_version < "3.14"
-virtualenv==20.29.3 ; python_version >= "3.10" and python_version < "3.14"
+virtualenv==20.30.0 ; python_version >= "3.10" and python_version < "3.14"
+wcwidth==0.2.13 ; python_version >= "3.10" and python_version < "3.14"
 wheel==0.45.1 ; python_version >= "3.10" and python_version < "3.14"
 win32-setctime==1.2.0 ; python_version >= "3.10" and python_version < "3.14" and sys_platform == "win32"
 wrapt==1.17.2 ; python_version >= "3.10" and python_version < "3.14"
-wtpsplit==2.1.4 ; python_version >= "3.10" and python_version < "3.14"
-yarl==1.18.3 ; python_version >= "3.10" and python_version < "3.14"
+wtpsplit==2.1.5 ; python_version >= "3.10" and python_version < "3.14"
+yarl==1.19.0 ; python_version >= "3.10" and python_version < "3.14"
 zipp==3.21.0 ; python_version >= "3.10" and python_version < "3.14"

dev/requirements/requirements.main.txt

@@ -1,6 +1,6 @@
 adapters==1.1.0 ; python_version >= "3.10" and python_version < "3.14"
 aiohappyeyeballs==2.6.1 ; python_version >= "3.10" and python_version < "3.14"
-aiohttp==3.11.14 ; python_version >= "3.10" and python_version < "3.14"
+aiohttp==3.11.16 ; python_version >= "3.10" and python_version < "3.14"
 aiolimiter==1.2.1 ; python_version >= "3.10" and python_version < "3.14"
 aiosignal==1.3.2 ; python_version >= "3.10" and python_version < "3.14"
 annotated-types==0.7.0 ; python_version >= "3.10" and python_version < "3.14"
@@ -12,32 +12,29 @@ certifi==2025.1.31 ; python_version >= "3.10" and python_version < "3.14"
 charset-normalizer==3.4.1 ; python_version >= "3.10" and python_version < "3.14"
 click==8.1.8 ; python_version >= "3.10" and python_version < "3.14"
 colorama==0.4.6 ; python_version >= "3.10" and python_version < "3.14" and (platform_system == "Windows" or sys_platform == "win32")
-coloredlogs==15.0.1 ; python_version >= "3.10" and python_version < "3.14"
 distro==1.9.0 ; python_version >= "3.10" and python_version < "3.14"
 docopt==0.6.2 ; python_version >= "3.10" and python_version < "3.14"
 exceptiongroup==1.2.2 ; python_version == "3.10"
 filelock==3.18.0 ; python_version >= "3.10" and python_version < "3.14"
-flatbuffers==25.2.10 ; python_version >= "3.10" and python_version < "3.14"
 frozenlist==1.5.0 ; python_version >= "3.10" and python_version < "3.14"
-fsspec==2025.3.1 ; python_version >= "3.10" and python_version < "3.14"
+fsspec==2025.3.2 ; python_version >= "3.10" and python_version < "3.14"
 h11==0.14.0 ; python_version >= "3.10" and python_version < "3.14"
 httpcore==1.0.7 ; python_version >= "3.10" and python_version < "3.14"
 httpx==0.28.1 ; python_version >= "3.10" and python_version < "3.14"
-huggingface-hub==0.29.3 ; python_version >= "3.10" and python_version < "3.14"
-humanfriendly==10.0 ; python_version >= "3.10" and python_version < "3.14"
+huggingface-hub==0.30.2 ; python_version >= "3.10" and python_version < "3.14"
 idna==3.10 ; python_version >= "3.10" and python_version < "3.14"
 importlib-metadata==8.6.1 ; python_version >= "3.10" and python_version < "3.14"
 jinja2==3.1.6 ; python_version >= "3.10" and python_version < "3.14"
 jiter==0.9.0 ; python_version >= "3.10" and python_version < "3.14"
 joblib==1.4.2 ; python_version >= "3.10" and python_version < "3.14"
 jsonschema-specifications==2024.10.1 ; python_version >= "3.10" and python_version < "3.14"
 jsonschema==4.23.0 ; python_version >= "3.10" and python_version < "3.14"
-litellm==1.65.0 ; python_version >= "3.10" and python_version < "3.14"
+litellm==1.65.5 ; python_version >= "3.10" and python_version < "3.14"
 loguru==0.7.3 ; python_version >= "3.10" and python_version < "3.14"
 markupsafe==3.0.2 ; python_version >= "3.10" and python_version < "3.14"
 mosestokenizer==1.2.1 ; python_version >= "3.10" and python_version < "3.14"
 mpmath==1.3.0 ; python_version >= "3.10" and python_version < "3.14"
-multidict==6.2.0 ; python_version >= "3.10" and python_version < "3.14"
+multidict==6.4.2 ; python_version >= "3.10" and python_version < "3.14"
 networkx==3.4.2 ; python_version >= "3.10" and python_version < "3.14"
 numpy==2.2.4 ; python_version >= "3.10" and python_version < "3.14"
 nvidia-cublas-cu12==12.4.5.8 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
@@ -53,16 +50,13 @@ nvidia-cusparselt-cu12==0.6.2 ; python_version >= "3.10" and python_version < "3
 nvidia-nccl-cu12==2.21.5 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
 nvidia-nvjitlink-cu12==12.4.127 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
 nvidia-nvtx-cu12==12.4.127 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
-onnxruntime==1.21.0 ; python_version >= "3.10" and python_version < "3.14"
-openai==1.69.0 ; python_version >= "3.10" and python_version < "3.14"
+openai==1.72.0 ; python_version >= "3.10" and python_version < "3.14"
 openfile==0.0.7 ; python_version >= "3.10" and python_version < "3.14"
 packaging==24.2 ; python_version >= "3.10" and python_version < "3.14"
 pandas==2.2.3 ; python_version >= "3.10" and python_version < "3.14"
 propcache==0.3.1 ; python_version >= "3.10" and python_version < "3.14"
-protobuf==6.30.2 ; python_version >= "3.10" and python_version < "3.14"
-pydantic-core==2.33.0 ; python_version >= "3.10" and python_version < "3.14"
-pydantic==2.11.1 ; python_version >= "3.10" and python_version < "3.14"
-pyreadline3==3.5.4 ; python_version >= "3.10" and python_version < "3.14" and sys_platform == "win32"
+pydantic-core==2.33.1 ; python_version >= "3.10" and python_version < "3.14"
+pydantic==2.11.3 ; python_version >= "3.10" and python_version < "3.14"
 python-dateutil==2.9.0.post0 ; python_version >= "3.10" and python_version < "3.14"
 python-dotenv==1.1.0 ; python_version >= "3.10" and python_version < "3.14"
 python-ulid==3.0.0 ; python_version >= "3.10" and python_version < "3.14"
@@ -89,12 +83,12 @@ torch==2.6.0 ; python_version >= "3.10" and python_version < "3.14"
 tqdm==4.67.1 ; python_version >= "3.10" and python_version < "3.14"
 transformers==4.47.1 ; python_version >= "3.10" and python_version < "3.14"
 triton==3.2.0 ; python_version >= "3.10" and python_version < "3.14" and platform_system == "Linux" and platform_machine == "x86_64"
-typing-extensions==4.13.0 ; python_version >= "3.10" and python_version < "3.14"
+typing-extensions==4.13.2 ; python_version >= "3.10" and python_version < "3.14"
 typing-inspection==0.4.0 ; python_version >= "3.10" and python_version < "3.14"
 tzdata==2025.2 ; python_version >= "3.10" and python_version < "3.14"
 uctools==1.3.0 ; python_version >= "3.10" and python_version < "3.14"
-urllib3==2.3.0 ; python_version >= "3.10" and python_version < "3.14"
+urllib3==2.4.0 ; python_version >= "3.10" and python_version < "3.14"
 win32-setctime==1.2.0 ; python_version >= "3.10" and python_version < "3.14" and sys_platform == "win32"
-wtpsplit==2.1.4 ; python_version >= "3.10" and python_version < "3.14"
-yarl==1.18.3 ; python_version >= "3.10" and python_version < "3.14"
+wtpsplit==2.1.5 ; python_version >= "3.10" and python_version < "3.14"
+yarl==1.19.0 ; python_version >= "3.10" and python_version < "3.14"
 zipp==3.21.0 ; python_version >= "3.10" and python_version < "3.14"

docs/source/conf.py

@@ -22,7 +22,7 @@
 project = "ContextGem"
 copyright = "2025, Shcherbak AI AS"
 author = "Sergii Shcherbak"
-release = "0.1.1"
+release = "0.1.1.post1"
 
 
 # Add path to the package