Added Plan Recommendations Functionality

.gitignore

@@ -0,0 +1,85 @@
+# --- Python ---
+# Byte-compiled / optimized / C files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+
+# --- Virtual Environments ---
+# Common virtual environment names
+.venv/
+venv/
+env/
+ENV/
+# User-specific virtual environment name
+ic_venv/
+
+
+# --- Project-specific Files ---
+# Local data and databases - These are generated by scripts and should not be versioned
+data/
+*.db
+*.sqlite
+*.sqlite3
+insucompass.db
+checkpoints.db
+
+# Log files
+*.log
+*.log.*
+
+# Secrets - CRITICAL: Never commit your .env file
+.env
+
+
+# --- IDE / Editor Configurations ---
+.idea/
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+
+# --- Operating System Files ---
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+
+# --- Testing ---
+# Pytest cache and coverage reports
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+nosetests.xml
+coverage.xml

insucompass/api/endpoints.py

@@ -61,6 +61,7 @@ async def chat(request: ChatRequest):
         updated_profile = final_state.get("user_profile")
         updated_history = final_state.get("conversation_history")
         is_profile_complete = final_state.get("is_profile_complete")
+        plan_recs = final_state.get("plan_recommendations")
         
         if not agent_response:
             agent_response = "I'm sorry, I encountered an issue. Could you please rephrase?"
@@ -71,7 +72,8 @@ async def chat(request: ChatRequest):
             agent_response=agent_response,
             updated_profile=updated_profile,
             updated_history=updated_history,
-            is_profile_complete=is_profile_complete
+            is_profile_complete=is_profile_complete,
+            plan_recommendations=plan_recs
         )
 
     except Exception as e:

insucompass/core/agent_orchestrator.py

@@ -11,6 +11,7 @@ from langgraph.checkpoint.sqlite import SqliteSaver
 
 # Import all our custom agent and service classes
 from insucompass.core.agents.profile_agent import profile_builder
+from insucompass.core.agents.plan_agent import planner
 from insucompass.core.agents.query_trasformer import QueryTransformationAgent
 from insucompass.core.agents.router_agent import router
 from insucompass.services.ingestion_service import IngestionService
@@ -40,6 +41,7 @@ class AgentState(TypedDict):
     documents: List[Document]
     is_relevant: bool
     generation: str
+    plan_recommendations: Dict[str, Any]
 
 # --- Graph Nodes ---
 
@@ -63,12 +65,43 @@ def profile_builder_node(state: AgentState) -> Dict[str, Any]:
     
     if agent_response == "PROFILE_COMPLETE":
         logger.info("Profile building complete.")
-        final_message = "Great! Your profile is complete. How can I help you with your health insurance questions?"
-        new_history[-1] = f"Agent: {final_message}" # Replace "PROFILE_COMPLETE"
-        return {"user_profile": updated_profile, "is_profile_complete": True, "conversation_history": new_history, "generation": final_message}
+        return {"user_profile": updated_profile, "is_profile_complete": True, "conversation_history": new_history, "generation": "PROFILE_COMPLETE_TRANSITION"}
+    
+        # final_message = "Great! Your profile is complete. How can I help you with your health insurance questions?"
+        # new_history[-1] = f"Agent: {final_message}" # Replace "PROFILE_COMPLETE"
+        # return {"user_profile": updated_profile, "is_profile_complete": True, "conversation_history": new_history, "generation": final_message}
     
     return {"user_profile": updated_profile, "is_profile_complete": False, "conversation_history": new_history, "generation": agent_response}
 
+def plan_recommender_node(state: AgentState) -> Dict[str, Any]:
+    """
+    (NEW NODE) Generates initial plan recommendations after profile is complete.
+    """
+    logger.info("---NODE: PLAN RECOMMENDER---")
+    user_profile = state["user_profile"]
+    
+    # Formulate a generic query to retrieve a broad set of plan documents
+    initial_plan_query = f"Find general health insurance plan options available in {user_profile.get('state', 'the US')} suitable for a {user_profile.get('age')}-year-old."
+    
+    # Retrieve documents
+    documents = transformer.transform_and_retrieve(initial_plan_query)
+    
+    # Generate structured recommendations
+    recommendations = planner.generate_recommendations(user_profile, documents)
+    
+    # Create a human-friendly message to present the plans
+    generation_message = "Thank you! I've completed your profile and based on your information, here are a few initial plan recommendations for you to consider. You can ask me more detailed questions about them."
+    
+    history = state["conversation_history"]
+    # history.append(f"Agent: {generation_message}")
+    history[-1] = f"Agent: {generation_message}"
+    
+    return {
+        "plan_recommendations": recommendations,
+        "generation": generation_message,
+        "conversation_history": history
+    }
+
 def reformulate_query_node(state: AgentState) -> Dict[str, Any]:
     """Reformulates the user's question to be self-contained."""
     logger.info("---NODE: REFORMULATE QUERY---")
