Transforming change into a Recruitment Challenge

Author: okhere21@gmail.com

.github/ISSUE_TEMPLATE/bug-fix-winner-check.md

@@ -0,0 +1,12 @@
+name: Fix Rummy winner detection
+about: Correct the game completion and winner detection logic in the modular Rummy implementation.
+title: Fix winner detection and end-of-game flow
+labels: bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The current Rummy implementation should end the game as soon as a player has successfully melded and discarded all cards. Review `rummy/game.py` and `rummy/env.py` to ensure that:
+        - empty hands are recognized as winning states
+        - invalid actions do not advance the turn or corrupt the deck/discard piles
+        - the discard pile is restocked when the deck runs out

.github/ISSUE_TEMPLATE/feature-meld-validation.md

@@ -0,0 +1,12 @@
+name: Improve meld validation rules
+about: Add support for full meld validation and joker handling in the Rummy engine.
+title: Improve Rummy meld validation and wildcard rules
+labels: enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The baseline Rummy engine validates simple melds, but several edge cases remain. Update the validation logic to support:
+        - impure sets and sequences that use printed Jokers or selected wild ranks
+        - same-suit sequence construction with wildcard fill cards
+        - no duplicate cards and correct suit/rank constraints for valid melds

.github/ISSUE_TEMPLATE/feature-rl-observation.md

@@ -0,0 +1,12 @@
+name: Design RL-friendly observations and actions
+about: Refine the Rummy environment so agents can interact without user prompts.
+title: Improve RL environment observation/action design
+labels: enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The current environment exposes a minimal action API, but there is an opportunity to make it more RL-friendly. Update `rummy/env.py` so that:
+        - observations include the current hand, wild rank, top discard, and remaining card counts
+        - actions are encoded as structured dictionaries instead of human input
+        - invalid actions return a consistent penalty and do not corrupt game state

.github/workflows/python-app.yml

@@ -0,0 +1,22 @@
+name: Python CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pytest
+      - name: Run tests
+        run: python -m pytest -q

README.md

@@ -1,13 +1,69 @@
-# RUMMY
-An attempt to make a simple CLI version of the card game-Rummy.
-Another Odd day at College, my hostel neighbor came up to me and gave me a task,"Hey Dude, Can you code Rummy??"
-I was like, "Well that's interesting! Lemme give it a try...."
-And so we have this!!😁
+# Rummy
 
-P.S.- I have never really played  any card came so if there's any fishy game logic, feel free to raise issues, 
-suggestions are always welcome.
+A modular Python implementation of the classic Rummy card game, refactored for agent-based play and reinforcement-learning experiments.
 
-To run the program download the python script, navigate to the downloaded directory and run the following command:<br>
-<br>
-python rummy.py
+This repository turns a single legacy script into an importable package (`rummy/`) with clear separation for:
 
+- Card definitions and helpers (rummy/cards.py)
+- Deck and discard pile management (rummy/deck.py)
+- Game rules and meld validation (rummy/game.py)
+- A simple RL-style environment wrapper (rummy/env.py)
+- A small random agent example (rummy/agents.py)
+
+Why this project
+
+- Make the Rummy game engine testable and importable for research or challenge tasks.
+- Provide a minimal environment API so agents can play without human input.
+- Include CI and tests so merges won't regress core behavior.
+
+Quick start (using uv)
+
+All startup, installs and test runs should use the provided uv environment wrapper from this directory.
+
+1. Open a shell in the repository root and change into the RUMMY folder:
+
+    cd RUMMY
+
+2. Run tests and install dev deps (example):
+
+    uv run python3 -m pip install --upgrade pip
+    uv run python3 -m pip install pytest
+    uv run python3 -m pytest -q
+
+3. Run the example entrypoint (small simulation):
+
+    uv run python3 Rummy.py
+
+Package usage (importing in code)
+
+- From your Python code you can import the environment and game directly:
+
+    from rummy.env import RummyEnv
+    from rummy.game import RummyGame
+
+- Create an environment and reset to get the first observation:
+
+    env = RummyEnv(["Alice", "Bob"], seed=42)
+    obs = env.reset()
+
+Testing and CI
+
+- The repository contains unit tests under `tests/` that validate deck size, dealing, and meld/sequence validation.
+- A GitHub Actions workflow at `.github/workflows/python-app.yml` runs the tests on push and pull requests.
+
+Challenge notes
+
+This repo is intended as a small challenge: some rules and edge cases are intentionally simplified and there are three suggested issues for contributors to improve:
+
+- Fix winner detection and game-end flow
+- Improve meld and wildcard validation rules
+- Expand the RL observation/action API for agents
+
+Contributing
+
+- Open a PR with targeted changes and include/adjust tests to cover the change.
+- The CI workflow will run the test-suite automatically.
+
+License
+
+- This project is provided as-is for educational and challenge purposes. Add a license file if you want to publish it.