asplain 0.0.0__tar.gz

asplain-0.0.0/.envrc

@@ -0,0 +1,10 @@
+# automatically activate dev environment when in project tree using direnv.
+ACT=.nox/dev/bin/activate
+
+if [ -e $ACT ]
+then
+    source $ACT
+else
+    echo "Activation script ${ACT} not found for dev environment.
+Run nox -s dev to install dev environment"
+fi

asplain-0.0.0/.github/workflows/deploy.yml

@@ -0,0 +1,48 @@
+name: deploy to pypi
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  deploy:
+    name: deploy
+    needs: test
+    permissions:
+      id-token: write
+    environment: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.11
+
+      - name: install build dependencies
+        run: python3 -m pip install build
+
+      - name: build package
+        run: python3 -m build --sdist --wheel --outdir dist/
+
+      - name: upload package
+        uses: actions/upload-artifact@v4
+        with:
+          name: package
+          path: dist/
+      - name: publish package (pypi)
+        if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: publish package (test.pypi)
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: "https://test.pypi.org/legacy/"

asplain-0.0.0/.github/workflows/doc.yml

@@ -0,0 +1,51 @@
+name: Deploy Documentation
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.12
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .[doc]
+      - name: Build the documentation
+        run: mkdocs build
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v6
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: "./site"
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

asplain-0.0.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: run CI test
+
+on:
+  push:
+    branches: [devel, main, master, wip]
+  pull_request:
+  workflow_call:
+
+env:
+  FORCE_COLOR: "3"
+
+jobs:
+  build:
+    name: test on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: |
+            3.10
+            3.11
+            3.12
+
+      - name: install requirements
+        run: python -m pip install nox pre-commit
+
+      - name: run pre-commit
+        if: ${{ matrix.os == 'ubuntu-latest' }}
+        run: pre-commit run --all --show-diff-on-failure
+
+      - name: run tests
+        run: nox

