Upload 7 files

Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.10
+
+WORKDIR /code
+
+COPY ./requirements.txt /code/requirements.txt
+
+RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
+
+COPY . /code
+
+CMD ["uvicorn", "fapi:app", "--host", "0.0.0.0", "--port", "7860"]

agents.py

@@ -0,0 +1,39 @@
+from google.adk.agents import LlmAgent,Agent
+from google.adk.tools import google_search
+from constants import INSTRUCTIONS_ABOUT_COLLEGE, INSTRUCTIONS_COLLEGE_PREDICTOR, INSTRUCTIONS_COLLEGE_SENIOR, INSTRUCTIONS_COORDINATOR
+from tools import db_tool, tavily_tool, predictor_tool, mentor_tool
+
+about_college = LlmAgent(
+    name="about_college_agent",
+    description="An agent to provide information about the college.",
+    instruction = INSTRUCTIONS_ABOUT_COLLEGE,
+    tools=[db_tool, tavily_tool],
+    model="gemini-2.0-flash"
+)
+
+college_predictor = LlmAgent(
+    name="college_predictor_agent",
+    description="An agent to predict college outcomes.",
+    instruction = INSTRUCTIONS_COLLEGE_PREDICTOR,
+    tools=[predictor_tool],
+    model="gemini-2.0-flash"
+)
+
+college_senior = LlmAgent(
+    name="college_senior_agent",
+    description="An agent to assist college seniors.",
+    instruction = INSTRUCTIONS_COLLEGE_SENIOR,
+    tools=[mentor_tool],
+    model="gemini-2.0-flash"
+)
+
+
+coordinator = Agent(
+    name="coordinator_agent",
+    description="An agent to coordinate with students in college counselling.",
+    instruction=INSTRUCTIONS_COORDINATOR,
+    sub_agents=[about_college, college_predictor, college_senior],
+    model="gemini-2.0-flash"
+)
+
+

app.py

@@ -0,0 +1,8 @@
+"""
+Main entry point for Hugging Face Spaces deployment
+"""
+from fapi import app
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

constants.py

