Spaces:
Sleeping
Sleeping
| """Job Evaluator (Instruction Set 1). | |
| A hybrid rule layer that screens one uploaded Upwork opportunity through a | |
| fixed 10-signal apply/skip checklist *before* the proposal is written. It | |
| protects a beginner profile from wasting connects on jobs that are | |
| statistically not worth a proposal. | |
| Eight signals are fully **deterministic** (computed here from the confirmed | |
| job fields). Two signals are **judgment calls** — job-description quality | |
| and niche match — that the match engine computes with the LLM and passes in | |
| via ``job_desc_quality`` / ``niche_match``. When those are not supplied the | |
| evaluator falls back to a safe deterministic heuristic so it still works | |
| offline (and in tests). | |
| The 9 signals (each votes GO / CAUTION / NO GO): | |
| 1. Proposals — <20 GO · 20-50 CAUTION · 50+ NO GO | |
| 2. Hire rate — 50%+ GO · 25-50% CAUTION · <25% NO GO (only for a client | |
| with a track record) · not visible CAUTION · new client GO | |
| 3. Payment — verified GO · not verified NO GO · no data CAUTION | |
| 4. Client rating — 4.8+ GO · 4.5-4.8 CAUTION · <4.5 NO GO · no rating CAUTION | |
| 5. Job desc. — clear scope GO · everything else CAUTION (never NO GO) | |
| 6. Time posted — <2h GO · 2-6h CAUTION · 6h+ NO GO · no data CAUTION | |
| 7. Experience — Entry GO · Intermediate CAUTION · Expert NO GO | |
| 8. Contract type — fixed + clear GO · hourly/vague CAUTION | |
| 9. Client activity— consistent hiring GO · mixed CAUTION · zero hires NO GO | |
| Niche match (job vs the freelancer's offer) is a separate, non-blocking | |
| **note** — FULL / PARTIAL / NONE — never counted in the GO/CAUTION/NO-GO | |
| totals. | |
| The overall result is the *worst* signal: any NO GO → "Not recommended" | |
| (``Do Not Proceed``); else any CAUTION → "Proceed with caution" | |
| (``Proceed With Caution``); else "Strong opportunity" (``Apply Confidently``). | |
| A field that is not legible is recorded and, where the spec allows, simply | |
| lowers confidence rather than inventing a verdict. | |
| """ | |
| from __future__ import annotations | |
| import re | |
| from datetime import date | |
| from typing import Any, Optional | |
| NOT_VISIBLE = "Not visible" | |
| # Result vocabulary (kept stable for the scoring + recommendation layers). | |
| APPLY_CONFIDENTLY = "Apply Confidently" | |
| PROCEED_WITH_CAUTION = "Proceed With Caution" | |
| DO_NOT_PROCEED = "Do Not Proceed" | |
| # Status tokens shown in the output table. | |
| GO = "GO" | |
| CAUTION = "CAUTION" | |
| NO_GO = "NO GO" | |
| # Map a worst-signal status to the internal result + the recommendation line. | |
| _STATUS_TO_RESULT = {GO: APPLY_CONFIDENTLY, CAUTION: PROCEED_WITH_CAUTION, NO_GO: DO_NOT_PROCEED} | |
| # --- User-facing reason strings ------------------------------------------- | |
| # NO GO reasons. | |
| REASON_PROPOSALS_50_PLUS = ( | |
| "This job already has 50 or more proposals, so competition is too high " | |
| "for a beginner profile." | |
| ) | |
| REASON_HIRE_RATE_LOW = ( | |
| "The client has posted several jobs but hires for fewer than 1 in 4, so " | |
| "they rarely hire — a high risk of wasted connects." | |
| ) | |
| REASON_PAYMENT_NOT_VERIFIED = ( | |
| "Payment is not verified, so there is a higher risk of not getting paid." | |
| ) | |
| REASON_RATING_LOW = ( | |
| "The client's rating is below 4.5, so they may be difficult to satisfy." | |
| ) | |
| REASON_POSTED_STALE = ( | |
| "This job was posted more than 6 hours ago, so the client may already be " | |
| "reviewing other freelancers." | |
| ) | |
| REASON_EXPERT_LEVEL = ( | |
| "This job is marked Expert level, so a beginner profile will likely be " | |
| "screened out." | |
| ) | |
| REASON_ACTIVITY_DEAD = ( | |
| "The client has posted jobs but made no hires, so they may not actually " | |
| "hire anyone." | |
| ) | |
| # CAUTION reasons. | |
| WARN_PROPOSALS_20_49 = ( | |
| "Competition is moderate (20-50 proposals), so the proposal must be very strong." | |
| ) | |
| WARN_HIRE_RATE_MID = "The client's hire rate is 25-50%, so a hire is not guaranteed." | |
| # A hire rate that could not be read is unknown, not low: it is checked by the | |
| # user, never held against the client. | |
| WARN_HIRE_RATE_UNKNOWN = ( | |
| "The client's hire rate was not visible in the screenshot. Check it in the " | |
| "'About the client' box on Upwork before applying." | |
| ) | |
| WARN_HIRE_RATE_LOW_UNPROVEN = ( | |
| "The hire rate looks low, but the client's job history was not visible. " | |
| "Check how many jobs they have posted before applying." | |
| ) | |
| WARN_ACTIVITY_UNPROVEN = ( | |
| "The client shows no hires yet, but their job history was not visible. " | |
| "Check how many jobs they have posted before applying." | |
| ) | |
| WARN_PAYMENT_UNKNOWN = "Payment verification was not visible, so confirm it before applying." | |
| WARN_RATING_MID = ( | |
| "The client's rating is 4.5-4.8 — read the past reviews carefully before applying." | |
| ) | |
| WARN_RATING_NONE = "The client has no rating yet, so there is no track record to judge." | |
| WARN_DESC_VAGUE = ( | |
| "The job description is vague or bundles several tasks, so scope the proposal carefully." | |
| ) | |
| WARN_POSTED_RECENT = "This job was posted 2-6 hours ago, so apply quickly while it is still fresh." | |
| WARN_POSTED_UNKNOWN = "The posting time was not visible, so you may not be early." | |
| WARN_INTERMEDIATE = ( | |
| "This job is Intermediate level, so lead with strong, directly relevant proof." | |
| ) | |
| WARN_CONTRACT_HOURLY = "This is an hourly/ongoing role, so set clear expectations up front." | |
| WARN_CONTRACT_VAGUE = "Fixed price with vague scope — pin down the deliverable before committing." | |
| WARN_ACTIVITY_MIXED = "The client's hiring history is mixed, so vet them before spending connects." | |
| WARN_ACTIVITY_UNKNOWN = "The client's hiring activity was not visible." | |
| # Friendly labels for the fields that, when missing, lower confidence. | |
| _FIELD_LABELS: dict[str, str] = { | |
| "payment_verification": "payment verification", | |
| "proposal_count": "proposal count", | |
| "hire_rate": "hire rate", | |
| "client_rating": "client rating", | |
| "posted_date": "posted time", | |
| "experience_level": "experience level", | |
| "contract_type": "contract type", | |
| "client_activity": "client activity", | |
| } | |
| # --------------------------------------------------------------------------- | |
| # Field access helpers | |
| # --------------------------------------------------------------------------- | |
| def _value(confirmed_job: dict, *keys: str) -> str: | |
| for key in keys: | |
| entry = (confirmed_job or {}).get(key) | |
| if isinstance(entry, dict): | |
| value = str(entry.get("value", "") or "").strip() | |
| else: | |
| value = str(entry or "").strip() | |
| if not _is_missing(value): | |
| return value | |
| return "" | |
| def _is_missing(value: Optional[str]) -> bool: | |
| if value is None: | |
| return True | |
| v = value.strip() | |
| return not v or v.lower() == NOT_VISIBLE.lower() | |
| def _ints(value: str) -> list[int]: | |
| return [int(tok) for tok in re.findall(r"\d+", value.replace(",", ""))] | |
| def _first_float(value: str) -> Optional[float]: | |
| match = re.search(r"\d+(?:\.\d+)?", value.replace(",", "")) | |
| if not match: | |
| return None | |
| try: | |
| return float(match.group(0)) | |
| except ValueError: | |
| return None | |
| # --------------------------------------------------------------------------- | |
| # Field parsers — each returns a stable bucket; never guesses on missing data | |
| # --------------------------------------------------------------------------- | |
| def _payment_status(value: str) -> str: | |
| """``"verified"`` | ``"not_verified"`` | ``"not_visible"``.""" | |
| if _is_missing(value): | |
| return "not_visible" | |
| low = value.lower() | |
| negative = ( | |
| "not verified", "not_verified", "unverified", "no payment", | |
| "payment not", "not confirmed", "billing not", | |
| ) | |
| if any(marker in low for marker in negative): | |
| return "not_verified" | |
| if low in {"no", "n", "false", "unverified"}: | |
| return "not_verified" | |
| if "verified" in low or "verify" in low or low in {"yes", "y", "true"}: | |
| return "verified" | |
| return "not_visible" | |
| def _proposal_count(value: str) -> Optional[int]: | |
| if _is_missing(value): | |
| return None | |
| ints = _ints(value) | |
| if not ints: | |
| return None | |
| low = value.lower() | |
| if any(p in low for p in ("less than", "fewer than", "under", "below")): | |
| return max(min(ints) - 1, 0) | |
| return ints[0] | |
| def _proposal_bucket(count: Optional[int]) -> str: | |
| """``"low"`` (<20) | ``"high"`` (20-49) | ``"too_high"`` (50+) | ``"not_visible"``.""" | |
| if count is None: | |
| return "not_visible" | |
| if count >= 50: | |
| return "too_high" | |
| if count >= 20: | |
| return "high" | |
| return "low" | |
| def _hire_rate(value: str) -> Optional[float]: | |
| if _is_missing(value): | |
| return None | |
| low = value.lower() | |
| if any(p in low for p in ("no hire", "not rated", "new client", "n/a")): | |
| return None | |
| m = re.search(r"(\d+(?:\.\d+)?)\s*%", value) | |
| if m: | |
| try: | |
| rate = float(m.group(1)) | |
| except ValueError: | |
| return None | |
| else: | |
| rate = _first_float(value) | |
| if rate is None: | |
| return None | |
| if rate < 0 or rate > 100: | |
| return None | |
| return rate | |
| def _hire_rate_bucket(rate: Optional[float]) -> str: | |
| """``"low"`` (<25) | ``"mid"`` (25-49) | ``"high"`` (50+) | ``"not_visible"``.""" | |
| if rate is None: | |
| return "not_visible" | |
| if rate < 25: | |
| return "low" | |
| if rate < 50: | |
| return "mid" | |
| return "high" | |
| def _posted_age_hours(value: str, today: Optional[date] = None) -> Optional[float]: | |
| if _is_missing(value): | |
| return None | |
| low = value.lower() | |
| if any(m in low for m in ( | |
| "just now", "moments ago", "seconds ago", "less than a minute", | |
| "a minute ago", "minute ago", | |
| )): | |
| return 0.0 | |
| m = re.search(r"(\d+)\s*min", low) | |
| if m: | |
| return int(m.group(1)) / 60.0 | |
| if any(p in low for p in ("less than an hour", "under an hour", "<1 hour", "<1 hr")): | |
| return 0.5 | |
| # Counts before the one-unit phrases: "11 hours ago" contains "1 hour" | |
| # and "21 days ago" contains "1 day". | |
| m = re.search(r"(\d+)\s*hour", low) or re.search(r"(\d+)\s*hr", low) | |
| if m: | |
| return float(int(m.group(1))) | |
| if any(p in low for p in ("an hour ago", "a hour ago", "1 hour", "an hr", "1 hr")): | |
| return 1.0 | |
| if any(p in low for p in ("few hours", "couple hours", "couple of hours", "several hours")): | |
| return 4.0 | |
| m = re.search(r"(\d+)\s*day", low) | |
| if m: | |
| return int(m.group(1)) * 24.0 | |
| if "yesterday" in low or "a day ago" in low or "1 day" in low: | |
| return 24.0 | |
| m = re.search(r"(\d+)\s*week", low) | |
| if m: | |
| return int(m.group(1)) * 7 * 24.0 | |
| if "last week" in low or "a week ago" in low or "1 week" in low: | |
| return 7 * 24.0 | |
| m = re.search(r"(\d+)\s*month", low) | |
| if m: | |
| return int(m.group(1)) * 30 * 24.0 | |
| if "last month" in low or "a month ago" in low or "1 month" in low: | |
| return 30 * 24.0 | |
| days = _absolute_age_days(value, today) | |
| return None if days is None else days * 24.0 | |
| def _absolute_age_days(value: str, today: Optional[date]) -> Optional[int]: | |
| reference = today or _today() | |
| if reference is None: | |
| return None | |
| for fmt in ("%b %d, %Y", "%B %d, %Y", "%Y-%m-%d", "%m/%d/%Y", "%d %b %Y", "%d %B %Y"): | |
| try: | |
| parsed = _strptime_date(value.strip(), fmt) | |
| except ValueError: | |
| continue | |
| if parsed is None: | |
| continue | |
| return max((reference - parsed).days, 0) | |
| return None | |
| def _today() -> Optional[date]: | |
| try: | |
| return date.today() | |
| except Exception: # pragma: no cover - defensive only | |
| return None | |
| def _strptime_date(value: str, fmt: str) -> Optional[date]: | |
| from datetime import datetime | |
| return datetime.strptime(value, fmt).date() | |
| def _posted_bucket(age_hours: Optional[float]) -> str: | |
| """``"fresh"`` (<2h) | ``"recent"`` (2-6h) | ``"stale"`` (6h+) | ``"not_visible"``.""" | |
| if age_hours is None: | |
| return "not_visible" | |
| if age_hours < 2: | |
| return "fresh" | |
| if age_hours < 6: | |
| return "recent" | |
| return "stale" | |
| def _rating(value: str) -> Optional[float]: | |
| if _is_missing(value): | |
| return None | |
| low = value.lower() | |
| if any(p in low for p in ("no review", "no rating", "not rated", "new client", "no feedback")): | |
| return None | |
| if re.search(r"(?<![\d.])0\s*reviews?\b", low): | |
| return None | |
| # The rating is the first number up to 5 that is not a review count, so | |
| # "4.8 of 12 reviews" and "(12 reviews) 4.8" both read 4.8. Upwork stars | |
| # run from 1 to 5: a 0 ("0.0 of 0 reviews") means no rating yet. | |
| for m in re.finditer(r"(\d+(?:\.\d+)?)(\s*reviews?\b)?", low.replace(",", "")): | |
| if m.group(2): | |
| continue | |
| r = float(m.group(1)) | |
| if r <= 5: | |
| return r if r > 0 else None | |
| return None | |
| def _rating_bucket(rating: Optional[float]) -> str: | |
| """``"low"`` (<4.5) | ``"mid"`` (4.5-4.79) | ``"high"`` (4.8+) | ``"not_visible"``.""" | |
| if rating is None: | |
| return "not_visible" | |
| if rating < 4.5: | |
| return "low" | |
| if rating < 4.8: | |
| return "mid" | |
| return "high" | |
| def _experience_level(value: str) -> str: | |
| """``"entry"`` | ``"intermediate"`` | ``"expert"`` | ``"other"`` | ``"not_visible"``.""" | |
| if _is_missing(value): | |
| return "not_visible" | |
| low = value.lower() | |
| if "expert" in low: | |
| return "expert" | |
| if "intermediate" in low: | |
| return "intermediate" | |
| if "entry" in low or "beginner" in low: | |
| return "entry" | |
| return "other" | |
| def _contract_type(value: str) -> str: | |
| """``"fixed"`` | ``"hourly"`` | ``"not_visible"``.""" | |
| if _is_missing(value): | |
| return "not_visible" | |
| low = value.lower() | |
| if "hour" in low: | |
| return "hourly" | |
| if "fixed" in low: | |
| return "fixed" | |
| return "not_visible" | |
| # A client with fewer than this many jobs posted is treated as "new". A new | |
| # client naturally has little/no hire rate, rating, or history — that is normal | |
| # and is NOT a red flag. New clients are often the best odds for a beginner, so | |
| # we do not penalise the absence of a track record for them. (An *established* | |
| # client who has posted many jobs but still made no hires IS a red flag.) | |
| _NEW_CLIENT_JOB_LIMIT = 5 | |
| REASON_NEW_CLIENT = ( | |
| "New client with little history yet — normal, and often good odds for a beginner." | |
| ) | |
| def _jobs_posted(jobs: Optional[int], hires: Optional[int], hire_rate: Optional[float]) -> Optional[float]: | |
| """Jobs the client has posted: the visible count, else an estimate. | |
| When the count isn't visible but a hire rate above zero and at least one | |
| hire are, it is about hires * 100 / rate (an 8% rate with 4 hires is about | |
| 50 jobs). A hires count on its own is never used: it may be the "Hires: 0" | |
| Upwork shows for this one open post, and a client with a few hires may | |
| still have posted many jobs. | |
| """ | |
| if jobs is not None: | |
| return float(jobs) | |
| if hires and hire_rate: | |
| return hires * 100.0 / hire_rate | |
| return None | |
| def _is_new_client(jobs: Optional[int], hires: Optional[int], hire_rate: Optional[float] = None) -> bool: | |
| """True when the client is new enough that a thin track record is expected. | |
| Based on jobs posted (the clearest signal), seen or worked out from a | |
| visible hire rate and hires count. Returns False when we have no positive | |
| evidence of newness, so an unknown client is checked rather than waved | |
| through and an established-but-non-hiring client is still flagged. | |
| """ | |
| posted = _jobs_posted(jobs, hires, hire_rate) | |
| return posted is not None and posted < _NEW_CLIENT_JOB_LIMIT | |
| def _client_activity_bucket(jobs: Optional[int], hires: Optional[int], hire_rate: Optional[float]) -> str: | |
| """``"consistent"`` | ``"mixed"`` | ``"dead"`` | ``"not_visible"``. | |
| * Zero hires across one or more posted jobs (or a 0% hire rate) → dead. | |
| * A healthy hire ratio (>=50%) → consistent. | |
| * Anything in between, or only partial data → mixed. | |
| """ | |
| if hires is None and jobs is None and hire_rate is None: | |
| return "not_visible" | |
| # A visible hire rate above zero outranks a hires count of 0: that 0 is | |
| # most likely the "Hires: 0" Upwork shows for this one open post. | |
| if hire_rate is not None and hire_rate > 0: | |
| return "consistent" if hire_rate >= 50 else "mixed" | |
| # Explicit "posted jobs, hired no one" signal. | |
| if hires == 0 and ((jobs or 0) >= 1 or (hire_rate is not None and hire_rate == 0)): | |
| return "dead" | |
| if hire_rate is not None and hire_rate == 0: | |
| return "dead" | |
| if jobs and hires is not None: | |
| ratio = hires / jobs if jobs else 0.0 | |
| if ratio >= 0.5 and hires >= 1: | |
| return "consistent" | |
| if hires >= 1: | |
| return "mixed" | |
| return "dead" | |
| if hire_rate is not None: | |
| return "consistent" if hire_rate >= 50 else "mixed" | |
| if hires and hires >= 1: | |
| return "consistent" | |
| return "mixed" | |
| def _desc_quality_heuristic(confirmed_job: dict) -> str: | |
| """Deterministic fallback for Signal 5 — returns ``GO`` or ``CAUTION``. | |
| Used only when the LLM job-description-quality signal is not supplied. | |
| A description is treated as clear (GO) when it is reasonably detailed | |
| and a deliverable + budget are present; otherwise CAUTION. Never NO GO. | |
| """ | |
| desc = _value(confirmed_job, "job_description", "client_need") | |
| deliverable = _value(confirmed_job, "required_deliverables") | |
| budget = _value(confirmed_job, "budget_or_rate") | |
| if not desc: | |
| return CAUTION | |
| words = len(desc.split()) | |
| if words >= 25 and (deliverable or budget): | |
| return GO | |
| return CAUTION | |
| # --------------------------------------------------------------------------- | |
| # Public API | |
| # --------------------------------------------------------------------------- | |
| def evaluate( | |
| confirmed_job: dict, | |
| *, | |
| today: Optional[date] = None, | |
| job_desc_quality: Optional[dict] = None, | |
| niche_match: Optional[dict] = None, | |
| ) -> dict[str, Any]: | |
| """Run the 10-signal checklist over one confirmed opportunity. | |
| ``job_desc_quality`` (optional) is the LLM judgment for Signal 5: | |
| ``{"status": "GO"|"CAUTION", "data": str}``. ``niche_match`` (optional) | |
| is the LLM niche assessment: ``{"status": "FULL"|"PARTIAL"|"NONE", | |
| "note": str}``. Both are computed by :mod:`app.services.match_engine` | |
| when an API key is available; safe deterministic fallbacks run otherwise. | |
| Returns a plain dict carrying the per-signal table (``signals``), the | |
| GO/CAUTION/NO-GO counts, the recommendation line, the niche-match note, | |
| plus the legacy fields (``result``, ``instant_no``, ``reasons``, | |
| ``warnings``, ``score_signals``, ``fields`` …) the rest of the app reads. | |
| Never raises on missing or malformed fields. | |
| """ | |
| confirmed_job = confirmed_job or {} | |
| # --- Parse every field once --------------------------------------- | |
| payment_value = _value(confirmed_job, "payment_verification") | |
| proposal_value = _value(confirmed_job, "proposal_count") | |
| hire_value = _value(confirmed_job, "hire_rate") | |
| rating_value = _value(confirmed_job, "client_rating") | |
| posted_value = _value(confirmed_job, "posted_date", "posted_age") | |
| experience_value = _value(confirmed_job, "experience_level") | |
| contract_value = _value(confirmed_job, "contract_type", "project_type") | |
| jobs_value = _value(confirmed_job, "client_jobs_posted") | |
| hires_value = _value(confirmed_job, "client_hires") | |
| last_active_value = _value(confirmed_job, "client_last_active") | |
| payment = _payment_status(payment_value) | |
| count = _proposal_count(proposal_value) | |
| proposal_b = _proposal_bucket(count) | |
| hire = _hire_rate(hire_value) | |
| rating = _rating(rating_value) | |
| rating_b = _rating_bucket(rating) | |
| age_hours = _posted_age_hours(posted_value, today=today) | |
| posted_b = _posted_bucket(age_hours) | |
| experience = _experience_level(experience_value) | |
| contract = _contract_type(contract_value) | |
| jobs_n = (_ints(jobs_value)[0] if _ints(jobs_value) else None) | |
| hires_n = (_ints(hires_value)[0] if _ints(hires_value) else None) | |
| # If the hire-rate % isn't shown but both the client's jobs posted and | |
| # total hires are, the rate can be worked out from them. Both counts are | |
| # needed: a hires count on its own may be the "Hires: 0" that Upwork shows | |
| # for this one open post, which says nothing about the client. | |
| if hire is None and hires_n is not None and jobs_n: | |
| hire = min(100.0, 100.0 * hires_n / jobs_n) | |
| if _is_missing(hire_value): | |
| hire_value = f"{round(hire)}% ({hires_n} hires from {jobs_n} jobs)" | |
| hire_b = _hire_rate_bucket(hire) | |
| activity_b = _client_activity_bucket(jobs_n, hires_n, hire) | |
| new_client = _is_new_client(jobs_n, hires_n, hire) | |
| # A low hire rate only means something once the client has a real record: | |
| # enough jobs posted (seen, or worked out from the hire rate) or, failing | |
| # that, enough hires to judge them by. Without that evidence, low or | |
| # missing numbers are a reason to check, never a reason to skip the job. | |
| has_history = not new_client and ( | |
| _jobs_posted(jobs_n, hires_n, hire) is not None | |
| or (hires_n or 0) >= _NEW_CLIENT_JOB_LIMIT | |
| ) | |
| # Signal 5 — job description quality (LLM if supplied, else heuristic). | |
| if isinstance(job_desc_quality, dict) and job_desc_quality.get("status") in (GO, CAUTION): | |
| desc_status = job_desc_quality["status"] | |
| desc_data = str(job_desc_quality.get("data") or "").strip() or ( | |
| "Clear scope" if desc_status == GO else "Vague / bundled scope" | |
| ) | |
| else: | |
| desc_status = _desc_quality_heuristic(confirmed_job) | |
| desc_data = "Clear scope, deliverable present" if desc_status == GO else "Vague or thin description" | |
| # --- Build the 10 signal rows ------------------------------------- | |
| rows: list[dict[str, Any]] = [] | |
| def add(key, label, data, status, reason=""): | |
| rows.append({"key": key, "label": label, "data": data, "status": status, "reason": reason}) | |
| # 1 — Proposals | |
| if proposal_b == "too_high": | |
| add("proposals", "Proposals", proposal_value or NOT_VISIBLE, NO_GO, REASON_PROPOSALS_50_PLUS) | |
| elif proposal_b == "high": | |
| add("proposals", "Proposals", proposal_value, CAUTION, WARN_PROPOSALS_20_49) | |
| elif proposal_b == "low": | |
| add("proposals", "Proposals", proposal_value, GO) | |
| else: | |
| add("proposals", "Proposals", NOT_VISIBLE, CAUTION, "Proposal count was not visible.") | |
| # 2 — Hire rate. A low hire rate is a NO GO only for a client with a real | |
| # track record. For a NEW client (few jobs posted) it is expected and fine — | |
| # beginners often win work from new clients. A rate that was not visible, | |
| # or a low rate with no visible history, is a CAUTION: check it on Upwork. | |
| if hire_b == "high": | |
| add("hire_rate", "Hire Rate", hire_value, GO) | |
| elif hire_b == "mid": | |
| add("hire_rate", "Hire Rate", hire_value, CAUTION, WARN_HIRE_RATE_MID) | |
| elif new_client: | |
| add("hire_rate", "Hire Rate", (hire_value or NOT_VISIBLE) + " — new client", GO, | |
| "") | |
| elif hire_b == "low" and has_history: | |
| add("hire_rate", "Hire Rate", hire_value, NO_GO, REASON_HIRE_RATE_LOW) | |
| elif hire_b == "low": | |
| add("hire_rate", "Hire Rate", hire_value, CAUTION, WARN_HIRE_RATE_LOW_UNPROVEN) | |
| else: | |
| add("hire_rate", "Hire Rate", NOT_VISIBLE, CAUTION, WARN_HIRE_RATE_UNKNOWN) | |
| # 3 — Payment verified | |
| if payment == "verified": | |
| add("payment", "Payment Verified", payment_value, GO) | |
| elif payment == "not_verified": | |
| add("payment", "Payment Verified", payment_value, NO_GO, REASON_PAYMENT_NOT_VERIFIED) | |
| else: | |
| add("payment", "Payment Verified", NOT_VISIBLE, CAUTION, WARN_PAYMENT_UNKNOWN) | |
| # 4 — Client rating. No rating is normal for a NEW client (no reviews yet) → | |
| # don't flag it. An ESTABLISHED client with no rating stays a soft caution. | |
| # An explicit low rating (<4.5) is always a NO GO, new or not. | |
| if rating_b == "high": | |
| add("client_rating", "Client Rating", rating_value, GO) | |
| elif rating_b == "mid": | |
| add("client_rating", "Client Rating", rating_value, CAUTION, WARN_RATING_MID) | |
| elif rating_b == "low": | |
| add("client_rating", "Client Rating", rating_value, NO_GO, REASON_RATING_LOW) | |
| elif new_client: | |
| add("client_rating", "Client Rating", "No reviews yet — new client", GO, "") | |
| else: | |
| add("client_rating", "Client Rating", NOT_VISIBLE, CAUTION, WARN_RATING_NONE) | |
| # 5 — Job description quality (GO or CAUTION only) | |
| add( | |
| "job_description", "Job Description", desc_data, desc_status, | |
| "" if desc_status == GO else WARN_DESC_VAGUE, | |
| ) | |
| # 6 — Time since posted | |
| if posted_b == "fresh": | |
| add("posted", "Time Since Posted", posted_value, GO) | |
| elif posted_b == "recent": | |
| add("posted", "Time Since Posted", posted_value, CAUTION, WARN_POSTED_RECENT) | |
| elif posted_b == "stale": | |
| add("posted", "Time Since Posted", posted_value, NO_GO, REASON_POSTED_STALE) | |
| else: | |
| add("posted", "Time Since Posted", NOT_VISIBLE, CAUTION, WARN_POSTED_UNKNOWN) | |
| # 7 — Experience level | |
| if experience == "entry": | |
| add("experience", "Experience Level", experience_value, GO) | |
| elif experience == "intermediate": | |
| add("experience", "Experience Level", experience_value, CAUTION, WARN_INTERMEDIATE) | |
| elif experience == "expert": | |
| add("experience", "Experience Level", experience_value, NO_GO, REASON_EXPERT_LEVEL) | |
| else: | |
| add("experience", "Experience Level", experience_value or NOT_VISIBLE, CAUTION, | |
| "Experience level was not clearly shown.") | |
| # 8 — Contract type (depends on desc clarity for fixed-price) | |
| if contract == "fixed": | |
| if desc_status == GO: | |
| add("contract_type", "Contract Type", contract_value, GO) | |
| else: | |
| add("contract_type", "Contract Type", contract_value, CAUTION, WARN_CONTRACT_VAGUE) | |
| elif contract == "hourly": | |
| add("contract_type", "Contract Type", contract_value, CAUTION, WARN_CONTRACT_HOURLY) | |
| else: | |
| add("contract_type", "Contract Type", contract_value or NOT_VISIBLE, CAUTION, | |
| "Contract type was not visible.") | |
| # 9 — Client activity. "No hires" is a NO GO for an ESTABLISHED client | |
| # (posts many jobs, never hires), but for a NEW client it's expected and is | |
| # actually a good opening for a beginner — so a new client is never flagged | |
| # down here on the basis of a thin history. | |
| data = _activity_data(jobs_value, hires_value, last_active_value) | |
| if activity_b == "consistent": | |
| add("client_activity", "Client Activity", data, GO) | |
| elif new_client and activity_b in ("dead", "mixed"): | |
| add("client_activity", "Client Activity", | |
| (data if data != NOT_VISIBLE else "New client") + " — new client", GO, "") | |
| elif activity_b == "mixed": | |
| add("client_activity", "Client Activity", data, CAUTION, WARN_ACTIVITY_MIXED) | |
| elif activity_b == "dead" and has_history: | |
| add("client_activity", "Client Activity", data, NO_GO, REASON_ACTIVITY_DEAD) | |
| elif activity_b == "dead": | |
| add("client_activity", "Client Activity", data, CAUTION, WARN_ACTIVITY_UNPROVEN) | |
| else: | |
| add("client_activity", "Client Activity", NOT_VISIBLE, CAUTION, WARN_ACTIVITY_UNKNOWN) | |
| # --- Niche match (separate note row, never counted) --------------- | |
| niche = _normalize_niche(niche_match) | |
| # --- Aggregate ---------------------------------------------------- | |
| go_count = sum(1 for r in rows if r["status"] == GO) | |
| caution_count = sum(1 for r in rows if r["status"] == CAUTION) | |
| nogo_count = sum(1 for r in rows if r["status"] == NO_GO) | |
| if nogo_count: | |
| worst = NO_GO | |
| elif caution_count: | |
| worst = CAUTION | |
| else: | |
| worst = GO | |
| result = _STATUS_TO_RESULT[worst] | |
| instant_no = worst == NO_GO | |
| nogo_reasons = [r["reason"] for r in rows if r["status"] == NO_GO and r["reason"]] | |
| caution_reasons = [r["reason"] for r in rows if r["status"] == CAUTION and r["reason"]] | |
| warnings = [ | |
| {"key": _warn_key(r["key"]), "reason": r["reason"]} | |
| for r in rows | |
| if r["status"] == CAUTION and r["reason"] | |
| ] | |
| if worst == NO_GO: | |
| reasons = nogo_reasons[:2] | |
| triggered_rule = "do_not_proceed:" + next( | |
| (r["key"] for r in rows if r["status"] == NO_GO), "unknown" | |
| ) | |
| recommendation_line = "Not recommended — " + _join_signal_names(rows, NO_GO) + ". Consider skipping this one." | |
| elif worst == CAUTION: | |
| reasons = caution_reasons[:2] | |
| triggered_rule = "proceed_with_caution:" + _warn_key( | |
| next((r["key"] for r in rows if r["status"] == CAUTION), "unknown") | |
| ) | |
| recommendation_line = "Proceed with caution — watch " + _join_signal_names(rows, CAUTION) + "." | |
| else: | |
| reasons = ["Every signal is a GO — strong opportunity, proceed to proposal."] | |
| triggered_rule = "apply_confidently:all_conditions_met" | |
| recommendation_line = "Strong opportunity — proceed to proposal." | |
| # --- Missing-info / confidence ------------------------------------ | |
| missing_fields: list[str] = [] | |
| if payment == "not_visible": | |
| missing_fields.append("payment_verification") | |
| if proposal_b == "not_visible": | |
| missing_fields.append("proposal_count") | |
| # For a new client, a blank hire rate / rating is expected, not "missing | |
| # info" worth flagging — so don't add them when the client is new. | |
| if hire_b == "not_visible" and not new_client: | |
| missing_fields.append("hire_rate") | |
| if rating_b == "not_visible" and not new_client: | |
| missing_fields.append("client_rating") | |
| if posted_b == "not_visible": | |
| missing_fields.append("posted_date") | |
| if experience in ("not_visible", "other"): | |
| missing_fields.append("experience_level") | |
| if contract == "not_visible": | |
| missing_fields.append("contract_type") | |
| if activity_b == "not_visible": | |
| missing_fields.append("client_activity") | |
| reduce_confidence = bool(missing_fields) | |
| missing_info_note: Optional[str] = None | |
| if missing_fields: | |
| labels = ", ".join(_FIELD_LABELS.get(f, f) for f in missing_fields) | |
| missing_info_note = ( | |
| f"Could not confirm: {labels}. Treating this recommendation with extra caution." | |
| ) | |
| score_signals = { | |
| "payment_not_verified": payment == "not_verified", | |
| # Only a visible low rate from a client with a track record counts | |
| # against them; a blank rate, or a new client's low one, does not. | |
| "hire_rate_below_25": hire_b == "low" and has_history, | |
| "hire_rate_unknown": hire_b == "not_visible" and not new_client, | |
| "hire_rate_mid": hire_b == "mid", | |
| "hire_rate_high": hire_b == "high", | |
| "rating_below_4_5": rating_b == "low", | |
| "rating_mid": rating_b == "mid", | |
| "rating_high": rating_b == "high", | |
| "proposals_50_plus": proposal_b == "too_high", | |
| "proposals_20_49": proposal_b == "high", | |
| "proposals_under_20": proposal_b == "low", | |
| "posted_fresh": posted_b == "fresh", | |
| "posted_recent": posted_b == "recent", | |
| "posted_stale": posted_b == "stale", | |
| "expert_level": experience == "expert", | |
| "intermediate_level": experience == "intermediate", | |
| } | |
| fields = { | |
| "payment_verification": {"value": payment_value or NOT_VISIBLE, "result": payment}, | |
| "proposal_count": {"value": proposal_value or NOT_VISIBLE, "count": count, "bucket": proposal_b}, | |
| "hire_rate": {"value": hire_value or NOT_VISIBLE, "rate": hire, "bucket": hire_b, | |
| "warning": hire_b in ("low", "mid", "not_visible")}, | |
| "client_rating": {"value": rating_value or NOT_VISIBLE, "rating": rating, "bucket": rating_b, | |
| "warning": rating_b in ("low", "mid")}, | |
| "posted_age": {"value": posted_value or NOT_VISIBLE, "age_hours": age_hours, | |
| "age_days": None if age_hours is None else round(age_hours / 24.0, 2), | |
| "bucket": posted_b}, | |
| "experience_level": {"value": experience_value or NOT_VISIBLE, "level": experience, | |
| "warning": experience in ("expert", "intermediate")}, | |
| "contract_type": {"value": contract_value or NOT_VISIBLE, "type": contract}, | |
| "client_activity": {"value": _activity_data(jobs_value, hires_value, last_active_value), | |
| "jobs": jobs_n, "hires": hires_n, "bucket": activity_b}, | |
| "job_description": {"value": desc_data, "status": desc_status}, | |
| } | |
| return { | |
| # New table-oriented output (Instruction Set 1, Step 5). | |
| "signals": rows, | |
| "go_count": go_count, | |
| "caution_count": caution_count, | |
| "nogo_count": nogo_count, | |
| "recommendation_line": recommendation_line, | |
| "niche_match": niche, | |
| # Legacy fields consumed by scoring / recommendation / UI. | |
| "result": result, | |
| "instant_no": instant_no, | |
| "reasons": reasons, | |
| "warnings": warnings, | |
| "instant_no_reasons": nogo_reasons, | |
| "fields": fields, | |
| "missing_fields": missing_fields, | |
| "missing_info_note": missing_info_note, | |
| "reduce_confidence": reduce_confidence, | |
| "triggered_rule": triggered_rule, | |
| "score_signals": score_signals, | |
| } | |
| # --------------------------------------------------------------------------- | |
| # Small helpers used by evaluate() | |
| # --------------------------------------------------------------------------- | |
| _SIGNAL_NAMES = { | |
| "proposals": "proposals", "hire_rate": "hire rate", "payment": "payment", | |
| "client_rating": "client rating", "job_description": "job description", | |
| "posted": "time since posted", "experience": "experience level", | |
| "contract_type": "contract type", "client_activity": "client activity", | |
| } | |
| # Map a signal key to the warning key the scoring/recommendation layers expect. | |
| _WARN_KEYS = { | |
| "proposals": "proposals_20_49", | |
| "hire_rate": "hire_rate_25_50", | |
| "client_rating": "client_rating_4_5_to_4_8", | |
| "posted": "posted_2_to_6_hours", | |
| "experience": "intermediate_level", | |
| "payment": "payment_unknown", | |
| "job_description": "job_description_vague", | |
| "contract_type": "contract_type", | |
| "client_activity": "client_activity", | |
| } | |
| def _warn_key(signal_key: str) -> str: | |
| return _WARN_KEYS.get(signal_key, signal_key) | |
| def _join_signal_names(rows: list[dict], status: str) -> str: | |
| names = [_SIGNAL_NAMES.get(r["key"], r["key"]) for r in rows if r["status"] == status] | |
| if not names: | |
| return "the flagged signals" | |
| if len(names) == 1: | |
| return names[0] | |
| return ", ".join(names[:-1]) + " and " + names[-1] | |
| def _activity_data(jobs_value: str, hires_value: str, last_active_value: str) -> str: | |
| parts = [] | |
| if jobs_value: | |
| parts.append(f"{jobs_value} jobs" if "job" not in jobs_value.lower() else jobs_value) | |
| if hires_value: | |
| parts.append(f"{hires_value} hires" if "hire" not in hires_value.lower() else hires_value) | |
| if last_active_value: | |
| parts.append(f"active {last_active_value}") | |
| return ", ".join(parts) if parts else NOT_VISIBLE | |
| def _normalize_niche(niche_match: Optional[dict]) -> dict: | |
| """Normalize the niche-match input to ``{"status", "note"}``. | |
| ``status`` is one of ``"FULL"`` | ``"PARTIAL"`` | ``"NONE"`` | ``None``. | |
| A PARTIAL / NONE status carries the standard non-blocking warning note. | |
| """ | |
| if not isinstance(niche_match, dict): | |
| return {"status": None, "note": ""} | |
| status = str(niche_match.get("status") or "").upper().strip() or None | |
| if status not in {"FULL", "PARTIAL", "NONE"}: | |
| return {"status": None, "note": str(niche_match.get("note") or "")} | |
| note = str(niche_match.get("note") or "").strip() | |
| if not note: | |
| if status == "PARTIAL": | |
| note = ( | |
| "PARTIAL NICHE MATCH: This job touches your skill set but sits " | |
| "outside your core offer. You can apply, but tailor the proposal " | |
| "tightly to the overlapping skills only. Do not claim experience " | |
| "in the parts that don't match." | |
| ) | |
| elif status == "NONE": | |
| note = ( | |
| "NICHE MISMATCH: This job is outside your current offer and skill " | |
| "set. Applying means competing without your core strengths. Proceed " | |
| "only if you are intentionally exploring a different direction — and " | |
| "be honest about your relevant background." | |
| ) | |
| return {"status": status, "note": note} | |