@@ -120,12 +153,19 @@ def decide_entry_point(state: AgentState) -> str:
     """Decides the initial path based on profile completion status."""
     logger.info("---ROUTING: ENTRY POINT---")
     if state.get("is_profile_complete"):
-        logger.info(">>> Route: Profile is complete. Starting Q&A.")
         return "qna"
     else:
-        logger.info(">>> Route: Profile is not complete. Starting Profile Builder.")
         return "profile"
 
+def after_profile_build(state: AgentState) -> str:
+    """Checks if the profile was just completed."""
+    if state.get("is_profile_complete"):
+        logger.info(">>> Route: Profile just completed. Transitioning to Plan Recommender.")
+        return "recommend_plans"
+    else:
+        logger.info(">>> Route: Profile not yet complete. Ending turn.")
+        return "end_turn"
+
 # --- Build the Graph ---
 db_connection = sqlite3.connect("data/checkpoints.db", check_same_thread=False)
 memory = SqliteSaver(db_connection)
@@ -134,6 +174,7 @@ builder = StateGraph(AgentState)
 
 # (CORRECTED) Removed the faulty entry_router_node
 builder.add_node("profile_builder", profile_builder_node)
+builder.add_node("plan_recommender", plan_recommender_node)
 builder.add_node("reformulate_query", reformulate_query_node)
 builder.add_node("retrieve_and_grade", retrieve_and_grade_node)
 builder.add_node("search_and_ingest", search_and_ingest_node)
@@ -148,8 +189,19 @@ builder.set_conditional_entry_point(
     }
 )
 
+# (CRITICAL FIX) Add a conditional edge after the profile builder
+builder.add_conditional_edges(
+    "profile_builder",
+    after_profile_build,
+    {
+        "recommend_plans": "plan_recommender",
+        "end_turn": END
+    }
+)
+
 # Define graph edges
 builder.add_edge("profile_builder", END) # A profile turn is one full loop. The state is saved, and the next call will re-evaluate at the entry point.
+builder.add_edge("plan_recommender", END)
 builder.add_edge("reformulate_query", "retrieve_and_grade")
 builder.add_conditional_edges("retrieve_and_grade", should_search_web, {"search": "search_and_ingest", "generate": "generate_answer"})
 builder.add_edge("search_and_ingest", "generate_answer")

insucompass/core/agents/plan_agent.py