@@ -0,0 +1,210 @@
+INSTRUCTIONS_COORDINATOR="""
+You are an AI college counsellor for engineering students (JEE Mains) with 10 years of experience, and you will redirect users' queries to one of your sub-agents based on their expertise, providing the appropriate assistance to the user.
+
+1. You will receive a query from the user, which will have two sections:
+    a. `user_query`: The query from the user.
+    b. `user_designation`: This will contain- 'userCrl': int, 'userCategory': str, 'userGender': str, 'userHomeState': str
+
+2. If the `user_query` in query is an answer to follow-up question than you will send the query to sub-agent to which you sent the previous query.
+
+3.  If the `user_query` is a new query than you will analyse the `user_query` and based on the content, you will decide which sub-agent to use:
+    a. If the `user_query` is a greeting than greet back the user and ask how you can help them with their college queries.
+    b. If the `user_query` is about general college information, use the `about_college_agent` to provide detailed information and you will send the `user_query` to the sub-agent and discard the `user_designation`.
+    c. If the `user_query` is about college predictions, use the `college_predictor_agent` to predict college outcomes and you will send the complete user query to the sub-agent.
+    d. If the `user_query` is about college seniors, use the `college_senior_agent` and you will only send the `user_query` to the sub-agent and discard the `user_designation`.
+
+3. Try to answer in simple and clear language and well formated. For bold letters use `**bold text**` format and for next line use `\n` character. Follow the below given format- 
+e.g. Based on your rank of **123**, here are the college predictions:\n  **College**: Indian Institute of Information Technology, Allahabad (IIITA)\n **Branch**: Information Technology (4 Years, Bachelor of Technology) \n **Category**: OPEN \n **Closing Rank**: 5870 
+
+
+"""
+INSTRUCTIONS_ABOUT_COLLEGE="""
+You are a highly experienced college counselor, specializing in helping high school students choose the right engineering colleges. Please follow these guidelines while assisting students:
+    1. Call `db_search` with the user’s query.
+    2. If `db_search` returns an empty `results` list, immediately call `tavily_search`.
+    3. Do not produce any output until one of those calls returns data.
+    4. As soon as you have non‑empty results, stop further searches and craft your answer using only that source.
+    5. Return the answer in a well-formatted manner and clear language and keep it short and simple. For bold letters use `**bold text**` format and for next line use `\n` character. Follow the below given format- 
+    e.g. Here's some information about the Indian Institute of Information Technology (IIIT) Ranchi: \n **Location:** Ranchi, Jharkhand \n **Campus:** It operates from a temporary campus, with a permanent 67-acre campus planned in Kanke, Ranchi. \n **Placements**:  Overall Placement Percentage: 88.79%, overall Median CTC: 13.32 LPA, overall Highest CTC: 83.38 LPA \n 
+"""
+INSTRUCTIONS_COLLEGE_PREDICTOR="""
+You are a an AI assistant for engineering students (JEE Mains). Follow the below task strictly.
+You will receive a query from the user, which will have two sections:
+    1. `user_query`: The query from the user.
+    2. `user_designation`: This will contain- 'userCrl': int, 'userCategory': str, 'userGender': str, 'userHomeState': str
+    3. You will use the predictor_tool to predict the college based on the values you extracted from the `user_designation` and the `user_query`.
+    4. Here is what you will extract.
+        a. `userCrl`: This will be extracted from user_designation and it will be an integer value.
+        b. `userCategory`: This will be extracted from user_designation and it will be a string value.
+        c. `userGender`: This will be extracted from user_designation and it will be a string value.
+        d. `userHomeState`: This will be extracted from user_designation and it will be a string value.
+        e. `limit` (optional): This will be an integer value and it will be 4 by default.
+        f. `collegeName` (optional): This will be extracted from `user_query` and it will be a string value. If the user does not provide a college name, it will be "national institute of technology" by default.
+        g. `branchName` (optional): This will be extracted from `user_query` and it will be a string value. If the user does not provide a branch name, it will be "computer science and engineering" by default.
+        h. `counsellingName` (optional): This will be alwayas "csab" by default.
+
+    5. If the user_query doesn't mention any specific college (collegeName) or branch (branchName), ask a follow-up question like:
+    "Do you have any preference for a college (like IIIT, NIT) or a branch (like CSE)?"
+    
+    6. If you face some error gracefully handle it and if some fields are required from user end ask it.
+    
+    7. Once API returns the answer, add "For more detailed information, please visit https://www.precollege.in/college-predictor" to the end of the answer.
+    
+    8. Return the final answer in a well-formatted manner and clear language and keep it short and simple. For bold letters use `**bold text**` format and for next line use `\n` character.  Follow the below given format-
+    e.g. Based on your rank of **123**, here are the college predictions:\n  **College**: Indian Institute of Information Technology, Allahabad (IIITA)\n **Branch**: Information Technology (4 Years, Bachelor of Technology) \n **Category**: OPEN \n **Closing Rank**: 5870 
+       
+
+"""
+INSTRUCTIONS_COLLEGE_SENIOR="""
+You are an AI assistant for engineering students (JEE Mains). Follow the below task strictly.
+
+1. From user's query, extract the college name.
+2. If you can't find any college name ask the user for the college name.
+3. if you extracted the college name than pass the college name to the `mentor_tool` to get the college senior's information.
+4. If the `mentor_tool` returns an empty `results` list, return a message saying "No college seniors found for this college. Please try - https://www.precollege.in/search".
+5. If the `mentor_tool` returns a non-empty `results` list, return the top 4 results in a well-formatted manner and clear language and keep it short and simple. For bold letters use `**bold text**` format and for next line use `\n` character. Follow the below given format-
+e.g. Here are some seniors from the Indian Institute of Information Technology, Ranchi that I found: \n **Aditya Gautam**: `https://www.precollege.in/mentor/Adityagautam`\n **SUBARNA MASANTA**: `https://www.precollege.in/mentor/subarna` 
+"""
+
+INSTITUTE_MAPPING = {
+    "iit": ["indian institute of technology"],
+    "IIT": ["indian institute of technology"],
+    "i.i.t": ["indian institute of technology"],
+    "I.I.T": ["indian institute of technology"],
+    "i i t": ["indian institute of technology"],
+    "I I T": ["indian institute of technology"],
+    "indian institute of technology": ["indian institute of technology"],
+    "Indian Institute of Technology": ["indian institute of technology"],
+    "nit": ["national institute of technology"],
+    "NIT": ["national institute of technology"],
+    "n.i.t": ["national institute of technology"],
+    "N.I.T": ["national institute of technology"],
+    "n i t": ["national institute of technology"],
+    "N I T": ["national institute of technology"],
+    "national institute of technology": ["national institute of technology"],
+    "National Institute of Technology": ["national institute of technology"],
+    "iiit": ["indian institute of information technology"],
+    "IIIT": ["indian institute of information technology"],
+    "i.i.i.t": ["indian institute of information technology"],
+    "I.I.I.T": ["indian institute of information technology"],
+    "i i i t": ["indian institute of information technology"],
+    "I I I T": ["indian institute of information technology"],
+    "indian institute of information technology": ["indian institute of information technology"],
+    "Indian Institute of Information Technology": ["indian institute of information technology"],
+    "bit": ["birla institute of technology"],
+    "BIT": ["birla institute of technology"],
+    "b.i.t": ["birla institute of technology"],
+    "B.I.T": ["birla institute of technology"],
+    "b i t": ["birla institute of technology"],
+    "B I T": ["birla institute of technology"],
+    "birla institute of technology": ["birla institute of technology"],
+    "Birla Institute of Technology": ["birla institute of technology"],
+    "bits": ["birla institute of technology and science"],
+    "BITS": ["birla institute of technology and science"],
+    "b.i.t.s": ["birla institute of technology and science"],
+    "B.I.T.S": ["birla institute of technology and science"],
+    "b i t s": ["birla institute of technology and science"],
+    "B I T S": ["birla institute of technology and science"],
+    "birla institute of technology and science": ["birla institute of technology and science"],
+    "Birla Institute of Technology and Science": ["birla institute of technology and science"],
+    "dtu": ["delhi technological university"],
+    "DTU": ["delhi technological university"],
+    "nsut": ["netaji subhas university of technology"],
+    "NSUT": ["netaji subhas university of technology"],
+    "iiitd": ["indraprastha institute of information technology delhi"],
+    "IIITD": ["indraprastha institute of information technology delhi"],
+    "iiith": ["international institute of information technology hyderabad"],
+    "IIITH": ["international institute of information technology hyderabad"],
+    "iiitb": ["international institute of information technology bangalore"],
+    "IIITB": ["international institute of information technology bangalore"],
+    "vit": ["vellore institute of technology"],
+    "VIT": ["vellore institute of technology"],
+    "srm": ["srm institute of science and technology"],
+    "SRM": ["srm institute of science and technology"],
+    "mit": ["manipal institute of technology"],
+    "MIT": ["manipal institute of technology"],
+    "pes": ["pes university"],
+    "PES": ["pes university"],
+    "bms": ["bms college of engineering"],
+    "BMS": ["bms college of engineering"],
+    "ramaiah": ["ms ramaiah institute of technology"],
+    "RAMAIAH": ["ms ramaiah institute of technology"],
+    "thapar": ["thapar institute of engineering and technology"],
+    "THAPAR": ["thapar institute of engineering and technology"],
+    "ism": ["indian school of mines"],
+    "ISM": ["indian school of mines"],
+    "spa": ["school of planning & architecture"],
+    "SPA": ["school of planning & architecture"],
+    "vnit": ["visvesvaraya national institute of technology"],
+    "VNIT": ["visvesvaraya national institute of technology"],
+    "manit": ["maulana azad national institute of technology"],
+    "MANIT": ["maulana azad national institute of technology"],
+    "svnit": ["sardar vallabhbhai national institute of technology"],
+    "SVNIT": ["sardar vallabhbhai national institute of technology"],
+    "mnit": ["malaviya national institute of technology"],
+    "MNIT": ["malaviya national institute of technology"],
+    "mnnit": ["motilal nehru national institute of technology"],
+    "MNNIT": ["motilal nehru national institute of technology"],
+    "sliet": ["sant longowal institute of engineering and technology"],
+    "SLIET": ["sant longowal institute of engineering and technology"],
+    "iiest": ["indian institute of engineering science and technology"],
+    "IIEST": ["indian institute of engineering science and technology"],
+    "cusat": ["cochin university of science and technology"],
+    "CUSAT": ["cochin university of science and technology"],
+    "niftem": ["national institute of food technology entrepreneurship and management"],
+    "NIFTEM": ["national institute of food technology entrepreneurship and management"],
+    "iiht": ["indian institute of handloom technology"],
+    "IIHT": ["indian institute of handloom technology"],
+    "ict": ["institute of chemical technology"],
+    "ICT": ["institute of chemical technology"],
+    "iitram": ["institute of infrastructure, technology, research and management"],
+    "IITRAM": ["institute of infrastructure, technology, research and management"],
+    "csvtu": ["chhattisgarh swami vivekanada technical university"],
+    "CSVTU": ["chhattisgarh swami vivekanada technical university"],
+    "gkc": ["ghani khan choudhary institute of engineering and technology"],
+    "GKC": ["ghani khan choudhary institute of engineering and technology"],
+    "nerist": ["north eastern regional institute of science and technology"],
+    "NERIST": ["north eastern regional institute of science and technology"],
+    "cit": ["central institute of technology"],
+    "CIT": ["central institute of technology"],
+    "tezu": ["tezpur university"],
+    "TEZU": ["tezpur university"],
+    "nehu": ["north-eastern hill university"],
+    "NEHU": ["north-eastern hill university"],
+    "mizoram": ["mizoram university"],
+    "MIZORAM": ["mizoram university"],
+    "assam": ["assam university"],
+    "ASSAM": ["assam university"],
+    "smvdu": ["shri mata vaishno devi university"],
+    "SMVDU": ["shri mata vaishno devi university"],
+    "ptu": ["puducherry technological university"],
+    "PTU": ["puducherry technological university"],
+    "jnu": ["jawaharlal nehru university"],
+    "JNU": ["jawaharlal nehru university"],
+    "uoh": ["university of hyderabad"],
+    "UOH": ["university of hyderabad"],
+    "ggu": ["guru ghasidas vishwavidyalaya"],
+    "GGU": ["guru ghasidas vishwavidyalaya"],
+    "gsv": ["gati shakti vishwavidyalaya"],
+    "GSV": ["gati shakti vishwavidyalaya"],
+    "gkv": ["gurukula kangri vishwavidyalaya"],
+    "GKV": ["gurukula kangri vishwavidyalaya"]
+}
+
+BRANCH_MAPPING = {
+    "cse": "computer science and engineering",
+    "CSE": "computer science and engineering",
+    "ece": "electronics and communication engineering",
+    "ECE": "electronics and communication engineering",
+    "che": "chemical engineering",
+    "CHE": "chemical engineering",
+    "aero": "aerospace engineering",
+    "AERO": "aerospace engineering",
+    "bio": "biotechnology",
+    "BIO": "biotechnology"
+}
+
+
+
+ 
+

