Metadata-Version: 2.4
Name: aimsapccoe
Version: 0.1.1
Summary: College club recruitment matching using web-scraped GitHub & portfolio data scored via NLP.
Author: chiragferwani
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: Flask
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: morphscrapper
Requires-Dist: flask
Requires-Dist: nltk
Requires-Dist: scikit-learn
Requires-Dist: textstat
Requires-Dist: langdetect

# aimsapccoe — College Club Recruitment Matcher

<p align="left">
  <img src="aimsapccoe/web/static/aimsa.jpeg" width="280" alt="AIMSAPCCOE Logo">
</p>

`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):

```bash
# 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:

```python
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:

```bash
aimsapccoe web
```

Then visit [http://127.0.0.1:5000](http://127.0.0.1:5000) in your browser.

### 2. Python API Usage

#### Secretary Mode (Evaluate Applicants)
```python
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)
```python
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:

```bash
# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
twine upload --repository testpypi dist/*
```
*Note: You will need to create an account on [TestPyPI](https://test.pypi.org/) and generate an API Token.*

### 5. Upload to PyPI Production
Once verified on TestPyPI, upload to the live PyPI index:
```bash
twine upload dist/*
```
*Note: You will need a production [PyPI](https://pypi.org/) account and an API Token to authenticate.*

