feat: add property search, intent routing, and intent summarization

app.py

@@ -1,198 +1,72 @@
 import json
-import re
 
 # Suppress all UserWarnings
 import warnings
-from typing import Any
 
 import gradio as gr
-from langchain.retrievers import ContextualCompressionRetriever
-from langchain.retrievers.document_compressors import LLMChainFilter
-from langchain.retrievers.document_compressors.chain_filter_prompt import (
-    prompt_template,
-)
-from langchain.schema import StrOutputParser
-from langchain_community.vectorstores.elasticsearch import ElasticsearchStore
-from langchain_core.documents import Document
-from langchain_core.output_parsers import BaseOutputParser
-from langchain_core.prompts import ChatPromptTemplate, PromptTemplate
-from langchain_core.runnables import RunnablePassthrough
-from langchain_core.runnables.base import RunnableSerializable
-from langchain_openai import ChatOpenAI, OpenAIEmbeddings
 
 from config import get_settings
-from prompts import CONTEXT_TEMPLATE, QA_WITH_CONTEXT_PROMPT, SYSTEM_PROMPT
-
-warnings.filterwarnings("ignore", category=UserWarning)
-
-KNOWLEDGE_BASE_INDEX_NAME = "pinsmart_revamp_prototype"
-EMBEDDING_MODEL = "text-embedding-3-large"
-RAG_LLM_MODEL = "gpt-3.5-turbo-0125"
-NROF_RETRIEVED_CONTEXT = 5
-
-ERROR_MESSAGE = "Terjadi kesalahan, silakan coba kembali"
-
-# ES only support up to 2048 embedding dimension
-embeddings = OpenAIEmbeddings(
-    model=EMBEDDING_MODEL,
-    api_key=get_settings().openai_api_key,
-    dimensions=2048,
-    timeout=20,
+from schemas.chatbot import (
+    IntentCategories,
 )
-
-vector_db = ElasticsearchStore(
-    es_url=get_settings().es_url,
-    index_name=KNOWLEDGE_BASE_INDEX_NAME,
-    embedding=embeddings,
-)
-
-llm = ChatOpenAI(
-    model_name=RAG_LLM_MODEL,
-    temperature=0,
-    api_key=get_settings().openai_api_key,
-    timeout=20,
+from services.intent_routing import (
+    generate_intent_routing,
+    generate_user_question_intent,
 )
+from services.property_knowledge import generate_property_knowledge_answer
+from services.property_search import search_property_listing
+from services.utils import parse_histories
 
-qa_prompt = ChatPromptTemplate.from_messages(
-    [
-        ("system", SYSTEM_PROMPT),
-        ("human", QA_WITH_CONTEXT_PROMPT),
-    ]
-)
-
-
-class ImprovedBooleanOutputParser(BaseOutputParser[bool]):
-    """Parse the output of an LLM call to a boolean."""
-
-    true_val: str = "YES"
-    """The string value that should be parsed as True."""
-    false_val: str = "NO"
-    """The string value that should be parsed as False."""
-
-    def parse(self, text: str) -> bool:
-        """Parse the output of an LLM call to a boolean.
-
-        Args:
-            text: output of a language model
-
-        Returns:
-            boolean
-
-        """
-        cleaned_text = text.strip()
-        if (self.true_val.upper() not in cleaned_text.upper()) and (
-            self.false_val.upper() not in cleaned_text.upper()
-        ):
-            raise ValueError(
-                f"ImprovedBooleanOutputParser expected output value to either "
-                f"contains {self.true_val} or {self.false_val}. "
-                f"Received {cleaned_text}."
-            )
-
-        return self.true_val.upper() in cleaned_text.upper()
-
-    @property
-    def _type(self) -> str:
-        """Snake-case string identifier for an output parser type."""
-        return "improved_boolean_output_parser"
+warnings.filterwarnings("ignore", category=UserWarning)
 
+N_HISTORIES = 10
 
-_filter = LLMChainFilter.from_llm(
-    llm,
-    prompt=PromptTemplate(
-        template=prompt_template,
-        input_variables=["question", "context"],
-        output_parser=ImprovedBooleanOutputParser(),
-    ),
-)
-docs_retriever = vector_db.as_retriever(
-    search_kwargs={"k": NROF_RETRIEVED_CONTEXT}
-)
+ERROR_MESSAGE = "Terjadi kesalahan, silakan coba kembali"
 
 
-def format_contexts(docs: list[Document]) -> str:
-    aggregate_context = ""
-    for doc in docs:
-        context = CONTEXT_TEMPLATE.format(
-            source=doc.metadata["document_id"],
-            title=doc.metadata["heading_title"],
-            content=doc.page_content,
+def get_prompt_response(message: str, histories: list[str, str]):
+    try:
+        conversational_histories = parse_histories(histories)
+        response = generate_user_question_intent(
+            conversational_histories, message
+        )
+        summarized_user_question_intent = response.choices[0].message.content
+        user_intent = generate_intent_routing(
+            summarized_user_question_intent,
+            model=get_settings().intent_routing__chat_completion_model_name,
         )
 
-        aggregate_context += context
-
-    return aggregate_context
-
-
-docs_compression_retriever = ContextualCompressionRetriever(
-    base_compressor=_filter, base_retriever=docs_retriever
-)
-
-
-def get_end_device_target(*args: Any) -> str:
-    return "mobile"
-
-
-rag_chain: RunnableSerializable = (
-    {
-        "context": docs_compression_retriever | format_contexts,
-        "device": get_end_device_target,
-        "question": RunnablePassthrough(),
-    }
-    | qa_prompt
-    | llm
-    | StrOutputParser()
-)
-
-
-def parse_response(response: str) -> tuple[str, list[dict] | None]:
-    answer_match = re.search(
-        r"\[ANSWER\]\n(.+?)(?=\n\[(.*?)\])", response, re.DOTALL
-    )
-    related_docs_match = re.search(r"\[REFERENCE\]\n(.+)", response, re.DOTALL)
-
-    if answer_match:
-        answer = answer_match.group(1).strip()
-        related_docs = None
-
-        if related_docs_match:
-            related_docs_str = (
-                related_docs_match.group(1).strip().replace("```", "")
+        if user_intent == IntentCategories.property_knowledge_qa:
+            answer = generate_property_knowledge_answer(
+                summarized_user_question_intent,
+            )
+        else:
+            answer = search_property_listing(
+                user_question=summarized_user_question_intent
             )
-            try:
-                related_docs = json.loads(related_docs_str)
-            except Exception:
-                print(f"failed to parse related docs: {related_docs_str}")
-
-        return answer, related_docs
-
-    raise ValueError(f"failed to parse response: {response}")
-
 
-def get_prompt_response(message: str):
-    try:
-        response = rag_chain.invoke(message)
-        answer, related_docs = parse_response(response)
+        # Note: for debugging
+        conversational_histories = json.dumps(
+            conversational_histories, indent=4
+        )
+        print(f"{'='*7} {message} {'='*7}")
+        print(f"User Conversation: {conversational_histories}")
+        print(f"Generated Intent: {summarized_user_question_intent}")
+        print("=" * 30)
     except Exception as e:
         print(f"Error : {e}")
         return ERROR_MESSAGE
 
-    if related_docs:
-        reference_str = "Referensi: \n"
-        for doc in related_docs:
-            reference_title = doc["title"]
-            reference_str += f"- Artikel: {reference_title}\n"
-
-        answer += "\n\n" + reference_str
-
     return answer
 
 
 def chat(message, history):
     history = history or []
-    response = get_prompt_response(message)
+    response = get_prompt_response(message, history)
 
     history.append((message, response))
+    if len(history) >= N_HISTORIES:
+        history = history[-N_HISTORIES:]
 
     return history, history
 

config.py

@@ -1,15 +1,24 @@
 from functools import lru_cache
 
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import BaseSettings
 
 
 class Settings(BaseSettings):
     openai_api_key: str
     es_url: str
-
-    model_config = SettingsConfigDict(
-        env_file=".env", env_file_encoding="utf-8", extra="ignore"
+    collection_index_name: str = (
+        "property_knowledge_references_collection__v1_0"  # noqa
     )
+    intent_routing__chat_completion_model_name: str = "gpt-3.5-turbo-0125"
+    property_search__chat_completion_model_name: str = "gpt-3.5-turbo-1106"
+    property_search__location_similarity_thres: int = 60
+    property_search__limit_search_size: int = 3
+    property_search__exact_price_range_thres: float = 0.1
+    property_search__limit_price_range_thres: float = 0.25
+    property_search__value_range_thres: float = 0.1
+
+    class Config:
+        env_file = ".env"
 
 
 @lru_cache

prompts.py

@@ -3,6 +3,7 @@ SYSTEM_PROMPT = (
     " as PinSmart. You work for Pinhome.id and hence cannot mention other "
     "competitor such as rumah.com, rumah123.com, lamudi.id, 99.co, and so on."
 )
+
 QA_WITH_CONTEXT_PROMPT = """
 ## Instructions
 
@@ -21,12 +22,10 @@ QA_WITH_CONTEXT_PROMPT = """
     [REFERENCE]
     [
         {{
-            "source" : "context_source1",
-            "title" : "context_title1"
+            "source" : "context_source1"
         }},
         {{
-            "source" : "context_source2",
-            "title" : "context_title2"
+            "source" : "context_source2"
         }},
         ...
     ]
@@ -60,3 +59,512 @@ title: {title}
 
 {content}
 """
+
+
+SUMMARIZED_USER_QUESTION_INTENT_SYSTEM_PROMPT = """
+    You are a linguist that processes last user-chat conversations and the 
+    given previous conversations into a summary intent for the last question.
+    The system should analyze the content of the conversations and identify 
+    the main topic or query expressed by the user. The context is set in 
+    Indonesian, there for 10m means 10 milyar or 5m means 5 milyar
+"""
+
+
+SUMMARIZED_USER_QUESTION_INTENT_USER_PROMPT = """
+## Instructions
+
+- Formulate a concise user intent for the given question, 
+    it should consider context from previous interactions 
+    if available to produce more accurate summaries
+- You MUST not interpret any abbreviation
+- The generated intent MUST BE on Bahasa Indonesia
+- It should also highlight the main topic and the keyword of the conversation
+- You may excluded irrelevant contexts
+- The output MUST only the generated intent in string format
+
+Here's the given example that you can use as reference:
+
+-----
+### Example Contexts
+[
+    {{
+        "role": "user",
+        "content": "Hi min, mau nanya dong apa itu kpr?"
+    }},
+    {{
+        "role": "assistant",
+        "content": "KPR adalah singkatan dari Kredit Kepemilikan Rumah, 
+        yaitu jenis pinjaman yang diberikan oleh bank 
+        atau lembaga keuangan lainnya kepada individu untuk membeli rumah.",
+    }}
+]
+
+### Example Question
+sorii, yang takeover maksudnya?
+
+### Example Intent
+User menanyakan tentang kpr takeover
+
+----
+
+### Example Contexts
+[
+    {{
+        "role": "user",
+        "content": "Saya ingin mencari rumah tapak di 
+        Yogyakarta dengan budget 2M"
+    }},
+    {{
+        "role": "assistant",
+        "content": "{{'location': 'Yogyakarta', 'maxPrice': '2000000000', 
+        'buildingType': 'building_type.house'}}",
+    }},
+    {{
+        "role": "user",
+        "content": "Kalo yang kamar tidur 2 ada?"
+    }},
+    {{
+        "role": "assistant",
+        "content": "{{'location': 'Yogyakarta', 'maxPrice': '2000000000', 
+        'buildingType': 'building_type.house', 'bedroom': '2'}}",
+    }}
+]
+
+### Example Question
+Apa itu kpr?
+
+### Example Intent
+User menanyakan tentang definisi kpr
+
+-----
+
+## Contexts
+{contexts}
+
+## Question
+{question}
+
+## Intent
+
+"""
+
+PROPERTY_SEARCH_FUNCTION_CALLING_PROMPT = [
+    {
+        "type": "function",
+        "function": {
+            "name": "get_listing_by_search_param",
+            "description": "Function to search property by text"
+            "listing by parsed text param",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "keyword": {
+                        "type": "string",
+                        "description": (
+                            "The term that indicates the location or "
+                            "point of interest. E.g. Tangsel, Depok, Jaksel, "
+                            "SCBD, BSD, Cendana Spring, Vasa Jagakarsa"
+                        ),
+                    },
+                    "maxBuildingArea": {
+                        "type": "integer",
+                        "description": (
+                            "The maximum size of property building area in "
+                            "square meter"
+                        ),
+                    },
+                    "minBuildingArea": {
+                        "type": "integer",
+                        "description": (
+                            "The minimum size of property building area in "
+                            "square meter"
+                        ),
+                    },
+                    "maxSurfaceArea": {
+                        "type": "integer",
+                        "description": (
+                            "The maximum size of property land surface area in"
+                            " square meter"
+                        ),
+                    },
+                    "minSurfaceArea": {
+                        "type": "integer",
+                        "description": (
+                            "The minimum size of property land surface area in"
+                            " square meter"
+                        ),
+                    },
+                    "maxPrice": {
+                        "type": "integer",
+                        "description": (
+                            "The maximum property's price limit in Indonesian "
+                            "Rupiah context, E.g 1m means 1000000000 or "
+                            "10M means 10000000000 or 100M means 100000000000"
+                        ),
+                    },
+                    "minPrice": {
+                        "type": "integer",
+                        "description": (
+                            "The minimum property's price limit Indonesian "
+                            "Rupiah context, E.g 1m means 1000000000 or "
+                            "10M means 10000000000 or 100M means 100000000000"
+                        ),
+                    },
+                    "maxBedroom": {
+                        "type": "integer",
+                        "description": (
+                            "The maximum property's bedroom limit"
+                        ),
+                    },
+                    "minBedroom": {
+                        "type": "integer",
+                        "description": (
+                            "The minimum property's bedroom limit"
+                        ),
+                    },
+                    "minToilet": {
+                        "type": "integer",
+                        "description": ("The minimum property's toilet limit"),
+                    },
+                    "maxToilet": {
+                        "type": "integer",
+                        "description": ("The maximum property's toilet limit"),
+                    },
+                    "marketType": {
+                        "type": "string",
+                        "enum": [
+                            "property_market_type.primary",
+                            "property_market_type.secondary",
+                            "property_market_type.auction",
+                        ],
+                        "description": (
+                            "The property type of market categories, "
+                            "For e.g: property_market_type.primary "
+                            "refers to new property, "
+                            "property_market_type.secondary refers "
+                            "to used property, "
+                            "and property_market_type.auction refers "
+                            "to auction property"
+                        ),
+                    },
+                    "buildingType": {
+                        "type": "string",
+                        "enum": [
+                            "building_type.apartement",
+                            "building_type.house",
+                            "building_type.ruko",
+                            "building_type.land_residential",
+                            "building_type.land_commercial",
+                        ],
+                        "description": (
+                            "The property building type categories. "
+                            "For e.g: rumah (building_type.house), "
+                            "apartemen (building_type.apartement), and etc"
+                        ),
+                    },
+                    "listingType": {
+                        "type": "string",
+                        "enum": [
+                            "property_listing_type.sell",
+                            "property_listing_type.rent",
+                        ],
+                        "description": (
+                            "The property type of listing categories. "
+                            "For e.g: dijual or membeli refers to "
+                            "property_listing_type.sell, "
+                            "and disewa or kontrak refers to "
+                            "property_listing_type.rent"
+                        ),
+                    },
+                },
+            },
+        },
+    },
+]
+
+PROPERTY_TEXT_PARSER_SYSTEM_MSG = """
+    You are an expert property consultant in Pinhome, Indonesia.
+    In answering question related to property education (e.g. mortgage
+    process, documents needed), you will always need to retrieve relevant
+    context in our database.
+    Also make sure the the answer provided in Indonesia context,
+    for example: property price, which letter m refers to billion not million.
+    Don't make assumptions about what values to plug into functions.
+    Tell user what parameters required to make the function call
+"""
+
+
+# FAQ QUERY BY LLM
+
+FAQ_QUERY_BY_LLM_SYSTEM_MESSAGE = """
+You are an expert linguistic assistant in evaluating set of questions
+to extract its subjects and contexts and evaluate it's answer similarity.
+"""
+
+SAME_QUESTIONS_EVALUATION_PROMPT_NO_EXPLAIN = """
+# ADDITIONAL INFORMATION
+
+- KPR (Kredit Kepemilikan Rumah): a type of mortgage or home loan used to
+    finance the purchase of a house or residential property
+- KPR TAKE OVER: a specific process to the transfer or refinancing of an
+    existing KPR, so you need to already have a KPR to do KPR TAKE OVER and
+    the process is different with KPR
+- KMG (Kredit Multi Guna): a more versatile type of loan that can be used for
+    various purposes
+
+# INSTRUCTIONS
+
+Given a query and target question and it's extracted subjects and contexts,
+evaluate in english if they are the same question or different based on the
+subjects, contexts, and any related additional information provided above.
+
+- It is expected that if the query and target question is evaluated to be SAME,
+    we can safely return EXACT SAME answer. For example:
+    - Query question asking for definition of KPR and target question asking
+     for explanation of KPR, this can be considered SAME, we can answer it
+         with the process and description of KPR
+    - Query question asking for definition and target question asking for
+        documents needed for KPR, this can be considered DIFFERENT, one asking
+        for definition and process, the latter asking specifically what
+        documents is required
+    - Query question asking for definition of KPR and target question asking
+        for definition of KPR TAKE OVER, this can be considered DIFFERENT,
+        one asking for KPR, the latter asking for KPR TAKE OVER, and these
+        are different subjects
+
+ONLY give the final verdict without any explanation, e.g. SAME or DIFFERENT
+verdict
+
+- ONLY RETURN THE VERDICT USING THE FOLLOWING FORMAT
+
+[VERDICT]: SAME or DIFFERENT
+
+===
+
+[QUERY QUESTION]: {query_question}
+[SUBJECTS]: {query_subjects}
+[CONTEXTS]: {query_contexts}
+
+[TARGET QUESTION]: {target_question}
+[SUBJECTS]: {target_subjects}
+[CONTEXTS]: {target_contexts}
+
+[VERDICT]:
+"""
+
+EXTRACT_QUESTION_CONTEXTS_SUBJECTS_PROMPT = """
+Given a question, evaluate the question in english and extract the user
+subjects (in english ) and contexts. If encountered an unknown subjects
+in english (e.g. abbreviation), return it as it is. In asking the question and
+return the extracted purpose strictly following the examples format below.
+
+# EXAMPLES
+
+[QUESTION]: apa itu kpr
+[RESULT]: {{
+    "subjects":["kpr"],
+    "contexts":"user want to know the definition of kpr"
+}}
+
+===
+
+[QUESTION]: apa itu take over kpr
+[RESULT]: {{
+    "subjects":["take over kpr"],
+    "contexts":"user want to know the definition of take over kpr"
+}}
+
+===
+
+[QUESTION]: apa yang membedakan kpr dan kmg?
+[RESULT]: {{
+    "subjects":["kpr","kmg"],
+    "contexts":"user want to know the difference of kpr and kmg"
+}}
+
+===
+
+[QUESTION]: apakah saya bisa mengajukan KPR tanpa membayar DP atau DP 0%?
+[RESULT]: {{
+    "subjects":["kpr","dp 0%"],
+    "contexts":"user want to know whether it is possible to "
+    "apply for kpr without paying dp or dp 0%"
+}}
+
+===
+
+[QUESTION]: {question}
+[RESULT]:
+"""
+
+
+PROPERTY_SEARCH_ROUTING_SYSTEM_PROMPT = (
+    "You are an expert property consultant in Pinhome, Indonesia. "
+    "You can correctly identify questions related to property intents. "
+    "If user query shown any interest in a particular type property, "
+    "you also can derived the property search intent from it"
+)
+
+PROPERTY_SEARCH_ROUTING_USER_PROMPT = """
+## INSTRUCTIONS
+- You have capabilities to query our property listing database and show it to
+    user.
+- Your task is to evaluate and understand the given user query and give verdict
+    whether it is correct and appropriate to respond user query by giving those
+    property listing.
+- The query might be in Bahasa Indonesia language, however you MUST reason and
+    answer in English
+- Think carefully and explain your understanding about the user query, then
+    state your verdict at the end
+
+## EXAMPLE
+
+query : Saya ingin tahu lebih banyak tentang rumah tapak di Yogyakarta
+        dengan harga di bawah 500 juta
+response : this query show that user want to find property in particular type
+  house in Yogyakarta under 500 million, hence it is appropriate to return
+  property listing to the user. [VERDICT]:YES
+
+---
+
+query : cara menjual rumah seken
+response : this query shows that user want to know how to sell secondary house
+  on our platform, so it is not appropriate to return property listing to the
+  user. [VERDICT]:NO
+
+---
+
+query : rumah dp 0%
+response : this query shows that user is looking for particular type of house
+  which can provide 0 percent down payment, hence it is correct to return
+  property listing. [VERDICT]:YES
+
+---
+
+query : syarat rumah dp 0%
+response : this query shows that user want to know the requirements for
+  particular type of house which can provide 0 percent down payment,
+  hence it is not appropriate to return property listing to the
+  user. [VERDICT]:NO
+
+---
+
+query : kontrakan bulanan
+response : this query, even if it short,shows interest to find a particular
+  property of monthly rental type, hence it is appropriate to return property
+  listing to the user. [VERDICT]:YES
+
+---
+
+query : coba sebutkan pilihan properti
+response : this query, even if it's rather unclear,shows that user ask for
+  property recommendations, hence it is appropriate to return property
+  listing to the user. [VERDICT]:YES
+
+---
+
+query : apa itu pinvalue?
+response : this query, ask about the definition of specific term called
+  `pinvalue` term which might be a Pinhome product, hence it is not correct
+  to return property lising to the user. [VERDICT]:NO
+
+---
+
+## TASK
+
+query : {question}
+response : 
+"""
+
+
+LOCATION_LEVEL_FINDER_SYSTEM_MSG = (
+    "You're a location-based search engine for real estate in Indonesia. "
+    "Please make sure the answer is consistent. "
+)
+
+LOCATION_LEVEL_FINDER_USER_PROMPT = """
+Given a user query for a location using the string,
+You need to identify and return all relevant locations in Indonesia.
+
+The structured format for the results should be only in JSON format,
+adhering to the following criteria:
+---------------------
+[
+    {{
+        "name": "location name",
+        "level": "location level"
+    }}
+]
+---------------------
+
+Where "level" is represented by the following integers:
+
+---------------------
+1: Province level (provinsi)
+2: City or Regency level (kota/kabupaten)
+3: District level (kecamatan)
+4: Subdistrict level (kelurahan)
+---------------------
+
+If the location level is at level 2,
+provide an exact prefix indicating whether it is a Kota or Kabupaten.
+If the location level is at level 3 and 4,
+remove the prefix regarding to Kelurahan (`Kel.`) or Kecamatan (`Kec.`).
+
+If there are similar location name,
+you only return the most popular one based on Indonesia
+real estate trends context.
+
+For example:
+
+-------
+Given the query Bekasi
+Expected result: [
+    {{"name": "Kota Bekasi", "level": 2}},
+    {{"name": "Jawa Barat", "level": 1}}
+]
+-------
+
+-------
+Given the query Cikarang
+Expected result: [
+    {{"name": "Cikarang Selatan", "level": 3}},
+    {{"name": "Kab. Bekasi", "level": 2}},
+    {{"name": "Jawa Barat", "level": 1}}
+]
+-------
+-------
+Given the query Jakut
+Expected result: [
+    {{"name": "Kota Jakarta Utara", "level": 2}},
+    {{"name": "DKI Jakarta", "level": 1}}
+]
+-------
+-------
+Given the query Bintaro
+Expected result: [
+    {{"name": "Bintaro", "level": 4}},
+    {{"name": "Pesanggrahan", "level": 3}},
+    {{"name": "Kota Jakarta Selatan", "level": 2}},
+    {{"name": "DKI Jakarta", "level": 1}}
+]
+-------
+-------
+Given the query Kemang
+Expected result: [
+  {{"name": "Mampang Prapatan", "level": 3}},
+  {{"name": "Kota Jakarta Selatan","level": 2}},
+  {{"name": "DKI Jakarta","level": 1}}
+]
+-------
+-------
+Given the query Bali
+Expected result: [
+    {{"name": "Bali", "level": 1}}
+]
+-------
+
+# task
+Given query `{location}`
+Expected result:
+"""

pyproject.toml

@@ -9,12 +9,15 @@ packages = []
 [tool.poetry.dependencies]
 python = "^3.10"
 gradio = { version = "3.44.3", source = "pypi" }
-pydantic-settings = { version = "^2.0.3", extras = ["dotenv"], source = "pypi" }
 langchain = {version = "^0.1.7", source = "pypi"}
 langchain-openai = {version = "^0.0.6", source = "pypi"}
 tiktoken = {version = "^0.6.0", source = "pypi"}
 elasticsearch = {version = "^8.12.0", source = "pypi"}
-
+fuzzywuzzy = {version = "^0.18.0", source = "pypi"}
+python-levenshtein = {version = "^0.25.1", source = "pypi"}
+standard-logger = {path = "local_dists/standard_logger-1.1.0-py3-none-any.whl"}
+data-model = {path = "local_dists/data_model-2.9.0-py3-none-any.whl"}
+backend-clients = {path = "local_dists/backend_clients-4.5.0-py3-none-any.whl"}
 
 [tool.ruff]
 # Enable the pycodestyle (`E`) and Pyflakes (`F`) rules by default.

schemas/chatbot.py

@@ -0,0 +1,122 @@
+import json
+from enum import Enum
+
+from backend_clients.dto.omnisearch import CardLocation
+from data_model.enums.property import BuildingType, ListingType, MarketType
+from langchain_core.output_parsers import BaseOutputParser
+from pydantic import BaseModel, Field
+
+
+class PropertySearchRequest(BaseModel):
+    question: str
+    model_name: str | None = Field(None, alias="modelName")
+
+
+class SearchParams(BaseModel):
+    location: CardLocation | None = Field(None, alias="location")
+    building_type: BuildingType | None = Field(None, alias="buildingType")
+    listing_type: ListingType = Field(None, alias="listingType")
+    market_type: MarketType | None = Field(None, alias="marketType")
+    min_surface_area: int | None = Field(None, alias="minSurfaceArea")
+    max_surface_area: int | None = Field(None, alias="maxSurfaceArea")
+    max_price: int | None = Field(None, alias="maxPrice")
+    min_price: int | None = Field(None, alias="minPrice")
+    max_building_area: int | None = Field(None, alias="maxBuildingArea")
+    min_building_area: int | None = Field(None, alias="minBuildingArea")
+    max_bedroom: int | None = Field(None, alias="maxBedroom")
+    min_bedroom: int | None = Field(None, alias="minBedroom")
+    min_toilet: int | None = Field(None, alias="minToilet")
+    max_toilet: int | None = Field(None, alias="maxToilet")
+    keyword: str | None = Field(None)
+
+
+class PropertySearchObject(BaseModel):
+    search_params: SearchParams | None = Field(None, alias="searchParams")
+    search_results: list[dict] = Field([], alias="searchResults")
+    search_results_total: int = Field(0, alias="searchResultsTotal")
+
+
+class PropertySearchResponse(BaseModel):
+    data: PropertySearchObject = Field(None, alias="data")
+
+
+class IntentRoutingRequest(BaseModel):
+    question: str
+    model_name: str | None = Field(None, alias="modelName")
+
+
+class IntentRoutingObject(BaseModel):
+    intent: str
+
+
+class IntentRoutingResponse(BaseModel):
+    data: IntentRoutingObject | None = Field(None)
+
+
+class CardLocation(BaseModel):
+    id: int | None = Field(None, alias="id")
+    title: str | None = Field(None, alias="title")
+    alias: str | None = Field(None, alias="alias")
+
+
+class IntentCategories(str, Enum):
+    property_knowledge_qa = "property_knowledge_qa"
+    property_search = "property_search"
+
+
+class ImprovedBooleanOutputParser(BaseOutputParser[bool]):
+    """Parse the output of an LLM call to a boolean."""
+
+    true_val: str = "YES"
+    """The string value that should be parsed as True."""
+    false_val: str = "NO"
+    """The string value that should be parsed as False."""
+
+    def parse(self, text: str) -> bool:
+        """Parse the output of an LLM call to a boolean.
+
+        Args:
+            text: output of a language model
+
+        Returns:
+            boolean
+
+        """
+        cleaned_text = text.strip()
+        if (self.true_val.upper() not in cleaned_text.upper()) and (
+            self.false_val.upper() not in cleaned_text.upper()
+        ):
+            raise ValueError(
+                f"ImprovedBooleanOutputParser expected output value to either "
+                f"contains {self.true_val} or {self.false_val}. "
+                f"Received {cleaned_text}."
+            )
+
+        return self.true_val.upper() in cleaned_text.upper()
+
+    @property
+    def _type(self) -> str:
+        """Snake-case string identifier for an output parser type."""
+        return "improved_boolean_output_parser"
+
+
+class RouterOutputParser:
+    @staticmethod
+    def _marshal_output_to_json(output: str) -> str:
+        output = output.replace("```json", "")
+        output = output.replace("```", "")
+        output = output.strip()
+        return output
+
+    def parse(self, output: str) -> list[dict]:
+        """Parse string."""
+        try:
+            json_output = RouterOutputParser._marshal_output_to_json(output)
+            json_dicts = json.loads(json_output)
+            return json_dicts
+        except Exception as err:
+            print(
+                f"[RouterOutputParser] got error when parse {output}, "
+                f"message: {err}"
+            )
+            return []

services/intent_routing.py

@@ -0,0 +1,84 @@
+import re
+
+from openai import OpenAI
+
+from config import get_settings
+from prompts import (
+    PROPERTY_SEARCH_ROUTING_SYSTEM_PROMPT,
+    PROPERTY_SEARCH_ROUTING_USER_PROMPT,
+    SUMMARIZED_USER_QUESTION_INTENT_SYSTEM_PROMPT,
+    SUMMARIZED_USER_QUESTION_INTENT_USER_PROMPT,
+)
+from schemas.chatbot import (
+    IntentCategories,
+)
+from services.utils import get_chat_model_response, parse_message
+
+RAG_LLM_MODEL = "gpt-3.5-turbo-0125"
+
+
+LLM_CLIENT = OpenAI(
+    api_key=get_settings().openai_api_key,
+    timeout=20,
+)
+
+
+def generate_intent_routing(
+    question: str,
+    model: str | None = None,
+) -> str | None:
+    messages = [
+        {
+            "role": "system",
+            "content": PROPERTY_SEARCH_ROUTING_SYSTEM_PROMPT,
+        },
+        {
+            "role": "user",
+            "content": PROPERTY_SEARCH_ROUTING_USER_PROMPT.format(
+                question=question,
+            ),
+        },
+    ]
+
+    if model is None:
+        model = get_settings().intent_routing__chat_completion_model_name
+
+    response = get_chat_model_response(model=model, messages=messages)
+    message_content = parse_message(response=response)
+    if message_content is None:
+        return IntentCategories.property_knowledge_qa
+
+    triage_regex = r"(YES|NO)"
+    triage_match = re.search(triage_regex, message_content)
+    if triage_match is None:
+        print(
+            "improper property search intent routing prediction -> user "
+            f"question : {question}, response : {message_content}"
+        )
+        return IntentCategories.property_knowledge_qa
+
+    if triage_match.group(0) == "YES":
+        return IntentCategories.property_search
+
+    return IntentCategories.property_knowledge_qa
+
+
+def generate_user_question_intent(previous_user_conversations, question):
+    messages = [
+        {
+            "role": "system",
+            "content": SUMMARIZED_USER_QUESTION_INTENT_SYSTEM_PROMPT,
+        },
+        {
+            "role": "user",
+            "content": SUMMARIZED_USER_QUESTION_INTENT_USER_PROMPT.format_map(
+                {"contexts": previous_user_conversations, "question": question}
+            ),
+        },
+    ]
+
+    response = LLM_CLIENT.chat.completions.create(
+        model=RAG_LLM_MODEL, messages=messages, temperature=0
+    )
+
+    return response

services/property_knowledge.py

@@ -0,0 +1,150 @@
+# Suppress all UserWarnings
+import warnings
+from typing import Any
+
+from langchain.retrievers import ContextualCompressionRetriever
+from langchain.retrievers.document_compressors import LLMChainFilter
+from langchain.retrievers.document_compressors.chain_filter_prompt import (
+    prompt_template,
+)
+from langchain.schema import StrOutputParser
+from langchain_community.vectorstores.elasticsearch import ElasticsearchStore
+from langchain_core.documents import Document
+from langchain_core.prompts import ChatPromptTemplate, PromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+from langchain_core.runnables.base import RunnableSerializable
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+
+from config import get_settings
+from prompts import (
+    CONTEXT_TEMPLATE,
+    QA_WITH_CONTEXT_PROMPT,
+    SYSTEM_PROMPT,
+)
+from schemas.chatbot import ImprovedBooleanOutputParser
+from services.utils import parse_response
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+EMBEDDING_MODEL = "text-embedding-3-large"
+RAG_LLM_MODEL = "gpt-3.5-turbo-0125"
+NROF_RETRIEVED_CONTEXT = 5
+
+
+# ES only support up to 2048 embedding dimension
+embeddings = OpenAIEmbeddings(
+    model=EMBEDDING_MODEL,
+    api_key=get_settings().openai_api_key,
+    dimensions=2048,
+    timeout=20,
+)
+
+vector_db = ElasticsearchStore(
+    es_url=get_settings().es_url,
+    index_name=get_settings().collection_index_name,
+    embedding=embeddings,
+)
+
+llm = ChatOpenAI(
+    model_name=RAG_LLM_MODEL,
+    temperature=0,
+    api_key=get_settings().openai_api_key,
+    timeout=20,
+)
+
+
+qa_prompt = ChatPromptTemplate.from_messages(
+    [
+        ("system", SYSTEM_PROMPT),
+        ("human", QA_WITH_CONTEXT_PROMPT),
+    ]
+)
+
+
+_filter = LLMChainFilter.from_llm(
+    llm,
+    prompt=PromptTemplate(
+        template=prompt_template,
+        input_variables=["question", "context"],
+        output_parser=ImprovedBooleanOutputParser(),
+    ),
+)
+docs_retriever = vector_db.as_retriever(
+    search_kwargs={"k": NROF_RETRIEVED_CONTEXT}
+)
+
+
+def format_contexts(docs: list[Document]) -> str:
+    aggregate_context = ""
+    for doc in docs:
+        context = CONTEXT_TEMPLATE.format(
+            source=doc.metadata["content_id"],
+            title=doc.metadata["content_title"],
+            content=doc.page_content,
+        )
+
+        aggregate_context += context
+
+    return aggregate_context
+
+
+docs_compression_retriever = ContextualCompressionRetriever(
+    base_compressor=_filter, base_retriever=docs_retriever
+)
+
+
+def get_end_device_target(*args: Any) -> str:
+    return "mobile"
+
+
+rag_chain: RunnableSerializable = (
+    {
+        "context": RunnablePassthrough(),
+        "device": get_end_device_target,
+        "question": RunnablePassthrough(),
+        "chat_histories": RunnablePassthrough(),
+        "question_intent": RunnablePassthrough(),
+    }
+    | qa_prompt
+    | llm
+    | StrOutputParser()
+)
+
+
+def compress_knowledge_docs(
+    collection: ElasticsearchStore,
+    question: str,
+):
+    docs_retriever = collection.as_retriever(search_kwargs={"k": 5})
+
+    _filter = LLMChainFilter.from_llm(
+        llm,
+        prompt=PromptTemplate(
+            template=prompt_template,
+            input_variables=["question", "context"],
+            output_parser=ImprovedBooleanOutputParser(),
+        ),
+    )
+    docs_compression_retriever = ContextualCompressionRetriever(
+        base_retriever=docs_retriever, base_compressor=_filter
+    )
+
+    relevant_docs = docs_compression_retriever.invoke(question)
+    return relevant_docs
+
+
+def generate_property_knowledge_answer(summarized_user_question_intent):
+    relevant_docs = compress_knowledge_docs(
+        vector_db, summarized_user_question_intent
+    )
+    formatted_contexts = format_contexts(relevant_docs)
+
+    response = rag_chain.invoke(
+        {
+            "context": formatted_contexts,
+            "question": summarized_user_question_intent,
+        }
+    )
+
+    answer, _ = parse_response(response)
+    return answer

services/property_search.py

@@ -0,0 +1,537 @@
+# Suppress all UserWarnings
+import json
+import warnings
+from http import HTTPStatus
+
+from backend_clients.services.bff.omnisearch import (
+    OmnisearchClient,
+    OmnisearchWithFallbackRequest,
+    OmnisearchWithFallbackResponse,
+)
+from backend_clients.services.location_api.es import (
+    ESClient,
+    ESSuggestLocationListRequest,
+    LocationSuggestionResponse,
+)
+from data_model.enums.property import (
+    BuildingType,
+    DeveloperProjectStatus,
+    EntityType,
+    ListingType,
+    MarketType,
+    PropertyUnitStatus,
+)
+from fuzzywuzzy import fuzz
+
+from config import get_settings
+from prompts import (
+    LOCATION_LEVEL_FINDER_SYSTEM_MSG,
+    LOCATION_LEVEL_FINDER_USER_PROMPT,
+    PROPERTY_SEARCH_FUNCTION_CALLING_PROMPT,
+    PROPERTY_TEXT_PARSER_SYSTEM_MSG,
+)
+from schemas.chatbot import CardLocation, RouterOutputParser, SearchParams
+from services.utils import (
+    get_chat_model_response,
+    parse_message,
+    parse_tools_message,
+)
+
+warnings.filterwarnings("ignore", category=UserWarning)
+
+
+DEFAULT_SIZE = 20
+LISTED_LOCATION_LEVEL_FIELDS = [
+    "provinceTitle",
+    "cityTitle",
+    "districtTitle",
+    "subDistrictTitle",
+]
+FILTERED_PARAMS = [
+    "name",
+    "minPrice",
+    "maxPrice",
+    "city",
+    "district",
+    "subDistrict",
+    "specifications",
+]
+
+
+def parse_text_to_user_preference(
+    user_question: str,
+    model: str = get_settings().property_search__chat_completion_model_name,
+) -> dict | None:
+    prompt_messages = [
+        {
+            "role": "system",
+            "content": PROPERTY_TEXT_PARSER_SYSTEM_MSG,
+        },
+        {
+            "role": "user",
+            "content": user_question,
+        },
+    ]
+
+    parsed_user_preference_response = get_chat_model_response(
+        model=model,
+        messages=prompt_messages,
+        tools=PROPERTY_SEARCH_FUNCTION_CALLING_PROMPT,
+    )
+
+    parsed_user_preference = parse_tools_message(
+        parsed_user_preference_response
+    )
+    return parsed_user_preference
+
+
+def get_location_detail_by_keyword(
+    location_keyword: str,
+    model="gpt-3.5-turbo-1106",
+):
+    """
+    Retrieves the location details based on a given keyword.
+
+    Args:
+        location_keyword (str):
+            The keyword used to search for location details.
+        model (str, optional):
+            The model to use for generating the response.
+            Defaults to "gpt-3.5-turbo-1106".
+
+    Returns:
+        dict: The location details retrieved based on the keyword.
+    """
+    if location_keyword is None or location_keyword == "":
+        return None
+
+    prompt_messages = [
+        {
+            "role": "system",
+            "content": LOCATION_LEVEL_FINDER_SYSTEM_MSG,
+        },
+        {
+            "role": "user",
+            "content": LOCATION_LEVEL_FINDER_USER_PROMPT.format(
+                location=location_keyword
+            ),
+        },
+    ]
+
+    response = get_chat_model_response(model=model, messages=prompt_messages)
+
+    parsed_content_message = parse_message(response)
+    location_details = RouterOutputParser().parse(parsed_content_message)
+    return location_details
+
+
+def _get_list_of_location_candidates(
+    detail_locations: list[dict[str, str | int]],
+) -> LocationSuggestionResponse | None:
+    """
+    Retrieves a list of location candidates based on
+    the given list of detailed locations.
+
+    Note: we skip the first level (province),
+    because it is too broad/wide
+
+    Args:
+        detail_locations (list[dict[str, str | int]]):
+            A list of dictionaries representing detailed locations.
+            Each dictionary should have the following keys:
+            - "name" (str): The name of the location.
+            - "level" (str | int): The level of the location.
+
+    Returns:
+        LocationSuggestionResponse | None:
+            A response object containing the location candidates.
+            Returns None if no candidates are found.
+    """
+    location_api_es_client = ESClient()
+
+    location_candidates = None
+    for location_obj in reversed(detail_locations):
+        search_keyword = location_obj["name"].split(".")[-1]
+
+        location_search_level = location_obj["level"]
+        if location_search_level == 1:
+            return None
+
+        response = location_api_es_client.get_location_suggestions(
+            request=ESSuggestLocationListRequest(
+                search=search_keyword,
+                levels=location_search_level,
+                size=DEFAULT_SIZE,
+            )
+        )
+        if response.status_code == HTTPStatus.OK and response.data is not None:
+            location_candidates: LocationSuggestionResponse = response.data
+            break
+
+    return location_candidates
+
+
+def _get_most_similar_location(
+    location_candidates: list[LocationSuggestionResponse],
+    detail_locations: list[dict[str, str | int]],
+) -> dict[str, str | int]:
+    """
+    Find the most similar location candidate based on
+    a list of location candidates and a list of detail locations.
+
+    Args:
+        location_candidates (list[LocationSuggestionResponse]):
+            A list of location candidates.
+        detail_locations (list[dict[str, str | int]]):
+            A list of detail locations.
+
+    Returns:
+        dict[str, str | int]:
+            The best location candidate with the highest similarity score.
+    """
+    best_similarity_score = 0
+    best_location_candidate = None
+
+    merged_location_title_ref = "-".join(
+        detail_location["name"] for detail_location in detail_locations
+    )
+
+    for location_obj_candidate in location_candidates:
+        location_candidate_dict = location_obj_candidate.dict(
+            exclude_none=True, by_alias=True
+        )
+
+        level = location_candidate_dict["level"]
+        filtered_location_fields = LISTED_LOCATION_LEVEL_FIELDS[:level]
+
+        merged_location_title = ""
+        for location_field in filtered_location_fields:
+            location_field_value = location_candidate_dict[location_field]
+            if location_field_value is not None:
+                merged_location_title += location_field_value + "-"
+
+        similarity_score = fuzz.ratio(
+            merged_location_title_ref, merged_location_title
+        )
+        if similarity_score > best_similarity_score:
+            best_similarity_score = similarity_score
+            best_location_candidate = location_candidate_dict
+
+    if (
+        best_similarity_score
+        < get_settings().property_search__location_similarity_thres
+    ):
+        return None
+
+    return best_location_candidate
+
+
+def get_most_similar_pinhome_location(
+    detail_locations: list[dict[str, str | int]]
+) -> dict[str, str | int]:
+    """
+    Get the most similar pinhome location based on a list of detail locations.
+
+    Args:
+        detail_locations (list[dict[str, str | int]]):
+            A list of detail locations, each represented as a dictionary with
+            keys "level" (int), "title" (str), and "alias" (str).
+    Returns:
+        dict[str, str | int]:
+            The most similar pinhome location, represented as a dictionary with
+            keys "level" (int), "title" (str), and "alias" (str).
+    """
+    detail_locations = sorted(
+        detail_locations,
+        key=lambda x: x["level"],
+        reverse=False,
+    )
+
+    location_candidates = _get_list_of_location_candidates(detail_locations)
+    if location_candidates is None:
+        return None
+
+    most_similar_location_obj = _get_most_similar_location(
+        location_candidates, detail_locations
+    )
+    return most_similar_location_obj
+
+
+def construct_pinhome_card_location(most_similar_location_obj: dict):
+    """
+    Constructs a `CardLocation` object based on the provided
+    `most_similar_location_obj` and `parsed_location_param`.
+
+    Parameters:
+        most_similar_location_obj (dict):
+            A dictionary representing the most similar location object.
+            It should contain the following keys:
+                - matchId (str): The ID of the location.
+                - title (str): The title of the location.
+
+    Returns:
+        CardLocation: A `CardLocation` object with the following attributes:
+            - id (str): The ID of the location.
+            - title (str): The title of the location.
+            - alias (str): The alias location.
+    """
+    location_id = most_similar_location_obj.get("matchId", None)
+    location_title = most_similar_location_obj.get("title", None)
+    location_alias = most_similar_location_obj.get("match", None)
+
+    return CardLocation(
+        id=location_id,
+        title=location_title,
+        alias=location_alias,
+    )
+
+
+def _set_base_query_params(
+    omnisearch_request: OmnisearchWithFallbackRequest,
+) -> OmnisearchWithFallbackRequest:
+    """
+    Set base query based on market type.
+
+    Args:
+        omnisearch_request (OmnisearchWithFallbackRequest):
+            The omnisearch parameters.
+
+    Returns:
+        OmnisearchWithFallbackRequest:
+            The Omnisearch response data.
+    """
+    match omnisearch_request.market_type:
+        case MarketType.primary:
+            omnisearch_request.entity_type = EntityType.project
+            omnisearch_request.status = DeveloperProjectStatus.active
+        case MarketType.secondary:
+            omnisearch_request.entity_type = EntityType.propertyunit
+            omnisearch_request.status = PropertyUnitStatus.active
+        case _:
+            omnisearch_request.entity_type = ",".join(
+                [EntityType.project, EntityType.propertyunit]
+            )
+            omnisearch_request.status = ",".join(
+                [DeveloperProjectStatus.active, PropertyUnitStatus.active]
+            )
+
+    return omnisearch_request
+
+
+def get_omnisearch_exact_with_fallback(
+    search_params: SearchParams,
+) -> OmnisearchWithFallbackResponse | None:
+    """
+    Get the exact Omnisearch result with fallback if necessary.
+
+    Args:
+        search_params (SearchParams):
+            The search parameters.
+
+    Returns:
+        OmnisearchWithFallbackResponse | None:
+            The Omnisearch response data if available,
+            or None if no data is found.
+    """
+    omnisearch_client = OmnisearchClient()
+
+    search_limit = get_settings().property_search__limit_search_size
+
+    parsed_location = search_params.keyword
+    if (
+        search_params.location is not None
+        and search_params.location.id is not None
+    ):
+        search_params.keyword = None
+
+    omnisearch_request = OmnisearchWithFallbackRequest(
+        **search_params.dict(exclude_none=True, by_alias=True),
+    )
+    omnisearch_request = _set_base_query_params(omnisearch_request)
+
+    response = omnisearch_client.get_omnisearch_exact_with_fallback(
+        omnisearch_request, search_limit
+    )
+
+    search_params.keyword = parsed_location
+    return response.data
+
+
+def enrich_parsed_location_params(
+    parsed_params: dict,
+) -> dict:
+    """
+    Enriches the parsed location parameters.
+
+    Args:
+        parsed_params (dict):
+            The dictionary containing the parsed parameters.
+
+    Returns:
+        dict: The enriched parsed parameters.
+    """
+    parsed_location_param = parsed_params.get("keyword", None)
+
+    if parsed_location_param is not None:
+        detail_locations = get_location_detail_by_keyword(
+            location_keyword=parsed_location_param
+        )
+
+        if detail_locations is not None:
+            most_similar_pinhome_location = get_most_similar_pinhome_location(
+                detail_locations
+            )
+
+            if most_similar_pinhome_location is not None:
+                location_params = construct_pinhome_card_location(
+                    most_similar_location_obj=most_similar_pinhome_location,
+                )
+                parsed_params["location"] = location_params
+
+    return parsed_params
+
+
+def _generate_price_range(search_params: SearchParams) -> SearchParams:
+    """
+    Generates a price range for the given search parameters.
+
+    Args:
+        search_params (SearchParams):
+            The search parameters.
+
+    Returns:
+        SearchParams:
+            The search parameters with the generated price range.
+    """
+    if search_params.min_price is None and search_params.max_price is None:
+        return search_params
+
+    if search_params.min_price == search_params.max_price:
+        search_params.min_price = round(
+            search_params.min_price
+            * (1 - get_settings().property_search__exact_price_range_thres)
+        )
+
+    if search_params.min_price is not None and search_params.max_price is None:
+        price = search_params.min_price
+
+        search_params.max_price = round(
+            price
+            * (1 + get_settings().property_search__limit_price_range_thres)
+        )
+
+    if search_params.min_price is None and search_params.max_price is not None:
+        price = search_params.max_price
+
+        search_params.min_price = round(
+            price
+            * (1 - get_settings().property_search__limit_price_range_thres)
+        )
+
+    return search_params
+
+
+def _generate_value_range(
+    min_value: float | None,
+    max_value: float | None,
+    value_threshold: float = 0.1,
+) -> tuple[float, float]:
+    """
+    Generates a value range for the given search parameters.
+
+    Args:
+        min_value (float | None):
+            The mininum search parameters value.
+        max_value (float | None):
+            The maximum search parameters value.
+        value_threshold (float | None):
+            The value threshold range.
+
+    Returns:
+        tuple[float, float]:
+            The search parameters with the generated value range.
+    """
+    if min_value is None and max_value is None:
+        return min_value, max_value
+
+    if min_value == max_value:
+        value = min_value
+
+        min_value = round(value * (1 - value_threshold))
+        max_value = round(value * (1 + value_threshold))
+
+    return min_value, max_value
+
+
+def construct_search_params(parsed_params: dict):
+    """
+    Constructs the search parameters object from the parsed parameters.
+
+    Parameters:
+        parsed_params (dict):
+            A dictionary containing the parsed parameters.
+
+    Returns:
+        search_params (SearchParams):
+            The constructed search parameters object.
+
+    """
+    search_params = SearchParams(**parsed_params)
+
+    if search_params.building_type is None:
+        search_params.building_type = BuildingType.house
+
+    if search_params.listing_type is None:
+        search_params.listing_type = ListingType.sell
+
+    search_params = _generate_price_range(search_params=search_params)
+
+    value_threshold = get_settings().property_search__value_range_thres
+    (
+        search_params.min_surface_area,
+        search_params.max_surface_area,
+    ) = _generate_value_range(
+        search_params.min_surface_area,
+        search_params.max_surface_area,
+        value_threshold,
+    )
+
+    (
+        search_params.min_building_area,
+        search_params.max_building_area,
+    ) = _generate_value_range(
+        search_params.min_building_area,
+        search_params.max_building_area,
+        value_threshold,
+    )
+    return search_params
+
+
+def search_property_listing(user_question):
+    parsed_params = parse_text_to_user_preference(
+        user_question=user_question,
+    )
+    if parsed_params is None:
+        parsed_params = {}
+    else:
+        parsed_params = enrich_parsed_location_params(
+            parsed_params=parsed_params
+        )
+
+    search_params = construct_search_params(parsed_params=parsed_params)
+
+    omnisearch_result = get_omnisearch_exact_with_fallback(
+        search_params=search_params
+    )
+
+    filter_results = []
+    for result in omnisearch_result.result_list:
+        filtered_values = {}
+        for filtered_param in FILTERED_PARAMS:
+            if filtered_param in result.keys():
+                filtered_values.update(
+                    {filtered_param: result[filtered_param]}
+                )
+        filter_results.append(filtered_values)
+
+    return json.dumps(filter_results, indent=4)

services/utils.py

@@ -0,0 +1,95 @@
+import json
+import re
+
+# Suppress all UserWarnings
+from openai import OpenAI
+
+from config import get_settings
+
+LLM_CLIENT = OpenAI(
+    api_key=get_settings().openai_api_key,
+    timeout=20,
+)
+
+
+def parse_response(response: str) -> tuple[str, list[dict] | None]:
+    answer_match = re.search(
+        r"\[ANSWER\]\n(.+?)(?=\n\[(.*?)\])", response, re.DOTALL
+    )
+    related_docs_match = re.search(r"\[REFERENCE\]\n(.+)", response, re.DOTALL)
+
+    if answer_match:
+        answer = answer_match.group(1).strip()
+        related_docs = None
+
+        if related_docs_match:
+            related_docs_str = (
+                related_docs_match.group(1).strip().replace("```", "")
+            )
+            try:
+                related_docs = json.loads(related_docs_str)
+            except Exception:
+                print(f"failed to parse related docs: {related_docs_str}")
+
+        return answer, related_docs
+
+    raise ValueError(f"failed to parse response: {response}")
+
+
+def parse_histories(histories: list[str, str]):
+    conversational_histories = []
+    for history in histories:
+        user_message, assistant_message = history
+        conversational_histories.extend(
+            [
+                {"role": "user", "content": user_message},
+                {"role": "assistant", "content": assistant_message},
+            ]
+        )
+
+    return conversational_histories
+
+
+def get_chat_model_response(
+    model: str,
+    messages: list[str],
+    temperature: float = 0,
+    tools: list | None = None,
+):
+    if tools is not None:
+        chat_model_response = LLM_CLIENT.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+            tools=tools,
+        )
+    else:
+        chat_model_response = LLM_CLIENT.chat.completions.create(
+            model=model,
+            messages=messages,
+            temperature=temperature,
+        )
+
+    return chat_model_response
+
+
+def parse_tools_message(response) -> dict:
+    response_choices = response.choices
+    if len(response_choices) == 0:
+        return None
+
+    tool_calls_response = response_choices[0].message.tool_calls
+    if not tool_calls_response:
+        return None
+
+    response_choice_argument = tool_calls_response[0].function.arguments
+    response_choice_argument_dict = json.loads(response_choice_argument)
+    return response_choice_argument_dict
+
+
+def parse_message(response) -> str | None:
+    response_choices = response.choices
+    if len(response.choices) == 0:
+        return None
+
+    return response_choices[0].message.content