fapi.py

@@ -0,0 +1,171 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+from agents import coordinator
+from google.adk.sessions import InMemorySessionService
+from constants import INSTITUTE_MAPPING, BRANCH_MAPPING
+from google.adk.tools import google_search
+from google.adk.runners import Runner
+from google.genai import types  # Add this import for Content and Part
+from dotenv import load_dotenv
+import os
+import re
+import datetime
+import datetime
+ 
+# Load environment variables
+load_dotenv()
+GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
+ 
+
+app = FastAPI(
+    title="PreBot College Counselor API",
+    description="AI-powered college counseling system with multi-agent architecture",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Enable CORS for all origins (adjust for production)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Use a shared session service instance
+session_service = InMemorySessionService()
+
+class ChatRequest(BaseModel):
+    user_id: str
+    session_id: str
+    question: str
+
+class ChatResponse(BaseModel):
+    session_id: str
+    answer: str
+
+def preprocess_query(query: str) -> str:
+    sorted_institutes = sorted(INSTITUTE_MAPPING.keys(), key=len, reverse=True)
+    for key in sorted_institutes:
+        pattern = rf'\b{re.escape(key)}\b'
+        query = re.sub(pattern, INSTITUTE_MAPPING[key][0], query, flags=re.IGNORECASE)
+
+    for key, full_name in BRANCH_MAPPING.items():
+        pattern = rf'\b{re.escape(key)}\b'
+        query = re.sub(pattern, full_name, query, flags=re.IGNORECASE)
+
+    return query
+
+@app.options("/chat")
+async def chat_options():
+    return JSONResponse(
+        content={"message": "OK"},
+        headers={
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "POST, OPTIONS",
+            "Access-Control-Allow-Headers": "*",
+        }
+    )
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(req: ChatRequest):
+    try:
+        print(f"Received request - User ID: {req.user_id}, Session ID: {req.session_id}")
+        print(f"Question: {req.question}")
+        
+        # Check if session exists, create if not (methods are NOT async for InMemorySessionService)
+        print("Checking for existing session...")
+        existing_session = session_service.get_session(
+            app_name="coordinator_agent",
+            user_id=req.user_id,
+            session_id=req.session_id
+        )
+        
+        if not existing_session:
+            print("Creating new session...")
+            session_service.create_session(
+                app_name="coordinator_agent",
+                user_id=req.user_id,
+                session_id=req.session_id
+            )
+        else:
+            print("Using existing session")
+        
+        # Use the shared session service for the Runner
+        print("Creating runner...")
+        runner = Runner(
+            agent=coordinator, 
+            app_name="coordinator_agent", 
+            session_service=session_service  # Use the shared session service
+        )
+        
+        # Create properly formatted message using Google ADK types
+        print("Processing query...")
+        processed_query = preprocess_query(req.question)
+        print(f"Processed query: {processed_query}")
+        
+        user_msg = types.Content(role="user", parts=[types.Part(text=processed_query)])
+        
+        print("Running agent...")
+        agent_response = runner.run(
+            user_id=req.user_id,
+            session_id=req.session_id,
+            new_message=user_msg,
+        )
+        
+        # Process the generator response to extract the final answer
+        print(f"Agent response type: {type(agent_response)}")
+        reply_text = ""
+        
+        if hasattr(agent_response, '__iter__') and not isinstance(agent_response, str):
+            print("Processing iterable response...")
+            for event in agent_response:
+                print(f"Processing event: {event}")
+                if hasattr(event, 'is_final_response') and event.is_final_response():
+                    if hasattr(event, 'content') and hasattr(event.content, 'parts'):
+                        for part in event.content.parts:
+                            if hasattr(part, 'text') and part.text:
+                                reply_text = part.text
+                                break
+                        if reply_text:
+                            break
+                    elif hasattr(event, 'text'):
+                        reply_text = event.text
+                        break
+            
+            if not reply_text:
+                reply_text = "Sorry, there is an issue in our end :("
+        else:
+            print("Processing direct response...")
+            reply_text = str(agent_response)
+            
+        print(f"Final reply: {reply_text}")
+        return ChatResponse(session_id=req.session_id, answer=reply_text)
+    except Exception as e:
+        print(f"Error occurred: {str(e)}")
+        print(f"Error type: {type(e)}")
+        import traceback
+        print(f"Full traceback: {traceback.format_exc()}")
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+# Add health check endpoint
+@app.get("/")
+async def root():
+    return {
+        "message": "PreBot College Counselor API is running!",
+        "status": "healthy",
+        "version": "1.0.0",
+        "endpoints": {
+            "chat": "/chat",
+            "docs": "/docs",
+            "redoc": "/redoc"
+        }
+    }
+
+@app.get("/health")
+async def health_check():
+    return {"status": "healthy", "timestamp": datetime.datetime.now().isoformat()}

requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-dotenv==1.0.0
+requests==2.31.0
+langchain==0.1.0
+langchain-community==0.0.13
+sentence-transformers==2.2.2
+faiss-cpu==1.7.4
+pydantic==2.5.0
+langchain-tavily==0.1.0
+google-adk
+google-genai
+google-cloud-aiplatform

tools.py

@@ -0,0 +1,235 @@
+import os
+import json
+import datetime
+import requests
+import logging
+# import gspread
+from dotenv import load_dotenv
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+# from huggingface_hub import login as hf_login
+from langchain_community.vectorstores import FAISS
+from langchain.embeddings.base import Embeddings
+from sentence_transformers import SentenceTransformer
+from langchain_tavily import TavilySearch
+from google.adk.tools import FunctionTool
+
+# === LOAD ENV ===
+load_dotenv()
+# HF_TOKEN = os.getenv("HUGGINGFACE_TOKEN")
+# GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
+TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
+# SERVICE_ACCOUNT_JSON = os.getenv("GOOGLE_SERVICE_ACCOUNT_JSON")
+# SHEET_KEY = os.getenv("SHEET_KEY")
+PREDICTOR_API_URL = os.getenv("PREDICTOR_API_URL")
+PREDICTOR_API_KEY = os.getenv("PREDICTOR_API_KEY")
+
+# hf_login(token=HF_TOKEN)
+
+# === GOOGLE SHEET LOGGING ===
+# service_account_dict = json.loads(SERVICE_ACCOUNT_JSON) if isinstance(SERVICE_ACCOUNT_JSON, str) else SERVICE_ACCOUNT_JSON
+
+# def add_query_to_sheet(user_id: str, query: str, response: str):
+#     gc = gspread.service_account_from_dict(service_account_dict)
+#     sh = gc.open_by_key(SHEET_KEY)
+#     ws = sh.worksheet("Sheet1")
+#     timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+#     ws.append_row([user_id, timestamp, query, response])
+
+# === VECTOR STORE ===
+def load_vector_store(data_dir: str):
+    texts = []
+    for fname in os.listdir(data_dir):
+        if fname.lower().endswith(".md"):
+            path = os.path.join(data_dir, fname)
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    texts.append(f.read())
+            except UnicodeDecodeError:
+                with open(path, "r", encoding="latin-1") as f:
+                    texts.append(f.read())
+    st_model = SentenceTransformer("all-MiniLM-L6-v2")
+    class LocalEmbeddings(Embeddings):
+        def embed_documents(self, docs):
+            return st_model.encode(docs).tolist()
+        def embed_query(self, q):
+            return st_model.encode([q])[0].tolist()
+    return FAISS.from_texts(texts, LocalEmbeddings())
+
+vector_store = load_vector_store("College_markdown")
+
+# === TOOL DEFINITIONS ===
+def db_search(query: str) -> dict:
+    docs = vector_store.similarity_search(query, k=6)
+    if not docs: return {"results": []}
+    return {"results": [d.page_content for d in docs]}
+
+def tavily_search(query: str) -> dict:
+    if not TAVILY_API_KEY:
+        return {"results": ["Tavily API key not configured"]}
+    
+    tool = TavilySearch(api_key=TAVILY_API_KEY, max_results=6, topic="general", include_raw_content=True)
+    result = tool.invoke({"query": query})
+    snippets = [item.get('content') for item in result.get('results', [])]
+    return {"results": snippets or []}
+
+def college_predictor(
+    userCrl: int,
+    userCategory: str,
+    userGender: str,
+    userHomeState: str,
+    limit: int = 4,
+    counsellingName: str = "csab",
+    collegeName: str = "national institute of technology",
+    branchName: str = "computer science and engineering"
+) -> str:
+    # Log the function call with all parameters
+    logger.info("=" * 80)
+    logger.info("PREDICTOR API CALL STARTED")
+    logger.info("=" * 80)
+    
+    logger.info("Input Parameters:")
+    logger.info(f"  userCrl: {userCrl} (type: {type(userCrl)})")
+    logger.info(f"  userCategory: {userCategory} (type: {type(userCategory)})")
+    logger.info(f"  userGender: {userGender} (type: {type(userGender)})")
+    logger.info(f"  userHomeState: {userHomeState} (type: {type(userHomeState)})")
+    logger.info(f"  limit: {limit} (type: {type(limit)})")
+    logger.info(f"  counsellingName: {counsellingName} (type: {type(counsellingName)})")
+    logger.info(f"  collegeName: {collegeName} (type: {type(collegeName)})")
+    logger.info(f"  branchName: {branchName} (type: {type(branchName)})")
+    
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {PREDICTOR_API_KEY}"
+    }
+    
+    try:
+        # Log parameter conversion
+        logger.info("Converting parameters...")
+        converted_crl = int(userCrl)
+        logger.info(f"  userCrl converted: {converted_crl} (type: {type(converted_crl)})")
+        
+        params = {
+            "userCrl": converted_crl,
+            "userCategory": userCategory,
+            "userGender": userGender,
+            "userHomeState": userHomeState,
+            "limit": limit,
+            "counsellingName": counsellingName,
+        }
+        
+        if collegeName:
+            params["collegeQuery"] = collegeName
+            logger.info(f"  Added collegeQuery: {collegeName}")
+        if branchName:
+            params["branchQuery"] = branchName
+            logger.info(f"  Added branchQuery: {branchName}")
+
+        # Log the final payload
+        logger.info("Final API Request:")
+        logger.info(f"  URL: {PREDICTOR_API_URL}")
+        logger.info(f"  Headers: {json.dumps(headers, indent=2)}")
+        logger.info(f"  Payload: {json.dumps(params, indent=2)}")
+
+        logger.info("Making API request...")
+        response = requests.post(PREDICTOR_API_URL, json=params, headers=headers, timeout=30)
+        
+        # Log response details
+        logger.info("API Response:")
+        logger.info(f"  Status Code: {response.status_code}")
+        logger.info(f"  Response Headers: {dict(response.headers)}")
+        logger.info(f"  Response Content: {response.text}")
+        
+        response.raise_for_status()
+        data = response.json()
+
+        logger.info("Response parsed successfully")
+        logger.info(f"  Parsed data keys: {list(data.keys()) if data else 'None'}")
+
+        if not data or 'data' not in data or 'colleges' not in data['data']:
+            logger.warning("No college predictions found in response")
+            return "No college predictions found with the given criteria."
+
+        colleges = data['data']['colleges']
+        logger.info(f"Found {len(colleges)} colleges in response")
+        
+        if not colleges:
+            logger.warning("Colleges list is empty")
+            return "No college predictions found with the given criteria."
+
+        results = []
+        for i, college in enumerate(colleges[:limit], start=1):
+            logger.info(f"Processing college {i}: {college.get('Institute', 'N/A')}")
+            parts = [f"{i}. College: {college.get('Institute', 'N/A')}"]
+            if college.get('Academic_Program_Name'):
+                parts.append(f"Branch: {college['Academic_Program_Name']}")
+            if college.get('Seat_Type'):
+                parts.append(f"Category: {college['Seat_Type']}")
+            if college.get('Max_ClosingRank'):
+                parts.append(f"Closing Rank: {college['Max_ClosingRank']}")
+            results.append(", ".join(parts))
+
+        final_result = f"Based on your rank {userCrl}, here are college predictions:\n\n" + "\n".join(results)
+        
+        logger.info("=" * 80)
+        logger.info("PREDICTOR API CALL COMPLETED SUCCESSFULLY")
+        logger.info("=" * 80)
+        
+        return final_result
+
+    except ValueError as e:
+        error_msg = f"Parameter conversion error: {str(e)}"
+        logger.error(f"ValueError: {error_msg}")
+        logger.error("=" * 80)
+        return error_msg
+        
+    except requests.exceptions.HTTPError as e:
+        error_msg = f"HTTP Error: {str(e)}"
+        logger.error(f"HTTPError: {error_msg}")
+        logger.error(f"Response body: {response.text if 'response' in locals() else 'No response'}")
+        logger.error("=" * 80)
+        return f"Error fetching college predictions: {error_msg}"
+        
+    except requests.exceptions.RequestException as e:
+        error_msg = f"Request Error: {str(e)}"
+        logger.error(f"RequestException: {error_msg}")
+        logger.error("=" * 80)
+        return f"Error fetching college predictions: {error_msg}"
+        
+    except Exception as e:
+        error_msg = f"Unexpected error: {str(e)}"
+        logger.error(f"Exception: {error_msg}")
+        logger.error("=" * 80)
+        return f"Error fetching college predictions: {error_msg}"
+
+def mentor_search(college_query: str) -> str:
+    """Search mentors by college name and return formatted links."""
+    url = f"https://api.precollege.in/api/v1/llm/search?limit=3&college={college_query}"
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if not data or "data" not in data or not data["data"]:
+            return f"No mentors found for '{college_query}'."
+
+        mentors = data["data"]
+        lines = []
+        for mentor in mentors:
+            name = mentor.get("name", "Unknown")
+            username = mentor.get("username", "")
+            profile_url = f"https://www.precollege.in/mentor/{username}" if username else "No profile link"
+            lines.append(f"{name}: {profile_url}")
+
+        return f"Mentors for '{college_query}':\n\n" + "\n".join(lines)
+    except requests.exceptions.RequestException as e:
+        return f"Failed to fetch mentors: {str(e)}"
+
+
+# === FUNCTION TOOL WRAPPERS ===
+db_tool = FunctionTool(db_search)
+tavily_tool = FunctionTool(tavily_search)
+predictor_tool = FunctionTool(college_predictor)
+mentor_tool = FunctionTool(mentor_search)