asplain-0.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Editors
+.vscode/
+*~
+\#*\#
+.\#*
+.idea
+.zed
+
+# Mac/OSX
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.pytest_cache/
+
+# pyenv
+.python-version
+
+# venv
+.venv
+
+# dotenv
+.env
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+*egg-info*
+
+# unclassified
+dist
+build
+.coverage
+_build
+_autosummary
+site
+
+out/*
+*out/

asplain-0.0.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+repos:
+  - repo: https://github.com/myint/autoflake
+    rev: v2.3.1
+    hooks:
+    - id: autoflake
+      args: ["--in-place",  "--imports=asplain", "--ignore-init-module-imports", "--remove-unused-variables"]
+      exclude: ^.github/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+      exclude: ^.github/
+
+  - repo: https://github.com/pycqa/isort
+    rev: 7.0.0
+    hooks:
+      - id: isort
+        exclude: ^.github/
+
+  - repo: https://github.com/psf/black
+    rev: 25.9.0
+    hooks:
+    - id: black
+      exclude: ^.github/
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 1.0.0
+    hooks:
+    - id: mdformat
+      args: ["--wrap", "79"]
+      exclude: ^docs/
+      additional_dependencies:
+      - mdformat-gfm

asplain-0.0.0/.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.10"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: setuptools
+      path: .[doc]

asplain-0.0.0/CHANGES.md

@@ -0,0 +1,5 @@
+# Changes
+
+## v0.1.0
+
+- create project

asplain-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for considering a contribution to asplain. ❤️
+
+## How to get help or discuss possible contributions
+
+To avoid duplicating issues, please search our [issue tracker][issues] and our
+[mailing list][mailing_list] before filing a new issue.
+
+- Open an [issue][new_issue] describing your problem.
+- [Subscribe] to our mailing list on SourceForge.
+
+## How to make a contribution
+
+- Fork the [asplain][project_url] repository and create a branch for your
+  changes.
+- Submit a pull request to the master branch with your changes.
+- Respond to feedback on your pull request.
+- If everything is fine your pull request is merged. 🥳
+
+## License
+
+When contributing to this project, you agree that you have authored 100% of the
+content, that you have the necessary rights to the content and that the content
+you contribute may be provided under the project license.
+
+[issues]: asplainissues/
+[mailing_list]: https://sourceforge.net/p/potassco/mailman/potassco-users/
+[new_issue]: asplainissues/new/
+[project_url]: asplain
+[subscribe]: https://sourceforge.net/projects/potassco/lists/potassco-users/

asplain-0.0.0/DEPLOYMENT.md

@@ -0,0 +1,27 @@
+# Deployment
+
+Releases are deployed on [pypi] whenever a tag of form `vMajor.Minor.Revision`
+is pushed. Furthermore, the deployment workflow can be triggered manually to
+deploy test releases on [test.pypi].
+
+For this to work, the workflow has to be granted permission to deploy on the
+two services. Please follow this packaging [guide] to setup your accounts
+accordingly. We also recommend to setup a github [environment] to restrict
+which contributors can deploy packages.
+
+## Automatic Documentation Deployment
+
+You can automatically publish project documentation to GitHub Pages on every
+new tag. To enable this:
+
+- Go to your repository on GitHub.
+- Navigate to **Settings** > **Pages**.
+- Under **Build and deployment**, set **Source** to **GitHub Actions**.
+
+This setup ensures your documentation is updated and available online whenever
+you create a new release tag via Github workflows.
+
+[environment]: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment/
+[guide]: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+[pypi]: https://pypi.org/
+[test.pypi]: https://test.pypi.org/

asplain-0.0.0/DEVELOPMENT.md

@@ -0,0 +1,63 @@
+# Development
+
+To improve code quality, we use [nox] to run linters, type checkers, unit
+tests, and more. We recommend installing nox using [pipx] to have it available
+globally.
+
+```bash
+# install
+python -m pip install pipx
+python -m pipx install nox
+
+# run all sessions
+nox
+
+# list all sessions
+nox -l
+
+# run individual session
+nox -s session_name
+
+# run individual session (reuse install)
+nox -Rs session_name
+```
+
+Note that the nox sessions create [editable] installs. In case there are
+issues, try recreating environments by dropping the `-R` option. If your
+project is incompatible with editable installs, adjust the `noxfile.py` to
+disable them.
+
+We also provide a [pre-commit][pre] config to autoformat code upon commits. It
+can be set up using the following commands:
+
+```bash
+python -m pipx install pre-commit
+pre-commit install
+```
+
+## Documentation
+
+Make sure the documentation dependencies for the project are properly installed
+with
+
+```bash
+pip install .[doc]
+```
+
+To run the documentation locally use the following command and click the
+provided link to open it in the browser.
+
+```bash
+mkdocs serve
+```
+
+Live development:
+
+```bash
+mkdocs serve --livereload
+```
+
+[editable]: https://setuptools.pypa.io/en/latest/userguide/development_mode.html
+[nox]: https://nox.thea.codes/en/stable/index.html
+[pipx]: https://pypa.github.io/pipx/
+[pre]: https://pre-commit.com/

asplain-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Susana Hahn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asplain-0.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: asplain
+Version: 0.0.0
+Summary: A template project.
+Author-email: Susana Hahn <hahnmartinlu@uni-potsdam.de>
+License: MIT License
+        
+        Copyright (c) 2024 Susana Hahn
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/potassco/asplain.git/
+Project-URL: Documentation, https://docs.potassco.org/asplain/
+Project-URL: Repository, https://github.com/potassco/asplain
+Project-URL: Issues, https://github.com/potassco/asplain/issues
+Project-URL: Changelog, https://github.com/potassco/asplain/blob/master/CHANGES.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clingo>=5.6.0
+Requires-Dist: meta-tools-clingo>=0.3.4
+Requires-Dist: clingraph>=1.2.2
+Provides-Extra: ui
+Requires-Dist: clinguin>=2.7.5; extra == "ui"
+Provides-Extra: llm
+Requires-Dist: openai>=2.8.1; extra == "llm"
+Requires-Dist: dotenv; extra == "llm"
+Requires-Dist: clorm; extra == "llm"
+Requires-Dist: google-genai; extra == "llm"
+Provides-Extra: format
+Requires-Dist: black; extra == "format"
+Requires-Dist: isort; extra == "format"
+Requires-Dist: autoflake; extra == "format"
+Provides-Extra: lint-pylint
+Requires-Dist: pylint; extra == "lint-pylint"
+Provides-Extra: typecheck
+Requires-Dist: types-setuptools; extra == "typecheck"
+Requires-Dist: mypy; extra == "typecheck"
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == "test"
+Provides-Extra: doc
+Requires-Dist: mkdocs; extra == "doc"
+Requires-Dist: mkdocs-material; extra == "doc"
+Requires-Dist: mkdocstrings>=1.0.4; extra == "doc"
+Requires-Dist: mkdocstrings-python>=2.0; extra == "doc"
+Requires-Dist: clindocs>=1.5.2; extra == "doc"
+Requires-Dist: mkdocs-literate-nav; extra == "doc"
+Requires-Dist: pygments_clingo; extra == "doc"
+Provides-Extra: dev
+Requires-Dist: asplain[doc,lint_pylint,test,typecheck]; extra == "dev"
+Dynamic: license-file
+
+[![Documentation](https://img.shields.io/badge/docs-potassco.org-blue)](https://docs.potassco.org/asplain/)
+[![PyPI version](https://img.shields.io/pypi/v/asplain)](https://pypi.org/project/asplain/)
+[![License](https://img.shields.io/github/license/potassco/asplain)](LICENSE)
+
+# asplain
+
+Asplain is a tool for generating contrastive explanations for answer set
+programs (ASP).
+
+## Installation
+
+To install the project, run
+
+```bash
+pip install .
+```
+
+For rendering the images with cligraph, Graphviz needs to be installed
+following `graphviz <https://www.graphviz.org/download/>`\_ (version 2.50 or
+greater).
+
+## Documentation
+
+Full documentation is available at
+**[docs.potassco.org/asplain](https://docs.potassco.org/asplain/)**.
+
+## Usage
+
+Run the following for basic usage information:
+
+```bash
+asplain -h
+```
+
+For a basic usage example, see the
+[examples/james-bond/README.md](examples/james-bond/README.md) file.
+
+### LLM Integration
+
+For using the OpenAI API, an API-Key has to be provided in the `OPENAI_API_KEY`
+environment variable. This can be done using a `.env`file or directly in the
+command line.
+
+#### Using the `.env` file
+
+Create a `.env` file in the root directory of the project and add the following
+line
+
+```.env
+OPENAI_API_KEY=<your-api-key>
+```
+
+#### Using the command line
+
+```bash
+OPENAI_API_KEY=<your-api-key> asplain --llm=<model-tag>
+```

asplain-0.0.0/README.md

@@ -0,0 +1,57 @@
+[![Documentation](https://img.shields.io/badge/docs-potassco.org-blue)](https://docs.potassco.org/asplain/)
+[![PyPI version](https://img.shields.io/pypi/v/asplain)](https://pypi.org/project/asplain/)
+[![License](https://img.shields.io/github/license/potassco/asplain)](LICENSE)
+
+# asplain
+
+Asplain is a tool for generating contrastive explanations for answer set
+programs (ASP).
+
+## Installation
+
+To install the project, run
+
+```bash
+pip install .
+```
+
+For rendering the images with cligraph, Graphviz needs to be installed
+following `graphviz <https://www.graphviz.org/download/>`\_ (version 2.50 or
+greater).
+
+## Documentation
+
+Full documentation is available at
+**[docs.potassco.org/asplain](https://docs.potassco.org/asplain/)**.
+
+## Usage
+
+Run the following for basic usage information:
+
+```bash
+asplain -h
+```
+
+For a basic usage example, see the
+[examples/james-bond/README.md](examples/james-bond/README.md) file.
+
+### LLM Integration
+
+For using the OpenAI API, an API-Key has to be provided in the `OPENAI_API_KEY`
+environment variable. This can be done using a `.env`file or directly in the
+command line.
+
+#### Using the `.env` file
+
+Create a `.env` file in the root directory of the project and add the following
+line
+
+```.env
+OPENAI_API_KEY=<your-api-key>
+```
+
+#### Using the command line
+
+```bash
+OPENAI_API_KEY=<your-api-key> asplain --llm=<model-tag>
+```

asplain-0.0.0/docs/SUMMARY.md

@@ -0,0 +1,35 @@
+* Getting Started
+    * [Getting Started](use/quick-start.md)
+    * [Installation](use/installation.md)
+    * [Help](use/help.md)
+* Reference
+    * [Reference](reference/index.md)
+    * [CLI](reference/cli.md)
+    * [Contrastive Explanation](reference/explanation-graph.md)
+    * Implementation Details
+        * [Setup Construction](reference/setup.md)
+        * [Finding Explanations](reference/foils.md)
+    * Customization
+        * [Tagging](reference/tagging.md)
+        * Explanation Selection
+            * [Explanation Selection](reference/preferences/index.md)
+            * [`model-difference.lp`](reference/preferences/model-difference.md)
+            * [`program-difference.lp`](reference/preferences/program-difference.md)
+            * [`penalize-added.lp`](reference/preferences/penalize-added.md)
+            * [`penalize-removed.lp`](reference/preferences/penalize-removed.md)
+            * [`penalize-non-constraints.lp`](reference/preferences/penalize-non-constraints.md)
+            * [`penalize-non-facts.lp`](reference/preferences/penalize-non-facts.md)
+            * [`penalize-non-assumptions.lp`](reference/preferences/penalize-non-assumptions.md)
+        * [Pruning Methods](reference/pruning.md)
+* Examples
+    * [Examples](examples/index.md)
+    * [James Bond](examples/jamesbond.md)
+    * [Sudoku](examples/sudoku.md)
+    * [Cat-dog](examples/catdog.md)
+    * [Don't drive drunk](examples/dontdrivedrunk.md)
+* Community
+    * [Community](community/index.md)
+    * [Changes](community/CHANGES.md)
+    * [Contributing](community/CONTRIBUTING.md)
+    * [Development](community/DEVELOPMENT.md)
+    * [Deployment](community/DEPLOYMENT.md)