Spaces:
Runtime error
Runtime error
Download src/graph/reasoning.py from Harshilforworks/rag-backend: direct link, hf CLI and curl.
- Browser
- Download file 20.5 kB
-
https://huggingface.co/spaces/Harshilforworks/rag-backend/resolve/main/src/graph/reasoning.py
- Command line
-
hf download hf://spaces/Harshilforworks/rag-backend/src/graph/reasoning.py
-
curl -L -o reasoning.py https://huggingface.co/spaces/Harshilforworks/rag-backend/resolve/main/src/graph/reasoning.py
20.5 kB
| """ | |
| Graph reasoning layer β all prerequisite logic lives here. | |
| Operates on the singleton DiGraph from graph.store. | |
| """ | |
| import re | |
| import networkx as nx | |
| from src.graph.store import get_graph | |
| from src.core.logger import get_logger | |
| log = get_logger(__name__) | |
| _FINANCIAL_AID_SCOPE_RE = re.compile( | |
| r""" | |
| \b(?: | |
| federal\s*student\s*(?:financial|nancial)\s*assistance| | |
| (?:financial|nancial)\s*aid| | |
| federal\s*aid| | |
| federal\s*regulations| | |
| satisfactory\s*academic\s*progress| | |
| (?:financial|nancial)\s*aid\s*(?:warning|probation)| | |
| 67\s*%| | |
| 150\s*%| | |
| \bpace\b | |
| )\b | |
| """, | |
| re.IGNORECASE | re.VERBOSE, | |
| ) | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # Internal helpers | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def _normalize(code: str) -> str: | |
| """Uppercase and strip whitespace so lookups are consistent.""" | |
| return code.strip().upper() | |
| def _predecessors_of(G: nx.DiGraph, course: str) -> list[tuple[str, dict]]: | |
| """Return (prereq_code, edge_attrs) for all direct prerequisites.""" | |
| return [(u, G[u][course]) for u in G.predecessors(course)] | |
| def _grade_ok(grade_received: str, min_grade: str) -> bool: | |
| """ | |
| Simple letter-grade comparison. | |
| Order: A > B > C > D > F | |
| Returns True when grade_received meets or exceeds min_grade. | |
| """ | |
| order = {"A": 5, "B": 4, "C": 3, "D": 2, "F": 1, "": 0} | |
| received = grade_received.strip().upper()[:1] | |
| minimum = min_grade.strip().upper()[:1] | |
| return order.get(received, 0) >= order.get(minimum, 0) | |
| def _coerce_gpa_value(value: object) -> float | None: | |
| """Convert numeric/string GPA to float when possible.""" | |
| if value is None: | |
| return None | |
| if isinstance(value, (int, float)): | |
| return float(value) | |
| if isinstance(value, str): | |
| match = re.search(r"\d(?:\.\d+)?", value) | |
| if match: | |
| try: | |
| return float(match.group(0)) | |
| except ValueError: | |
| return None | |
| return None | |
| def _format_gpa(value: float) -> str: | |
| """Format GPA values consistently for messages.""" | |
| return f"{value:.1f}" | |
| def _normalize_student_level(value: object) -> str: | |
| """Normalize audience level labels used by policy rules.""" | |
| if value is None: | |
| return "" | |
| lowered = str(value).strip().lower() | |
| if lowered.startswith("under"): | |
| return "undergraduate" | |
| if lowered.startswith("grad"): | |
| return "graduate" | |
| return "" | |
| def _normalize_policy_scope(value: object) -> str: | |
| """Normalize policy scope labels used to decide applicability.""" | |
| if value is None: | |
| return "" | |
| lowered = str(value).strip().lower().replace("-", "_").replace(" ", "_") | |
| if lowered in {"financial_aid", "aid", "federal_aid"}: | |
| return "financial_aid" | |
| if lowered in {"general", "enrollment", "academic", "all"}: | |
| return "general" | |
| return "" | |
| def _infer_policy_scope(rule: dict) -> str: | |
| """ | |
| Infer policy scope for backward compatibility with previously ingested data. | |
| Old graph metadata may not include a scope field, so we infer from evidence | |
| text and treat policies as general unless they explicitly mention aid. | |
| """ | |
| explicit = _normalize_policy_scope(rule.get("scope")) | |
| if explicit: | |
| return explicit | |
| evidence_blob = " ".join( | |
| [ | |
| str(rule.get("evidence_text", "") or ""), | |
| str(rule.get("document_name", "") or ""), | |
| ] | |
| ) | |
| if _FINANCIAL_AID_SCOPE_RE.search(evidence_blob): | |
| return "financial_aid" | |
| return "general" | |
| def _filter_policy_requirements( | |
| policy_requirements: list[dict], | |
| include_financial_aid_policies: bool, | |
| ) -> list[dict]: | |
| """Return only policies relevant to the current eligibility context.""" | |
| filtered: list[dict] = [] | |
| for rule in policy_requirements: | |
| scope = _infer_policy_scope(rule) | |
| if scope == "financial_aid" and not include_financial_aid_policies: | |
| continue | |
| normalized_rule = dict(rule) | |
| normalized_rule["scope"] = scope | |
| filtered.append(normalized_rule) | |
| return filtered | |
| def _evaluate_global_gpa_requirements( | |
| policy_requirements: list[dict], | |
| student_gpa: float | None, | |
| student_level: str, | |
| ) -> tuple[list[str], bool, bool, bool]: | |
| """ | |
| Returns (issues, missing_gpa_info, has_hard_violation, missing_level_info). | |
| """ | |
| issues: list[str] = [] | |
| missing_gpa_info = False | |
| has_hard_violation = False | |
| missing_level_info = False | |
| seen_rules: set[tuple[str, float, float | None]] = set() | |
| missing_level_audiences: set[str] = set() | |
| for rule in policy_requirements: | |
| if str(rule.get("type", "")).lower() != "gpa": | |
| continue | |
| audience = _normalize_student_level(rule.get("audience", "all")) | |
| if not audience: | |
| audience = "all" | |
| if audience != "all" and not student_level: | |
| missing_level_audiences.add(audience) | |
| continue | |
| if audience != "all" and audience != student_level: | |
| continue | |
| threshold = _coerce_gpa_value(rule.get("threshold")) | |
| if threshold is None: | |
| continue | |
| operator = str(rule.get("operator", ">=") or ">=") | |
| scale_max = _coerce_gpa_value(rule.get("scale_max")) | |
| dedupe_key = (operator, threshold, scale_max) | |
| if dedupe_key in seen_rules: | |
| continue | |
| seen_rules.add(dedupe_key) | |
| rule_text = f"cumulative GPA {operator} {_format_gpa(threshold)}" | |
| if scale_max is not None: | |
| rule_text += f" on {_format_gpa(scale_max)} scale" | |
| if student_gpa is None: | |
| issues.append(f"Requires {rule_text} - GPA not provided") | |
| missing_gpa_info = True | |
| continue | |
| if operator == ">": | |
| ok = student_gpa > threshold | |
| else: | |
| ok = student_gpa >= threshold | |
| if not ok: | |
| issues.append(f"Requires {rule_text}, got {_format_gpa(student_gpa)}") | |
| has_hard_violation = True | |
| if missing_level_audiences: | |
| ordered = ", ".join(sorted(missing_level_audiences)) | |
| issues.append( | |
| f"GPA policy depends on student level ({ordered}) - student level not provided" | |
| ) | |
| missing_level_info = True | |
| return issues, missing_gpa_info, has_hard_violation, missing_level_info | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| # Public API | |
| # βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| def check_eligibility( | |
| course_code: str, | |
| completed: list[str], | |
| grades: dict[str, str] | None = None, | |
| student_gpa: float | str | None = None, | |
| student_level: str | None = None, | |
| enforce_gpa_policies: bool = True, | |
| include_financial_aid_policies: bool = False, | |
| ) -> dict: | |
| """ | |
| Check whether a student is eligible to enrol in course_code. | |
| By default, GPA policies classified as financial-aid rules are excluded so | |
| non-aid prerequisite checks are not over-constrained. | |
| Returns | |
| ------- | |
| { | |
| "eligible": bool, | |
| "decision": "Eligible" | "Not eligible" | "Need more info", | |
| "missing_prereqs": list[str], | |
| "missing_coreqs": list[str], | |
| "grade_issues": list[str], | |
| "gpa_issues": list[str], | |
| "policy_requirements": list[dict], | |
| "prereq_path": list[str], # full ordered chain | |
| "either_or_options": list[list[str]] | |
| } | |
| """ | |
| G = get_graph() | |
| course = _normalize(course_code) | |
| normalized_grades = grades or {} | |
| gpa_value = _coerce_gpa_value(student_gpa) | |
| level_value = _normalize_student_level(student_level) | |
| completed_set = {_normalize(c) for c in completed} | |
| raw_policy_requirements = ( | |
| list(G.graph.get("global_policy_requirements", [])) if enforce_gpa_policies else [] | |
| ) | |
| policy_requirements = _filter_policy_requirements( | |
| raw_policy_requirements, | |
| include_financial_aid_policies, | |
| ) | |
| result = { | |
| "eligible": False, | |
| "decision": "Need more info", | |
| "missing_prereqs": [], | |
| "missing_coreqs": [], | |
| "grade_issues": [], | |
| "gpa_issues": [], | |
| "prereq_path": [], | |
| "either_or_options": [], | |
| "policy_requirements": policy_requirements, | |
| } | |
| if course not in G: | |
| log.warning(f"Course {course} not found in graph.") | |
| result["decision"] = "Need more info" | |
| return result | |
| missing_prereqs: list[str] = [] | |
| missing_coreqs: list[str] = [] | |
| grade_issues: list[str] = [] | |
| gpa_issues, missing_gpa_info, gpa_hard_violation, missing_level_info = _evaluate_global_gpa_requirements( | |
| policy_requirements, | |
| gpa_value, | |
| level_value, | |
| ) | |
| either_or_options: list[list[str]] = [] | |
| # Group predecessors by requirement_type | |
| required_edges: list[tuple[str, dict]] = [] | |
| either_or_groups: dict[str, dict[str, list[str]]] = {} | |
| coreq_edges: list[tuple[str, dict]] = [] | |
| for prereq, attrs in _predecessors_of(G, course): | |
| req_type = attrs.get("requirement_type", "required") | |
| group = attrs.get("either_or_group", None) | |
| if req_type == "corequisite": | |
| coreq_edges.append((prereq, attrs)) | |
| elif req_type == "either_or" and group: | |
| branch_ids = attrs.get("either_or_branches", []) or [] | |
| if not branch_ids: | |
| single_branch = attrs.get("either_or_branch") | |
| if single_branch: | |
| branch_ids = [single_branch] | |
| if not branch_ids: | |
| # Backward compatibility for previously-ingested edges with no branch metadata. | |
| branch_ids = [prereq] | |
| group_branches = either_or_groups.setdefault(group, {}) | |
| for branch_id in branch_ids: | |
| branch_key = str(branch_id) | |
| group_branches.setdefault(branch_key, []).append(prereq) | |
| else: | |
| required_edges.append((prereq, attrs)) | |
| # ββ Check hard required prereqs ββββββββββββββββββββββββββββββββββββββββββ | |
| for prereq, attrs in required_edges: | |
| min_grade = attrs.get("min_grade", "") | |
| if prereq not in completed_set: | |
| missing_prereqs.append(prereq) | |
| elif min_grade: | |
| received = normalized_grades.get(prereq, "") | |
| if received and not _grade_ok(received, min_grade): | |
| grade_issues.append( | |
| f"{prereq} requires grade {min_grade}, got {received}" | |
| ) | |
| elif not received: | |
| # Grade unknown β flag but don't block | |
| grade_issues.append( | |
| f"{prereq} requires grade {min_grade} β grade not provided" | |
| ) | |
| has_hard_missing_prereqs = bool(missing_prereqs) | |
| # ββ Check either/or groups βββββββββββββββββββββββββββββββββββββββββββββββ | |
| for group_key, branch_map in either_or_groups.items(): | |
| if has_hard_missing_prereqs: | |
| # Defer alternative-group guidance until hard required prerequisites are met. | |
| continue | |
| branch_options: list[list[str]] = [] | |
| for courses in branch_map.values(): | |
| unique_courses: list[str] = [] | |
| for code in courses: | |
| if code not in unique_courses: | |
| unique_courses.append(code) | |
| if unique_courses: | |
| branch_options.append(unique_courses) | |
| if not branch_options: | |
| continue | |
| common_courses = set(branch_options[0]) | |
| for branch in branch_options[1:]: | |
| common_courses &= set(branch) | |
| ordered_common = [code for code in branch_options[0] if code in common_courses] | |
| for code in ordered_common: | |
| if code not in completed_set and code not in missing_prereqs: | |
| missing_prereqs.append(code) | |
| common_satisfied = all(code in completed_set for code in ordered_common) | |
| if not common_satisfied: | |
| # Shared prerequisites are still missing; alternatives are not actionable yet. | |
| continue | |
| reduced_options: list[list[str]] = [] | |
| for branch in branch_options: | |
| reduced = [code for code in branch if code not in common_courses] | |
| if reduced and reduced not in reduced_options: | |
| reduced_options.append(reduced) | |
| # No residual options means the group effectively reduced to shared required courses. | |
| if not reduced_options: | |
| continue | |
| satisfied = any(all(course in completed_set for course in branch) for branch in reduced_options) | |
| if not satisfied: | |
| option_labels: list[str] = [] | |
| for branch in reduced_options: | |
| if len(branch) == 1: | |
| option_labels.append(branch[0]) | |
| else: | |
| option_labels.append(" and ".join(branch)) | |
| if option_labels: | |
| either_or_options.append(option_labels) | |
| # ββ Check coreqs βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| for coreq, attrs in coreq_edges: | |
| if coreq not in completed_set: | |
| # Coreqs can be taken concurrently β flag but handle separately | |
| missing_coreqs.append(coreq) | |
| # ββ Build prereq path ββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| try: | |
| prereq_path = get_full_prereq_chain(course) | |
| except Exception: | |
| prereq_path = [] | |
| result["prereq_path"] = prereq_path | |
| result["missing_prereqs"] = missing_prereqs | |
| result["missing_coreqs"] = missing_coreqs | |
| result["grade_issues"] = grade_issues | |
| result["gpa_issues"] = gpa_issues | |
| result["either_or_options"] = either_or_options | |
| # ββ Final decision βββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| has_missing_either_or = bool(either_or_options) | |
| if not missing_prereqs and not has_missing_either_or and not grade_issues and not gpa_issues: | |
| result["eligible"] = True | |
| result["decision"] = "Eligible" | |
| elif ( | |
| (missing_gpa_info or missing_level_info) | |
| and not missing_prereqs | |
| and not has_missing_either_or | |
| and not grade_issues | |
| and not gpa_hard_violation | |
| ): | |
| result["eligible"] = False | |
| result["decision"] = "Need more info" | |
| elif missing_prereqs or has_missing_either_or: | |
| result["eligible"] = False | |
| result["decision"] = "Not eligible" | |
| else: | |
| # Grade and/or GPA policy issues remain | |
| result["eligible"] = False | |
| result["decision"] = "Not eligible" | |
| return result | |
| def get_full_prereq_chain(course_code: str) -> list[str]: | |
| """ | |
| Return a topologically sorted list of ALL courses that must be | |
| completed before enrolling in course_code (transitive closure). | |
| """ | |
| G = get_graph() | |
| course = _normalize(course_code) | |
| if course not in G: | |
| return [] | |
| # Collect all ancestors | |
| ancestors = nx.ancestors(G, course) | |
| if not ancestors: | |
| return [] | |
| # Build subgraph of just ancestors + target, then topo sort | |
| sub = G.subgraph(ancestors | {course}).copy() | |
| self_loops = list(nx.selfloop_edges(sub)) | |
| if self_loops: | |
| sub.remove_edges_from(self_loops) | |
| log.warning( | |
| f"Ignored {len(self_loops)} self-loop edge(s) while computing prereq chain for {course}" | |
| ) | |
| try: | |
| ordered = list(nx.topological_sort(sub)) | |
| # Remove the target course itself from the chain | |
| return [n for n in ordered if n != course] | |
| except nx.NetworkXUnfeasible: | |
| log.warning(f"Cycle detected in graph while computing prereq chain for {course}") | |
| return sorted(ancestors) | |
| def get_available_next_courses(completed: list[str]) -> list[str]: | |
| """ | |
| Return all courses a student can now enrol in, given their | |
| completed course list (ignoring grade requirements for simplicity). | |
| """ | |
| G = get_graph() | |
| completed_set = {_normalize(c) for c in completed} | |
| available: list[str] = [] | |
| for node in G.nodes(): | |
| if node in completed_set: | |
| continue | |
| preds = list(G.predecessors(node)) | |
| if not preds: | |
| # No prereqs β always available | |
| available.append(node) | |
| continue | |
| # Check if all required prereqs are met (simple version, ignores grades) | |
| result = check_eligibility(node, completed, {}, enforce_gpa_policies=False) | |
| if result["eligible"]: | |
| available.append(node) | |
| return sorted(available) | |
| def find_path_to_course(target_course: str, completed: list[str]) -> dict: | |
| """ | |
| Build a DAG-ready payload for the frontend path visualiser. | |
| Returns | |
| ------- | |
| { | |
| "nodes": [{"id", "label", "credits", "completed": bool}], | |
| "edges": [{"from", "to", "type", "min_grade"}], | |
| "paths": list[list[str]], | |
| "shortest_path": list[str], | |
| "student_completed": list[str] | |
| } | |
| """ | |
| G = get_graph() | |
| target = _normalize(target_course) | |
| comp_set = {_normalize(c) for c in completed} | |
| if target not in G: | |
| return { | |
| "nodes": [], "edges": [], "paths": [], | |
| "shortest_path": [], "student_completed": list(comp_set), | |
| } | |
| ancestors = nx.ancestors(G, target) | {target} | |
| sub = G.subgraph(ancestors) | |
| # Build nodes | |
| nodes = [] | |
| for n in sub.nodes(): | |
| attrs = G.nodes[n] | |
| nodes.append({ | |
| "id": n, | |
| "label": attrs.get("course_name", n), | |
| "credits": attrs.get("credits", 0), | |
| "completed": n in comp_set, | |
| }) | |
| # Build edges | |
| edges = [] | |
| for u, v, attrs in sub.edges(data=True): | |
| edges.append({ | |
| "from": u, | |
| "to": v, | |
| "type": attrs.get("requirement_type", "required"), | |
| "min_grade": attrs.get("min_grade", ""), | |
| }) | |
| # Find all simple paths from any root (no prereqs) to target | |
| roots = [n for n in sub.nodes() if sub.in_degree(n) == 0] | |
| all_paths: list[list[str]] = [] | |
| for root in roots: | |
| try: | |
| for path in nx.all_simple_paths(G, root, target): | |
| all_paths.append(path) | |
| except nx.NetworkXNoPath: | |
| pass | |
| # Shortest path: fewest hops from any completed course or root | |
| shortest: list[str] = [] | |
| if all_paths: | |
| shortest = min(all_paths, key=len) | |
| return { | |
| "nodes": nodes, | |
| "edges": edges, | |
| "paths": all_paths, | |
| "shortest_path": shortest, | |
| "student_completed": list(comp_set), | |
| } |