aimsapccoe — College Club Recruitment Matcher

aimsapccoe is a Python package and web application for college club recruitment matching. It automatically evaluates and scores candidate fit against position requirements or club descriptions using web-scraped GitHub and portfolio data.

Scoring is processed across 5 weighted NLP levels:

1. Level 1 — Language & Word Count (10 pts)
2. Level 2 — Vocabulary Richness (20 pts)
3. Level 3 — Keyword Match (30 pts) — TF-IDF cosine similarity
4. Level 4 — Readability (15 pts) — Flesch Reading Ease
5. Level 5 — Parts of Speech Analysis (25 pts) — Action verb and noun ratios

---

📦 Installation

To install the package in editable mode (for development and local running):

# From the project root folder:
pip install -e .

📥 Post-Install NLTK Setup

aimsapccoe automatically attempts to verify and download required NLTK corpus datasets upon first run, but you can download them manually if needed:

import nltk
nltk.download('punkt')
nltk.download('punkt_tab')
nltk.download('averaged_perceptron_tagger')
nltk.download('averaged_perceptron_tagger_eng')
nltk.download('stopwords')

---

🚀 Usage

1. Launch the Web UI

The package includes a modern local dashboard built using a Neo-Brutalism design system. Launch the Flask application with:

aimsapccoe web

Then visit http://127.0.0.1:5000 in your browser.

2. Python API Usage

Secretary Mode (Evaluate Applicants)

from aimsapccoe import SecretaryEvaluator

# Define what position requirements the club is looking for
evaluator = SecretaryEvaluator(
    position_description="Looking for a Python backend developer skilled in Flask and SQL."
)

# Run scoring against the candidate's public URLs
result = evaluator.evaluate_student(
    github_url="https://github.com/someuser",
    portfolio_url="https://someuser.github.io"
)

print(f"Total Match Score: {result['score']}/100")
print(f"Recommendation Verdict: {result['recommendation']}")
# Output: RECRUIT, REVIEW, or IGNORE

Student Mode (Evaluate Personal Fit)

from aimsapccoe import StudentEvaluator

# Scrapes and caches target club site once upon instantiation
evaluator = StudentEvaluator(
    club_website_url="https://acm.pccoe.org"
)

# Evaluate fit against your own profile URLs
result = evaluator.evaluate_fit(
    github_url="https://github.com/myusername",
    portfolio_url="https://myportfolio.dev"
)

print(f"Fit Match Score: {result['score']}/100")
print(f"Recommendation: {result['recommendation']}")
# Output: APPLY or SKIP

---

🧪 Running Tests

Unit tests use mocked API/Scraping requests to run instantly without making live HTTP requests:

# Run using unittest
python -m unittest discover -s tests

---

🚀 Publishing to PyPI

To upload this package to PyPI, follow these steps:

1. Install Build Tools

Ensure you have the latest versions of build and twine installed:

pip install --upgrade build twine

2. Build the Package

Generate the source distribution and wheel archives by running the python build frontend from the project root:

python -m build

This will create a dist/ directory containing the distribution packages (.tar.gz and .whl).

3. Check Distribution Archives

Validate that your package description will render correctly on PyPI:

twine check dist/*

4. Upload to TestPyPI (Recommended first step)

It is highly recommended to upload your package to TestPyPI first to verify everything looks correct:

twine upload --repository testpypi dist/*

Note: You will need to create an account on TestPyPI and generate an API Token.

5. Upload to PyPI Production

Once verified on TestPyPI, upload to the live PyPI index:

twine upload dist/*

Note: You will need a production PyPI account and an API Token to authenticate.