ucsc-chessai 0.0.0__tar.gz

ucsc_chessai-0.0.0/.ci/build_site.sh

@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# Create a full website including all documentation ready to be deployed.
+# This script should only be done from a clean repo on the main branch.
+# Documentation will be generated from the main branch (latest) as well as each version tag.
+
+readonly THIS_DIR="$(cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd | xargs realpath)"
+readonly ROOT_DIR="${THIS_DIR}/.."
+readonly TEMPLATE_HTML_DIR="${THIS_DIR}/html"
+readonly BUILD_DIR="${ROOT_DIR}/html"
+readonly BASE_OUT_DIR="${ROOT_DIR}/._site"
+readonly DOCS_DIRNAME='docs'
+readonly DOCS_OUT_DIR="${BASE_OUT_DIR}/${DOCS_DIRNAME}"
+readonly GEN_DOCS_SCRIPT="${ROOT_DIR}/scripts/gen_docs.sh"
+
+readonly MAIN_BRANCH="main"
+
+readonly INDEX_TITLE_LOCATION='<header class="pdoc">'
+readonly MODULE_TITLE_LOCATION='<section class="module-info">'
+
+readonly API_DOC_MARKER='<!-- API-DOC-MARKER -->'
+
+# Don't generate any docs for this version or earlier.
+readonly ONLY_AFTER_TAG='v2.0.2'
+
+function check_git() {
+    if [ ! -z "$(git status --porcelain)" ] ; then
+        echo "ERROR: Repository is not clean."
+        exit 1
+    fi
+
+    if [ $(git branch --show-current) != 'main' ] ; then
+        echo "ERROR: Repository is not on the main branch."
+        exit 2
+    fi
+
+    return 0
+}
+
+function gen_docs() {
+    local label=$1
+    local reference=$2
+
+    echo "Generating docs for '${label}'."
+
+    rm -rf "${BUILD_DIR}"
+    ${GEN_DOCS_SCRIPT}
+
+    # Add in the label to the landing pages.
+    local git_link="https://github.com/ucsc-cse-240/chessai/tree/${reference}"
+
+    local index_title="<h1 style='flex-grow: 1'>Chessai API Reference: <a href='${git_link}'>${label}</a></h1>"
+    sed -i "s#${INDEX_TITLE_LOCATION}#${INDEX_TITLE_LOCATION}${index_title}#" "${BUILD_DIR}/index.html"
+
+    local module_title="<h1>Chessai API Reference: <a href='${git_link}'>${label}</a></h1>"
+    sed -i "s#${MODULE_TITLE_LOCATION}#${MODULE_TITLE_LOCATION}${module_title}#" "${BUILD_DIR}/chessai.html"
+
+    # Moved the compiled documentation to the main site.
+    mkdir -p "${DOCS_OUT_DIR}"
+    mv "${BUILD_DIR}" "${DOCS_OUT_DIR}/${label}"
+
+    # Add this documentation to the main index page.
+    local index_li="<li><a href='${DOCS_DIRNAME}/${label}/index.html'>${label}</a></li>"
+    sed -i "s#${API_DOC_MARKER}#${index_li}${API_DOC_MARKER}#" "${BASE_OUT_DIR}/index.html"
+}
+
+function main() {
+    if [[ $# -ne 0 ]]; then
+        echo "USAGE: $0"
+        exit 1
+    fi
+
+    set -e
+    trap exit SIGINT
+
+    cd "${ROOT_DIR}"
+
+    # Remove any existing output.
+    rm -rf "${BASE_OUT_DIR}"
+    cp -r "${TEMPLATE_HTML_DIR}" "${BASE_OUT_DIR}"
+
+    # Ensure that the repo looks good.
+    check_git
+
+    # Generate the latest documentation.
+    local git_hash=$(git rev-parse --short HEAD)
+    gen_docs "latest (${git_hash})" "${git_hash}"
+
+    # Generate docs for each tagged version.
+    for tag in $(git tag -l | grep -P '^v\d+\.\d+\.\d+') ; do
+        if [[ ! "${tag}" > "${ONLY_AFTER_TAG}" ]] ; then
+            continue
+        fi
+
+        git checkout --quiet "${tag}"
+        gen_docs "${tag}" "${tag}"
+    done
+
+    # Move back to main.
+    git checkout --quiet main
+
+    return 0
+}
+
+[[ "${BASH_SOURCE[0]}" == "${0}" ]] && main "$@"

ucsc_chessai-0.0.0/.ci/html/css/style.css

@@ -0,0 +1,18 @@
+ul {
+    margin: 0;
+}
+
+h1, p {
+    margin: 0;
+}
+
+.page {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    flex-wrap: nowrap;
+    justify-content: flex-start;
+    align-items: center;
+    gap: 2em;
+}

ucsc_chessai-0.0.0/.ci/html/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset='utf-8'/>
+        <meta name='viewport' content='width=device-width, initial-scale=1.0'>
+
+        <title>Chessai</title>
+
+        <!-- <link rel="icon" href="images/favicon.ico"> -->
+
+        <link rel='stylesheet' type='text/css' href='css/style.css'>
+    </head>
+    <body>
+        <div class='page'>
+            <h1>chessai</h1>
+
+            <!-- <img src='images/pacman.webp' alt='Pac-Man Game' /> -->
+
+            <div class='overview'>
+                <p>Chessai is an AI educational project disguised as <a href='https://en.wikipedia.org/wiki/Chess'>Chess!</a></p>
+                <p>You can find the main repository at <a href='https://github.com/ucsc-cse-240/chessai'>github.com/ucsc-cse-240/chessai</a>.</p>
+                <p>Below you can find API references for various different version of chessai.</p>
+                </p>
+            </div>
+
+            <div class='docs'>
+                <span>Versions:</span>
+                <ul>
+                    <!-- API-DOC-MARKER -->
+                </ul>
+            </div>
+        </div>
+    </body>
+</html>

ucsc_chessai-0.0.0/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Chessai Code of Conduct
+
+*This document outlines the general principles that one should follow when participating in any event/space that Chessai manages.*
+
+Our goal is to create a healthy and vibrant community of contributors to support our mission.
+To that end, we have created a few guiding principles that we ask all participants to adhere to.
+The principles enumerated here are are guidelines, not hard-and-fast rules, and may evolve over time.
+Do your best to act in accordance with the spirit of these guidelines.
+
+Serious or repeat offenders may be temporarily or permanently banned from Chessai resources.
+
+## Code of Conduct
+
+### You are Responsible for Your Contributions
+
+You should be able to understand, explain, and justify every piece of code or resource that you contribute.
+Of course, we do not expect all code to be impossibly bug-free,
+but you should do your best to produce the highest quality code you can.
+
+You are responsible for ensuring that you have the legal right to submit all code/resources you present.
+
+### Be Respectful
+
+Try to act with respect, compassion, and empathy towards everyone in accordance with reason.
+Insults or harassment are not acceptable.
+
+### Act in Good Faith and Assume Good Faith from Others
+
+There are many differing ways to produce high-quality software,
+assume that others are working towards that same goal as you
+(even if they are approaching it from a different direction).
+
+### Foster Collaboration
+
+Do your best to promote a collaborative environment.
+
+Ask questions when you need to and do your best to answer the questions of others.
+When asking questions, be mindful to respect the time of others.
+Asking for help is an inevitable part of contributing,
+but ensure that your have done your due-diligence before asking for help.
+
+Prefer open communication methods (e.g., a forum post instead of a direct message)
+so that others can learn from and join relevant discussions.
+
+Try to keep discussions and disagreements constructive and focused on the task at hand.
+
+### Try to be Concise
+
+More text often means more work and more opportunities for misunderstanding.
+Try to be concise and direct with your communication, documentation, and code.
+Take your time to choose words carefully rather than using many words that may be misconstrued.
+
+### Never Stop Learning
+
+In addition to just collaborating,
+do your best to maintain a safe learning environment for everyone.
+We strive to always learn more and improve.
+
+### When Someone Breaks the Code
+
+If you encounter someone who is not adhering to these guidelines,
+try to politely point them to this code of conduct.
+Remember that someone may just be having a hard time or trouble communicating.
+
+If you have persisting problems, contact [lmellenb@ucsc.edu](mailto:lmellenb@ucsc.edu).
+
+## Resources / Inspirations
+
+Below are some resources that we consulted and took inspiration from when writing our code of conduct:
+ - https://opensourceconduct.com
+ - https://www.ashedryden.com/blog/codes-of-conduct-101-faq
+ - https://confcodeofconduct.com/
+ - https://terms.archlinux.org/docs/code-of-conduct/
+ - https://www.apache.org/foundation/policies/conduct.html
+ - https://www.debian.org/code_of_conduct
+ - https://www.djangoproject.com/conduct/
+ - https://www.freebsd.org/internal/code-of-conduct/

ucsc_chessai-0.0.0/.github/CONTRIBUTING.md

@@ -0,0 +1,152 @@
+# Chessai Contributing Guide
+
+Thanks for wanting to contribute!
+
+All code and resources contributed to a project become owned by the project under the respective license upon submission.
+
+## Code of Conduct
+
+Make sure to familiarize yourself with our [Code of Conduct](./CODE_OF_CONDUCT.md).
+
+## Reporting Issues
+
+To allow for flexibility when it comes to issue types and submission contexts,
+we do not have a strict template for reporting issues.
+Try to follow this general guidance when submitting (or dealing with) issues:
+
+ - Be sure to clearly state your issue.
+   Be descriptive and concise.
+   The required information changes depending on the specific needs,
+   but some information generally required for bugs is:
+    - Steps to reproduce the issue.
+    - Expected vs actual behavior.
+    - Your environment (OS, language version, etc.) if applicable.
+
+ - Note that issues are not meant for arbitrary communication,
+   see [the Discussion section](#discussion) for guidance on that.
+
+ - Remember that the aims of the project may differ from your personal needs.
+   So, a contributor may not agree with the priority or need for an issue.
+
+ - Remember that this is open source and we have limited resources,
+   so we may not address an issue as fast as you would like.
+   In cases like this, submitting a PR yourself could help out.
+
+ - We don't call "dibs" or reserve issues.
+   A PR is the best way to show others your interest in an issue.
+   Conversely, if you clearly see someone working on an issue, don't try to "scoop" them.
+   If it looks like an effort was abandoned, feel free to politely ask them or an admin if they are going forward with it.
+
+## Submitting a PR
+
+Thanks for wanting to contribute to our projects!
+Healthy open source ecosystems depend on contributors like you.
+Pull/Merge requests (and code reviews) are a fundamental part of Software Engineering.
+They can be very intimidating (especially to a new developer),
+but they are the type of thing that gets easier the more you do them.
+
+### General Guidance on PRs
+
+ - Contributors should strive to make things as easy as possible on the reviewer.
+   You are using their time, so make sure to respect it.
+
+ - Ensure that the description is sufficient, but concise.
+   Overly long PR descriptions waste the reviewer's time.
+
+ - Keep in mind that PR comments are generally terse, but constructive.
+   Try to read them with a positive outlook.
+   Receiving criticism on code can be tough at first, it gets easier over time.
+
+ - You are responsible for ensuring that you have the legal right to submit all code/resources you present.
+
+ - When you are ready for a new pass/re-review, make sure to explicitly let the reviewer know you are ready.
+   Often the PR system (like GitHub) may send out messages for every commit, so it can be hard for a reviewer to tell when the code is ready.
+   There will usually be a "Re-request Review" button you can use to indicate that you are ready for another pass.
+
+ - Ensure that all comments are addressed before requesting another pass by a reviewer.
+   If a comment has been fully addressed, resolve it (via the resolve button) without further comments.
+   If a comment requires further discussion, then comment on it.
+   Keep in mind what things will look like for the reviewer.
+   When they re-review a PR, they should only see things that need action on their part.
+
+    - Note that this also applies when a reviewer asks a question in a comment,
+      and you agree with the premise of the question and make changes accordingly.
+      For example, if a review says: "Shouldn't this be 1?",
+      then you can just resolve if you agree that it should be 1 and you make that change.
+      Only comment if further discussion is required.
+
+ - Take your time.
+   Quality is strongly preferred over quantity.
+
+ - Do not submit an AI code review to your own PR (e.g., having CoPilot do a pass on a PR).
+   A reviewer may choose to use an AI tool to assist them with a review,
+   but a contributor should not submit reviews to their own code.
+
+ - Review your own PR before asking for a (re)review.
+
+### Extra Advice for New Contributors
+
+For contributors that are new to PRs,
+here is a general procedure you can follow:
+ 1. Fork the target repo.
+ 2. Make a branch in your fork for the new changes (here we will call it `change-branch`).
+ 3. Implement your code, tests, and documentation in `change-branch`. Make sure your code passes testing and CI.
+ 4. Review your code.
+ 5. Create a new branch for your PR based on `change-branch` (here we will call it `pr-branch`).
+ 6. Create a PR using `pr-branch`.
+ 7. Wait patiently for comments.
+ 8. Address comments first in `change-branch`.
+ 9. Do a self review. Make sure to check style, tests, and CI.
+ 10. Once your changes are looking good, merge them into `pr-branch`.
+ 11. Re-request a review (there is usually a button for this).
+ 12. If changes are requested, GOTO 7.
+ 13. Done! Update your fork.
+
+Note that the use of multiple branches is to avoid excess emails that can happen when you push changes to a branch with an open PR.
+It also gives more advanced users the opportunity to squash changes before the next PR pass.
+
+For new contributors, we have some additional rules:
+ - At most 1 open PR at a time.
+ - Try to stick to "Easy" issues.
+   It is expected that contributors tackling "Medium/Hard" issues are experienced with this repository and/or open source development.
+   We will provide limited or no support for new contributor tackling harder issues.
+
+## General Coding Style
+
+The coding style we use will differ based on the language and project.
+Follow the rules of the specific project/repo you are in.
+
+In general, follow these principles:
+
+ - Be consistent with existing code.
+ - Strive to write maintainable code that is:
+   - easy to read,
+   - self documenting,
+   - and not surprising.
+
+## AI Tools
+
+We do not outright ban the use of AI coding tools.
+However, it is important to remember that all code you submit is considered yours.
+You are responsible for all your code.
+You are expected to fully understand, explain, and justify all your code.
+If we find that you are not acting responsibly with your code, we may ban you.
+
+AI tools can make it very easy to do things like submit PRs,
+but can waste a reviewer's time if the code is of low-quality.
+Not respecting a review's time is against our [Code of Conduct](./CODE_OF_CONDUCT.md#foster-collaboration) and can result in being banned.
+
+If you are using a coding tool and someone asks you about it,
+you should be honest and willing to disclose the tool, version, and how you used it.
+If you are not comfortable disclosing this information, then avoid using AI coding tools.
+
+Also be wary when using AI tools for text/conversations (e.g., emails, PR descriptions, issues, etc).
+AI will often generate text that is much longer and more verbose than necessary.
+Unnecessarily long conversations are generally against our [Code of Conduct](./CODE_OF_CONDUCT.md#try-to-be-concise).
+
+We always encourage learning.
+If you use AI tools, use them in a way that helps you learn, instead of taking away your learning opportunities.
+
+## Discussion
+
+For discussion outside of GitHub, you can use our [Discord](https://discord.gg/xRxdbWqtWS).

ucsc_chessai-0.0.0/.github/workflows/main.yml

@@ -0,0 +1,152 @@
+name: Main
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+        os: ['ubuntu-22.04', 'ubuntu-24.04', 'macos-14', 'macos-15', 'windows-2022', 'windows-2025']
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache Python Dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-os:${{ matrix.os }}-python:${{ matrix.python-version }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}
+
+      - name: Install Dependencies
+        shell: bash
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Check Python Version Compatibility
+        shell: bash
+        run: scripts/check_python_version.sh
+
+      - name: Check Types
+        shell: bash
+        run: ./scripts/check_types.sh
+
+      - name: Check Lint
+        shell: bash
+        run: ./scripts/check_lint.sh
+
+      - name: Run Tests
+        shell: bash
+        run: ./scripts/run_tests.sh
+
+      - name: Generate Documentation
+        if: runner.os == 'Linux'
+        shell: bash
+        run: ./scripts/gen_docs.sh
+
+  docs:
+    needs: test
+    if: ${{ github.event_name == 'push' && github.repository_owner == 'ucsc-cse-240' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/')) }}
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    strategy:
+      matrix:
+        python-version: ['3.11']
+        os: ['ubuntu-24.04']
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache Python Dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-os:${{ matrix.os }}-python:${{ matrix.python-version }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}
+
+      - name: Install Dependencies
+        shell: bash
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build Site
+        shell: bash
+        run: |
+            git checkout main
+            ./.ci/build_site.sh
+
+      - name: Upload Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '._site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  deploy:
+    needs: docs
+
+    strategy:
+      matrix:
+        python-version: ['3.11']
+        os: ['ubuntu-24.04']
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set Up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache Python Dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-os:${{ matrix.os }}-python:${{ matrix.python-version }}-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ hashFiles('requirements.txt') }}-${{ hashFiles('requirements-dev.txt') }}
+
+      - name: Install Python Dependencies
+        shell: bash
+        run: pip3 install -r requirements.txt -r requirements-dev.txt
+
+      - name: Deploy
+        uses: casperdcl/deploy-pypi@10cf4cd83fc885003a8d4f37f93a5a0f0fc2d2f4  # v2.4.1
+        with:
+          build: --sdist --wheel --outdir dist . --verbose
+          # Only upload if a tag is pushed (otherwise just build & check).
+          upload: ${{ github.event_name == 'push' && github.repository_owner == 'ucsc-cse-240' && startsWith(github.event.ref, 'refs/tags') }}
+          password: ${{ secrets.PYPI_TOKEN }}

ucsc_chessai-0.0.0/.gitignore

@@ -0,0 +1,34 @@
+# Editor Files
+.DS_Store
+*.swp
+
+# Language Dirents
+.ipynb_checkpoints
+node_modules/
+venv/
+*.pyc
+__pycache__/
+
+# Common Temp Dirents
+old/
+temp/
+out*/
+/test*
+
+# Build
+/bin/
+/build/
+/dist/
+*.egg-info
+/html/
+/.mypy_*/
+
+# Project-Specific
+*.gif
+*.gz
+/._site/
+*.zip
+*.xcf
+
+# Do track .gz files in the resources/games directory.
+!chessai/resources/games/*.gz

ucsc_chessai-0.0.0/.mypy.ini

@@ -0,0 +1,9 @@
+[mypy]
+
+exclude = _test\.py$
+
+strict = false
+disable_error_code = type-arg
+
+[mypy-edq.*]
+ignore_missing_imports = True