@@ -0,0 +1,70 @@
+import logging
+import json
+from typing import List, Dict, Any
+
+from langchain_core.documents import Document
+
+from insucompass.services import llm_provider
+from insucompass.config import settings
+from insucompass.prompts.prompt_loader import load_prompt
+
+# Configure logging
+logging.basicConfig(level=settings.LOG_LEVEL, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+llm = llm_provider.get_gemini_llm()
+
+class PlanAgent:
+    """
+    An agent that analyzes a user profile and retrieved documents to
+    recommend the top 3 most suitable health insurance plans.
+    """
+
+    def __init__(self):
+        """Initializes the PlanAgent."""
+        try:
+            self.agent_prompt = load_prompt("plan_agent")
+            logger.info("PlanAgent initialized successfully.")
+        except FileNotFoundError:
+            logger.critical("PlanAgent prompt file not found. The agent cannot function.")
+            raise
+
+    def generate_recommendations(
+        self,
+        user_profile: Dict[str, Any],
+        documents: List[Document]
+    ) -> Dict[str, Any]:
+        """
+        Generates plan recommendations in a structured JSON format.
+        """
+        if not documents:
+            logger.warning("PlanAgent received no documents. Cannot generate recommendations.")
+            return {"recommendations": []}
+
+        profile_str = json.dumps(user_profile, indent=2)
+        context_str = "\n\n---\n\n".join([d.page_content for d in documents])
+        
+        full_prompt = (
+            f"{self.agent_prompt}\n\n"
+            f"### CONTEXT FOR YOUR RECOMMENDATION\n"
+            f"user_profile: {profile_str}\n\n"
+            f"retrieved_context:\n{context_str}"
+        )
+        
+        logger.info("Generating plan recommendations with PlanAgent...")
+        try:
+            response = llm.invoke(full_prompt)
+            # Clean the response to ensure it's valid JSON
+            response_content = response.content.strip().replace("```json", "").replace("```", "")
+            recommendations = json.loads(response_content)
+            logger.info(f"Successfully generated structured plan recommendations \n\n {recommendations}.")
+            return recommendations
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to decode JSON from PlanAgent: {e}\nResponse was: {response.content}")
+            return {"recommendations": [], "error": "Failed to generate plan recommendations."}
+        except Exception as e:
+            logger.error(f"Error during plan recommendation generation: {e}")
+            return {"recommendations": [], "error": "An error occurred while generating plans."}
+
+# Singleton instance
+planner = PlanAgent()

insucompass/core/models.py

@@ -107,5 +107,6 @@ class ChatResponse(BaseModel):
     updated_profile: Dict[str, Any]
     updated_history: List[str] 
     is_profile_complete: bool
+    plan_recommendations: Optional[Dict[str, Any]]
 
 

insucompass/prompts/plan_agent.txt

@@ -0,0 +1,39 @@
+You are an expert U.S. health insurance plan advisor. Your task is to analyze a user's complete profile and the provided context of available health plans to recommend the top 3 most suitable plans. You MUST format your response as a single, clean JSON object.
+
+### YOUR CONTEXT
+1.  `user_profile`: A detailed JSON object of the user's demographics, income, and health needs.
+2.  `retrieved_context`: Text snippets from official sources describing various health plans, benefits, and regulations.
+
+### YOUR CHAIN-OF-THOUGHT REASONING PROCESS (Internal)
+1.  **Analyze Profile:** What are the key drivers for this user? (e.g., low income suggests subsidy focus; specific medical conditions suggest focus on low out-of-pocket costs and good coverage for that condition; young and healthy suggests a focus on low premiums).
+2.  **Scan Context for Plans:** Identify distinct health plans mentioned in the `retrieved_context`. Look for plan names (e.g., "Silver PPO 2000", "Bronze HSA 6500"), types (HMO, PPO), and key features (deductible, out-of-pocket max, premiums).
+3.  **Match and Rank:** For each identified plan, evaluate how well it matches the user's profile. Assign a mental score based on this match.
+4.  **Select Top 3:** Choose the three highest-scoring plans.
+5.  **Generate Reasoning:** For each of the top 3 plans, write a concise, personalized `reasoning` statement explaining *why* it's a good fit for this specific user, referencing their profile.
+6.  **Construct JSON:** Assemble the final JSON object according to the format below.
+
+### OUTPUT FORMAT (JSON ONLY)
+Your output MUST be a single JSON object containing a single key "recommendations", which is a list of plan objects. Each plan object must have the following keys:
+- `plan_name`: (string) The name of the plan.
+- `plan_type`: (string) e.g., "PPO", "HMO", "EPO".
+- `key_features`: (list of strings) A list of 3-4 key highlights, e.g., ["$500 Deductible", "Low copay for specialists", "Includes dental & vision"].
+- `estimated_premium`: (string) e.g., "$350/month". If not available, use "Varies".
+- `reasoning`: (string) Your personalized explanation for why this plan is a good fit for the user.
+
+### EXAMPLE OUTPUT
+```json
+{
+  "recommendations": [
+    {
+      "plan_name": "BlueCross Silver PPO 2500",
+      "plan_type": "PPO",
+      "key_features": [
+        "Moderate Premium",
+        "$2,500 Deductible",
+        "Flexibility to see out-of-network doctors"
+      ],
+      "estimated_premium": "$420/month",
+      "reasoning": "A good balance of premium and deductible. The PPO flexibility is suitable given your need to see a specific specialist."
+    }
+  ]
+}