aimsapccoe 0.1.0__tar.gz

aimsapccoe-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: aimsapccoe
+Version: 0.1.0
+Summary: College club recruitment matching using web-scraped GitHub & portfolio data scored via NLP.
+Author-email: aimsapccoe Team <info@aimsapccoe.org>
+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
+
+`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.*
+

aimsapccoe-0.1.0/README.md

@@ -0,0 +1,138 @@
+# 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):
+
+```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.*
+

aimsapccoe-0.1.0/aimsapccoe/__init__.py

@@ -0,0 +1,41 @@
+"""
+aimsapccoe — College Club Recruitment Matching Package
+=======================================================
+A Python package for matching students to college clubs (or evaluating
+students for club positions) using web-scraped GitHub and portfolio data,
+tokenized and scored across 5 weighted NLP levels.
+
+Modules:
+    core        — shared scraping, tokenization, and scoring logic
+    secretary   — evaluate students for a specific position/club role
+    student     — evaluate student fit for a club based on its website
+    web         — Flask-based dashboard (Neo-Brutalism UI)
+    cli         — command-line entry points
+
+Usage (Python API):
+    from aimsapccoe.secretary import SecretaryEvaluator
+    ev = SecretaryEvaluator(position_description="We need a passionate coder...")
+    result = ev.evaluate_student(
+        github_url="https://github.com/someuser",
+        portfolio_url="https://someuser.dev"
+    )
+    print(result)  # {"score": 75, "breakdown": {...}, "recommendation": "RECRUIT"}
+
+Usage (Web UI):
+    $ aimsapccoe web         # launches http://127.0.0.1:5000
+"""
+
+__version__ = "0.1.0"
+__author__ = "aimsapccoe"
+__description__ = "College club recruitment matching via NLP scoring"
+
+# Expose top-level convenience imports so users can do:
+#   from aimsapccoe import SecretaryEvaluator, StudentEvaluator
+from aimsapccoe.secretary.evaluator import SecretaryEvaluator
+from aimsapccoe.student.evaluator import StudentEvaluator
+
+__all__ = [
+    "SecretaryEvaluator",
+    "StudentEvaluator",
+    "__version__",
+]

aimsapccoe-0.1.0/aimsapccoe/cli.py

@@ -0,0 +1,102 @@
+"""
+cli.py — Command-line entry point for aimsapccoe
+=================================================
+Purpose:
+    Provides the `aimsapccoe` command-line interface. Currently supports:
+
+        aimsapccoe web          — launch the web dashboard on localhost:5000
+
+    Future commands could include:
+        aimsapccoe score        — score from command line arguments
+        aimsapccoe batch        — score a CSV of applicants
+
+Usage:
+    $ aimsapccoe web
+    $ aimsapccoe web --port 8080
+    $ aimsapccoe web --host 0.0.0.0
+"""
+
+import argparse
+import sys
+
+
+def _cmd_web(args):
+    """
+    Launch the aimsapccoe web dashboard.
+
+    Args:
+        args: Parsed argparse namespace with .host and .port attributes.
+    """
+    # Import Flask app here (not at module level) so `aimsapccoe` CLI commands
+    # that don't use the web UI don't pay the Flask import cost.
+    from aimsapccoe.web.app import create_app
+
+    app = create_app()
+    print(f"\n🚀  aimsapccoe web dashboard starting...")
+    print(f"    URL: http://{args.host}:{args.port}")
+    print(f"    Press Ctrl+C to stop.\n")
+
+    app.run(host=args.host, port=args.port, debug=args.debug)
+
+
+def main():
+    """
+    Main entry point for the `aimsapccoe` CLI command.
+
+    Parses arguments and dispatches to the appropriate sub-command handler.
+    Registered in pyproject.toml under [project.scripts].
+    """
+    parser = argparse.ArgumentParser(
+        prog="aimsapccoe",
+        description="aimsapccoe — College Club Recruitment Matching via NLP",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  aimsapccoe web                  # launch on http://127.0.0.1:5000\n"
+            "  aimsapccoe web --port 8080      # use a different port\n"
+            "  aimsapccoe web --host 0.0.0.0   # expose on all interfaces\n"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    subparsers.required = True
+
+    # ── `aimsapccoe web` sub-command ──────────────────────────────────────────
+    web_parser = subparsers.add_parser(
+        "web",
+        help="Launch the aimsapccoe web dashboard (Neo-Brutalism UI)",
+        description=(
+            "Start the local Flask web server. Open http://127.0.0.1:5000 in "
+            "your browser to use the dashboard."
+        ),
+    )
+    web_parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind the server to. Default: 127.0.0.1",
+    )
+    web_parser.add_argument(
+        "--port",
+        type=int,
+        default=5000,
+        help="Port to run the server on. Default: 5000",
+    )
+    web_parser.add_argument(
+        "--debug",
+        action="store_true",
+        default=False,
+        help="Enable Flask debug mode (auto-reloads on code changes).",
+    )
+    web_parser.set_defaults(func=_cmd_web)
+
+    # Parse and dispatch
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print("\n\nStopped.")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

