course-rag-backend / src /agents /crew_runtime.py
Harshilforworks's picture
Src uploaded
3b06b67 verified
Raw History Blame Contribute Delete
21.1 kB
from __future__ import annotations
import asyncio
import os
from typing import Any
from langchain_core.runnables import RunnableLambda, RunnableParallel
try:
from langchain_groq import ChatGroq
except Exception: # pragma: no cover - optional runtime dependency
ChatGroq = None
from src.agents.intake import IntakeAgent
from src.agents.planner import PlannerAgent
from src.agents.retriever_agent import CatalogRetrieverAgent
from src.agents.verifier import VerifierAgent
from src.core.config import settings
from src.core.constants import ABSTENTION_MSG, COURSE_CODE_PAT
from src.core.exceptions import GraphNodeNotFoundError
from src.core.logger import get_logger
from src.graph.reasoning import check_eligibility, get_available_next_courses
log = get_logger(__name__)
# Keep Crew runtime quiet and avoid best-effort telemetry export timeouts in local/dev runs.
os.environ.setdefault("CREWAI_DISABLE_TELEMETRY", "true")
os.environ.setdefault("OTEL_SDK_DISABLED", "true")
os.environ.setdefault("CREWAI_TRACING_ENABLED", "false")
try:
from crewai import Agent as CrewAgent
from crewai import Crew, Process, Task
from crewai import LLM as CrewLLM
from crewai.llm import BaseLLM
except Exception: # pragma: no cover - optional runtime dependency
CrewAgent = None
Crew = None
Process = None
Task = None
CrewLLM = None
BaseLLM = None
class CrewRuntime:
def __init__(
self,
intake_agent: IntakeAgent,
retriever_agent: CatalogRetrieverAgent,
planner_agent: PlannerAgent,
verifier_agent: VerifierAgent,
) -> None:
self._intake = intake_agent
self._retriever = retriever_agent
self._planner = planner_agent
self._verifier = verifier_agent
def _extract_target_course(self, question: str) -> str:
match = COURSE_CODE_PAT.search(question.upper())
if not match:
return ""
return match.group(0).replace(" ", "").upper()
def _normalize_decision(self, decision: str, fallback: str = "Need more info") -> str:
allowed = {"Eligible", "Not eligible", "Need more info"}
if decision in allowed:
return decision
if fallback in allowed:
return fallback
return "Need more info"
def _default_graph_result(self) -> dict[str, Any]:
return {
"eligible": False,
"decision": "Need more info",
"missing_prereqs": [],
"missing_coreqs": [],
"grade_issues": [],
"gpa_issues": [],
"prereq_path": [],
"either_or_options": [],
}
def _make_evidence(self, citations: list[dict[str, Any]]) -> str:
if not citations:
return "No cited evidence available in retrieved context."
lines = []
for citation in citations:
lines.append(
"[SOURCE: "
f"{citation.get('document_name', '')}, "
f"Section: {citation.get('section_heading', '')}, "
f"Chunk: {citation.get('chunk_id', '')}]"
)
return "\n".join(lines)
def _next_step(self, graph_result: dict[str, Any]) -> str:
missing = graph_result.get("missing_prereqs", [])
if missing:
return f"Complete missing prerequisites first: {', '.join(missing)}."
either_or_options = graph_result.get("either_or_options", [])
if either_or_options:
groups: list[str] = []
for options in either_or_options[:3]:
if not isinstance(options, list):
continue
cleaned = [str(option).strip() for option in options if str(option).strip()]
if cleaned:
formatted = [f"({option})" if " and " in option.lower() else option for option in cleaned[:4]]
groups.append(" OR ".join(formatted))
if groups:
return f"Complete one option from each prerequisite group: {'; '.join(groups)}."
gpa_issues = graph_result.get("gpa_issues", [])
if gpa_issues:
if any("student level not provided" in str(issue).lower() for issue in gpa_issues):
return "Share whether you are an undergraduate or graduate student for accurate GPA policy checks."
if any("not provided" in str(issue).lower() for issue in gpa_issues):
return "Share your current cumulative GPA for complete eligibility verification."
return "Review GPA requirement constraints and contact your advisor if needed."
if graph_result.get("decision") == "Need more info":
return "Share additional profile details for a precise eligibility check."
return "You can proceed with enrollment verification through your department/advisor."
def _build_crewai_groq_llm(self, model_name: str, groq_key: str) -> Any | None:
if ChatGroq is None or BaseLLM is None:
return None
chat_model = ChatGroq(
model=model_name,
groq_api_key=groq_key,
temperature=float(settings.TEMP_REASONING),
max_tokens=int(settings.LLM_MAX_TOKENS),
)
class CrewGroqLLMAdapter(BaseLLM):
def __init__(self) -> None:
super().__init__(
model=model_name,
temperature=float(settings.TEMP_REASONING),
api_key=groq_key,
provider="groq",
)
self._chat_model = chat_model
@staticmethod
def _serialize_messages(messages: Any) -> str:
if isinstance(messages, str):
return messages
lines: list[str] = []
for msg in messages or []:
if isinstance(msg, dict):
role = str(msg.get("role", "user"))
content = msg.get("content", "")
else:
role = str(getattr(msg, "role", "user"))
content = getattr(msg, "content", "")
if isinstance(content, list):
parts: list[str] = []
for item in content:
if isinstance(item, dict):
parts.append(str(item.get("text", "")))
else:
parts.append(str(item))
content = " ".join(parts).strip()
lines.append(f"{role}: {content}")
return "\n".join(lines).strip()
def call(
self,
messages: Any,
tools: Any = None,
callbacks: Any = None,
available_functions: Any = None,
from_task: Any = None,
from_agent: Any = None,
response_model: Any = None,
) -> str:
prompt = self._serialize_messages(messages)
response = self._chat_model.invoke(prompt)
content = getattr(response, "content", "")
if isinstance(content, list):
parts: list[str] = []
for item in content:
if isinstance(item, dict):
parts.append(str(item.get("text", "")))
else:
parts.append(str(item))
return " ".join(parts).strip()
return str(content or "")
return CrewGroqLLMAdapter()
def _normalize_groq_model(self, model_name: str) -> tuple[str, str]:
normalized = (model_name or "").strip()
if not normalized:
normalized = str(settings.LLM_MODEL or "").strip()
if not normalized:
normalized = "openai/gpt-oss-120b"
if normalized.startswith("groq/"):
return normalized, normalized.split("/", 1)[1]
return f"groq/{normalized}", normalized
def _resolve_crewai_llm(self) -> tuple[Any | None, bool]:
explicit_model = str(os.getenv("CREWAI_MODEL", "") or "").strip()
configured_model = str(settings.LLM_MODEL or "").strip()
groq_key = str(settings.GROQ_API_KEY or "").strip()
if groq_key and not groq_key.startswith("dev-placeholder"):
preferred_model = explicit_model or configured_model or str(os.getenv("CREWAI_GROQ_MODEL", "") or "").strip()
crewai_model, adapter_model = self._normalize_groq_model(preferred_model)
if CrewLLM is not None:
try:
return (
CrewLLM(
model=crewai_model,
api_key=groq_key,
temperature=float(settings.TEMP_REASONING),
max_tokens=int(settings.LLM_MAX_TOKENS),
),
True,
)
except Exception as exc:
log.warning(
"CrewAI LLM initialization failed for model %s (%s); falling back to adapter.",
crewai_model,
exc,
)
adapter = self._build_crewai_groq_llm(adapter_model, groq_key)
if adapter is not None:
return adapter, True
log.warning("Groq CrewAI LLM fallback unavailable; langchain-groq/CrewAI BaseLLM not ready.")
return None, False
if explicit_model:
return explicit_model, explicit_model.startswith("groq/")
openai_key = str(os.getenv("OPENAI_API_KEY", "") or "").strip()
if openai_key:
return str(os.getenv("OPENAI_MODEL", "gpt-4o-mini") or "gpt-4o-mini").strip(), False
return None, False
def _create_crewai_crew(self, mode: str) -> Any | None:
if not bool(settings.CREWAI_ENABLED):
return None
if Crew is None or CrewAgent is None or Task is None:
log.warning("CrewAI package not available; continuing with LangChain stage orchestration.")
return None
crewai_llm, is_groq_llm = self._resolve_crewai_llm()
if not crewai_llm:
log.warning(
"CrewAI model/provider not configured; set CREWAI_MODEL or configure GROQ_API_KEY/OPENAI_API_KEY. "
"Continuing with LangChain stage orchestration."
)
return None
try:
intake = CrewAgent(
role="Intake Agent",
goal="Normalize student profile and identify missing info",
backstory="Handles student profile normalization and clarification checks.",
llm=crewai_llm,
verbose=settings.CREWAI_VERBOSE,
allow_delegation=False,
)
retriever = CrewAgent(
role="Catalog Retriever Agent",
goal="Retrieve catalog evidence and citations",
backstory="Finds relevant catalog chunks and citation metadata.",
llm=crewai_llm,
verbose=settings.CREWAI_VERBOSE,
allow_delegation=False,
)
planner = CrewAgent(
role="Planner Agent",
goal="Produce policy-grounded student guidance",
backstory="Generates structured plans and eligibility guidance from evidence.",
llm=crewai_llm,
verbose=settings.CREWAI_VERBOSE,
allow_delegation=False,
)
verifier = CrewAgent(
role="Verifier Agent",
goal="Audit factual support and decision consistency",
backstory="Checks citation support and graph reasoning consistency.",
llm=crewai_llm,
verbose=settings.CREWAI_VERBOSE,
allow_delegation=False,
)
tasks = [
Task(
description=f"Run intake normalization for {mode} query request.",
expected_output="Normalized profile payload.",
agent=intake,
),
Task(
description=f"Retrieve relevant catalog context for {mode} query.",
expected_output="Retrieved chunks with citations.",
agent=retriever,
),
Task(
description=f"Generate structured planner response for {mode} query.",
expected_output="Structured planner output.",
agent=planner,
),
Task(
description="Audit the response for citation and consistency issues.",
expected_output="Structured verification output.",
agent=verifier,
),
]
use_memory = bool(settings.CREWAI_MEMORY)
if is_groq_llm and use_memory:
log.warning("CrewAI memory disabled for Groq model compatibility.")
use_memory = False
process = Process.sequential if Process is not None else "sequential"
return Crew(
agents=[intake, retriever, planner, verifier],
tasks=tasks,
verbose=settings.CREWAI_VERBOSE,
memory=use_memory,
process=process,
)
except Exception as exc:
log.warning(
"CrewAI initialization failed (%s); continuing with LangChain stage orchestration.",
exc,
)
return None
async def _touch_crewai(self, mode: str, payload: dict[str, Any]) -> None:
"""
Instantiate and kickoff CrewAI orchestration metadata pass.
The authoritative response is still produced by LangChain-backed stage chains,
but this keeps CrewAI as the orchestration layer entrypoint when enabled.
"""
if not bool(settings.CREWAI_ENABLED):
return
crew = self._create_crewai_crew(mode)
if crew is None:
return
def _kickoff() -> None:
crew.kickoff(inputs={"mode": mode, "payload": payload})
try:
await asyncio.wait_for(
asyncio.to_thread(_kickoff),
timeout=float(settings.CREWAI_TIMEOUT_SECONDS),
)
except Exception:
log.exception("CrewAI kickoff failed; continuing with LangChain stage orchestration.")
async def run_prereq(self, payload: dict[str, Any], trace_id: str) -> dict[str, Any]:
question = str(payload.get("question", "") or "")
await self._touch_crewai("prereq", payload)
profile = await self._intake.run(payload, mode="prereq")
missing_profile_fields = [
str(field).strip()
for field in (profile.get("missing_fields", []) or [])
if str(field).strip()
]
needs_profile_clarification = bool(missing_profile_fields)
target_course = self._extract_target_course(question)
enforce_gpa_policies = bool(
profile.get("gpa", None) is not None
or str(profile.get("student_level", "")).strip()
or bool(profile.get("include_financial_aid_policies", False))
)
async def _graph_task() -> dict[str, Any]:
if not target_course:
return self._default_graph_result()
try:
return await asyncio.to_thread(
check_eligibility,
target_course,
profile.get("completed_courses", []),
profile.get("grades", {}),
student_gpa=profile.get("gpa", None),
student_level=profile.get("student_level", ""),
enforce_gpa_policies=enforce_gpa_policies,
include_financial_aid_policies=bool(profile.get("include_financial_aid_policies", False)),
)
except GraphNodeNotFoundError:
return self._default_graph_result()
filters = {"catalog_year": profile.get("catalog_year", "")} if profile.get("catalog_year") else None
async def _vector_task(_: dict[str, Any]) -> dict[str, Any]:
return await self._retriever.run(question, filters=filters)
async def _graph_stage_task(_: dict[str, Any]) -> dict[str, Any]:
return await _graph_task()
stage_parallel = RunnableParallel(
vector_ctx=RunnableLambda(_vector_task),
graph_result=RunnableLambda(_graph_stage_task),
)
parallel_result = await stage_parallel.ainvoke({})
vector_ctx = parallel_result.get("vector_ctx", {})
graph_result = parallel_result.get("graph_result", self._default_graph_result())
graph_result_for_prereq = graph_result
if needs_profile_clarification:
graph_result_for_prereq = self._default_graph_result()
planner_result = await self._planner.run(
profile=profile,
vector_ctx=vector_ctx,
graph_result=graph_result_for_prereq,
mode="prereq",
question=question,
)
effective_decision = self._normalize_decision(
str(graph_result_for_prereq.get("decision", "Need more info")),
fallback="Need more info",
)
draft = {
"decision": effective_decision,
"answer": str(planner_result.get("answer", ABSTENTION_MSG)),
"evidence": self._make_evidence(planner_result.get("citations", [])),
"citations": planner_result.get("citations", []),
"next_step": self._next_step(graph_result_for_prereq),
"clarifying_questions": (
planner_result.get("clarifying_questions", [])
if effective_decision == "Need more info"
else []
),
"graph_result": {
"eligible": bool(graph_result_for_prereq.get("eligible", False)),
"missing_prereqs": graph_result_for_prereq.get("missing_prereqs", []),
"missing_coreqs": graph_result_for_prereq.get("missing_coreqs", []),
"grade_issues": graph_result_for_prereq.get("grade_issues", []),
"gpa_issues": graph_result_for_prereq.get("gpa_issues", []),
"prereq_path": graph_result_for_prereq.get("prereq_path", []),
"either_or_options": graph_result_for_prereq.get("either_or_options", []),
},
"assumptions": planner_result.get("assumptions", []),
"trace_id": trace_id,
}
verified = await self._verifier.run(draft, vector_ctx.get("retrieved_chunks", []), graph_result_for_prereq)
final_payload = dict(verified["final_response"])
final_payload["decision"] = self._normalize_decision(
str(final_payload.get("decision", draft["decision"])),
fallback=draft["decision"],
)
final_payload["trace_id"] = trace_id
chunks_retrieved = len(vector_ctx.get("retrieved_chunks", []))
citation_count = len(final_payload.get("citations", []))
abstained = ABSTENTION_MSG in str(final_payload.get("answer", ""))
return {
"response": final_payload,
"chunks_retrieved": chunks_retrieved,
"citation_count": citation_count,
"abstained": abstained,
"graph_used": True,
"verifier_passed": bool(verified.get("passed", False)),
"verifier_issues": verified.get("issues", []),
"agents_called": [
"IntakeAgent",
"CatalogRetrieverAgent",
"PlannerAgent",
"VerifierAgent",
"CrewRuntime",
],
}
async def run_plan(self, payload: dict[str, Any], trace_id: str) -> dict[str, Any]:
await self._touch_crewai("plan", payload)
profile = await self._intake.run(payload, mode="plan")
plan_question = str(payload.get("question", "") or "").strip()
if not plan_question:
plan_question = (
f"Create a {profile.get('target_term', '')} course plan for {profile.get('target_major', '')} "
f"with at most {profile.get('max_credits', 0)} credits."
)
filters = {"catalog_year": profile.get("catalog_year", "")} if profile.get("catalog_year") else None
async def _vector_task(_: dict[str, Any]) -> dict[str, Any]:
return await self._retriever.run(plan_question, filters=filters)
async def _available_courses_task(_: dict[str, Any]) -> list[Any]:
completed_courses = profile.get("completed_courses", [])
if not completed_courses:
return []
return await asyncio.to_thread(get_available_next_courses, completed_courses)
stage_parallel = RunnableParallel(
vector_ctx=RunnableLambda(_vector_task),
available_courses=RunnableLambda(_available_courses_task),
)
parallel_result = await stage_parallel.ainvoke({})
vector_ctx = parallel_result.get("vector_ctx", {})
available_courses = parallel_result.get("available_courses", [])
graph_result = {"available_next_courses": available_courses}
planner_result = await self._planner.run(
profile=profile,
vector_ctx=vector_ctx,
graph_result=graph_result,
mode="plan",
question=plan_question,
)
draft = {
"answer": planner_result.get("answer", ""),
"plan": planner_result.get("plan", []),
"citations": planner_result.get("citations", []),
"clarifying_questions": planner_result.get("clarifying_questions", []),
"assumptions": planner_result.get("assumptions", []),
"risks": planner_result.get("risks", []),
}
verified = await self._verifier.run(draft, vector_ctx.get("retrieved_chunks", []), graph_result)
final_payload = dict(verified["final_response"])
final_payload["trace_id"] = trace_id
final_payload["total_credits"] = int(
sum(int(course.get("credits", 0) or 0) for course in final_payload.get("plan", []))
)
chunks_retrieved = len(vector_ctx.get("retrieved_chunks", []))
citation_count = len(final_payload.get("citations", []))
abstained = ABSTENTION_MSG in str(final_payload.get("answer", ""))
return {
"response": final_payload,
"chunks_retrieved": chunks_retrieved,
"citation_count": citation_count,
"abstained": abstained,
"graph_used": True,
"verifier_passed": bool(verified.get("passed", False)),
"verifier_issues": verified.get("issues", []),
"agents_called": [
"IntakeAgent",
"CatalogRetrieverAgent",
"PlannerAgent",
"VerifierAgent",
"CrewRuntime",
],
}
async def run_ask(self, payload: dict[str, Any], trace_id: str) -> dict[str, Any]:
await self._touch_crewai("ask", payload)
question = str(payload.get("question", "") or "")
filters = payload.get("filters")
profile = await self._intake.run({}, mode="ask")
vector_ctx = await self._retriever.run(question, filters=filters)
planner_result = await self._planner.run(
profile=profile,
vector_ctx=vector_ctx,
graph_result={},
mode="ask",
question=question,
)
draft = {
"answer": str(planner_result.get("answer", ABSTENTION_MSG)),
"citations": planner_result.get("citations", []),
"abstained": ABSTENTION_MSG in str(planner_result.get("answer", "")),
}
verified = await self._verifier.run(draft, vector_ctx.get("retrieved_chunks", []), {})
final_payload = dict(verified["final_response"])
final_payload["abstained"] = bool(final_payload.get("abstained", False)) or (
ABSTENTION_MSG in str(final_payload.get("answer", ""))
)
final_payload["trace_id"] = trace_id
chunks_retrieved = len(vector_ctx.get("retrieved_chunks", []))
citation_count = len(final_payload.get("citations", []))
abstained = bool(final_payload.get("abstained", False))
return {
"response": final_payload,
"chunks_retrieved": chunks_retrieved,
"citation_count": citation_count,
"abstained": abstained,
"graph_used": False,
"verifier_passed": bool(verified.get("passed", False)),
"verifier_issues": verified.get("issues", []),
"agents_called": [
"IntakeAgent",
"CatalogRetrieverAgent",
"PlannerAgent",
"VerifierAgent",
"CrewRuntime",
],
}