(refactor) update launch configurations and remove obsolete tasks.json

Test coverage for parsers

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -113,6 +113,7 @@ venv.bak/
 # Spyder project settings
 .spyderproject
 .spyproject
+.jwt_secret_key
 
 # Rope project settings
 .ropeproject

.vscode/launch.json

@@ -2,15 +2,11 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Docker Debug Frontend",
+      "name": "Frontend Debug (npm)",
+      "type": "node-terminal",
       "request": "launch",
-      "type": "chrome",
-      "preLaunchTask": "docker-compose: debug:frontend",
-      "url": "http://127.0.0.1:5173",
-      "webRoot": "${workspaceFolder}/frontend",
-      "skipFiles": [
-        "<node_internals>/**"
-      ]
+      "command": "npm run dev",
+      "cwd": "${workspaceFolder}/frontend"
     },
     {
         "name": "Flask Debugger",
@@ -49,6 +45,27 @@
         "--pool=solo"
       ],
       "cwd": "${workspaceFolder}"
+    },
+    {
+      "name": "Dev Containers (Mongo + Redis)",
+      "type": "node-terminal",
+      "request": "launch",
+      "command": "docker compose -f deployment/docker-compose-dev.yaml up --build",
+      "cwd": "${workspaceFolder}"
+    }
+  ],
+  "compounds": [
+    {
+      "name": "DocsGPT: Full Stack",
+      "configurations": [
+        "Frontend Debug (npm)",
+        "Flask Debugger",
+        "Celery Debugger"
+      ],
+      "presentation": {
+        "group": "DocsGPT",
+        "order": 1
+      }
     }
   ]
 }

.vscode/tasks.json

@@ -1,21 +0,0 @@
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "type": "docker-compose",
-      "label": "docker-compose: debug:frontend",
-      "dockerCompose": {
-        "up": {
-          "detached": true,
-          "services": [
-            "frontend"
-          ],
-          "build": true
-        },
-        "files": [
-          "${workspaceFolder}/docker-compose.yaml"
-        ]
-      }
-    }
-  ]
-}

README.md

@@ -3,11 +3,11 @@
 </h1>
 
 <p align="center">
-  <strong>Open-Source RAG Assistant</strong>
+  <strong>Private AI for agents, assistants and enterprise search</strong>
 </p>
 
 <p align="left">
-  <strong><a href="https://www.docsgpt.cloud/">DocsGPT</a></strong> is an open-source genAI tool that helps users get reliable answers from any knowledge source, while avoiding hallucinations. It enables quick and reliable information retrieval, with tooling and agentic system capability built in.
+  <strong><a href="https://www.docsgpt.cloud/">DocsGPT</a></strong> is an open-source AI platform for building intelligent agents and assistants. Features Agent Builder, deep research tools, document analysis (PDF, Office, web content), Multi-model support (choose your provider or run locally), and rich API connectivity for agents with actionable tools and integrations. Deploy anywhere with complete privacy control.
 </p>
 
 <div align="center">
@@ -19,10 +19,10 @@
   <a href="https://discord.gg/n5BX8dh8rU">![link to discord](https://img.shields.io/discord/1070046503302877216)</a>
   <a href="https://twitter.com/docsgptai">![X (formerly Twitter) URL](https://img.shields.io/twitter/follow/docsgptai)</a>
 
-  <a href="https://docs.docsgpt.cloud/quickstart">⚡️ Quickstart</a> • <a href="https://app.docsgpt.cloud/">☁️ Cloud Version</a> • <a href="https://discord.gg/n5BX8dh8rU">💬 Discord</a>
-  <br>
-  <a href="https://docs.docsgpt.cloud/">📖 Documentation</a> • <a href="https://github.com/arc53/DocsGPT/blob/main/CONTRIBUTING.md">👫 Contribute</a> • <a href="https://blog.docsgpt.cloud/">🗞 Blog</a>
-  <br>
+<a href="https://docs.docsgpt.cloud/quickstart">⚡️ Quickstart</a> • <a href="https://app.docsgpt.cloud/">☁️ Cloud Version</a> • <a href="https://discord.gg/n5BX8dh8rU">💬 Discord</a>
+<br>
+<a href="https://docs.docsgpt.cloud/">📖 Documentation</a> • <a href="https://github.com/arc53/DocsGPT/blob/main/CONTRIBUTING.md">👫 Contribute</a> • <a href="https://blog.docsgpt.cloud/">🗞 Blog</a>
+<br>
 
 </div>
 <div align="center">
@@ -48,10 +48,19 @@
 - [x] Add tools (Jan 2025)
 - [x] Manually updating chunks in the app UI (Feb 2025)
 - [x] Devcontainer for easy development (Feb 2025)
-- [ ] Anthropic Tool compatibility
-- [ ] Add triggerable actions / tools (webhook)
-- [ ] Add OAuth 2.0 authentication for tools and sources
-- [ ] Chatbots menu re-design to handle tools, scheduling, and more
+- [x] ReACT agent (March 2025)
+- [x] Chatbots menu re-design to handle tools, agent types, and more (April 2025)
+- [x] New input box in the conversation menu (April 2025)
+- [x] Add triggerable actions / tools (webhook) (April 2025)
+- [x] Agent optimisations (May 2025)
+- [x] Filesystem sources update (July 2025)
+- [x] Json Responses (August 2025)
+- [x] MCP support (August 2025)
+- [x] Google Drive integration (September 2025)
+- [ ] Add OAuth 2.0 authentication for MCP (September 2025)
+- [ ] Sharepoint integration (October 2025)
+- [ ] Deep Agents (October 2025)
+- [ ] Agent scheduling
 
 You can find our full roadmap [here](https://github.com/orgs/arc53/projects/2). Please don't hesitate to contribute or create issues, it helps us improve DocsGPT!
 
@@ -65,11 +74,10 @@ We're eager to provide personalized assistance when deploying your DocsGPT to a
 
 ## Join the Lighthouse Program 🌟
 
-Calling all developers and GenAI innovators! The **DocsGPT Lighthouse Program** connects technical leaders actively deploying or extending DocsGPT in real-world scenarios. Collaborate directly with our team to shape the roadmap, access priority support, and build enterprise-ready solutions with exclusive community insights.  
+Calling all developers and GenAI innovators! The **DocsGPT Lighthouse Program** connects technical leaders actively deploying or extending DocsGPT in real-world scenarios. Collaborate directly with our team to shape the roadmap, access priority support, and build enterprise-ready solutions with exclusive community insights.
 
 [Learn More & Apply →](https://docs.google.com/forms/d/1KAADiJinUJ8EMQyfTXUIGyFbqINNClNR3jBNWq7DgTE)
 
-
 ## QuickStart
 
 > [!Note]
@@ -92,13 +100,15 @@ A more detailed [Quickstart](https://docs.docsgpt.cloud/quickstart) is available
    ./setup.sh
    ```
 
-This interactive script will guide you through setting up DocsGPT. It offers four options: using the public API, running locally, connecting to a local inference engine, or using a cloud API provider.  The script will automatically configure your `.env` file and handle necessary downloads and installations based on your chosen option.
-
 **For Windows:**
 
-2. **Follow the Docker Deployment Guide:**
+2. **Run the PowerShell setup script:**
 
-   Please refer to the [Docker Deployment documentation](https://docs.docsgpt.cloud/Deploying/Docker-Deploying) for detailed step-by-step instructions on setting up DocsGPT using Docker. 
+   ```powershell
+   PowerShell -ExecutionPolicy Bypass -File .\setup.ps1
+   ```
+
+Either script will guide you through setting up DocsGPT. Four options available: using the public API, running locally, connecting to a local inference engine, or using a cloud API provider. Scripts will automatically configure your `.env` file and handle necessary downloads and installations based on your chosen option.
 
 **Navigate to http://localhost:5173/**
 
@@ -107,7 +117,8 @@ To stop DocsGPT, open a terminal in the `DocsGPT` directory and run:
 ```bash
 docker compose -f deployment/docker-compose.yaml down
 ```
-(or use the specific `docker compose down` command shown after running `setup.sh`).
+
+(or use the specific `docker compose down` command shown after running the setup script).
 
 > [!Note]
 > For development environment setup instructions, please refer to the [Development Environment Guide](https://docs.docsgpt.cloud/Deploying/Development-Environment).
@@ -134,7 +145,6 @@ Please refer to the [CONTRIBUTING.md](CONTRIBUTING.md) file for information abou
 
 We as members, contributors, and leaders, pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. Please refer to the [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) file for more information about contributing.
 
-
 ## Many Thanks To Our Contributors⚡
 
 <a href="https://github.com/arc53/DocsGPT/graphs/contributors" alt="View Contributors">

application/Dockerfile

@@ -84,4 +84,4 @@ EXPOSE 7091
 USER appuser
 
 # Start Gunicorn
-CMD ["gunicorn", "-w", "2", "--timeout", "120", "--bind", "0.0.0.0:7091", "application.wsgi:app"]
+CMD ["gunicorn", "-w", "1", "--timeout", "120", "--bind", "0.0.0.0:7091", "--preload", "application.wsgi:app"]

application/agents/agent_creator.py

@@ -1,9 +1,11 @@
 from application.agents.classic_agent import ClassicAgent
+from application.agents.react_agent import ReActAgent
 
 
 class AgentCreator:
     agents = {
         "classic": ClassicAgent,
+        "react": ReActAgent,
     }
 
     @classmethod
@@ -11,7 +13,4 @@ class AgentCreator:
         agent_class = cls.agents.get(type.lower())
         if not agent_class:
             raise ValueError(f"No agent class found for type {type}")
-        config = kwargs.pop('config', None)
-        if isinstance(config, dict) and 'proxy_id' in config and 'proxy_id' not in kwargs:
-            kwargs['proxy_id'] = config['proxy_id']
         return agent_class(*args, **kwargs)

application/agents/base.py

@@ -1,54 +1,101 @@
-from typing import Dict, Generator
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from typing import Dict, Generator, List, Optional
+
+from bson.objectid import ObjectId
 
-from application.agents.llm_handler import get_llm_handler
 from application.agents.tools.tool_action_parser import ToolActionParser
 from application.agents.tools.tool_manager import ToolManager
-
 from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.llm.handlers.handler_creator import LLMHandlerCreator
 from application.llm.llm_creator import LLMCreator
+from application.logging import build_stack_data, log_activity, LogContext
+from application.retriever.base import BaseRetriever
+
+logger = logging.getLogger(__name__)
 
 
-class BaseAgent:
+class BaseAgent(ABC):
     def __init__(
         self,
-        endpoint,
-        llm_name,
-        gpt_model,
-        api_key,
-        user_api_key=None,
-        decoded_token=None,
-        proxy_id=None,
+        endpoint: str,
+        llm_name: str,
+        gpt_model: str,
+        api_key: str,
+        user_api_key: Optional[str] = None,
+        prompt: str = "",
+        chat_history: Optional[List[Dict]] = None,
+        decoded_token: Optional[Dict] = None,
+        attachments: Optional[List[Dict]] = None,
+        json_schema: Optional[Dict] = None,
     ):
         self.endpoint = endpoint
+        self.llm_name = llm_name
+        self.gpt_model = gpt_model
+        self.api_key = api_key
+        self.user_api_key = user_api_key
+        self.prompt = prompt
+        self.decoded_token = decoded_token or {}
+        self.user: str = decoded_token.get("sub")
+        self.tool_config: Dict = {}
+        self.tools: List[Dict] = []
+        self.tool_calls: List[Dict] = []
+        self.chat_history: List[Dict] = chat_history if chat_history is not None else []
         self.llm = LLMCreator.create_llm(
             llm_name,
             api_key=api_key,
             user_api_key=user_api_key,
             decoded_token=decoded_token,
         )
-        self.llm_handler = get_llm_handler(llm_name)
-        self.gpt_model = gpt_model
-        self.tools = []
-        self.tool_config = {}
-        self.tool_calls = []
-        self.proxy_id = proxy_id
+        self.llm_handler = LLMHandlerCreator.create_handler(
+            llm_name if llm_name else "default"
+        )
+        self.attachments = attachments or []
+        self.json_schema = json_schema
 
-    def gen(self, *args, **kwargs) -> Generator[Dict, None, None]:
-        raise NotImplementedError('Method "gen" must be implemented in the child class')
+    @log_activity()
+    def gen(
+        self, query: str, retriever: BaseRetriever, log_context: LogContext = None
+    ) -> Generator[Dict, None, None]:
+        yield from self._gen_inner(query, retriever, log_context)
+
+    @abstractmethod
+    def _gen_inner(
+        self, query: str, retriever: BaseRetriever, log_context: LogContext
+    ) -> Generator[Dict, None, None]:
+        pass
+
+    def _get_tools(self, api_key: str = None) -> Dict[str, Dict]:
+        mongo = MongoDB.get_client()
+        db = mongo[settings.MONGO_DB_NAME]
+        agents_collection = db["agents"]
+        tools_collection = db["user_tools"]
+
+        agent_data = agents_collection.find_one({"key": api_key or self.user_api_key})
+        tool_ids = agent_data.get("tools", []) if agent_data else []
+
+        tools = (
+            tools_collection.find(
+                {"_id": {"$in": [ObjectId(tool_id) for tool_id in tool_ids]}}
+            )
+            if tool_ids
+            else []
+        )
+        tools = list(tools)
+        tools_by_id = {str(tool["_id"]): tool for tool in tools} if tools else {}
+
+        return tools_by_id
 
     def _get_user_tools(self, user="local"):
         mongo = MongoDB.get_client()
-        db = mongo["docsgpt"]
+        db = mongo[settings.MONGO_DB_NAME]
         user_tools_collection = db["user_tools"]
         user_tools = user_tools_collection.find({"user": user, "status": True})
         user_tools = list(user_tools)
-        tools_by_id = {str(tool["_id"]): tool for tool in user_tools}
-        if hasattr(self, 'proxy_id') and self.proxy_id:
-            for tool_id, tool in tools_by_id.items():
-                if 'config' not in tool:
-                    tool['config'] = {}
-                tool['config']['proxy_id'] = self.proxy_id
-        return tools_by_id
+
+        return {str(i): tool for i, tool in enumerate(user_tools)}
 
     def _build_tool_parameters(self, action):
         params = {"type": "object", "properties": {}, "required": []}
@@ -92,6 +139,49 @@ class BaseAgent:
         parser = ToolActionParser(self.llm.__class__.__name__)
         tool_id, action_name, call_args = parser.parse_args(call)
 
+        call_id = getattr(call, "id", None) or str(uuid.uuid4())
+
+        # Check if parsing failed
+        if tool_id is None or action_name is None:
+            error_message = f"Error: Failed to parse LLM tool call. Tool name: {getattr(call, 'name', 'unknown')}"
+            logger.error(error_message)
+
+            tool_call_data = {
+                "tool_name": "unknown",
+                "call_id": call_id,
+                "action_name": getattr(call, "name", "unknown"),
+                "arguments": call_args or {},
+                "result": f"Failed to parse tool call. Invalid tool name format: {getattr(call, 'name', 'unknown')}",
+            }
+            yield {"type": "tool_call", "data": {**tool_call_data, "status": "error"}}
+            self.tool_calls.append(tool_call_data)
+            return "Failed to parse tool call.", call_id
+
+        # Check if tool_id exists in available tools
+        if tool_id not in tools_dict:
+            error_message = f"Error: Tool ID '{tool_id}' extracted from LLM call not found in available tools_dict. Available IDs: {list(tools_dict.keys())}"
+            logger.error(error_message)
+
+            # Return error result
+            tool_call_data = {
+                "tool_name": "unknown",
+                "call_id": call_id,
+                "action_name": f"{action_name}_{tool_id}",
+                "arguments": call_args,
+                "result": f"Tool with ID {tool_id} not found. Available tools: {list(tools_dict.keys())}",
+            }
+            yield {"type": "tool_call", "data": {**tool_call_data, "status": "error"}}
+            self.tool_calls.append(tool_call_data)
+            return f"Tool with ID {tool_id} not found.", call_id
+
+        tool_call_data = {
+            "tool_name": tools_dict[tool_id]["name"],
+            "call_id": call_id,
+            "action_name": f"{action_name}_{tool_id}",
+            "arguments": call_args,
+        }
+        yield {"type": "tool_call", "data": {**tool_call_data, "status": "pending"}}
+
         tool_data = tools_dict[tool_id]
         action_data = (
             tool_data["config"]["actions"][action_name]
@@ -116,14 +206,12 @@ class BaseAgent:
                 for param, details in action_data[param_type]["properties"].items():
                     if param not in call_args and "value" in details:
                         target_dict[param] = details["value"]
-
         for param, value in call_args.items():
             for param_type, target_dict in param_types.items():
                 if param_type in action_data and param in action_data[param_type].get(
                     "properties", {}
                 ):
                     target_dict[param] = value
-
         tm = ToolManager(config={})
         tool = tm.load_tool(
             tool_data["name"],
@@ -133,11 +221,11 @@ class BaseAgent:
                     "method": tool_data["config"]["actions"][action_name]["method"],
                     "headers": headers,
                     "query_params": query_params,
-                    "proxy_id": self.proxy_id,
                 }
                 if tool_data["name"] == "api_tool"
                 else tool_data["config"]
             ),
+            user_id=self.user,  # Pass user ID for MCP tools credential decryption
         )
         if tool_data["name"] == "api_tool":
             print(
@@ -147,15 +235,175 @@ class BaseAgent:
         else:
             print(f"Executing tool: {action_name} with args: {call_args}")
             result = tool.execute_action(action_name, **parameters)
-        call_id = getattr(call, "id", None)
+        tool_call_data["result"] = (
+            f"{str(result)[:50]}..." if len(str(result)) > 50 else result
+        )
 
-        tool_call_data = {
-            "tool_name": tool_data["name"],
-            "call_id": call_id if call_id is not None else "None",
-            "action_name": f"{action_name}_{tool_id}",
-            "arguments": call_args,
-            "result": result,
-        }
+        yield {"type": "tool_call", "data": {**tool_call_data, "status": "completed"}}
         self.tool_calls.append(tool_call_data)
 
         return result, call_id
+
+    def _get_truncated_tool_calls(self):
+        return [
+            {
+                **tool_call,
+                "result": (
+                    f"{str(tool_call['result'])[:50]}..."
+                    if len(str(tool_call["result"])) > 50
+                    else tool_call["result"]
+                ),
+                "status": "completed",
+            }
+            for tool_call in self.tool_calls
+        ]
+
+    def _build_messages(
+        self,
+        system_prompt: str,
+        query: str,
+        retrieved_data: List[Dict],
+    ) -> List[Dict]:
+        docs_with_filenames = []
+        for doc in retrieved_data:
+            filename = doc.get("filename") or doc.get("title") or doc.get("source")
+            if filename:
+                chunk_header = str(filename)
+                docs_with_filenames.append(f"{chunk_header}\n{doc['text']}")
+            else:
+                docs_with_filenames.append(doc["text"])
+        docs_together = "\n\n".join(docs_with_filenames)
+        p_chat_combine = system_prompt.replace("{summaries}", docs_together)
+        messages_combine = [{"role": "system", "content": p_chat_combine}]
+
+        for i in self.chat_history:
+            if "prompt" in i and "response" in i:
+                messages_combine.append({"role": "user", "content": i["prompt"]})
+                messages_combine.append({"role": "assistant", "content": i["response"]})
+            if "tool_calls" in i:
+                for tool_call in i["tool_calls"]:
+                    call_id = tool_call.get("call_id") or str(uuid.uuid4())
+
+                    function_call_dict = {
+                        "function_call": {
+                            "name": tool_call.get("action_name"),
+                            "args": tool_call.get("arguments"),
+                            "call_id": call_id,
+                        }
+                    }
+                    function_response_dict = {
+                        "function_response": {
+                            "name": tool_call.get("action_name"),
+                            "response": {"result": tool_call.get("result")},
+                            "call_id": call_id,
+                        }
+                    }
+
+                    messages_combine.append(
+                        {"role": "assistant", "content": [function_call_dict]}
+                    )
+                    messages_combine.append(
+                        {"role": "tool", "content": [function_response_dict]}
+                    )
+        messages_combine.append({"role": "user", "content": query})
+        return messages_combine
+
+    def _retriever_search(
+        self,
+        retriever: BaseRetriever,
+        query: str,
+        log_context: Optional[LogContext] = None,
+    ) -> List[Dict]:
+        retrieved_data = retriever.search(query)
+        if log_context:
+            data = build_stack_data(retriever, exclude_attributes=["llm"])
+            log_context.stacks.append({"component": "retriever", "data": data})
+        return retrieved_data
+
+    def _llm_gen(self, messages: List[Dict], log_context: Optional[LogContext] = None):
+        gen_kwargs = {"model": self.gpt_model, "messages": messages}
+
+        if (
+            hasattr(self.llm, "_supports_tools")
+            and self.llm._supports_tools
+            and self.tools
+        ):
+            gen_kwargs["tools"] = self.tools
+
+        if (
+            self.json_schema
+            and hasattr(self.llm, "_supports_structured_output")
+            and self.llm._supports_structured_output()
+        ):
+            structured_format = self.llm.prepare_structured_output_format(
+                self.json_schema
+            )
+            if structured_format:
+                if self.llm_name == "openai":
+                    gen_kwargs["response_format"] = structured_format
+                elif self.llm_name == "google":
+                    gen_kwargs["response_schema"] = structured_format
+
+        resp = self.llm.gen_stream(**gen_kwargs)
+
+        if log_context:
+            data = build_stack_data(self.llm, exclude_attributes=["client"])
+            log_context.stacks.append({"component": "llm", "data": data})
+        return resp
+
+    def _llm_handler(
+        self,
+        resp,
+        tools_dict: Dict,
+        messages: List[Dict],
+        log_context: Optional[LogContext] = None,
+        attachments: Optional[List[Dict]] = None,
+    ):
+        resp = self.llm_handler.process_message_flow(
+            self, resp, tools_dict, messages, attachments, True
+        )
+        if log_context:
+            data = build_stack_data(self.llm_handler, exclude_attributes=["tool_calls"])
+            log_context.stacks.append({"component": "llm_handler", "data": data})
+        return resp
+
+    def _handle_response(self, response, tools_dict, messages, log_context):
+        is_structured_output = (
+            self.json_schema is not None
+            and hasattr(self.llm, "_supports_structured_output")
+            and self.llm._supports_structured_output()
+        )
+
+        if isinstance(response, str):
+            answer_data = {"answer": response}
+            if is_structured_output:
+                answer_data["structured"] = True
+                answer_data["schema"] = self.json_schema
+            yield answer_data
+            return
+        if hasattr(response, "message") and getattr(response.message, "content", None):
+            answer_data = {"answer": response.message.content}
+            if is_structured_output:
+                answer_data["structured"] = True
+                answer_data["schema"] = self.json_schema
+            yield answer_data
+            return
+        processed_response_gen = self._llm_handler(
+            response, tools_dict, messages, log_context, self.attachments
+        )
+
+        for event in processed_response_gen:
+            if isinstance(event, str):
+                answer_data = {"answer": event}
+                if is_structured_output:
+                    answer_data["structured"] = True
+                    answer_data["schema"] = self.json_schema
+                yield answer_data
+            elif hasattr(event, "message") and getattr(event.message, "content", None):
+                answer_data = {"answer": event.message.content}
+                if is_structured_output:
+                    answer_data["structured"] = True
+                    answer_data["schema"] = self.json_schema
+                yield answer_data
+            elif isinstance(event, dict) and "type" in event:
+                yield event

application/agents/classic_agent.py

@@ -1,141 +1,53 @@
-import uuid
 from typing import Dict, Generator
-
 from application.agents.base import BaseAgent
-from application.logging import build_stack_data, log_activity, LogContext
-
+from application.logging import LogContext
 from application.retriever.base import BaseRetriever
+import logging
+
+logger = logging.getLogger(__name__)
 
 
 class ClassicAgent(BaseAgent):
-    def __init__(
-        self,
-        endpoint,
-        llm_name,
-        gpt_model,
-        api_key,
-        user_api_key=None,
-        prompt="",
-        chat_history=None,
-        decoded_token=None,
-        proxy_id=None,
-    ):
-        super().__init__(
-            endpoint, llm_name, gpt_model, api_key, user_api_key, decoded_token, proxy_id
-        )
-        self.user = decoded_token.get("sub")
-        self.prompt = prompt
-        self.chat_history = chat_history if chat_history is not None else []
+    """A simplified agent with clear execution flow.
 
-    @log_activity()
-    def gen(
-        self, query: str, retriever: BaseRetriever, log_context: LogContext = None
-    ) -> Generator[Dict, None, None]:
-        yield from self._gen_inner(query, retriever, log_context)
+    Usage:
+    1. Processes a query through retrieval
+    2. Sets up available tools
+    3. Generates responses using LLM
+    4. Handles tool interactions if needed
+    5. Returns standardized outputs
+
+    Easy to extend by overriding specific steps.
+    """
 
     def _gen_inner(
         self, query: str, retriever: BaseRetriever, log_context: LogContext
     ) -> Generator[Dict, None, None]:
+        # Step 1: Retrieve relevant data
         retrieved_data = self._retriever_search(retriever, query, log_context)
 
-        docs_together = "\n".join([doc["text"] for doc in retrieved_data])
-        p_chat_combine = self.prompt.replace("{summaries}", docs_together)
-        messages_combine = [{"role": "system", "content": p_chat_combine}]
-
-        if len(self.chat_history) > 0:
-            for i in self.chat_history:
-                if "prompt" in i and "response" in i:
-                    messages_combine.append({"role": "user", "content": i["prompt"]})
-                    messages_combine.append(
-                        {"role": "assistant", "content": i["response"]}
-                    )
-                if "tool_calls" in i:
-                    for tool_call in i["tool_calls"]:
-                        call_id = tool_call.get("call_id")
-                        if call_id is None or call_id == "None":
-                            call_id = str(uuid.uuid4())
-
-                        function_call_dict = {
-                            "function_call": {
-                                "name": tool_call.get("action_name"),
-                                "args": tool_call.get("arguments"),
-                                "call_id": call_id,
-                            }
-                        }
-                        function_response_dict = {
-                            "function_response": {
-                                "name": tool_call.get("action_name"),
-                                "response": {"result": tool_call.get("result")},
-                                "call_id": call_id,
-                            }
-                        }
-
-                        messages_combine.append(
-                            {"role": "assistant", "content": [function_call_dict]}
-                        )
-                        messages_combine.append(
-                            {"role": "tool", "content": [function_response_dict]}
-                        )
-        messages_combine.append({"role": "user", "content": query})
-
-        tools_dict = self._get_user_tools(self.user)
+        # Step 2: Prepare tools
+        tools_dict = (
+            self._get_user_tools(self.user)
+            if not self.user_api_key
+            else self._get_tools(self.user_api_key)
+        )
         self._prepare_tools(tools_dict)
 
-        resp = self._llm_gen(messages_combine, log_context)
+        # Step 3: Build and process messages
+        messages = self._build_messages(self.prompt, query, retrieved_data)
+        llm_response = self._llm_gen(messages, log_context)
 
-        if isinstance(resp, str):
-            yield {"answer": resp}
-            return
-        if (
-            hasattr(resp, "message")
-            and hasattr(resp.message, "content")
-            and resp.message.content is not None
-        ):
-            yield {"answer": resp.message.content}
-            return
-
-        resp = self._llm_handler(resp, tools_dict, messages_combine, log_context)
-
-        if isinstance(resp, str):
-            yield {"answer": resp}
-        elif (
-            hasattr(resp, "message")
-            and hasattr(resp.message, "content")
-            and resp.message.content is not None
-        ):
-            yield {"answer": resp.message.content}
-        else:
-            completion = self.llm.gen_stream(
-                model=self.gpt_model, messages=messages_combine, tools=self.tools
-            )
-            for line in completion:
-                if isinstance(line, str):
-                    yield {"answer": line}
+        # Step 4: Handle the response
+        yield from self._handle_response(
+            llm_response, tools_dict, messages, log_context
+        )
 
+        # Step 5: Return metadata
         yield {"sources": retrieved_data}
-        yield {"tool_calls": self.tool_calls.copy()}
+        yield {"tool_calls": self._get_truncated_tool_calls()}
 
-    def _retriever_search(self, retriever, query, log_context):
-        retrieved_data = retriever.search(query)
-        if log_context:
-            data = build_stack_data(retriever, exclude_attributes=["llm"])
-            log_context.stacks.append({"component": "retriever", "data": data})
-        return retrieved_data
-
-    def _llm_gen(self, messages_combine, log_context):
-        resp = self.llm.gen_stream(
-            model=self.gpt_model, messages=messages_combine, tools=self.tools
+        # Log tool calls for debugging
+        log_context.stacks.append(
+            {"component": "agent", "data": {"tool_calls": self.tool_calls.copy()}}
         )
-        if log_context:
-            data = build_stack_data(self.llm)
-            log_context.stacks.append({"component": "llm", "data": data})
-        return resp
-
-    def _llm_handler(self, resp, tools_dict, messages_combine, log_context):
-        resp = self.llm_handler.handle_response(
-            self, resp, tools_dict, messages_combine
-        )
-        if log_context:
-            data = build_stack_data(self.llm_handler)
-            log_context.stacks.append({"component": "llm_handler", "data": data})
-        return resp

application/agents/llm_handler.py

@@ -1,254 +0,0 @@
-import json
-from abc import ABC, abstractmethod
-
-from application.logging import build_stack_data
-
-
-class LLMHandler(ABC):
-    def __init__(self):
-        self.llm_calls = []
-        self.tool_calls = []
-
-    @abstractmethod
-    def handle_response(self, agent, resp, tools_dict, messages, **kwargs):
-        pass
-
-
-class OpenAILLMHandler(LLMHandler):
-    def handle_response(self, agent, resp, tools_dict, messages, stream: bool = True):
-        if not stream:
-            while hasattr(resp, "finish_reason") and resp.finish_reason == "tool_calls":
-                message = json.loads(resp.model_dump_json())["message"]
-                keys_to_remove = {"audio", "function_call", "refusal"}
-                filtered_data = {
-                    k: v for k, v in message.items() if k not in keys_to_remove
-                }
-                messages.append(filtered_data)
-
-                tool_calls = resp.message.tool_calls
-                for call in tool_calls:
-                    try:
-                        self.tool_calls.append(call)
-                        tool_response, call_id = agent._execute_tool_action(
-                            tools_dict, call
-                        )
-                        function_call_dict = {
-                            "function_call": {
-                                "name": call.function.name,
-                                "args": call.function.arguments,
-                                "call_id": call_id,
-                            }
-                        }
-                        function_response_dict = {
-                            "function_response": {
-                                "name": call.function.name,
-                                "response": {"result": tool_response},
-                                "call_id": call_id,
-                            }
-                        }
-
-                        messages.append(
-                            {"role": "assistant", "content": [function_call_dict]}
-                        )
-                        messages.append(
-                            {"role": "tool", "content": [function_response_dict]}
-                        )
-
-                    except Exception as e:
-                        messages.append(
-                            {
-                                "role": "tool",
-                                "content": f"Error executing tool: {str(e)}",
-                                "tool_call_id": call_id,
-                            }
-                        )
-                resp = agent.llm.gen_stream(
-                    model=agent.gpt_model, messages=messages, tools=agent.tools
-                )
-                self.llm_calls.append(build_stack_data(agent.llm))
-            return resp
-
-        else:
-            while True:
-                tool_calls = {}
-                for chunk in resp:
-                    if isinstance(chunk, str) and len(chunk) > 0:
-                        return
-                    elif hasattr(chunk, "delta"): 
-                        chunk_delta = chunk.delta
-
-                        if (
-                            hasattr(chunk_delta, "tool_calls")
-                            and chunk_delta.tool_calls is not None
-                        ):
-                            for tool_call in chunk_delta.tool_calls:
-                                index = tool_call.index
-                                if index not in tool_calls:
-                                    tool_calls[index] = {
-                                        "id": "",
-                                        "function": {"name": "", "arguments": ""},
-                                    }
-
-                                current = tool_calls[index]
-                                if tool_call.id:
-                                    current["id"] = tool_call.id
-                                if tool_call.function.name:
-                                    current["function"][
-                                        "name"
-                                    ] = tool_call.function.name
-                                if tool_call.function.arguments:
-                                    current["function"][
-                                        "arguments"
-                                    ] += tool_call.function.arguments
-                                tool_calls[index] = current
-
-                        if (
-                            hasattr(chunk, "finish_reason")
-                            and chunk.finish_reason == "tool_calls"
-                        ):
-                            for index in sorted(tool_calls.keys()):
-                                call = tool_calls[index]
-                                try:
-                                    self.tool_calls.append(call)
-                                    tool_response, call_id = agent._execute_tool_action(
-                                        tools_dict, call
-                                    )
-                                    if isinstance(call["function"]["arguments"], str):
-                                        call["function"]["arguments"] = json.loads(call["function"]["arguments"])
-
-                                    function_call_dict = {
-                                        "function_call": {
-                                            "name": call["function"]["name"],
-                                            "args": call["function"]["arguments"],
-                                            "call_id": call["id"],
-                                        }
-                                    }
-                                    function_response_dict = {
-                                        "function_response": {
-                                            "name": call["function"]["name"],
-                                            "response": {"result": tool_response},
-                                            "call_id": call["id"],
-                                        }
-                                    }
-
-                                    messages.append(
-                                        {
-                                            "role": "assistant",
-                                            "content": [function_call_dict],
-                                        }
-                                    )
-                                    messages.append(
-                                        {
-                                            "role": "tool",
-                                            "content": [function_response_dict],
-                                        }
-                                    )
-
-                                except Exception as e:
-                                    messages.append(
-                                        {
-                                            "role": "assistant",
-                                            "content": f"Error executing tool: {str(e)}",
-                                        }
-                                    )
-                            tool_calls = {}
-
-                        if (
-                            hasattr(chunk, "finish_reason")
-                            and chunk.finish_reason == "stop"
-                        ):
-                            return
-                    elif isinstance(chunk, str) and len(chunk) == 0:
-                            continue
-
-                resp = agent.llm.gen_stream(
-                    model=agent.gpt_model, messages=messages, tools=agent.tools
-                )
-                self.llm_calls.append(build_stack_data(agent.llm))
-
-
-class GoogleLLMHandler(LLMHandler):
-    def handle_response(self, agent, resp, tools_dict, messages, stream: bool = True):
-        from google.genai import types
-
-        while True:
-            if not stream:
-                response = agent.llm.gen(
-                    model=agent.gpt_model, messages=messages, tools=agent.tools
-                )
-                self.llm_calls.append(build_stack_data(agent.llm))
-                if response.candidates and response.candidates[0].content.parts:
-                    tool_call_found = False
-                    for part in response.candidates[0].content.parts:
-                        if part.function_call:
-                            tool_call_found = True
-                            self.tool_calls.append(part.function_call)
-                            tool_response, call_id = agent._execute_tool_action(
-                                tools_dict, part.function_call
-                            )
-                            function_response_part = types.Part.from_function_response(
-                                name=part.function_call.name,
-                                response={"result": tool_response},
-                            )
-
-                            messages.append(
-                                {"role": "model", "content": [part.to_json_dict()]}
-                            )
-                            messages.append(
-                                {
-                                    "role": "tool",
-                                    "content": [function_response_part.to_json_dict()],
-                                }
-                            )
-
-                    if (
-                        not tool_call_found
-                        and response.candidates[0].content.parts
-                        and response.candidates[0].content.parts[0].text
-                    ):
-                        return response.candidates[0].content.parts[0].text
-                    elif not tool_call_found:
-                        return response.candidates[0].content.parts
-
-                else:
-                    return response
-
-            else:
-                response = agent.llm.gen_stream(
-                    model=agent.gpt_model, messages=messages, tools=agent.tools
-                )
-                self.llm_calls.append(build_stack_data(agent.llm))
-
-                tool_call_found = False
-                for result in response:
-                    if hasattr(result, "function_call"):
-                        tool_call_found = True
-                        self.tool_calls.append(result.function_call)
-                        tool_response, call_id = agent._execute_tool_action(
-                            tools_dict, result.function_call
-                        )
-                        function_response_part = types.Part.from_function_response(
-                            name=result.function_call.name,
-                            response={"result": tool_response},
-                        )
-
-                        messages.append(
-                            {"role": "model", "content": [result.to_json_dict()]}
-                        )
-                        messages.append(
-                            {
-                                "role": "tool",
-                                "content": [function_response_part.to_json_dict()],
-                            }
-                        )
-
-                if not tool_call_found:
-                    return response
-
-
-def get_llm_handler(llm_type):
-    handlers = {
-        "openai": OpenAILLMHandler(),
-        "google": GoogleLLMHandler(),
-    }
-    return handlers.get(llm_type, OpenAILLMHandler())

application/agents/react_agent.py

@@ -0,0 +1,229 @@
+import os
+from typing import Dict, Generator, List, Any
+import logging
+
+from application.agents.base import BaseAgent
+from application.logging import build_stack_data, LogContext
+from application.retriever.base import BaseRetriever
+
+logger = logging.getLogger(__name__)
+
+current_dir = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
+with open(
+    os.path.join(current_dir, "application/prompts", "react_planning_prompt.txt"), "r"
+) as f:
+    planning_prompt_template = f.read()
+with open(
+    os.path.join(current_dir, "application/prompts", "react_final_prompt.txt"),
+    "r",
+) as f:
+    final_prompt_template = f.read()
+    
+MAX_ITERATIONS_REASONING = 10
+
+class ReActAgent(BaseAgent):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.plan: str = ""
+        self.observations: List[str] = []
+
+    def _extract_content_from_llm_response(self, resp: Any) -> str:
+        """
+        Helper to extract string content from various LLM response types.
+        Handles strings, message objects (OpenAI-like), and streams.
+        Adapt stream handling for your specific LLM client if not OpenAI.
+        """
+        collected_content = []
+        if isinstance(resp, str):
+            collected_content.append(resp)
+        elif ( # OpenAI non-streaming or Anthropic non-streaming (older SDK style)
+            hasattr(resp, "message")
+            and hasattr(resp.message, "content")
+            and resp.message.content is not None
+        ):
+            collected_content.append(resp.message.content)
+        elif ( # OpenAI non-streaming (Pydantic model), Anthropic new SDK non-streaming
+            hasattr(resp, "choices") and resp.choices and
+            hasattr(resp.choices[0], "message") and
+            hasattr(resp.choices[0].message, "content") and
+            resp.choices[0].message.content is not None
+        ):
+            collected_content.append(resp.choices[0].message.content) # OpenAI
+        elif ( # Anthropic new SDK non-streaming content block
+             hasattr(resp, "content") and isinstance(resp.content, list) and resp.content and
+             hasattr(resp.content[0], "text")
+        ):
+            collected_content.append(resp.content[0].text) # Anthropic
+        else:
+            # Assume resp is a stream if not a recognized object
+            try:
+                for chunk in resp: # This will fail if resp is not iterable (e.g. a non-streaming response object)
+                    content_piece = ""
+                    # OpenAI-like stream
+                    if hasattr(chunk, 'choices') and len(chunk.choices) > 0 and \
+                       hasattr(chunk.choices[0], 'delta') and \
+                       hasattr(chunk.choices[0].delta, 'content') and \
+                       chunk.choices[0].delta.content is not None:
+                        content_piece = chunk.choices[0].delta.content
+                    # Anthropic-like stream (ContentBlockDelta)
+                    elif hasattr(chunk, 'type') and chunk.type == 'content_block_delta' and \
+                         hasattr(chunk, 'delta') and hasattr(chunk.delta, 'text'):
+                        content_piece = chunk.delta.text
+                    elif isinstance(chunk, str): # Simplest case: stream of strings
+                        content_piece = chunk
+
+                    if content_piece:
+                        collected_content.append(content_piece)
+            except TypeError: # If resp is not iterable (e.g. a final response object that wasn't caught above)
+                logger.debug(f"Response type {type(resp)} could not be iterated as a stream. It might be a non-streaming object not handled by specific checks.")
+            except Exception as e:
+                logger.error(f"Error processing potential stream chunk: {e}, chunk was: {getattr(chunk, '__dict__', chunk)}")
+
+
+        return "".join(collected_content)
+
+    def _gen_inner(
+        self, query: str, retriever: BaseRetriever, log_context: LogContext
+    ) -> Generator[Dict, None, None]:
+        # Reset state for this generation call
+        self.plan = ""
+        self.observations = []
+        retrieved_data = self._retriever_search(retriever, query, log_context)
+
+        if self.user_api_key:
+            tools_dict = self._get_tools(self.user_api_key)
+        else:
+            tools_dict = self._get_user_tools(self.user)
+        self._prepare_tools(tools_dict)
+
+        docs_together = "\n".join([doc["text"] for doc in retrieved_data])
+        iterating_reasoning = 0
+        while iterating_reasoning < MAX_ITERATIONS_REASONING:
+            iterating_reasoning += 1
+            # 1. Create Plan
+            logger.info("ReActAgent: Creating plan...")
+            plan_stream = self._create_plan(query, docs_together, log_context)
+            current_plan_parts = []
+            yield {"thought": f"Reasoning... (iteration {iterating_reasoning})\n\n"}
+            for line_chunk in plan_stream:
+                current_plan_parts.append(line_chunk)
+                yield {"thought": line_chunk}
+            self.plan = "".join(current_plan_parts)
+            if self.plan:
+                self.observations.append(f"Plan: {self.plan} Iteration: {iterating_reasoning}")
+
+
+            max_obs_len = 20000
+            obs_str = "\n".join(self.observations)
+            if len(obs_str) > max_obs_len:
+                obs_str = obs_str[:max_obs_len] + "\n...[observations truncated]"
+            execution_prompt_str = (
+                (self.prompt or "")
+                + f"\n\nFollow this plan:\n{self.plan}"
+                + f"\n\nObservations:\n{obs_str}"
+                + f"\n\nIf there is enough data to complete user query '{query}', Respond with 'SATISFIED' only. Otherwise, continue. Dont Menstion 'SATISFIED' in your response if you are not ready. "
+            )
+            
+            messages = self._build_messages(execution_prompt_str, query, retrieved_data)
+
+            resp_from_llm_gen = self._llm_gen(messages, log_context)
+
+            initial_llm_thought_content = self._extract_content_from_llm_response(resp_from_llm_gen)
+            if initial_llm_thought_content:
+                self.observations.append(f"Initial thought/response: {initial_llm_thought_content}")
+            else:
+                logger.info("ReActAgent: Initial LLM response (before handler) had no textual content (might be only tool calls).")
+            resp_after_handler = self._llm_handler(resp_from_llm_gen, tools_dict, messages, log_context)
+            
+            for tool_call_info in self.tool_calls: # Iterate over self.tool_calls populated by _llm_handler
+                observation_string = (
+                    f"Executed Action: Tool '{tool_call_info.get('tool_name', 'N/A')}' "
+                    f"with arguments '{tool_call_info.get('arguments', '{}')}'. Result: '{str(tool_call_info.get('result', ''))[:200]}...'"
+                )
+                self.observations.append(observation_string)
+
+            content_after_handler = self._extract_content_from_llm_response(resp_after_handler)
+            if content_after_handler:
+                self.observations.append(f"Response after tool execution: {content_after_handler}")
+            else:
+                logger.info("ReActAgent: LLM response after handler had no textual content.")
+
+            if log_context:
+                log_context.stacks.append(
+                    {"component": "agent_tool_calls", "data": {"tool_calls": self.tool_calls.copy()}}
+                )
+
+            yield {"sources": retrieved_data}
+
+            display_tool_calls = []
+            for tc in self.tool_calls:
+                cleaned_tc = tc.copy()
+                if len(str(cleaned_tc.get("result", ""))) > 50:
+                    cleaned_tc["result"] = str(cleaned_tc["result"])[:50] + "..."
+                display_tool_calls.append(cleaned_tc)
+            if display_tool_calls:
+                yield {"tool_calls": display_tool_calls}
+            
+            if "SATISFIED" in content_after_handler:
+                logger.info("ReActAgent: LLM satisfied with the plan and data. Stopping reasoning.")
+                break
+
+        # 3. Create Final Answer based on all observations
+        final_answer_stream = self._create_final_answer(query, self.observations, log_context)
+        for answer_chunk in final_answer_stream:
+            yield {"answer": answer_chunk}
+        logger.info("ReActAgent: Finished generating final answer.")
+
+    def _create_plan(
+        self, query: str, docs_data: str, log_context: LogContext = None
+    ) -> Generator[str, None, None]:
+        plan_prompt_filled = planning_prompt_template.replace("{query}", query)
+        if "{summaries}" in plan_prompt_filled:
+            summaries = docs_data if docs_data else "No documents retrieved."
+            plan_prompt_filled = plan_prompt_filled.replace("{summaries}", summaries)
+        plan_prompt_filled = plan_prompt_filled.replace("{prompt}", self.prompt or "")
+        plan_prompt_filled = plan_prompt_filled.replace("{observations}", "\n".join(self.observations))
+
+        messages = [{"role": "user", "content": plan_prompt_filled}]
+
+        plan_stream_from_llm = self.llm.gen_stream(
+            model=self.gpt_model, messages=messages, tools=getattr(self, 'tools', None) # Use self.tools
+        )
+        if log_context:
+            data = build_stack_data(self.llm)
+            log_context.stacks.append({"component": "planning_llm", "data": data})
+
+        for chunk in plan_stream_from_llm:
+            content_piece = self._extract_content_from_llm_response(chunk)
+            if content_piece:
+                yield content_piece
+
+    def _create_final_answer(
+        self, query: str, observations: List[str], log_context: LogContext = None
+    ) -> Generator[str, None, None]:
+        observation_string = "\n".join(observations)
+        max_obs_len = 10000
+        if len(observation_string) > max_obs_len:
+            observation_string = observation_string[:max_obs_len] + "\n...[observations truncated]"
+            logger.warning("ReActAgent: Truncated observations for final answer prompt due to length.")
+
+        final_answer_prompt_filled = final_prompt_template.format(
+            query=query, observations=observation_string
+        )
+
+        messages = [{"role": "user", "content": final_answer_prompt_filled}]
+
+        # Final answer should synthesize, not call tools.
+        final_answer_stream_from_llm = self.llm.gen_stream(
+            model=self.gpt_model, messages=messages, tools=None
+        )
+        if log_context:
+            data = build_stack_data(self.llm)
+            log_context.stacks.append({"component": "final_answer_llm", "data": data})
+
+        for chunk in final_answer_stream_from_llm:
+            content_piece = self._extract_content_from_llm_response(chunk)
+            if content_piece:
+                yield content_piece

application/agents/tools/api_tool.py

@@ -23,43 +23,15 @@ class APITool(Tool):
         )
 
     def _make_api_call(self, url, method, headers, query_params, body):
-        sanitized_headers = {}
-        for key, value in headers.items():
-            if isinstance(value, str):
-                sanitized_value = value.encode('latin-1', errors='ignore').decode('latin-1')
-                sanitized_headers[key] = sanitized_value
-            else:
-                sanitized_headers[key] = value
-
         if query_params:
             url = f"{url}?{requests.compat.urlencode(query_params)}"
-        if isinstance(body, dict):
-            body = json.dumps(body)
-        response = None
+        # if isinstance(body, dict):
+        #     body = json.dumps(body)
         try:
             print(f"Making API call: {method} {url} with body: {body}")
             if body == "{}":
                 body = None
-
-            proxy_id = self.config.get("proxy_id", None)
-            request_kwargs = {
-                'method': method,
-                'url': url,
-                'headers': sanitized_headers,
-                'data': body
-            }
-            try:
-                if proxy_id:
-                    from application.agents.tools.proxy_handler import apply_proxy_to_request
-                    response = apply_proxy_to_request(
-                        requests.request,
-                        proxy_id=proxy_id,
-                        **request_kwargs
-                    )
-                else:
-                    response = requests.request(**request_kwargs)
-            except ImportError:
-                response = requests.request(**request_kwargs)
+            response = requests.request(method, url, headers=headers, data=body)
             response.raise_for_status()
             content_type = response.headers.get(
                 "Content-Type", "application/json"

application/agents/tools/brave.py

@@ -25,27 +25,35 @@ class BraveSearchTool(Tool):
         else:
             raise ValueError(f"Unknown action: {action_name}")
 
-    def _web_search(self, query, country="ALL", search_lang="en", count=10, 
-                   offset=0, safesearch="off", freshness=None, 
-                   result_filter=None, extra_snippets=False, summary=False):
+    def _web_search(
+        self,
+        query,
+        country="ALL",
+        search_lang="en",
+        count=10,
+        offset=0,
+        safesearch="off",
+        freshness=None,
+        result_filter=None,
+        extra_snippets=False,
+        summary=False,
+    ):
         """
         Performs a web search using the Brave Search API.
         """
         print(f"Performing Brave web search for: {query}")
-        
+
         url = f"{self.base_url}/web/search"
-        
-        # Build query parameters
+
         params = {
             "q": query,
             "country": country,
             "search_lang": search_lang,
             "count": min(count, 20),
             "offset": min(offset, 9),
-            "safesearch": safesearch
+            "safesearch": safesearch,
         }
-        
-        # Add optional parameters only if they have values
+
         if freshness:
             params["freshness"] = freshness
         if result_filter:
@@ -54,68 +62,69 @@ class BraveSearchTool(Tool):
             params["extra_snippets"] = 1
         if summary:
             params["summary"] = 1
-        
-        # Set up headers
         headers = {
             "Accept": "application/json",
             "Accept-Encoding": "gzip",
-            "X-Subscription-Token": self.token
+            "X-Subscription-Token": self.token,
         }
-        
-        # Make the request
+
         response = requests.get(url, params=params, headers=headers)
-        
+
         if response.status_code == 200:
             return {
                 "status_code": response.status_code,
                 "results": response.json(),
-                "message": "Search completed successfully."
+                "message": "Search completed successfully.",
             }
         else:
             return {
                 "status_code": response.status_code,
-                "message": f"Search failed with status code: {response.status_code}."
+                "message": f"Search failed with status code: {response.status_code}.",
             }
-    
-    def _image_search(self, query, country="ALL", search_lang="en", count=5, 
-                     safesearch="off", spellcheck=False):
+
+    def _image_search(
+        self,
+        query,
+        country="ALL",
+        search_lang="en",
+        count=5,
+        safesearch="off",
+        spellcheck=False,
+    ):
         """
         Performs an image search using the Brave Search API.
         """
         print(f"Performing Brave image search for: {query}")
-        
+
         url = f"{self.base_url}/images/search"
-        
-        # Build query parameters
+
         params = {
             "q": query,
             "country": country,
             "search_lang": search_lang,
             "count": min(count, 100),  # API max is 100
             "safesearch": safesearch,
-            "spellcheck": 1 if spellcheck else 0
+            "spellcheck": 1 if spellcheck else 0,
         }
-        
-        # Set up headers
+
         headers = {
             "Accept": "application/json",
             "Accept-Encoding": "gzip",
-            "X-Subscription-Token": self.token
+            "X-Subscription-Token": self.token,
         }
-        
-        # Make the request
+
         response = requests.get(url, params=params, headers=headers)
-        
+
         if response.status_code == 200:
             return {
                 "status_code": response.status_code,
                 "results": response.json(),
-                "message": "Image search completed successfully."
+                "message": "Image search completed successfully.",
             }
         else:
             return {
                 "status_code": response.status_code,
-                "message": f"Image search failed with status code: {response.status_code}."
+                "message": f"Image search failed with status code: {response.status_code}.",
             }
 
     def get_actions_metadata(self):
@@ -130,42 +139,14 @@ class BraveSearchTool(Tool):
                             "type": "string",
                             "description": "The search query (max 400 characters, 50 words)",
                         },
-                        # "country": {
-                        #     "type": "string",
-                        #     "description": "The 2-character country code (default: US)",
-                        # },
                         "search_lang": {
                             "type": "string",
                             "description": "The search language preference (default: en)",
                         },
-                        # "count": {
-                        #     "type": "integer",
-                        #     "description": "Number of results to return (max 20, default: 10)",
-                        # },
-                        # "offset": {
-                        #     "type": "integer",
-                        #     "description": "Pagination offset (max 9, default: 0)",
-                        # },
-                        # "safesearch": {
-                        #     "type": "string",
-                        #     "description": "Filter level for adult content (off, moderate, strict)",
-                        # },
                         "freshness": {
                             "type": "string",
                             "description": "Time filter for results (pd: last 24h, pw: last week, pm: last month, py: last year)",
                         },
-                        # "result_filter": {
-                        #     "type": "string",
-                        #     "description": "Comma-delimited list of result types to include",
-                        # },
-                        # "extra_snippets": {
-                        #     "type": "boolean",
-                        #     "description": "Get additional excerpts from result pages",
-                        # },
-                        # "summary": {
-                        #     "type": "boolean",
-                        #     "description": "Enable summary generation in search results",
-                        # }
                     },
                     "required": ["query"],
                     "additionalProperties": False,
@@ -181,37 +162,21 @@ class BraveSearchTool(Tool):
                             "type": "string",
                             "description": "The search query (max 400 characters, 50 words)",
                         },
-                        # "country": {
-                        #     "type": "string",
-                        #     "description": "The 2-character country code (default: US)",
-                        # },
-                        # "search_lang": {
-                        #     "type": "string",
-                        #     "description": "The search language preference (default: en)",
-                        # },
                         "count": {
                             "type": "integer",
                             "description": "Number of results to return (max 100, default: 5)",
                         },
-                        # "safesearch": {
-                        #     "type": "string",
-                        #     "description": "Filter level for adult content (off, strict). Default: strict",
-                        # },
-                        # "spellcheck": {
-                        #     "type": "boolean",
-                        #     "description": "Whether to spellcheck provided query (default: true)",
-                        # }
                     },
                     "required": ["query"],
                     "additionalProperties": False,
                 },
-            }
+            },
         ]
 
     def get_config_requirements(self):
         return {
             "token": {
-                "type": "string", 
-                "description": "Brave Search API key for authentication"
+                "type": "string",
+                "description": "Brave Search API key for authentication",
             },
-        }
+        }

application/agents/tools/duckduckgo.py

@@ -0,0 +1,114 @@
+from application.agents.tools.base import Tool
+from duckduckgo_search import DDGS
+
+
+class DuckDuckGoSearchTool(Tool):
+    """
+    DuckDuckGo Search
+    A tool for performing web and image searches using DuckDuckGo.
+    """
+
+    def __init__(self, config):
+        self.config = config
+
+    def execute_action(self, action_name, **kwargs):
+        actions = {
+            "ddg_web_search": self._web_search,
+            "ddg_image_search": self._image_search,
+        }
+
+        if action_name in actions:
+            return actions[action_name](**kwargs)
+        else:
+            raise ValueError(f"Unknown action: {action_name}")
+
+    def _web_search(
+        self,
+        query,
+        max_results=5,
+    ):
+        print(f"Performing DuckDuckGo web search for: {query}")
+
+        try:
+            results = DDGS().text(
+                query,
+                max_results=max_results,
+            )
+
+            return {
+                "status_code": 200,
+                "results": results,
+                "message": "Web search completed successfully.",
+            }
+        except Exception as e:
+            return {
+                "status_code": 500,
+                "message": f"Web search failed: {str(e)}",
+            }
+
+    def _image_search(
+        self,
+        query,
+        max_results=5,
+    ):
+        print(f"Performing DuckDuckGo image search for: {query}")
+
+        try:
+            results = DDGS().images(
+                keywords=query,
+                max_results=max_results,
+            )
+
+            return {
+                "status_code": 200,
+                "results": results,
+                "message": "Image search completed successfully.",
+            }
+        except Exception as e:
+            return {
+                "status_code": 500,
+                "message": f"Image search failed: {str(e)}",
+            }
+
+    def get_actions_metadata(self):
+        return [
+            {
+                "name": "ddg_web_search",
+                "description": "Perform a web search using DuckDuckGo.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "description": "Number of results to return (default: 5)",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            },
+            {
+                "name": "ddg_image_search",
+                "description": "Perform an image search using DuckDuckGo.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "description": "Number of results to return (default: 5, max: 50)",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            },
+        ]
+
+    def get_config_requirements(self):
+        return {}

application/agents/tools/mcp_tool.py

@@ -0,0 +1,861 @@
+import asyncio
+import base64
+import json
+import logging
+import time
+from typing import Any, Dict, List, Optional
+from urllib.parse import parse_qs, urlparse
+
+from application.agents.tools.base import Tool
+from application.api.user.tasks import mcp_oauth_status_task, mcp_oauth_task
+from application.cache import get_redis_instance
+
+from application.core.mongo_db import MongoDB
+
+from application.core.settings import settings
+
+from application.security.encryption import decrypt_credentials
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+from fastmcp.client.transports import (
+    SSETransport,
+    StdioTransport,
+    StreamableHttpTransport,
+)
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+from pydantic import AnyHttpUrl, ValidationError
+from redis import Redis
+
+mongo = MongoDB.get_client()
+db = mongo[settings.MONGO_DB_NAME]
+
+_mcp_clients_cache = {}
+
+
+class MCPTool(Tool):
+    """
+    MCP Tool
+    Connect to remote Model Context Protocol (MCP) servers to access dynamic tools and resources. Supports various authentication methods and provides secure access to external services through the MCP protocol.
+    """
+
+    def __init__(self, config: Dict[str, Any], user_id: Optional[str] = None):
+        """
+        Initialize the MCP Tool with configuration.
+
+        Args:
+            config: Dictionary containing MCP server configuration:
+                - server_url: URL of the remote MCP server
+                - transport_type: Transport type (auto, sse, http, stdio)
+                - auth_type: Type of authentication (bearer, oauth, api_key, basic, none)
+                - encrypted_credentials: Encrypted credentials (if available)
+                - timeout: Request timeout in seconds (default: 30)
+                - headers: Custom headers for requests
+                - command: Command for STDIO transport
+                - args: Arguments for STDIO transport
+                - oauth_scopes: OAuth scopes for oauth auth type
+                - oauth_client_name: OAuth client name for oauth auth type
+            user_id: User ID for decrypting credentials (required if encrypted_credentials exist)
+        """
+        self.config = config
+        self.user_id = user_id
+        self.server_url = config.get("server_url", "")
+        self.transport_type = config.get("transport_type", "auto")
+        self.auth_type = config.get("auth_type", "none")
+        self.timeout = config.get("timeout", 30)
+        self.custom_headers = config.get("headers", {})
+
+        self.auth_credentials = {}
+        if config.get("encrypted_credentials") and user_id:
+            self.auth_credentials = decrypt_credentials(
+                config["encrypted_credentials"], user_id
+            )
+        else:
+            self.auth_credentials = config.get("auth_credentials", {})
+        self.oauth_scopes = config.get("oauth_scopes", [])
+        self.oauth_task_id = config.get("oauth_task_id", None)
+        self.oauth_client_name = config.get("oauth_client_name", "DocsGPT-MCP")
+        self.redirect_uri = f"{settings.API_URL}/api/mcp_server/callback"
+
+        self.available_tools = []
+        self._cache_key = self._generate_cache_key()
+        self._client = None
+
+        # Only validate and setup if server_url is provided and not OAuth
+
+        if self.server_url and self.auth_type != "oauth":
+            self._setup_client()
+
+    def _generate_cache_key(self) -> str:
+        """Generate a unique cache key for this MCP server configuration."""
+        auth_key = ""
+        if self.auth_type == "oauth":
+            scopes_str = ",".join(self.oauth_scopes) if self.oauth_scopes else "none"
+            auth_key = f"oauth:{self.oauth_client_name}:{scopes_str}"
+        elif self.auth_type in ["bearer"]:
+            token = self.auth_credentials.get(
+                "bearer_token", ""
+            ) or self.auth_credentials.get("access_token", "")
+            auth_key = f"bearer:{token[:10]}..." if token else "bearer:none"
+        elif self.auth_type == "api_key":
+            api_key = self.auth_credentials.get("api_key", "")
+            auth_key = f"apikey:{api_key[:10]}..." if api_key else "apikey:none"
+        elif self.auth_type == "basic":
+            username = self.auth_credentials.get("username", "")
+            auth_key = f"basic:{username}"
+        else:
+            auth_key = "none"
+        return f"{self.server_url}#{self.transport_type}#{auth_key}"
+
+    def _setup_client(self):
+        """Setup FastMCP client with proper transport and authentication."""
+        global _mcp_clients_cache
+        if self._cache_key in _mcp_clients_cache:
+            cached_data = _mcp_clients_cache[self._cache_key]
+            if time.time() - cached_data["created_at"] < 1800:
+                self._client = cached_data["client"]
+                return
+            else:
+                del _mcp_clients_cache[self._cache_key]
+        transport = self._create_transport()
+        auth = None
+
+        if self.auth_type == "oauth":
+            redis_client = get_redis_instance()
+            auth = DocsGPTOAuth(
+                mcp_url=self.server_url,
+                scopes=self.oauth_scopes,
+                redis_client=redis_client,
+                redirect_uri=self.redirect_uri,
+                task_id=self.oauth_task_id,
+                db=db,
+                user_id=self.user_id,
+            )
+        elif self.auth_type == "bearer":
+            token = self.auth_credentials.get(
+                "bearer_token", ""
+            ) or self.auth_credentials.get("access_token", "")
+            if token:
+                auth = BearerAuth(token)
+        self._client = Client(transport, auth=auth)
+        _mcp_clients_cache[self._cache_key] = {
+            "client": self._client,
+            "created_at": time.time(),
+        }
+
+    def _create_transport(self):
+        """Create appropriate transport based on configuration."""
+        headers = {"Content-Type": "application/json", "User-Agent": "DocsGPT-MCP/1.0"}
+        headers.update(self.custom_headers)
+
+        if self.auth_type == "api_key":
+            api_key = self.auth_credentials.get("api_key", "")
+            header_name = self.auth_credentials.get("api_key_header", "X-API-Key")
+            if api_key:
+                headers[header_name] = api_key
+        elif self.auth_type == "basic":
+            username = self.auth_credentials.get("username", "")
+            password = self.auth_credentials.get("password", "")
+            if username and password:
+                credentials = base64.b64encode(
+                    f"{username}:{password}".encode()
+                ).decode()
+                headers["Authorization"] = f"Basic {credentials}"
+        if self.transport_type == "auto":
+            if "sse" in self.server_url.lower() or self.server_url.endswith("/sse"):
+                transport_type = "sse"
+            else:
+                transport_type = "http"
+        else:
+            transport_type = self.transport_type
+        if transport_type == "sse":
+            headers.update({"Accept": "text/event-stream", "Cache-Control": "no-cache"})
+            return SSETransport(url=self.server_url, headers=headers)
+        elif transport_type == "http":
+            return StreamableHttpTransport(url=self.server_url, headers=headers)
+        elif transport_type == "stdio":
+            command = self.config.get("command", "python")
+            args = self.config.get("args", [])
+            env = self.auth_credentials if self.auth_credentials else None
+            return StdioTransport(command=command, args=args, env=env)
+        else:
+            return StreamableHttpTransport(url=self.server_url, headers=headers)
+
+    def _format_tools(self, tools_response) -> List[Dict]:
+        """Format tools response to match expected format."""
+        if hasattr(tools_response, "tools"):
+            tools = tools_response.tools
+        elif isinstance(tools_response, list):
+            tools = tools_response
+        else:
+            tools = []
+        tools_dict = []
+        for tool in tools:
+            if hasattr(tool, "name"):
+                tool_dict = {
+                    "name": tool.name,
+                    "description": tool.description,
+                }
+                if hasattr(tool, "inputSchema"):
+                    tool_dict["inputSchema"] = tool.inputSchema
+                tools_dict.append(tool_dict)
+            elif isinstance(tool, dict):
+                tools_dict.append(tool)
+            else:
+                if hasattr(tool, "model_dump"):
+                    tools_dict.append(tool.model_dump())
+                else:
+                    tools_dict.append({"name": str(tool), "description": ""})
+        return tools_dict
+
+    async def _execute_with_client(self, operation: str, *args, **kwargs):
+        """Execute operation with FastMCP client."""
+        if not self._client:
+            raise Exception("FastMCP client not initialized")
+        async with self._client:
+            if operation == "ping":
+                return await self._client.ping()
+            elif operation == "list_tools":
+                tools_response = await self._client.list_tools()
+                self.available_tools = self._format_tools(tools_response)
+                return self.available_tools
+            elif operation == "call_tool":
+                tool_name = args[0]
+                tool_args = kwargs
+                return await self._client.call_tool(tool_name, tool_args)
+            elif operation == "list_resources":
+                return await self._client.list_resources()
+            elif operation == "list_prompts":
+                return await self._client.list_prompts()
+            else:
+                raise Exception(f"Unknown operation: {operation}")
+
+    def _run_async_operation(self, operation: str, *args, **kwargs):
+        """Run async operation in sync context."""
+        try:
+            try:
+                loop = asyncio.get_running_loop()
+                import concurrent.futures
+
+                def run_in_thread():
+                    new_loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(new_loop)
+                    try:
+                        return new_loop.run_until_complete(
+                            self._execute_with_client(operation, *args, **kwargs)
+                        )
+                    finally:
+                        new_loop.close()
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(run_in_thread)
+                    return future.result(timeout=self.timeout)
+            except RuntimeError:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                try:
+                    return loop.run_until_complete(
+                        self._execute_with_client(operation, *args, **kwargs)
+                    )
+                finally:
+                    loop.close()
+        except Exception as e:
+            print(f"Error occurred while running async operation: {e}")
+            raise
+
+    def discover_tools(self) -> List[Dict]:
+        """
+        Discover available tools from the MCP server using FastMCP.
+
+        Returns:
+            List of tool definitions from the server
+        """
+        if not self.server_url:
+            return []
+        if not self._client:
+            self._setup_client()
+        try:
+            tools = self._run_async_operation("list_tools")
+            self.available_tools = tools
+            return self.available_tools
+        except Exception as e:
+            raise Exception(f"Failed to discover tools from MCP server: {str(e)}")
+
+    def execute_action(self, action_name: str, **kwargs) -> Any:
+        """
+        Execute an action on the remote MCP server using FastMCP.
+
+        Args:
+            action_name: Name of the action to execute
+            **kwargs: Parameters for the action
+
+        Returns:
+            Result from the MCP server
+        """
+        if not self.server_url:
+            raise Exception("No MCP server configured")
+        if not self._client:
+            self._setup_client()
+        cleaned_kwargs = {}
+        for key, value in kwargs.items():
+            if value == "" or value is None:
+                continue
+            cleaned_kwargs[key] = value
+        try:
+            result = self._run_async_operation(
+                "call_tool", action_name, **cleaned_kwargs
+            )
+            return self._format_result(result)
+        except Exception as e:
+            raise Exception(f"Failed to execute action '{action_name}': {str(e)}")
+
+    def _format_result(self, result) -> Dict:
+        """Format FastMCP result to match expected format."""
+        if hasattr(result, "content"):
+            content_list = []
+            for content_item in result.content:
+                if hasattr(content_item, "text"):
+                    content_list.append({"type": "text", "text": content_item.text})
+                elif hasattr(content_item, "data"):
+                    content_list.append({"type": "data", "data": content_item.data})
+                else:
+                    content_list.append(
+                        {"type": "unknown", "content": str(content_item)}
+                    )
+            return {
+                "content": content_list,
+                "isError": getattr(result, "isError", False),
+            }
+        else:
+            return result
+
+    def test_connection(self) -> Dict:
+        """
+        Test the connection to the MCP server and validate functionality.
+
+        Returns:
+            Dictionary with connection test results including tool count
+        """
+        if not self.server_url:
+            return {
+                "success": False,
+                "message": "No MCP server URL configured",
+                "tools_count": 0,
+                "transport_type": self.transport_type,
+                "auth_type": self.auth_type,
+                "error_type": "ConfigurationError",
+            }
+        if not self._client:
+            self._setup_client()
+        try:
+            if self.auth_type == "oauth":
+                return self._test_oauth_connection()
+            else:
+                return self._test_regular_connection()
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"Connection failed: {str(e)}",
+                "tools_count": 0,
+                "transport_type": self.transport_type,
+                "auth_type": self.auth_type,
+                "error_type": type(e).__name__,
+            }
+
+    def _test_regular_connection(self) -> Dict:
+        """Test connection for non-OAuth auth types."""
+        try:
+            self._run_async_operation("ping")
+            ping_success = True
+        except Exception:
+            ping_success = False
+        tools = self.discover_tools()
+
+        message = f"Successfully connected to MCP server. Found {len(tools)} tools."
+        if not ping_success:
+            message += " (Ping not supported, but tool discovery worked)"
+        return {
+            "success": True,
+            "message": message,
+            "tools_count": len(tools),
+            "transport_type": self.transport_type,
+            "auth_type": self.auth_type,
+            "ping_supported": ping_success,
+            "tools": [tool.get("name", "unknown") for tool in tools],
+        }
+
+    def _test_oauth_connection(self) -> Dict:
+        """Test connection for OAuth auth type with proper async handling."""
+        try:
+            task = mcp_oauth_task.delay(config=self.config, user=self.user_id)
+            if not task:
+                raise Exception("Failed to start OAuth authentication")
+            return {
+                "success": True,
+                "requires_oauth": True,
+                "task_id": task.id,
+                "status": "pending",
+                "message": "OAuth flow started",
+            }
+        except Exception as e:
+            return {
+                "success": False,
+                "message": f"OAuth connection failed: {str(e)}",
+                "tools_count": 0,
+                "transport_type": self.transport_type,
+                "auth_type": self.auth_type,
+                "error_type": type(e).__name__,
+            }
+
+    def get_actions_metadata(self) -> List[Dict]:
+        """
+        Get metadata for all available actions.
+
+        Returns:
+            List of action metadata dictionaries
+        """
+        actions = []
+        for tool in self.available_tools:
+            input_schema = (
+                tool.get("inputSchema")
+                or tool.get("input_schema")
+                or tool.get("schema")
+                or tool.get("parameters")
+            )
+
+            parameters_schema = {
+                "type": "object",
+                "properties": {},
+                "required": [],
+            }
+
+            if input_schema:
+                if isinstance(input_schema, dict):
+                    if "properties" in input_schema:
+                        parameters_schema = {
+                            "type": input_schema.get("type", "object"),
+                            "properties": input_schema.get("properties", {}),
+                            "required": input_schema.get("required", []),
+                        }
+
+                        for key in ["additionalProperties", "description"]:
+                            if key in input_schema:
+                                parameters_schema[key] = input_schema[key]
+                    else:
+                        parameters_schema["properties"] = input_schema
+            action = {
+                "name": tool.get("name", ""),
+                "description": tool.get("description", ""),
+                "parameters": parameters_schema,
+            }
+            actions.append(action)
+        return actions
+
+    def get_config_requirements(self) -> Dict:
+        """Get configuration requirements for the MCP tool."""
+        return {
+            "server_url": {
+                "type": "string",
+                "description": "URL of the remote MCP server (e.g., https://api.example.com/mcp or https://docs.mcp.cloudflare.com/sse)",
+                "required": True,
+            },
+            "transport_type": {
+                "type": "string",
+                "description": "Transport type for connection",
+                "enum": ["auto", "sse", "http", "stdio"],
+                "default": "auto",
+                "required": False,
+                "help": {
+                    "auto": "Automatically detect best transport",
+                    "sse": "Server-Sent Events (for real-time streaming)",
+                    "http": "HTTP streaming (recommended for production)",
+                    "stdio": "Standard I/O (for local servers)",
+                },
+            },
+            "auth_type": {
+                "type": "string",
+                "description": "Authentication type",
+                "enum": ["none", "bearer", "oauth", "api_key", "basic"],
+                "default": "none",
+                "required": True,
+                "help": {
+                    "none": "No authentication",
+                    "bearer": "Bearer token authentication",
+                    "oauth": "OAuth 2.1 authentication (with frontend integration)",
+                    "api_key": "API key authentication",
+                    "basic": "Basic authentication",
+                },
+            },
+            "auth_credentials": {
+                "type": "object",
+                "description": "Authentication credentials (varies by auth_type)",
+                "required": False,
+                "properties": {
+                    "bearer_token": {
+                        "type": "string",
+                        "description": "Bearer token for bearer auth",
+                    },
+                    "access_token": {
+                        "type": "string",
+                        "description": "Access token for OAuth (if pre-obtained)",
+                    },
+                    "api_key": {
+                        "type": "string",
+                        "description": "API key for api_key auth",
+                    },
+                    "api_key_header": {
+                        "type": "string",
+                        "description": "Header name for API key (default: X-API-Key)",
+                    },
+                    "username": {
+                        "type": "string",
+                        "description": "Username for basic auth",
+                    },
+                    "password": {
+                        "type": "string",
+                        "description": "Password for basic auth",
+                    },
+                },
+            },
+            "oauth_scopes": {
+                "type": "array",
+                "description": "OAuth scopes to request (for oauth auth_type)",
+                "items": {"type": "string"},
+                "required": False,
+                "default": [],
+            },
+            "oauth_client_name": {
+                "type": "string",
+                "description": "Client name for OAuth registration (for oauth auth_type)",
+                "default": "DocsGPT-MCP",
+                "required": False,
+            },
+            "headers": {
+                "type": "object",
+                "description": "Custom headers to send with requests",
+                "required": False,
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Request timeout in seconds",
+                "default": 30,
+                "minimum": 1,
+                "maximum": 300,
+                "required": False,
+            },
+            "command": {
+                "type": "string",
+                "description": "Command to run for STDIO transport (e.g., 'python')",
+                "required": False,
+            },
+            "args": {
+                "type": "array",
+                "description": "Arguments for STDIO command",
+                "items": {"type": "string"},
+                "required": False,
+            },
+        }
+
+
+class DocsGPTOAuth(OAuthClientProvider):
+    """
+    Custom OAuth handler for DocsGPT that uses frontend redirect instead of browser.
+    """
+
+    def __init__(
+        self,
+        mcp_url: str,
+        redirect_uri: str,
+        redis_client: Redis | None = None,
+        redis_prefix: str = "mcp_oauth:",
+        task_id: str = None,
+        scopes: str | list[str] | None = None,
+        client_name: str = "DocsGPT-MCP",
+        user_id=None,
+        db=None,
+        additional_client_metadata: dict[str, Any] | None = None,
+    ):
+        """
+        Initialize custom OAuth client provider for DocsGPT.
+
+        Args:
+            mcp_url: Full URL to the MCP endpoint
+            redirect_uri: Custom redirect URI for DocsGPT frontend
+            redis_client: Redis client for storing auth state
+            redis_prefix: Prefix for Redis keys
+            task_id: Task ID for tracking auth status
+            scopes: OAuth scopes to request
+            client_name: Name for this client during registration
+            user_id: User ID for token storage
+            db: Database instance for token storage
+            additional_client_metadata: Extra fields for OAuthClientMetadata
+        """
+
+        self.redirect_uri = redirect_uri
+        self.redis_client = redis_client
+        self.redis_prefix = redis_prefix
+        self.task_id = task_id
+        self.user_id = user_id
+        self.db = db
+
+        parsed_url = urlparse(mcp_url)
+        self.server_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
+
+        if isinstance(scopes, list):
+            scopes = " ".join(scopes)
+        client_metadata = OAuthClientMetadata(
+            client_name=client_name,
+            redirect_uris=[AnyHttpUrl(redirect_uri)],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+            scope=scopes,
+            **(additional_client_metadata or {}),
+        )
+
+        storage = DBTokenStorage(
+            server_url=self.server_base_url, user_id=self.user_id, db_client=self.db
+        )
+
+        super().__init__(
+            server_url=self.server_base_url,
+            client_metadata=client_metadata,
+            storage=storage,
+            redirect_handler=self.redirect_handler,
+            callback_handler=self.callback_handler,
+        )
+
+        self.auth_url = None
+        self.extracted_state = None
+
+    def _process_auth_url(self, authorization_url: str) -> tuple[str, str]:
+        """Process authorization URL to extract state"""
+        try:
+            parsed_url = urlparse(authorization_url)
+            query_params = parse_qs(parsed_url.query)
+
+            state_params = query_params.get("state", [])
+            if state_params:
+                state = state_params[0]
+            else:
+                raise ValueError("No state in auth URL")
+            return authorization_url, state
+        except Exception as e:
+            raise Exception(f"Failed to process auth URL: {e}")
+
+    async def redirect_handler(self, authorization_url: str) -> None:
+        """Store auth URL and state in Redis for frontend to use."""
+        auth_url, state = self._process_auth_url(authorization_url)
+        logging.info(
+            "[DocsGPTOAuth] Processed auth_url: %s, state: %s", auth_url, state
+        )
+        self.auth_url = auth_url
+        self.extracted_state = state
+
+        if self.redis_client and self.extracted_state:
+            key = f"{self.redis_prefix}auth_url:{self.extracted_state}"
+            self.redis_client.setex(key, 600, auth_url)
+            logging.info("[DocsGPTOAuth] Stored auth_url in Redis: %s", key)
+
+            if self.task_id:
+                status_key = f"mcp_oauth_status:{self.task_id}"
+                status_data = {
+                    "status": "requires_redirect",
+                    "message": "OAuth authorization required",
+                    "authorization_url": self.auth_url,
+                    "state": self.extracted_state,
+                    "requires_oauth": True,
+                    "task_id": self.task_id,
+                }
+                self.redis_client.setex(status_key, 600, json.dumps(status_data))
+
+    async def callback_handler(self) -> tuple[str, str | None]:
+        """Wait for auth code from Redis using the state value."""
+        if not self.redis_client or not self.extracted_state:
+            raise Exception("Redis client or state not configured for OAuth")
+        poll_interval = 1
+        max_wait_time = 300
+        code_key = f"{self.redis_prefix}code:{self.extracted_state}"
+
+        if self.task_id:
+            status_key = f"mcp_oauth_status:{self.task_id}"
+            status_data = {
+                "status": "awaiting_callback",
+                "message": "Waiting for OAuth callback...",
+                "authorization_url": self.auth_url,
+                "state": self.extracted_state,
+                "requires_oauth": True,
+                "task_id": self.task_id,
+            }
+            self.redis_client.setex(status_key, 600, json.dumps(status_data))
+        start_time = time.time()
+        while time.time() - start_time < max_wait_time:
+            code_data = self.redis_client.get(code_key)
+            if code_data:
+                code = code_data.decode()
+                returned_state = self.extracted_state
+
+                self.redis_client.delete(code_key)
+                self.redis_client.delete(
+                    f"{self.redis_prefix}auth_url:{self.extracted_state}"
+                )
+                self.redis_client.delete(
+                    f"{self.redis_prefix}state:{self.extracted_state}"
+                )
+
+                if self.task_id:
+                    status_data = {
+                        "status": "callback_received",
+                        "message": "OAuth callback received, completing authentication...",
+                        "task_id": self.task_id,
+                    }
+                    self.redis_client.setex(status_key, 600, json.dumps(status_data))
+                return code, returned_state
+            error_key = f"{self.redis_prefix}error:{self.extracted_state}"
+            error_data = self.redis_client.get(error_key)
+            if error_data:
+                error_msg = error_data.decode()
+                self.redis_client.delete(error_key)
+                self.redis_client.delete(
+                    f"{self.redis_prefix}auth_url:{self.extracted_state}"
+                )
+                self.redis_client.delete(
+                    f"{self.redis_prefix}state:{self.extracted_state}"
+                )
+                raise Exception(f"OAuth error: {error_msg}")
+            await asyncio.sleep(poll_interval)
+        self.redis_client.delete(f"{self.redis_prefix}auth_url:{self.extracted_state}")
+        self.redis_client.delete(f"{self.redis_prefix}state:{self.extracted_state}")
+        raise Exception("OAuth callback timeout: no code received within 5 minutes")
+
+
+class DBTokenStorage(TokenStorage):
+    def __init__(self, server_url: str, user_id: str, db_client):
+        self.server_url = server_url
+        self.user_id = user_id
+        self.db_client = db_client
+        self.collection = db_client["connector_sessions"]
+
+    @staticmethod
+    def get_base_url(url: str) -> str:
+        parsed = urlparse(url)
+        return f"{parsed.scheme}://{parsed.netloc}"
+
+    def get_db_key(self) -> dict:
+        return {
+            "server_url": self.get_base_url(self.server_url),
+            "user_id": self.user_id,
+        }
+
+    async def get_tokens(self) -> OAuthToken | None:
+        doc = await asyncio.to_thread(self.collection.find_one, self.get_db_key())
+        if not doc or "tokens" not in doc:
+            return None
+        try:
+            tokens = OAuthToken.model_validate(doc["tokens"])
+            return tokens
+        except ValidationError as e:
+            logging.error(f"Could not load tokens: {e}")
+            return None
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        await asyncio.to_thread(
+            self.collection.update_one,
+            self.get_db_key(),
+            {"$set": {"tokens": tokens.model_dump()}},
+            True,
+        )
+        logging.info(f"Saved tokens for {self.get_base_url(self.server_url)}")
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        doc = await asyncio.to_thread(self.collection.find_one, self.get_db_key())
+        if not doc or "client_info" not in doc:
+            return None
+        try:
+            client_info = OAuthClientInformationFull.model_validate(doc["client_info"])
+            tokens = await self.get_tokens()
+            if tokens is None:
+                logging.debug(
+                    "No tokens found, clearing client info to force fresh registration."
+                )
+                await asyncio.to_thread(
+                    self.collection.update_one,
+                    self.get_db_key(),
+                    {"$unset": {"client_info": ""}},
+                )
+                return None
+            return client_info
+        except ValidationError as e:
+            logging.error(f"Could not load client info: {e}")
+            return None
+
+    def _serialize_client_info(self, info: dict) -> dict:
+        if "redirect_uris" in info and isinstance(info["redirect_uris"], list):
+            info["redirect_uris"] = [str(u) for u in info["redirect_uris"]]
+        return info
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        serialized_info = self._serialize_client_info(client_info.model_dump())
+        await asyncio.to_thread(
+            self.collection.update_one,
+            self.get_db_key(),
+            {"$set": {"client_info": serialized_info}},
+            True,
+        )
+        logging.info(f"Saved client info for {self.get_base_url(self.server_url)}")
+
+    async def clear(self) -> None:
+        await asyncio.to_thread(self.collection.delete_one, self.get_db_key())
+        logging.info(f"Cleared OAuth cache for {self.get_base_url(self.server_url)}")
+
+    @classmethod
+    async def clear_all(cls, db_client) -> None:
+        collection = db_client["connector_sessions"]
+        await asyncio.to_thread(collection.delete_many, {})
+        logging.info("Cleared all OAuth client cache data.")
+
+
+class MCPOAuthManager:
+    """Manager for handling MCP OAuth callbacks."""
+
+    def __init__(self, redis_client: Redis | None, redis_prefix: str = "mcp_oauth:"):
+        self.redis_client = redis_client
+        self.redis_prefix = redis_prefix
+
+    def handle_oauth_callback(
+        self, state: str, code: str, error: Optional[str] = None
+    ) -> bool:
+        """
+        Handle OAuth callback from provider.
+
+        Args:
+            state: The state parameter from OAuth callback
+            code: The authorization code from OAuth callback
+            error: Error message if OAuth failed
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            if not self.redis_client or not state:
+                raise Exception("Redis client or state not provided")
+            if error:
+                error_key = f"{self.redis_prefix}error:{state}"
+                self.redis_client.setex(error_key, 300, error)
+                raise Exception(f"OAuth error received: {error}")
+            code_key = f"{self.redis_prefix}code:{state}"
+            self.redis_client.setex(code_key, 300, code)
+
+            state_key = f"{self.redis_prefix}state:{state}"
+            self.redis_client.setex(state_key, 300, "completed")
+
+            return True
+        except Exception as e:
+            logging.error(f"Error handling OAuth callback: {e}")
+            return False
+
+    def get_oauth_status(self, task_id: str) -> Dict[str, Any]:
+        """Get current status of OAuth flow using provided task_id."""
+        if not task_id:
+            return {"status": "not_started", "message": "OAuth flow not started"}
+        return mcp_oauth_status_task(task_id)

application/agents/tools/proxy_handler.py

@@ -1,63 +0,0 @@
-import logging
-import requests
-from typing import Dict, Optional
-from bson.objectid import ObjectId
-
-from application.core.mongo_db import MongoDB
-
-logger = logging.getLogger(__name__)
-
-# Get MongoDB connection
-mongo = MongoDB.get_client()
-db = mongo["docsgpt"]
-proxies_collection = db["proxies"]
-
-def get_proxy_config(proxy_id: str) -> Optional[Dict[str, str]]:
-    """
-    Retrieve proxy configuration from the database.
-    
-    Args:
-        proxy_id: The ID of the proxy configuration
-        
-    Returns:
-        A dictionary with proxy configuration or None if not found
-    """
-    if not proxy_id or proxy_id == "none":
-        return None
-        
-    try:
-        if ObjectId.is_valid(proxy_id):
-            proxy_config = proxies_collection.find_one({"_id": ObjectId(proxy_id)})
-            if proxy_config and "connection" in proxy_config:
-                connection_str = proxy_config["connection"].strip()
-                if connection_str:
-                    # Format proxy for requests library
-                    return {
-                        "http": connection_str,
-                        "https": connection_str
-                    }
-        return None
-    except Exception as e:
-        logger.error(f"Error retrieving proxy configuration: {e}")
-        return None
-
-def apply_proxy_to_request(request_func, proxy_id=None, **kwargs):
-    """
-    Apply proxy configuration to a requests function if available.
-    This is a minimal wrapper that doesn't change the function signature.
-    
-    Args:
-        request_func: The requests function to call (e.g., requests.get, requests.post)
-        proxy_id: Optional proxy ID to use
-        **kwargs: Arguments to pass to the request function
-    
-    Returns:
-        The response from the request
-    """
-    if proxy_id:
-        proxy_config = get_proxy_config(proxy_id)
-        if proxy_config:
-            kwargs['proxies'] = proxy_config
-            logger.info(f"Using proxy for request")
-    
-    return request_func(**kwargs)

application/agents/tools/read_webpage.py

@@ -0,0 +1,83 @@
+import requests
+from markdownify import markdownify
+from application.agents.tools.base import Tool
+from urllib.parse import urlparse
+
+class ReadWebpageTool(Tool):
+    """
+    Read Webpage (browser)
+    A tool to fetch the HTML content of a URL and convert it to Markdown.
+    """
+
+    def __init__(self, config=None):
+        """
+        Initializes the tool.
+        :param config: Optional configuration dictionary. Not used by this tool.
+        """
+        self.config = config
+
+    def execute_action(self, action_name: str, **kwargs) -> str:
+        """
+        Executes the specified action. For this tool, the only action is 'read_webpage'.
+
+        :param action_name: The name of the action to execute. Should be 'read_webpage'.
+        :param kwargs: Keyword arguments, must include 'url'.
+        :return: The Markdown content of the webpage or an error message.
+        """
+        if action_name != "read_webpage":
+            return f"Error: Unknown action '{action_name}'. This tool only supports 'read_webpage'."
+
+        url = kwargs.get("url")
+        if not url:
+            return "Error: URL parameter is missing."
+
+        # Ensure the URL has a scheme (if not, default to http)
+        parsed_url = urlparse(url)
+        if not parsed_url.scheme:
+            url = "http://" + url
+        
+        try:
+            response = requests.get(url, timeout=10, headers={'User-Agent': 'DocsGPT-Agent/1.0'})
+            response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
+            
+            html_content = response.text
+            #soup = BeautifulSoup(html_content, 'html.parser')
+            
+            
+            markdown_content = markdownify(html_content, heading_style="ATX", newline_style="BACKSLASH")
+            
+            return markdown_content
+
+        except requests.exceptions.RequestException as e:
+            return f"Error fetching URL {url}: {e}"
+        except Exception as e:
+            return f"Error processing URL {url}: {e}"
+
+    def get_actions_metadata(self):
+        """
+        Returns metadata for the actions supported by this tool.
+        """
+        return [
+            {
+                "name": "read_webpage",
+                "description": "Fetches the HTML content of a given URL and returns it as clean Markdown text. Input must be a valid URL.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "url": {
+                            "type": "string",
+                            "description": "The fully qualified URL of the webpage to read (e.g., 'https://www.example.com').",
+                        }
+                    },
+                    "required": ["url"],
+                    "additionalProperties": False,
+                },
+            }
+        ]
+
+    def get_config_requirements(self):
+        """
+        Returns a dictionary describing the configuration requirements for the tool.
+        This tool does not require any specific configuration.
+        """
+        return {}

application/agents/tools/tool_action_parser.py

@@ -17,26 +17,45 @@ class ToolActionParser:
         return parser(call)
 
     def _parse_openai_llm(self, call):
-        if isinstance(call, dict):
-            try:
-                call_args = json.loads(call["function"]["arguments"])
-                tool_id = call["function"]["name"].split("_")[-1]
-                action_name = call["function"]["name"].rsplit("_", 1)[0]
-            except (KeyError, TypeError) as e:
-                logger.error(f"Error parsing OpenAI LLM call: {e}")
-                return None, None, None
-        else:
-            try:
-                call_args = json.loads(call.function.arguments)
-                tool_id = call.function.name.split("_")[-1]
-                action_name = call.function.name.rsplit("_", 1)[0]
-            except (AttributeError, TypeError) as e:
-                logger.error(f"Error parsing OpenAI LLM call: {e}")
+        try:
+            call_args = json.loads(call.arguments)
+            tool_parts = call.name.split("_")
+            
+            # If the tool name doesn't contain an underscore, it's likely a hallucinated tool
+            if len(tool_parts) < 2:
+                logger.warning(f"Invalid tool name format: {call.name}. Expected format: action_name_tool_id")
                 return None, None, None
+                
+            tool_id = tool_parts[-1]
+            action_name = "_".join(tool_parts[:-1])
+            
+            # Validate that tool_id looks like a numerical ID
+            if not tool_id.isdigit():
+                logger.warning(f"Tool ID '{tool_id}' is not numerical. This might be a hallucinated tool call.")
+                
+        except (AttributeError, TypeError) as e:
+            logger.error(f"Error parsing OpenAI LLM call: {e}")
+            return None, None, None
         return tool_id, action_name, call_args
 
     def _parse_google_llm(self, call):
-        call_args = call.args
-        tool_id = call.name.split("_")[-1]
-        action_name = call.name.rsplit("_", 1)[0]
+        try:
+            call_args = call.arguments
+            tool_parts = call.name.split("_")
+            
+            # If the tool name doesn't contain an underscore, it's likely a hallucinated tool
+            if len(tool_parts) < 2:
+                logger.warning(f"Invalid tool name format: {call.name}. Expected format: action_name_tool_id")
+                return None, None, None
+                
+            tool_id = tool_parts[-1]
+            action_name = "_".join(tool_parts[:-1])
+            
+            # Validate that tool_id looks like a numerical ID
+            if not tool_id.isdigit():
+                logger.warning(f"Tool ID '{tool_id}' is not numerical. This might be a hallucinated tool call.")
+                
+        except (AttributeError, TypeError) as e:
+            logger.error(f"Error parsing Google LLM call: {e}")
+            return None, None, None
         return tool_id, action_name, call_args

application/agents/tools/tool_manager.py

@@ -23,16 +23,23 @@ class ToolManager:
                     tool_config = self.config.get(name, {})
                     self.tools[name] = obj(tool_config)
 
-    def load_tool(self, tool_name, tool_config):
+    def load_tool(self, tool_name, tool_config, user_id=None):
         self.config[tool_name] = tool_config
         module = importlib.import_module(f"application.agents.tools.{tool_name}")
         for member_name, obj in inspect.getmembers(module, inspect.isclass):
             if issubclass(obj, Tool) and obj is not Tool:
-                return obj(tool_config)
+                if tool_name == "mcp_tool" and user_id:
+                    return obj(tool_config, user_id)
+                else:
+                    return obj(tool_config)
 
-    def execute_action(self, tool_name, action_name, **kwargs):
+    def execute_action(self, tool_name, action_name, user_id=None, **kwargs):
         if tool_name not in self.tools:
             raise ValueError(f"Tool '{tool_name}' not loaded")
+        if tool_name == "mcp_tool" and user_id:
+            tool_config = self.config.get(tool_name, {})
+            tool = self.load_tool(tool_name, tool_config, user_id)
+            return tool.execute_action(action_name, **kwargs)
         return self.tools[tool_name].execute_action(action_name, **kwargs)
 
     def get_all_actions_metadata(self):

application/api/__init__.py

@@ -0,0 +1,7 @@
+from flask_restx import Api
+
+api = Api(
+    version="1.0",
+    title="DocsGPT API",
+    description="API for DocsGPT",
+)

application/api/answer/__init__.py

@@ -0,0 +1,19 @@
+from flask import Blueprint
+
+from application.api import api
+from application.api.answer.routes.answer import AnswerResource
+from application.api.answer.routes.base import answer_ns
+from application.api.answer.routes.stream import StreamResource
+
+
+answer = Blueprint("answer", __name__)
+
+api.add_namespace(answer_ns)
+
+
+def init_answer_routes():
+    api.add_resource(StreamResource, "/stream")
+    api.add_resource(AnswerResource, "/api/answer")
+
+
+init_answer_routes()

application/api/answer/routes.py

@@ -1,798 +0,0 @@
-import asyncio
-import datetime
-import json
-import logging
-import os
-import traceback
-
-from bson.dbref import DBRef
-from bson.objectid import ObjectId
-from flask import Blueprint, make_response, request, Response
-from flask_restx import fields, Namespace, Resource
-
-from application.agents.agent_creator import AgentCreator
-
-from application.core.mongo_db import MongoDB
-from application.core.settings import settings
-from application.error import bad_request
-from application.extensions import api
-from application.llm.llm_creator import LLMCreator
-from application.retriever.retriever_creator import RetrieverCreator
-from application.utils import check_required_fields, limit_chat_history
-
-logger = logging.getLogger(__name__)
-
-mongo = MongoDB.get_client()
-db = mongo["docsgpt"]
-conversations_collection = db["conversations"]
-sources_collection = db["sources"]
-prompts_collection = db["prompts"]
-api_key_collection = db["api_keys"]
-user_logs_collection = db["user_logs"]
-
-answer = Blueprint("answer", __name__)
-answer_ns = Namespace("answer", description="Answer related operations", path="/")
-api.add_namespace(answer_ns)
-
-gpt_model = ""
-# to have some kind of default behaviour
-if settings.LLM_NAME == "openai":
-    gpt_model = "gpt-4o-mini"
-elif settings.LLM_NAME == "anthropic":
-    gpt_model = "claude-2"
-elif settings.LLM_NAME == "groq":
-    gpt_model = "llama3-8b-8192"
-elif settings.LLM_NAME == "novita":
-    gpt_model = "deepseek/deepseek-r1"
-
-if settings.MODEL_NAME:  # in case there is particular model name configured
-    gpt_model = settings.MODEL_NAME
-
-# load the prompts
-current_dir = os.path.dirname(
-    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-)
-with open(os.path.join(current_dir, "prompts", "chat_combine_default.txt"), "r") as f:
-    chat_combine_template = f.read()
-
-with open(os.path.join(current_dir, "prompts", "chat_reduce_prompt.txt"), "r") as f:
-    chat_reduce_template = f.read()
-
-with open(os.path.join(current_dir, "prompts", "chat_combine_creative.txt"), "r") as f:
-    chat_combine_creative = f.read()
-
-with open(os.path.join(current_dir, "prompts", "chat_combine_strict.txt"), "r") as f:
-    chat_combine_strict = f.read()
-
-api_key_set = settings.API_KEY is not None
-embeddings_key_set = settings.EMBEDDINGS_KEY is not None
-
-
-async def async_generate(chain, question, chat_history):
-    result = await chain.arun({"question": question, "chat_history": chat_history})
-    return result
-
-
-def run_async_chain(chain, question, chat_history):
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-    result = {}
-    try:
-        answer = loop.run_until_complete(async_generate(chain, question, chat_history))
-    finally:
-        loop.close()
-    result["answer"] = answer
-    return result
-
-
-def get_data_from_api_key(api_key):
-    data = api_key_collection.find_one({"key": api_key})
-    # # Raise custom exception if the API key is not found
-    if data is None:
-        raise Exception("Invalid API Key, please generate new key", 401)
-
-    if "source" in data and isinstance(data["source"], DBRef):
-        source_doc = db.dereference(data["source"])
-        data["source"] = str(source_doc["_id"])
-        if "retriever" in source_doc:
-            data["retriever"] = source_doc["retriever"]
-    else:
-        data["source"] = {}
-    return data
-
-
-def get_retriever(source_id: str):
-    doc = sources_collection.find_one({"_id": ObjectId(source_id)})
-    if doc is None:
-        raise Exception("Source document does not exist", 404)
-    retriever_name = None if "retriever" not in doc else doc["retriever"]
-    return retriever_name
-
-
-def is_azure_configured():
-    return (
-        settings.OPENAI_API_BASE
-        and settings.OPENAI_API_VERSION
-        and settings.AZURE_DEPLOYMENT_NAME
-    )
-
-
-def save_conversation(
-    conversation_id,
-    question,
-    response,
-    source_log_docs,
-    tool_calls,
-    llm,
-    decoded_token,
-    index=None,
-    api_key=None,
-):
-    current_time = datetime.datetime.now(datetime.timezone.utc)
-    if conversation_id is not None and index is not None:
-        conversations_collection.update_one(
-            {"_id": ObjectId(conversation_id), f"queries.{index}": {"$exists": True}},
-            {
-                "$set": {
-                    f"queries.{index}.prompt": question,
-                    f"queries.{index}.response": response,
-                    f"queries.{index}.sources": source_log_docs,
-                    f"queries.{index}.tool_calls": tool_calls,
-                    f"queries.{index}.timestamp": current_time,
-                }
-            },
-        )
-        ##remove following queries from the array
-        conversations_collection.update_one(
-            {"_id": ObjectId(conversation_id), f"queries.{index}": {"$exists": True}},
-            {"$push": {"queries": {"$each": [], "$slice": index + 1}}},
-        )
-    elif conversation_id is not None and conversation_id != "None":
-        conversations_collection.update_one(
-            {"_id": ObjectId(conversation_id)},
-            {
-                "$push": {
-                    "queries": {
-                        "prompt": question,
-                        "response": response,
-                        "sources": source_log_docs,
-                        "tool_calls": tool_calls,
-                        "timestamp": current_time,
-                    }
-                }
-            },
-        )
-
-    else:
-        # create new conversation
-        # generate summary
-        messages_summary = [
-            {
-                "role": "assistant",
-                "content": "Summarise following conversation in no more than 3 "
-                "words, respond ONLY with the summary, use the same "
-                "language as the system",
-            },
-            {
-                "role": "user",
-                "content": "Summarise following conversation in no more than 3 words, "
-                "respond ONLY with the summary, use the same language as the "
-                "system \n\nUser: " + question + "\n\n" + "AI: " + response,
-            },
-        ]
-
-        completion = llm.gen(model=gpt_model, messages=messages_summary, max_tokens=30)
-        conversation_data = {
-            "user": decoded_token.get("sub"),
-            "date": datetime.datetime.utcnow(),
-            "name": completion,
-            "queries": [
-                {
-                    "prompt": question,
-                    "response": response,
-                    "sources": source_log_docs,
-                    "tool_calls": tool_calls,
-                    "timestamp": current_time,
-                }
-            ],
-        }
-        if api_key:
-            api_key_doc = api_key_collection.find_one({"key": api_key})
-            if api_key_doc:
-                conversation_data["api_key"] = api_key_doc["key"]
-        conversation_id = conversations_collection.insert_one(
-            conversation_data
-        ).inserted_id
-    return conversation_id
-
-
-def get_prompt(prompt_id):
-    if prompt_id == "default":
-        prompt = chat_combine_template
-    elif prompt_id == "creative":
-        prompt = chat_combine_creative
-    elif prompt_id == "strict":
-        prompt = chat_combine_strict
-    else:
-        prompt = prompts_collection.find_one({"_id": ObjectId(prompt_id)})["content"]
-    return prompt
-
-
-def complete_stream(
-    question,
-    agent,
-    retriever,
-    conversation_id,
-    user_api_key,
-    decoded_token,
-    isNoneDoc=False,
-    index=None,
-    should_save_conversation=True,
-):
-    try:
-        response_full = ""
-        source_log_docs = []
-        tool_calls = []
-
-        answer = agent.gen(query=question, retriever=retriever)
-
-        for line in answer:
-            if "answer" in line:
-                response_full += str(line["answer"])
-                data = json.dumps({"type": "answer", "answer": line["answer"]})
-                yield f"data: {data}\n\n"
-            elif "sources" in line:
-                truncated_sources = []
-                source_log_docs = line["sources"]
-                for source in line["sources"]:
-                    truncated_source = source.copy()
-                    if "text" in truncated_source:
-                        truncated_source["text"] = (
-                            truncated_source["text"][:100].strip() + "..."
-                        )
-                    truncated_sources.append(truncated_source)
-                if len(truncated_sources) > 0:
-                    data = json.dumps({"type": "source", "source": truncated_sources})
-                    yield f"data: {data}\n\n"
-            elif "tool_calls" in line:
-                tool_calls = line["tool_calls"]
-                data = json.dumps({"type": "tool_calls", "tool_calls": tool_calls})
-                yield f"data: {data}\n\n"
-
-        if isNoneDoc:
-            for doc in source_log_docs:
-                doc["source"] = "None"
-
-        llm = LLMCreator.create_llm(
-            settings.LLM_NAME,
-            api_key=settings.API_KEY,
-            user_api_key=user_api_key,
-            decoded_token=decoded_token,
-        )
-
-        if should_save_conversation:
-            conversation_id = save_conversation(
-                conversation_id,
-                question,
-                response_full,
-                source_log_docs,
-                tool_calls,
-                llm,
-                decoded_token,
-                index,
-                api_key=user_api_key,
-            )
-        else:
-            conversation_id = None
-
-        # send data.type = "end" to indicate that the stream has ended as json
-        data = json.dumps({"type": "id", "id": str(conversation_id)})
-        yield f"data: {data}\n\n"
-
-        retriever_params = retriever.get_params()
-        user_logs_collection.insert_one(
-            {
-                "action": "stream_answer",
-                "level": "info",
-                "user": decoded_token.get("sub"),
-                "api_key": user_api_key,
-                "question": question,
-                "response": response_full,
-                "sources": source_log_docs,
-                "retriever_params": retriever_params,
-                "timestamp": datetime.datetime.now(datetime.timezone.utc),
-            }
-        )
-        data = json.dumps({"type": "end"})
-        yield f"data: {data}\n\n"
-    except Exception as e:
-        logger.error(f"Error in stream: {str(e)}")
-        logger.error(traceback.format_exc())
-        data = json.dumps(
-            {
-                "type": "error",
-                "error": "Please try again later. We apologize for any inconvenience.",
-            }
-        )
-        yield f"data: {data}\n\n"
-        return
-
-
-@answer_ns.route("/stream")
-class Stream(Resource):
-    stream_model = api.model(
-        "StreamModel",
-        {
-            "question": fields.String(
-                required=True, description="Question to be asked"
-            ),
-            "history": fields.List(
-                fields.String, required=False, description="Chat history"
-            ),
-            "conversation_id": fields.String(
-                required=False, description="Conversation ID"
-            ),
-            "prompt_id": fields.String(
-                required=False, default="default", description="Prompt ID"
-            ),
-            "proxy_id": fields.String(
-                required=False, description="Proxy ID to use for API calls"
-            ),
-            "chunks": fields.Integer(
-                required=False, default=2, description="Number of chunks"
-            ),
-            "token_limit": fields.Integer(required=False, description="Token limit"),
-            "retriever": fields.String(required=False, description="Retriever type"),
-            "api_key": fields.String(required=False, description="API key"),
-            "active_docs": fields.String(
-                required=False, description="Active documents"
-            ),
-            "isNoneDoc": fields.Boolean(
-                required=False, description="Flag indicating if no document is used"
-            ),
-            "index": fields.Integer(
-                required=False, description="The position where query is to be updated"
-            ),
-            "save_conversation": fields.Boolean(
-                required=False, default=True, description="Flag to save conversation"
-            ),
-        },
-    )
-
-    @api.expect(stream_model)
-    @api.doc(description="Stream a response based on the question and retriever")
-    def post(self):
-        data = request.get_json()
-        required_fields = ["question"]
-        if "index" in data:
-            required_fields = ["question", "conversation_id"]
-        missing_fields = check_required_fields(data, required_fields)
-        if missing_fields:
-            return missing_fields
-
-        save_conv = data.get("save_conversation", True)
-
-        try:
-            question = data["question"]
-            history = limit_chat_history(
-                json.loads(data.get("history", [])), gpt_model=gpt_model
-            )
-            conversation_id = data.get("conversation_id")
-            prompt_id = data.get("prompt_id", "default")
-            proxy_id = data.get("proxy_id", None)
-
-            index = data.get("index", None)
-            chunks = int(data.get("chunks", 2))
-            token_limit = data.get("token_limit", settings.DEFAULT_MAX_HISTORY)
-            retriever_name = data.get("retriever", "classic")
-
-            if "api_key" in data:
-                data_key = get_data_from_api_key(data["api_key"])
-                chunks = int(data_key.get("chunks", 2))
-                prompt_id = data_key.get("prompt_id", "default")
-                proxy_id = data_key.get("proxy_id", None)
-                source = {"active_docs": data_key.get("source")}
-                retriever_name = data_key.get("retriever", retriever_name)
-                user_api_key = data["api_key"]
-                decoded_token = {"sub": data_key.get("user")}
-
-            elif "active_docs" in data:
-                source = {"active_docs": data["active_docs"]}
-                retriever_name = get_retriever(data["active_docs"]) or retriever_name
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            else:
-                source = {}
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            if not decoded_token:
-                return make_response({"error": "Unauthorized"}, 401)
-
-            logger.info(
-                f"/stream - request_data: {data}, source: {source}",
-                extra={"data": json.dumps({"request_data": data, "source": source})},
-            )
-
-            prompt = get_prompt(prompt_id)
-            if "isNoneDoc" in data and data["isNoneDoc"] is True:
-                chunks = 0
-
-            agent = AgentCreator.create_agent(
-                settings.AGENT_NAME,
-                endpoint="stream",
-                llm_name=settings.LLM_NAME,
-                gpt_model=gpt_model,
-                api_key=settings.API_KEY,
-                user_api_key=user_api_key,
-                prompt=prompt,
-                proxy_id=proxy_id,
-                chat_history=history,
-                decoded_token=decoded_token,
-            )
-
-            retriever = RetrieverCreator.create_retriever(
-                retriever_name,
-                source=source,
-                chat_history=history,
-                prompt=prompt,
-                chunks=chunks,
-                token_limit=token_limit,
-                gpt_model=gpt_model,
-                user_api_key=user_api_key,
-                decoded_token=decoded_token,
-            )
-
-            return Response(
-                complete_stream(
-                    question=question,
-                    agent=agent,
-                    retriever=retriever,
-                    conversation_id=conversation_id,
-                    user_api_key=user_api_key,
-                    decoded_token=decoded_token,
-                    isNoneDoc=data.get("isNoneDoc"),
-                    index=index,
-                    should_save_conversation=save_conv,
-                ),
-                mimetype="text/event-stream",
-            )
-
-        except ValueError:
-            message = "Malformed request body"
-            logger.error(f"/stream - error: {message}")
-            return Response(
-                error_stream_generate(message),
-                status=400,
-                mimetype="text/event-stream",
-            )
-        except Exception as e:
-            logger.error(
-                f"/stream - error: {str(e)} - traceback: {traceback.format_exc()}",
-                extra={"error": str(e), "traceback": traceback.format_exc()},
-            )
-            status_code = 400
-            return Response(
-                error_stream_generate("Unknown error occurred"),
-                status=status_code,
-                mimetype="text/event-stream",
-            )
-
-
-def error_stream_generate(err_response):
-    data = json.dumps({"type": "error", "error": err_response})
-    yield f"data: {data}\n\n"
-
-
-@answer_ns.route("/api/answer")
-class Answer(Resource):
-    answer_model = api.model(
-        "AnswerModel",
-        {
-            "question": fields.String(
-                required=True, description="The question to answer"
-            ),
-            "history": fields.List(
-                fields.String, required=False, description="Conversation history"
-            ),
-            "conversation_id": fields.String(
-                required=False, description="Conversation ID"
-            ),
-            "prompt_id": fields.String(
-                required=False, default="default", description="Prompt ID"
-            ),
-            "proxy_id": fields.String(
-                required=False, description="Proxy ID to use for API calls"
-            ),
-            "chunks": fields.Integer(
-                required=False, default=2, description="Number of chunks"
-            ),
-            "token_limit": fields.Integer(required=False, description="Token limit"),
-            "retriever": fields.String(required=False, description="Retriever type"),
-            "api_key": fields.String(required=False, description="API key"),
-            "active_docs": fields.String(
-                required=False, description="Active documents"
-            ),
-            "isNoneDoc": fields.Boolean(
-                required=False, description="Flag indicating if no document is used"
-            ),
-        },
-    )
-
-    @api.expect(answer_model)
-    @api.doc(description="Provide an answer based on the question and retriever")
-    def post(self):
-        data = request.get_json()
-        required_fields = ["question"]
-        missing_fields = check_required_fields(data, required_fields)
-        if missing_fields:
-            return missing_fields
-
-        try:
-            question = data["question"]
-            history = limit_chat_history(
-                json.loads(data.get("history", [])), gpt_model=gpt_model
-            )
-            conversation_id = data.get("conversation_id")
-            prompt_id = data.get("prompt_id", "default")
-            proxy_id = data.get("proxy_id", None)
-            chunks = int(data.get("chunks", 2))
-            token_limit = data.get("token_limit", settings.DEFAULT_MAX_HISTORY)
-            retriever_name = data.get("retriever", "classic")
-
-            if "api_key" in data:
-                data_key = get_data_from_api_key(data["api_key"])
-                chunks = int(data_key.get("chunks", 2))
-                prompt_id = data_key.get("prompt_id", "default")
-                proxy_id = data_key.get("proxy_id", None)
-                source = {"active_docs": data_key.get("source")}
-                retriever_name = data_key.get("retriever", retriever_name)
-                user_api_key = data["api_key"]
-                decoded_token = {"sub": data_key.get("user")}
-
-            elif "active_docs" in data:
-                source = {"active_docs": data["active_docs"]}
-                retriever_name = get_retriever(data["active_docs"]) or retriever_name
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            else:
-                source = {}
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            if not decoded_token:
-                return make_response({"error": "Unauthorized"}, 401)
-
-            prompt = get_prompt(prompt_id)
-
-            logger.info(
-                f"/api/answer - request_data: {data}, source: {source}",
-                extra={"data": json.dumps({"request_data": data, "source": source})},
-            )
-
-            agent = AgentCreator.create_agent(
-                settings.AGENT_NAME,
-                endpoint="api/answer",
-                llm_name=settings.LLM_NAME,
-                gpt_model=gpt_model,
-                api_key=settings.API_KEY,
-                user_api_key=user_api_key,
-                prompt=prompt,
-                proxy_id=proxy_id,
-                chat_history=history,
-                decoded_token=decoded_token,
-            )
-
-            retriever = RetrieverCreator.create_retriever(
-                retriever_name,
-                source=source,
-                chat_history=history,
-                prompt=prompt,
-                chunks=chunks,
-                token_limit=token_limit,
-                gpt_model=gpt_model,
-                user_api_key=user_api_key,
-                decoded_token=decoded_token,
-            )
-
-            response_full = ""
-            source_log_docs = []
-            tool_calls = []
-            stream_ended = False
-
-            for line in complete_stream(
-                question=question,
-                agent=agent,
-                retriever=retriever,
-                conversation_id=conversation_id,
-                user_api_key=user_api_key,
-                decoded_token=decoded_token,
-                isNoneDoc=data.get("isNoneDoc"),
-                index=None,
-                should_save_conversation=False,
-            ):
-                try:
-                    event_data = line.replace("data: ", "").strip()
-                    event = json.loads(event_data)
-
-                    if event["type"] == "answer":
-                        response_full += event["answer"]
-                    elif event["type"] == "source":
-                        source_log_docs = event["source"]
-                    elif event["type"] == "tool_calls":
-                        tool_calls = event["tool_calls"]
-                    elif event["type"] == "error":
-                        logger.error(f"Error from stream: {event['error']}")
-                        return bad_request(500, event["error"])
-                    elif event["type"] == "end":
-                        stream_ended = True
-
-                except (json.JSONDecodeError, KeyError) as e:
-                    logger.warning(f"Error parsing stream event: {e}, line: {line}")
-                    continue
-
-            if not stream_ended:
-                logger.error("Stream ended unexpectedly without an 'end' event.")
-                return bad_request(500, "Stream ended unexpectedly.")
-
-            if data.get("isNoneDoc"):
-                for doc in source_log_docs:
-                    doc["source"] = "None"
-
-            llm = LLMCreator.create_llm(
-                settings.LLM_NAME,
-                api_key=settings.API_KEY,
-                user_api_key=user_api_key,
-                decoded_token=decoded_token,
-            )
-
-            result = {"answer": response_full, "sources": source_log_docs}
-            result["conversation_id"] = str(
-                save_conversation(
-                    conversation_id,
-                    question,
-                    response_full,
-                    source_log_docs,
-                    tool_calls,
-                    llm,
-                    decoded_token,
-                    api_key=user_api_key,
-                )
-            )
-
-            retriever_params = retriever.get_params()
-            user_logs_collection.insert_one(
-                {
-                    "action": "api_answer",
-                    "level": "info",
-                    "user": decoded_token.get("sub"),
-                    "api_key": user_api_key,
-                    "question": question,
-                    "response": response_full,
-                    "sources": source_log_docs,
-                    "retriever_params": retriever_params,
-                    "timestamp": datetime.datetime.now(datetime.timezone.utc),
-                }
-            )
-
-        except Exception as e:
-            logger.error(
-                f"/api/answer - error: {str(e)} - traceback: {traceback.format_exc()}",
-                extra={"error": str(e), "traceback": traceback.format_exc()},
-            )
-            return bad_request(500, str(e))
-
-        return make_response(result, 200)
-
-
-@answer_ns.route("/api/search")
-class Search(Resource):
-    search_model = api.model(
-        "SearchModel",
-        {
-            "question": fields.String(
-                required=True, description="The question to search"
-            ),
-            "chunks": fields.Integer(
-                required=False, default=2, description="Number of chunks"
-            ),
-            "api_key": fields.String(
-                required=False, description="API key for authentication"
-            ),
-            "active_docs": fields.String(
-                required=False, description="Active documents for retrieval"
-            ),
-            "retriever": fields.String(required=False, description="Retriever type"),
-            "token_limit": fields.Integer(
-                required=False, description="Limit for tokens"
-            ),
-            "isNoneDoc": fields.Boolean(
-                required=False, description="Flag indicating if no document is used"
-            ),
-        },
-    )
-
-    @api.expect(search_model)
-    @api.doc(
-        description="Search for relevant documents based on the question and retriever"
-    )
-    def post(self):
-        data = request.get_json()
-        required_fields = ["question"]
-        missing_fields = check_required_fields(data, required_fields)
-        if missing_fields:
-            return missing_fields
-
-        try:
-            question = data["question"]
-            chunks = int(data.get("chunks", 2))
-            token_limit = data.get("token_limit", settings.DEFAULT_MAX_HISTORY)
-            retriever_name = data.get("retriever", "classic")
-
-            if "api_key" in data:
-                data_key = get_data_from_api_key(data["api_key"])
-                chunks = int(data_key.get("chunks", 2))
-                source = {"active_docs": data_key.get("source")}
-                user_api_key = data["api_key"]
-                decoded_token = {"sub": data_key.get("user")}
-
-            elif "active_docs" in data:
-                source = {"active_docs": data["active_docs"]}
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            else:
-                source = {}
-                user_api_key = None
-                decoded_token = request.decoded_token
-
-            if not decoded_token:
-                return make_response({"error": "Unauthorized"}, 401)
-
-            logger.info(
-                f"/api/answer - request_data: {data}, source: {source}",
-                extra={"data": json.dumps({"request_data": data, "source": source})},
-            )
-
-            retriever = RetrieverCreator.create_retriever(
-                retriever_name,
-                source=source,
-                chat_history=[],
-                prompt="default",
-                chunks=chunks,
-                token_limit=token_limit,
-                gpt_model=gpt_model,
-                user_api_key=user_api_key,
-                decoded_token=decoded_token,
-            )
-
-            docs = retriever.search(question)
-            retriever_params = retriever.get_params()
-
-            user_logs_collection.insert_one(
-                {
-                    "action": "api_search",
-                    "level": "info",
-                    "user": decoded_token.get("sub"),
-                    "api_key": user_api_key,
-                    "question": question,
-                    "sources": docs,
-                    "retriever_params": retriever_params,
-                    "timestamp": datetime.datetime.now(datetime.timezone.utc),
-                }
-            )
-
-            if data.get("isNoneDoc"):
-                for doc in docs:
-                    doc["source"] = "None"
-
-        except Exception as e:
-            logger.error(
-                f"/api/search - error: {str(e)} - traceback: {traceback.format_exc()}",
-                extra={"error": str(e), "traceback": traceback.format_exc()},
-            )
-            return bad_request(500, str(e))
-
-        return make_response(docs, 200)

application/api/answer/routes/answer.py

@@ -0,0 +1,122 @@
+import logging
+import traceback
+
+from flask import make_response, request
+from flask_restx import fields, Resource
+
+from application.api import api
+
+from application.api.answer.routes.base import answer_ns, BaseAnswerResource
+
+from application.api.answer.services.stream_processor import StreamProcessor
+
+logger = logging.getLogger(__name__)
+
+
+@answer_ns.route("/api/answer")
+class AnswerResource(Resource, BaseAnswerResource):
+    def __init__(self, *args, **kwargs):
+        Resource.__init__(self, *args, **kwargs)
+        BaseAnswerResource.__init__(self)
+
+    answer_model = answer_ns.model(
+        "AnswerModel",
+        {
+            "question": fields.String(
+                required=True, description="Question to be asked"
+            ),
+            "history": fields.List(
+                fields.String,
+                required=False,
+                description="Conversation history (only for new conversations)",
+            ),
+            "conversation_id": fields.String(
+                required=False,
+                description="Existing conversation ID (loads history)",
+            ),
+            "prompt_id": fields.String(
+                required=False, default="default", description="Prompt ID"
+            ),
+            "chunks": fields.Integer(
+                required=False, default=2, description="Number of chunks"
+            ),
+            "token_limit": fields.Integer(required=False, description="Token limit"),
+            "retriever": fields.String(required=False, description="Retriever type"),
+            "api_key": fields.String(required=False, description="API key"),
+            "active_docs": fields.String(
+                required=False, description="Active documents"
+            ),
+            "isNoneDoc": fields.Boolean(
+                required=False, description="Flag indicating if no document is used"
+            ),
+            "save_conversation": fields.Boolean(
+                required=False,
+                default=True,
+                description="Whether to save the conversation",
+            ),
+        },
+    )
+
+    @api.expect(answer_model)
+    @api.doc(description="Provide a response based on the question and retriever")
+    def post(self):
+        data = request.get_json()
+        if error := self.validate_request(data):
+            return error
+        decoded_token = getattr(request, "decoded_token", None)
+        processor = StreamProcessor(data, decoded_token)
+        try:
+            processor.initialize()
+            if not processor.decoded_token:
+                return make_response({"error": "Unauthorized"}, 401)
+            agent = processor.create_agent()
+            retriever = processor.create_retriever()
+
+            stream = self.complete_stream(
+                question=data["question"],
+                agent=agent,
+                retriever=retriever,
+                conversation_id=processor.conversation_id,
+                user_api_key=processor.agent_config.get("user_api_key"),
+                decoded_token=processor.decoded_token,
+                isNoneDoc=data.get("isNoneDoc"),
+                index=None,
+                should_save_conversation=data.get("save_conversation", True),
+            )
+            stream_result = self.process_response_stream(stream)
+
+            if len(stream_result) == 7:
+                (
+                    conversation_id,
+                    response,
+                    sources,
+                    tool_calls,
+                    thought,
+                    error,
+                    structured_info,
+                ) = stream_result
+            else:
+                conversation_id, response, sources, tool_calls, thought, error = (
+                    stream_result
+                )
+                structured_info = None
+
+            if error:
+                return make_response({"error": error}, 400)
+            result = {
+                "conversation_id": conversation_id,
+                "answer": response,
+                "sources": sources,
+                "tool_calls": tool_calls,
+                "thought": thought,
+            }
+
+            if structured_info:
+                result.update(structured_info)
+        except Exception as e:
+            logger.error(
+                f"/api/answer - error: {str(e)} - traceback: {traceback.format_exc()}",
+                extra={"error": str(e), "traceback": traceback.format_exc()},
+            )
+            return make_response({"error": str(e)}, 500)
+        return make_response(result, 200)

application/api/answer/routes/base.py

@@ -0,0 +1,263 @@
+import datetime
+import json
+import logging
+from typing import Any, Dict, Generator, List, Optional
+
+from flask import Response
+from flask_restx import Namespace
+
+from application.api.answer.services.conversation_service import ConversationService
+
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.llm.llm_creator import LLMCreator
+from application.utils import check_required_fields, get_gpt_model
+
+logger = logging.getLogger(__name__)
+
+
+answer_ns = Namespace("answer", description="Answer related operations", path="/")
+
+
+class BaseAnswerResource:
+    """Shared base class for answer endpoints"""
+
+    def __init__(self):
+        mongo = MongoDB.get_client()
+        db = mongo[settings.MONGO_DB_NAME]
+        self.user_logs_collection = db["user_logs"]
+        self.gpt_model = get_gpt_model()
+        self.conversation_service = ConversationService()
+
+    def validate_request(
+        self, data: Dict[str, Any], require_conversation_id: bool = False
+    ) -> Optional[Response]:
+        """Common request validation"""
+        required_fields = ["question"]
+        if require_conversation_id:
+            required_fields.append("conversation_id")
+        if missing_fields := check_required_fields(data, required_fields):
+            return missing_fields
+        return None
+
+    def complete_stream(
+        self,
+        question: str,
+        agent: Any,
+        retriever: Any,
+        conversation_id: Optional[str],
+        user_api_key: Optional[str],
+        decoded_token: Dict[str, Any],
+        isNoneDoc: bool = False,
+        index: Optional[int] = None,
+        should_save_conversation: bool = True,
+        attachment_ids: Optional[List[str]] = None,
+        agent_id: Optional[str] = None,
+        is_shared_usage: bool = False,
+        shared_token: Optional[str] = None,
+    ) -> Generator[str, None, None]:
+        """
+        Generator function that streams the complete conversation response.
+
+        Args:
+            question: The user's question
+            agent: The agent instance
+            retriever: The retriever instance
+            conversation_id: Existing conversation ID
+            user_api_key: User's API key if any
+            decoded_token: Decoded JWT token
+            isNoneDoc: Flag for document-less responses
+            index: Index of message to update
+            should_save_conversation: Whether to persist the conversation
+            attachment_ids: List of attachment IDs
+            agent_id: ID of agent used
+            is_shared_usage: Flag for shared agent usage
+            shared_token: Token for shared agent
+
+        Yields:
+            Server-sent event strings
+        """
+        try:
+            response_full, thought, source_log_docs, tool_calls = "", "", [], []
+            is_structured = False
+            schema_info = None
+            structured_chunks = []
+
+            for line in agent.gen(query=question, retriever=retriever):
+                if "answer" in line:
+                    response_full += str(line["answer"])
+                    if line.get("structured"):
+                        is_structured = True
+                        schema_info = line.get("schema")
+                        structured_chunks.append(line["answer"])
+                    else:
+                        data = json.dumps({"type": "answer", "answer": line["answer"]})
+                        yield f"data: {data}\n\n"
+                elif "sources" in line:
+                    truncated_sources = []
+                    source_log_docs = line["sources"]
+                    for source in line["sources"]:
+                        truncated_source = source.copy()
+                        if "text" in truncated_source:
+                            truncated_source["text"] = (
+                                truncated_source["text"][:100].strip() + "..."
+                            )
+                        truncated_sources.append(truncated_source)
+                    if truncated_sources:
+                        data = json.dumps(
+                            {"type": "source", "source": truncated_sources}
+                        )
+                        yield f"data: {data}\n\n"
+                elif "tool_calls" in line:
+                    tool_calls = line["tool_calls"]
+                elif "thought" in line:
+                    thought += line["thought"]
+                    data = json.dumps({"type": "thought", "thought": line["thought"]})
+                    yield f"data: {data}\n\n"
+                elif "type" in line:
+                    data = json.dumps(line)
+                    yield f"data: {data}\n\n"
+
+            if is_structured and structured_chunks:
+                structured_data = {
+                    "type": "structured_answer",
+                    "answer": response_full,
+                    "structured": True,
+                    "schema": schema_info,
+                }
+                data = json.dumps(structured_data)
+                yield f"data: {data}\n\n"
+
+            if isNoneDoc:
+                for doc in source_log_docs:
+                    doc["source"] = "None"
+            llm = LLMCreator.create_llm(
+                settings.LLM_PROVIDER,
+                api_key=settings.API_KEY,
+                user_api_key=user_api_key,
+                decoded_token=decoded_token,
+            )
+
+            if should_save_conversation:
+                conversation_id = self.conversation_service.save_conversation(
+                    conversation_id,
+                    question,
+                    response_full,
+                    thought,
+                    source_log_docs,
+                    tool_calls,
+                    llm,
+                    self.gpt_model,
+                    decoded_token,
+                    index=index,
+                    api_key=user_api_key,
+                    agent_id=agent_id,
+                    is_shared_usage=is_shared_usage,
+                    shared_token=shared_token,
+                    attachment_ids=attachment_ids,
+                )
+            else:
+                conversation_id = None
+            id_data = {"type": "id", "id": str(conversation_id)}
+            data = json.dumps(id_data)
+            yield f"data: {data}\n\n"
+
+            retriever_params = retriever.get_params()
+            log_data = {
+                "action": "stream_answer",
+                "level": "info",
+                "user": decoded_token.get("sub"),
+                "api_key": user_api_key,
+                "question": question,
+                "response": response_full,
+                "sources": source_log_docs,
+                "retriever_params": retriever_params,
+                "attachments": attachment_ids,
+                "timestamp": datetime.datetime.now(datetime.timezone.utc),
+            }
+            if is_structured:
+                log_data["structured_output"] = True
+                if schema_info:
+                    log_data["schema"] = schema_info
+  
+            # clean up text fields to be no longer than 10000 characters
+            for key, value in log_data.items():
+                if isinstance(value, str) and len(value) > 10000:
+                    log_data[key] = value[:10000]
+            
+            self.user_logs_collection.insert_one(log_data)
+
+            # End of stream
+
+            data = json.dumps({"type": "end"})
+            yield f"data: {data}\n\n"
+        except Exception as e:
+            logger.error(f"Error in stream: {str(e)}", exc_info=True)
+            data = json.dumps(
+                {
+                    "type": "error",
+                    "error": "Please try again later. We apologize for any inconvenience.",
+                }
+            )
+            yield f"data: {data}\n\n"
+            return
+
+    def process_response_stream(self, stream):
+        """Process the stream response for non-streaming endpoint"""
+        conversation_id = ""
+        response_full = ""
+        source_log_docs = []
+        tool_calls = []
+        thought = ""
+        stream_ended = False
+        is_structured = False
+        schema_info = None
+
+        for line in stream:
+            try:
+                event_data = line.replace("data: ", "").strip()
+                event = json.loads(event_data)
+
+                if event["type"] == "id":
+                    conversation_id = event["id"]
+                elif event["type"] == "answer":
+                    response_full += event["answer"]
+                elif event["type"] == "structured_answer":
+                    response_full = event["answer"]
+                    is_structured = True
+                    schema_info = event.get("schema")
+                elif event["type"] == "source":
+                    source_log_docs = event["source"]
+                elif event["type"] == "tool_calls":
+                    tool_calls = event["tool_calls"]
+                elif event["type"] == "thought":
+                    thought = event["thought"]
+                elif event["type"] == "error":
+                    logger.error(f"Error from stream: {event['error']}")
+                    return None, None, None, None, event["error"]
+                elif event["type"] == "end":
+                    stream_ended = True
+            except (json.JSONDecodeError, KeyError) as e:
+                logger.warning(f"Error parsing stream event: {e}, line: {line}")
+                continue
+        if not stream_ended:
+            logger.error("Stream ended unexpectedly without an 'end' event.")
+            return None, None, None, None, "Stream ended unexpectedly"
+
+        result = (
+            conversation_id,
+            response_full,
+            source_log_docs,
+            tool_calls,
+            thought,
+            None,
+        )
+
+        if is_structured:
+            result = result + ({"structured": True, "schema": schema_info},)
+
+        return result
+
+    def error_stream_generate(self, err_response):
+        data = json.dumps({"type": "error", "error": err_response})
+        yield f"data: {data}\n\n"

application/api/answer/routes/stream.py

@@ -0,0 +1,117 @@
+import logging
+import traceback
+
+from flask import request, Response
+from flask_restx import fields, Resource
+
+from application.api import api
+
+from application.api.answer.routes.base import answer_ns, BaseAnswerResource
+
+from application.api.answer.services.stream_processor import StreamProcessor
+
+logger = logging.getLogger(__name__)
+
+
+@answer_ns.route("/stream")
+class StreamResource(Resource, BaseAnswerResource):
+    def __init__(self, *args, **kwargs):
+        Resource.__init__(self, *args, **kwargs)
+        BaseAnswerResource.__init__(self)
+
+    stream_model = answer_ns.model(
+        "StreamModel",
+        {
+            "question": fields.String(
+                required=True, description="Question to be asked"
+            ),
+            "history": fields.List(
+                fields.String,
+                required=False,
+                description="Conversation history (only for new conversations)",
+            ),
+            "conversation_id": fields.String(
+                required=False,
+                description="Existing conversation ID (loads history)",
+            ),
+            "prompt_id": fields.String(
+                required=False, default="default", description="Prompt ID"
+            ),
+            "chunks": fields.Integer(
+                required=False, default=2, description="Number of chunks"
+            ),
+            "token_limit": fields.Integer(required=False, description="Token limit"),
+            "retriever": fields.String(required=False, description="Retriever type"),
+            "api_key": fields.String(required=False, description="API key"),
+            "active_docs": fields.String(
+                required=False, description="Active documents"
+            ),
+            "isNoneDoc": fields.Boolean(
+                required=False, description="Flag indicating if no document is used"
+            ),
+            "index": fields.Integer(
+                required=False, description="Index of the query to update"
+            ),
+            "save_conversation": fields.Boolean(
+                required=False,
+                default=True,
+                description="Whether to save the conversation",
+            ),
+            "attachments": fields.List(
+                fields.String, required=False, description="List of attachment IDs"
+            ),
+        },
+    )
+
+    @api.expect(stream_model)
+    @api.doc(description="Stream a response based on the question and retriever")
+    def post(self):
+        data = request.get_json()
+        if error := self.validate_request(data, "index" in data):
+            return error
+        decoded_token = getattr(request, "decoded_token", None)
+        processor = StreamProcessor(data, decoded_token)
+        try:
+            processor.initialize()
+            agent = processor.create_agent()
+            retriever = processor.create_retriever()
+
+            return Response(
+                self.complete_stream(
+                    question=data["question"],
+                    agent=agent,
+                    retriever=retriever,
+                    conversation_id=processor.conversation_id,
+                    user_api_key=processor.agent_config.get("user_api_key"),
+                    decoded_token=processor.decoded_token,
+                    isNoneDoc=data.get("isNoneDoc"),
+                    index=data.get("index"),
+                    should_save_conversation=data.get("save_conversation", True),
+                    attachment_ids=data.get("attachments", []),
+                    agent_id=data.get("agent_id"),
+                    is_shared_usage=processor.is_shared_usage,
+                    shared_token=processor.shared_token,
+                ),
+                mimetype="text/event-stream",
+            )
+        except ValueError as e:
+            message = "Malformed request body"
+            logger.error(
+                f"/stream - error: {message} - specific error: {str(e)} - traceback: {traceback.format_exc()}",
+                extra={"error": str(e), "traceback": traceback.format_exc()},
+            )
+            return Response(
+                self.error_stream_generate(message),
+                status=400,
+                mimetype="text/event-stream",
+            )
+        except Exception as e:
+            logger.error(
+                f"/stream - error: {str(e)} - traceback: {traceback.format_exc()}",
+                extra={"error": str(e), "traceback": traceback.format_exc()},
+            )
+            return Response(
+                self.error_stream_generate("Unknown error occurred"),
+                status=400,
+                mimetype="text/event-stream",
+            )

application/api/answer/services/conversation_service.py

@@ -0,0 +1,180 @@
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from application.core.mongo_db import MongoDB
+
+from application.core.settings import settings
+from bson import ObjectId
+
+
+logger = logging.getLogger(__name__)
+
+
+class ConversationService:
+    def __init__(self):
+        mongo = MongoDB.get_client()
+        db = mongo[settings.MONGO_DB_NAME]
+        self.conversations_collection = db["conversations"]
+        self.agents_collection = db["agents"]
+
+    def get_conversation(
+        self, conversation_id: str, user_id: str
+    ) -> Optional[Dict[str, Any]]:
+        """Retrieve a conversation with proper access control"""
+        if not conversation_id or not user_id:
+            return None
+        try:
+            conversation = self.conversations_collection.find_one(
+                {
+                    "_id": ObjectId(conversation_id),
+                    "$or": [{"user": user_id}, {"shared_with": user_id}],
+                }
+            )
+
+            if not conversation:
+                logger.warning(
+                    f"Conversation not found or unauthorized - ID: {conversation_id}, User: {user_id}"
+                )
+                return None
+            conversation["_id"] = str(conversation["_id"])
+            return conversation
+        except Exception as e:
+            logger.error(f"Error fetching conversation: {str(e)}", exc_info=True)
+            return None
+
+    def save_conversation(
+        self,
+        conversation_id: Optional[str],
+        question: str,
+        response: str,
+        thought: str,
+        sources: List[Dict[str, Any]],
+        tool_calls: List[Dict[str, Any]],
+        llm: Any,
+        gpt_model: str,
+        decoded_token: Dict[str, Any],
+        index: Optional[int] = None,
+        api_key: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        is_shared_usage: bool = False,
+        shared_token: Optional[str] = None,
+        attachment_ids: Optional[List[str]] = None,
+    ) -> str:
+        """Save or update a conversation in the database"""
+        user_id = decoded_token.get("sub")
+        if not user_id:
+            raise ValueError("User ID not found in token")
+        current_time = datetime.now(timezone.utc)
+        
+        # clean up in sources array such that we save max 1k characters for text part
+        for source in sources:
+            if "text" in source and isinstance(source["text"], str):
+                source["text"] = source["text"][:1000]
+
+        if conversation_id is not None and index is not None:
+            # Update existing conversation with new query
+
+            result = self.conversations_collection.update_one(
+                {
+                    "_id": ObjectId(conversation_id),
+                    "user": user_id,
+                    f"queries.{index}": {"$exists": True},
+                },
+                {
+                    "$set": {
+                        f"queries.{index}.prompt": question,
+                        f"queries.{index}.response": response,
+                        f"queries.{index}.thought": thought,
+                        f"queries.{index}.sources": sources,
+                        f"queries.{index}.tool_calls": tool_calls,
+                        f"queries.{index}.timestamp": current_time,
+                        f"queries.{index}.attachments": attachment_ids,
+                    }
+                },
+            )
+
+            if result.matched_count == 0:
+                raise ValueError("Conversation not found or unauthorized")
+            self.conversations_collection.update_one(
+                {
+                    "_id": ObjectId(conversation_id),
+                    "user": user_id,
+                    f"queries.{index}": {"$exists": True},
+                },
+                {"$push": {"queries": {"$each": [], "$slice": index + 1}}},
+            )
+            return conversation_id
+        elif conversation_id:
+            # Append new message to existing conversation
+
+            result = self.conversations_collection.update_one(
+                {"_id": ObjectId(conversation_id), "user": user_id},
+                {
+                    "$push": {
+                        "queries": {
+                            "prompt": question,
+                            "response": response,
+                            "thought": thought,
+                            "sources": sources,
+                            "tool_calls": tool_calls,
+                            "timestamp": current_time,
+                            "attachments": attachment_ids,
+                        }
+                    }
+                },
+            )
+
+            if result.matched_count == 0:
+                raise ValueError("Conversation not found or unauthorized")
+            return conversation_id
+        else:
+            # Create new conversation
+
+            messages_summary = [
+                {
+                    "role": "assistant",
+                    "content": "Summarise following conversation in no more than 3 "
+                    "words, respond ONLY with the summary, use the same "
+                    "language as the user query",
+                },
+                {
+                    "role": "user",
+                    "content": "Summarise following conversation in no more than 3 words, "
+                    "respond ONLY with the summary, use the same language as the "
+                    "user query \n\nUser: " + question + "\n\n" + "AI: " + response,
+                },
+            ]
+
+            completion = llm.gen(
+                model=gpt_model, messages=messages_summary, max_tokens=30
+            )
+
+            conversation_data = {
+                "user": user_id,
+                "date": current_time,
+                "name": completion,
+                "queries": [
+                    {
+                        "prompt": question,
+                        "response": response,
+                        "thought": thought,
+                        "sources": sources,
+                        "tool_calls": tool_calls,
+                        "timestamp": current_time,
+                        "attachments": attachment_ids,
+                    }
+                ],
+            }
+
+            if api_key:
+                if agent_id:
+                    conversation_data["agent_id"] = agent_id
+                    if is_shared_usage:
+                        conversation_data["is_shared_usage"] = is_shared_usage
+                        conversation_data["shared_token"] = shared_token
+                agent = self.agents_collection.find_one({"key": api_key})
+                if agent:
+                    conversation_data["api_key"] = agent["key"]
+            result = self.conversations_collection.insert_one(conversation_data)
+            return str(result.inserted_id)

application/api/answer/services/stream_processor.py

@@ -0,0 +1,353 @@
+import datetime
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from bson.dbref import DBRef
+
+from bson.objectid import ObjectId
+
+from application.agents.agent_creator import AgentCreator
+from application.api.answer.services.conversation_service import ConversationService
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.retriever.retriever_creator import RetrieverCreator
+from application.utils import get_gpt_model, limit_chat_history
+
+logger = logging.getLogger(__name__)
+
+
+def get_prompt(prompt_id: str, prompts_collection=None) -> str:
+    """
+    Get a prompt by preset name or MongoDB ID
+    """
+    current_dir = Path(__file__).resolve().parents[3]
+    prompts_dir = current_dir / "prompts"
+
+    preset_mapping = {
+        "default": "chat_combine_default.txt",
+        "creative": "chat_combine_creative.txt",
+        "strict": "chat_combine_strict.txt",
+        "reduce": "chat_reduce_prompt.txt",
+    }
+
+    if prompt_id in preset_mapping:
+        file_path = os.path.join(prompts_dir, preset_mapping[prompt_id])
+        try:
+            with open(file_path, "r") as f:
+                return f.read()
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Prompt file not found: {file_path}")
+    try:
+        if prompts_collection is None:
+            mongo = MongoDB.get_client()
+            db = mongo[settings.MONGO_DB_NAME]
+            prompts_collection = db["prompts"]
+        prompt_doc = prompts_collection.find_one({"_id": ObjectId(prompt_id)})
+        if not prompt_doc:
+            raise ValueError(f"Prompt with ID {prompt_id} not found")
+        return prompt_doc["content"]
+    except Exception as e:
+        raise ValueError(f"Invalid prompt ID: {prompt_id}") from e
+
+
+class StreamProcessor:
+    def __init__(
+        self, request_data: Dict[str, Any], decoded_token: Optional[Dict[str, Any]]
+    ):
+        mongo = MongoDB.get_client()
+        self.db = mongo[settings.MONGO_DB_NAME]
+        self.agents_collection = self.db["agents"]
+        self.attachments_collection = self.db["attachments"]
+        self.prompts_collection = self.db["prompts"]
+
+        self.data = request_data
+        self.decoded_token = decoded_token
+        self.initial_user_id = (
+            self.decoded_token.get("sub") if self.decoded_token is not None else None
+        )
+        self.conversation_id = self.data.get("conversation_id")
+        self.source = {}
+        self.all_sources = []
+        self.attachments = []
+        self.history = []
+        self.agent_config = {}
+        self.retriever_config = {}
+        self.is_shared_usage = False
+        self.shared_token = None
+        self.gpt_model = get_gpt_model()
+        self.conversation_service = ConversationService()
+
+    def initialize(self):
+        """Initialize all required components for processing"""
+        self._configure_agent()
+        self._configure_source()
+        self._configure_retriever()
+        self._configure_agent()
+        self._load_conversation_history()
+        self._process_attachments()
+
+    def _load_conversation_history(self):
+        """Load conversation history either from DB or request"""
+        if self.conversation_id and self.initial_user_id:
+            conversation = self.conversation_service.get_conversation(
+                self.conversation_id, self.initial_user_id
+            )
+            if not conversation:
+                raise ValueError("Conversation not found or unauthorized")
+            self.history = [
+                {"prompt": query["prompt"], "response": query["response"]}
+                for query in conversation.get("queries", [])
+            ]
+        else:
+            self.history = limit_chat_history(
+                json.loads(self.data.get("history", "[]")), gpt_model=self.gpt_model
+            )
+
+    def _process_attachments(self):
+        """Process any attachments in the request"""
+        attachment_ids = self.data.get("attachments", [])
+        self.attachments = self._get_attachments_content(
+            attachment_ids, self.initial_user_id
+        )
+
+    def _get_attachments_content(self, attachment_ids, user_id):
+        """
+        Retrieve content from attachment documents based on their IDs.
+        """
+        if not attachment_ids:
+            return []
+        attachments = []
+        for attachment_id in attachment_ids:
+            try:
+                attachment_doc = self.attachments_collection.find_one(
+                    {"_id": ObjectId(attachment_id), "user": user_id}
+                )
+
+                if attachment_doc:
+                    attachments.append(attachment_doc)
+            except Exception as e:
+                logger.error(
+                    f"Error retrieving attachment {attachment_id}: {e}", exc_info=True
+                )
+        return attachments
+
+    def _get_agent_key(self, agent_id: Optional[str], user_id: Optional[str]) -> tuple:
+        """Get API key for agent with access control"""
+        if not agent_id:
+            return None, False, None
+        try:
+            agent = self.agents_collection.find_one({"_id": ObjectId(agent_id)})
+            if agent is None:
+                raise Exception("Agent not found")
+            is_owner = agent.get("user") == user_id
+            is_shared_with_user = agent.get(
+                "shared_publicly", False
+            ) or user_id in agent.get("shared_with", [])
+
+            if not (is_owner or is_shared_with_user):
+                raise Exception("Unauthorized access to the agent")
+            if is_owner:
+                self.agents_collection.update_one(
+                    {"_id": ObjectId(agent_id)},
+                    {
+                        "$set": {
+                            "lastUsedAt": datetime.datetime.now(datetime.timezone.utc)
+                        }
+                    },
+                )
+            return str(agent["key"]), not is_owner, agent.get("shared_token")
+        except Exception as e:
+            logger.error(f"Error in get_agent_key: {str(e)}", exc_info=True)
+            raise
+
+    def _get_data_from_api_key(self, api_key: str) -> Dict[str, Any]:
+        data = self.agents_collection.find_one({"key": api_key})
+        if not data:
+            raise Exception("Invalid API Key, please generate a new key", 401)
+        source = data.get("source")
+        if isinstance(source, DBRef):
+            source_doc = self.db.dereference(source)
+            if source_doc:
+                data["source"] = str(source_doc["_id"])
+                data["retriever"] = source_doc.get("retriever", data.get("retriever"))
+                data["chunks"] = source_doc.get("chunks", data.get("chunks"))
+            else:
+                data["source"] = None
+        elif source == "default":
+            data["source"] = "default"
+        else:
+            data["source"] = None
+        # Handle multiple sources
+
+        sources = data.get("sources", [])
+        if sources and isinstance(sources, list):
+            sources_list = []
+            for i, source_ref in enumerate(sources):
+                if source_ref == "default":
+                    processed_source = {
+                        "id": "default",
+                        "retriever": "classic",
+                        "chunks": data.get("chunks", "2"),
+                    }
+                    sources_list.append(processed_source)
+                elif isinstance(source_ref, DBRef):
+                    source_doc = self.db.dereference(source_ref)
+                    if source_doc:
+                        processed_source = {
+                            "id": str(source_doc["_id"]),
+                            "retriever": source_doc.get("retriever", "classic"),
+                            "chunks": source_doc.get("chunks", data.get("chunks", "2")),
+                        }
+                        sources_list.append(processed_source)
+            data["sources"] = sources_list
+        else:
+            data["sources"] = []
+        return data
+
+    def _configure_source(self):
+        """Configure the source based on agent data"""
+        api_key = self.data.get("api_key") or self.agent_key
+
+        if api_key:
+            agent_data = self._get_data_from_api_key(api_key)
+
+            if agent_data.get("sources") and len(agent_data["sources"]) > 0:
+                source_ids = [
+                    source["id"] for source in agent_data["sources"] if source.get("id")
+                ]
+                if source_ids:
+                    self.source = {"active_docs": source_ids}
+                else:
+                    self.source = {}
+                self.all_sources = agent_data["sources"]
+            elif agent_data.get("source"):
+                self.source = {"active_docs": agent_data["source"]}
+                self.all_sources = [
+                    {
+                        "id": agent_data["source"],
+                        "retriever": agent_data.get("retriever", "classic"),
+                    }
+                ]
+            else:
+                self.source = {}
+                self.all_sources = []
+            return
+        if "active_docs" in self.data:
+            self.source = {"active_docs": self.data["active_docs"]}
+            return
+        self.source = {}
+        self.all_sources = []
+
+    def _configure_agent(self):
+        """Configure the agent based on request data"""
+        agent_id = self.data.get("agent_id")
+        self.agent_key, self.is_shared_usage, self.shared_token = self._get_agent_key(
+            agent_id, self.initial_user_id
+        )
+
+        api_key = self.data.get("api_key")
+        if api_key:
+            data_key = self._get_data_from_api_key(api_key)
+            self.agent_config.update(
+                {
+                    "prompt_id": data_key.get("prompt_id", "default"),
+                    "agent_type": data_key.get("agent_type", settings.AGENT_NAME),
+                    "user_api_key": api_key,
+                    "json_schema": data_key.get("json_schema"),
+                }
+            )
+            self.initial_user_id = data_key.get("user")
+            self.decoded_token = {"sub": data_key.get("user")}
+            if data_key.get("source"):
+                self.source = {"active_docs": data_key["source"]}
+            if data_key.get("retriever"):
+                self.retriever_config["retriever_name"] = data_key["retriever"]
+            if data_key.get("chunks") is not None:
+                try:
+                    self.retriever_config["chunks"] = int(data_key["chunks"])
+                except (ValueError, TypeError):
+                    logger.warning(
+                        f"Invalid chunks value: {data_key['chunks']}, using default value 2"
+                    )
+                    self.retriever_config["chunks"] = 2
+        elif self.agent_key:
+            data_key = self._get_data_from_api_key(self.agent_key)
+            self.agent_config.update(
+                {
+                    "prompt_id": data_key.get("prompt_id", "default"),
+                    "agent_type": data_key.get("agent_type", settings.AGENT_NAME),
+                    "user_api_key": self.agent_key,
+                    "json_schema": data_key.get("json_schema"),
+                }
+            )
+            self.decoded_token = (
+                self.decoded_token
+                if self.is_shared_usage
+                else {"sub": data_key.get("user")}
+            )
+            if data_key.get("source"):
+                self.source = {"active_docs": data_key["source"]}
+            if data_key.get("retriever"):
+                self.retriever_config["retriever_name"] = data_key["retriever"]
+            if data_key.get("chunks") is not None:
+                try:
+                    self.retriever_config["chunks"] = int(data_key["chunks"])
+                except (ValueError, TypeError):
+                    logger.warning(
+                        f"Invalid chunks value: {data_key['chunks']}, using default value 2"
+                    )
+                    self.retriever_config["chunks"] = 2
+        else:
+            self.agent_config.update(
+                {
+                    "prompt_id": self.data.get("prompt_id", "default"),
+                    "agent_type": settings.AGENT_NAME,
+                    "user_api_key": None,
+                    "json_schema": None,
+                }
+            )
+
+    def _configure_retriever(self):
+        """Configure the retriever based on request data"""
+        self.retriever_config = {
+            "retriever_name": self.data.get("retriever", "classic"),
+            "chunks": int(self.data.get("chunks", 2)),
+            "token_limit": self.data.get("token_limit", settings.DEFAULT_MAX_HISTORY),
+        }
+
+        api_key = self.data.get("api_key") or self.agent_key
+        if not api_key and "isNoneDoc" in self.data and self.data["isNoneDoc"]:
+            self.retriever_config["chunks"] = 0
+
+    def create_agent(self):
+        """Create and return the configured agent"""
+        return AgentCreator.create_agent(
+            self.agent_config["agent_type"],
+            endpoint="stream",
+            llm_name=settings.LLM_PROVIDER,
+            gpt_model=self.gpt_model,
+            api_key=settings.API_KEY,
+            user_api_key=self.agent_config["user_api_key"],
+            prompt=get_prompt(self.agent_config["prompt_id"], self.prompts_collection),
+            chat_history=self.history,
+            decoded_token=self.decoded_token,
+            attachments=self.attachments,
+            json_schema=self.agent_config.get("json_schema"),
+        )
+
+    def create_retriever(self):
+        """Create and return the configured retriever"""
+        return RetrieverCreator.create_retriever(
+            self.retriever_config["retriever_name"],
+            source=self.source,
+            chat_history=self.history,
+            prompt=get_prompt(self.agent_config["prompt_id"], self.prompts_collection),
+            chunks=self.retriever_config["chunks"],
+            token_limit=self.retriever_config["token_limit"],
+            gpt_model=self.gpt_model,
+            user_api_key=self.agent_config["user_api_key"],
+            decoded_token=self.decoded_token,
+        )

application/api/connector/routes.py

@@ -0,0 +1,695 @@
+import base64
+import datetime
+import json
+import uuid
+
+
+from bson.objectid import ObjectId
+from flask import (
+    Blueprint,
+    current_app,
+    jsonify,
+    make_response,
+    request
+)
+from flask_restx import fields, Namespace, Resource
+
+
+from application.api.user.tasks import (
+    ingest_connector_task,
+)
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.api import api
+
+
+from application.utils import (
+    check_required_fields
+)
+
+
+from application.parser.connectors.connector_creator import ConnectorCreator
+
+
+
+mongo = MongoDB.get_client()
+db = mongo[settings.MONGO_DB_NAME]
+sources_collection = db["sources"]
+sessions_collection = db["connector_sessions"]
+
+connector = Blueprint("connector", __name__)
+connectors_ns = Namespace("connectors", description="Connector operations", path="/")
+api.add_namespace(connectors_ns)
+
+
+
+@connectors_ns.route("/api/connectors/upload")
+class UploadConnector(Resource):
+    @api.expect(
+        api.model(
+            "ConnectorUploadModel",
+            {
+                "user": fields.String(required=True, description="User ID"),
+                "source": fields.String(
+                    required=True, description="Source type (google_drive, github, etc.)"
+                ),
+                "name": fields.String(required=True, description="Job name"),
+                "data": fields.String(required=True, description="Configuration data"),
+                "repo_url": fields.String(description="GitHub repository URL"),
+            },
+        )
+    )
+    @api.doc(
+        description="Uploads connector source for vectorization",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        data = request.form
+        required_fields = ["user", "source", "name", "data"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            config = json.loads(data["data"])
+            source_data = None
+            sync_frequency = config.get("sync_frequency", "never")
+
+            if data["source"] == "github":
+                source_data = config.get("repo_url")
+            elif data["source"] in ["crawler", "url"]:
+                source_data = config.get("url")
+            elif data["source"] == "reddit":
+                source_data = config
+            elif data["source"] in ConnectorCreator.get_supported_connectors():
+                session_token = config.get("session_token")
+                if not session_token:
+                    return make_response(jsonify({
+                        "success": False,
+                        "error": f"Missing session_token in {data['source']} configuration"
+                    }), 400)
+
+                file_ids = config.get("file_ids", [])
+                if isinstance(file_ids, str):
+                    file_ids = [id.strip() for id in file_ids.split(',') if id.strip()]
+                elif not isinstance(file_ids, list):
+                    file_ids = []
+
+                folder_ids = config.get("folder_ids", [])
+                if isinstance(folder_ids, str):
+                    folder_ids = [id.strip() for id in folder_ids.split(',') if id.strip()]
+                elif not isinstance(folder_ids, list):
+                    folder_ids = []
+
+                config["file_ids"] = file_ids
+                config["folder_ids"] = folder_ids
+
+                task = ingest_connector_task.delay(
+                    job_name=data["name"],
+                    user=decoded_token.get("sub"),
+                    source_type=data["source"],
+                    session_token=session_token,
+                    file_ids=file_ids,
+                    folder_ids=folder_ids,
+                    recursive=config.get("recursive", False),
+                    retriever=config.get("retriever", "classic"),
+                    sync_frequency=sync_frequency
+                )
+                return make_response(jsonify({"success": True, "task_id": task.id}), 200)
+            task = ingest_connector_task.delay(
+                source_data=source_data,
+                job_name=data["name"],
+                user=decoded_token.get("sub"),
+                loader=data["source"],
+                sync_frequency=sync_frequency
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error uploading connector source: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True, "task_id": task.id}), 200)
+
+
+@connectors_ns.route("/api/connectors/task_status")
+class ConnectorTaskStatus(Resource):
+    task_status_model = api.model(
+        "ConnectorTaskStatusModel",
+        {"task_id": fields.String(required=True, description="Task ID")},
+    )
+
+    @api.expect(task_status_model)
+    @api.doc(description="Get connector task status")
+    def get(self):
+        task_id = request.args.get("task_id")
+        if not task_id:
+            return make_response(
+                jsonify({"success": False, "message": "Task ID is required"}), 400
+            )
+        try:
+            from application.celery_init import celery
+
+            task = celery.AsyncResult(task_id)
+            task_meta = task.info
+            print(f"Task status: {task.status}")
+            if not isinstance(
+                task_meta, (dict, list, str, int, float, bool, type(None))
+            ):
+                task_meta = str(task_meta)
+        except Exception as err:
+            current_app.logger.error(f"Error getting task status: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"status": task.status, "result": task_meta}), 200)
+
+
+@connectors_ns.route("/api/connectors/sources")
+class ConnectorSources(Resource):
+    @api.doc(description="Get connector sources")
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        try:
+            sources = sources_collection.find({"user": user, "type": "connector:file"}).sort("date", -1)
+            connector_sources = []
+            for source in sources:
+                connector_sources.append({
+                    "id": str(source["_id"]),
+                    "name": source.get("name"),
+                    "date": source.get("date"),
+                    "type": source.get("type"),
+                    "source": source.get("source"),
+                    "tokens": source.get("tokens", ""),
+                    "retriever": source.get("retriever", "classic"),
+                    "syncFrequency": source.get("sync_frequency", ""),
+                })
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving connector sources: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify(connector_sources), 200)
+
+
+@connectors_ns.route("/api/connectors/delete")
+class DeleteConnectorSource(Resource):
+    @api.doc(
+        description="Delete a connector source",
+        params={"source_id": "The source ID to delete"},
+    )
+    def delete(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        source_id = request.args.get("source_id")
+        if not source_id:
+            return make_response(
+                jsonify({"success": False, "message": "source_id is required"}), 400
+            )
+        try:
+            result = sources_collection.delete_one(
+                {"_id": ObjectId(source_id), "user": decoded_token.get("sub")}
+            )
+            if result.deleted_count == 0:
+                return make_response(
+                    jsonify({"success": False, "message": "Source not found"}), 404
+                )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error deleting connector source: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@connectors_ns.route("/api/connectors/auth")
+class ConnectorAuth(Resource):
+    @api.doc(description="Get connector OAuth authorization URL", params={"provider": "Connector provider (e.g., google_drive)"})
+    def get(self):
+        try:
+            provider = request.args.get('provider') or request.args.get('source')
+            if not provider:
+                return make_response(jsonify({"success": False, "error": "Missing provider"}), 400)
+
+            if not ConnectorCreator.is_supported(provider):
+                return make_response(jsonify({"success": False, "error": f"Unsupported provider: {provider}"}), 400)
+
+            decoded_token = request.decoded_token
+            if not decoded_token:
+                return make_response(jsonify({"success": False, "error": "Unauthorized"}), 401)
+            user_id = decoded_token.get('sub')
+
+            now = datetime.datetime.now(datetime.timezone.utc)
+            result = sessions_collection.insert_one({
+                "provider": provider,
+                "user": user_id,
+                "status": "pending",
+                "created_at": now
+            })
+            state_dict = {
+                "provider": provider,
+                "object_id": str(result.inserted_id)
+            }
+            state = base64.urlsafe_b64encode(json.dumps(state_dict).encode()).decode()
+
+            auth = ConnectorCreator.create_auth(provider)
+            authorization_url = auth.get_authorization_url(state=state)
+            return make_response(jsonify({
+                "success": True,
+                "authorization_url": authorization_url,
+                "state": state
+            }), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error generating connector auth URL: {e}")
+            return make_response(jsonify({"success": False, "error": str(e)}), 500)
+
+
+@connectors_ns.route("/api/connectors/callback")
+class ConnectorsCallback(Resource):
+    @api.doc(description="Handle OAuth callback for external connectors")
+    def get(self):
+        """Handle OAuth callback for external connectors"""
+        try:
+            from application.parser.connectors.connector_creator import ConnectorCreator
+            from flask import request, redirect
+
+            authorization_code = request.args.get('code')
+            state = request.args.get('state')
+            error = request.args.get('error')
+
+            state_dict = json.loads(base64.urlsafe_b64decode(state.encode()).decode())
+            provider = state_dict["provider"]
+            state_object_id = state_dict["object_id"]
+
+            if error:
+                if error == "access_denied":
+                    return redirect(f"/api/connectors/callback-status?status=cancelled&message=Authentication+was+cancelled.+You+can+try+again+if+you'd+like+to+connect+your+account.&provider={provider}")
+                else:
+                    current_app.logger.warning(f"OAuth error in callback: {error}")
+                    return redirect(f"/api/connectors/callback-status?status=error&message=Authentication+failed.+Please+try+again+and+make+sure+to+grant+all+requested+permissions.&provider={provider}")
+
+            if not authorization_code:
+                return redirect(f"/api/connectors/callback-status?status=error&message=Authentication+failed.+Please+try+again+and+make+sure+to+grant+all+requested+permissions.&provider={provider}")
+
+            try:
+                auth = ConnectorCreator.create_auth(provider)
+                token_info = auth.exchange_code_for_tokens(authorization_code)
+
+                session_token = str(uuid.uuid4())
+
+                try:
+                    credentials = auth.create_credentials_from_token_info(token_info)
+                    service = auth.build_drive_service(credentials)
+                    user_info = service.about().get(fields="user").execute()
+                    user_email = user_info.get('user', {}).get('emailAddress', 'Connected User')
+                except Exception as e:
+                    current_app.logger.warning(f"Could not get user info: {e}")
+                    user_email = 'Connected User'
+
+                sanitized_token_info = {
+                    "access_token": token_info.get("access_token"),
+                    "refresh_token": token_info.get("refresh_token"),
+                    "token_uri": token_info.get("token_uri"),
+                    "expiry": token_info.get("expiry")
+                }
+
+                sessions_collection.find_one_and_update(
+                    {"_id": ObjectId(state_object_id), "provider": provider},
+                    {
+                        "$set": {
+                            "session_token": session_token,
+                            "token_info": sanitized_token_info,
+                            "user_email": user_email,
+                            "status": "authorized"
+                        }
+                    }
+                )
+
+                # Redirect to success page with session token and user email
+                return redirect(f"/api/connectors/callback-status?status=success&message=Authentication+successful&provider={provider}&session_token={session_token}&user_email={user_email}")
+
+            except Exception as e:
+                current_app.logger.error(f"Error exchanging code for tokens: {str(e)}", exc_info=True)
+                return redirect(f"/api/connectors/callback-status?status=error&message=Authentication+failed.+Please+try+again+and+make+sure+to+grant+all+requested+permissions.&provider={provider}")
+
+        except Exception as e:
+            current_app.logger.error(f"Error handling connector callback: {e}")
+            return redirect("/api/connectors/callback-status?status=error&message=Authentication+failed.+Please+try+again+and+make+sure+to+grant+all+requested+permissions.")
+
+
+@connectors_ns.route("/api/connectors/refresh")
+class ConnectorRefresh(Resource):
+    @api.expect(api.model("ConnectorRefreshModel", {"provider": fields.String(required=True), "refresh_token": fields.String(required=True)}))
+    @api.doc(description="Refresh connector access token")
+    def post(self):
+        try:
+            data = request.get_json()
+            provider = data.get('provider')
+            refresh_token = data.get('refresh_token')
+
+            if not provider or not refresh_token:
+                return make_response(jsonify({"success": False, "error": "provider and refresh_token are required"}), 400)
+
+            auth = ConnectorCreator.create_auth(provider)
+            token_info = auth.refresh_access_token(refresh_token)
+            return make_response(jsonify({"success": True, "token_info": token_info}), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error refreshing token for connector: {e}")
+            return make_response(jsonify({"success": False, "error": str(e)}), 500)
+
+
+@connectors_ns.route("/api/connectors/files")
+class ConnectorFiles(Resource):
+    @api.expect(api.model("ConnectorFilesModel", {
+        "provider": fields.String(required=True), 
+        "session_token": fields.String(required=True), 
+        "folder_id": fields.String(required=False), 
+        "limit": fields.Integer(required=False), 
+        "page_token": fields.String(required=False),
+        "search_query": fields.String(required=False)
+    }))
+    @api.doc(description="List files from a connector provider (supports pagination and search)")
+    def post(self):
+        try:
+            data = request.get_json()
+            provider = data.get('provider')
+            session_token = data.get('session_token')
+            folder_id = data.get('folder_id')
+            limit = data.get('limit', 10)
+            page_token = data.get('page_token')
+            search_query = data.get('search_query')
+            
+            if not provider or not session_token:
+                return make_response(jsonify({"success": False, "error": "provider and session_token are required"}), 400)
+
+            decoded_token = request.decoded_token
+            if not decoded_token:
+                return make_response(jsonify({"success": False, "error": "Unauthorized"}), 401)
+            user = decoded_token.get('sub')
+            session = sessions_collection.find_one({"session_token": session_token, "user": user})
+            if not session:
+                return make_response(jsonify({"success": False, "error": "Invalid or unauthorized session"}), 401)
+
+            loader = ConnectorCreator.create_connector(provider, session_token)
+            input_config = {
+                'limit': limit,
+                'list_only': True,
+                'session_token': session_token,
+                'folder_id': folder_id,
+                'page_token': page_token
+            }
+            if search_query:
+                input_config['search_query'] = search_query
+                
+            documents = loader.load_data(input_config)
+
+            files = []
+            for doc in documents[:limit]:
+                metadata = doc.extra_info
+                modified_time = metadata.get('modified_time')
+                if modified_time:
+                    date_part = modified_time.split('T')[0]
+                    time_part = modified_time.split('T')[1].split('.')[0].split('Z')[0]
+                    formatted_time = f"{date_part} {time_part}"
+                else:
+                    formatted_time = None
+
+                files.append({
+                    'id': doc.doc_id,
+                    'name': metadata.get('file_name', 'Unknown File'),
+                    'type': metadata.get('mime_type', 'unknown'),
+                    'size': metadata.get('size', None),
+                    'modifiedTime': formatted_time,
+                    'isFolder': metadata.get('is_folder', False)
+                })
+
+            next_token = getattr(loader, 'next_page_token', None)
+            has_more = bool(next_token)
+
+            return make_response(jsonify({
+                "success": True, 
+                "files": files, 
+                "total": len(files), 
+                "next_page_token": next_token, 
+                "has_more": has_more
+            }), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error loading connector files: {e}")
+            return make_response(jsonify({"success": False, "error": f"Failed to load files: {str(e)}"}), 500)
+
+
+@connectors_ns.route("/api/connectors/validate-session")
+class ConnectorValidateSession(Resource):
+    @api.expect(api.model("ConnectorValidateSessionModel", {"provider": fields.String(required=True), "session_token": fields.String(required=True)}))
+    @api.doc(description="Validate connector session token and return user info and access token")
+    def post(self):
+        try:
+            data = request.get_json()
+            provider = data.get('provider')
+            session_token = data.get('session_token')
+            if not provider or not session_token:
+                return make_response(jsonify({"success": False, "error": "provider and session_token are required"}), 400)
+
+            decoded_token = request.decoded_token
+            if not decoded_token:
+                return make_response(jsonify({"success": False, "error": "Unauthorized"}), 401)
+            user = decoded_token.get('sub')
+
+            session = sessions_collection.find_one({"session_token": session_token, "user": user})
+            if not session or "token_info" not in session:
+                return make_response(jsonify({"success": False, "error": "Invalid or expired session"}), 401)
+
+            token_info = session["token_info"]
+            auth = ConnectorCreator.create_auth(provider)
+            is_expired = auth.is_token_expired(token_info)
+
+            if is_expired and token_info.get('refresh_token'):
+                try:
+                    refreshed_token_info = auth.refresh_access_token(token_info.get('refresh_token'))
+                    sanitized_token_info = {
+                    "access_token": refreshed_token_info.get("access_token"),
+                    "refresh_token": refreshed_token_info.get("refresh_token"),
+                    "token_uri": refreshed_token_info.get("token_uri"),
+                    "expiry": refreshed_token_info.get("expiry")
+                }    
+                    sessions_collection.update_one(
+                        {"session_token": session_token},
+                        {"$set": {"token_info": sanitized_token_info}}
+                    )
+                    token_info = sanitized_token_info
+                    is_expired = False
+                except Exception as refresh_error:
+                    current_app.logger.error(f"Failed to refresh token: {refresh_error}")
+            
+            if is_expired:
+                return make_response(jsonify({
+                    "success": False,
+                    "expired": True,
+                    "error": "Session token has expired. Please reconnect."
+                }), 401)
+
+            return make_response(jsonify({
+                "success": True,
+                "expired": False,
+                "user_email": session.get('user_email', 'Connected User'),
+                "access_token": token_info.get('access_token')
+            }), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error validating connector session: {e}")
+            return make_response(jsonify({"success": False, "error": str(e)}), 500)
+
+
+@connectors_ns.route("/api/connectors/disconnect")
+class ConnectorDisconnect(Resource):
+    @api.expect(api.model("ConnectorDisconnectModel", {"provider": fields.String(required=True), "session_token": fields.String(required=False)}))
+    @api.doc(description="Disconnect a connector session")
+    def post(self):
+        try:
+            data = request.get_json()
+            provider = data.get('provider')
+            session_token = data.get('session_token')
+            if not provider:
+                return make_response(jsonify({"success": False, "error": "provider is required"}), 400)
+
+
+            if session_token:
+                sessions_collection.delete_one({"session_token": session_token})
+            
+            return make_response(jsonify({"success": True}), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error disconnecting connector session: {e}")
+            return make_response(jsonify({"success": False, "error": str(e)}), 500)
+
+
+@connectors_ns.route("/api/connectors/sync")
+class ConnectorSync(Resource):
+    @api.expect(
+        api.model(
+            "ConnectorSyncModel",
+            {
+                "source_id": fields.String(required=True, description="Source ID to sync"),
+                "session_token": fields.String(required=True, description="Authentication token")
+            },
+        )
+    )
+    @api.doc(description="Sync connector source to check for modifications")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+
+        try:
+            data = request.get_json()
+            source_id = data.get('source_id')
+            session_token = data.get('session_token')
+
+            if not all([source_id, session_token]):
+                return make_response(
+                    jsonify({
+                        "success": False,
+                        "error": "source_id and session_token are required"
+                    }), 
+                    400
+                )
+            source = sources_collection.find_one({"_id": ObjectId(source_id)})
+            if not source:
+                return make_response(
+                    jsonify({
+                        "success": False,
+                        "error": "Source not found"
+                    }), 
+                    404
+                )
+
+            if source.get('user') != decoded_token.get('sub'):
+                return make_response(
+                    jsonify({
+                        "success": False,
+                        "error": "Unauthorized access to source"
+                    }), 
+                    403
+                )
+
+            remote_data = {}
+            try:
+                if source.get('remote_data'):
+                    remote_data = json.loads(source.get('remote_data'))
+            except json.JSONDecodeError:
+                current_app.logger.error(f"Invalid remote_data format for source {source_id}")
+                remote_data = {}
+
+            source_type = remote_data.get('provider')
+            if not source_type:
+                return make_response(
+                    jsonify({
+                        "success": False,
+                        "error": "Source provider not found in remote_data"
+                    }), 
+                    400
+                )
+
+            # Extract configuration from remote_data
+            file_ids = remote_data.get('file_ids', [])
+            folder_ids = remote_data.get('folder_ids', [])
+            recursive = remote_data.get('recursive', True)
+
+            # Start the sync task
+            task = ingest_connector_task.delay(
+                job_name=source.get('name'),
+                user=decoded_token.get('sub'),
+                source_type=source_type,
+                session_token=session_token,
+                file_ids=file_ids,
+                folder_ids=folder_ids,
+                recursive=recursive,
+                retriever=source.get('retriever', 'classic'),
+                operation_mode="sync",
+                doc_id=source_id,
+                sync_frequency=source.get('sync_frequency', 'never')
+            )
+
+            return make_response(
+                jsonify({
+                    "success": True,
+                    "task_id": task.id
+                }), 
+                200
+            )
+
+        except Exception as err:
+            current_app.logger.error(
+                f"Error syncing connector source: {err}",
+                exc_info=True
+            )
+            return make_response(
+                jsonify({
+                    "success": False,
+                    "error": str(err)
+                }), 
+                400
+            )
+
+
+@connectors_ns.route("/api/connectors/callback-status")
+class ConnectorCallbackStatus(Resource):
+    @api.doc(description="Return HTML page with connector authentication status")
+    def get(self):
+        """Return HTML page with connector authentication status"""
+        try:
+            status = request.args.get('status', 'error')
+            message = request.args.get('message', '')
+            provider = request.args.get('provider', 'connector')
+            session_token = request.args.get('session_token', '')
+            user_email = request.args.get('user_email', '')
+            
+            html_content = f"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>{provider.replace('_', ' ').title()} Authentication</title>
+                <style>
+                    body {{ font-family: Arial, sans-serif; text-align: center; padding: 40px; }}
+                    .container {{ max-width: 600px; margin: 0 auto; }}
+                    .success {{ color: #4CAF50; }}
+                    .error {{ color: #F44336; }}
+                    .cancelled {{ color: #FF9800; }}
+                </style>
+                <script>
+                    window.onload = function() {{
+                        const status = "{status}";
+                        const sessionToken = "{session_token}";
+                        const userEmail = "{user_email}";
+
+                        if (status === "success" && window.opener) {{
+                            window.opener.postMessage({{
+                                type: '{provider}_auth_success',
+                                session_token: sessionToken,
+                                user_email: userEmail
+                            }}, '*');
+
+                            setTimeout(() => window.close(), 3000);
+                        }} else if (status === "cancelled" || status === "error") {{
+                            setTimeout(() => window.close(), 3000);
+                        }}
+                    }};
+                </script>
+            </head>
+            <body>
+                <div class="container">
+                    <h2>{provider.replace('_', ' ').title()} Authentication</h2>
+                    <div class="{status}">
+                        <p>{message}</p>
+                        {f'<p>Connected as: {user_email}</p>' if status == 'success' else ''}
+                    </div>
+                    <p><small>You can close this window. {f"Your {provider.replace('_', ' ').title()} is now connected and ready to use." if status == 'success' else "Feel free to close this window."}</small></p>
+                </div>
+            </body>
+            </html>
+            """
+            
+            return make_response(html_content, 200, {'Content-Type': 'text/html'})
+        except Exception as e:
+            current_app.logger.error(f"Error rendering callback status page: {e}")
+            return make_response("Authentication error occurred", 500, {'Content-Type': 'text/html'})
+
+

application/api/internal/routes.py

@@ -1,14 +1,18 @@
 import os
 import datetime
+import json
 from flask import Blueprint, request, send_from_directory
 from werkzeug.utils import secure_filename
 from bson.objectid import ObjectId
-
+import logging
 from application.core.mongo_db import MongoDB
 from application.core.settings import settings
+from application.storage.storage_creator import StorageCreator
 
+
+logger = logging.getLogger(__name__)
 mongo = MongoDB.get_client()
-db = mongo["docsgpt"]
+db = mongo[settings.MONGO_DB_NAME]
 conversations_collection = db["conversations"]
 sources_collection = db["sources"]
 
@@ -34,37 +38,52 @@ def upload_index_files():
     """Upload two files(index.faiss, index.pkl) to the user's folder."""
     if "user" not in request.form:
         return {"status": "no user"}
-    user = secure_filename(request.form["user"])
+    user = request.form["user"] 
     if "name" not in request.form:
         return {"status": "no name"}
-    job_name = secure_filename(request.form["name"])
-    tokens = secure_filename(request.form["tokens"])
-    retriever = secure_filename(request.form["retriever"])
-    id = secure_filename(request.form["id"])
-    type = secure_filename(request.form["type"])
+    job_name = request.form["name"]
+    tokens = request.form["tokens"]
+    retriever = request.form["retriever"]
+    id = request.form["id"]
+    type = request.form["type"]
     remote_data = request.form["remote_data"] if "remote_data" in request.form else None
-    sync_frequency = secure_filename(request.form["sync_frequency"]) if "sync_frequency" in request.form else None
+    sync_frequency = request.form["sync_frequency"] if "sync_frequency" in request.form else None
+    
+    file_path = request.form.get("file_path")
+    directory_structure = request.form.get("directory_structure")
+    
+    if directory_structure:
+        try:
+            directory_structure = json.loads(directory_structure)
+        except Exception:
+            logger.error("Error parsing directory_structure")
+            directory_structure = {}
+    else:
+        directory_structure = {}
 
-    save_dir = os.path.join(current_dir, "indexes", str(id))
+    storage = StorageCreator.get_storage()
+    index_base_path = f"indexes/{id}"
+    
     if settings.VECTOR_STORE == "faiss":
         if "file_faiss" not in request.files:
-            print("No file part")
+            logger.error("No file_faiss part")
             return {"status": "no file"}
         file_faiss = request.files["file_faiss"]
         if file_faiss.filename == "":
             return {"status": "no file name"}
         if "file_pkl" not in request.files:
-            print("No file part")
+            logger.error("No file_pkl part")
             return {"status": "no file"}
         file_pkl = request.files["file_pkl"]
         if file_pkl.filename == "":
             return {"status": "no file name"}
-        # saves index files
 
-        if not os.path.exists(save_dir):
-            os.makedirs(save_dir)
-        file_faiss.save(os.path.join(save_dir, "index.faiss"))
-        file_pkl.save(os.path.join(save_dir, "index.pkl"))
+        # Save index files to storage
+        faiss_storage_path = f"{index_base_path}/index.faiss"
+        pkl_storage_path = f"{index_base_path}/index.pkl"
+        storage.save_file(file_faiss, faiss_storage_path)
+        storage.save_file(file_pkl, pkl_storage_path)
+
 
     existing_entry = sources_collection.find_one({"_id": ObjectId(id)})
     if existing_entry:
@@ -82,6 +101,8 @@ def upload_index_files():
                     "retriever": retriever,
                     "remote_data": remote_data,
                     "sync_frequency": sync_frequency,
+                    "file_path": file_path,
+                    "directory_structure": directory_structure,
                 }
             },
         )
@@ -99,6 +120,8 @@ def upload_index_files():
                 "retriever": retriever,
                 "remote_data": remote_data,
                 "sync_frequency": sync_frequency,
+                "file_path": file_path,
+                "directory_structure": directory_structure,
             }
         )
     return {"status": "ok"}

application/api/user/tasks.py

@@ -1,12 +1,20 @@
 from datetime import timedelta
 
 from application.celery_init import celery
-from application.worker import ingest_worker, remote_worker, sync_worker
+from application.worker import (
+    agent_webhook_worker,
+    attachment_worker,
+    ingest_worker,
+    mcp_oauth,
+    mcp_oauth_status,
+    remote_worker,
+    sync_worker,
+)
 
 
 @celery.task(bind=True)
-def ingest(self, directory, formats, name_job, filename, user):
-    resp = ingest_worker(self, directory, formats, name_job, filename, user)
+def ingest(self, directory, formats, job_name, user, file_path, filename):
+    resp = ingest_worker(self, directory, formats, job_name, file_path, filename, user)
     return resp
 
 
@@ -16,12 +24,66 @@ def ingest_remote(self, source_data, job_name, user, loader):
     return resp
 
 
+@celery.task(bind=True)
+def reingest_source_task(self, source_id, user):
+    from application.worker import reingest_source_worker
+
+    resp = reingest_source_worker(self, source_id, user)
+    return resp
+
+
 @celery.task(bind=True)
 def schedule_syncs(self, frequency):
     resp = sync_worker(self, frequency)
     return resp
 
 
+@celery.task(bind=True)
+def store_attachment(self, file_info, user):
+    resp = attachment_worker(self, file_info, user)
+    return resp
+
+
+@celery.task(bind=True)
+def process_agent_webhook(self, agent_id, payload):
+    resp = agent_webhook_worker(self, agent_id, payload)
+    return resp
+
+
+@celery.task(bind=True)
+def ingest_connector_task(
+    self,
+    job_name,
+    user,
+    source_type,
+    session_token=None,
+    file_ids=None,
+    folder_ids=None,
+    recursive=True,
+    retriever="classic",
+    operation_mode="upload",
+    doc_id=None,
+    sync_frequency="never",
+):
+    from application.worker import ingest_connector
+
+    resp = ingest_connector(
+        self,
+        job_name,
+        user,
+        source_type,
+        session_token=session_token,
+        file_ids=file_ids,
+        folder_ids=folder_ids,
+        recursive=recursive,
+        retriever=retriever,
+        operation_mode=operation_mode,
+        doc_id=doc_id,
+        sync_frequency=sync_frequency,
+    )
+    return resp
+
+
 @celery.on_after_configure.connect
 def setup_periodic_tasks(sender, **kwargs):
     sender.add_periodic_task(
@@ -36,3 +98,15 @@ def setup_periodic_tasks(sender, **kwargs):
         timedelta(days=30),
         schedule_syncs.s("monthly"),
     )
+
+
+@celery.task(bind=True)
+def mcp_oauth_task(self, config, user):
+    resp = mcp_oauth(self, config, user)
+    return resp
+
+
+@celery.task(bind=True)
+def mcp_oauth_status_task(self, task_id):
+    resp = mcp_oauth_status(self, task_id)
+    return resp

application/app.py

@@ -12,25 +12,26 @@ from application.core.logging_config import setup_logging
 
 setup_logging()
 
-from application.api.answer.routes import answer  # noqa: E402
+from application.api import api  # noqa: E402
+from application.api.answer import answer  # noqa: E402
 from application.api.internal.routes import internal  # noqa: E402
 from application.api.user.routes import user  # noqa: E402
+from application.api.connector.routes import connector  # noqa: E402
 from application.celery_init import celery  # noqa: E402
 from application.core.settings import settings  # noqa: E402
-from application.extensions import api  # noqa: E402
 
 
 if platform.system() == "Windows":
     import pathlib
 
     pathlib.PosixPath = pathlib.WindowsPath
-
 dotenv.load_dotenv()
 
 app = Flask(__name__)
 app.register_blueprint(user)
 app.register_blueprint(answer)
 app.register_blueprint(internal)
+app.register_blueprint(connector)
 app.config.update(
     UPLOAD_FOLDER="inputs",
     CELERY_BROKER_URL=settings.CELERY_BROKER_URL,
@@ -52,7 +53,6 @@ if settings.AUTH_TYPE in ("simple_jwt", "session_jwt") and not settings.JWT_SECR
         settings.JWT_SECRET_KEY = new_key
     except Exception as e:
         raise RuntimeError(f"Failed to setup JWT_SECRET_KEY: {e}")
-
 SIMPLE_JWT_TOKEN = None
 if settings.AUTH_TYPE == "simple_jwt":
     payload = {"sub": "local"}
@@ -92,7 +92,6 @@ def generate_token():
 def authenticate_request():
     if request.method == "OPTIONS":
         return "", 200
-
     decoded_token = handle_auth(request)
     if not decoded_token:
         request.decoded_token = None

application/cache.py

@@ -61,14 +61,14 @@ def gen_cache(func):
                 if cached_response:
                     return cached_response.decode("utf-8")
             except Exception as e:
-                logger.error(f"Error getting cached response: {e}")
+                logger.error(f"Error getting cached response: {e}", exc_info=True)
 
         result = func(self, model, messages, stream, tools, *args, **kwargs)
         if redis_client and isinstance(result, str):
             try:
                 redis_client.set(cache_key, result, ex=1800)
             except Exception as e:
-                logger.error(f"Error setting cache: {e}")
+                logger.error(f"Error setting cache: {e}", exc_info=True)
 
         return result
 
@@ -100,7 +100,7 @@ def stream_cache(func):
                         time.sleep(0.03)  # Simulate streaming delay
                     return
             except Exception as e:
-                logger.error(f"Error getting cached stream: {e}")
+                logger.error(f"Error getting cached stream: {e}", exc_info=True)
 
         stream_cache_data = []
         for chunk in func(self, model, messages, stream, tools, *args, **kwargs):
@@ -112,6 +112,6 @@ def stream_cache(func):
                 redis_client.set(cache_key, json.dumps(stream_cache_data), ex=1800)
                 logger.info(f"Stream cache saved for key: {cache_key}")
             except Exception as e:
-                logger.error(f"Error setting stream cache: {e}")
+                logger.error(f"Error setting stream cache: {e}", exc_info=True)
 
     return wrapper

application/core/settings.py

@@ -10,30 +10,41 @@ current_dir = os.path.dirname(
 
 
 class Settings(BaseSettings):
-    AUTH_TYPE: Optional[str] = None
-    LLM_NAME: str = "docsgpt"
-    MODEL_NAME: Optional[str] = (
-        None  # if LLM_NAME is openai, MODEL_NAME can be gpt-4 or gpt-3.5-turbo
+    AUTH_TYPE: Optional[str] = None  # simple_jwt, session_jwt, or None
+    LLM_PROVIDER: str = "docsgpt"
+    LLM_NAME: Optional[str] = (
+        None  # if LLM_PROVIDER is openai, LLM_NAME can be gpt-4 or gpt-3.5-turbo
     )
     EMBEDDINGS_NAME: str = "huggingface_sentence-transformers/all-mpnet-base-v2"
     CELERY_BROKER_URL: str = "redis://localhost:6379/0"
     CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
     MONGO_URI: str = "mongodb://localhost:27017/docsgpt"
-    MODEL_PATH: str = os.path.join(current_dir, "models/docsgpt-7b-f16.gguf")
+    MONGO_DB_NAME: str = "docsgpt"
+    LLM_PATH: str = os.path.join(current_dir, "models/docsgpt-7b-f16.gguf")
     DEFAULT_MAX_HISTORY: int = 150
-    MODEL_TOKEN_LIMITS: dict = {
+    LLM_TOKEN_LIMITS: dict = {
         "gpt-4o-mini": 128000,
         "gpt-3.5-turbo": 4096,
         "claude-2": 1e5,
-        "gemini-2.0-flash-exp": 1e6,
+        "gemini-2.5-flash": 1e6,
     }
     UPLOAD_FOLDER: str = "inputs"
     PARSE_PDF_AS_IMAGE: bool = False
+    PARSE_IMAGE_REMOTE: bool = False
     VECTOR_STORE: str = (
         "faiss"  #  "faiss" or "elasticsearch" or "qdrant" or "milvus" or "lancedb"
     )
-    RETRIEVERS_ENABLED: list = ["classic_rag", "duckduck_search"]  # also brave_search
+    RETRIEVERS_ENABLED: list = ["classic_rag"]
     AGENT_NAME: str = "classic"
+    FALLBACK_LLM_PROVIDER: Optional[str] = None  # provider for fallback llm
+    FALLBACK_LLM_NAME: Optional[str] = None  # model name for fallback llm
+    FALLBACK_LLM_API_KEY: Optional[str] = None  # api key for fallback llm
+
+    # Google Drive integration
+    GOOGLE_CLIENT_ID: Optional[str] = None # Replace with your actual Google OAuth client ID
+    GOOGLE_CLIENT_SECRET: Optional[str] = None# Replace with your actual Google OAuth client secret
+    CONNECTOR_REDIRECT_BASE_URI: Optional[str] = "http://127.0.0.1:7091/api/connectors/callback" ##add redirect url as it is to your provider's console(gcp)
+
 
     # LLM Cache
     CACHE_REDIS_URL: str = "redis://localhost:6379/2"
@@ -85,6 +96,8 @@ class Settings(BaseSettings):
     QDRANT_PATH: Optional[str] = None
     QDRANT_DISTANCE_FUNC: str = "Cosine"
 
+    # PGVector vectorstore config
+    PGVECTOR_CONNECTION_STRING: Optional[str] = None
     # Milvus vectorstore config
     MILVUS_COLLECTION_NAME: Optional[str] = "docsgpt"
     MILVUS_URI: Optional[str] = "./milvus_local.db"  # milvus lite version as default
@@ -95,12 +108,16 @@ class Settings(BaseSettings):
     LANCEDB_TABLE_NAME: Optional[str] = (
         "docsgpts"  # Name of the table to use for storing vectors
     )
-    BRAVE_SEARCH_API_KEY: Optional[str] = None
 
     FLASK_DEBUG_MODE: bool = False
+    STORAGE_TYPE: str = "local"  # local or s3
+    URL_STRATEGY: str = "backend"  # backend or s3
 
     JWT_SECRET_KEY: str = ""
 
+    # Encryption settings
+    ENCRYPTION_SECRET_KEY: str = "default-docsgpt-encryption-key"
+
 
 path = Path(__file__).parent.parent.absolute()
 settings = Settings(_env_file=path.joinpath(".env"), _env_file_encoding="utf-8")

application/extensions.py

@@ -1,7 +0,0 @@
-from flask_restx import Api
-
-api = Api(
-    version="1.0",
-    title="DocsGPT API",
-    description="API for DocsGPT",
-)

application/llm/base.py

@@ -1,53 +1,117 @@
+import logging
 from abc import ABC, abstractmethod
 
 from application.cache import gen_cache, stream_cache
+
+from application.core.settings import settings
 from application.usage import gen_token_usage, stream_token_usage
 
+logger = logging.getLogger(__name__)
+
 
 class BaseLLM(ABC):
-    def __init__(self, decoded_token=None):
+    def __init__(
+        self,
+        decoded_token=None,
+    ):
         self.decoded_token = decoded_token
         self.token_usage = {"prompt_tokens": 0, "generated_tokens": 0}
+        self.fallback_provider = settings.FALLBACK_LLM_PROVIDER
+        self.fallback_model_name = settings.FALLBACK_LLM_NAME
+        self.fallback_llm_api_key = settings.FALLBACK_LLM_API_KEY
+        self._fallback_llm = None
 
-    def _apply_decorator(self, method, decorators, *args, **kwargs):
-        for decorator in decorators:
-            method = decorator(method)
-        return method(self, *args, **kwargs)
+    @property
+    def fallback_llm(self):
+        """Lazy-loaded fallback LLM instance."""
+        if (
+            self._fallback_llm is None
+            and self.fallback_provider
+            and self.fallback_model_name
+        ):
+            try:
+                from application.llm.llm_creator import LLMCreator
+
+                self._fallback_llm = LLMCreator.create_llm(
+                    self.fallback_provider,
+                    self.fallback_llm_api_key,
+                    None,
+                    self.decoded_token,
+                )
+            except Exception as e:
+                logger.error(
+                    f"Failed to initialize fallback LLM: {str(e)}", exc_info=True
+                )
+        return self._fallback_llm
+
+    def _execute_with_fallback(
+        self, method_name: str, decorators: list, *args, **kwargs
+    ):
+        """
+        Unified method execution with fallback support.
+
+        Args:
+            method_name: Name of the raw method ('_raw_gen' or '_raw_gen_stream')
+            decorators: List of decorators to apply
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+        """
+
+        def decorated_method():
+            method = getattr(self, method_name)
+            for decorator in decorators:
+                method = decorator(method)
+            return method(self, *args, **kwargs)
+
+        try:
+            return decorated_method()
+        except Exception as e:
+            if not self.fallback_llm:
+                logger.error(f"Primary LLM failed and no fallback available: {str(e)}")
+                raise
+            logger.warning(
+                f"Falling back to {self.fallback_provider}/{self.fallback_model_name}. Error: {str(e)}"
+            )
+
+            fallback_method = getattr(
+                self.fallback_llm, method_name.replace("_raw_", "")
+            )
+            return fallback_method(*args, **kwargs)
+
+    def gen(self, model, messages, stream=False, tools=None, *args, **kwargs):
+        decorators = [gen_token_usage, gen_cache]
+        return self._execute_with_fallback(
+            "_raw_gen",
+            decorators,
+            model=model,
+            messages=messages,
+            stream=stream,
+            tools=tools,
+            *args,
+            **kwargs,
+        )
+
+    def gen_stream(self, model, messages, stream=True, tools=None, *args, **kwargs):
+        decorators = [stream_cache, stream_token_usage]
+        return self._execute_with_fallback(
+            "_raw_gen_stream",
+            decorators,
+            model=model,
+            messages=messages,
+            stream=stream,
+            tools=tools,
+            *args,
+            **kwargs,
+        )
 
     @abstractmethod
     def _raw_gen(self, model, messages, stream, tools, *args, **kwargs):
         pass
 
-    def gen(self, model, messages, stream=False, tools=None, *args, **kwargs):
-        decorators = [gen_token_usage, gen_cache]
-        return self._apply_decorator(
-            self._raw_gen,
-            decorators=decorators,
-            model=model,
-            messages=messages,
-            stream=stream,
-            tools=tools,
-            *args,
-            **kwargs
-        )
-
     @abstractmethod
     def _raw_gen_stream(self, model, messages, stream, *args, **kwargs):
         pass
 
-    def gen_stream(self, model, messages, stream=True, tools=None, *args, **kwargs):
-        decorators = [stream_cache, stream_token_usage]
-        return self._apply_decorator(
-            self._raw_gen_stream,
-            decorators=decorators,
-            model=model,
-            messages=messages,
-            stream=stream,
-            tools=tools,
-            *args,
-            **kwargs
-        )
-
     def supports_tools(self):
         return hasattr(self, "_supports_tools") and callable(
             getattr(self, "_supports_tools")
@@ -55,3 +119,26 @@ class BaseLLM(ABC):
 
     def _supports_tools(self):
         raise NotImplementedError("Subclass must implement _supports_tools method")
+
+    def supports_structured_output(self):
+        """Check if the LLM supports structured output/JSON schema enforcement"""
+        return hasattr(self, "_supports_structured_output") and callable(
+            getattr(self, "_supports_structured_output")
+        )
+
+    def _supports_structured_output(self):
+        return False
+
+    def prepare_structured_output_format(self, json_schema):
+        """Prepare structured output format specific to the LLM provider"""
+        _ = json_schema
+        return None
+
+    def get_supported_attachment_types(self):
+        """
+        Return a list of MIME types supported by this LLM for file uploads.
+
+        Returns:
+            list: List of supported MIME types
+        """
+        return []

application/llm/google_ai.py

@@ -1,7 +1,13 @@
+import json
+import logging
+
 from google import genai
 from google.genai import types
 
+from application.core.settings import settings
+
 from application.llm.base import BaseLLM
+from application.storage.storage_creator import StorageCreator
 
 
 class GoogleLLM(BaseLLM):
@@ -9,8 +15,135 @@ class GoogleLLM(BaseLLM):
         super().__init__(*args, **kwargs)
         self.api_key = api_key
         self.user_api_key = user_api_key
+        self.client = genai.Client(api_key=self.api_key)
+        self.storage = StorageCreator.get_storage()
+
+    def get_supported_attachment_types(self):
+        """
+        Return a list of MIME types supported by Google Gemini for file uploads.
+
+        Returns:
+            list: List of supported MIME types
+        """
+        return [
+            "application/pdf",
+            "image/png",
+            "image/jpeg",
+            "image/jpg",
+            "image/webp",
+            "image/gif",
+        ]
+
+    def prepare_messages_with_attachments(self, messages, attachments=None):
+        """
+        Process attachments using Google AI's file API for more efficient handling.
+
+        Args:
+            messages (list): List of message dictionaries.
+            attachments (list): List of attachment dictionaries with content and metadata.
+
+        Returns:
+            list: Messages formatted with file references for Google AI API.
+        """
+        if not attachments:
+            return messages
+
+        prepared_messages = messages.copy()
+
+        # Find the user message to attach files to the last one
+        user_message_index = None
+        for i in range(len(prepared_messages) - 1, -1, -1):
+            if prepared_messages[i].get("role") == "user":
+                user_message_index = i
+                break
+
+        if user_message_index is None:
+            user_message = {"role": "user", "content": []}
+            prepared_messages.append(user_message)
+            user_message_index = len(prepared_messages) - 1
+
+        if isinstance(prepared_messages[user_message_index].get("content"), str):
+            text_content = prepared_messages[user_message_index]["content"]
+            prepared_messages[user_message_index]["content"] = [
+                {"type": "text", "text": text_content}
+            ]
+        elif not isinstance(prepared_messages[user_message_index].get("content"), list):
+            prepared_messages[user_message_index]["content"] = []
+
+        files = []
+        for attachment in attachments:
+            mime_type = attachment.get("mime_type")
+
+            if mime_type in self.get_supported_attachment_types():
+                try:
+                    file_uri = self._upload_file_to_google(attachment)
+                    logging.info(
+                        f"GoogleLLM: Successfully uploaded file, got URI: {file_uri}"
+                    )
+                    files.append({"file_uri": file_uri, "mime_type": mime_type})
+                except Exception as e:
+                    logging.error(
+                        f"GoogleLLM: Error uploading file: {e}", exc_info=True
+                    )
+                    if "content" in attachment:
+                        prepared_messages[user_message_index]["content"].append(
+                            {
+                                "type": "text",
+                                "text": f"[File could not be processed: {attachment.get('path', 'unknown')}]",
+                            }
+                        )
+
+        if files:
+            logging.info(f"GoogleLLM: Adding {len(files)} files to message")
+            prepared_messages[user_message_index]["content"].append({"files": files})
+
+        return prepared_messages
+
+    def _upload_file_to_google(self, attachment):
+        """
+        Upload a file to Google AI and return the file URI.
+
+        Args:
+            attachment (dict): Attachment dictionary with path and metadata.
+
+        Returns:
+            str: Google AI file URI for the uploaded file.
+        """
+        if "google_file_uri" in attachment:
+            return attachment["google_file_uri"]
+
+        file_path = attachment.get("path")
+        if not file_path:
+            raise ValueError("No file path provided in attachment")
+
+        if not self.storage.file_exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        try:
+            file_uri = self.storage.process_file(
+                file_path,
+                lambda local_path, **kwargs: self.client.files.upload(
+                    file=local_path
+                ).uri,
+            )
+
+            from application.core.mongo_db import MongoDB
+
+            mongo = MongoDB.get_client()
+            db = mongo[settings.MONGO_DB_NAME]
+            attachments_collection = db["attachments"]
+            if "_id" in attachment:
+                attachments_collection.update_one(
+                    {"_id": attachment["_id"]}, {"$set": {"google_file_uri": file_uri}}
+                )
+
+            return file_uri
+        except Exception as e:
+            logging.error(f"Error uploading file to Google AI: {e}", exc_info=True)
+            raise
 
     def _clean_messages_google(self, messages):
+        """Convert OpenAI format messages to Google AI format."""
         cleaned_messages = []
         for message in messages:
             role = message.get("role")
@@ -18,6 +151,8 @@ class GoogleLLM(BaseLLM):
 
             if role == "assistant":
                 role = "model"
+            elif role == "tool":
+                role = "model"
 
             parts = []
             if role and content is not None:
@@ -26,7 +161,7 @@ class GoogleLLM(BaseLLM):
                 elif isinstance(content, list):
                     for item in content:
                         if "text" in item:
-                            parts.append(types.Part.from_text(item["text"]))
+                            parts.append(types.Part.from_text(text=item["text"]))
                         elif "function_call" in item:
                             parts.append(
                                 types.Part.from_function_call(
@@ -41,6 +176,14 @@ class GoogleLLM(BaseLLM):
                                     response=item["function_response"]["response"],
                                 )
                             )
+                        elif "files" in item:
+                            for file_data in item["files"]:
+                                parts.append(
+                                    types.Part.from_uri(
+                                        file_uri=file_data["file_uri"],
+                                        mime_type=file_data["mime_type"],
+                                    )
+                                )
                         else:
                             raise ValueError(
                                 f"Unexpected content dictionary format:{item}"
@@ -48,11 +191,63 @@ class GoogleLLM(BaseLLM):
                 else:
                     raise ValueError(f"Unexpected content type: {type(content)}")
 
-                cleaned_messages.append(types.Content(role=role, parts=parts))
+                if parts:
+                    cleaned_messages.append(types.Content(role=role, parts=parts))
 
         return cleaned_messages
 
+    def _clean_schema(self, schema_obj):
+        """
+        Recursively remove unsupported fields from schema objects
+        and validate required properties.
+        """
+        if not isinstance(schema_obj, dict):
+            return schema_obj
+        allowed_fields = {
+            "type",
+            "description",
+            "items",
+            "properties",
+            "required",
+            "enum",
+            "pattern",
+            "minimum",
+            "maximum",
+            "nullable",
+            "default",
+        }
+
+        cleaned = {}
+        for key, value in schema_obj.items():
+            if key not in allowed_fields:
+                continue
+            elif key == "type" and isinstance(value, str):
+                cleaned[key] = value.upper()
+            elif isinstance(value, dict):
+                cleaned[key] = self._clean_schema(value)
+            elif isinstance(value, list):
+                cleaned[key] = [self._clean_schema(item) for item in value]
+            else:
+                cleaned[key] = value
+
+        # Validate that required properties actually exist in properties
+        if "required" in cleaned and "properties" in cleaned:
+            valid_required = []
+            properties_keys = set(cleaned["properties"].keys())
+            for required_prop in cleaned["required"]:
+                if required_prop in properties_keys:
+                    valid_required.append(required_prop)
+            if valid_required:
+                cleaned["required"] = valid_required
+            else:
+                cleaned.pop("required", None)
+        elif "required" in cleaned and "properties" not in cleaned:
+            cleaned.pop("required", None)
+
+        return cleaned
+
     def _clean_tools_format(self, tools_list):
+        """Convert OpenAI format tools to Google AI format."""
         genai_tools = []
         for tool_data in tools_list:
             if tool_data["type"] == "function":
@@ -61,18 +256,16 @@ class GoogleLLM(BaseLLM):
                 properties = parameters.get("properties", {})
 
                 if properties:
+                    cleaned_properties = {}
+                    for k, v in properties.items():
+                        cleaned_properties[k] = self._clean_schema(v)
+
                     genai_function = dict(
                         name=function["name"],
                         description=function["description"],
                         parameters={
                             "type": "OBJECT",
-                            "properties": {
-                                k: {
-                                    **v,
-                                    "type": v["type"].upper() if v["type"] else None,
-                                }
-                                for k, v in properties.items()
-                            },
+                            "properties": cleaned_properties,
                             "required": (
                                 parameters["required"]
                                 if "required" in parameters
@@ -99,8 +292,10 @@ class GoogleLLM(BaseLLM):
         stream=False,
         tools=None,
         formatting="openai",
+        response_schema=None,
         **kwargs,
     ):
+        """Generate content using Google AI API without streaming."""
         client = genai.Client(api_key=self.api_key)
         if formatting == "openai":
             messages = self._clean_messages_google(messages)
@@ -112,16 +307,21 @@ class GoogleLLM(BaseLLM):
         if tools:
             cleaned_tools = self._clean_tools_format(tools)
             config.tools = cleaned_tools
-            response = client.models.generate_content(
-                model=model,
-                contents=messages,
-                config=config,
-            )
+
+        # Add response schema for structured output if provided
+        if response_schema:
+            config.response_schema = response_schema
+            config.response_mime_type = "application/json"
+
+        response = client.models.generate_content(
+            model=model,
+            contents=messages,
+            config=config,
+        )
+
+        if tools:
             return response
         else:
-            response = client.models.generate_content(
-                model=model, contents=messages, config=config
-            )
             return response.text
 
     def _raw_gen_stream(
@@ -132,8 +332,10 @@ class GoogleLLM(BaseLLM):
         stream=True,
         tools=None,
         formatting="openai",
+        response_schema=None,
         **kwargs,
     ):
+        """Generate content using Google AI API with streaming."""
         client = genai.Client(api_key=self.api_key)
         if formatting == "openai":
             messages = self._clean_messages_google(messages)
@@ -146,11 +348,31 @@ class GoogleLLM(BaseLLM):
             cleaned_tools = self._clean_tools_format(tools)
             config.tools = cleaned_tools
 
+        # Add response schema for structured output if provided
+        if response_schema:
+            config.response_schema = response_schema
+            config.response_mime_type = "application/json"
+
+        # Check if we have both tools and file attachments
+        has_attachments = False
+        for message in messages:
+            for part in message.parts:
+                if hasattr(part, "file_data") and part.file_data is not None:
+                    has_attachments = True
+                    break
+            if has_attachments:
+                break
+
+        logging.info(
+            f"GoogleLLM: Starting stream generation. Model: {model}, Messages: {json.dumps(messages, default=str)}, Has attachments: {has_attachments}"
+        )
+
         response = client.models.generate_content_stream(
             model=model,
             contents=messages,
             config=config,
         )
+
         for chunk in response:
             if hasattr(chunk, "candidates") and chunk.candidates:
                 for candidate in chunk.candidates:
@@ -164,4 +386,79 @@ class GoogleLLM(BaseLLM):
                 yield chunk.text
 
     def _supports_tools(self):
+        """Return whether this LLM supports function calling."""
         return True
+
+    def _supports_structured_output(self):
+        """Return whether this LLM supports structured JSON output."""
+        return True
+
+    def prepare_structured_output_format(self, json_schema):
+        """Convert JSON schema to Google AI structured output format."""
+        if not json_schema:
+            return None
+
+        type_map = {
+            "object": "OBJECT",
+            "array": "ARRAY",
+            "string": "STRING",
+            "integer": "INTEGER",
+            "number": "NUMBER",
+            "boolean": "BOOLEAN",
+        }
+
+        def convert(schema):
+            if not isinstance(schema, dict):
+                return schema
+
+            result = {}
+            schema_type = schema.get("type")
+            if schema_type:
+                result["type"] = type_map.get(schema_type.lower(), schema_type.upper())
+
+            for key in [
+                "description",
+                "nullable",
+                "enum",
+                "minItems",
+                "maxItems",
+                "required",
+                "propertyOrdering",
+            ]:
+                if key in schema:
+                    result[key] = schema[key]
+
+            if "format" in schema:
+                format_value = schema["format"]
+                if schema_type == "string":
+                    if format_value == "date":
+                        result["format"] = "date-time"
+                    elif format_value in ["enum", "date-time"]:
+                        result["format"] = format_value
+                else:
+                    result["format"] = format_value
+
+            if "properties" in schema:
+                result["properties"] = {
+                    k: convert(v) for k, v in schema["properties"].items()
+                }
+                if "propertyOrdering" not in result and result.get("type") == "OBJECT":
+                    result["propertyOrdering"] = list(result["properties"].keys())
+
+            if "items" in schema:
+                result["items"] = convert(schema["items"])
+
+            for field in ["anyOf", "oneOf", "allOf"]:
+                if field in schema:
+                    result[field] = [convert(s) for s in schema[field]]
+
+            return result
+
+        try:
+            return convert(json_schema)
+        except Exception as e:
+            logging.error(
+                f"Error preparing structured output format for Google: {e}",
+                exc_info=True,
+            )
+            return None

application/llm/handlers/base.py

@@ -0,0 +1,351 @@
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, Generator, List, Optional, Union
+
+from application.logging import build_stack_data
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ToolCall:
+    """Represents a tool/function call from the LLM."""
+
+    id: str
+    name: str
+    arguments: Union[str, Dict]
+    index: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict) -> "ToolCall":
+        """Create ToolCall from dictionary."""
+        return cls(
+            id=data.get("id", ""),
+            name=data.get("name", ""),
+            arguments=data.get("arguments", {}),
+            index=data.get("index"),
+        )
+
+
+@dataclass
+class LLMResponse:
+    """Represents a response from the LLM."""
+
+    content: str
+    tool_calls: List[ToolCall]
+    finish_reason: str
+    raw_response: Any
+
+    @property
+    def requires_tool_call(self) -> bool:
+        """Check if the response requires tool calls."""
+        return bool(self.tool_calls) and self.finish_reason == "tool_calls"
+
+
+class LLMHandler(ABC):
+    """Abstract base class for LLM handlers."""
+
+    def __init__(self):
+        self.llm_calls = []
+        self.tool_calls = []
+
+    @abstractmethod
+    def parse_response(self, response: Any) -> LLMResponse:
+        """Parse raw LLM response into standardized format."""
+        pass
+
+    @abstractmethod
+    def create_tool_message(self, tool_call: ToolCall, result: Any) -> Dict:
+        """Create a tool result message for the conversation history."""
+        pass
+
+    @abstractmethod
+    def _iterate_stream(self, response: Any) -> Generator:
+        """Iterate through streaming response chunks."""
+        pass
+
+    def process_message_flow(
+        self,
+        agent,
+        initial_response,
+        tools_dict: Dict,
+        messages: List[Dict],
+        attachments: Optional[List] = None,
+        stream: bool = False,
+    ) -> Union[str, Generator]:
+        """
+        Main orchestration method for processing LLM message flow.
+
+        Args:
+            agent: The agent instance
+            initial_response: Initial LLM response
+            tools_dict: Dictionary of available tools
+            messages: Conversation history
+            attachments: Optional attachments
+            stream: Whether to use streaming
+
+        Returns:
+            Final response or generator for streaming
+        """
+        messages = self.prepare_messages(agent, messages, attachments)
+
+        if stream:
+            return self.handle_streaming(agent, initial_response, tools_dict, messages)
+        else:
+            return self.handle_non_streaming(
+                agent, initial_response, tools_dict, messages
+            )
+
+    def prepare_messages(
+        self, agent, messages: List[Dict], attachments: Optional[List] = None
+    ) -> List[Dict]:
+        """
+        Prepare messages with attachments and provider-specific formatting.
+
+        Args:
+            agent: The agent instance
+            messages: Original messages
+            attachments: List of attachments
+
+        Returns:
+            Prepared messages list
+        """
+        if not attachments:
+            return messages
+        logger.info(f"Preparing messages with {len(attachments)} attachments")
+        supported_types = agent.llm.get_supported_attachment_types()
+
+        supported_attachments = [
+            a for a in attachments if a.get("mime_type") in supported_types
+        ]
+        unsupported_attachments = [
+            a for a in attachments if a.get("mime_type") not in supported_types
+        ]
+
+        # Process supported attachments with the LLM's custom method
+
+        if supported_attachments:
+            logger.info(
+                f"Processing {len(supported_attachments)} supported attachments"
+            )
+            messages = agent.llm.prepare_messages_with_attachments(
+                messages, supported_attachments
+            )
+        # Process unsupported attachments with default method
+
+        if unsupported_attachments:
+            logger.info(
+                f"Processing {len(unsupported_attachments)} unsupported attachments"
+            )
+            messages = self._append_unsupported_attachments(
+                messages, unsupported_attachments
+            )
+        return messages
+
+    def _append_unsupported_attachments(
+        self, messages: List[Dict], attachments: List[Dict]
+    ) -> List[Dict]:
+        """
+        Default method to append unsupported attachment content to system prompt.
+
+        Args:
+            messages: Current messages
+            attachments: List of unsupported attachments
+
+        Returns:
+            Updated messages list
+        """
+        prepared_messages = messages.copy()
+        attachment_texts = []
+
+        for attachment in attachments:
+            logger.info(f"Adding attachment {attachment.get('id')} to context")
+            if "content" in attachment:
+                attachment_texts.append(
+                    f"Attached file content:\n\n{attachment['content']}"
+                )
+        if attachment_texts:
+            combined_text = "\n\n".join(attachment_texts)
+
+            system_msg = next(
+                (msg for msg in prepared_messages if msg.get("role") == "system"),
+                {"role": "system", "content": ""},
+            )
+
+            if system_msg not in prepared_messages:
+                prepared_messages.insert(0, system_msg)
+            system_msg["content"] += f"\n\n{combined_text}"
+        return prepared_messages
+
+    def handle_tool_calls(
+        self, agent, tool_calls: List[ToolCall], tools_dict: Dict, messages: List[Dict]
+    ) -> Generator:
+        """
+        Execute tool calls and update conversation history.
+
+        Args:
+            agent: The agent instance
+            tool_calls: List of tool calls to execute
+            tools_dict: Available tools dictionary
+            messages: Current conversation history
+
+        Returns:
+            Updated messages list
+        """
+        updated_messages = messages.copy()
+
+        for call in tool_calls:
+            try:
+                self.tool_calls.append(call)
+                tool_executor_gen = agent._execute_tool_action(tools_dict, call)
+                while True:
+                    try:
+                        yield next(tool_executor_gen)
+                    except StopIteration as e:
+                        tool_response, call_id = e.value
+                        break
+                updated_messages.append(
+                    {
+                        "role": "assistant",
+                        "content": [
+                            {
+                                "function_call": {
+                                    "name": call.name,
+                                    "args": call.arguments,
+                                    "call_id": call_id,
+                                }
+                            }
+                        ],
+                    }
+                )
+
+                updated_messages.append(self.create_tool_message(call, tool_response))
+            except Exception as e:
+                logger.error(f"Error executing tool: {str(e)}", exc_info=True)
+                error_call = ToolCall(
+                    id=call.id, name=call.name, arguments=call.arguments
+                )
+                error_response = f"Error executing tool: {str(e)}"
+                error_message = self.create_tool_message(error_call, error_response)
+                updated_messages.append(error_message)
+
+                call_parts = call.name.split("_")
+                if len(call_parts) >= 2:
+                    tool_id = call_parts[-1]  # Last part is tool ID (e.g., "1")
+                    action_name = "_".join(call_parts[:-1])
+                    tool_name = tools_dict.get(tool_id, {}).get("name", "unknown_tool")
+                    full_action_name = f"{action_name}_{tool_id}"
+                else:
+                    tool_name = "unknown_tool"
+                    action_name = call.name
+                    full_action_name = call.name
+                yield {
+                    "type": "tool_call",
+                    "data": {
+                        "tool_name": tool_name,
+                        "call_id": call.id,
+                        "action_name": full_action_name,
+                        "arguments": call.arguments,
+                        "error": error_response,
+                        "status": "error",
+                    },
+                }
+        return updated_messages
+
+    def handle_non_streaming(
+        self, agent, response: Any, tools_dict: Dict, messages: List[Dict]
+    ) -> Generator:
+        """
+        Handle non-streaming response flow.
+
+        Args:
+            agent: The agent instance
+            response: Current LLM response
+            tools_dict: Available tools dictionary
+            messages: Conversation history
+
+        Returns:
+            Final response after processing all tool calls
+        """
+        parsed = self.parse_response(response)
+        self.llm_calls.append(build_stack_data(agent.llm))
+
+        while parsed.requires_tool_call:
+            tool_handler_gen = self.handle_tool_calls(
+                agent, parsed.tool_calls, tools_dict, messages
+            )
+            while True:
+                try:
+                    yield next(tool_handler_gen)
+                except StopIteration as e:
+                    messages = e.value
+                    break
+            response = agent.llm.gen(
+                model=agent.gpt_model, messages=messages, tools=agent.tools
+            )
+            parsed = self.parse_response(response)
+            self.llm_calls.append(build_stack_data(agent.llm))
+        return parsed.content
+
+    def handle_streaming(
+        self, agent, response: Any, tools_dict: Dict, messages: List[Dict]
+    ) -> Generator:
+        """
+        Handle streaming response flow.
+
+        Args:
+            agent: The agent instance
+            response: Current LLM response
+            tools_dict: Available tools dictionary
+            messages: Conversation history
+
+        Yields:
+            Streaming response chunks
+        """
+        buffer = ""
+        tool_calls = {}
+
+        for chunk in self._iterate_stream(response):
+            if isinstance(chunk, str):
+                yield chunk
+                continue
+            parsed = self.parse_response(chunk)
+
+            if parsed.tool_calls:
+                for call in parsed.tool_calls:
+                    if call.index not in tool_calls:
+                        tool_calls[call.index] = call
+                    else:
+                        existing = tool_calls[call.index]
+                        if call.id:
+                            existing.id = call.id
+                        if call.name:
+                            existing.name = call.name
+                        if call.arguments:
+                            existing.arguments += call.arguments
+            if parsed.finish_reason == "tool_calls":
+                tool_handler_gen = self.handle_tool_calls(
+                    agent, list(tool_calls.values()), tools_dict, messages
+                )
+                while True:
+                    try:
+                        yield next(tool_handler_gen)
+                    except StopIteration as e:
+                        messages = e.value
+                        break
+                tool_calls = {}
+
+                response = agent.llm.gen_stream(
+                    model=agent.gpt_model, messages=messages, tools=agent.tools
+                )
+                self.llm_calls.append(build_stack_data(agent.llm))
+
+                yield from self.handle_streaming(agent, response, tools_dict, messages)
+                return
+            if parsed.content:
+                buffer += parsed.content
+                yield buffer
+                buffer = ""
+            if parsed.finish_reason == "stop":
+                return

application/llm/handlers/google.py

@@ -0,0 +1,78 @@
+import uuid
+from typing import Any, Dict, Generator
+
+from application.llm.handlers.base import LLMHandler, LLMResponse, ToolCall
+
+
+class GoogleLLMHandler(LLMHandler):
+    """Handler for Google's GenAI API."""
+
+    def parse_response(self, response: Any) -> LLMResponse:
+        """Parse Google response into standardized format."""
+
+        if isinstance(response, str):
+            return LLMResponse(
+                content=response,
+                tool_calls=[],
+                finish_reason="stop",
+                raw_response=response,
+            )
+        if hasattr(response, "candidates"):
+            parts = response.candidates[0].content.parts if response.candidates else []
+            tool_calls = [
+                ToolCall(
+                    id=str(uuid.uuid4()),
+                    name=part.function_call.name,
+                    arguments=part.function_call.args,
+                )
+                for part in parts
+                if hasattr(part, "function_call") and part.function_call is not None
+            ]
+
+            content = " ".join(
+                part.text
+                for part in parts
+                if hasattr(part, "text") and part.text is not None
+            )
+            return LLMResponse(
+                content=content,
+                tool_calls=tool_calls,
+                finish_reason="tool_calls" if tool_calls else "stop",
+                raw_response=response,
+            )
+        else:
+            tool_calls = []
+            if hasattr(response, "function_call"):
+                tool_calls.append(
+                    ToolCall(
+                        id=str(uuid.uuid4()),
+                        name=response.function_call.name,
+                        arguments=response.function_call.args,
+                    )
+                )
+            return LLMResponse(
+                content=response.text if hasattr(response, "text") else "",
+                tool_calls=tool_calls,
+                finish_reason="tool_calls" if tool_calls else "stop",
+                raw_response=response,
+            )
+
+    def create_tool_message(self, tool_call: ToolCall, result: Any) -> Dict:
+        """Create Google-style tool message."""
+
+        return {
+            "role": "model",
+            "content": [
+                {
+                    "function_response": {
+                        "name": tool_call.name,
+                        "response": {"result": result},
+                    }
+                }
+            ],
+        }
+
+    def _iterate_stream(self, response: Any) -> Generator:
+        """Iterate through Google streaming response."""
+        for chunk in response:
+            yield chunk

application/llm/handlers/handler_creator.py

@@ -0,0 +1,18 @@
+from application.llm.handlers.base import LLMHandler
+from application.llm.handlers.google import GoogleLLMHandler
+from application.llm.handlers.openai import OpenAILLMHandler
+
+
+class LLMHandlerCreator:
+    handlers = {
+        "openai": OpenAILLMHandler,
+        "google": GoogleLLMHandler,
+        "default": OpenAILLMHandler,
+    }
+
+    @classmethod
+    def create_handler(cls, llm_type: str, *args, **kwargs) -> LLMHandler:
+        handler_class = cls.handlers.get(llm_type.lower())
+        if not handler_class:
+            handler_class = OpenAILLMHandler
+        return handler_class(*args, **kwargs)

application/llm/handlers/openai.py

@@ -0,0 +1,57 @@
+from typing import Any, Dict, Generator
+
+from application.llm.handlers.base import LLMHandler, LLMResponse, ToolCall
+
+
+class OpenAILLMHandler(LLMHandler):
+    """Handler for OpenAI API."""
+
+    def parse_response(self, response: Any) -> LLMResponse:
+        """Parse OpenAI response into standardized format."""
+        if isinstance(response, str):
+            return LLMResponse(
+                content=response,
+                tool_calls=[],
+                finish_reason="stop",
+                raw_response=response,
+            )
+
+        message = getattr(response, "message", None) or getattr(response, "delta", None)
+
+        tool_calls = []
+        if hasattr(message, "tool_calls"):
+            tool_calls = [
+                ToolCall(
+                    id=getattr(tc, "id", ""),
+                    name=getattr(tc.function, "name", ""),
+                    arguments=getattr(tc.function, "arguments", ""),
+                    index=getattr(tc, "index", None),
+                )
+                for tc in message.tool_calls or []
+            ]
+        return LLMResponse(
+            content=getattr(message, "content", ""),
+            tool_calls=tool_calls,
+            finish_reason=getattr(response, "finish_reason", ""),
+            raw_response=response,
+        )
+
+    def create_tool_message(self, tool_call: ToolCall, result: Any) -> Dict:
+        """Create OpenAI-style tool message."""
+        return {
+            "role": "tool",
+            "content": [
+                {
+                    "function_response": {
+                        "name": tool_call.name,
+                        "response": {"result": result},
+                        "call_id": tool_call.id,
+                    }
+                }
+            ],
+        }
+
+    def _iterate_stream(self, response: Any) -> Generator:
+        """Iterate through OpenAI streaming response."""
+        for chunk in response:
+            yield chunk

application/llm/llama_cpp.py

@@ -2,6 +2,7 @@ from application.llm.base import BaseLLM
 from application.core.settings import settings
 import threading
 
+
 class LlamaSingleton:
     _instances = {}
     _lock = threading.Lock()  # Add a lock for thread synchronization
@@ -29,7 +30,7 @@ class LlamaCpp(BaseLLM):
         self,
         api_key=None,
         user_api_key=None,
-        llm_name=settings.MODEL_PATH,
+        llm_name=settings.LLM_PATH,
         *args,
         **kwargs,
     ):
@@ -42,14 +43,18 @@ class LlamaCpp(BaseLLM):
         context = messages[0]["content"]
         user_question = messages[-1]["content"]
         prompt = f"### Instruction \n {user_question} \n ### Context \n {context} \n ### Answer \n"
-        result = LlamaSingleton.query_model(self.llama, prompt, max_tokens=150, echo=False)
+        result = LlamaSingleton.query_model(
+            self.llama, prompt, max_tokens=150, echo=False
+        )
         return result["choices"][0]["text"].split("### Answer \n")[-1]
 
     def _raw_gen_stream(self, baseself, model, messages, stream=True, **kwargs):
         context = messages[0]["content"]
         user_question = messages[-1]["content"]
         prompt = f"### Instruction \n {user_question} \n ### Context \n {context} \n ### Answer \n"
-        result = LlamaSingleton.query_model(self.llama, prompt, max_tokens=150, echo=False, stream=stream)
+        result = LlamaSingleton.query_model(
+            self.llama, prompt, max_tokens=150, echo=False, stream=stream
+        )
         for item in result:
             for choice in item["choices"]:
-                yield choice["text"]
+                yield choice["text"]

application/llm/openai.py

@@ -1,7 +1,10 @@
+import base64
 import json
+import logging
 
 from application.core.settings import settings
 from application.llm.base import BaseLLM
+from application.storage.storage_creator import StorageCreator
 
 
 class OpenAILLM(BaseLLM):
@@ -10,12 +13,17 @@ class OpenAILLM(BaseLLM):
         from openai import OpenAI
 
         super().__init__(*args, **kwargs)
-        if settings.OPENAI_BASE_URL:
+        if (
+            isinstance(settings.OPENAI_BASE_URL, str)
+            and settings.OPENAI_BASE_URL.strip()
+        ):
             self.client = OpenAI(api_key=api_key, base_url=settings.OPENAI_BASE_URL)
         else:
-            self.client = OpenAI(api_key=api_key)
+            DEFAULT_OPENAI_API_BASE = "https://api.openai.com/v1"
+            self.client = OpenAI(api_key=api_key, base_url=DEFAULT_OPENAI_API_BASE)
         self.api_key = api_key
         self.user_api_key = user_api_key
+        self.storage = StorageCreator.get_storage()
 
     def _clean_messages_openai(self, messages):
         cleaned_messages = []
@@ -65,6 +73,33 @@ class OpenAILLM(BaseLLM):
                                     ),
                                 }
                             )
+                        elif isinstance(item, dict):
+                            content_parts = []
+                            if "text" in item:
+                                content_parts.append(
+                                    {"type": "text", "text": item["text"]}
+                                )
+                            elif (
+                                "type" in item
+                                and item["type"] == "text"
+                                and "text" in item
+                            ):
+                                content_parts.append(item)
+                            elif (
+                                "type" in item
+                                and item["type"] == "file"
+                                and "file" in item
+                            ):
+                                content_parts.append(item)
+                            elif (
+                                "type" in item
+                                and item["type"] == "image_url"
+                                and "image_url" in item
+                            ):
+                                content_parts.append(item)
+                            cleaned_messages.append(
+                                {"role": role, "content": content_parts}
+                            )
                         else:
                             raise ValueError(
                                 f"Unexpected content dictionary format: {item}"
@@ -82,22 +117,29 @@ class OpenAILLM(BaseLLM):
         stream=False,
         tools=None,
         engine=settings.AZURE_DEPLOYMENT_NAME,
+        response_format=None,
         **kwargs,
     ):
         messages = self._clean_messages_openai(messages)
+
+        request_params = {
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+            **kwargs,
+        }
+
+        if tools:
+            request_params["tools"] = tools
+
+        if response_format:
+            request_params["response_format"] = response_format
+
+        response = self.client.chat.completions.create(**request_params)
+
         if tools:
-            response = self.client.chat.completions.create(
-                model=model,
-                messages=messages,
-                stream=stream,
-                tools=tools,
-                **kwargs,
-            )
             return response.choices[0]
         else:
-            response = self.client.chat.completions.create(
-                model=model, messages=messages, stream=stream, **kwargs
-            )
             return response.choices[0].message.content
 
     def _raw_gen_stream(
@@ -108,24 +150,32 @@ class OpenAILLM(BaseLLM):
         stream=True,
         tools=None,
         engine=settings.AZURE_DEPLOYMENT_NAME,
+        response_format=None,
         **kwargs,
     ):
         messages = self._clean_messages_openai(messages)
+
+        request_params = {
+            "model": model,
+            "messages": messages,
+            "stream": stream,
+            **kwargs,
+        }
+
         if tools:
-            response = self.client.chat.completions.create(
-                model=model,
-                messages=messages,
-                stream=stream,
-                tools=tools,
-                **kwargs,
-            )
-        else:
-            response = self.client.chat.completions.create(
-                model=model, messages=messages, stream=stream, **kwargs
-            )
+            request_params["tools"] = tools
+
+        if response_format:
+            request_params["response_format"] = response_format
+
+        response = self.client.chat.completions.create(**request_params)
 
         for line in response:
-            if len(line.choices) > 0 and line.choices[0].delta.content is not None and len(line.choices[0].delta.content) > 0:
+            if (
+                len(line.choices) > 0
+                and line.choices[0].delta.content is not None
+                and len(line.choices[0].delta.content) > 0
+            ):
                 yield line.choices[0].delta.content
             elif len(line.choices) > 0:
                 yield line.choices[0]
@@ -133,12 +183,232 @@ class OpenAILLM(BaseLLM):
     def _supports_tools(self):
         return True
 
+    def _supports_structured_output(self):
+        return True
+
+    def prepare_structured_output_format(self, json_schema):
+        if not json_schema:
+            return None
+
+        try:
+
+            def add_additional_properties_false(schema_obj):
+                if isinstance(schema_obj, dict):
+                    schema_copy = schema_obj.copy()
+
+                    if schema_copy.get("type") == "object":
+                        schema_copy["additionalProperties"] = False
+                        # Ensure 'required' includes all properties for OpenAI strict mode
+                        if "properties" in schema_copy:
+                            schema_copy["required"] = list(
+                                schema_copy["properties"].keys()
+                            )
+
+                    for key, value in schema_copy.items():
+                        if key == "properties" and isinstance(value, dict):
+                            schema_copy[key] = {
+                                prop_name: add_additional_properties_false(prop_schema)
+                                for prop_name, prop_schema in value.items()
+                            }
+                        elif key == "items" and isinstance(value, dict):
+                            schema_copy[key] = add_additional_properties_false(value)
+                        elif key in ["anyOf", "oneOf", "allOf"] and isinstance(
+                            value, list
+                        ):
+                            schema_copy[key] = [
+                                add_additional_properties_false(sub_schema)
+                                for sub_schema in value
+                            ]
+
+                    return schema_copy
+                return schema_obj
+
+            processed_schema = add_additional_properties_false(json_schema)
+
+            result = {
+                "type": "json_schema",
+                "json_schema": {
+                    "name": processed_schema.get("name", "response"),
+                    "description": processed_schema.get(
+                        "description", "Structured response"
+                    ),
+                    "schema": processed_schema,
+                    "strict": True,
+                },
+            }
+
+            return result
+
+        except Exception as e:
+            logging.error(f"Error preparing structured output format: {e}")
+            return None
+
+    def get_supported_attachment_types(self):
+        """
+        Return a list of MIME types supported by OpenAI for file uploads.
+
+        Returns:
+            list: List of supported MIME types
+        """
+        return [
+            "application/pdf",
+            "image/png",
+            "image/jpeg",
+            "image/jpg",
+            "image/webp",
+            "image/gif",
+        ]
+
+    def prepare_messages_with_attachments(self, messages, attachments=None):
+        """
+        Process attachments using OpenAI's file API for more efficient handling.
+
+        Args:
+            messages (list): List of message dictionaries.
+            attachments (list): List of attachment dictionaries with content and metadata.
+
+        Returns:
+            list: Messages formatted with file references for OpenAI API.
+        """
+        if not attachments:
+            return messages
+
+        prepared_messages = messages.copy()
+
+        # Find the user message to attach file_id to the last one
+        user_message_index = None
+        for i in range(len(prepared_messages) - 1, -1, -1):
+            if prepared_messages[i].get("role") == "user":
+                user_message_index = i
+                break
+
+        if user_message_index is None:
+            user_message = {"role": "user", "content": []}
+            prepared_messages.append(user_message)
+            user_message_index = len(prepared_messages) - 1
+
+        if isinstance(prepared_messages[user_message_index].get("content"), str):
+            text_content = prepared_messages[user_message_index]["content"]
+            prepared_messages[user_message_index]["content"] = [
+                {"type": "text", "text": text_content}
+            ]
+        elif not isinstance(prepared_messages[user_message_index].get("content"), list):
+            prepared_messages[user_message_index]["content"] = []
+
+        for attachment in attachments:
+            mime_type = attachment.get("mime_type")
+
+            if mime_type and mime_type.startswith("image/"):
+                try:
+                    base64_image = self._get_base64_image(attachment)
+                    prepared_messages[user_message_index]["content"].append(
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": f"data:{mime_type};base64,{base64_image}"
+                            },
+                        }
+                    )
+                except Exception as e:
+                    logging.error(
+                        f"Error processing image attachment: {e}", exc_info=True
+                    )
+                    if "content" in attachment:
+                        prepared_messages[user_message_index]["content"].append(
+                            {
+                                "type": "text",
+                                "text": f"[Image could not be processed: {attachment.get('path', 'unknown')}]",
+                            }
+                        )
+            # Handle PDFs using the file API
+            elif mime_type == "application/pdf":
+                try:
+                    file_id = self._upload_file_to_openai(attachment)
+                    prepared_messages[user_message_index]["content"].append(
+                        {"type": "file", "file": {"file_id": file_id}}
+                    )
+                except Exception as e:
+                    logging.error(f"Error uploading PDF to OpenAI: {e}", exc_info=True)
+                    if "content" in attachment:
+                        prepared_messages[user_message_index]["content"].append(
+                            {
+                                "type": "text",
+                                "text": f"File content:\n\n{attachment['content']}",
+                            }
+                        )
+
+        return prepared_messages
+
+    def _get_base64_image(self, attachment):
+        """
+        Convert an image file to base64 encoding.
+
+        Args:
+            attachment (dict): Attachment dictionary with path and metadata.
+
+        Returns:
+            str: Base64-encoded image data.
+        """
+        file_path = attachment.get("path")
+        if not file_path:
+            raise ValueError("No file path provided in attachment")
+
+        try:
+            with self.storage.get_file(file_path) as image_file:
+                return base64.b64encode(image_file.read()).decode("utf-8")
+        except FileNotFoundError:
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+    def _upload_file_to_openai(self, attachment):
+        """
+        Upload a file to OpenAI and return the file_id.
+
+        Args:
+            attachment (dict): Attachment dictionary with path and metadata.
+                Expected keys:
+                - path: Path to the file
+                - id: Optional MongoDB ID for caching
+
+        Returns:
+            str: OpenAI file_id for the uploaded file.
+        """
+        import logging
+
+        if "openai_file_id" in attachment:
+            return attachment["openai_file_id"]
+
+        file_path = attachment.get("path")
+
+        if not self.storage.file_exists(file_path):
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        try:
+            file_id = self.storage.process_file(
+                file_path,
+                lambda local_path, **kwargs: self.client.files.create(
+                    file=open(local_path, "rb"), purpose="assistants"
+                ).id,
+            )
+
+            from application.core.mongo_db import MongoDB
+
+            mongo = MongoDB.get_client()
+            db = mongo[settings.MONGO_DB_NAME]
+            attachments_collection = db["attachments"]
+            if "_id" in attachment:
+                attachments_collection.update_one(
+                    {"_id": attachment["_id"]}, {"$set": {"openai_file_id": file_id}}
+                )
+
+            return file_id
+        except Exception as e:
+            logging.error(f"Error uploading file to OpenAI: {e}", exc_info=True)
+            raise
+
 
 class AzureOpenAILLM(OpenAILLM):
 
-    def __init__(
-        self, api_key, user_api_key, *args, **kwargs 
-    ):
+    def __init__(self, api_key, user_api_key, *args, **kwargs):
 
         super().__init__(api_key)
         self.api_base = (settings.OPENAI_API_BASE,)
@@ -149,5 +419,5 @@ class AzureOpenAILLM(OpenAILLM):
         self.client = AzureOpenAI(
             api_key=api_key,
             api_version=settings.OPENAI_API_VERSION,
-            azure_endpoint=settings.OPENAI_API_BASE
+            azure_endpoint=settings.OPENAI_API_BASE,
         )

application/logging.py

@@ -7,6 +7,7 @@ import uuid
 from typing import Any, Callable, Dict, Generator, List
 
 from application.core.mongo_db import MongoDB
+from application.core.settings import settings
 
 logging.basicConfig(
     level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
@@ -29,6 +30,8 @@ def build_stack_data(
     exclude_attributes: List[str] = None,
     custom_data: Dict = None,
 ) -> Dict:
+    if obj is None:
+        raise ValueError("The 'obj' parameter cannot be None")
     data = {}
     if include_attributes is None:
         include_attributes = []
@@ -56,8 +59,8 @@ def build_stack_data(
                         data[attr_name] = [str(item) for item in attr_value]
                 elif isinstance(attr_value, dict):
                     data[attr_name] = {k: str(v) for k, v in attr_value.items()}
-                else:
-                    data[attr_name] = str(attr_value)
+        except AttributeError as e:
+            logging.warning(f"AttributeError while accessing {attr_name}: {e}")
         except AttributeError:
             pass
     if custom_data:
@@ -131,8 +134,10 @@ def _log_to_mongodb(
 ) -> None:
     try:
         mongo = MongoDB.get_client()
-        db = mongo["docsgpt"]
+        db = mongo[settings.MONGO_DB_NAME]
         user_logs_collection = db["stack_logs"]
+        
+
 
         log_entry = {
             "endpoint": endpoint,
@@ -144,8 +149,13 @@ def _log_to_mongodb(
             "stacks": stacks,
             "timestamp": datetime.datetime.now(datetime.timezone.utc),
         }
+        # clean up text fields to be no longer than 10000 characters
+        for key, value in log_entry.items():
+            if isinstance(value, str) and len(value) > 10000:
+                log_entry[key] = value[:10000]
+    
         user_logs_collection.insert_one(log_entry)
         logging.debug(f"Logged activity to MongoDB: {activity_id}")
 
     except Exception as e:
-        logging.error(f"Failed to log to MongoDB: {e}")
+        logging.error(f"Failed to log to MongoDB: {e}", exc_info=True)

application/parser/chunking.py

@@ -32,16 +32,7 @@ class Chunker:
             header, body = "", text  # No header, treat entire text as body
         return header, body
 
-    def combine_documents(self, doc: Document, next_doc: Document) -> Document:
-        combined_text = doc.text + " " + next_doc.text
-        combined_token_count = len(self.encoding.encode(combined_text))
-        new_doc = Document(
-            text=combined_text,
-            doc_id=doc.doc_id,
-            embedding=doc.embedding,
-            extra_info={**(doc.extra_info or {}), "token_count": combined_token_count}
-        )
-        return new_doc
+
     
     def split_document(self, doc: Document) -> List[Document]:
         split_docs = []
@@ -82,26 +73,11 @@ class Chunker:
                 processed_docs.append(doc)
                 i += 1
             elif token_count < self.min_tokens:
-                if i + 1 < len(documents):
-                    next_doc = documents[i + 1]
-                    next_tokens = self.encoding.encode(next_doc.text)
-                    if token_count + len(next_tokens) <= self.max_tokens:
-                        # Combine small documents
-                        combined_doc = self.combine_documents(doc, next_doc)
-                        processed_docs.append(combined_doc)
-                        i += 2
-                    else:
-                        # Keep the small document as is if adding next_doc would exceed max_tokens
-                        doc.extra_info = doc.extra_info or {}
-                        doc.extra_info["token_count"] = token_count
-                        processed_docs.append(doc)
-                        i += 1
-                else:
-                    # No next document to combine with; add the small document as is
-                    doc.extra_info = doc.extra_info or {}
-                    doc.extra_info["token_count"] = token_count
-                    processed_docs.append(doc)
-                    i += 1
+  
+                doc.extra_info = doc.extra_info or {}
+                doc.extra_info["token_count"] = token_count
+                processed_docs.append(doc)
+                i += 1
             else:
                 # Split large documents
                 processed_docs.extend(self.split_document(doc))

application/parser/connectors/__init__.py

@@ -0,0 +1,18 @@
+"""
+External knowledge base connectors for DocsGPT.
+
+This module contains connectors for external knowledge bases and document storage systems
+that require authentication and specialized handling, separate from simple web scrapers.
+"""
+
+from .base import BaseConnectorAuth, BaseConnectorLoader
+from .connector_creator import ConnectorCreator
+from .google_drive import GoogleDriveAuth, GoogleDriveLoader
+
+__all__ = [
+    'BaseConnectorAuth',
+    'BaseConnectorLoader',
+    'ConnectorCreator',
+    'GoogleDriveAuth',
+    'GoogleDriveLoader'
+]

application/parser/connectors/base.py

@@ -0,0 +1,129 @@
+"""
+Base classes for external knowledge base connectors.
+
+This module provides minimal abstract base classes that define the essential
+interface for external knowledge base connectors.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+from application.parser.schema.base import Document
+
+
+class BaseConnectorAuth(ABC):
+    """
+    Abstract base class for connector authentication.
+    
+    Defines the minimal interface that all connector authentication
+    implementations must follow.
+    """
+    
+    @abstractmethod
+    def get_authorization_url(self, state: Optional[str] = None) -> str:
+        """
+        Generate authorization URL for OAuth flows.
+        
+        Args:
+            state: Optional state parameter for CSRF protection
+            
+        Returns:
+            Authorization URL
+        """
+        pass
+    
+    @abstractmethod
+    def exchange_code_for_tokens(self, authorization_code: str) -> Dict[str, Any]:
+        """
+        Exchange authorization code for access tokens.
+        
+        Args:
+            authorization_code: Authorization code from OAuth callback
+            
+        Returns:
+            Dictionary containing token information
+        """
+        pass
+    
+    @abstractmethod
+    def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]:
+        """
+        Refresh an expired access token.
+        
+        Args:
+            refresh_token: Refresh token
+            
+        Returns:
+            Dictionary containing refreshed token information
+        """
+        pass
+    
+    @abstractmethod
+    def is_token_expired(self, token_info: Dict[str, Any]) -> bool:
+        """
+        Check if a token is expired.
+        
+        Args:
+            token_info: Token information dictionary
+            
+        Returns:
+            True if token is expired, False otherwise
+        """
+        pass
+
+
+class BaseConnectorLoader(ABC):
+    """
+    Abstract base class for connector loaders.
+    
+    Defines the minimal interface that all connector loader
+    implementations must follow.
+    """
+    
+    @abstractmethod
+    def __init__(self, session_token: str):
+        """
+        Initialize the connector loader.
+        
+        Args:
+            session_token: Authentication session token
+        """
+        pass
+    
+    @abstractmethod
+    def load_data(self, inputs: Dict[str, Any]) -> List[Document]:
+        """
+        Load documents from the external knowledge base.
+        
+        Args:
+            inputs: Configuration dictionary containing:
+                - file_ids: Optional list of specific file IDs to load
+                - folder_ids: Optional list of folder IDs to browse/download
+                - limit: Maximum number of items to return
+                - list_only: If True, return metadata without content
+                - recursive: Whether to recursively process folders
+                
+        Returns:
+            List of Document objects
+        """
+        pass
+    
+    @abstractmethod
+    def download_to_directory(self, local_dir: str, source_config: Dict[str, Any] = None) -> Dict[str, Any]:
+        """
+        Download files/folders to a local directory.
+        
+        Args:
+            local_dir: Local directory path to download files to
+            source_config: Configuration for what to download
+            
+        Returns:
+            Dictionary containing download results:
+                - files_downloaded: Number of files downloaded
+                - directory_path: Path where files were downloaded
+                - empty_result: Whether no files were downloaded
+                - source_type: Type of connector
+                - config_used: Configuration that was used
+                - error: Error message if download failed (optional)
+        """
+        pass

application/parser/connectors/connector_creator.py

@@ -0,0 +1,81 @@
+from application.parser.connectors.google_drive.loader import GoogleDriveLoader
+from application.parser.connectors.google_drive.auth import GoogleDriveAuth
+
+
+class ConnectorCreator:
+    """
+    Factory class for creating external knowledge base connectors and auth providers.
+
+    These are different from remote loaders as they typically require
+    authentication and connect to external document storage systems.
+    """
+
+    connectors = {
+        "google_drive": GoogleDriveLoader,
+    }
+
+    auth_providers = {
+        "google_drive": GoogleDriveAuth,
+    }
+
+    @classmethod
+    def create_connector(cls, connector_type, *args, **kwargs):
+        """
+        Create a connector instance for the specified type.
+
+        Args:
+            connector_type: Type of connector to create (e.g., 'google_drive')
+            *args, **kwargs: Arguments to pass to the connector constructor
+
+        Returns:
+            Connector instance
+
+        Raises:
+            ValueError: If connector type is not supported
+        """
+        connector_class = cls.connectors.get(connector_type.lower())
+        if not connector_class:
+            raise ValueError(f"No connector class found for type {connector_type}")
+        return connector_class(*args, **kwargs)
+
+    @classmethod
+    def create_auth(cls, connector_type):
+        """
+        Create an auth provider instance for the specified connector type.
+
+        Args:
+            connector_type: Type of connector auth to create (e.g., 'google_drive')
+
+        Returns:
+            Auth provider instance
+
+        Raises:
+            ValueError: If connector type is not supported for auth
+        """
+        auth_class = cls.auth_providers.get(connector_type.lower())
+        if not auth_class:
+            raise ValueError(f"No auth class found for type {connector_type}")
+        return auth_class()
+
+    @classmethod
+    def get_supported_connectors(cls):
+        """
+        Get list of supported connector types.
+
+        Returns:
+            List of supported connector type strings
+        """
+        return list(cls.connectors.keys())
+
+    @classmethod
+    def is_supported(cls, connector_type):
+        """
+        Check if a connector type is supported.
+
+        Args:
+            connector_type: Type of connector to check
+
+        Returns:
+            True if supported, False otherwise
+        """
+        return connector_type.lower() in cls.connectors

application/parser/connectors/google_drive/__init__.py

@@ -0,0 +1,10 @@
+"""
+Google Drive connector for DocsGPT.
+
+This module provides authentication and document loading capabilities for Google Drive.
+"""
+
+from .auth import GoogleDriveAuth
+from .loader import GoogleDriveLoader
+
+__all__ = ['GoogleDriveAuth', 'GoogleDriveLoader']

application/parser/connectors/google_drive/auth.py

@@ -0,0 +1,267 @@
+import logging
+import datetime
+from typing import Optional, Dict, Any
+
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import Flow
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from application.core.settings import settings
+from application.parser.connectors.base import BaseConnectorAuth
+
+
+class GoogleDriveAuth(BaseConnectorAuth):
+    """
+    Handles Google OAuth 2.0 authentication for Google Drive access.
+    """
+    
+    SCOPES = [
+        'https://www.googleapis.com/auth/drive.file'
+    ]
+    
+    def __init__(self):
+        self.client_id = settings.GOOGLE_CLIENT_ID
+        self.client_secret = settings.GOOGLE_CLIENT_SECRET
+        self.redirect_uri = f"{settings.CONNECTOR_REDIRECT_BASE_URI}"
+        
+        if not self.client_id or not self.client_secret:
+            raise ValueError("Google OAuth credentials not configured. Please set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in settings.")
+
+
+
+    def get_authorization_url(self, state: Optional[str] = None) -> str:
+        try:
+            flow = Flow.from_client_config(
+                {
+                    "web": {
+                        "client_id": self.client_id,
+                        "client_secret": self.client_secret,
+                        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                        "token_uri": "https://oauth2.googleapis.com/token",
+                        "redirect_uris": [self.redirect_uri]
+                    }
+                },
+                scopes=self.SCOPES
+            )
+            flow.redirect_uri = self.redirect_uri
+            
+            authorization_url, _ = flow.authorization_url(
+                access_type='offline',
+                prompt='consent',
+                include_granted_scopes='false',
+                state=state
+            )
+            
+            return authorization_url
+            
+        except Exception as e:
+            logging.error(f"Error generating authorization URL: {e}")
+            raise
+    
+    def exchange_code_for_tokens(self, authorization_code: str) -> Dict[str, Any]:
+        try:
+            if not authorization_code:
+                raise ValueError("Authorization code is required")
+
+            flow = Flow.from_client_config(
+                {
+                    "web": {
+                        "client_id": self.client_id,
+                        "client_secret": self.client_secret,
+                        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                        "token_uri": "https://oauth2.googleapis.com/token",
+                        "redirect_uris": [self.redirect_uri]
+                    }
+                },
+                scopes=self.SCOPES
+            )
+            flow.redirect_uri = self.redirect_uri
+
+            flow.fetch_token(code=authorization_code)
+
+            credentials = flow.credentials
+
+            if not credentials.refresh_token:
+                logging.warning("OAuth flow did not return a refresh_token.")
+            if not credentials.token:
+                raise ValueError("OAuth flow did not return an access token")
+
+            if not credentials.token_uri:
+                credentials.token_uri = "https://oauth2.googleapis.com/token"
+
+            if not credentials.client_id:
+                credentials.client_id = self.client_id
+
+            if not credentials.client_secret:
+                credentials.client_secret = self.client_secret
+
+            if not credentials.refresh_token:
+                raise ValueError(
+                    "No refresh token received. This typically happens when offline access wasn't granted. "
+                )
+
+            return {
+                'access_token': credentials.token,
+                'refresh_token': credentials.refresh_token,
+                'token_uri': credentials.token_uri,
+                'client_id': credentials.client_id,
+                'client_secret': credentials.client_secret,
+                'scopes': credentials.scopes,
+                'expiry': credentials.expiry.isoformat() if credentials.expiry else None
+            }
+
+        except Exception as e:
+            logging.error(f"Error exchanging code for tokens: {e}")
+            raise
+    
+    def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]:
+        try:
+            if not refresh_token:
+                raise ValueError("Refresh token is required")
+
+            credentials = Credentials(
+                token=None,
+                refresh_token=refresh_token,
+                token_uri="https://oauth2.googleapis.com/token",
+                client_id=self.client_id,
+                client_secret=self.client_secret
+            )
+
+            from google.auth.transport.requests import Request
+            credentials.refresh(Request())
+
+            return {
+                'access_token': credentials.token,
+                'refresh_token': refresh_token,
+                'token_uri': credentials.token_uri,
+                'client_id': credentials.client_id,
+                'client_secret': credentials.client_secret,
+                'scopes': credentials.scopes,
+                'expiry': credentials.expiry.isoformat() if credentials.expiry else None
+            }
+        except Exception as e:
+            logging.error(f"Error refreshing access token: {e}", exc_info=True)
+            raise
+    
+    def create_credentials_from_token_info(self, token_info: Dict[str, Any]) -> Credentials:
+        from application.core.settings import settings
+
+        access_token = token_info.get('access_token')
+        if not access_token:
+            raise ValueError("No access token found in token_info")
+
+        credentials = Credentials(
+            token=access_token,
+            refresh_token=token_info.get('refresh_token'),
+            token_uri= 'https://oauth2.googleapis.com/token',
+            client_id=settings.GOOGLE_CLIENT_ID,
+            client_secret=settings.GOOGLE_CLIENT_SECRET,
+            scopes=token_info.get('scopes', ['https://www.googleapis.com/auth/drive.readonly'])
+        )
+
+        if not credentials.token:
+            raise ValueError("Credentials created without valid access token")
+
+        return credentials
+    
+    def build_drive_service(self, credentials: Credentials):
+        try:
+            if not credentials:
+                raise ValueError("No credentials provided")
+
+            if not credentials.token and not credentials.refresh_token:
+                raise ValueError("No access token or refresh token available. User must re-authorize with offline access.")
+
+            needs_refresh = credentials.expired or not credentials.token
+            if needs_refresh:
+                if credentials.refresh_token:
+                    try:
+                        from google.auth.transport.requests import Request
+                        credentials.refresh(Request())
+                    except Exception as refresh_error:
+                        raise ValueError(f"Failed to refresh credentials: {refresh_error}")
+                else:
+                    raise ValueError("No access token or refresh token available. User must re-authorize with offline access.")
+
+            return build('drive', 'v3', credentials=credentials)
+
+        except HttpError as e:
+            raise ValueError(f"Failed to build Google Drive service: HTTP {e.resp.status}")
+        except Exception as e:
+            raise ValueError(f"Failed to build Google Drive service: {str(e)}")
+        
+    def is_token_expired(self, token_info):
+        if 'expiry' in token_info and token_info['expiry']:
+            try:
+                from dateutil import parser
+                # Google Drive provides timezone-aware ISO8601 dates
+                expiry_dt = parser.parse(token_info['expiry'])
+                current_time = datetime.datetime.now(datetime.timezone.utc)
+                return current_time >= expiry_dt - datetime.timedelta(seconds=60)
+            except Exception:
+                return True
+
+        if 'access_token' in token_info and token_info['access_token']:
+            return False
+
+        return True
+    
+    def get_token_info_from_session(self, session_token: str) -> Dict[str, Any]:
+        try:
+            from application.core.mongo_db import MongoDB
+            from application.core.settings import settings
+
+            mongo = MongoDB.get_client()
+            db = mongo[settings.MONGO_DB_NAME]
+            
+            sessions_collection = db["connector_sessions"]
+            session = sessions_collection.find_one({"session_token": session_token})   
+            if not session:
+                raise ValueError(f"Invalid session token: {session_token}")
+
+            if "token_info" not in session:
+                raise ValueError("Session missing token information")
+
+            token_info = session["token_info"]
+            if not token_info:
+                raise ValueError("Invalid token information")
+
+            required_fields = ["access_token", "refresh_token"]
+            missing_fields = [field for field in required_fields if field not in token_info or not token_info.get(field)]
+            if missing_fields:
+                raise ValueError(f"Missing required token fields: {missing_fields}")
+
+            if 'client_id' not in token_info:
+                token_info['client_id'] = settings.GOOGLE_CLIENT_ID
+            if 'client_secret' not in token_info:
+                token_info['client_secret'] = settings.GOOGLE_CLIENT_SECRET
+            if 'token_uri' not in token_info:
+                token_info['token_uri'] = 'https://oauth2.googleapis.com/token'
+
+            return token_info
+
+        except Exception as e:
+            raise ValueError(f"Failed to retrieve Google Drive token information: {str(e)}")
+
+    def validate_credentials(self, credentials: Credentials) -> bool:
+        """
+        Validate Google Drive credentials by making a test API call.
+
+        Args:
+            credentials: Google credentials object
+
+        Returns:
+            True if credentials are valid, False otherwise
+        """
+        try:
+            service = self.build_drive_service(credentials)
+            service.about().get(fields="user").execute()
+            return True
+
+        except HttpError as e:
+            logging.error(f"HTTP error validating credentials: {e}")
+            return False
+        except Exception as e:
+            logging.error(f"Error validating credentials: {e}")
+            return False

application/parser/connectors/google_drive/loader.py

@@ -0,0 +1,559 @@
+"""
+Google Drive loader for DocsGPT.
+Loads documents from Google Drive using Google Drive API.
+"""
+
+import io
+import logging
+import os
+from typing import List, Dict, Any, Optional
+
+from googleapiclient.http import MediaIoBaseDownload
+from googleapiclient.errors import HttpError
+
+from application.parser.connectors.base import BaseConnectorLoader
+from application.parser.connectors.google_drive.auth import GoogleDriveAuth
+from application.parser.schema.base import Document
+
+
+class GoogleDriveLoader(BaseConnectorLoader):
+
+    SUPPORTED_MIME_TYPES = {
+        'application/pdf': '.pdf',
+        'application/vnd.google-apps.document': '.docx',
+        'application/vnd.google-apps.presentation': '.pptx',
+        'application/vnd.google-apps.spreadsheet': '.xlsx',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+        'application/msword': '.doc',
+        'application/vnd.ms-powerpoint': '.ppt',
+        'application/vnd.ms-excel': '.xls',
+        'text/plain': '.txt',
+        'text/csv': '.csv',
+        'text/html': '.html',
+        'text/markdown': '.md',
+        'text/x-rst': '.rst',
+        'application/json': '.json',
+        'application/epub+zip': '.epub',
+        'application/rtf': '.rtf',
+        'image/jpeg': '.jpg',
+        'image/jpg': '.jpg',
+        'image/png': '.png',
+    }
+
+    EXPORT_FORMATS = {
+        'application/vnd.google-apps.document': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        'application/vnd.google-apps.presentation': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        'application/vnd.google-apps.spreadsheet': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+    }
+
+    def __init__(self, session_token: str):
+        self.auth = GoogleDriveAuth()
+        self.session_token = session_token
+
+        token_info = self.auth.get_token_info_from_session(session_token)
+        self.credentials = self.auth.create_credentials_from_token_info(token_info)
+
+        try:
+            self.service = self.auth.build_drive_service(self.credentials)
+        except Exception as e:
+            logging.warning(f"Could not build Google Drive service: {e}")
+            self.service = None
+
+        self.next_page_token = None
+
+
+
+    def _process_file(self, file_metadata: Dict[str, Any], load_content: bool = True) -> Optional[Document]:
+        try:
+            file_id = file_metadata.get('id')
+            file_name = file_metadata.get('name', 'Unknown')
+            mime_type = file_metadata.get('mimeType', 'application/octet-stream')
+
+            if mime_type not in self.SUPPORTED_MIME_TYPES and not mime_type.startswith('application/vnd.google-apps.'):
+                return None
+            if mime_type not in self.SUPPORTED_MIME_TYPES and not mime_type.startswith('application/vnd.google-apps.'):
+                logging.info(f"Skipping unsupported file type: {mime_type} for file {file_name}")
+                return None
+            # Google Drive provides timezone-aware ISO8601 dates
+            doc_metadata = {
+                'file_name': file_name,
+                'mime_type': mime_type,
+                'size': file_metadata.get('size', None),
+                'created_time': file_metadata.get('createdTime'),
+                'modified_time': file_metadata.get('modifiedTime'),
+                'parents': file_metadata.get('parents', []),
+                'source': 'google_drive'
+            }
+
+            if not load_content:
+                return Document(
+                    text="",
+                    doc_id=file_id,
+                    extra_info=doc_metadata
+                )
+
+            content = self._download_file_content(file_id, mime_type)
+            if content is None:
+                logging.warning(f"Could not load content for file {file_name} ({file_id})")
+                return None
+
+            return Document(
+                text=content,
+                doc_id=file_id,
+                extra_info=doc_metadata
+            )
+
+        except Exception as e:
+            logging.error(f"Error processing file: {e}")
+            return None
+
+    def load_data(self, inputs: Dict[str, Any]) -> List[Document]:
+        session_token = inputs.get('session_token')
+        if session_token and session_token != self.session_token:
+            logging.warning("Session token in inputs differs from loader's session token. Using loader's session token.")
+        self.config = inputs
+
+        try:
+            documents: List[Document] = []
+
+            folder_id = inputs.get('folder_id')
+            file_ids = inputs.get('file_ids', [])
+            limit = inputs.get('limit', 100)
+            list_only = inputs.get('list_only', False)
+            load_content = not list_only
+            page_token = inputs.get('page_token')
+            search_query = inputs.get('search_query')
+            self.next_page_token = None
+
+            if file_ids:
+                # Specific files requested: load them
+                for file_id in file_ids:
+                    try:
+                        doc = self._load_file_by_id(file_id, load_content=load_content)
+                        if doc:
+                            if not search_query or (
+                                search_query.lower() in doc.extra_info.get('file_name', '').lower()
+                            ):
+                                documents.append(doc)
+                        elif hasattr(self, '_credential_refreshed') and self._credential_refreshed:
+                            self._credential_refreshed = False
+                            logging.info(f"Retrying load of file {file_id} after credential refresh")
+                            doc = self._load_file_by_id(file_id, load_content=load_content)
+                            if doc and (
+                                not search_query or 
+                                search_query.lower() in doc.extra_info.get('file_name', '').lower()
+                            ):
+                                documents.append(doc)
+                    except Exception as e:
+                        logging.error(f"Error loading file {file_id}: {e}")
+                        continue
+            else:
+                # Browsing mode: list immediate children of provided folder or root
+                parent_id = folder_id if folder_id else 'root'
+                documents = self._list_items_in_parent(
+                    parent_id, 
+                    limit=limit, 
+                    load_content=load_content, 
+                    page_token=page_token,
+                    search_query=search_query
+                )
+
+            logging.info(f"Loaded {len(documents)} documents from Google Drive")
+            return documents
+
+        except Exception as e:
+            logging.error(f"Error loading data from Google Drive: {e}", exc_info=True)
+            raise
+
+
+
+    def _load_file_by_id(self, file_id: str, load_content: bool = True) -> Optional[Document]:
+        self._ensure_service()
+
+        try:
+            file_metadata = self.service.files().get(
+                fileId=file_id,
+                fields='id,name,mimeType,size,createdTime,modifiedTime,parents'
+            ).execute()
+
+            return self._process_file(file_metadata, load_content=load_content)
+
+        except HttpError as e:
+            logging.error(f"HTTP error loading file {file_id}: {e.resp.status} - {e.content}")
+
+            if e.resp.status in [401, 403]:
+                if hasattr(self.credentials, 'refresh_token') and self.credentials.refresh_token:
+                    try:
+                        from google.auth.transport.requests import Request
+                        self.credentials.refresh(Request())
+                        self._ensure_service()
+                        return None
+                    except Exception as refresh_error:
+                        raise ValueError(f"Authentication failed and could not be refreshed: {refresh_error}")
+                else:
+                    raise ValueError("Authentication failed and cannot be refreshed: missing refresh_token")
+
+            return None
+        except Exception as e:
+            logging.error(f"Error loading file {file_id}: {e}")
+            return None
+
+
+    def _list_items_in_parent(self, parent_id: str, limit: int = 100, load_content: bool = False, page_token: Optional[str] = None, search_query: Optional[str] = None) -> List[Document]:
+        self._ensure_service()
+
+        documents: List[Document] = []
+
+        try:
+            query = f"'{parent_id}' in parents and trashed=false"
+
+            if search_query:
+                safe_search = search_query.replace("'", "\\'")
+                query += f" and name contains '{safe_search}'"
+
+            next_token_out: Optional[str] = None
+
+            while True:
+                page_size = 100
+                if limit:
+                    remaining = max(0, limit - len(documents))
+                    if remaining == 0:
+                        break
+                    page_size = min(100, remaining)
+
+                results = self.service.files().list(
+                    q=query,
+                    fields='nextPageToken,files(id,name,mimeType,size,createdTime,modifiedTime,parents)',
+                    pageToken=page_token,
+                    pageSize=page_size,
+                    orderBy='name'
+                ).execute()
+
+                items = results.get('files', [])
+                for item in items:
+                    mime_type = item.get('mimeType')
+                    if mime_type == 'application/vnd.google-apps.folder':
+                        doc_metadata = {
+                            'file_name': item.get('name', 'Unknown'),
+                            'mime_type': mime_type,
+                            'size': item.get('size', None),
+                            'created_time': item.get('createdTime'),
+                            'modified_time': item.get('modifiedTime'),
+                            'parents': item.get('parents', []),
+                            'source': 'google_drive',
+                            'is_folder': True
+                        }
+                        documents.append(Document(text="", doc_id=item.get('id'), extra_info=doc_metadata))
+                    else:
+                        doc = self._process_file(item, load_content=load_content)
+                        if doc:
+                            documents.append(doc)
+
+                    if limit and len(documents) >= limit:
+                        self.next_page_token = results.get('nextPageToken')
+                        return documents
+
+                page_token = results.get('nextPageToken')
+                next_token_out = page_token
+                if not page_token:
+                    break
+
+            self.next_page_token = next_token_out
+            return documents
+        except Exception as e:
+            logging.error(f"Error listing items under parent {parent_id}: {e}")
+            return documents
+
+
+
+
+    def _download_file_content(self, file_id: str, mime_type: str) -> Optional[str]:
+        if not self.credentials.token:
+            logging.warning("No access token in credentials, attempting to refresh")
+            if hasattr(self.credentials, 'refresh_token') and self.credentials.refresh_token:
+                try:
+                    from google.auth.transport.requests import Request
+                    self.credentials.refresh(Request())
+                    logging.info("Credentials refreshed successfully")
+                    self._ensure_service()
+                except Exception as e:
+                    logging.error(f"Failed to refresh credentials: {e}")
+                    raise ValueError("Authentication failed and cannot be refreshed: missing or invalid refresh_token")
+            else:
+                logging.error("No access token and no refresh_token available")
+                raise ValueError("Authentication failed and cannot be refreshed: missing refresh_token")
+
+        if self.credentials.expired:
+            logging.warning("Credentials are expired, attempting to refresh")
+            if hasattr(self.credentials, 'refresh_token') and self.credentials.refresh_token:
+                try:
+                    from google.auth.transport.requests import Request
+                    self.credentials.refresh(Request())
+                    logging.info("Credentials refreshed successfully")
+                    self._ensure_service()
+                except Exception as e:
+                    logging.error(f"Failed to refresh expired credentials: {e}")
+                    raise ValueError("Authentication failed and cannot be refreshed: expired credentials")
+            else:
+                logging.error("Credentials expired and no refresh_token available")
+                raise ValueError("Authentication failed and cannot be refreshed: missing refresh_token")
+
+        try:
+            if mime_type in self.EXPORT_FORMATS:
+                export_mime_type = self.EXPORT_FORMATS[mime_type]
+                request = self.service.files().export_media(
+                    fileId=file_id,
+                    mimeType=export_mime_type
+                )
+            else:
+                request = self.service.files().get_media(fileId=file_id)
+
+            file_io = io.BytesIO()
+            downloader = MediaIoBaseDownload(file_io, request)
+
+            done = False
+            while done is False:
+                try:
+                    _, done = downloader.next_chunk()
+                except HttpError as e:
+                    logging.error(f"HTTP error downloading file {file_id}: {e.resp.status} - {e.content}")
+                    return None
+                except Exception as e:
+                    logging.error(f"Error during download of file {file_id}: {e}")
+                    return None
+
+            content_bytes = file_io.getvalue()
+
+            try:
+                content = content_bytes.decode('utf-8')
+            except UnicodeDecodeError:
+                try:
+                    content = content_bytes.decode('latin-1')
+                except UnicodeDecodeError:
+                    logging.error(f"Could not decode file {file_id} as text")
+                    return None
+
+            return content
+
+        except HttpError as e:
+            logging.error(f"HTTP error downloading file {file_id}: {e.resp.status} - {e.content}")
+
+            if e.resp.status in [401, 403]:
+                logging.error(f"Authentication error downloading file {file_id}")
+
+                if hasattr(self.credentials, 'refresh_token') and self.credentials.refresh_token:
+                    logging.info(f"Attempting to refresh credentials for file {file_id}")
+                    try:
+                        from google.auth.transport.requests import Request
+                        self.credentials.refresh(Request())
+                        logging.info("Credentials refreshed successfully")
+                        self._credential_refreshed = True
+                        self._ensure_service()
+                        return None
+                    except Exception as refresh_error:
+                        logging.error(f"Error refreshing credentials: {refresh_error}")
+                        raise ValueError(f"Authentication failed and could not be refreshed: {refresh_error}")
+                else:
+                    logging.error("Cannot refresh credentials: missing refresh_token")
+                    raise ValueError("Authentication failed and cannot be refreshed: missing refresh_token")
+
+            return None
+        except Exception as e:
+            logging.error(f"Error downloading file {file_id}: {e}")
+            return None
+
+
+    def _download_file_to_directory(self, file_id: str, local_dir: str) -> bool:
+        try:
+            self._ensure_service()
+            return self._download_single_file(file_id, local_dir)
+        except Exception as e:
+            logging.error(f"Error downloading file {file_id}: {e}", exc_info=True)
+            return False
+
+    def _ensure_service(self):
+        if not self.service:
+            try:
+                self.service = self.auth.build_drive_service(self.credentials)
+            except Exception as e:
+                raise ValueError(f"Cannot access Google Drive: {e}")
+
+    def _download_single_file(self, file_id: str, local_dir: str) -> bool:
+        file_metadata = self.service.files().get(
+            fileId=file_id,
+            fields='name,mimeType'
+        ).execute()
+
+        file_name = file_metadata['name']
+        mime_type = file_metadata['mimeType']
+
+        if mime_type not in self.SUPPORTED_MIME_TYPES and not mime_type.startswith('application/vnd.google-apps.'):
+            return False
+
+        os.makedirs(local_dir, exist_ok=True)
+        full_path = os.path.join(local_dir, file_name)
+
+        if mime_type in self.EXPORT_FORMATS:
+            export_mime_type = self.EXPORT_FORMATS[mime_type]
+            request = self.service.files().export_media(
+                fileId=file_id,
+                mimeType=export_mime_type
+            )
+            extension = self._get_extension_for_mime_type(export_mime_type)
+            if not full_path.endswith(extension):
+                full_path += extension
+        else:
+            request = self.service.files().get_media(fileId=file_id)
+
+        with open(full_path, 'wb') as f:
+            downloader = MediaIoBaseDownload(f, request)
+            done = False
+            while not done:
+                _, done = downloader.next_chunk()
+
+        return True
+
+    def _download_folder_recursive(self, folder_id: str, local_dir: str, recursive: bool = True) -> int:
+        files_downloaded = 0
+        try:
+            os.makedirs(local_dir, exist_ok=True)
+
+            query = f"'{folder_id}' in parents and trashed=false"
+            page_token = None
+
+            while True:
+                results = self.service.files().list(
+                    q=query,
+                    fields='nextPageToken, files(id, name, mimeType)',
+                    pageToken=page_token,
+                    pageSize=1000
+                ).execute()
+
+                items = results.get('files', [])
+                logging.info(f"Found {len(items)} items in folder {folder_id}")
+
+                for item in items:
+                    item_name = item['name']
+                    item_id = item['id']
+                    mime_type = item['mimeType']
+
+                    if mime_type == 'application/vnd.google-apps.folder':
+                        if recursive:
+                            # Create subfolder and recurse
+                            subfolder_path = os.path.join(local_dir, item_name)
+                            os.makedirs(subfolder_path, exist_ok=True)
+                            subfolder_files = self._download_folder_recursive(
+                                item_id,
+                                subfolder_path,
+                                recursive
+                            )
+                            files_downloaded += subfolder_files
+                            logging.info(f"Downloaded {subfolder_files} files from subfolder {item_name}")
+                    else:
+                        # Download file
+                        success = self._download_single_file(item_id, local_dir)
+                        if success:
+                            files_downloaded += 1
+                            logging.info(f"Downloaded file: {item_name}")
+                        else:
+                            logging.warning(f"Failed to download file: {item_name}")
+
+                page_token = results.get('nextPageToken')
+                if not page_token:
+                    break
+
+            return files_downloaded
+
+        except Exception as e:
+            logging.error(f"Error in _download_folder_recursive for folder {folder_id}: {e}", exc_info=True)
+            return files_downloaded
+
+    def _get_extension_for_mime_type(self, mime_type: str) -> str:
+        extensions = {
+            'application/pdf': '.pdf',
+            'text/plain': '.txt',
+            'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+            'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+            'text/html': '.html',
+            'text/markdown': '.md',
+        }
+        return extensions.get(mime_type, '.bin')
+
+    def _download_folder_contents(self, folder_id: str, local_dir: str, recursive: bool = True) -> int:
+        try:
+            self._ensure_service()
+            return self._download_folder_recursive(folder_id, local_dir, recursive)
+        except Exception as e:
+            logging.error(f"Error downloading folder {folder_id}: {e}", exc_info=True)
+            return 0
+
+    def download_to_directory(self, local_dir: str, source_config: dict = None) -> dict:
+        if source_config is None:
+            source_config = {}
+
+        config = source_config if source_config else getattr(self, 'config', {})
+        files_downloaded = 0
+
+        try:
+            folder_ids = config.get('folder_ids', [])
+            file_ids = config.get('file_ids', [])
+            recursive = config.get('recursive', True)
+
+            self._ensure_service()
+
+            if file_ids:
+                if isinstance(file_ids, str):
+                    file_ids = [file_ids]
+
+                for file_id in file_ids:
+                    if self._download_file_to_directory(file_id, local_dir):
+                        files_downloaded += 1
+
+            # Process folders
+            if folder_ids:
+                if isinstance(folder_ids, str):
+                    folder_ids = [folder_ids]
+
+                for folder_id in folder_ids:
+                    try:
+                        folder_metadata = self.service.files().get(
+                            fileId=folder_id,
+                            fields='name'
+                        ).execute()
+                        folder_name = folder_metadata.get('name', '')
+                        folder_path = os.path.join(local_dir, folder_name)
+                        os.makedirs(folder_path, exist_ok=True)
+
+                        folder_files = self._download_folder_recursive(
+                            folder_id,
+                            folder_path,
+                            recursive
+                        )
+                        files_downloaded += folder_files
+                        logging.info(f"Downloaded {folder_files} files from folder {folder_name}")
+                    except Exception as e:
+                        logging.error(f"Error downloading folder {folder_id}: {e}", exc_info=True)
+
+            if not file_ids and not folder_ids:
+                raise ValueError("No folder_ids or file_ids provided for download")
+
+            return {
+                "files_downloaded": files_downloaded,
+                "directory_path": local_dir,
+                "empty_result": files_downloaded == 0,
+                "source_type": "google_drive",
+                "config_used": config
+            }
+
+        except Exception as e:
+            return {
+                "files_downloaded": files_downloaded,
+                "directory_path": local_dir,
+                "empty_result": True,
+                "source_type": "google_drive",
+                "config_used": config,
+                "error": str(e)
+            }

application/parser/embedding_pipeline.py

@@ -6,6 +6,21 @@ from application.core.settings import settings
 from application.vectorstore.vector_creator import VectorCreator
 
 
+def sanitize_content(content: str) -> str:
+    """
+    Remove NUL characters that can cause vector store ingestion to fail.
+    
+    Args:
+        content (str): Raw content that may contain NUL characters
+        
+    Returns:
+        str: Sanitized content with NUL characters removed
+    """
+    if not content:
+        return content
+    return content.replace('\x00', '')
+
+
 @retry(tries=10, delay=60)
 def add_text_to_store_with_retry(store, doc, source_id):
     """
@@ -16,10 +31,13 @@ def add_text_to_store_with_retry(store, doc, source_id):
         source_id: Unique identifier for the source.
     """
     try:
+        # Sanitize content to remove NUL characters that cause ingestion failures
+        doc.page_content = sanitize_content(doc.page_content)
+        
         doc.metadata["source_id"] = str(source_id)
         store.add_texts([doc.page_content], metadatas=[doc.metadata])
     except Exception as e:
-        logging.error(f"Failed to add document with retry: {e}")
+        logging.error(f"Failed to add document with retry: {e}", exc_info=True)
         raise
 
 
@@ -46,7 +64,7 @@ def embed_and_store_documents(docs, folder_name, source_id, task_status):
         store = VectorCreator.create_vectorstore(
             settings.VECTOR_STORE,
             docs_init=docs_init,
-            source_id=folder_name,
+            source_id=source_id,
             embeddings_key=os.getenv("EMBEDDINGS_KEY"),
         )
     else:
@@ -75,7 +93,7 @@ def embed_and_store_documents(docs, folder_name, source_id, task_status):
             # Add document to vector store
             add_text_to_store_with_retry(store, doc, source_id)
         except Exception as e:
-            logging.error(f"Error embedding document {idx}: {e}")
+            logging.error(f"Error embedding document {idx}: {e}", exc_info=True)
             logging.info(f"Saving progress at document {idx} out of {total_docs}")
             store.save_local(folder_name)
             break

application/parser/file/bulk.py

@@ -15,6 +15,7 @@ from application.parser.file.json_parser import JSONParser
 from application.parser.file.pptx_parser import PPTXParser
 from application.parser.file.image_parser import ImageParser
 from application.parser.schema.base import Document
+from application.utils import num_tokens_from_string
 
 DEFAULT_FILE_EXTRACTOR: Dict[str, BaseParser] = {
     ".pdf": PDFParser(),
@@ -141,11 +142,12 @@ class SimpleDirectoryReader(BaseReader):
 
         Returns:
             List[Document]: A list of documents.
-
         """
         data: Union[str, List[str]] = ""
         data_list: List[str] = []
         metadata_list = []
+        self.file_token_counts = {}
+        
         for input_file in self.input_files:
             if input_file.suffix in self.file_extractor:
                 parser = self.file_extractor[input_file.suffix]
@@ -156,24 +158,48 @@ class SimpleDirectoryReader(BaseReader):
                 # do standard read
                 with open(input_file, "r", errors=self.errors) as f:
                     data = f.read()
-            # Prepare metadata for this file
-            if self.file_metadata is not None:
-                file_metadata = self.file_metadata(str(input_file))
+            
+            # Calculate token count for this file
+            if isinstance(data, List):
+                file_tokens = sum(num_tokens_from_string(str(d)) for d in data)
             else:
-                # Provide a default empty metadata
-                file_metadata = {'title': '', 'store': ''}
-                # TODO: Find a case with no metadata and check if breaks anything 
+                file_tokens = num_tokens_from_string(str(data))
+            
+            full_path = str(input_file.resolve())
+            self.file_token_counts[full_path] = file_tokens
+            
+            base_metadata = {
+                'title': input_file.name,
+                'token_count': file_tokens,
+            }
+            
+            if hasattr(self, 'input_dir'):
+                try:
+                    relative_path = str(input_file.relative_to(self.input_dir))
+                    base_metadata['source'] = relative_path
+                except ValueError:
+                    base_metadata['source'] = str(input_file)
+            else:
+                base_metadata['source'] = str(input_file)
+
+            if self.file_metadata is not None:
+                custom_metadata = self.file_metadata(input_file.name)
+                base_metadata.update(custom_metadata)
 
             if isinstance(data, List):
                 # Extend data_list with each item in the data list
                 data_list.extend([str(d) for d in data])
-                # For each item in the data list, add the file's metadata to metadata_list
-                metadata_list.extend([file_metadata for _ in data])
+                metadata_list.extend([base_metadata for _ in data])
             else:
-                # Add the single piece of data to data_list
                 data_list.append(str(data))
-                # Add the file's metadata to metadata_list
-                metadata_list.append(file_metadata)
+                metadata_list.append(base_metadata)
+        
+        # Build directory structure if input_dir is provided
+        if hasattr(self, 'input_dir'):
+            self.directory_structure = self.build_directory_structure(self.input_dir)
+            logging.info("Directory structure built successfully")
+        else:
+            self.directory_structure = {}
 
         if concatenate:
             return [Document("\n".join(data_list))]
@@ -181,3 +207,48 @@ class SimpleDirectoryReader(BaseReader):
             return [Document(d, extra_info=m) for d, m in zip(data_list, metadata_list)]
         else:
             return [Document(d) for d in data_list]
+
+    def build_directory_structure(self, base_path):
+        """Build a dictionary representing the directory structure.
+
+        Args:
+            base_path: The base path to start building the structure from.
+
+        Returns:
+            dict: A nested dictionary representing the directory structure.
+        """
+        import mimetypes
+        
+        def build_tree(path):
+            """Helper function to recursively build the directory tree."""
+            result = {}
+            
+            for item in path.iterdir():
+                if self.exclude_hidden and item.name.startswith('.'):
+                    continue
+                    
+                if item.is_dir():
+                    subtree = build_tree(item)
+                    if subtree:
+                        result[item.name] = subtree
+                else:
+                    if self.required_exts is not None and item.suffix not in self.required_exts:
+                        continue
+                    
+                    full_path = str(item.resolve())
+                    file_size_bytes = item.stat().st_size
+                    mime_type = mimetypes.guess_type(item.name)[0] or "application/octet-stream"
+                    
+                    file_info = {
+                        "type": mime_type,
+                        "size_bytes": file_size_bytes
+                    }
+                    
+                    if hasattr(self, 'file_token_counts') and full_path in self.file_token_counts:
+                        file_info["token_count"] = self.file_token_counts[full_path]
+                        
+                    result[item.name] = file_info
+                    
+            return result
+        
+        return build_tree(Path(base_path))

application/parser/file/image_parser.py

@@ -8,6 +8,7 @@ import requests
 from typing import Dict, Union
 
 from application.parser.file.base_parser import BaseParser
+from application.core.settings import settings
 
 
 class ImageParser(BaseParser):
@@ -18,10 +19,13 @@ class ImageParser(BaseParser):
         return {}
 
     def parse_file(self, file: Path, errors: str = "ignore") -> Union[str, list[str]]:
-        doc2md_service = "https://llm.arc53.com/doc2md"
-        # alternatively you can use local vision capable LLM
-        with open(file, "rb") as file_loaded:
-            files = {'file': file_loaded}
-            response = requests.post(doc2md_service, files=files)   
-            data = response.json()["markdown"] 
+        if settings.PARSE_IMAGE_REMOTE:
+            doc2md_service = "https://llm.arc53.com/doc2md"
+            # alternatively you can use local vision capable LLM
+            with open(file, "rb") as file_loaded:
+                files = {'file': file_loaded}
+                response = requests.post(doc2md_service, files=files)   
+                data = response.json()["markdown"] 
+        else:
+            data = ""
         return data

application/parser/file/tabular_parser.py

@@ -73,7 +73,13 @@ class PandasCSVParser(BaseParser):
             for more information.
             Set to empty dict by default, this means pandas will try to figure
             out the separators, table head, etc. on its own.
-
+            
+        header_period (int): Controls how headers are included in output:
+            - 0: Headers only at the beginning
+            - 1: Headers in every row
+            - N > 1: Headers every N rows
+            
+        header_prefix (str): Prefix for header rows. Default is "HEADERS: ".
     """
 
     def __init__(
@@ -83,6 +89,8 @@ class PandasCSVParser(BaseParser):
             col_joiner: str = ", ",
             row_joiner: str = "\n",
             pandas_config: dict = {},
+            header_period: int = 20,
+            header_prefix: str = "HEADERS: ",
             **kwargs: Any
     ) -> None:
         """Init params."""
@@ -91,6 +99,8 @@ class PandasCSVParser(BaseParser):
         self._col_joiner = col_joiner
         self._row_joiner = row_joiner
         self._pandas_config = pandas_config
+        self._header_period = header_period
+        self._header_prefix = header_prefix
 
     def _init_parser(self) -> Dict:
         """Init parser."""
@@ -104,15 +114,26 @@ class PandasCSVParser(BaseParser):
             raise ValueError("pandas module is required to read CSV files.")
 
         df = pd.read_csv(file, **self._pandas_config)
+        headers = df.columns.tolist()
+        header_row = f"{self._header_prefix}{self._col_joiner.join(headers)}"
 
-        text_list = df.apply(
-            lambda row: (self._col_joiner).join(row.astype(str).tolist()), axis=1
-        ).tolist()
+        if not self._concat_rows:
+            return df.apply(
+                lambda row: (self._col_joiner).join(row.astype(str).tolist()), axis=1
+            ).tolist()
+        
+        text_list = []
+        if self._header_period != 1:
+            text_list.append(header_row)
+        
+        for i, row in df.iterrows():
+            if (self._header_period > 1 and i > 0 and i % self._header_period == 0):
+                text_list.append(header_row)
+            text_list.append(self._col_joiner.join(row.astype(str).tolist()))
+            if self._header_period == 1 and i < len(df) - 1:
+                text_list.append(header_row)
 
-        if self._concat_rows:
-            return (self._row_joiner).join(text_list)
-        else:
-            return text_list
+        return self._row_joiner.join(text_list)
 
 
 class ExcelParser(BaseParser):
@@ -138,7 +159,13 @@ class ExcelParser(BaseParser):
             for more information.
             Set to empty dict by default, this means pandas will try to figure
             out the table structure on its own.
-
+            
+        header_period (int): Controls how headers are included in output:
+            - 0: Headers only at the beginning (default)
+            - 1: Headers in every row
+            - N > 1: Headers every N rows
+            
+        header_prefix (str): Prefix for header rows. Default is "HEADERS: ".
     """
 
     def __init__(
@@ -148,6 +175,8 @@ class ExcelParser(BaseParser):
             col_joiner: str = ", ",
             row_joiner: str = "\n",
             pandas_config: dict = {},
+            header_period: int = 20,
+            header_prefix: str = "HEADERS: ",
             **kwargs: Any
     ) -> None:
         """Init params."""
@@ -156,6 +185,8 @@ class ExcelParser(BaseParser):
         self._col_joiner = col_joiner
         self._row_joiner = row_joiner
         self._pandas_config = pandas_config
+        self._header_period = header_period
+        self._header_prefix = header_prefix
 
     def _init_parser(self) -> Dict:
         """Init parser."""
@@ -169,12 +200,22 @@ class ExcelParser(BaseParser):
             raise ValueError("pandas module is required to read Excel files.")
 
         df = pd.read_excel(file, **self._pandas_config)
+        headers = df.columns.tolist()
+        header_row = f"{self._header_prefix}{self._col_joiner.join(headers)}"
+        
+        if not self._concat_rows:
+            return df.apply(
+                lambda row: (self._col_joiner).join(row.astype(str).tolist()), axis=1
+            ).tolist()
+        
+        text_list = []
+        if self._header_period != 1:
+            text_list.append(header_row)
 
-        text_list = df.apply(
-            lambda row: (self._col_joiner).join(row.astype(str).tolist()), axis=1
-        ).tolist()
-
-        if self._concat_rows:
-            return (self._row_joiner).join(text_list)
-        else:
-            return text_list
+        for i, row in df.iterrows():
+            if (self._header_period > 1 and i > 0 and i % self._header_period == 0):
+                text_list.append(header_row)
+            text_list.append(self._col_joiner.join(row.astype(str).tolist()))
+            if self._header_period == 1 and i < len(df) - 1:
+                text_list.append(header_row)
+        return self._row_joiner.join(text_list)

application/parser/remote/crawler_loader.py

@@ -1,3 +1,4 @@
+import logging
 import requests
 from urllib.parse import urlparse, urljoin
 from bs4 import BeautifulSoup
@@ -42,7 +43,7 @@ class CrawlerLoader(BaseRemote):
                         )
                     )
             except Exception as e:
-                print(f"Error processing URL {current_url}: {e}")
+                logging.error(f"Error processing URL {current_url}: {e}", exc_info=True)
                 continue
 
             # Parse the HTML content to extract all links
@@ -61,4 +62,4 @@ class CrawlerLoader(BaseRemote):
             if self.limit is not None and len(visited_urls) >= self.limit:
                 break
 
-        return loaded_content
+        return loaded_content

application/parser/remote/remote_creator.py

@@ -6,6 +6,16 @@ from application.parser.remote.github_loader import GitHubLoader
 
 
 class RemoteCreator:
+    """
+    Factory class for creating remote content loaders.
+
+    These loaders fetch content from remote web sources like URLs,
+    sitemaps, web crawlers, social media platforms, etc.
+
+    For external knowledge base connectors (like Google Drive),
+    use ConnectorCreator instead.
+    """
+
     loaders = {
         "url": WebLoader,
         "sitemap": SitemapLoader,
@@ -18,5 +28,5 @@ class RemoteCreator:
     def create_loader(cls, type, *args, **kwargs):
         loader_class = cls.loaders.get(type.lower())
         if not loader_class:
-            raise ValueError(f"No LLM class found for type {type}")
+            raise ValueError(f"No loader class found for type {type}")
         return loader_class(*args, **kwargs)

application/parser/remote/sitemap_loader.py

@@ -1,3 +1,4 @@
+import logging
 import requests
 import re  # Import regular expression library
 import xml.etree.ElementTree as ET
@@ -32,7 +33,7 @@ class SitemapLoader(BaseRemote):
                 documents.extend(loader.load())
                 processed_urls += 1  # Increment the counter after processing each URL
             except Exception as e:
-                print(f"Error processing URL {url}: {e}")
+                logging.error(f"Error processing URL {url}: {e}", exc_info=True)
                 continue
 
         return documents

application/parser/remote/web_loader.py

@@ -1,3 +1,4 @@
+import logging
 from application.parser.remote.base import BaseRemote
 from application.parser.schema.base import Document
 from langchain_community.document_loaders import WebBaseLoader
@@ -39,6 +40,6 @@ class WebLoader(BaseRemote):
                         )
                     )
             except Exception as e:
-                print(f"Error processing URL {url}: {e}")
+                logging.error(f"Error processing URL {url}: {e}", exc_info=True)
                 continue
-        return documents
+        return documents

application/prompts/chat_combine_creative.txt

@@ -1,9 +1,15 @@
-You are a DocsGPT, friendly and helpful AI assistant by Arc53 that provides help with documents. You give thorough answers with code examples if possible.
-Use the following pieces of context to help answer the users question. If its not relevant to the question, provide friendly responses.
-You have access to chat history, and can use it to help answer the question.
-When using code examples, use the following format:
+You are a helpful AI assistant, DocsGPT. You are proactive and helpful. Try to use tools, if they are available to you, 
+be proactive and fill in missing information.
+Users can Upload documents for your context as attachments or sources via UI using the Conversation input box.
+If appropriate, your answers can include code examples, formatted as follows:
 ```(language)
 (code)
 ```
+Users are also able to see charts and diagrams if you use them with valid mermaid syntax in your responses.
+Try to respond with mermaid charts if visualization helps with users queries.
+You effectively utilize chat history, ensuring relevant and tailored responses. 
+Try to use additional provided context if it's available, otherwise use your knowledge and tool capabilities.
+Allow yourself to be very creative and use your imagination.
 ----------------
+Possible additional context from uploaded sources:
 {summaries}

application/prompts/chat_combine_default.txt

@@ -1,9 +1,14 @@
-You are a helpful AI assistant, DocsGPT, specializing in document assistance, designed to offer detailed and informative responses. 
+You are a helpful AI assistant, DocsGPT. You are proactive and helpful. Try to use tools, if they are available to you, 
+be proactive and fill in missing information.
+Users can Upload documents for your context as attachments or sources via UI using the Conversation input box.
 If appropriate, your answers can include code examples, formatted as follows:
 ```(language)
 (code)
 ```
+Users are also able to see charts and diagrams if you use them with valid mermaid syntax in your responses.
+Try to respond with mermaid charts if visualization helps with users queries.
 You effectively utilize chat history, ensuring relevant and tailored responses. 
-If a question doesn't align with your context, you provide friendly and helpful replies.
+Try to use additional provided context if it's available, otherwise use your knowledge and tool capabilities.
 ----------------
+Possible additional context from uploaded sources:
 {summaries}

application/prompts/chat_combine_strict.txt

@@ -1,13 +1,17 @@
-You are an AI Assistant, DocsGPT, adept at offering document assistance. 
-Your expertise lies in providing answer on top of provided context. 
-You can leverage the chat history if needed.
-Answer the question based on the context below. 
-Keep the answer concise. Respond "Irrelevant context" if not sure about the answer.
-If question is not related to the context, respond "Irrelevant context".
-When using code examples, use the following format:
+You are a helpful AI assistant, DocsGPT. You are proactive and helpful. Try to use tools, if they are available to you, 
+be proactive and fill in missing information.
+Users can Upload documents for your context as attachments or sources via UI using the Conversation input box.
+If appropriate, your answers can include code examples, formatted as follows:
 ```(language)
 (code)
 ```
- ----------------
- Context:
- {summaries}
+Users are also able to see charts and diagrams if you use them with valid mermaid syntax in your responses.
+Try to respond with mermaid charts if visualization helps with users queries.
+You effectively utilize chat history, ensuring relevant and tailored responses. 
+Use context provided below or use available tools tool capabilities to answer user queries.
+If you dont have enough information from the context or tools, answer "I don't know" or "I don't have enough information".
+Never make up information or provide false information!
+Allow yourself to be very creative and use your imagination.
+----------------
+Context from uploaded sources:
+{summaries}

application/prompts/react_final_prompt.txt

@@ -0,0 +1,3 @@
+Query: {query}
+Observations: {observations}
+Now, using the insights from the observations, formulate a well-structured and precise final answer.

application/prompts/react_planning_prompt.txt

@@ -0,0 +1,13 @@
+You are an AI assistant and talk like you're thinking out loud. Given the following query, outline a concise thought process that includes key steps and considerations necessary for effective analysis and response. Avoid pointwise formatting. The goal is to break down the query into manageable components without excessive detail, focusing on clarity and logical progression.
+
+Include the following elements in your thought and execution process:
+1. Identify the main objective of the query.
+2. Determine any relevant context or background information needed to understand the query.
+3. List potential approaches or methods to address the query.
+4. Highlight any critical factors or constraints that may influence the outcome.
+5. Plan with available tools to help you with the analysis but dont execute them. Tools will be executed by another AI.
+
+Query: {query}  
+Summaries: {summaries}
+Prompt: {prompt}
+Observations(potentially previous tool calls): {observations}

application/requirements.txt

@@ -1,25 +1,25 @@
 anthropic==0.49.0
-boto3==1.35.97
-beautifulsoup4==4.12.3
+boto3==1.38.18
+beautifulsoup4==4.13.4
 celery==5.4.0
+cryptography==42.0.8
 dataclasses-json==0.6.7
 docx2txt==0.8
 duckduckgo-search==7.5.2
 ebooklib==0.18
-elastic-transport==8.17.0
-elasticsearch==8.17.1
 escodegen==1.0.11
 esprima==4.0.1
 esutils==1.0.1
-Flask==3.1.0
+Flask==3.1.1
 faiss-cpu==1.9.0.post1
+fastmcp==2.11.0
 flask-restx==1.3.0
-gevent==24.11.1
 google-genai==1.3.0
-google-generativeai==0.8.3
+google-api-python-client==2.179.0
+google-auth-httplib2==0.2.0
+google-auth-oauthlib==1.2.2
 gTTS==2.5.4
 gunicorn==23.0.0
-html2text==2024.2.26
 javalang==0.13.0
 jinja2==3.1.6
 jiter==0.8.2
@@ -27,71 +27,64 @@ jmespath==1.0.1
 joblib==1.4.2
 jsonpatch==1.33
 jsonpointer==3.0.0
-jsonschema==4.23.0
-jsonschema-spec==0.2.4
-jsonschema-specifications==2023.7.1
 kombu==5.4.2
 langchain==0.3.20
 langchain-community==0.3.19
-langchain-core==0.3.45
-langchain-openai==0.3.8
-langchain-text-splitters==0.3.6
-langsmith==0.3.15
+langchain-core==0.3.59
+langchain-openai==0.3.16
+langchain-text-splitters==0.3.8
+langsmith==0.3.42
 lazy-object-proxy==1.10.0
 lxml==5.3.1
 markupsafe==3.0.2
 marshmallow==3.26.1
 mpmath==1.3.0
-multidict==6.1.0
+multidict==6.4.3
 mypy-extensions==1.0.0
 networkx==3.4.2
 numpy==2.2.1
-openai==1.66.3
-openapi-schema-validator==0.6.3
-openapi-spec-validator==0.6.0
-openapi3-parser==1.1.19
+openai==1.78.1
+openapi3-parser==1.1.21
 orjson==3.10.14
-packaging==24.1
+packaging==24.2
 pandas==2.2.3
 openpyxl==3.1.5
 pathable==0.4.4
 pillow==11.1.0
-portalocker==2.10.1
+portalocker>=2.7.0,<3.0.0
 prance==23.6.21.0
-primp==0.14.0
-prompt-toolkit==3.0.50
+prompt-toolkit==3.0.51
 protobuf==5.29.3
 psycopg2-binary==2.9.10
 py==1.11.0
-pydantic==2.10.6
-pydantic-core==2.27.2
-pydantic-settings==2.7.1
-pymongo==4.10.1
-pypdf==5.2.0
+pydantic
+pydantic-core
+pydantic-settings
+pymongo==4.11.3
+pypdf==5.5.0
 python-dateutil==2.9.0.post0
-python-dotenv==1.0.1
+python-dotenv
 python-jose==3.4.0
 python-pptx==1.0.2
-qdrant-client==1.13.2
 redis==5.2.1
-referencing==0.30.2
+referencing>=0.28.0,<0.31.0
 regex==2024.11.6
 requests==2.32.3
 retry==0.9.2
 sentence-transformers==3.3.1
 tiktoken==0.8.0
 tokenizers==0.21.0
-torch==2.5.1
+torch==2.7.0
 tqdm==4.67.1
-transformers==4.49.0
+transformers==4.51.3
 typing-extensions==4.12.2
 typing-inspect==0.9.0
 tzdata==2024.2
 urllib3==2.3.0
 vine==5.1.0
 wcwidth==0.2.13
-werkzeug==3.1.3
-yarl==1.18.3
-markdownify==0.14.1
+werkzeug>=3.1.0,<3.1.2
+yarl==1.20.0
+markdownify==1.1.0
 tldextract==5.1.3
 websockets==14.1

application/retriever/base.py

@@ -5,10 +5,6 @@ class BaseRetriever(ABC):
     def __init__(self):
         pass
 
-    @abstractmethod
-    def gen(self, *args, **kwargs):
-        pass
-
     @abstractmethod
     def search(self, *args, **kwargs):
         pass

application/retriever/brave_search.py

@@ -1,112 +0,0 @@
-import json
-
-from langchain_community.tools import BraveSearch
-
-from application.core.settings import settings
-from application.llm.llm_creator import LLMCreator
-from application.retriever.base import BaseRetriever
-
-
-class BraveRetSearch(BaseRetriever):
-
-    def __init__(
-        self,
-        source,
-        chat_history,
-        prompt,
-        chunks=2,
-        token_limit=150,
-        gpt_model="docsgpt",
-        user_api_key=None,
-        decoded_token=None,
-    ):
-        self.question = ""
-        self.source = source
-        self.chat_history = chat_history
-        self.prompt = prompt
-        self.chunks = chunks
-        self.gpt_model = gpt_model
-        self.token_limit = (
-            token_limit
-            if token_limit
-            < settings.MODEL_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-            else settings.MODEL_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-        )
-        self.user_api_key = user_api_key
-        self.decoded_token = decoded_token
-
-    def _get_data(self):
-        if self.chunks == 0:
-            docs = []
-        else:
-            search = BraveSearch.from_api_key(
-                api_key=settings.BRAVE_SEARCH_API_KEY,
-                search_kwargs={"count": int(self.chunks)},
-            )
-            results = search.run(self.question)
-            results = json.loads(results)
-
-            docs = []
-            for i in results:
-                try:
-                    title = i["title"]
-                    link = i["link"]
-                    snippet = i["snippet"]
-                    docs.append({"text": snippet, "title": title, "link": link})
-                except IndexError:
-                    pass
-        if settings.LLM_NAME == "llama.cpp":
-            docs = [docs[0]]
-
-        return docs
-
-    def gen(self):
-        docs = self._get_data()
-
-        # join all page_content together with a newline
-        docs_together = "\n".join([doc["text"] for doc in docs])
-        p_chat_combine = self.prompt.replace("{summaries}", docs_together)
-        messages_combine = [{"role": "system", "content": p_chat_combine}]
-        for doc in docs:
-            yield {"source": doc}
-
-        if len(self.chat_history) > 0:
-            for i in self.chat_history:
-                if "prompt" in i and "response" in i:
-                    messages_combine.append({"role": "user", "content": i["prompt"]})
-                    messages_combine.append(
-                        {"role": "assistant", "content": i["response"]}
-                    )
-        messages_combine.append({"role": "user", "content": self.question})
-
-        llm = LLMCreator.create_llm(
-            settings.LLM_NAME,
-            api_key=settings.API_KEY,
-            user_api_key=self.user_api_key,
-            decoded_token=self.decoded_token,
-        )
-
-        completion = llm.gen_stream(model=self.gpt_model, messages=messages_combine)
-        for line in completion:
-            yield {"answer": str(line)}
-
-    def search(self, query: str = ""):
-        if query:
-            self.question = query
-        return self._get_data()
-
-    def get_params(self):
-        return {
-            "question": self.question,
-            "source": self.source,
-            "chat_history": self.chat_history,
-            "prompt": self.prompt,
-            "chunks": self.chunks,
-            "token_limit": self.token_limit,
-            "gpt_model": self.gpt_model,
-            "user_api_key": self.user_api_key,
-        }

application/retriever/classic_rag.py

@@ -1,3 +1,6 @@
+import logging
+import os
+
 from application.core.settings import settings
 from application.llm.llm_creator import LLMCreator
 from application.retriever.base import BaseRetriever
@@ -15,22 +18,32 @@ class ClassicRAG(BaseRetriever):
         token_limit=150,
         gpt_model="docsgpt",
         user_api_key=None,
-        llm_name=settings.LLM_NAME,
+        llm_name=settings.LLM_PROVIDER,
         api_key=settings.API_KEY,
         decoded_token=None,
     ):
-        self.original_question = ""
+        """Initialize ClassicRAG retriever with vectorstore sources and LLM configuration"""
+        self.original_question = source.get("question", "")
         self.chat_history = chat_history if chat_history is not None else []
         self.prompt = prompt
-        self.chunks = chunks
+        if isinstance(chunks, str):
+            try:
+                self.chunks = int(chunks)
+            except ValueError:
+                logging.warning(
+                    f"Invalid chunks value '{chunks}', using default value 2"
+                )
+                self.chunks = 2
+        else:
+            self.chunks = chunks
         self.gpt_model = gpt_model
         self.token_limit = (
             token_limit
             if token_limit
-            < settings.MODEL_TOKEN_LIMITS.get(
+            < settings.LLM_TOKEN_LIMITS.get(
                 self.gpt_model, settings.DEFAULT_MAX_HISTORY
             )
-            else settings.MODEL_TOKEN_LIMITS.get(
+            else settings.LLM_TOKEN_LIMITS.get(
                 self.gpt_model, settings.DEFAULT_MAX_HISTORY
             )
         )
@@ -43,23 +56,52 @@ class ClassicRAG(BaseRetriever):
             user_api_key=self.user_api_key,
             decoded_token=decoded_token,
         )
+
+        if "active_docs" in source and source["active_docs"] is not None:
+            if isinstance(source["active_docs"], list):
+                self.vectorstores = source["active_docs"]
+            else:
+                self.vectorstores = [source["active_docs"]]
+        else:
+            self.vectorstores = []
         self.question = self._rephrase_query()
-        self.vectorstore = source["active_docs"] if "active_docs" in source else None
         self.decoded_token = decoded_token
+        self._validate_vectorstore_config()
+
+    def _validate_vectorstore_config(self):
+        """Validate vectorstore IDs and remove any empty/invalid entries"""
+        if not self.vectorstores:
+            logging.warning("No vectorstores configured for retrieval")
+            return
+        invalid_ids = [
+            vs_id for vs_id in self.vectorstores if not vs_id or not vs_id.strip()
+        ]
+        if invalid_ids:
+            logging.warning(f"Found invalid vectorstore IDs: {invalid_ids}")
+            self.vectorstores = [
+                vs_id for vs_id in self.vectorstores if vs_id and vs_id.strip()
+            ]
 
     def _rephrase_query(self):
+        """Rephrase user query with chat history context for better retrieval"""
         if (
             not self.original_question
             or not self.chat_history
             or self.chat_history == []
+            or self.chunks == 0
+            or not self.vectorstores
         ):
             return self.original_question
-
         prompt = f"""Given the following conversation history:
+
         {self.chat_history}
 
+
+
         Rephrase the following user question to be a standalone search query 
+
         that captures all relevant context from the conversation:
+
         """
 
         messages = [
@@ -72,48 +114,79 @@ class ClassicRAG(BaseRetriever):
             print(f"Rephrased query: {rephrased_query}")
             return rephrased_query if rephrased_query else self.original_question
         except Exception as e:
-            print(f"Error rephrasing query: {e}")
+            logging.error(f"Error rephrasing query: {e}", exc_info=True)
             return self.original_question
 
     def _get_data(self):
-        if self.chunks == 0:
-            docs = []
-        else:
-            docsearch = VectorCreator.create_vectorstore(
-                settings.VECTOR_STORE, self.vectorstore, settings.EMBEDDINGS_KEY
-            )
-            docs_temp = docsearch.search(self.question, k=self.chunks)
-            docs = [
-                {
-                    "title": i.metadata.get(
-                        "title", i.metadata.get("post_title", i.page_content)
-                    ).split("/")[-1],
-                    "text": i.page_content,
-                    "source": (
-                        i.metadata.get("source")
-                        if i.metadata.get("source")
-                        else "local"
-                    ),
-                }
-                for i in docs_temp
-            ]
+        """Retrieve relevant documents from configured vectorstores"""
+        if self.chunks == 0 or not self.vectorstores:
+            return []
+        all_docs = []
+        chunks_per_source = max(1, self.chunks // len(self.vectorstores))
 
-        return docs
+        for vectorstore_id in self.vectorstores:
+            if vectorstore_id:
+                try:
+                    docsearch = VectorCreator.create_vectorstore(
+                        settings.VECTOR_STORE, vectorstore_id, settings.EMBEDDINGS_KEY
+                    )
+                    docs_temp = docsearch.search(self.question, k=chunks_per_source)
 
-    def gen():
-        pass
+                    for doc in docs_temp:
+                        if hasattr(doc, "page_content") and hasattr(doc, "metadata"):
+                            page_content = doc.page_content
+                            metadata = doc.metadata
+                        else:
+                            page_content = doc.get("text", doc.get("page_content", ""))
+                            metadata = doc.get("metadata", {})
+                        title = metadata.get(
+                            "title", metadata.get("post_title", page_content)
+                        )
+                        if not isinstance(title, str):
+                            title = str(title)
+                        title = title.split("/")[-1]
+
+                        filename = (
+                            metadata.get("filename")
+                            or metadata.get("file_name")
+                            or metadata.get("source")
+                        )
+                        if isinstance(filename, str):
+                            filename = os.path.basename(filename) or filename
+                        else:
+                            filename = title
+                        if not filename:
+                            filename = title
+                        source_path = metadata.get("source") or vectorstore_id
+                        all_docs.append(
+                            {
+                                "title": title,
+                                "text": page_content,
+                                "source": source_path,
+                                "filename": filename,
+                            }
+                        )
+                except Exception as e:
+                    logging.error(
+                        f"Error searching vectorstore {vectorstore_id}: {e}",
+                        exc_info=True,
+                    )
+                    continue
+        return all_docs
 
     def search(self, query: str = ""):
+        """Search for documents using optional query override"""
         if query:
             self.original_question = query
             self.question = self._rephrase_query()
         return self._get_data()
 
     def get_params(self):
+        """Return current retriever configuration parameters"""
         return {
             "question": self.original_question,
             "rephrased_question": self.question,
-            "source": self.vectorstore,
+            "sources": self.vectorstores,
             "chunks": self.chunks,
             "token_limit": self.token_limit,
             "gpt_model": self.gpt_model,

application/retriever/duckduck_search.py

@@ -1,111 +0,0 @@
-from langchain_community.tools import DuckDuckGoSearchResults
-from langchain_community.utilities import DuckDuckGoSearchAPIWrapper
-
-from application.core.settings import settings
-from application.llm.llm_creator import LLMCreator
-from application.retriever.base import BaseRetriever
-
-
-class DuckDuckSearch(BaseRetriever):
-
-    def __init__(
-        self,
-        source,
-        chat_history,
-        prompt,
-        chunks=2,
-        token_limit=150,
-        gpt_model="docsgpt",
-        user_api_key=None,
-        decoded_token=None,
-    ):
-        self.question = ""
-        self.source = source
-        self.chat_history = chat_history
-        self.prompt = prompt
-        self.chunks = chunks
-        self.gpt_model = gpt_model
-        self.token_limit = (
-            token_limit
-            if token_limit
-            < settings.MODEL_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-            else settings.MODEL_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-        )
-        self.user_api_key = user_api_key
-        self.decoded_token = decoded_token
-
-    def _get_data(self):
-        if self.chunks == 0:
-            docs = []
-        else:
-            wrapper = DuckDuckGoSearchAPIWrapper(max_results=self.chunks)
-            search = DuckDuckGoSearchResults(api_wrapper=wrapper, output_format="list")
-            results = search.run(self.question)
-
-            docs = []
-            for i in results:
-                try:
-                    docs.append(
-                        {
-                            "text": i.get("snippet", "").strip(),
-                            "title": i.get("title", "").strip(),
-                            "link": i.get("link", "").strip(),
-                        }
-                    )
-                except IndexError:
-                    pass
-        if settings.LLM_NAME == "llama.cpp":
-            docs = [docs[0]]
-
-        return docs
-
-    def gen(self):
-        docs = self._get_data()
-
-        # join all page_content together with a newline
-        docs_together = "\n".join([doc["text"] for doc in docs])
-        p_chat_combine = self.prompt.replace("{summaries}", docs_together)
-        messages_combine = [{"role": "system", "content": p_chat_combine}]
-        for doc in docs:
-            yield {"source": doc}
-
-        if len(self.chat_history) > 0:
-            for i in self.chat_history:
-                if "prompt" in i and "response" in i:
-                    messages_combine.append({"role": "user", "content": i["prompt"]})
-                    messages_combine.append(
-                        {"role": "assistant", "content": i["response"]}
-                    )
-        messages_combine.append({"role": "user", "content": self.question})
-
-        llm = LLMCreator.create_llm(
-            settings.LLM_NAME,
-            api_key=settings.API_KEY,
-            user_api_key=self.user_api_key,
-            decoded_token=self.decoded_token,
-        )
-
-        completion = llm.gen_stream(model=self.gpt_model, messages=messages_combine)
-        for line in completion:
-            yield {"answer": str(line)}
-
-    def search(self, query: str = ""):
-        if query:
-            self.question = query
-        return self._get_data()
-
-    def get_params(self):
-        return {
-            "question": self.question,
-            "source": self.source,
-            "chat_history": self.chat_history,
-            "prompt": self.prompt,
-            "chunks": self.chunks,
-            "token_limit": self.token_limit,
-            "gpt_model": self.gpt_model,
-            "user_api_key": self.user_api_key,
-        }

application/retriever/retriever_creator.py

@@ -1,20 +1,16 @@
 from application.retriever.classic_rag import ClassicRAG
-from application.retriever.duckduck_search import DuckDuckSearch
-from application.retriever.brave_search import BraveRetSearch
-
 
 
 class RetrieverCreator:
     retrievers = {
-        'classic': ClassicRAG,
-        'duckduck_search': DuckDuckSearch,
-        'brave_search': BraveRetSearch,
-        'default': ClassicRAG
+        "classic": ClassicRAG,
+        "default": ClassicRAG,
     }
 
     @classmethod
     def create_retriever(cls, type, *args, **kwargs):
-        retiever_class = cls.retrievers.get(type.lower())
+        retriever_type = (type or "default").lower()
+        retiever_class = cls.retrievers.get(retriever_type)
         if not retiever_class:
             raise ValueError(f"No retievers class found for type {type}")
-        return retiever_class(*args, **kwargs)
+        return retiever_class(*args, **kwargs)

application/security/encryption.py

@@ -0,0 +1,85 @@
+import base64
+import json
+import os
+
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers import algorithms, Cipher, modes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from application.core.settings import settings
+
+
+def _derive_key(user_id: str, salt: bytes) -> bytes:
+    app_secret = settings.ENCRYPTION_SECRET_KEY
+
+    password = f"{app_secret}#{user_id}".encode()
+
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=100000,
+        backend=default_backend(),
+    )
+
+    return kdf.derive(password)
+
+
+def encrypt_credentials(credentials: dict, user_id: str) -> str:
+    if not credentials:
+        return ""
+    try:
+        salt = os.urandom(16)
+        iv = os.urandom(16)
+        key = _derive_key(user_id, salt)
+
+        json_str = json.dumps(credentials)
+
+        cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=default_backend())
+        encryptor = cipher.encryptor()
+
+        padded_data = _pad_data(json_str.encode())
+        encrypted_data = encryptor.update(padded_data) + encryptor.finalize()
+
+        result = salt + iv + encrypted_data
+        return base64.b64encode(result).decode()
+    except Exception as e:
+        print(f"Warning: Failed to encrypt credentials: {e}")
+        return ""
+
+
+def decrypt_credentials(encrypted_data: str, user_id: str) -> dict:
+    if not encrypted_data:
+        return {}
+    try:
+        data = base64.b64decode(encrypted_data.encode())
+
+        salt = data[:16]
+        iv = data[16:32]
+        encrypted_content = data[32:]
+
+        key = _derive_key(user_id, salt)
+
+        cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=default_backend())
+        decryptor = cipher.decryptor()
+
+        decrypted_padded = decryptor.update(encrypted_content) + decryptor.finalize()
+        decrypted_data = _unpad_data(decrypted_padded)
+
+        return json.loads(decrypted_data.decode())
+    except Exception as e:
+        print(f"Warning: Failed to decrypt credentials: {e}")
+        return {}
+
+
+def _pad_data(data: bytes) -> bytes:
+    block_size = 16
+    padding_len = block_size - (len(data) % block_size)
+    padding = bytes([padding_len]) * padding_len
+    return data + padding
+
+
+def _unpad_data(data: bytes) -> bytes:
+    padding_len = data[-1]
+    return data[:-padding_len]

application/storage/base.py

@@ -0,0 +1,124 @@
+"""Base storage class for file system abstraction."""
+
+from abc import ABC, abstractmethod
+from typing import BinaryIO, List, Callable
+
+
+class BaseStorage(ABC):
+    """Abstract base class for storage implementations."""
+
+    @abstractmethod
+    def save_file(self, file_data: BinaryIO, path: str, **kwargs) -> dict:
+        """
+        Save a file to storage.
+
+        Args:
+            file_data: File-like object containing the data
+            path: Path where the file should be stored
+
+        Returns:
+            dict: A dictionary containing metadata about the saved file, including:
+                - 'path': The path where the file was saved
+                - 'storage_type': The type of storage (e.g., 'local', 's3')
+                - Other storage-specific metadata (e.g., 'uri', 'bucket_name', etc.)
+        """
+        pass
+
+    @abstractmethod
+    def get_file(self, path: str) -> BinaryIO:
+        """
+        Retrieve a file from storage.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            BinaryIO: File-like object containing the file data
+        """
+        pass
+
+    @abstractmethod
+    def process_file(self, path: str, processor_func: Callable, **kwargs):
+        """
+        Process a file using the provided processor function.
+
+        This method handles the details of retrieving the file and providing
+        it to the processor function in an appropriate way based on the storage type.
+
+        Args:
+            path: Path to the file
+            processor_func: Function that processes the file
+            **kwargs: Additional arguments to pass to the processor function
+
+        Returns:
+            The result of the processor function
+        """
+        pass
+
+    @abstractmethod
+    def delete_file(self, path: str) -> bool:
+        """
+        Delete a file from storage.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            bool: True if deletion was successful
+        """
+        pass
+
+    @abstractmethod
+    def file_exists(self, path: str) -> bool:
+        """
+        Check if a file exists.
+
+        Args:
+            path: Path to the file
+
+        Returns:
+            bool: True if the file exists
+        """
+        pass
+
+    @abstractmethod
+    def list_files(self, directory: str) -> List[str]:
+        """
+        List all files in a directory.
+
+        Args:
+            directory: Directory path to list
+
+        Returns:
+            List[str]: List of file paths
+        """
+        pass
+        
+    @abstractmethod
+    def is_directory(self, path: str) -> bool:
+        """
+        Check if a path is a directory.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            bool: True if the path is a directory
+        """
+        pass
+
+    @abstractmethod
+    def remove_directory(self, directory: str) -> bool:
+        """
+        Remove a directory and all its contents.
+
+        For local storage, this removes the directory and all files/subdirectories within it.
+        For S3 storage, this removes all objects with the directory path as a prefix.
+
+        Args:
+            directory: Directory path to remove
+
+        Returns:
+            bool: True if removal was successful, False otherwise
+        """
+        pass

application/storage/local.py

@@ -0,0 +1,140 @@
+"""Local file system implementation."""
+import os
+import shutil
+from typing import BinaryIO, List, Callable
+
+from application.storage.base import BaseStorage
+
+
+class LocalStorage(BaseStorage):
+    """Local file system storage implementation."""
+
+    def __init__(self, base_dir: str = None):
+        """
+        Initialize local storage.
+
+        Args:
+            base_dir: Base directory for all operations. If None, uses current directory.
+        """
+        self.base_dir = base_dir or os.path.dirname(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        )
+
+    def _get_full_path(self, path: str) -> str:
+        """Get absolute path by combining base_dir and path."""
+        if os.path.isabs(path):
+            return path
+        return os.path.join(self.base_dir, path)
+
+    def save_file(self, file_data: BinaryIO, path: str) -> dict:
+        """Save a file to local storage."""
+        full_path = self._get_full_path(path)
+
+        os.makedirs(os.path.dirname(full_path), exist_ok=True)
+
+        if hasattr(file_data, 'save'):
+            file_data.save(full_path)
+        else:
+            with open(full_path, 'wb') as f:
+                shutil.copyfileobj(file_data, f)
+
+        return {
+            'storage_type': 'local'
+        }
+
+    def get_file(self, path: str) -> BinaryIO:
+        """Get a file from local storage."""
+        full_path = self._get_full_path(path)
+
+        if not os.path.exists(full_path):
+            raise FileNotFoundError(f"File not found: {full_path}")
+
+        return open(full_path, 'rb')
+
+    def delete_file(self, path: str) -> bool:
+        """Delete a file from local storage."""
+        full_path = self._get_full_path(path)
+
+        if not os.path.exists(full_path):
+            return False
+
+        os.remove(full_path)
+        return True
+
+    def file_exists(self, path: str) -> bool:
+        """Check if a file exists in local storage."""
+        full_path = self._get_full_path(path)
+        return os.path.exists(full_path)
+
+    def list_files(self, directory: str) -> List[str]:
+        """List all files in a directory in local storage."""
+        full_path = self._get_full_path(directory)
+
+        if not os.path.exists(full_path):
+            return []
+
+        result = []
+        for root, _, files in os.walk(full_path):
+            for file in files:
+                rel_path = os.path.relpath(os.path.join(root, file), self.base_dir)
+                result.append(rel_path)
+
+        return result
+
+    def process_file(self, path: str, processor_func: Callable, **kwargs):
+        """
+        Process a file using the provided processor function.
+
+        For local storage, we can directly pass the full path to the processor.
+
+        Args:
+            path: Path to the file
+            processor_func: Function that processes the file
+            **kwargs: Additional arguments to pass to the processor function
+
+        Returns:
+            The result of the processor function
+        """
+        full_path = self._get_full_path(path)
+
+        if not os.path.exists(full_path):
+            raise FileNotFoundError(f"File not found: {full_path}")
+
+        return processor_func(local_path=full_path, **kwargs)
+
+    def is_directory(self, path: str) -> bool:
+        """
+        Check if a path is a directory in local storage.
+        
+        Args:
+            path: Path to check
+        
+        Returns:
+            bool: True if the path is a directory, False otherwise
+        """
+        full_path = self._get_full_path(path)
+        return os.path.isdir(full_path)
+
+    def remove_directory(self, directory: str) -> bool:
+        """
+        Remove a directory and all its contents from local storage.
+
+        Args:
+            directory: Directory path to remove
+
+        Returns:
+            bool: True if removal was successful, False otherwise
+        """
+        full_path = self._get_full_path(directory)
+
+        if not os.path.exists(full_path):
+            return False
+
+        if not os.path.isdir(full_path):
+            return False
+
+        try:
+            shutil.rmtree(full_path)
+            return True
+        except (OSError, PermissionError):
+            return False

application/storage/s3.py

@@ -0,0 +1,206 @@
+"""S3 storage implementation."""
+
+import io
+import os
+from typing import BinaryIO, Callable, List
+
+import boto3
+from application.core.settings import settings
+
+from application.storage.base import BaseStorage
+from botocore.exceptions import ClientError
+
+
+class S3Storage(BaseStorage):
+    """AWS S3 storage implementation."""
+
+    def __init__(self, bucket_name=None):
+        """
+        Initialize S3 storage.
+
+        Args:
+            bucket_name: S3 bucket name (optional, defaults to settings)
+        """
+        self.bucket_name = bucket_name or getattr(
+            settings, "S3_BUCKET_NAME", "docsgpt-test-bucket"
+        )
+
+        # Get credentials from settings
+
+        aws_access_key_id = getattr(settings, "SAGEMAKER_ACCESS_KEY", None)
+        aws_secret_access_key = getattr(settings, "SAGEMAKER_SECRET_KEY", None)
+        region_name = getattr(settings, "SAGEMAKER_REGION", None)
+
+        self.s3 = boto3.client(
+            "s3",
+            aws_access_key_id=aws_access_key_id,
+            aws_secret_access_key=aws_secret_access_key,
+            region_name=region_name,
+        )
+
+    def save_file(
+        self,
+        file_data: BinaryIO,
+        path: str,
+        storage_class: str = "INTELLIGENT_TIERING",
+        **kwargs,
+    ) -> dict:
+        """Save a file to S3 storage."""
+        self.s3.upload_fileobj(
+            file_data, self.bucket_name, path, ExtraArgs={"StorageClass": storage_class}
+        )
+
+        region = getattr(settings, "SAGEMAKER_REGION", None)
+
+        return {
+            "storage_type": "s3",
+            "bucket_name": self.bucket_name,
+            "uri": f"s3://{self.bucket_name}/{path}",
+            "region": region,
+        }
+
+    def get_file(self, path: str) -> BinaryIO:
+        """Get a file from S3 storage."""
+        if not self.file_exists(path):
+            raise FileNotFoundError(f"File not found: {path}")
+        file_obj = io.BytesIO()
+        self.s3.download_fileobj(self.bucket_name, path, file_obj)
+        file_obj.seek(0)
+        return file_obj
+
+    def delete_file(self, path: str) -> bool:
+        """Delete a file from S3 storage."""
+        try:
+            self.s3.delete_object(Bucket=self.bucket_name, Key=path)
+            return True
+        except ClientError:
+            return False
+
+    def file_exists(self, path: str) -> bool:
+        """Check if a file exists in S3 storage."""
+        try:
+            self.s3.head_object(Bucket=self.bucket_name, Key=path)
+            return True
+        except ClientError:
+            return False
+
+    def list_files(self, directory: str) -> List[str]:
+        """List all files in a directory in S3 storage."""
+        # Ensure directory ends with a slash if it's not empty
+
+        if directory and not directory.endswith("/"):
+            directory += "/"
+        result = []
+        paginator = self.s3.get_paginator("list_objects_v2")
+        pages = paginator.paginate(Bucket=self.bucket_name, Prefix=directory)
+
+        for page in pages:
+            if "Contents" in page:
+                for obj in page["Contents"]:
+                    result.append(obj["Key"])
+        return result
+
+    def process_file(self, path: str, processor_func: Callable, **kwargs):
+        """
+        Process a file using the provided processor function.
+
+        Args:
+            path: Path to the file
+            processor_func: Function that processes the file
+            **kwargs: Additional arguments to pass to the processor function
+
+        Returns:
+            The result of the processor function
+        """
+        import logging
+        import tempfile
+
+        if not self.file_exists(path):
+            raise FileNotFoundError(f"File not found in S3: {path}")
+        with tempfile.NamedTemporaryFile(
+            suffix=os.path.splitext(path)[1], delete=True
+        ) as temp_file:
+            try:
+                # Download the file from S3 to the temporary file
+
+                self.s3.download_fileobj(self.bucket_name, path, temp_file)
+                temp_file.flush()
+
+                return processor_func(local_path=temp_file.name, **kwargs)
+            except Exception as e:
+                logging.error(f"Error processing S3 file {path}: {e}", exc_info=True)
+                raise
+
+    def is_directory(self, path: str) -> bool:
+        """
+        Check if a path is a directory in S3 storage.
+
+        In S3, directories are virtual concepts. A path is considered a directory
+        if there are objects with the path as a prefix.
+
+        Args:
+            path: Path to check
+
+        Returns:
+            bool: True if the path is a directory, False otherwise
+        """
+        # Ensure path ends with a slash if not empty
+        if path and not path.endswith('/'):
+            path += '/'
+
+        response = self.s3.list_objects_v2(
+            Bucket=self.bucket_name,
+            Prefix=path,
+            MaxKeys=1
+        )
+
+        return 'Contents' in response
+
+    def remove_directory(self, directory: str) -> bool:
+        """
+        Remove a directory and all its contents from S3 storage.
+
+        In S3, this removes all objects with the directory path as a prefix.
+        Since S3 doesn't have actual directories, this effectively removes
+        all files within the virtual directory structure.
+
+        Args:
+            directory: Directory path to remove
+
+        Returns:
+            bool: True if removal was successful, False otherwise
+        """
+        # Ensure directory ends with a slash if not empty
+        if directory and not directory.endswith('/'):
+            directory += '/'
+
+        try:
+            # Get all objects with the directory prefix
+            objects_to_delete = []
+            paginator = self.s3.get_paginator('list_objects_v2')
+            pages = paginator.paginate(Bucket=self.bucket_name, Prefix=directory)
+
+            for page in pages:
+                if 'Contents' in page:
+                    for obj in page['Contents']:
+                        objects_to_delete.append({'Key': obj['Key']})
+
+            if not objects_to_delete:
+                return False
+
+            batch_size = 1000
+            for i in range(0, len(objects_to_delete), batch_size):
+                batch = objects_to_delete[i:i + batch_size]
+
+                response = self.s3.delete_objects(
+                    Bucket=self.bucket_name,
+                    Delete={'Objects': batch}
+                )
+
+                if 'Errors' in response and response['Errors']:
+                    return False
+
+            return True
+
+        except ClientError:
+            return False

application/storage/storage_creator.py

@@ -0,0 +1,32 @@
+"""Storage factory for creating different storage implementations."""
+from typing import Dict, Type
+
+from application.storage.base import BaseStorage
+from application.storage.local import LocalStorage
+from application.storage.s3 import S3Storage
+from application.core.settings import settings
+
+
+class StorageCreator:
+    storages: Dict[str, Type[BaseStorage]] = {
+        "local": LocalStorage,
+        "s3": S3Storage,
+    }
+    
+    _instance = None
+    
+    @classmethod
+    def get_storage(cls) -> BaseStorage:
+        if cls._instance is None:
+            storage_type = getattr(settings, "STORAGE_TYPE", "local")
+            cls._instance = cls.create_storage(storage_type)
+        
+        return cls._instance
+    
+    @classmethod
+    def create_storage(cls, type_name: str, *args, **kwargs) -> BaseStorage:
+        storage_class = cls.storages.get(type_name.lower())
+        if not storage_class:
+            raise ValueError(f"No storage implementation found for type {type_name}")
+        
+        return storage_class(*args, **kwargs)

application/usage.py

@@ -2,10 +2,11 @@ import sys
 from datetime import datetime
 
 from application.core.mongo_db import MongoDB
+from application.core.settings import settings
 from application.utils import num_tokens_from_object_or_list, num_tokens_from_string
 
 mongo = MongoDB.get_client()
-db = mongo["docsgpt"]
+db = mongo[settings.MONGO_DB_NAME]
 usage_collection = db["token_usage"]
 
 

application/utils.py

@@ -1,8 +1,13 @@
 import hashlib
+import os
 import re
+import uuid
 
 import tiktoken
 from flask import jsonify, make_response
+from werkzeug.utils import secure_filename
+
+from application.core.settings import settings
 
 
 _encoding = None
@@ -15,6 +20,41 @@ def get_encoding():
     return _encoding
 
 
+def get_gpt_model() -> str:
+    """Get the appropriate GPT model based on provider"""
+    model_map = {
+        "openai": "gpt-4o-mini",
+        "anthropic": "claude-2",
+        "groq": "llama3-8b-8192",
+        "novita": "deepseek/deepseek-r1",
+    }
+    return settings.LLM_NAME or model_map.get(settings.LLM_PROVIDER, "")
+
+
+def safe_filename(filename):
+    """
+    Creates a safe filename that preserves the original extension.
+    Uses secure_filename, but ensures a proper filename is returned even with non-Latin characters.
+
+    Args:
+        filename (str): The original filename
+
+    Returns:
+        str: A safe filename that can be used for storage
+    """
+    if not filename:
+        return str(uuid.uuid4())
+    _, extension = os.path.splitext(filename)
+
+    safe_name = secure_filename(filename)
+
+    # If secure_filename returns just the extension or an empty string
+
+    if not safe_name or safe_name == extension.lstrip("."):
+        return f"{str(uuid.uuid4())}{extension}"
+    return safe_name
+
+
 def num_tokens_from_string(string: str) -> int:
     encoding = get_encoding()
     if isinstance(string, str):
@@ -39,7 +79,6 @@ def count_tokens_docs(docs):
     docs_content = ""
     for doc in docs:
         docs_content += doc.page_content
-
     tokens = num_tokens_from_string(docs_content)
     return tokens
 
@@ -51,7 +90,7 @@ def check_required_fields(data, required_fields):
             jsonify(
                 {
                     "success": False,
-                    "message": f"Missing fields: {', '.join(missing_fields)}",
+                    "message": f"Missing required fields: {', '.join(missing_fields)}",
                 }
             ),
             400,
@@ -59,6 +98,27 @@ def check_required_fields(data, required_fields):
     return None
 
 
+def validate_required_fields(data, required_fields):
+    missing_fields = []
+    empty_fields = []
+
+    for field in required_fields:
+        if field not in data:
+            missing_fields.append(field)
+        elif not data[field]:
+            empty_fields.append(field)
+    errors = []
+    if missing_fields:
+        errors.append(f"Missing required fields: {', '.join(missing_fields)}")
+    if empty_fields:
+        errors.append(f"Empty values in required fields: {', '.join(empty_fields)}")
+    if errors:
+        return make_response(
+            jsonify({"success": False, "message": " | ".join(errors)}), 400
+        )
+    return None
+
+
 def get_hash(data):
     return hashlib.md5(data.encode(), usedforsecurity=False).hexdigest()
 
@@ -74,13 +134,12 @@ def limit_chat_history(history, max_token_limit=None, gpt_model="docsgpt"):
         max_token_limit
         if max_token_limit
         and max_token_limit
-        < settings.MODEL_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
-        else settings.MODEL_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
+        < settings.LLM_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
+        else settings.LLM_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
     )
 
     if not history:
         return []
-
     trimmed_history = []
     tokens_current_history = 0
 
@@ -89,18 +148,15 @@ def limit_chat_history(history, max_token_limit=None, gpt_model="docsgpt"):
         if "prompt" in message and "response" in message:
             tokens_batch += num_tokens_from_string(message["prompt"])
             tokens_batch += num_tokens_from_string(message["response"])
-
         if "tool_calls" in message:
             for tool_call in message["tool_calls"]:
                 tool_call_string = f"Tool: {tool_call.get('tool_name')} | Action: {tool_call.get('action_name')} | Args: {tool_call.get('arguments')} | Response: {tool_call.get('result')}"
                 tokens_batch += num_tokens_from_string(tool_call_string)
-
         if tokens_current_history + tokens_batch < max_token_limit:
             tokens_current_history += tokens_batch
             trimmed_history.insert(0, message)
         else:
             break
-
     return trimmed_history
 
 
@@ -109,3 +165,14 @@ def validate_function_name(function_name):
     if not re.match(r"^[a-zA-Z0-9_-]+$", function_name):
         return False
     return True
+
+
+def generate_image_url(image_path):
+    strategy = getattr(settings, "URL_STRATEGY", "backend")
+    if strategy == "s3":
+        bucket_name = getattr(settings, "S3_BUCKET_NAME", "docsgpt-test-bucket")
+        region_name = getattr(settings, "SAGEMAKER_REGION", "eu-central-1")
+        return f"https://{bucket_name}.s3.{region_name}.amazonaws.com/{image_path}"
+    else:
+        base_url = getattr(settings, "API_URL", "http://localhost:7091")
+        return f"{base_url}/api/images/{image_path}"

application/vectorstore/base.py

@@ -1,20 +1,28 @@
-from abc import ABC, abstractmethod
 import os
-from sentence_transformers import SentenceTransformer
+from abc import ABC, abstractmethod
+
 from langchain_openai import OpenAIEmbeddings
+from sentence_transformers import SentenceTransformer
+
 from application.core.settings import settings
 
+
 class EmbeddingsWrapper:
     def __init__(self, model_name, *args, **kwargs):
-        self.model = SentenceTransformer(model_name, config_kwargs={'allow_dangerous_deserialization': True}, *args, **kwargs)
+        self.model = SentenceTransformer(
+            model_name,
+            config_kwargs={"allow_dangerous_deserialization": True},
+            *args,
+            **kwargs
+        )
         self.dimension = self.model.get_sentence_embedding_dimension()
 
     def embed_query(self, query: str):
         return self.model.encode(query).tolist()
-    
+
     def embed_documents(self, documents: list):
         return self.model.encode(documents).tolist()
-    
+
     def __call__(self, text):
         if isinstance(text, str):
             return self.embed_query(text)
@@ -24,15 +32,14 @@ class EmbeddingsWrapper:
             raise ValueError("Input must be a string or a list of strings")
 
 
-
 class EmbeddingsSingleton:
     _instances = {}
 
     @staticmethod
     def get_instance(embeddings_name, *args, **kwargs):
         if embeddings_name not in EmbeddingsSingleton._instances:
-            EmbeddingsSingleton._instances[embeddings_name] = EmbeddingsSingleton._create_instance(
-                embeddings_name, *args, **kwargs
+            EmbeddingsSingleton._instances[embeddings_name] = (
+                EmbeddingsSingleton._create_instance(embeddings_name, *args, **kwargs)
             )
         return EmbeddingsSingleton._instances[embeddings_name]
 
@@ -40,9 +47,15 @@ class EmbeddingsSingleton:
     def _create_instance(embeddings_name, *args, **kwargs):
         embeddings_factory = {
             "openai_text-embedding-ada-002": OpenAIEmbeddings,
-            "huggingface_sentence-transformers/all-mpnet-base-v2": lambda: EmbeddingsWrapper("sentence-transformers/all-mpnet-base-v2"),
-            "huggingface_sentence-transformers-all-mpnet-base-v2": lambda: EmbeddingsWrapper("sentence-transformers/all-mpnet-base-v2"),
-            "huggingface_hkunlp/instructor-large": lambda: EmbeddingsWrapper("hkunlp/instructor-large"),
+            "huggingface_sentence-transformers/all-mpnet-base-v2": lambda: EmbeddingsWrapper(
+                "sentence-transformers/all-mpnet-base-v2"
+            ),
+            "huggingface_sentence-transformers-all-mpnet-base-v2": lambda: EmbeddingsWrapper(
+                "sentence-transformers/all-mpnet-base-v2"
+            ),
+            "huggingface_hkunlp/instructor-large": lambda: EmbeddingsWrapper(
+                "hkunlp/instructor-large"
+            ),
         }
 
         if embeddings_name in embeddings_factory:
@@ -50,34 +63,63 @@ class EmbeddingsSingleton:
         else:
             return EmbeddingsWrapper(embeddings_name, *args, **kwargs)
 
+
 class BaseVectorStore(ABC):
     def __init__(self):
         pass
 
     @abstractmethod
     def search(self, *args, **kwargs):
+        """Search for similar documents/chunks in the vectorstore"""
+        pass
+
+    @abstractmethod
+    def add_texts(self, texts, metadatas=None, *args, **kwargs):
+        """Add texts with their embeddings to the vectorstore"""
+        pass
+
+    def delete_index(self, *args, **kwargs):
+        """Delete the entire index/collection"""
+        pass
+
+    def save_local(self, *args, **kwargs):
+        """Save vectorstore to local storage"""
+        pass
+
+    def get_chunks(self, *args, **kwargs):
+        """Get all chunks from the vectorstore"""
+        pass
+
+    def add_chunk(self, text, metadata=None, *args, **kwargs):
+        """Add a single chunk to the vectorstore"""
+        pass
+
+    def delete_chunk(self, chunk_id, *args, **kwargs):
+        """Delete a specific chunk from the vectorstore"""
         pass
 
     def is_azure_configured(self):
-        return settings.OPENAI_API_BASE and settings.OPENAI_API_VERSION and settings.AZURE_DEPLOYMENT_NAME
+        return (
+            settings.OPENAI_API_BASE
+            and settings.OPENAI_API_VERSION
+            and settings.AZURE_DEPLOYMENT_NAME
+        )
 
     def _get_embeddings(self, embeddings_name, embeddings_key=None):
         if embeddings_name == "openai_text-embedding-ada-002":
             if self.is_azure_configured():
                 os.environ["OPENAI_API_TYPE"] = "azure"
                 embedding_instance = EmbeddingsSingleton.get_instance(
-                    embeddings_name,
-                    model=settings.AZURE_EMBEDDINGS_DEPLOYMENT_NAME
+                    embeddings_name, model=settings.AZURE_EMBEDDINGS_DEPLOYMENT_NAME
                 )
             else:
                 embedding_instance = EmbeddingsSingleton.get_instance(
-                    embeddings_name,
-                    openai_api_key=embeddings_key
+                    embeddings_name, openai_api_key=embeddings_key
                 )
         elif embeddings_name == "huggingface_sentence-transformers/all-mpnet-base-v2":
             if os.path.exists("./models/all-mpnet-base-v2"):
                 embedding_instance = EmbeddingsSingleton.get_instance(
-                    embeddings_name = "./models/all-mpnet-base-v2",
+                    embeddings_name="./models/all-mpnet-base-v2",
                 )
             else:
                 embedding_instance = EmbeddingsSingleton.get_instance(
@@ -87,4 +129,3 @@ class BaseVectorStore(ABC):
             embedding_instance = EmbeddingsSingleton.get_instance(embeddings_name)
 
         return embedding_instance
-    

application/vectorstore/elasticsearch.py

@@ -1,9 +1,6 @@
 from application.vectorstore.base import BaseVectorStore
 from application.core.settings import settings
 from application.vectorstore.document_class import Document
-import elasticsearch
-
-
 
 
 class ElasticsearchStore(BaseVectorStore):
@@ -26,8 +23,7 @@ class ElasticsearchStore(BaseVectorStore):
             else:
                 raise ValueError("Please provide either elasticsearch_url or cloud_id.")
 
-            
-
+            import elasticsearch
             ElasticsearchStore._es_connection = elasticsearch.Elasticsearch(**connection_params)
             
         self.docsearch = ElasticsearchStore._es_connection
@@ -155,8 +151,6 @@ class ElasticsearchStore(BaseVectorStore):
         **kwargs,
         ):
         
-        from elasticsearch.helpers import BulkIndexError, bulk
-
         bulk_kwargs = bulk_kwargs or {}
         import uuid
         embeddings = []
@@ -189,6 +183,7 @@ class ElasticsearchStore(BaseVectorStore):
 
 
         if len(requests) > 0:
+            from elasticsearch.helpers import BulkIndexError, bulk
             try:
                 success, failed = bulk(
                     self._es_connection,

application/vectorstore/faiss.py

@@ -1,17 +1,20 @@
 import os
+import tempfile
+import io
 
 from langchain_community.vectorstores import FAISS
 
 from application.core.settings import settings
 from application.parser.schema.base import Document
 from application.vectorstore.base import BaseVectorStore
+from application.storage.storage_creator import StorageCreator
 
 
 def get_vectorstore(path: str) -> str:
     if path:
-        vectorstore = os.path.join("application", "indexes", path)
+        vectorstore = f"indexes/{path}"
     else:
-        vectorstore = os.path.join("application")
+        vectorstore = "indexes"
     return vectorstore
 
 
@@ -21,16 +24,40 @@ class FaissStore(BaseVectorStore):
         self.source_id = source_id
         self.path = get_vectorstore(source_id)
         self.embeddings = self._get_embeddings(settings.EMBEDDINGS_NAME, embeddings_key)
+        self.storage = StorageCreator.get_storage()
 
         try:
             if docs_init:
                 self.docsearch = FAISS.from_documents(docs_init, self.embeddings)
             else:
-                self.docsearch = FAISS.load_local(
-                    self.path, self.embeddings, allow_dangerous_deserialization=True
-                )
-        except Exception:
-            raise
+                with tempfile.TemporaryDirectory() as temp_dir:
+                    faiss_path = f"{self.path}/index.faiss"
+                    pkl_path = f"{self.path}/index.pkl"
+
+                    if not self.storage.file_exists(
+                        faiss_path
+                    ) or not self.storage.file_exists(pkl_path):
+                        raise FileNotFoundError(
+                            f"Index files not found in storage at {self.path}"
+                        )
+
+                    faiss_file = self.storage.get_file(faiss_path)
+                    pkl_file = self.storage.get_file(pkl_path)
+
+                    local_faiss_path = os.path.join(temp_dir, "index.faiss")
+                    local_pkl_path = os.path.join(temp_dir, "index.pkl")
+
+                    with open(local_faiss_path, "wb") as f:
+                        f.write(faiss_file.read())
+
+                    with open(local_pkl_path, "wb") as f:
+                        f.write(pkl_file.read())
+
+                    self.docsearch = FAISS.load_local(
+                        temp_dir, self.embeddings, allow_dangerous_deserialization=True
+                    )
+        except Exception as e:
+            raise Exception(f"Error loading FAISS index: {str(e)}")
 
         self.assert_embedding_dimensions(self.embeddings)
 
@@ -40,8 +67,37 @@ class FaissStore(BaseVectorStore):
     def add_texts(self, *args, **kwargs):
         return self.docsearch.add_texts(*args, **kwargs)
 
-    def save_local(self, *args, **kwargs):
-        return self.docsearch.save_local(*args, **kwargs)
+    def _save_to_storage(self):
+        """
+        Save the FAISS index to storage using temporary directory pattern.
+        Works consistently for both local and S3 storage.
+        """
+        with tempfile.TemporaryDirectory() as temp_dir:
+            self.docsearch.save_local(temp_dir)
+
+            faiss_path = os.path.join(temp_dir, "index.faiss")
+            pkl_path = os.path.join(temp_dir, "index.pkl")
+
+            with open(faiss_path, "rb") as f_faiss:
+                faiss_data = f_faiss.read()
+
+            with open(pkl_path, "rb") as f_pkl:
+                pkl_data = f_pkl.read()
+
+            storage_path = get_vectorstore(self.source_id)
+            self.storage.save_file(io.BytesIO(faiss_data), f"{storage_path}/index.faiss")
+            self.storage.save_file(io.BytesIO(pkl_data), f"{storage_path}/index.pkl")
+
+        return True
+
+    def save_local(self, path=None):
+        if path:
+            os.makedirs(path, exist_ok=True)
+            self.docsearch.save_local(path)
+
+        self._save_to_storage()
+
+        return True
 
     def delete_index(self, *args, **kwargs):
         return self.docsearch.delete(*args, **kwargs)
@@ -77,13 +133,17 @@ class FaissStore(BaseVectorStore):
         return chunks
 
     def add_chunk(self, text, metadata=None):
+        """Add a new chunk and save to storage."""
         metadata = metadata or {}
         doc = Document(text=text, extra_info=metadata).to_langchain_format()
         doc_id = self.docsearch.add_documents([doc])
-        self.save_local(self.path)
+        self._save_to_storage()
         return doc_id
 
+
+
     def delete_chunk(self, chunk_id):
+        """Delete a chunk and save to storage."""
         self.delete_index([chunk_id])
-        self.save_local(self.path)
+        self._save_to_storage()
         return True

application/vectorstore/mongodb.py

@@ -1,3 +1,4 @@
+import logging
 from application.core.settings import settings
 from application.vectorstore.base import BaseVectorStore
 from application.vectorstore.document_class import Document
@@ -146,7 +147,7 @@ class MongoDBVectorStore(BaseVectorStore):
 
             return chunks
         except Exception as e:
-            print(f"Error getting chunks: {e}")
+            logging.error(f"Error getting chunks: {e}", exc_info=True)
             return []
 
     def add_chunk(self, text, metadata=None):
@@ -172,5 +173,5 @@ class MongoDBVectorStore(BaseVectorStore):
             result = self._collection.delete_one({"_id": object_id})
             return result.deleted_count > 0
         except Exception as e:
-            print(f"Error deleting chunk: {e}")
+            logging.error(f"Error deleting chunk: {e}", exc_info=True)
             return False

application/vectorstore/pgvector.py

@@ -0,0 +1,303 @@
+import logging
+from typing import List, Optional, Any, Dict
+from application.core.settings import settings
+from application.vectorstore.base import BaseVectorStore
+from application.vectorstore.document_class import Document
+
+
+class PGVectorStore(BaseVectorStore):
+    def __init__(
+        self,
+        source_id: str = "",
+        embeddings_key: str = "embeddings",
+        table_name: str = "documents",
+        vector_column: str = "embedding",
+        text_column: str = "text",
+        metadata_column: str = "metadata",
+        connection_string: str = None,
+    ):
+        super().__init__()
+        # Store the source_id for use in add_chunk
+        self._source_id = str(source_id).replace("application/indexes/", "").rstrip("/")
+        self._embeddings_key = embeddings_key
+        self._table_name = table_name
+        self._vector_column = vector_column
+        self._text_column = text_column
+        self._metadata_column = metadata_column
+        self._embedding = self._get_embeddings(settings.EMBEDDINGS_NAME, embeddings_key)
+        
+        # Use provided connection string or fall back to settings
+        self._connection_string = connection_string or getattr(settings, 'PGVECTOR_CONNECTION_STRING', None)
+        
+        if not self._connection_string:
+            raise ValueError(
+                "PostgreSQL connection string is required. "
+                "Set PGVECTOR_CONNECTION_STRING in settings or pass connection_string parameter."
+            )
+
+        try:
+            import psycopg2
+            from psycopg2.extras import Json
+            import pgvector.psycopg2
+        except ImportError:
+            raise ImportError(
+                "Could not import required packages. "
+                "Please install with `pip install psycopg2-binary pgvector`."
+            )
+
+        self._psycopg2 = psycopg2
+        self._Json = Json
+        self._pgvector = pgvector.psycopg2
+        self._connection = None
+        self._ensure_table_exists()
+
+    def _get_connection(self):
+        """Get or create database connection"""
+        if self._connection is None or self._connection.closed:
+            self._connection = self._psycopg2.connect(self._connection_string)
+            # Register pgvector types
+            self._pgvector.register_vector(self._connection)
+        return self._connection
+
+    def _ensure_table_exists(self):
+        """Create table and enable pgvector extension if they don't exist"""
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            # Enable pgvector extension
+            cursor.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+            
+            # Get embedding dimension
+            embedding_dim = getattr(self._embedding, 'dimension', 1536)  # Default to OpenAI dimension
+            
+            # Create table with vector column
+            create_table_query = f"""
+            CREATE TABLE IF NOT EXISTS {self._table_name} (
+                id SERIAL PRIMARY KEY,
+                {self._text_column} TEXT NOT NULL,
+                {self._vector_column} vector({embedding_dim}),
+                {self._metadata_column} JSONB,
+                source_id TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+            """
+            cursor.execute(create_table_query)
+            
+            # Create index for vector similarity search
+            index_query = f"""
+            CREATE INDEX IF NOT EXISTS {self._table_name}_{self._vector_column}_idx 
+            ON {self._table_name} USING ivfflat ({self._vector_column} vector_cosine_ops)
+            WITH (lists = 100);
+            """
+            cursor.execute(index_query)
+            
+            # Create index for source_id filtering
+            source_index_query = f"""
+            CREATE INDEX IF NOT EXISTS {self._table_name}_source_id_idx 
+            ON {self._table_name} (source_id);
+            """
+            cursor.execute(source_index_query)
+            
+            conn.commit()
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error creating table: {e}")
+            raise
+        finally:
+            cursor.close()
+
+    def search(self, question: str, k: int = 2, *args, **kwargs) -> List[Document]:
+        """Search for similar documents using vector similarity"""
+        query_vector = self._embedding.embed_query(question)
+        
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            # Use cosine distance for similarity search with proper vector formatting
+            search_query = f"""
+            SELECT {self._text_column}, {self._metadata_column}, 
+                   ({self._vector_column} <=> %s::vector) as distance
+            FROM {self._table_name}
+            WHERE source_id = %s
+            ORDER BY {self._vector_column} <=> %s::vector
+            LIMIT %s;
+            """
+            
+            cursor.execute(search_query, (query_vector, self._source_id, query_vector, k))
+            results = cursor.fetchall()
+            
+            
+            documents = []
+            for text, metadata, distance in results:
+                metadata = metadata or {}
+                documents.append(Document(page_content=text, metadata=metadata))
+            
+            return documents
+            
+        except Exception as e:
+            logging.error(f"Error searching documents: {e}", exc_info=True)
+            return []
+        finally:
+            cursor.close()
+
+    def add_texts(
+        self,
+        texts: List[str],
+        metadatas: Optional[List[Dict[str, Any]]] = None,
+        *args,
+        **kwargs,
+    ) -> List[str]:
+        """Add texts with their embeddings to the vector store"""
+        if not texts:
+            return []
+        
+        embeddings = self._embedding.embed_documents(texts)
+        metadatas = metadatas or [{}] * len(texts)
+        
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            insert_query = f"""
+            INSERT INTO {self._table_name} ({self._text_column}, {self._vector_column}, {self._metadata_column}, source_id)
+            VALUES (%s, %s, %s, %s)
+            RETURNING id;
+            """
+            
+            inserted_ids = []
+            for text, embedding, metadata in zip(texts, embeddings, metadatas):
+                cursor.execute(
+                    insert_query,
+                    (text, embedding, self._Json(metadata), self._source_id)
+                )
+                inserted_id = cursor.fetchone()[0]
+                inserted_ids.append(str(inserted_id))
+            
+            conn.commit()
+            return inserted_ids
+            
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error adding texts: {e}")
+            raise
+        finally:
+            cursor.close()
+
+    def delete_index(self, *args, **kwargs):
+        """Delete all documents for this source_id"""
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            delete_query = f"DELETE FROM {self._table_name} WHERE source_id = %s;"
+            cursor.execute(delete_query, (self._source_id,))
+            conn.commit()
+            
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error deleting index: {e}")
+            raise
+        finally:
+            cursor.close()
+
+    def save_local(self, *args, **kwargs):
+        """No-op for PostgreSQL - data is already persisted"""
+        pass
+
+    def get_chunks(self) -> List[Dict[str, Any]]:
+        """Get all chunks for this source_id"""
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            select_query = f"""
+            SELECT id, {self._text_column}, {self._metadata_column}
+            FROM {self._table_name}
+            WHERE source_id = %s;
+            """
+            cursor.execute(select_query, (self._source_id,))
+            results = cursor.fetchall()
+            
+            chunks = []
+            for doc_id, text, metadata in results:
+                chunks.append({
+                    "doc_id": str(doc_id),
+                    "text": text,
+                    "metadata": metadata or {}
+                })
+            
+            return chunks
+            
+        except Exception as e:
+            logging.error(f"Error getting chunks: {e}")
+            return []
+        finally:
+            cursor.close()
+
+    def add_chunk(self, text: str, metadata: Optional[Dict[str, Any]] = None) -> str:
+        """Add a single chunk to the vector store"""
+        metadata = metadata or {}
+        
+        # Create a copy to avoid modifying the original metadata
+        final_metadata = metadata.copy()
+        
+        # Ensure the source_id is in the metadata so the chunk can be found by filters
+        final_metadata["source_id"] = self._source_id
+        
+        embeddings = self._embedding.embed_documents([text])
+        
+        if not embeddings:
+            raise ValueError("Could not generate embedding for chunk")
+        
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            insert_query = f"""
+            INSERT INTO {self._table_name} ({self._text_column}, {self._vector_column}, {self._metadata_column}, source_id)
+            VALUES (%s, %s, %s, %s)
+            RETURNING id;
+            """
+            
+            cursor.execute(
+                insert_query,
+                (text, embeddings[0], self._Json(final_metadata), self._source_id)
+            )
+            inserted_id = cursor.fetchone()[0]
+            conn.commit()
+            
+            return str(inserted_id)
+            
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error adding chunk: {e}")
+            raise
+        finally:
+            cursor.close()
+
+    def delete_chunk(self, chunk_id: str) -> bool:
+        """Delete a specific chunk by its ID"""
+        conn = self._get_connection()
+        cursor = conn.cursor()
+        
+        try:
+            delete_query = f"DELETE FROM {self._table_name} WHERE id = %s AND source_id = %s;"
+            cursor.execute(delete_query, (int(chunk_id), self._source_id))
+            deleted_count = cursor.rowcount
+            conn.commit()
+            
+            return deleted_count > 0
+            
+        except Exception as e:
+            conn.rollback()
+            logging.error(f"Error deleting chunk: {e}")
+            return False
+        finally:
+            cursor.close()
+
+    def __del__(self):
+        """Close database connection when object is destroyed"""
+        if hasattr(self, '_connection') and self._connection and not self._connection.closed:
+            self._connection.close()

application/vectorstore/qdrant.py

@@ -1,23 +1,30 @@
-from langchain_community.vectorstores.qdrant import Qdrant
+import logging
 from application.vectorstore.base import BaseVectorStore
 from application.core.settings import settings
-from qdrant_client import models
+from application.vectorstore.document_class import Document
 
 
 class QdrantStore(BaseVectorStore):
     def __init__(self, source_id: str = "", embeddings_key: str = "embeddings"):
+        from qdrant_client import models
+        from langchain_community.vectorstores.qdrant import Qdrant
+
+        # Store the source_id for use in add_chunk
+        self._source_id = str(source_id).replace("application/indexes/", "").rstrip("/")
+        
         self._filter = models.Filter(
             must=[
                 models.FieldCondition(
                     key="metadata.source_id",
-                    match=models.MatchValue(value=source_id.replace("application/indexes/", "").rstrip("/")),
+                    match=models.MatchValue(value=self._source_id),
                 )
             ]
         )
 
+        embedding=self._get_embeddings(settings.EMBEDDINGS_NAME, embeddings_key)
         self._docsearch = Qdrant.construct_instance(
             ["TEXT_TO_OBTAIN_EMBEDDINGS_DIMENSION"],
-            embedding=self._get_embeddings(settings.EMBEDDINGS_NAME, embeddings_key),
+            embedding=embedding,
             collection_name=settings.QDRANT_COLLECTION_NAME,
             location=settings.QDRANT_LOCATION,
             url=settings.QDRANT_URL,
@@ -31,6 +38,32 @@ class QdrantStore(BaseVectorStore):
             path=settings.QDRANT_PATH,
             distance_func=settings.QDRANT_DISTANCE_FUNC,
         )
+        try:
+            collections = self._docsearch.client.get_collections()
+            collection_exists = settings.QDRANT_COLLECTION_NAME in [
+                collection.name for collection in collections.collections
+            ]
+            
+            if not collection_exists:
+                self._docsearch.client.recreate_collection(
+                    collection_name=settings.QDRANT_COLLECTION_NAME,
+                    vectors_config=models.VectorParams(size=embedding.client[1].word_embedding_dimension, distance=models.Distance.COSINE),
+                )
+            
+            # Ensure the required index exists for metadata.source_id
+            try:
+                self._docsearch.client.create_payload_index(
+                    collection_name=settings.QDRANT_COLLECTION_NAME,
+                    field_name="metadata.source_id",
+                    field_schema=models.PayloadSchemaType.KEYWORD,
+                )
+            except Exception as index_error:
+                # Index might already exist, which is fine
+                if "already exists" not in str(index_error).lower():
+                    logging.warning(f"Could not create index for metadata.source_id: {index_error}")
+                    
+        except Exception as e:
+            logging.warning(f"Could not check for collection: {e}")
 
     def search(self, *args, **kwargs):
         return self._docsearch.similarity_search(filter=self._filter, *args, **kwargs)
@@ -45,3 +78,59 @@ class QdrantStore(BaseVectorStore):
         return self._docsearch.client.delete(
             collection_name=settings.QDRANT_COLLECTION_NAME, points_selector=self._filter
         )
+
+    def get_chunks(self):
+        try:
+
+            chunks = []
+            offset = None
+            while True:
+                records, offset = self._docsearch.client.scroll(
+                    collection_name=settings.QDRANT_COLLECTION_NAME,
+                    scroll_filter=self._filter,
+                    limit=10,
+                    with_payload=True,
+                    with_vectors=False,
+                    offset=offset,
+                )
+                for record in records:
+                    doc_id = record.id
+                    text = record.payload.get("page_content")
+                    metadata = record.payload.get("metadata")
+                    chunks.append(
+                        {"doc_id": doc_id, "text": text, "metadata": metadata}
+                    )
+                if offset is None:
+                    break
+            return chunks
+        except Exception as e:
+            logging.error(f"Error getting chunks: {e}", exc_info=True)
+            return []
+
+    def add_chunk(self, text, metadata=None):
+        import uuid
+        metadata = metadata or {}
+        
+        # Create a copy to avoid modifying the original metadata
+        final_metadata = metadata.copy()
+        
+        # Ensure the source_id is in the metadata so the chunk can be found by filters
+        final_metadata["source_id"] = self._source_id
+        
+        doc = Document(page_content=text, metadata=final_metadata)
+        # Generate a unique ID for the document
+        doc_id = str(uuid.uuid4())
+        doc.id = doc_id
+        doc_ids = self._docsearch.add_documents([doc])
+        return doc_ids[0] if doc_ids else doc_id
+
+    def delete_chunk(self, chunk_id):
+        try:
+            self._docsearch.client.delete(
+                collection_name=settings.QDRANT_COLLECTION_NAME,
+                points_selector=[chunk_id],
+            )
+            return True
+        except Exception as e:
+            logging.error(f"Error deleting chunk: {e}", exc_info=True)
+            return False

application/vectorstore/vector_creator.py

@@ -3,6 +3,7 @@ from application.vectorstore.elasticsearch import ElasticsearchStore
 from application.vectorstore.milvus import MilvusStore
 from application.vectorstore.mongodb import MongoDBVectorStore
 from application.vectorstore.qdrant import QdrantStore
+from application.vectorstore.pgvector import PGVectorStore
 
 
 class VectorCreator:
@@ -12,6 +13,7 @@ class VectorCreator:
         "mongodb": MongoDBVectorStore,
         "qdrant": QdrantStore,
         "milvus": MilvusStore,
+        "pgvector": PGVectorStore
     }
 
     @classmethod

deployment/docker-compose-dev.yaml

@@ -1,3 +1,4 @@
+name: docsgpt-oss
 services:
 
   redis:

deployment/docker-compose-hub.yaml

@@ -0,0 +1,75 @@
+name: docsgpt-oss
+services:
+
+  frontend:
+    image: arc53/docsgpt-fe:develop
+    environment:
+      - VITE_API_HOST=http://localhost:7091
+      - VITE_API_STREAMING=$VITE_API_STREAMING
+      - VITE_GOOGLE_CLIENT_ID=$VITE_GOOGLE_CLIENT_ID
+    ports:
+      - "5173:5173"
+    depends_on:
+      - backend
+
+
+  backend:
+    user: root
+    image: arc53/docsgpt:develop
+    environment:
+      - API_KEY=$API_KEY
+      - EMBEDDINGS_KEY=$API_KEY
+      - LLM_PROVIDER=$LLM_PROVIDER
+      - LLM_NAME=$LLM_NAME
+      - CELERY_BROKER_URL=redis://redis:6379/0
+      - CELERY_RESULT_BACKEND=redis://redis:6379/1
+      - MONGO_URI=mongodb://mongo:27017/docsgpt
+      - CACHE_REDIS_URL=redis://redis:6379/2
+      - OPENAI_BASE_URL=$OPENAI_BASE_URL
+    ports:
+      - "7091:7091"
+    volumes:
+      - ../application/indexes:/app/indexes
+      - ../application/inputs:/app/inputs
+      - ../application/vectors:/app/vectors
+    depends_on:
+      - redis
+      - mongo
+
+
+  worker:
+    user: root
+    image: arc53/docsgpt:develop
+    command: celery -A application.app.celery worker -l INFO -B
+    environment:
+      - API_KEY=$API_KEY
+      - EMBEDDINGS_KEY=$API_KEY
+      - LLM_PROVIDER=$LLM_PROVIDER
+      - LLM_NAME=$LLM_NAME
+      - CELERY_BROKER_URL=redis://redis:6379/0
+      - CELERY_RESULT_BACKEND=redis://redis:6379/1
+      - MONGO_URI=mongodb://mongo:27017/docsgpt
+      - API_URL=http://backend:7091
+      - CACHE_REDIS_URL=redis://redis:6379/2
+    volumes:
+      - ../application/indexes:/app/indexes
+      - ../application/inputs:/app/inputs
+      - ../application/vectors:/app/vectors
+    depends_on:
+      - redis
+      - mongo
+
+  redis:
+    image: redis:6-alpine
+    ports:
+      - 6379:6379
+
+  mongo:
+    image: mongo:6
+    ports:
+      - 27017:27017
+    volumes:
+      - mongodb_data_container:/data/db
+
+volumes:
+  mongodb_data_container:

deployment/docker-compose.yaml

@@ -1,3 +1,4 @@
+name: docsgpt-oss
 services:
   frontend:
     build: ../frontend
@@ -6,45 +7,53 @@ services:
     environment:
       - VITE_API_HOST=http://localhost:7091
       - VITE_API_STREAMING=$VITE_API_STREAMING
+      - VITE_GOOGLE_CLIENT_ID=$VITE_GOOGLE_CLIENT_ID
     ports:
       - "5173:5173"
     depends_on:
       - backend
 
   backend:
+    user: root
     build: ../application
     environment:
       - API_KEY=$API_KEY
       - EMBEDDINGS_KEY=$API_KEY
+      - LLM_PROVIDER=$LLM_PROVIDER
       - LLM_NAME=$LLM_NAME
       - CELERY_BROKER_URL=redis://redis:6379/0
       - CELERY_RESULT_BACKEND=redis://redis:6379/1
       - MONGO_URI=mongodb://mongo:27017/docsgpt
       - CACHE_REDIS_URL=redis://redis:6379/2
       - OPENAI_BASE_URL=$OPENAI_BASE_URL
-      - MODEL_NAME=$MODEL_NAME
     ports:
       - "7091:7091"
     volumes:
-      - ../application/indexes:/app/application/indexes
-      - ../application/inputs:/app/application/inputs
-      - ../application/vectors:/app/application/vectors
+      - ../application/indexes:/app/indexes
+      - ../application/inputs:/app/inputs
+      - ../application/vectors:/app/vectors
     depends_on:
       - redis
       - mongo
 
   worker:
+    user: root
     build: ../application
-    command: celery -A application.app.celery worker -l INFO --pool=gevent -B
+    command: celery -A application.app.celery worker -l INFO -B
     environment:
       - API_KEY=$API_KEY
       - EMBEDDINGS_KEY=$API_KEY
+      - LLM_PROVIDER=$LLM_PROVIDER
       - LLM_NAME=$LLM_NAME
       - CELERY_BROKER_URL=redis://redis:6379/0
       - CELERY_RESULT_BACKEND=redis://redis:6379/1
       - MONGO_URI=mongodb://mongo:27017/docsgpt
       - API_URL=http://backend:7091
       - CACHE_REDIS_URL=redis://redis:6379/2
+    volumes:
+      - ../application/indexes:/app/indexes
+      - ../application/inputs:/app/inputs
+      - ../application/vectors:/app/vectors
     depends_on:
       - redis
       - mongo

deployment/k8s/docsgpt-secrets.yaml

@@ -4,7 +4,7 @@ metadata:
   name: docsgpt-secrets
 type: Opaque
 data:
-  LLM_NAME: ZG9jc2dwdA==
+  LLM_PROVIDER: ZG9jc2dwdA==
   INTERNAL_KEY: aW50ZXJuYWw=
   CELERY_BROKER_URL: cmVkaXM6Ly9yZWRpcy1zZXJ2aWNlOjYzNzkvMA==
   CELERY_RESULT_BACKEND: cmVkaXM6Ly9yZWRpcy1zZXJ2aWNlOjYzNzkvMA==

docs/components/ToolCards.jsx

@@ -0,0 +1,117 @@
+import Image from 'next/image';
+
+const iconMap = {
+    'API Tool': '/toolIcons/tool_api_tool.svg',
+    'Brave Search Tool': '/toolIcons/tool_brave.svg',
+    'Cryptoprice Tool': '/toolIcons/tool_cryptoprice.svg',
+    'Ntfy Tool': '/toolIcons/tool_ntfy.svg',
+    'PostgreSQL Tool': '/toolIcons/tool_postgres.svg',
+    'Read Webpage Tool': '/toolIcons/tool_read_webpage.svg',
+    'Telegram Tool': '/toolIcons/tool_telegram.svg'
+};
+
+
+export function ToolCards({ items }) {
+    return (
+        <>
+            <div className="tool-cards">
+                {items.map(({ title, link, description }) => {
+                    const isExternal = link.startsWith('https://');
+                    const iconSrc = iconMap[title] || '/default-icon.png'; // Default icon if not found
+
+                    return (
+                        <div
+                            key={title}
+                            className={`card${isExternal ? ' external' : ''}`}
+                        >
+                            <a href={link} target={isExternal ? '_blank' : undefined} rel="noopener noreferrer" className="card-link-wrapper">
+                                <div className="card-icon-container">
+                                    {iconSrc && <div className="card-icon"><Image src={iconSrc} alt={title} width={32} height={32} /></div>} {/* Reduced icon size */}
+                                </div>
+                                <h3 className="card-title">{title}</h3>
+                                {description && <p className="card-description">{description}</p>}
+                                {/* Card URL element removed from here */}
+                            </a>
+                        </div>
+                    );
+                })}
+            </div>
+
+            <style jsx>{`
+               .tool-cards {
+                    margin-top: 24px;
+                    display: grid;
+                    grid-template-columns: 1fr;
+                    gap: 16px;
+                }
+                @media (min-width: 768px) {
+                    .tool-cards {
+                        grid-template-columns: 1fr 1fr; /* Keeps two columns on wider screens */
+                    }
+                }
+                .card {
+                    background-color: #222222;
+                    border-radius: 8px;
+                    padding: 16px; /* Existing padding */
+                    transition: background-color 0.3s;
+                    position: relative;
+                    color: #ffffff;
+                    display: flex; /* Using flex to help with alignment */
+                    flex-direction: column;
+                    /* align-items: center; // Alignment for items inside card-link-wrapper is better */
+                    /* justify-content: center; // We want content to flow from top */
+                    height: 100%; /* Fill the height of the grid cell, ensures cards in a row are same height */
+                }
+                .card:hover {
+                    background-color: #333333;
+                }
+                .card.external::after {
+                    content: "↗";
+                    position: absolute;
+                    top: 12px;
+                    right: 12px;
+                    color: #ffffff;
+                    font-size: 0.7em;
+                    opacity: 0.8;
+                }
+                .card-link-wrapper {
+                    display: flex;
+                    flex-direction: column;
+                    align-items:center; /* Centers icon, title, description horizontally */
+                    text-align: center; /* Ensures text within p and h3 is centered */
+                    color: inherit;
+                    text-decoration: none;
+                    width:100%;
+                    height: 100%; /* Make the link wrapper take full card height */
+                    justify-content: flex-start; /* Align content to the top */
+                }
+               .card-icon-container{
+                    display:flex;
+                    justify-content:center;
+                    width: 100%;
+                    margin-top: 8px; /* Added some margin at the top if needed */
+                    margin-bottom: 12px; /* Increased space between icon and title */
+               }
+                .card-icon {
+                   display: block;
+                   /* margin: 0 auto; // Center handled by card-icon-container */
+                }
+                .card-title {
+                    font-weight: 600;
+                    margin-bottom: 8px; /* Increased space below title */
+                    font-size: 16px; /* Consider increasing slightly if descriptions are longer e.g. 17px or 18px */
+                    color: #f0f0f0;
+                }
+                .card-description {
+                    /* margin-bottom: 0; // Original value */
+                    font-size: 14px; /* Slightly increased font size for better readability */
+                    color: #aaaaaa;
+                    line-height: 1.5; /* Slightly increased line height */
+                    flex-grow: 1; /* Allows description to take available space */
+                    overflow-y: auto; /* Adds scroll if description is too long, though ideally content fits */
+                    padding-bottom: 8px; /* Add some padding at the bottom of the description area */
+                }
+            `}</style>
+        </>
+    );
+}

docs/package.json

@@ -7,8 +7,8 @@
   "license": "MIT",
   "dependencies": {
     "@vercel/analytics": "^1.1.1",
-    "docsgpt-react": "^0.5.0",
-    "next": "^14.2.26",
+    "docsgpt-react": "^0.5.1",
+    "next": "^15.3.3",
     "nextra": "^2.13.2",
     "nextra-theme-docs": "^2.13.2",
     "react": "^18.2.0",

docs/pages/Agents/_meta.json

@@ -0,0 +1,14 @@
+{
+  "basics": {
+    "title": "🤖 Agent Basics",
+    "href": "/Agents/basics"
+  },
+  "api": {
+    "title": "🔌 Agent API",
+    "href": "/Agents/api"
+  },
+  "webhooks": {
+    "title": "🪝 Agent Webhooks",
+    "href": "/Agents/webhooks"
+  }
+}

docs/pages/Agents/api.mdx

@@ -0,0 +1,227 @@
+---
+title: Interacting with Agents via API
+description: Learn how to programmatically interact with DocsGPT Agents using the streaming and non-streaming API endpoints.
+---
+
+import { Callout, Tabs } from 'nextra/components';
+
+# Interacting with Agents via API
+
+DocsGPT Agents can be accessed programmatically through a dedicated API, allowing you to integrate their specialized capabilities into your own applications, scripts, and workflows. This guide covers the two primary methods for interacting with an agent: the streaming API for real-time responses and the non-streaming API for a single, consolidated answer.
+
+When you use an API key generated for a specific agent, you do not need to pass `prompt`, `tools` etc. The agent's configuration (including its prompt, selected tools, and knowledge sources) is already associated with its unique API key. 
+
+### API Endpoints
+
+- **Non-Streaming:** `http://localhost:7091/api/answer`
+- **Streaming:** `http://localhost:7091/stream`
+
+<Callout type="info">
+For DocsGPT Cloud, use `https://gptcloud.arc53.com/` as the base URL.
+</Callout>
+
+For more technical details, you can explore the API swagger documentation available for the cloud version or your local instance.
+
+---
+
+## Non-Streaming API (`/api/answer`)
+
+This is a standard synchronous endpoint. It waits for the agent to fully process the request and returns a single JSON object with the complete answer. This is the simplest method and is ideal for backend processes where a real-time feed is not required.
+
+### Request
+
+-   **Endpoint:** `/api/answer`
+-   **Method:** `POST`
+-   **Payload:**
+    -   `question` (string, required): The user's query or input for the agent.
+    -   `api_key` (string, required): The unique API key for the agent you wish to interact with.
+    -   `history` (string, optional): A JSON string representing the conversation history, e.g., `[{\"prompt\": \"first question\", \"answer\": \"first answer\"}]`.
+
+### Response
+
+A single JSON object containing:
+-   `answer`: The complete, final answer from the agent.
+-   `sources`: A list of sources the agent consulted.
+-   `conversation_id`: The unique ID for the interaction.
+
+### Examples
+
+<Tabs items={['cURL', 'Python', 'JavaScript']}>
+  <Tabs.Tab>
+    ```bash
+    curl -X POST http://localhost:7091/api/answer \
+    -H "Content-Type: application/json" \
+    -d '{
+        "question": "your question here",
+        "api_key": "your_agent_api_key"
+    }'
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```python
+    import requests
+
+    API_URL = "http://localhost:7091/api/answer"
+    API_KEY = "your_agent_api_key"
+    QUESTION = "your question here"
+
+    response = requests.post(
+        API_URL,
+        json={"question": QUESTION, "api_key": API_KEY}
+    )
+
+    if response.status_code == 200:
+        print(response.json())
+    else:
+        print(f"Error: {response.status_code}")
+        print(response.text)
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```javascript
+    const apiUrl = 'http://localhost:7091/api/answer';
+    const apiKey = 'your_agent_api_key';
+    const question = 'your question here';
+
+    async function getAnswer() {
+    try {
+        const response = await fetch(apiUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ question, api_key: apiKey }),
+        });
+
+        if (!response.ok) {
+        throw new Error(`HTTP error! Status: ${response.status}`);
+        }
+
+        const data = await response.json();
+        console.log(data);
+    } catch (error) {
+        console.error("Failed to fetch answer:", error);
+    }
+    }
+
+    getAnswer();
+    ```
+  </Tabs.Tab>
+</Tabs>
+
+---
+
+## Streaming API (`/stream`)
+
+The `/stream` endpoint uses Server-Sent Events (SSE) to push data in real-time. This is ideal for applications where you want to display the response as it's being generated, such as in a live chatbot interface.
+
+### Request
+
+-   **Endpoint:** `/stream`
+-   **Method:** `POST`
+-   **Payload:** Same as the non-streaming API.
+
+### Response (SSE Stream)
+
+The stream consists of multiple `data:` events, each containing a JSON object. Your client should listen for these events and process them based on their `type`.
+
+**Event Types:**
+-   `answer`: A chunk of the agent's final answer.
+-   `source`: A document or source used by the agent.
+-   `thought`: A reasoning step from the agent (for ReAct agents).
+-   `id`: The unique `conversation_id` for the interaction.
+-   `error`: An error message.
+-   `end`: A final message indicating the stream has concluded.
+
+### Examples
+
+<Tabs items={['cURL', 'Python', 'JavaScript']}>
+  <Tabs.Tab>
+    ```bash
+    curl -X POST http://localhost:7091/stream \
+    -H "Content-Type: application/json" \
+    -H "Accept: text/event-stream" \
+    -d '{
+        "question": "your question here",
+        "api_key": "your_agent_api_key"
+    }'
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```python
+    import requests
+    import json
+
+    API_URL = "http://localhost:7091/stream"
+    payload = {
+        "question": "your question here",
+        "api_key": "your_agent_api_key"
+    }
+
+    with requests.post(API_URL, json=payload, stream=True) as r:
+        for line in r.iter_lines():
+            if line:
+                decoded_line = line.decode('utf-8')
+                if decoded_line.startswith('data: '):
+                    try:
+                        data = json.loads(decoded_line[6:])
+                        print(data)
+                    except json.JSONDecodeError:
+                        pass
+    ```
+  </Tabs.Tab>
+  <Tabs.Tab>
+    ```javascript
+    const apiUrl = 'http://localhost:7091/stream';
+    const apiKey = 'your_agent_api_key';
+    const question = 'your question here';
+
+    async function getStream() {
+    try {
+        const response = await fetch(apiUrl, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'text/event-stream'
+        },
+        // Corrected line: 'apiKey' is changed to 'api_key'
+        body: JSON.stringify({ question, api_key: apiKey }),
+        });
+
+        if (!response.ok) {
+        throw new Error(`HTTP error! Status: ${response.status}`);
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+
+        while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        const chunk = decoder.decode(value, { stream: true });
+        // Note: This parsing method assumes each chunk contains whole lines.
+        // For a more robust production implementation, buffer the chunks
+        // and process them line by line.
+        const lines = chunk.split('\n');
+        
+        for (const line of lines) {
+            if (line.startsWith('data: ')) {
+            try {
+                const data = JSON.parse(line.substring(6));
+                console.log(data);
+            } catch (e) {
+                console.error("Failed to parse JSON from SSE event:", e);
+            }
+            }
+        }
+        }
+    } catch (error) {
+        console.error("Failed to fetch stream:", error);
+    }
+    }
+
+    getStream();
+    ```
+  </Tabs.Tab>
+</Tabs>