problm-solver 1.5.1__tar.gz

problm_solver-1.5.1/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.3
+Name: problm-solver
+Version: 1.5.1
+Summary: A python library built on top of llama.cpp which generates and performs statistical analysis on language model outputs.
+Author: Clio
+Author-email: Clio <d.k.johnson@lancaster.ac.uk>
+Requires-Dist: fsspec
+Requires-Dist: huggingface-hub
+Requires-Dist: llama-cpp-python
+Requires-Dist: numpy
+Requires-Dist: pandas>=3.0.3
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: poethepoet
+Requires-Python: >=3.13, <4.0
+Project-URL: homepage, https://github.com/muse-writes/probLM-solver
+Project-URL: source, https://github.com/muse-writes/probLM-solver
+Project-URL: changelog, https://github.com/muse-writes/probLM-solver/blob/main/CHANGELOG.md
+Project-URL: releasenotes, https://github.com/muse-writes/probLM-solver/releases
+Project-URL: documentation, https://muse-writes.github.io/probLM-solver
+Project-URL: issues, https://github.com/muse-writes/probLM-solver/issues
+Description-Content-Type: text/markdown
+
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/muse-writes/probLM-solver) [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/muse-writes/probLM-solver) [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)](https://muse-writes.github.io/probLM-solver)
+
+# probLM-solver
+
+A python library and CLI app built on top of llama.cpp which can generate and modify language model outputs based on internal probabilities. Included are utilities for generating large numbers of LLM outputs for performing statistical analysis, as well as outputting and modifying token-by-token conditional probabilities for a given output.
+
+Of particular importance is the ability to define sampling functions for token generation, based off of the answer's power distribution, via iteratively sampling branches of future tokens.
+
+This library is currently in active development, so expect large changes.
+
+## Usage
+
+### Bare Metal
+
+This project is managed with uv, ensure you have Python, pip, and uv installed. To create and activate the virtual environment, run:
+
+```sh
+uv sync --python 3.13 --no-dev
+source .venv/bin/activate
+```
+
+To install this package as a library, if you have cloned the repository, run:
+
+```sh
+python3 -m pip install /path/to/repository
+```
+
+else, if you only desire the library, run:
+
+```sh
+pip install git+https://github.com/muse-writes/probLM-solver
+```
+
+### Conda
+
+An `environment.yml` is provided for conda users (Miniforge, Miniconda, or Anaconda). To create and activate the environment, run:
+
+```sh
+conda env create -f environment.yml
+conda activate problm-solver
+```
+
+If you have an NVIDIA GPU and want hardware-accelerated inference, reinstall `llama-cpp-python` with CUDA support after activating the environment:
+
+```sh
+CMAKE_ARGS="-DGGML_CUDA=on" pip install "llama-cpp-python>=0.3.23" --force-reinstall
+```
+
+On the HEC, and other HPC systems which use Nvidia L40(S) and H200 GPUs, oftentimes the login node won't have native GPUs, so use the command:
+
+```sh
+CMAKE_ARGS="-DGGML_CUDA=on -DGGML_NATIVE=off -DCMAKE_CUDA_ARCHITECTURES=89;90 pip install --force-reinstall --no-cache-dir "llama-cpp-python>=0.3.23"
+```
+
+For complete and custom installation of `llama-cpp-python`, see [llama.cpp build docs](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md#cuda).
+
+### Docker
+
+The CLI itself can be run in a docker container for testing the program.
+
+To serve this app, run:
+
+```sh
+docker-compose run app --build
+```
+
+Within the Dev Container this is equivalent to:
+
+```sh
+poe serve
+```
+
+## Contributing
+
+<details>
+<summary>Prerequisites</summary>
+
+1. [Generate an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) and [add the SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+1. Configure SSH to automatically load your SSH keys:
+
+    ```sh
+    cat << EOF >> ~/.ssh/config
+    
+    Host *
+      AddKeysToAgent yes
+      IgnoreUnknown UseKeychain
+      UseKeychain yes
+      ForwardAgent yes
+    EOF
+    ```
+
+1. [Install Docker Desktop](https://www.docker.com/get-started).
+1. [Install VS Code](https://code.visualstudio.com/) and [VS Code's Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Alternatively, install [PyCharm](https://www.jetbrains.com/pycharm/download/).
+1. _Optional:_ install a [Nerd Font](https://www.nerdfonts.com/font-downloads) such as [FiraCode Nerd Font](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/FiraCode) and [configure VS Code](https://github.com/tonsky/FiraCode/wiki/VS-Code-Instructions) or [PyCharm](https://github.com/tonsky/FiraCode/wiki/Intellij-products-instructions) to use it.
+
+</details>
+
+<details open>
+<summary>Development environments</summary>
+
+The following development environments are supported:
+
+1. ⭐️ _GitHub Codespaces_: click on [Open in GitHub Codespaces](https://github.com/codespaces/new/muse-writes/probLM-solver) to start developing in your browser.
+1. ⭐️ _VS Code Dev Container (with container volume)_: click on [Open in Dev Containers](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/muse-writes/probLM-solver) to clone this repository in a container volume and create a Dev Container with VS Code.
+1. ⭐️ _uv_: clone this repository and run the following from root of the repository:
+
+    ```sh
+    # Create and install a virtual environment
+    uv sync --python 3.13 --all-extras
+
+    # Activate the virtual environment
+    source .venv/bin/activate
+
+    # Install the pre-commit hooks
+    pre-commit install --install-hooks
+    ```
+
+1. _VS Code Dev Container_: clone this repository, open it with VS Code, and run <kbd>Ctrl/⌘</kbd> + <kbd>⇧</kbd> + <kbd>P</kbd> → _Dev Containers: Reopen in Container_.
+1. _PyCharm Dev Container_: clone this repository, open it with PyCharm, [create a Dev Container with Mount Sources](https://www.jetbrains.com/help/pycharm/start-dev-container-inside-ide.html), and [configure an existing Python interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html#widget) at `/opt/venv/bin/python`.
+
+</details>
+
+<details open>
+<summary>Developing</summary>
+
+- This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) with [Commitizen](https://github.com/commitizen-tools/commitizen).
+- Run `poe` from within the development environment to print a list of [Poe the Poet](https://github.com/nat-n/poethepoet) tasks available to run on this project.
+- Run `uv add {package}` from within the development environment to install a run time dependency and add it to `pyproject.toml` and `uv.lock`. Add `--dev` to install a development dependency.
+- Run `uv sync --upgrade` from within the development environment to upgrade all dependencies to the latest versions allowed by `pyproject.toml`. Add `--only-dev` to upgrade the development dependencies only.
+- Run `cz bump` to bump the app's version, update the `CHANGELOG.md`, and create a git tag. Then push the changes and the git tag with `git push origin main --tags`.
+- Run `poe mutmut` to analyse test coverage via mutation.
+- The library can be installed in editable mode using `python -m pip install -e .`.
+
+</details>

problm_solver-1.5.1/README.md

@@ -0,0 +1,134 @@
+[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTE3IDE2VjdsLTYgNU0yIDlWOGwxLTFoMWw0IDMgOC04aDFsNCAyIDEgMXYxNGwtMSAxLTQgMmgtMWwtOC04LTQgM0gzbC0xLTF2LTFsMy0zIi8+PC9zdmc+)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/muse-writes/probLM-solver) [![Open in GitHub Codespaces](https://img.shields.io/static/v1?label=GitHub%20Codespaces&message=Open&color=blue&logo=github)](https://github.com/codespaces/new/muse-writes/probLM-solver) [![Documentation](https://img.shields.io/static/v1?label=Documentation&message=View&color=blue&logo=readme&logoColor=white)](https://muse-writes.github.io/probLM-solver)
+
+# probLM-solver
+
+A python library and CLI app built on top of llama.cpp which can generate and modify language model outputs based on internal probabilities. Included are utilities for generating large numbers of LLM outputs for performing statistical analysis, as well as outputting and modifying token-by-token conditional probabilities for a given output.
+
+Of particular importance is the ability to define sampling functions for token generation, based off of the answer's power distribution, via iteratively sampling branches of future tokens.
+
+This library is currently in active development, so expect large changes.
+
+## Usage
+
+### Bare Metal
+
+This project is managed with uv, ensure you have Python, pip, and uv installed. To create and activate the virtual environment, run:
+
+```sh
+uv sync --python 3.13 --no-dev
+source .venv/bin/activate
+```
+
+To install this package as a library, if you have cloned the repository, run:
+
+```sh
+python3 -m pip install /path/to/repository
+```
+
+else, if you only desire the library, run:
+
+```sh
+pip install git+https://github.com/muse-writes/probLM-solver
+```
+
+### Conda
+
+An `environment.yml` is provided for conda users (Miniforge, Miniconda, or Anaconda). To create and activate the environment, run:
+
+```sh
+conda env create -f environment.yml
+conda activate problm-solver
+```
+
+If you have an NVIDIA GPU and want hardware-accelerated inference, reinstall `llama-cpp-python` with CUDA support after activating the environment:
+
+```sh
+CMAKE_ARGS="-DGGML_CUDA=on" pip install "llama-cpp-python>=0.3.23" --force-reinstall
+```
+
+On the HEC, and other HPC systems which use Nvidia L40(S) and H200 GPUs, oftentimes the login node won't have native GPUs, so use the command:
+
+```sh
+CMAKE_ARGS="-DGGML_CUDA=on -DGGML_NATIVE=off -DCMAKE_CUDA_ARCHITECTURES=89;90 pip install --force-reinstall --no-cache-dir "llama-cpp-python>=0.3.23"
+```
+
+For complete and custom installation of `llama-cpp-python`, see [llama.cpp build docs](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md#cuda).
+
+### Docker
+
+The CLI itself can be run in a docker container for testing the program.
+
+To serve this app, run:
+
+```sh
+docker-compose run app --build
+```
+
+Within the Dev Container this is equivalent to:
+
+```sh
+poe serve
+```
+
+## Contributing
+
+<details>
+<summary>Prerequisites</summary>
+
+1. [Generate an SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key) and [add the SSH key to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+1. Configure SSH to automatically load your SSH keys:
+
+    ```sh
+    cat << EOF >> ~/.ssh/config
+    
+    Host *
+      AddKeysToAgent yes
+      IgnoreUnknown UseKeychain
+      UseKeychain yes
+      ForwardAgent yes
+    EOF
+    ```
+
+1. [Install Docker Desktop](https://www.docker.com/get-started).
+1. [Install VS Code](https://code.visualstudio.com/) and [VS Code's Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). Alternatively, install [PyCharm](https://www.jetbrains.com/pycharm/download/).
+1. _Optional:_ install a [Nerd Font](https://www.nerdfonts.com/font-downloads) such as [FiraCode Nerd Font](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/FiraCode) and [configure VS Code](https://github.com/tonsky/FiraCode/wiki/VS-Code-Instructions) or [PyCharm](https://github.com/tonsky/FiraCode/wiki/Intellij-products-instructions) to use it.
+
+</details>
+
+<details open>
+<summary>Development environments</summary>
+
+The following development environments are supported:
+
+1. ⭐️ _GitHub Codespaces_: click on [Open in GitHub Codespaces](https://github.com/codespaces/new/muse-writes/probLM-solver) to start developing in your browser.
+1. ⭐️ _VS Code Dev Container (with container volume)_: click on [Open in Dev Containers](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/muse-writes/probLM-solver) to clone this repository in a container volume and create a Dev Container with VS Code.
+1. ⭐️ _uv_: clone this repository and run the following from root of the repository:
+
+    ```sh
+    # Create and install a virtual environment
+    uv sync --python 3.13 --all-extras
+
+    # Activate the virtual environment
+    source .venv/bin/activate
+
+    # Install the pre-commit hooks
+    pre-commit install --install-hooks
+    ```
+
+1. _VS Code Dev Container_: clone this repository, open it with VS Code, and run <kbd>Ctrl/⌘</kbd> + <kbd>⇧</kbd> + <kbd>P</kbd> → _Dev Containers: Reopen in Container_.
+1. _PyCharm Dev Container_: clone this repository, open it with PyCharm, [create a Dev Container with Mount Sources](https://www.jetbrains.com/help/pycharm/start-dev-container-inside-ide.html), and [configure an existing Python interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html#widget) at `/opt/venv/bin/python`.
+
+</details>
+
+<details open>
+<summary>Developing</summary>
+
+- This project follows the [Conventional Commits](https://www.conventionalcommits.org/) standard to automate [Semantic Versioning](https://semver.org/) and [Keep A Changelog](https://keepachangelog.com/) with [Commitizen](https://github.com/commitizen-tools/commitizen).
+- Run `poe` from within the development environment to print a list of [Poe the Poet](https://github.com/nat-n/poethepoet) tasks available to run on this project.
+- Run `uv add {package}` from within the development environment to install a run time dependency and add it to `pyproject.toml` and `uv.lock`. Add `--dev` to install a development dependency.
+- Run `uv sync --upgrade` from within the development environment to upgrade all dependencies to the latest versions allowed by `pyproject.toml`. Add `--only-dev` to upgrade the development dependencies only.
+- Run `cz bump` to bump the app's version, update the `CHANGELOG.md`, and create a git tag. Then push the changes and the git tag with `git push origin main --tags`.
+- Run `poe mutmut` to analyse test coverage via mutation.
+- The library can be installed in editable mode using `python -m pip install -e .`.
+
+</details>

problm_solver-1.5.1/pyproject.toml

@@ -0,0 +1,187 @@
+[build-system]  # https://docs.astral.sh/uv/concepts/build-backend/
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[project]  # https://packaging.python.org/en/latest/specifications/pyproject-toml/
+name = "problm-solver"
+version = "1.5.1"
+description = "A python library built on top of llama.cpp which generates and performs statistical analysis on language model outputs."
+readme = "README.md"
+authors = [
+  { name = "Clio", email = "d.k.johnson@lancaster.ac.uk" },
+]
+requires-python = ">=3.13,<4.0"
+dependencies = [
+  "fsspec",
+  "huggingface_hub",
+  "llama-cpp-python",
+  "numpy",
+  "pandas >= 3.0.3",
+  "tqdm >= 4.67.3",
+  "poethepoet",
+]
+
+[project.scripts]
+problm-solver = "problm_solver.cli:main"
+
+[project.urls]  # https://packaging.python.org/en/latest/specifications/well-known-project-urls/#well-known-labels
+homepage = "https://github.com/muse-writes/probLM-solver"
+source = "https://github.com/muse-writes/probLM-solver"
+changelog = "https://github.com/muse-writes/probLM-solver/blob/main/CHANGELOG.md"
+releasenotes = "https://github.com/muse-writes/probLM-solver/releases"
+documentation = "https://muse-writes.github.io/probLM-solver"
+issues = "https://github.com/muse-writes/probLM-solver/issues"
+
+[dependency-groups]  # https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies
+dev = [
+  "codespell (>=2.4.1)",
+  "commitizen (>=4.3.0)",
+  "coverage[toml] (>=7.6.10)",
+  "ipykernel (>=6.29.4)",
+  "ipython (>=8.18.0)",
+  "ipywidgets (>=8.1.2)",
+  "pre-commit (>=4.0.1)",
+  "pytest (>=8.3.4)",
+  "pytest-mock (>=3.14.0)",
+  "pytest-xdist (>=3.6.1)",
+  "ruff (>=0.9.2)",
+  "tqdm (>= 4.67.3)",
+  "ty (>=0.0.6)",
+  "typeguard (>=4.4.1)",
+  "sphinx (>=9.1.0)",
+  "sphinx-autodoc-typehints (>=3.10.2)",
+  "shibuya (>=2026.1.9)",
+  "mutmut>=3.5.0",
+]
+
+[tool.codespell]  # https://github.com/codespell-project/codespell
+builtin = "en-GB_to_en-US,clear,code,rare"
+check-filenames = true
+skip = "./*_cache/,./.venv,./reports"
+
+[tool.commitizen]  # https://commitizen-tools.github.io/commitizen/config/
+bump_message = "bump: v$current_version → v$new_version"
+tag_format = "v$version"
+update_changelog_on_bump = true
+version_provider = "uv"
+
+[tool.coverage.report]  # https://coverage.readthedocs.io/en/latest/config.html#report
+fail_under = 50
+precision = 1
+show_missing = true
+skip_covered = true
+
+[tool.coverage.run]  # https://coverage.readthedocs.io/en/latest/config.html#run
+branch = true
+command_line = "--module pytest"
+data_file = "reports/.coverage"
+source = ["src"]
+
+[tool.coverage.xml]  # https://coverage.readthedocs.io/en/latest/config.html#xml
+output = "reports/coverage.xml"
+
+[tool.pytest.ini_options]  # https://docs.pytest.org/en/latest/reference/reference.html#ini-options-ref
+addopts = "--color=yes --doctest-modules --exitfirst --failed-first --strict-config --strict-markers --verbosity=2 --junitxml=reports/pytest.xml"
+filterwarnings = ["error", "ignore::DeprecationWarning"]
+testpaths = ["src", "tests"]
+xfail_strict = true
+
+[tool.ruff]  # https://docs.astral.sh/ruff/settings/
+fix = true
+line-length = 100
+src = ["src", "tests"]
+target-version = "py313"
+
+[tool.ruff.format]
+docstring-code-format = true
+skip-magic-trailing-comma = true
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["CPY", "FIX", "ARG001", "COM812", "D203", "D213", "E501", "PD008", "PD009", "RET504", "S101", "TD003", "PTH"]
+unfixable = ["ERA001", "F401", "F841", "T201", "T203"]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+multiline-quotes = "single"
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = false
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ty.rules]
+unused-ignore-comment = "warn"
+
+[tool.mutmut]
+source_paths = ["src/"]
+pytest_add_cli_args_test_selection = ["tests/"]
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.poe.executor]  # https://github.com/nat-n/poethepoet
+type = "virtualenv"
+
+[tool.poe.tasks]
+
+  [tool.poe.tasks.docs]
+  help = "Build or serve the documentation"
+  shell = """
+    if [ $serve ]
+    then {
+      xdg-open docs/_build/html/index.html
+    } else {
+      cd docs
+      make html
+    } fi
+    """
+
+    [[tool.poe.tasks.docs.args]]
+    help = "Serve the documentation locally with live reload"
+    type = "boolean"
+    name = "serve"
+    options = ["--serve"]
+
+  [tool.poe.tasks.serve]
+  help = "Serve the app"
+  cmd = "problm-solver"
+
+  [tool.poe.tasks.lint]
+  help = "Lint this app"
+  cmd = """
+    pre-commit run
+      --all-files
+      --color always
+    """
+
+  [tool.poe.tasks.mutmut]
+  help = "Run mutation tests"
+  env = { PYTEST_ADDOPTS = "--color=yes --strict-config --strict-markers -q" }
+  cmd = "mutmut run"
+
+  [tool.poe.tasks.conda]
+  help = "Create the conda environment."
+  cmd = "conda env create -f environment.yml"
+
+  [tool.poe.tasks.test]
+  help = "Test this app"
+
+    [[tool.poe.tasks.test.sequence]]
+    cmd = "coverage run"
+
+    [[tool.poe.tasks.test.sequence]]
+    cmd = "coverage report"
+
+    [[tool.poe.tasks.test.sequence]]
+    cmd = "coverage xml"

problm_solver-1.5.1/src/problm_solver/__init__.py

@@ -0,0 +1,9 @@
+"""probLM-solver."""
+
+from problm_solver.random import RandomManager
+
+PSRandom = RandomManager
+
+__all__ = [
+    'PSRandom'
+]