aimsapccoe-0.1.0/aimsapccoe/core/__init__.py

@@ -0,0 +1,16 @@
+"""
+core/__init__.py — Core module for aimsapccoe
+=============================================
+Exposes the main shared utilities: scraper wrappers, the tokenization
+engine, and the scoring function. Both the secretary and student modules
+depend on this core.
+"""
+
+from aimsapccoe.core.scraper import scrape_profile, scrape_github_repos
+from aimsapccoe.core.scoring import calculate_score
+
+__all__ = [
+    "scrape_profile",
+    "scrape_github_repos",
+    "calculate_score",
+]

aimsapccoe-0.1.0/aimsapccoe/core/scoring.py

@@ -0,0 +1,64 @@
+"""
+core/scoring.py — Top-level scoring function for aimsapccoe
+============================================================
+Purpose:
+    Provides the single public function `calculate_score()` that acts as the
+    entry point for the entire NLP scoring pipeline. It wires together the
+    TokenizerEngine and returns a clean, standardised result dict.
+
+    Both the secretary and student evaluators call this function — they never
+    use TokenizerEngine directly. This keeps the interface simple and makes
+    it easy to swap the scoring engine in the future.
+"""
+
+from typing import Optional
+
+from aimsapccoe.core.tokenizer import TokenizerEngine
+
+
+def calculate_score(
+    candidate_text: str,
+    reference_text: str,
+    language_override: Optional[str] = None,
+) -> dict:
+    """
+    Score a candidate against a reference description.
+
+    Purpose:
+        Run the full 5-level NLP pipeline and return a structured result
+        suitable for use in the secretary/student evaluators and the web UI.
+
+    Args:
+        candidate_text (str): Combined text scraped from the candidate's GitHub
+            profile, repositories, and/or portfolio website.
+        reference_text (str): The reference text to compare against. For the
+            secretary module this is a position description; for the student
+            module this is the club's scraped website text.
+        language_override (str | None): Optional ISO language code (e.g. "en")
+            to skip auto-detection. Pass None (default) to auto-detect.
+
+    Returns:
+        dict: {
+            "total": int,       # Final score 0–100
+            "breakdown": {      # Per-level detail for UI display
+                "level1": { "score": int, "max": 10, "label": str, ... },
+                "level2": { "score": int, "max": 20, ... },
+                "level3": { "score": int, "max": 30, ... },
+                "level4": { "score": int, "max": 15, ... },
+                "level5": { "score": int, "max": 25, ... },
+            }
+        }
+
+    Example:
+        result = calculate_score(
+            candidate_text="Alice built a React dashboard for her college club...",
+            reference_text="We are looking for a front-end developer who knows React..."
+        )
+        print(result["total"])          # e.g. 68
+        print(result["breakdown"]["level3"]["similarity"])  # e.g. 0.423
+    """
+    engine = TokenizerEngine(language_override=language_override)
+    return engine.score(
+        candidate_text=candidate_text,
+        reference_text=reference_text,
+    )