chore(deps): bump the npm_and_yarn group across 1 directory with 4 updates

Bumps the npm_and_yarn group with 3 updates in the /docs directory: [next](https://github.com/vercel/next.js), [dompurify](https://github.com/cure53/DOMPurify) and [mermaid](https://github.com/mermaid-js/mermaid).


Updates `next` from 15.3.3 to 15.5.6
- [Release notes](https://github.com/vercel/next.js/releases)
- [Changelog](https://github.com/vercel/next.js/blob/canary/release.js)
- [Commits](https://github.com/vercel/next.js/compare/v15.3.3...v15.5.6)

Updates `dompurify` from 3.1.6 to 3.3.0
- [Release notes](https://github.com/cure53/DOMPurify/releases)
- [Commits](https://github.com/cure53/DOMPurify/compare/3.1.6...3.3.0)

Updates `mermaid` from 10.9.3 to 10.9.5
- [Release notes](https://github.com/mermaid-js/mermaid/releases)
- [Commits](https://github.com/mermaid-js/mermaid/compare/v10.9.3...v10.9.5)

Updates `mermaid` from 10.9.3 to 11.12.1
- [Release notes](https://github.com/mermaid-js/mermaid/releases)
- [Commits](https://github.com/mermaid-js/mermaid/compare/v10.9.3...v10.9.5)

Updates `micromatch` from 4.0.5 to 4.0.8
- [Release notes](https://github.com/micromatch/micromatch/releases)
- [Changelog](https://github.com/micromatch/micromatch/blob/master/CHANGELOG.md)
- [Commits](https://github.com/micromatch/micromatch/compare/4.0.5...4.0.8)

---
updated-dependencies:
- dependency-name: next
  dependency-version: 15.5.6
  dependency-type: direct:production
  dependency-group: npm_and_yarn
- dependency-name: dompurify
  dependency-version: 3.3.0
  dependency-type: indirect
  dependency-group: npm_and_yarn
- dependency-name: mermaid
  dependency-version: 10.9.5
  dependency-type: indirect
  dependency-group: npm_and_yarn
- dependency-name: mermaid
  dependency-version: 11.12.1
  dependency-type: indirect
  dependency-group: npm_and_yarn
- dependency-name: micromatch
  dependency-version: 4.0.8
  dependency-type: indirect
  dependency-group: npm_and_yarn
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/dependabot.yml

@@ -13,7 +13,11 @@ updates:
     directory: "/frontend" # Location of package manifests
     schedule:
       interval: "daily"
+  - package-ecosystem: "npm"
+    directory: "/extensions/react-widget"
+    schedule:
+      interval: "daily"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "daily"

.github/styles/DocsGPT/Spelling.yml

@@ -0,0 +1,11 @@
+extends: spelling
+level: warning
+message: "Did you really mean '%s'?"
+ignore:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/build/**"
+  - "**/coverage/**"
+  - "**/public/**"
+  - "**/static/**"
+vocab: DocsGPT

.github/styles/config/vocabularies/DocsGPT/accept.txt

@@ -0,0 +1,46 @@
+Ollama
+Qdrant
+Milvus
+Chatwoot
+Nextra
+VSCode
+npm
+LLMs
+APIs
+Groq
+SGLang
+LMDeploy
+OAuth
+Vite
+LLM
+JSONPath
+UIs
+configs
+uncomment
+qdrant
+vectorstore
+docsgpt
+llm
+GPUs
+kubectl
+Lightsail
+enqueues
+chatbot
+VSCode's
+Shareability
+feedbacks
+automations
+Premade
+Signup
+Repo
+repo
+env
+URl
+agentic
+llama_cpp
+parsable
+SDKs
+boolean
+bool
+hardcode
+EOL

.github/workflows/pytest.yml

@@ -16,15 +16,15 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install pytest pytest-cov
           cd application
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          cd ../tests
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
       - name: Test with pytest and generate coverage report
         run: |
-          python -m pytest --cov=application --cov-report=xml
+          python -m pytest --cov=application --cov-report=xml --cov-report=term-missing
       - name: Upload coverage reports to Codecov
         if: github.event_name == 'pull_request' && matrix.python-version == '3.12'
         uses: codecov/codecov-action@v5
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-

.github/workflows/vale.yml

@@ -0,0 +1,26 @@
+name: Vale Documentation Linter
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**/*.md'
+      - 'docs/**/*.mdx'
+      - '**/*.md'
+      - '.vale.ini'
+      - '.github/styles/**'
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Vale linter
+        uses: errata-ai/vale-action@v2
+        with:
+          files: docs
+          fail_on_error: false
+          version: 3.0.5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -3,6 +3,7 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+experiments
 # C extensions
 *.so
 *.next

.vale.ini

@@ -0,0 +1,5 @@
+MinAlertLevel = warning
+StylesPath = .github/styles
+
+[*.{md,mdx}]
+BasedOnStyles = DocsGPT

CONTRIBUTING.md

@@ -147,5 +147,5 @@ Here's a step-by-step guide on how to contribute to DocsGPT:
 Thank you for considering contributing to DocsGPT! 🙏
 
 ## Questions/collaboration
-Feel free to join our [Discord](https://discord.gg/n5BX8dh8rU). We're very friendly and welcoming to new contributors, so don't hesitate to reach out.
+Feel free to join our [Discord](https://discord.gg/vN7YFfdMpj). We're very friendly and welcoming to new contributors, so don't hesitate to reach out.
 # Thank you so much for considering to contributing DocsGPT!🙏

HACKTOBERFEST.md

@@ -3,6 +3,7 @@
 Welcome, contributors! We're excited to announce that DocsGPT is participating in Hacktoberfest. Get involved by submitting meaningful pull requests.
 
 All Meaningful contributors with accepted PRs that were created for issues with the `hacktoberfest` label (set by our maintainer team: dartpain, siiddhantt, pabik, ManishMadan2882) will receive a cool T-shirt! 🤩.
+<img width="1331" height="678" alt="hacktoberfest-mocks-preview" src="https://github.com/user-attachments/assets/633f6377-38db-48f5-b519-a8b3855a9eb4" />
 
 Fill in [this form](https://forms.gle/Npaba4n9Epfyx56S8
 ) after your PR was merged please 
@@ -31,8 +32,8 @@ Non-Code Contributions:
 - Before contributing check existing [issues](https://github.com/arc53/DocsGPT/issues) or [create](https://github.com/arc53/DocsGPT/issues/new/choose) an issue and wait to get assigned.
 - Once you are finished with your contribution, please fill in this [form](https://forms.gle/Npaba4n9Epfyx56S8).
 - Refer to the [Documentation](https://docs.docsgpt.cloud/).
-- Feel free to join our [Discord](https://discord.gg/n5BX8dh8rU) server. We're here to help newcomers, so don't hesitate to jump in! Join us [here](https://discord.gg/n5BX8dh8rU).
+- Feel free to join our [Discord](https://discord.gg/vN7YFfdMpj) server. We're here to help newcomers, so don't hesitate to jump in! Join us [here](https://discord.gg/vN7YFfdMpj).
   
 Thank you very much for considering contributing to DocsGPT during Hacktoberfest! 🙏 Your contributions (not just simple typos) could earn you a stylish new t-shirt.
 
-We will publish a t-shirt desing later into the October.
+We will publish a t-shirt design later into the October.

README.md

@@ -16,10 +16,10 @@
   <a href="https://github.com/arc53/DocsGPT">![link to main GitHub showing Forks number](https://img.shields.io/github/forks/arc53/docsgpt?style=social)</a>
   <a href="https://github.com/arc53/DocsGPT/blob/main/LICENSE">![link to license file](https://img.shields.io/github/license/arc53/docsgpt)</a>
   <a href="https://www.bestpractices.dev/projects/9907"><img src="https://www.bestpractices.dev/projects/9907/badge"></a>
-  <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://discord.gg/vN7YFfdMpj">![link to discord](https://img.shields.io/discord/1070046503302877216)</a>
+  <a href="https://x.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>
+<a href="https://docs.docsgpt.cloud/quickstart">⚡️ Quickstart</a> • <a href="https://app.docsgpt.cloud/">☁️ Cloud Version</a> • <a href="https://discord.gg/vN7YFfdMpj">💬 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>
@@ -67,8 +67,8 @@
 - [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)
+- [x] Add OAuth 2.0 authentication for MCP (September 2025)
+- [ ] SharePoint integration (October 2025)
 - [ ] Deep Agents (October 2025)
 - [ ] Agent scheduling
 
@@ -118,7 +118,7 @@ A more detailed [Quickstart](https://docs.docsgpt.cloud/quickstart) is available
    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.
+Either script will guide you through setting up DocsGPT. Five options available: using the public API, running locally, connecting to a local inference engine, using a cloud API provider, or build the docker image locally. Scripts will automatically configure your `.env` file and handle necessary downloads and installations based on your chosen option.
 
 **Navigate to http://localhost:5173/**
 

application/agents/agent_creator.py

@@ -1,5 +1,8 @@
 from application.agents.classic_agent import ClassicAgent
 from application.agents.react_agent import ReActAgent
+import logging
+
+logger = logging.getLogger(__name__)
 
 
 class AgentCreator:
@@ -13,4 +16,5 @@ class AgentCreator:
         agent_class = cls.agents.get(type.lower())
         if not agent_class:
             raise ValueError(f"No agent class found for type {type}")
+        
         return agent_class(*args, **kwargs)

application/agents/base.py

@@ -12,7 +12,6 @@ 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__)
 
@@ -22,23 +21,28 @@ class BaseAgent(ABC):
         self,
         endpoint: str,
         llm_name: str,
-        gpt_model: str,
+        model_id: str,
         api_key: str,
         user_api_key: Optional[str] = None,
         prompt: str = "",
         chat_history: Optional[List[Dict]] = None,
+        retrieved_docs: Optional[List[Dict]] = None,
         decoded_token: Optional[Dict] = None,
         attachments: Optional[List[Dict]] = None,
         json_schema: Optional[Dict] = None,
+        limited_token_mode: Optional[bool] = False,
+        token_limit: Optional[int] = settings.DEFAULT_AGENT_LIMITS["token_limit"],
+        limited_request_mode: Optional[bool] = False,
+        request_limit: Optional[int] = settings.DEFAULT_AGENT_LIMITS["request_limit"],
     ):
         self.endpoint = endpoint
         self.llm_name = llm_name
-        self.gpt_model = gpt_model
+        self.model_id = model_id
         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.user: str = self.decoded_token.get("sub")
         self.tool_config: Dict = {}
         self.tools: List[Dict] = []
         self.tool_calls: List[Dict] = []
@@ -48,22 +52,28 @@ class BaseAgent(ABC):
             api_key=api_key,
             user_api_key=user_api_key,
             decoded_token=decoded_token,
+            model_id=model_id,
         )
+        self.retrieved_docs = retrieved_docs or []
         self.llm_handler = LLMHandlerCreator.create_handler(
             llm_name if llm_name else "default"
         )
         self.attachments = attachments or []
         self.json_schema = json_schema
+        self.limited_token_mode = limited_token_mode
+        self.token_limit = token_limit
+        self.limited_request_mode = limited_request_mode
+        self.request_limit = request_limit
 
     @log_activity()
     def gen(
-        self, query: str, retriever: BaseRetriever, log_context: LogContext = None
+        self, query: str, log_context: LogContext = None
     ) -> Generator[Dict, None, None]:
-        yield from self._gen_inner(query, retriever, log_context)
+        yield from self._gen_inner(query, log_context)
 
     @abstractmethod
     def _gen_inner(
-        self, query: str, retriever: BaseRetriever, log_context: LogContext
+        self, query: str, log_context: LogContext
     ) -> Generator[Dict, None, None]:
         pass
 
@@ -142,6 +152,7 @@ class BaseAgent(ABC):
         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)
@@ -156,13 +167,14 @@ class BaseAgent(ABC):
             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,
@@ -173,7 +185,6 @@ class BaseAgent(ABC):
             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,
@@ -213,18 +224,25 @@ class BaseAgent(ABC):
                 ):
                     target_dict[param] = value
         tm = ToolManager(config={})
+
+        # Prepare tool_config and add tool_id for memory tools
+
+        if tool_data["name"] == "api_tool":
+            tool_config = {
+                "url": tool_data["config"]["actions"][action_name]["url"],
+                "method": tool_data["config"]["actions"][action_name]["method"],
+                "headers": headers,
+                "query_params": query_params,
+            }
+        else:
+            tool_config = tool_data["config"].copy() if tool_data["config"] else {}
+            # Add tool_id from MongoDB _id for tools that need instance isolation (like memory tool)
+            # Use MongoDB _id if available, otherwise fall back to enumerated tool_id
+
+            tool_config["tool_id"] = str(tool_data.get("_id", tool_id))
         tool = tm.load_tool(
             tool_data["name"],
-            tool_config=(
-                {
-                    "url": tool_data["config"]["actions"][action_name]["url"],
-                    "method": tool_data["config"]["actions"][action_name]["method"],
-                    "headers": headers,
-                    "query_params": query_params,
-                }
-                if tool_data["name"] == "api_tool"
-                else tool_data["config"]
-            ),
+            tool_config=tool_config,
             user_id=self.user,  # Pass user ID for MCP tools credential decryption
         )
         if tool_data["name"] == "api_tool":
@@ -262,24 +280,14 @@ class BaseAgent(ABC):
         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}]
+        """Build messages using pre-rendered system prompt"""
+        messages = [{"role": "system", "content": system_prompt}]
 
         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.append({"role": "user", "content": i["prompt"]})
+                messages.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())
@@ -299,29 +307,17 @@ class BaseAgent(ABC):
                         }
                     }
 
-                    messages_combine.append(
+                    messages.append(
                         {"role": "assistant", "content": [function_call_dict]}
                     )
-                    messages_combine.append(
+                    messages.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
+        messages.append({"role": "user", "content": query})
+        return messages
 
     def _llm_gen(self, messages: List[Dict], log_context: Optional[LogContext] = None):
-        gen_kwargs = {"model": self.gpt_model, "messages": messages}
+        gen_kwargs = {"model": self.model_id, "messages": messages}
 
         if (
             hasattr(self.llm, "_supports_tools")
@@ -329,7 +325,6 @@ class BaseAgent(ABC):
             and self.tools
         ):
             gen_kwargs["tools"] = self.tools
-
         if (
             self.json_schema
             and hasattr(self.llm, "_supports_structured_output")
@@ -343,7 +338,6 @@ class BaseAgent(ABC):
                     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:

application/agents/classic_agent.py

@@ -1,32 +1,20 @@
+import logging
 from typing import Dict, Generator
+
 from application.agents.base import BaseAgent
 from application.logging import LogContext
-from application.retriever.base import BaseRetriever
-import logging
 
 logger = logging.getLogger(__name__)
 
 
 class ClassicAgent(BaseAgent):
-    """A simplified agent with clear execution flow.
-
-    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.
-    """
+    """A simplified agent with clear execution flow"""
 
     def _gen_inner(
-        self, query: str, retriever: BaseRetriever, log_context: LogContext
+        self, query: str, log_context: LogContext
     ) -> Generator[Dict, None, None]:
-        # Step 1: Retrieve relevant data
-        retrieved_data = self._retriever_search(retriever, query, log_context)
+        """Core generator function for ClassicAgent execution flow"""
 
-        # Step 2: Prepare tools
         tools_dict = (
             self._get_user_tools(self.user)
             if not self.user_api_key
@@ -34,20 +22,16 @@ class ClassicAgent(BaseAgent):
         )
         self._prepare_tools(tools_dict)
 
-        # Step 3: Build and process messages
-        messages = self._build_messages(self.prompt, query, retrieved_data)
+        messages = self._build_messages(self.prompt, query)
         llm_response = self._llm_gen(messages, log_context)
 
-        # 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 {"sources": self.retrieved_docs}
         yield {"tool_calls": self._get_truncated_tool_calls()}
 
-        # Log tool calls for debugging
         log_context.stacks.append(
             {"component": "agent", "data": {"tool_calls": self.tool_calls.copy()}}
         )

application/agents/react_agent.py

@@ -1,229 +1,238 @@
-import os
-from typing import Dict, Generator, List, Any
 import logging
+import os
+from typing import Any, Dict, Generator, List
 
 from application.agents.base import BaseAgent
 from application.logging import build_stack_data, LogContext
-from application.retriever.base import BaseRetriever
 
 logger = logging.getLogger(__name__)
 
+MAX_ITERATIONS_REASONING = 10
+
 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()
+    PLANNING_PROMPT_TEMPLATE = f.read()
 with open(
-    os.path.join(current_dir, "application/prompts", "react_final_prompt.txt"),
-    "r",
+    os.path.join(current_dir, "application/prompts", "react_final_prompt.txt"), "r"
 ) as f:
-    final_prompt_template = f.read()
-    
-MAX_ITERATIONS_REASONING = 10
+    FINAL_PROMPT_TEMPLATE = f.read()
+
 
 class ReActAgent(BaseAgent):
+    """
+    Research and Action (ReAct) Agent - Advanced reasoning agent with iterative planning.
+
+    Implements a think-act-observe loop for complex problem-solving:
+    1. Creates a strategic plan based on the query
+    2. Executes tools and gathers observations
+    3. Iteratively refines approach until satisfied
+    4. Synthesizes final answer from all observations
+    """
+
     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
+        self, query: str, 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)
+        """Execute ReAct reasoning loop with planning, action, and observation cycles"""
 
-        if self.user_api_key:
-            tools_dict = self._get_tools(self.user_api_key)
-        else:
-            tools_dict = self._get_user_tools(self.user)
+        self._reset_state()
+
+        tools_dict = (
+            self._get_tools(self.user_api_key)
+            if self.user_api_key
+            else 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}")
+        for iteration in range(1, MAX_ITERATIONS_REASONING + 1):
+            yield {"thought": f"Reasoning... (iteration {iteration})\n\n"}
 
+            yield from self._planning_phase(query, log_context)
 
-            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]}...'"
+            if not self.plan:
+                logger.warning(
+                    f"ReActAgent: No plan generated in iteration {iteration}"
                 )
-                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
+            self.observations.append(f"Plan (iteration {iteration}): {self.plan}")
 
-        # 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.")
+            satisfied = yield from self._execution_phase(query, tools_dict, log_context)
 
-    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))
+            if satisfied:
+                logger.info("ReActAgent: Goal satisfied, stopping reasoning loop")
+                break
+        yield from self._synthesis_phase(query, log_context)
 
-        messages = [{"role": "user", "content": plan_prompt_filled}]
+    def _reset_state(self):
+        """Reset agent state for new query"""
+        self.plan = ""
+        self.observations = []
 
-        plan_stream_from_llm = self.llm.gen_stream(
-            model=self.gpt_model, messages=messages, tools=getattr(self, 'tools', None) # Use self.tools
+    def _planning_phase(
+        self, query: str, log_context: LogContext
+    ) -> Generator[Dict, None, None]:
+        """Generate strategic plan for query"""
+        logger.info("ReActAgent: Creating plan...")
+
+        plan_prompt = self._build_planning_prompt(query)
+        messages = [{"role": "user", "content": plan_prompt}]
+
+        plan_stream = self.llm.gen_stream(
+            model=self.model_id,
+            messages=messages,
+            tools=self.tools if self.tools else None,
         )
+
         if log_context:
-            data = build_stack_data(self.llm)
-            log_context.stacks.append({"component": "planning_llm", "data": data})
+            log_context.stacks.append(
+                {"component": "planning_llm", "data": build_stack_data(self.llm)}
+            )
+        plan_parts = []
+        for chunk in plan_stream:
+            content = self._extract_content(chunk)
+            if content:
+                plan_parts.append(content)
+                yield {"thought": content}
+        self.plan = "".join(plan_parts)
 
-        for chunk in plan_stream_from_llm:
-            content_piece = self._extract_content_from_llm_response(chunk)
-            if content_piece:
-                yield content_piece
+    def _execution_phase(
+        self, query: str, tools_dict: Dict, log_context: LogContext
+    ) -> Generator[bool, None, None]:
+        """Execute plan with tool calls and observations"""
+        execution_prompt = self._build_execution_prompt(query)
+        messages = self._build_messages(execution_prompt, query)
 
-    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.")
+        llm_response = self._llm_gen(messages, log_context)
+        initial_content = self._extract_content(llm_response)
 
-        final_answer_prompt_filled = final_prompt_template.format(
-            query=query, observations=observation_string
+        if initial_content:
+            self.observations.append(f"Initial response: {initial_content}")
+        processed_response = self._llm_handler(
+            llm_response, tools_dict, messages, log_context
         )
 
-        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
-        )
+        for tool_call in self.tool_calls:
+            observation = (
+                f"Executed: {tool_call.get('tool_name', 'Unknown')} "
+                f"with args {tool_call.get('arguments', {})}. "
+                f"Result: {str(tool_call.get('result', ''))[:200]}"
+            )
+            self.observations.append(observation)
+        final_content = self._extract_content(processed_response)
+        if final_content:
+            self.observations.append(f"Response after tools: {final_content}")
         if log_context:
-            data = build_stack_data(self.llm)
-            log_context.stacks.append({"component": "final_answer_llm", "data": data})
+            log_context.stacks.append(
+                {
+                    "component": "agent_tool_calls",
+                    "data": {"tool_calls": self.tool_calls.copy()},
+                }
+            )
+        yield {"sources": self.retrieved_docs}
+        yield {"tool_calls": self._get_truncated_tool_calls()}
 
-        for chunk in final_answer_stream_from_llm:
-            content_piece = self._extract_content_from_llm_response(chunk)
-            if content_piece:
-                yield content_piece
+        return "SATISFIED" in (final_content or "")
+
+    def _synthesis_phase(
+        self, query: str, log_context: LogContext
+    ) -> Generator[Dict, None, None]:
+        """Synthesize final answer from all observations"""
+        logger.info("ReActAgent: Generating final answer...")
+
+        final_prompt = self._build_final_answer_prompt(query)
+        messages = [{"role": "user", "content": final_prompt}]
+
+        final_stream = self.llm.gen_stream(
+            model=self.model_id, messages=messages, tools=None
+        )
+
+        if log_context:
+            log_context.stacks.append(
+                {"component": "final_answer_llm", "data": build_stack_data(self.llm)}
+            )
+        for chunk in final_stream:
+            content = self._extract_content(chunk)
+            if content:
+                yield {"answer": content}
+
+    def _build_planning_prompt(self, query: str) -> str:
+        """Build planning phase prompt"""
+        prompt = PLANNING_PROMPT_TEMPLATE.replace("{query}", query)
+        prompt = prompt.replace("{prompt}", self.prompt or "")
+        prompt = prompt.replace("{summaries}", "")
+        prompt = prompt.replace("{observations}", "\n".join(self.observations))
+        return prompt
+
+    def _build_execution_prompt(self, query: str) -> str:
+        """Build execution phase prompt with plan and observations"""
+        observations_str = "\n".join(self.observations)
+
+        if len(observations_str) > 20000:
+            observations_str = observations_str[:20000] + "\n...[truncated]"
+        return (
+            f"{self.prompt or ''}\n\n"
+            f"Follow this plan:\n{self.plan}\n\n"
+            f"Observations:\n{observations_str}\n\n"
+            f"If sufficient data exists to answer '{query}', respond with 'SATISFIED'. "
+            f"Otherwise, continue executing the plan."
+        )
+
+    def _build_final_answer_prompt(self, query: str) -> str:
+        """Build final synthesis prompt"""
+        observations_str = "\n".join(self.observations)
+
+        if len(observations_str) > 10000:
+            observations_str = observations_str[:10000] + "\n...[truncated]"
+            logger.warning("ReActAgent: Observations truncated for final answer")
+        return FINAL_PROMPT_TEMPLATE.format(query=query, observations=observations_str)
+
+    def _extract_content(self, response: Any) -> str:
+        """Extract text content from various LLM response formats"""
+        if not response:
+            return ""
+        collected = []
+
+        if isinstance(response, str):
+            return response
+        if hasattr(response, "message") and hasattr(response.message, "content"):
+            if response.message.content:
+                return response.message.content
+        if hasattr(response, "choices") and response.choices:
+            if hasattr(response.choices[0], "message"):
+                content = response.choices[0].message.content
+                if content:
+                    return content
+        if hasattr(response, "content") and isinstance(response.content, list):
+            if response.content and hasattr(response.content[0], "text"):
+                return response.content[0].text
+        try:
+            for chunk in response:
+                content_piece = ""
+
+                if hasattr(chunk, "choices") and chunk.choices:
+                    if hasattr(chunk.choices[0], "delta"):
+                        delta_content = chunk.choices[0].delta.content
+                        if delta_content:
+                            content_piece = delta_content
+                elif hasattr(chunk, "type") and chunk.type == "content_block_delta":
+                    if hasattr(chunk, "delta") and hasattr(chunk.delta, "text"):
+                        content_piece = chunk.delta.text
+                elif isinstance(chunk, str):
+                    content_piece = chunk
+                if content_piece:
+                    collected.append(content_piece)
+        except (TypeError, AttributeError):
+            logger.debug(
+                f"Response not iterable or unexpected format: {type(response)}"
+            )
+        except Exception as e:
+            logger.error(f"Error extracting content: {e}")
+        return "".join(collected)

application/agents/tools/mcp_tool.py

@@ -37,7 +37,7 @@ _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.
+    Connect to remote Model Context Protocol (MCP) servers to access dynamic tools and resources.
     """
 
     def __init__(self, config: Dict[str, Any], user_id: Optional[str] = None):

application/agents/tools/memory.py

@@ -0,0 +1,546 @@
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import re
+import uuid
+
+from .base import Tool
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+
+
+class MemoryTool(Tool):
+    """Memory
+
+    Stores and retrieves information across conversations through a memory file directory.
+    """
+
+    def __init__(self, tool_config: Optional[Dict[str, Any]] = None, user_id: Optional[str] = None) -> None:
+        """Initialize the tool.
+
+        Args:
+            tool_config: Optional tool configuration. Should include:
+                - tool_id: Unique identifier for this memory tool instance (from user_tools._id)
+                           This ensures each user's tool configuration has isolated memories
+            user_id: The authenticated user's id (should come from decoded_token["sub"]).
+        """
+        self.user_id: Optional[str] = user_id
+
+        # Get tool_id from configuration (passed from user_tools._id in production)
+        # In production, tool_id is the MongoDB ObjectId string from user_tools collection
+        if tool_config and "tool_id" in tool_config:
+            self.tool_id = tool_config["tool_id"]
+        elif user_id:
+            # Fallback for backward compatibility or testing
+            self.tool_id = f"default_{user_id}"
+        else:
+            # Last resort fallback (shouldn't happen in normal use)
+            self.tool_id = str(uuid.uuid4())
+
+        db = MongoDB.get_client()[settings.MONGO_DB_NAME]
+        self.collection = db["memories"]
+
+    # -----------------------------
+    # Action implementations
+    # -----------------------------
+    def execute_action(self, action_name: str, **kwargs: Any) -> str:
+        """Execute an action by name.
+
+        Args:
+            action_name: One of view, create, str_replace, insert, delete, rename.
+            **kwargs: Parameters for the action.
+
+        Returns:
+            A human-readable string result.
+        """
+        if not self.user_id:
+            return "Error: MemoryTool requires a valid user_id."
+
+        if action_name == "view":
+            return self._view(
+                kwargs.get("path", "/"),
+                kwargs.get("view_range")
+            )
+
+        if action_name == "create":
+            return self._create(
+                kwargs.get("path", ""),
+                kwargs.get("file_text", "")
+            )
+
+        if action_name == "str_replace":
+            return self._str_replace(
+                kwargs.get("path", ""),
+                kwargs.get("old_str", ""),
+                kwargs.get("new_str", "")
+            )
+
+        if action_name == "insert":
+            return self._insert(
+                kwargs.get("path", ""),
+                kwargs.get("insert_line", 1),
+                kwargs.get("insert_text", "")
+            )
+
+        if action_name == "delete":
+            return self._delete(kwargs.get("path", ""))
+
+        if action_name == "rename":
+            return self._rename(
+                kwargs.get("old_path", ""),
+                kwargs.get("new_path", "")
+            )
+
+        return f"Unknown action: {action_name}"
+
+    def get_actions_metadata(self) -> List[Dict[str, Any]]:
+        """Return JSON metadata describing supported actions for tool schemas."""
+        return [
+            {
+                "name": "view",
+                "description": "Shows directory contents or file contents with optional line ranges.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Path to file or directory (e.g., /notes.txt or /project/ or /)."
+                        },
+                        "view_range": {
+                            "type": "array",
+                            "items": {"type": "integer"},
+                            "description": "Optional [start_line, end_line] to view specific lines (1-indexed)."
+                        }
+                    },
+                    "required": ["path"]
+                },
+            },
+            {
+                "name": "create",
+                "description": "Create or overwrite a file.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "File path to create (e.g., /notes.txt or /project/task.txt)."
+                        },
+                        "file_text": {
+                            "type": "string",
+                            "description": "Content to write to the file."
+                        }
+                    },
+                    "required": ["path", "file_text"]
+                },
+            },
+            {
+                "name": "str_replace",
+                "description": "Replace text in a file.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "File path (e.g., /notes.txt)."
+                        },
+                        "old_str": {
+                            "type": "string",
+                            "description": "String to find."
+                        },
+                        "new_str": {
+                            "type": "string",
+                            "description": "String to replace with."
+                        }
+                    },
+                    "required": ["path", "old_str", "new_str"]
+                },
+            },
+            {
+                "name": "insert",
+                "description": "Insert text at a specific line in a file.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "File path (e.g., /notes.txt)."
+                        },
+                        "insert_line": {
+                            "type": "integer",
+                            "description": "Line number to insert at (1-indexed)."
+                        },
+                        "insert_text": {
+                            "type": "string",
+                            "description": "Text to insert."
+                        }
+                    },
+                    "required": ["path", "insert_line", "insert_text"]
+                },
+            },
+            {
+                "name": "delete",
+                "description": "Delete a file or directory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": "Path to delete (e.g., /notes.txt or /project/)."
+                        }
+                    },
+                    "required": ["path"]
+                },
+            },
+            {
+                "name": "rename",
+                "description": "Rename or move a file/directory.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "old_path": {
+                            "type": "string",
+                            "description": "Current path (e.g., /old.txt)."
+                        },
+                        "new_path": {
+                            "type": "string",
+                            "description": "New path (e.g., /new.txt)."
+                        }
+                    },
+                    "required": ["old_path", "new_path"]
+                },
+            },
+        ]
+
+    def get_config_requirements(self) -> Dict[str, Any]:
+        """Return configuration requirements."""
+        return {}
+
+    # -----------------------------
+    # Path validation
+    # -----------------------------
+    def _validate_path(self, path: str) -> Optional[str]:
+        """Validate and normalize path.
+
+        Args:
+            path: User-provided path.
+
+        Returns:
+            Normalized path or None if invalid.
+        """
+        if not path:
+            return None
+
+        # Remove any leading/trailing whitespace
+        path = path.strip()
+
+        # Preserve whether path ends with / (indicates directory)
+        is_directory = path.endswith("/")
+
+        # Ensure path starts with / for consistency
+        if not path.startswith("/"):
+            path = "/" + path
+
+        # Check for directory traversal patterns
+        if ".." in path or path.count("//") > 0:
+            return None
+
+        # Normalize the path
+        try:
+            # Convert to Path object and resolve to canonical form
+            normalized = str(Path(path).as_posix())
+
+            # Ensure it still starts with /
+            if not normalized.startswith("/"):
+                return None
+
+            # Preserve trailing slash for directories
+            if is_directory and not normalized.endswith("/") and normalized != "/":
+                normalized = normalized + "/"
+
+            return normalized
+        except Exception:
+            return None
+
+    # -----------------------------
+    # Internal helpers
+    # -----------------------------
+    def _view(self, path: str, view_range: Optional[List[int]] = None) -> str:
+        """View directory contents or file contents."""
+        validated_path = self._validate_path(path)
+        if not validated_path:
+            return "Error: Invalid path."
+
+        # Check if viewing directory (ends with / or is root)
+        if validated_path == "/" or validated_path.endswith("/"):
+            return self._view_directory(validated_path)
+
+        # Otherwise view file
+        return self._view_file(validated_path, view_range)
+
+    def _view_directory(self, path: str) -> str:
+        """List files in a directory."""
+        # Ensure path ends with / for proper prefix matching
+        search_path = path if path.endswith("/") else path + "/"
+
+        # Find all files that start with this directory path
+        query = {
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": {"$regex": f"^{re.escape(search_path)}"}
+        }
+
+        docs = list(self.collection.find(query, {"path": 1}))
+
+        if not docs:
+            return f"Directory: {path}\n(empty)"
+
+        # Extract filenames relative to the directory
+        files = []
+        for doc in docs:
+            file_path = doc["path"]
+            # Remove the directory prefix
+            if file_path.startswith(search_path):
+                relative = file_path[len(search_path):]
+                if relative:
+                    files.append(relative)
+
+        files.sort()
+        file_list = "\n".join(f"- {f}" for f in files)
+        return f"Directory: {path}\n{file_list}"
+
+    def _view_file(self, path: str, view_range: Optional[List[int]] = None) -> str:
+        """View file contents with optional line range."""
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id, "path": path})
+
+        if not doc or not doc.get("content"):
+            return f"Error: File not found: {path}"
+
+        content = str(doc["content"])
+
+        # Apply view_range if specified
+        if view_range and len(view_range) == 2:
+            lines = content.split("\n")
+            start, end = view_range
+            # Convert to 0-indexed
+            start_idx = max(0, start - 1)
+            end_idx = min(len(lines), end)
+
+            if start_idx >= len(lines):
+                return f"Error: Line range out of bounds. File has {len(lines)} lines."
+
+            selected_lines = lines[start_idx:end_idx]
+            # Add line numbers (enumerate with 1-based start)
+            numbered_lines = [f"{i}: {line}" for i, line in enumerate(selected_lines, start=start)]
+            return "\n".join(numbered_lines)
+
+        return content
+
+    def _create(self, path: str, file_text: str) -> str:
+        """Create or overwrite a file."""
+        validated_path = self._validate_path(path)
+        if not validated_path:
+            return "Error: Invalid path."
+
+        if validated_path == "/" or validated_path.endswith("/"):
+            return "Error: Cannot create a file at directory path."
+
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_path},
+            {
+                "$set": {
+                    "content": file_text,
+                    "updated_at": datetime.now()
+                }
+            },
+            upsert=True
+        )
+
+        return f"File created: {validated_path}"
+
+    def _str_replace(self, path: str, old_str: str, new_str: str) -> str:
+        """Replace text in a file."""
+        validated_path = self._validate_path(path)
+        if not validated_path:
+            return "Error: Invalid path."
+
+        if not old_str:
+            return "Error: old_str is required."
+
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_path})
+
+        if not doc or not doc.get("content"):
+            return f"Error: File not found: {validated_path}"
+
+        current_content = str(doc["content"])
+
+        # Check if old_str exists (case-insensitive)
+        if old_str.lower() not in current_content.lower():
+            return f"Error: String '{old_str}' not found in file."
+
+        # Replace the string (case-insensitive)
+        import re as regex_module
+        updated_content = regex_module.sub(regex_module.escape(old_str), new_str, current_content, flags=regex_module.IGNORECASE)
+
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_path},
+            {
+                "$set": {
+                    "content": updated_content,
+                    "updated_at": datetime.now()
+                }
+            }
+        )
+
+        return f"File updated: {validated_path}"
+
+    def _insert(self, path: str, insert_line: int, insert_text: str) -> str:
+        """Insert text at a specific line."""
+        validated_path = self._validate_path(path)
+        if not validated_path:
+            return "Error: Invalid path."
+
+        if not insert_text:
+            return "Error: insert_text is required."
+
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_path})
+
+        if not doc or not doc.get("content"):
+            return f"Error: File not found: {validated_path}"
+
+        current_content = str(doc["content"])
+        lines = current_content.split("\n")
+
+        # Convert to 0-indexed
+        index = insert_line - 1
+        if index < 0 or index > len(lines):
+            return f"Error: Invalid line number. File has {len(lines)} lines."
+
+        lines.insert(index, insert_text)
+        updated_content = "\n".join(lines)
+
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_path},
+            {
+                "$set": {
+                    "content": updated_content,
+                    "updated_at": datetime.now()
+                }
+            }
+        )
+
+        return f"Text inserted at line {insert_line} in {validated_path}"
+
+    def _delete(self, path: str) -> str:
+        """Delete a file or directory."""
+        validated_path = self._validate_path(path)
+        if not validated_path:
+            return "Error: Invalid path."
+
+        if validated_path == "/":
+            # Delete all files for this user and tool
+            result = self.collection.delete_many({"user_id": self.user_id, "tool_id": self.tool_id})
+            return f"Deleted {result.deleted_count} file(s) from memory."
+
+        # Check if it's a directory (ends with /)
+        if validated_path.endswith("/"):
+            # Delete all files in directory
+            result = self.collection.delete_many({
+                "user_id": self.user_id,
+                "tool_id": self.tool_id,
+                "path": {"$regex": f"^{re.escape(validated_path)}"}
+            })
+            return f"Deleted directory and {result.deleted_count} file(s)."
+
+        # Try to delete as directory first (without trailing slash)
+        # Check if any files start with this path + /
+        search_path = validated_path + "/"
+        directory_result = self.collection.delete_many({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": {"$regex": f"^{re.escape(search_path)}"}
+        })
+
+        if directory_result.deleted_count > 0:
+            return f"Deleted directory and {directory_result.deleted_count} file(s)."
+
+        # Delete single file
+        result = self.collection.delete_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": validated_path
+        })
+
+        if result.deleted_count:
+            return f"Deleted: {validated_path}"
+        return f"Error: File not found: {validated_path}"
+
+    def _rename(self, old_path: str, new_path: str) -> str:
+        """Rename or move a file/directory."""
+        validated_old = self._validate_path(old_path)
+        validated_new = self._validate_path(new_path)
+
+        if not validated_old or not validated_new:
+            return "Error: Invalid path."
+
+        if validated_old == "/" or validated_new == "/":
+            return "Error: Cannot rename root directory."
+
+        # Check if renaming a directory
+        if validated_old.endswith("/"):
+            # Ensure validated_new also ends with / for proper path replacement
+            if not validated_new.endswith("/"):
+                validated_new = validated_new + "/"
+
+            # Find all files in the old directory
+            docs = list(self.collection.find({
+                "user_id": self.user_id,
+                "tool_id": self.tool_id,
+                "path": {"$regex": f"^{re.escape(validated_old)}"}
+            }))
+
+            if not docs:
+                return f"Error: Directory not found: {validated_old}"
+
+            # Update paths for all files
+            for doc in docs:
+                old_file_path = doc["path"]
+                new_file_path = old_file_path.replace(validated_old, validated_new, 1)
+
+                self.collection.update_one(
+                    {"_id": doc["_id"]},
+                    {"$set": {"path": new_file_path, "updated_at": datetime.now()}}
+                )
+
+            return f"Renamed directory: {validated_old} -> {validated_new} ({len(docs)} files)"
+
+        # Rename single file
+        doc = self.collection.find_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": validated_old
+        })
+
+        if not doc:
+            return f"Error: File not found: {validated_old}"
+
+        # Check if new path already exists
+        existing = self.collection.find_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": validated_new
+        })
+
+        if existing:
+            return f"Error: File already exists at {validated_new}"
+
+        # Delete the old document and create a new one with the new path
+        self.collection.delete_one({"user_id": self.user_id, "tool_id": self.tool_id, "path": validated_old})
+        self.collection.insert_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "path": validated_new,
+            "content": doc.get("content", ""),
+            "updated_at": datetime.now()
+        })
+
+        return f"Renamed: {validated_old} -> {validated_new}"

application/agents/tools/notes.py

@@ -0,0 +1,199 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+import uuid
+
+from .base import Tool
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+
+
+class NotesTool(Tool):
+    """Notepad
+
+    Single note. Supports viewing, overwriting, string replacement.
+    """
+
+    def __init__(self, tool_config: Optional[Dict[str, Any]] = None, user_id: Optional[str] = None) -> None:
+        """Initialize the tool.
+
+        Args:
+            tool_config: Optional tool configuration. Should include:
+                - tool_id: Unique identifier for this notes tool instance (from user_tools._id)
+                           This ensures each user's tool configuration has isolated notes
+            user_id: The authenticated user's id (should come from decoded_token["sub"]).
+        """
+        self.user_id: Optional[str] = user_id
+
+        # Get tool_id from configuration (passed from user_tools._id in production)
+        # In production, tool_id is the MongoDB ObjectId string from user_tools collection
+        if tool_config and "tool_id" in tool_config:
+            self.tool_id = tool_config["tool_id"]
+        elif user_id:
+            # Fallback for backward compatibility or testing
+            self.tool_id = f"default_{user_id}"
+        else:
+            # Last resort fallback (shouldn't happen in normal use)
+            self.tool_id = str(uuid.uuid4())
+
+        db = MongoDB.get_client()[settings.MONGO_DB_NAME]
+        self.collection = db["notes"]
+
+    # -----------------------------
+    # Action implementations
+    # -----------------------------
+    def execute_action(self, action_name: str, **kwargs: Any) -> str:
+        """Execute an action by name.
+
+        Args:
+            action_name: One of view, overwrite, str_replace, insert, delete.
+            **kwargs: Parameters for the action.
+
+        Returns:
+            A human-readable string result.
+        """
+        if not self.user_id:
+             return "Error: NotesTool requires a valid user_id."
+
+        if action_name == "view":
+            return self._get_note()
+
+        if action_name == "overwrite":
+            return self._overwrite_note(kwargs.get("text", ""))
+
+        if action_name == "str_replace":
+            return self._str_replace(kwargs.get("old_str", ""), kwargs.get("new_str", ""))
+
+        if action_name == "insert":
+            return self._insert(kwargs.get("line_number", 1), kwargs.get("text", ""))
+
+        if action_name == "delete":
+            return self._delete_note()
+
+        return f"Unknown action: {action_name}"
+
+    def get_actions_metadata(self) -> List[Dict[str, Any]]:
+        """Return JSON metadata describing supported actions for tool schemas."""
+        return [
+            {
+                "name": "view",
+                "description": "Retrieve the user's note.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "overwrite",
+                "description": "Replace the entire note content (creates if doesn't exist).",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "text": {"type": "string", "description": "New note content."}
+                    },
+                    "required": ["text"],
+                },
+            },
+            {
+                "name": "str_replace",
+                "description": "Replace occurrences of old_str with new_str in the note.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "old_str": {"type": "string", "description": "String to find."},
+                        "new_str": {"type": "string", "description": "String to replace with."}
+                    },
+                    "required": ["old_str", "new_str"],
+                },
+            },
+            {
+                "name": "insert",
+                "description": "Insert text at the specified line number (1-indexed).",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "line_number": {"type": "integer", "description": "Line number to insert at (1-indexed)."},
+                        "text": {"type": "string", "description": "Text to insert."}
+                    },
+                    "required": ["line_number", "text"],
+                },
+            },
+            {
+                "name": "delete",
+                "description": "Delete the user's note.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        ]
+
+    def get_config_requirements(self) -> Dict[str, Any]:
+        """Return configuration requirements (none for now)."""
+        return {}
+
+    # -----------------------------
+    # Internal helpers (single-note)
+    # -----------------------------
+    def _get_note(self) -> str:
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id})
+        if not doc or not doc.get("note"):
+            return "No note found."
+        return str(doc["note"])
+
+    def _overwrite_note(self, content: str) -> str:
+        content = (content or "").strip()
+        if not content:
+            return "Note content required."
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id},
+            {"$set": {"note": content, "updated_at": datetime.utcnow()}},
+            upsert=True,  # ✅ create if missing
+        )
+        return "Note saved."
+
+    def _str_replace(self, old_str: str, new_str: str) -> str:
+        if not old_str:
+            return "old_str is required."
+
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id})
+        if not doc or not doc.get("note"):
+            return "No note found."
+
+        current_note = str(doc["note"])
+
+        # Case-insensitive search
+        if old_str.lower() not in current_note.lower():
+            return f"String '{old_str}' not found in note."
+
+        # Case-insensitive replacement
+        import re
+        updated_note = re.sub(re.escape(old_str), new_str, current_note, flags=re.IGNORECASE)
+
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id},
+            {"$set": {"note": updated_note, "updated_at": datetime.utcnow()}},
+        )
+        return "Note updated."
+
+    def _insert(self, line_number: int, text: str) -> str:
+        if not text:
+            return "Text is required."
+
+        doc = self.collection.find_one({"user_id": self.user_id, "tool_id": self.tool_id})
+        if not doc or not doc.get("note"):
+            return "No note found."
+
+        current_note = str(doc["note"])
+        lines = current_note.split("\n")
+
+        # Convert to 0-indexed and validate
+        index = line_number - 1
+        if index < 0 or index > len(lines):
+            return f"Invalid line number. Note has {len(lines)} lines."
+
+        lines.insert(index, text)
+        updated_note = "\n".join(lines)
+
+        self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id},
+            {"$set": {"note": updated_note, "updated_at": datetime.utcnow()}},
+        )
+        return "Text inserted."
+
+    def _delete_note(self) -> str:
+        res = self.collection.delete_one({"user_id": self.user_id, "tool_id": self.tool_id})
+        return "Note deleted." if res.deleted_count else "No note found to delete."

application/agents/tools/todo_list.py

@@ -0,0 +1,321 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+import uuid
+
+from .base import Tool
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+
+
+class TodoListTool(Tool):
+    """Todo List
+
+    Manages todo items for users. Supports creating, viewing, updating, and deleting todos.
+    """
+
+    def __init__(self, tool_config: Optional[Dict[str, Any]] = None, user_id: Optional[str] = None) -> None:
+        """Initialize the tool.
+
+        Args:
+            tool_config: Optional tool configuration. Should include:
+                - tool_id: Unique identifier for this todo list tool instance (from user_tools._id)
+                           This ensures each user's tool configuration has isolated todos
+            user_id: The authenticated user's id (should come from decoded_token["sub"]).
+        """
+        self.user_id: Optional[str] = user_id
+
+        # Get tool_id from configuration (passed from user_tools._id in production)
+        # In production, tool_id is the MongoDB ObjectId string from user_tools collection
+        if tool_config and "tool_id" in tool_config:
+            self.tool_id = tool_config["tool_id"]
+        elif user_id:
+            # Fallback for backward compatibility or testing
+            self.tool_id = f"default_{user_id}"
+        else:
+            # Last resort fallback (shouldn't happen in normal use)
+            self.tool_id = str(uuid.uuid4())
+
+        db = MongoDB.get_client()[settings.MONGO_DB_NAME]
+        self.collection = db["todos"]
+
+    # -----------------------------
+    # Action implementations
+    # -----------------------------
+    def execute_action(self, action_name: str, **kwargs: Any) -> str:
+        """Execute an action by name.
+
+        Args:
+            action_name: One of list, create, get, update, complete, delete.
+            **kwargs: Parameters for the action.
+
+        Returns:
+            A human-readable string result.
+        """
+        if not self.user_id:
+            return "Error: TodoListTool requires a valid user_id."
+
+        if action_name == "list":
+            return self._list()
+
+        if action_name == "create":
+            return self._create(kwargs.get("title", ""))
+
+        if action_name == "get":
+            return self._get(kwargs.get("todo_id"))
+
+        if action_name == "update":
+            return self._update(
+                kwargs.get("todo_id"),
+                kwargs.get("title", "")
+            )
+
+        if action_name == "complete":
+            return self._complete(kwargs.get("todo_id"))
+
+        if action_name == "delete":
+            return self._delete(kwargs.get("todo_id"))
+
+        return f"Unknown action: {action_name}"
+
+    def get_actions_metadata(self) -> List[Dict[str, Any]]:
+        """Return JSON metadata describing supported actions for tool schemas."""
+        return [
+            {
+                "name": "list",
+                "description": "List all todos for the user.",
+                "parameters": {"type": "object", "properties": {}},
+            },
+            {
+                "name": "create",
+                "description": "Create a new todo item.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "title": {
+                            "type": "string",
+                            "description": "Title of the todo item."
+                        }
+                    },
+                    "required": ["title"],
+                },
+            },
+            {
+                "name": "get",
+                "description": "Get a specific todo by ID.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "todo_id": {
+                            "type": "integer",
+                            "description": "The ID of the todo to retrieve."
+                        }
+                    },
+                    "required": ["todo_id"],
+                },
+            },
+            {
+                "name": "update",
+                "description": "Update a todo's title by ID.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "todo_id": {
+                            "type": "integer",
+                            "description": "The ID of the todo to update."
+                        },
+                        "title": {
+                            "type": "string",
+                            "description": "The new title for the todo."
+                        }
+                    },
+                    "required": ["todo_id", "title"],
+                },
+            },
+            {
+                "name": "complete",
+                "description": "Mark a todo as completed.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "todo_id": {
+                            "type": "integer",
+                            "description": "The ID of the todo to mark as completed."
+                        }
+                    },
+                    "required": ["todo_id"],
+                },
+            },
+            {
+                "name": "delete",
+                "description": "Delete a specific todo by ID.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "todo_id": {
+                            "type": "integer",
+                            "description": "The ID of the todo to delete."
+                        }
+                    },
+                    "required": ["todo_id"],
+                },
+            },
+        ]
+
+    def get_config_requirements(self) -> Dict[str, Any]:
+        """Return configuration requirements."""
+        return {}
+
+    # -----------------------------
+    # Internal helpers
+    # -----------------------------
+    def _coerce_todo_id(self, value: Optional[Any]) -> Optional[int]:
+        """Convert todo identifiers to sequential integers."""
+        if value is None:
+            return None
+
+        if isinstance(value, int):
+            return value if value > 0 else None
+
+        if isinstance(value, str):
+            stripped = value.strip()
+            if stripped.isdigit():
+                numeric_value = int(stripped)
+                return numeric_value if numeric_value > 0 else None
+
+        return None
+
+    def _get_next_todo_id(self) -> int:
+        """Get the next sequential todo_id for this user and tool.
+
+        Returns a simple integer (1, 2, 3, ...) scoped to this user/tool.
+        With 5-10 todos max, scanning is negligible.
+        """
+        # Find all todos for this user/tool and get their IDs
+        todos = list(self.collection.find(
+            {"user_id": self.user_id, "tool_id": self.tool_id},
+            {"todo_id": 1}
+        ))
+
+        # Find the maximum todo_id
+        max_id = 0
+        for todo in todos:
+            todo_id = self._coerce_todo_id(todo.get("todo_id"))
+            if todo_id is not None:
+                max_id = max(max_id, todo_id)
+
+        return max_id + 1
+
+    def _list(self) -> str:
+        """List all todos for the user."""
+        cursor = self.collection.find({"user_id": self.user_id, "tool_id": self.tool_id})
+        todos = list(cursor)
+
+        if not todos:
+            return "No todos found."
+
+        result_lines = ["Todos:"]
+        for doc in todos:
+            todo_id = doc.get("todo_id")
+            title = doc.get("title", "Untitled")
+            status = doc.get("status", "open")
+
+            line = f"[{todo_id}] {title} ({status})"
+            result_lines.append(line)
+
+        return "\n".join(result_lines)
+
+    def _create(self, title: str) -> str:
+        """Create a new todo item."""
+        title = (title or "").strip()
+        if not title:
+            return "Error: Title is required."
+
+        now = datetime.now()
+        todo_id = self._get_next_todo_id()
+
+        doc = {
+            "todo_id": todo_id,
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "title": title,
+            "status": "open",
+            "created_at": now,
+            "updated_at": now,
+        }
+        self.collection.insert_one(doc)
+        return f"Todo created with ID {todo_id}: {title}"
+
+    def _get(self, todo_id: Optional[Any]) -> str:
+        """Get a specific todo by ID."""
+        parsed_todo_id = self._coerce_todo_id(todo_id)
+        if parsed_todo_id is None:
+            return "Error: todo_id must be a positive integer."
+
+        doc = self.collection.find_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "todo_id": parsed_todo_id
+        })
+
+        if not doc:
+            return f"Error: Todo with ID {parsed_todo_id} not found."
+
+        title = doc.get("title", "Untitled")
+        status = doc.get("status", "open")
+
+        result = f"Todo [{parsed_todo_id}]:\nTitle: {title}\nStatus: {status}"
+
+        return result
+
+    def _update(self, todo_id: Optional[Any], title: str) -> str:
+        """Update a todo's title by ID."""
+        parsed_todo_id = self._coerce_todo_id(todo_id)
+        if parsed_todo_id is None:
+            return "Error: todo_id must be a positive integer."
+
+        title = (title or "").strip()
+        if not title:
+            return "Error: Title is required."
+
+        result = self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id, "todo_id": parsed_todo_id},
+            {"$set": {"title": title, "updated_at": datetime.now()}}
+        )
+
+        if result.matched_count == 0:
+            return f"Error: Todo with ID {parsed_todo_id} not found."
+
+        return f"Todo {parsed_todo_id} updated to: {title}"
+
+    def _complete(self, todo_id: Optional[Any]) -> str:
+        """Mark a todo as completed."""
+        parsed_todo_id = self._coerce_todo_id(todo_id)
+        if parsed_todo_id is None:
+            return "Error: todo_id must be a positive integer."
+
+        result = self.collection.update_one(
+            {"user_id": self.user_id, "tool_id": self.tool_id, "todo_id": parsed_todo_id},
+            {"$set": {"status": "completed", "updated_at": datetime.now()}}
+        )
+
+        if result.matched_count == 0:
+            return f"Error: Todo with ID {parsed_todo_id} not found."
+
+        return f"Todo {parsed_todo_id} marked as completed."
+
+    def _delete(self, todo_id: Optional[Any]) -> str:
+        """Delete a specific todo by ID."""
+        parsed_todo_id = self._coerce_todo_id(todo_id)
+        if parsed_todo_id is None:
+            return "Error: todo_id must be a positive integer."
+
+        result = self.collection.delete_one({
+            "user_id": self.user_id,
+            "tool_id": self.tool_id,
+            "todo_id": parsed_todo_id
+        })
+
+        if result.deleted_count == 0:
+            return f"Error: Todo with ID {parsed_todo_id} not found."
+
+        return f"Todo {parsed_todo_id} deleted."

application/agents/tools/tool_action_parser.py

@@ -20,20 +20,24 @@ class ToolActionParser:
         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")
+                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.warning(
+                    f"Tool ID '{tool_id}' is not numerical. This might be a hallucinated tool call."
+                )
+
+        except (AttributeError, TypeError, json.JSONDecodeError) as e:
             logger.error(f"Error parsing OpenAI LLM call: {e}")
             return None, None, None
         return tool_id, action_name, call_args
@@ -42,19 +46,23 @@ class ToolActionParser:
         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")
+                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.")
-                
+                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

application/agents/tools/tool_manager.py

@@ -28,7 +28,7 @@ class ToolManager:
         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:
-                if tool_name == "mcp_tool" and user_id:
+                if tool_name in {"mcp_tool", "notes", "memory", "todo_list"} and user_id:
                     return obj(tool_config, user_id)
                 else:
                     return obj(tool_config)
@@ -36,7 +36,7 @@ class ToolManager:
     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:
+        if tool_name in {"mcp_tool", "memory", "todo_list"} 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)

application/api/answer/routes/answer.py

@@ -54,6 +54,14 @@ class AnswerResource(Resource, BaseAnswerResource):
                 default=True,
                 description="Whether to save the conversation",
             ),
+            "model_id": fields.String(
+                required=False,
+                description="Model ID to use for this request",
+            ),
+            "passthrough": fields.Raw(
+                required=False,
+                description="Dynamic parameters to inject into prompt template",
+            ),
         },
     )
 
@@ -69,19 +77,31 @@ class AnswerResource(Resource, BaseAnswerResource):
             processor.initialize()
             if not processor.decoded_token:
                 return make_response({"error": "Unauthorized"}, 401)
-            agent = processor.create_agent()
-            retriever = processor.create_retriever()
+
+            docs_together, docs_list = processor.pre_fetch_docs(
+                data.get("question", "")
+            )
+            tools_data = processor.pre_fetch_tools()
+
+            agent = processor.create_agent(
+                docs_together=docs_together,
+                docs=docs_list,
+                tools_data=tools_data,
+            )
+
+            if error := self.check_usage(processor.agent_config):
+                return error
 
             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),
+                model_id=processor.model_id,
             )
             stream_result = self.process_response_stream(stream)
 

application/api/answer/routes/base.py

@@ -3,15 +3,20 @@ import json
 import logging
 from typing import Any, Dict, Generator, List, Optional
 
-from flask import Response
+from flask import jsonify, make_response, Response
 from flask_restx import Namespace
 
 from application.api.answer.services.conversation_service import ConversationService
+from application.core.model_utils import (
+    get_api_key_for_provider,
+    get_default_model_id,
+    get_provider_from_model_id,
+)
 
 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
+from application.utils import check_required_fields
 
 logger = logging.getLogger(__name__)
 
@@ -25,8 +30,9 @@ class BaseAnswerResource:
     def __init__(self):
         mongo = MongoDB.get_client()
         db = mongo[settings.MONGO_DB_NAME]
+        self.db = db
         self.user_logs_collection = db["user_logs"]
-        self.gpt_model = get_gpt_model()
+        self.default_model_id = get_default_model_id()
         self.conversation_service = ConversationService()
 
     def validate_request(
@@ -40,11 +46,104 @@ class BaseAnswerResource:
             return missing_fields
         return None
 
+    def check_usage(self, agent_config: Dict) -> Optional[Response]:
+        """Check if there is a usage limit and if it is exceeded
+
+        Args:
+            agent_config: The config dict of agent instance
+
+        Returns:
+            None or Response if either of limits exceeded.
+
+        """
+        api_key = agent_config.get("user_api_key")
+        if not api_key:
+            return None
+        agents_collection = self.db["agents"]
+        agent = agents_collection.find_one({"key": api_key})
+
+        if not agent:
+            return make_response(
+                jsonify({"success": False, "message": "Invalid API key."}), 401
+            )
+        limited_token_mode_raw = agent.get("limited_token_mode", False)
+        limited_request_mode_raw = agent.get("limited_request_mode", False)
+
+        limited_token_mode = (
+            limited_token_mode_raw
+            if isinstance(limited_token_mode_raw, bool)
+            else limited_token_mode_raw == "True"
+        )
+        limited_request_mode = (
+            limited_request_mode_raw
+            if isinstance(limited_request_mode_raw, bool)
+            else limited_request_mode_raw == "True"
+        )
+
+        token_limit = int(
+            agent.get("token_limit", settings.DEFAULT_AGENT_LIMITS["token_limit"])
+        )
+        request_limit = int(
+            agent.get("request_limit", settings.DEFAULT_AGENT_LIMITS["request_limit"])
+        )
+
+        token_usage_collection = self.db["token_usage"]
+
+        end_date = datetime.datetime.now()
+        start_date = end_date - datetime.timedelta(hours=24)
+
+        match_query = {
+            "timestamp": {"$gte": start_date, "$lte": end_date},
+            "api_key": api_key,
+        }
+
+        if limited_token_mode:
+            token_pipeline = [
+                {"$match": match_query},
+                {
+                    "$group": {
+                        "_id": None,
+                        "total_tokens": {
+                            "$sum": {"$add": ["$prompt_tokens", "$generated_tokens"]}
+                        },
+                    }
+                },
+            ]
+            token_result = list(token_usage_collection.aggregate(token_pipeline))
+            daily_token_usage = token_result[0]["total_tokens"] if token_result else 0
+        else:
+            daily_token_usage = 0
+        if limited_request_mode:
+            daily_request_usage = token_usage_collection.count_documents(match_query)
+        else:
+            daily_request_usage = 0
+        if not limited_token_mode and not limited_request_mode:
+            return None
+        token_exceeded = (
+            limited_token_mode and token_limit > 0 and daily_token_usage >= token_limit
+        )
+        request_exceeded = (
+            limited_request_mode
+            and request_limit > 0
+            and daily_request_usage >= request_limit
+        )
+
+        if token_exceeded or request_exceeded:
+            return make_response(
+                jsonify(
+                    {
+                        "success": False,
+                        "message": "Exceeding usage limit, please try again later.",
+                    }
+                ),
+                429,
+            )
+        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],
@@ -55,6 +154,7 @@ class BaseAnswerResource:
         agent_id: Optional[str] = None,
         is_shared_usage: bool = False,
         shared_token: Optional[str] = None,
+        model_id: Optional[str] = None,
     ) -> Generator[str, None, None]:
         """
         Generator function that streams the complete conversation response.
@@ -73,6 +173,8 @@ class BaseAnswerResource:
             agent_id: ID of agent used
             is_shared_usage: Flag for shared agent usage
             shared_token: Token for shared agent
+            model_id: Model ID used for the request
+            retrieved_docs: Pre-fetched documents for sources (optional)
 
         Yields:
             Server-sent event strings
@@ -83,7 +185,7 @@ class BaseAnswerResource:
             schema_info = None
             structured_chunks = []
 
-            for line in agent.gen(query=question, retriever=retriever):
+            for line in agent.gen(query=question):
                 if "answer" in line:
                     response_full += str(line["answer"])
                     if line.get("structured"):
@@ -119,7 +221,6 @@ class BaseAnswerResource:
                 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",
@@ -129,15 +230,22 @@ class BaseAnswerResource:
                 }
                 data = json.dumps(structured_data)
                 yield f"data: {data}\n\n"
-
             if isNoneDoc:
                 for doc in source_log_docs:
                     doc["source"] = "None"
+            provider = (
+                get_provider_from_model_id(model_id)
+                if model_id
+                else settings.LLM_PROVIDER
+            )
+            system_api_key = get_api_key_for_provider(provider or settings.LLM_PROVIDER)
+
             llm = LLMCreator.create_llm(
-                settings.LLM_PROVIDER,
-                api_key=settings.API_KEY,
+                provider or settings.LLM_PROVIDER,
+                api_key=system_api_key,
                 user_api_key=user_api_key,
                 decoded_token=decoded_token,
+                model_id=model_id,
             )
 
             if should_save_conversation:
@@ -149,7 +257,7 @@ class BaseAnswerResource:
                     source_log_docs,
                     tool_calls,
                     llm,
-                    self.gpt_model,
+                    model_id or self.default_model_id,
                     decoded_token,
                     index=index,
                     api_key=user_api_key,
@@ -164,7 +272,6 @@ class BaseAnswerResource:
             data = json.dumps(id_data)
             yield f"data: {data}\n\n"
 
-            retriever_params = retriever.get_params()
             log_data = {
                 "action": "stream_answer",
                 "level": "info",
@@ -173,7 +280,6 @@ class BaseAnswerResource:
                 "question": question,
                 "response": response_full,
                 "sources": source_log_docs,
-                "retriever_params": retriever_params,
                 "attachments": attachment_ids,
                 "timestamp": datetime.datetime.now(datetime.timezone.utc),
             }
@@ -181,18 +287,52 @@ class BaseAnswerResource:
                 log_data["structured_output"] = True
                 if schema_info:
                     log_data["schema"] = schema_info
-  
-            # clean up text fields to be no longer than 10000 characters
+            # 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 GeneratorExit:
+            logger.info(f"Stream aborted by client for question: {question[:50]}... ")
+            # Save partial response
+
+            if should_save_conversation and response_full:
+                try:
+                    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,
+                    )
+                    self.conversation_service.save_conversation(
+                        conversation_id,
+                        question,
+                        response_full,
+                        thought,
+                        source_log_docs,
+                        tool_calls,
+                        llm,
+                        model_id or self.default_model_id,
+                        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,
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"Error saving partial response: {str(e)}", exc_info=True
+                    )
+            raise
         except Exception as e:
             logger.error(f"Error in stream: {str(e)}", exc_info=True)
             data = json.dumps(
@@ -236,7 +376,7 @@ class BaseAnswerResource:
                     thought = event["thought"]
                 elif event["type"] == "error":
                     logger.error(f"Error from stream: {event['error']}")
-                    return None, None, None, None, event["error"]
+                    return None, None, None, None, event["error"], None
                 elif event["type"] == "end":
                     stream_ended = True
             except (json.JSONDecodeError, KeyError) as e:
@@ -244,8 +384,7 @@ class BaseAnswerResource:
                 continue
         if not stream_ended:
             logger.error("Stream ended unexpectedly without an 'end' event.")
-            return None, None, None, None, "Stream ended unexpectedly"
-
+            return None, None, None, None, "Stream ended unexpectedly", None
         result = (
             conversation_id,
             response_full,
@@ -257,7 +396,6 @@ class BaseAnswerResource:
 
         if is_structured:
             result = result + ({"structured": True, "schema": schema_info},)
-
         return result
 
     def error_stream_generate(self, err_response):

application/api/answer/routes/stream.py

@@ -57,9 +57,17 @@ class StreamResource(Resource, BaseAnswerResource):
                 default=True,
                 description="Whether to save the conversation",
             ),
+            "model_id": fields.String(
+                required=False,
+                description="Model ID to use for this request",
+            ),
             "attachments": fields.List(
                 fields.String, required=False, description="List of attachment IDs"
             ),
+            "passthrough": fields.Raw(
+                required=False,
+                description="Dynamic parameters to inject into prompt template",
+            ),
         },
     )
 
@@ -73,14 +81,20 @@ class StreamResource(Resource, BaseAnswerResource):
         processor = StreamProcessor(data, decoded_token)
         try:
             processor.initialize()
-            agent = processor.create_agent()
-            retriever = processor.create_retriever()
 
+            docs_together, docs_list = processor.pre_fetch_docs(data["question"])
+            tools_data = processor.pre_fetch_tools()
+
+            agent = processor.create_agent(
+                docs_together=docs_together, docs=docs_list, tools_data=tools_data
+            )
+
+            if error := self.check_usage(processor.agent_config):
+                return error
             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,
@@ -91,6 +105,7 @@ class StreamResource(Resource, BaseAnswerResource):
                     agent_id=data.get("agent_id"),
                     is_shared_usage=processor.is_shared_usage,
                     shared_token=processor.shared_token,
+                    model_id=processor.model_id,
                 ),
                 mimetype="text/event-stream",
             )

application/api/answer/services/conversation_service.py

@@ -52,7 +52,7 @@ class ConversationService:
         sources: List[Dict[str, Any]],
         tool_calls: List[Dict[str, Any]],
         llm: Any,
-        gpt_model: str,
+        model_id: str,
         decoded_token: Dict[str, Any],
         index: Optional[int] = None,
         api_key: Optional[str] = None,
@@ -66,7 +66,7 @@ class ConversationService:
         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):
@@ -90,6 +90,7 @@ class ConversationService:
                         f"queries.{index}.tool_calls": tool_calls,
                         f"queries.{index}.timestamp": current_time,
                         f"queries.{index}.attachments": attachment_ids,
+                        f"queries.{index}.model_id": model_id,
                     }
                 },
             )
@@ -120,6 +121,7 @@ class ConversationService:
                             "tool_calls": tool_calls,
                             "timestamp": current_time,
                             "attachments": attachment_ids,
+                            "model_id": model_id,
                         }
                     }
                 },
@@ -133,10 +135,9 @@ class ConversationService:
 
             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": "system",
+                    "content": "You are a helpful assistant that creates concise conversation titles. "
+                    "Summarize conversations in 3 words or less using the same language as the user.",
                 },
                 {
                     "role": "user",
@@ -147,7 +148,7 @@ class ConversationService:
             ]
 
             completion = llm.gen(
-                model=gpt_model, messages=messages_summary, max_tokens=30
+                model=model_id, messages=messages_summary, max_tokens=30
             )
 
             conversation_data = {
@@ -163,6 +164,7 @@ class ConversationService:
                         "tool_calls": tool_calls,
                         "timestamp": current_time,
                         "attachments": attachment_ids,
+                        "model_id": model_id,
                     }
                 ],
             }

application/api/answer/services/prompt_renderer.py

@@ -0,0 +1,97 @@
+import logging
+from typing import Any, Dict, Optional
+
+from application.templates.namespaces import NamespaceManager
+
+from application.templates.template_engine import TemplateEngine, TemplateRenderError
+
+logger = logging.getLogger(__name__)
+
+
+class PromptRenderer:
+    """Service for rendering prompts with dynamic context using namespaces"""
+
+    def __init__(self):
+        self.template_engine = TemplateEngine()
+        self.namespace_manager = NamespaceManager()
+
+    def render_prompt(
+        self,
+        prompt_content: str,
+        user_id: Optional[str] = None,
+        request_id: Optional[str] = None,
+        passthrough_data: Optional[Dict[str, Any]] = None,
+        docs: Optional[list] = None,
+        docs_together: Optional[str] = None,
+        tools_data: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ) -> str:
+        """
+        Render prompt with full context from all namespaces.
+
+        Args:
+            prompt_content: Raw prompt template string
+            user_id: Current user identifier
+            request_id: Unique request identifier
+            passthrough_data: Parameters from web request
+            docs: RAG retrieved documents
+            docs_together: Concatenated document content
+            tools_data: Pre-fetched tool results organized by tool name
+            **kwargs: Additional parameters for namespace builders
+
+        Returns:
+            Rendered prompt string with all variables substituted
+
+        Raises:
+            TemplateRenderError: If template rendering fails
+        """
+        if not prompt_content:
+            return ""
+
+        uses_template = self._uses_template_syntax(prompt_content)
+
+        if not uses_template:
+            return self._apply_legacy_substitutions(prompt_content, docs_together)
+
+        try:
+            context = self.namespace_manager.build_context(
+                user_id=user_id,
+                request_id=request_id,
+                passthrough_data=passthrough_data,
+                docs=docs,
+                docs_together=docs_together,
+                tools_data=tools_data,
+                **kwargs,
+            )
+
+            return self.template_engine.render(prompt_content, context)
+        except TemplateRenderError:
+            raise
+        except Exception as e:
+            error_msg = f"Prompt rendering failed: {str(e)}"
+            logger.error(error_msg)
+            raise TemplateRenderError(error_msg) from e
+
+    def _uses_template_syntax(self, prompt_content: str) -> bool:
+        """Check if prompt uses Jinja2 template syntax"""
+        return "{{" in prompt_content and "}}" in prompt_content
+
+    def _apply_legacy_substitutions(
+        self, prompt_content: str, docs_together: Optional[str] = None
+    ) -> str:
+        """
+        Apply backward-compatible substitutions for old prompt format.
+
+        Handles legacy {summaries} and {query} placeholders during transition period.
+        """
+        if docs_together:
+            prompt_content = prompt_content.replace("{summaries}", docs_together)
+        return prompt_content
+
+    def validate_template(self, prompt_content: str) -> bool:
+        """Validate prompt template syntax"""
+        return self.template_engine.validate_template(prompt_content)
+
+    def extract_variables(self, prompt_content: str) -> set[str]:
+        """Extract all variable names from prompt template"""
+        return self.template_engine.extract_variables(prompt_content)

application/api/answer/services/stream_processor.py

@@ -3,7 +3,7 @@ import json
 import logging
 import os
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Set
 
 from bson.dbref import DBRef
 
@@ -11,10 +11,20 @@ from bson.objectid import ObjectId
 
 from application.agents.agent_creator import AgentCreator
 from application.api.answer.services.conversation_service import ConversationService
+from application.api.answer.services.prompt_renderer import PromptRenderer
+from application.core.model_utils import (
+    get_api_key_for_provider,
+    get_default_model_id,
+    get_provider_from_model_id,
+    validate_model_id,
+)
 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
+from application.utils import (
+    calculate_doc_token_budget,
+    limit_chat_history,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -73,15 +83,20 @@ class StreamProcessor:
         self.all_sources = []
         self.attachments = []
         self.history = []
+        self.retrieved_docs = []
         self.agent_config = {}
         self.retriever_config = {}
         self.is_shared_usage = False
         self.shared_token = None
-        self.gpt_model = get_gpt_model()
+        self.model_id: Optional[str] = None
         self.conversation_service = ConversationService()
+        self.prompt_renderer = PromptRenderer()
+        self._prompt_content: Optional[str] = None
+        self._required_tool_actions: Optional[Dict[str, Set[Optional[str]]]] = None
 
     def initialize(self):
         """Initialize all required components for processing"""
+        self._validate_and_set_model()
         self._configure_agent()
         self._configure_source()
         self._configure_retriever()
@@ -103,7 +118,7 @@ class StreamProcessor:
             ]
         else:
             self.history = limit_chat_history(
-                json.loads(self.data.get("history", "[]")), gpt_model=self.gpt_model
+                json.loads(self.data.get("history", "[]")), model_id=self.model_id
             )
 
     def _process_attachments(self):
@@ -134,6 +149,25 @@ class StreamProcessor:
                 )
         return attachments
 
+    def _validate_and_set_model(self):
+        """Validate and set model_id from request"""
+        from application.core.model_settings import ModelRegistry
+
+        requested_model = self.data.get("model_id")
+
+        if requested_model:
+            if not validate_model_id(requested_model):
+                registry = ModelRegistry.get_instance()
+                available_models = [m.id for m in registry.get_enabled_models()]
+                raise ValueError(
+                    f"Invalid model_id '{requested_model}'. "
+                    f"Available models: {', '.join(available_models[:5])}"
+                    + (f" and {len(available_models) - 5} more" if len(available_models) > 5 else "")
+                )
+            self.model_id = requested_model
+        else:
+            self.model_id = get_default_model_id()
+
     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:
@@ -311,43 +345,330 @@ class StreamProcessor:
             )
 
     def _configure_retriever(self):
-        """Configure the retriever based on request data"""
+        history_token_limit = int(self.data.get("token_limit", 2000))
+        doc_token_limit = calculate_doc_token_budget(
+            model_id=self.model_id, history_token_limit=history_token_limit
+        )
+
         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),
+            "doc_token_limit": doc_token_limit,
+            "history_token_limit": history_token_limit,
         }
 
         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,
+            doc_token_limit=self.retriever_config.get("doc_token_limit", 50000),
+            model_id=self.model_id,
             user_api_key=self.agent_config["user_api_key"],
             decoded_token=self.decoded_token,
         )
+
+    def pre_fetch_docs(self, question: str) -> tuple[Optional[str], Optional[list]]:
+        """Pre-fetch documents for template rendering before agent creation"""
+        if self.data.get("isNoneDoc", False):
+            logger.info("Pre-fetch skipped: isNoneDoc=True")
+            return None, None
+        try:
+            retriever = self.create_retriever()
+            logger.info(
+                f"Pre-fetching docs with chunks={retriever.chunks}, doc_token_limit={retriever.doc_token_limit}"
+            )
+            docs = retriever.search(question)
+            logger.info(f"Pre-fetch retrieved {len(docs) if docs else 0} documents")
+
+            if not docs:
+                logger.info("Pre-fetch: No documents returned from search")
+                return None, None
+            self.retrieved_docs = docs
+
+            docs_with_filenames = []
+            for doc in docs:
+                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)
+
+            logger.info(f"Pre-fetch docs_together size: {len(docs_together)} chars")
+
+            return docs_together, docs
+        except Exception as e:
+            logger.error(f"Failed to pre-fetch docs: {str(e)}", exc_info=True)
+            return None, None
+
+    def pre_fetch_tools(self) -> Optional[Dict[str, Any]]:
+        """Pre-fetch tool data for template rendering before agent creation
+
+        Can be controlled via:
+        1. Global setting: ENABLE_TOOL_PREFETCH in .env
+        2. Per-request: disable_tool_prefetch in request data
+        """
+        if not settings.ENABLE_TOOL_PREFETCH:
+            logger.info(
+                "Tool pre-fetching disabled globally via ENABLE_TOOL_PREFETCH setting"
+            )
+            return None
+
+        if self.data.get("disable_tool_prefetch", False):
+            logger.info("Tool pre-fetching disabled for this request")
+            return None
+
+        required_tool_actions = self._get_required_tool_actions()
+        filtering_enabled = required_tool_actions is not None
+
+        try:
+            user_tools_collection = self.db["user_tools"]
+            user_id = self.initial_user_id or "local"
+
+            user_tools = list(
+                user_tools_collection.find({"user": user_id, "status": True})
+            )
+
+            if not user_tools:
+                return None
+
+            tools_data = {}
+
+            for tool_doc in user_tools:
+                tool_name = tool_doc.get("name")
+                tool_id = str(tool_doc.get("_id"))
+
+                if filtering_enabled:
+                    required_actions_by_name = required_tool_actions.get(
+                        tool_name, set()
+                    )
+                    required_actions_by_id = required_tool_actions.get(tool_id, set())
+
+                    required_actions = required_actions_by_name | required_actions_by_id
+
+                    if not required_actions:
+                        continue
+                else:
+                    required_actions = None
+
+                tool_data = self._fetch_tool_data(tool_doc, required_actions)
+                if tool_data:
+                    tools_data[tool_name] = tool_data
+                    tools_data[tool_id] = tool_data
+
+            return tools_data if tools_data else None
+        except Exception as e:
+            logger.warning(f"Failed to pre-fetch tools: {type(e).__name__}")
+            return None
+
+    def _fetch_tool_data(
+        self,
+        tool_doc: Dict[str, Any],
+        required_actions: Optional[Set[Optional[str]]],
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch and execute tool actions with saved parameters"""
+        try:
+            from application.agents.tools.tool_manager import ToolManager
+
+            tool_name = tool_doc.get("name")
+            tool_config = tool_doc.get("config", {}).copy()
+            tool_config["tool_id"] = str(tool_doc["_id"])
+
+            tool_manager = ToolManager(config={tool_name: tool_config})
+            user_id = self.initial_user_id or "local"
+            tool = tool_manager.load_tool(tool_name, tool_config, user_id=user_id)
+
+            if not tool:
+                logger.debug(f"Tool '{tool_name}' failed to load")
+                return None
+
+            tool_actions = tool.get_actions_metadata()
+            if not tool_actions:
+                logger.debug(f"Tool '{tool_name}' has no actions")
+                return None
+
+            saved_actions = tool_doc.get("actions", [])
+
+            include_all_actions = required_actions is None or (
+                required_actions and None in required_actions
+            )
+            allowed_actions: Set[str] = (
+                {action for action in required_actions if isinstance(action, str)}
+                if required_actions
+                else set()
+            )
+
+            action_results = {}
+            for action_meta in tool_actions:
+                action_name = action_meta.get("name")
+                if action_name is None:
+                    continue
+                if (
+                    not include_all_actions
+                    and allowed_actions
+                    and action_name not in allowed_actions
+                ):
+                    continue
+
+                try:
+                    saved_action = None
+                    for sa in saved_actions:
+                        if sa.get("name") == action_name:
+                            saved_action = sa
+                            break
+
+                    action_params = action_meta.get("parameters", {})
+                    properties = action_params.get("properties", {})
+
+                    kwargs = {}
+                    for param_name, param_spec in properties.items():
+                        if saved_action:
+                            saved_props = saved_action.get("parameters", {}).get(
+                                "properties", {}
+                            )
+                            if param_name in saved_props:
+                                param_value = saved_props[param_name].get("value")
+                                if param_value is not None:
+                                    kwargs[param_name] = param_value
+                                    continue
+
+                        if param_name in tool_config:
+                            kwargs[param_name] = tool_config[param_name]
+                        elif "default" in param_spec:
+                            kwargs[param_name] = param_spec["default"]
+
+                    result = tool.execute_action(action_name, **kwargs)
+                    action_results[action_name] = result
+                except Exception as e:
+                    logger.debug(
+                        f"Action '{action_name}' execution failed: {type(e).__name__}"
+                    )
+                    continue
+
+            return action_results if action_results else None
+
+        except Exception as e:
+            logger.debug(f"Tool pre-fetch failed for '{tool_name}': {type(e).__name__}")
+            return None
+
+    def _get_prompt_content(self) -> Optional[str]:
+        """Retrieve and cache the raw prompt content for the current agent configuration."""
+        if self._prompt_content is not None:
+            return self._prompt_content
+        prompt_id = (
+            self.agent_config.get("prompt_id")
+            if isinstance(self.agent_config, dict)
+            else None
+        )
+        if not prompt_id:
+            return None
+        try:
+            self._prompt_content = get_prompt(prompt_id, self.prompts_collection)
+        except ValueError as e:
+            logger.debug(f"Invalid prompt ID '{prompt_id}': {str(e)}")
+            self._prompt_content = None
+        except Exception as e:
+            logger.debug(f"Failed to fetch prompt '{prompt_id}': {type(e).__name__}")
+            self._prompt_content = None
+        return self._prompt_content
+
+    def _get_required_tool_actions(self) -> Optional[Dict[str, Set[Optional[str]]]]:
+        """Determine which tool actions are referenced in the prompt template"""
+        if self._required_tool_actions is not None:
+            return self._required_tool_actions
+
+        prompt_content = self._get_prompt_content()
+        if prompt_content is None:
+            return None
+
+        if "{{" not in prompt_content or "}}" not in prompt_content:
+            self._required_tool_actions = {}
+            return self._required_tool_actions
+
+        try:
+            from application.templates.template_engine import TemplateEngine
+
+            template_engine = TemplateEngine()
+            usages = template_engine.extract_tool_usages(prompt_content)
+            self._required_tool_actions = usages
+            return self._required_tool_actions
+        except Exception as e:
+            logger.debug(f"Failed to extract tool usages: {type(e).__name__}")
+            self._required_tool_actions = {}
+            return self._required_tool_actions
+
+    def _fetch_memory_tool_data(
+        self, tool_doc: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch memory tool data for pre-injection into prompt"""
+        try:
+            tool_config = tool_doc.get("config", {}).copy()
+            tool_config["tool_id"] = str(tool_doc["_id"])
+
+            from application.agents.tools.memory import MemoryTool
+
+            memory_tool = MemoryTool(tool_config, self.initial_user_id)
+
+            root_view = memory_tool.execute_action("view", path="/")
+
+            if "Error:" in root_view or not root_view.strip():
+                return None
+
+            return {"root": root_view, "available": True}
+        except Exception as e:
+            logger.warning(f"Failed to fetch memory tool data: {str(e)}")
+            return None
+
+    def create_agent(
+        self,
+        docs_together: Optional[str] = None,
+        docs: Optional[list] = None,
+        tools_data: Optional[Dict[str, Any]] = None,
+    ):
+        """Create and return the configured agent with rendered prompt"""
+        raw_prompt = self._get_prompt_content()
+        if raw_prompt is None:
+            raw_prompt = get_prompt(
+                self.agent_config["prompt_id"], self.prompts_collection
+            )
+            self._prompt_content = raw_prompt
+
+        rendered_prompt = self.prompt_renderer.render_prompt(
+            prompt_content=raw_prompt,
+            user_id=self.initial_user_id,
+            request_id=self.data.get("request_id"),
+            passthrough_data=self.data.get("passthrough"),
+            docs=docs,
+            docs_together=docs_together,
+            tools_data=tools_data,
+        )
+
+        provider = (
+            get_provider_from_model_id(self.model_id)
+            if self.model_id
+            else settings.LLM_PROVIDER
+        )
+        system_api_key = get_api_key_for_provider(provider or settings.LLM_PROVIDER)
+
+        return AgentCreator.create_agent(
+            self.agent_config["agent_type"],
+            endpoint="stream",
+            llm_name=provider or settings.LLM_PROVIDER,
+            model_id=self.model_id,
+            api_key=system_api_key,
+            user_api_key=self.agent_config["user_api_key"],
+            prompt=rendered_prompt,
+            chat_history=self.history,
+            retrieved_docs=self.retrieved_docs,
+            decoded_token=self.decoded_token,
+            attachments=self.attachments,
+            json_schema=self.agent_config.get("json_schema"),
+        )

application/api/connector/routes.py

@@ -23,15 +23,9 @@ 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"]
@@ -43,185 +37,6 @@ 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)"})
@@ -337,27 +152,6 @@ class ConnectorsCallback(Resource):
             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", {

application/api/user/__init__.py

@@ -0,0 +1,5 @@
+"""User API module - provides all user-related API endpoints"""
+
+from .routes import user
+
+__all__ = ["user"]

application/api/user/agents/__init__.py

@@ -0,0 +1,7 @@
+"""Agents module."""
+
+from .routes import agents_ns
+from .sharing import agents_sharing_ns
+from .webhooks import agents_webhooks_ns
+
+__all__ = ["agents_ns", "agents_sharing_ns", "agents_webhooks_ns"]

application/api/user/agents/sharing.py

@@ -0,0 +1,263 @@
+"""Agent management sharing functionality."""
+
+import datetime
+import secrets
+
+from bson import DBRef
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.core.settings import settings
+from application.api.user.base import (
+    agents_collection,
+    db,
+    ensure_user_doc,
+    resolve_tool_details,
+    user_tools_collection,
+    users_collection,
+)
+from application.utils import generate_image_url
+
+agents_sharing_ns = Namespace(
+    "agents", description="Agent management operations", path="/api"
+)
+
+
+@agents_sharing_ns.route("/shared_agent")
+class SharedAgent(Resource):
+    @api.doc(
+        params={
+            "token": "Shared token of the agent",
+        },
+        description="Get a shared agent by token or ID",
+    )
+    def get(self):
+        shared_token = request.args.get("token")
+
+        if not shared_token:
+            return make_response(
+                jsonify({"success": False, "message": "Token or ID is required"}), 400
+            )
+        try:
+            query = {
+                "shared_publicly": True,
+                "shared_token": shared_token,
+            }
+            shared_agent = agents_collection.find_one(query)
+            if not shared_agent:
+                return make_response(
+                    jsonify({"success": False, "message": "Shared agent not found"}),
+                    404,
+                )
+            agent_id = str(shared_agent["_id"])
+            data = {
+                "id": agent_id,
+                "user": shared_agent.get("user", ""),
+                "name": shared_agent.get("name", ""),
+                "image": (
+                    generate_image_url(shared_agent["image"])
+                    if shared_agent.get("image")
+                    else ""
+                ),
+                "description": shared_agent.get("description", ""),
+                "source": (
+                    str(source_doc["_id"])
+                    if isinstance(shared_agent.get("source"), DBRef)
+                    and (source_doc := db.dereference(shared_agent.get("source")))
+                    else ""
+                ),
+                "chunks": shared_agent.get("chunks", "0"),
+                "retriever": shared_agent.get("retriever", "classic"),
+                "prompt_id": shared_agent.get("prompt_id", "default"),
+                "tools": shared_agent.get("tools", []),
+                "tool_details": resolve_tool_details(shared_agent.get("tools", [])),
+                "agent_type": shared_agent.get("agent_type", ""),
+                "status": shared_agent.get("status", ""),
+                "json_schema": shared_agent.get("json_schema"),
+                "limited_token_mode": shared_agent.get("limited_token_mode", False),
+                "token_limit": shared_agent.get("token_limit", settings.DEFAULT_AGENT_LIMITS["token_limit"]),
+                "limited_request_mode": shared_agent.get("limited_request_mode", False),
+                "request_limit": shared_agent.get("request_limit", settings.DEFAULT_AGENT_LIMITS["request_limit"]),
+                "created_at": shared_agent.get("createdAt", ""),
+                "updated_at": shared_agent.get("updatedAt", ""),
+                "shared": shared_agent.get("shared_publicly", False),
+                "shared_token": shared_agent.get("shared_token", ""),
+                "shared_metadata": shared_agent.get("shared_metadata", {}),
+            }
+
+            if data["tools"]:
+                enriched_tools = []
+                for tool in data["tools"]:
+                    tool_data = user_tools_collection.find_one({"_id": ObjectId(tool)})
+                    if tool_data:
+                        enriched_tools.append(tool_data.get("name", ""))
+                data["tools"] = enriched_tools
+            decoded_token = getattr(request, "decoded_token", None)
+            if decoded_token:
+                user_id = decoded_token.get("sub")
+                owner_id = shared_agent.get("user")
+
+                if user_id != owner_id:
+                    ensure_user_doc(user_id)
+                    users_collection.update_one(
+                        {"user_id": user_id},
+                        {"$addToSet": {"agent_preferences.shared_with_me": agent_id}},
+                    )
+            return make_response(jsonify(data), 200)
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving shared agent: {err}")
+            return make_response(jsonify({"success": False}), 400)
+
+
+@agents_sharing_ns.route("/shared_agents")
+class SharedAgents(Resource):
+    @api.doc(description="Get shared agents explicitly shared with the user")
+    def get(self):
+        try:
+            decoded_token = request.decoded_token
+            if not decoded_token:
+                return make_response(jsonify({"success": False}), 401)
+            user_id = decoded_token.get("sub")
+
+            user_doc = ensure_user_doc(user_id)
+            shared_with_ids = user_doc.get("agent_preferences", {}).get(
+                "shared_with_me", []
+            )
+            shared_object_ids = [ObjectId(id) for id in shared_with_ids]
+
+            shared_agents_cursor = agents_collection.find(
+                {"_id": {"$in": shared_object_ids}, "shared_publicly": True}
+            )
+            shared_agents = list(shared_agents_cursor)
+
+            found_ids_set = {str(agent["_id"]) for agent in shared_agents}
+            stale_ids = [id for id in shared_with_ids if id not in found_ids_set]
+            if stale_ids:
+                users_collection.update_one(
+                    {"user_id": user_id},
+                    {"$pullAll": {"agent_preferences.shared_with_me": stale_ids}},
+                )
+            pinned_ids = set(user_doc.get("agent_preferences", {}).get("pinned", []))
+
+            list_shared_agents = [
+                {
+                    "id": str(agent["_id"]),
+                    "name": agent.get("name", ""),
+                    "description": agent.get("description", ""),
+                    "image": (
+                        generate_image_url(agent["image"]) if agent.get("image") else ""
+                    ),
+                    "tools": agent.get("tools", []),
+                    "tool_details": resolve_tool_details(agent.get("tools", [])),
+                    "agent_type": agent.get("agent_type", ""),
+                    "status": agent.get("status", ""),
+                    "json_schema": agent.get("json_schema"),
+                    "limited_token_mode": agent.get("limited_token_mode", False),
+                    "token_limit": agent.get("token_limit", settings.DEFAULT_AGENT_LIMITS["token_limit"]),
+                    "limited_request_mode": agent.get("limited_request_mode", False),
+                    "request_limit": agent.get("request_limit", settings.DEFAULT_AGENT_LIMITS["request_limit"]),
+                    "created_at": agent.get("createdAt", ""),
+                    "updated_at": agent.get("updatedAt", ""),
+                    "pinned": str(agent["_id"]) in pinned_ids,
+                    "shared": agent.get("shared_publicly", False),
+                    "shared_token": agent.get("shared_token", ""),
+                    "shared_metadata": agent.get("shared_metadata", {}),
+                }
+                for agent in shared_agents
+            ]
+
+            return make_response(jsonify(list_shared_agents), 200)
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving shared agents: {err}")
+            return make_response(jsonify({"success": False}), 400)
+
+
+@agents_sharing_ns.route("/share_agent")
+class ShareAgent(Resource):
+    @api.expect(
+        api.model(
+            "ShareAgentModel",
+            {
+                "id": fields.String(required=True, description="ID of the agent"),
+                "shared": fields.Boolean(
+                    required=True, description="Share or unshare the agent"
+                ),
+                "username": fields.String(
+                    required=False, description="Name of the user"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Share or unshare an agent")
+    def put(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+
+        data = request.get_json()
+        if not data:
+            return make_response(
+                jsonify({"success": False, "message": "Missing JSON body"}), 400
+            )
+        agent_id = data.get("id")
+        shared = data.get("shared")
+        username = data.get("username", "")
+
+        if not agent_id:
+            return make_response(
+                jsonify({"success": False, "message": "ID is required"}), 400
+            )
+        if shared is None:
+            return make_response(
+                jsonify(
+                    {
+                        "success": False,
+                        "message": "Shared parameter is required and must be true or false",
+                    }
+                ),
+                400,
+            )
+        try:
+            try:
+                agent_oid = ObjectId(agent_id)
+            except Exception:
+                return make_response(
+                    jsonify({"success": False, "message": "Invalid agent ID"}), 400
+                )
+            agent = agents_collection.find_one({"_id": agent_oid, "user": user})
+            if not agent:
+                return make_response(
+                    jsonify({"success": False, "message": "Agent not found"}), 404
+                )
+            if shared:
+                shared_metadata = {
+                    "shared_by": username,
+                    "shared_at": datetime.datetime.now(datetime.timezone.utc),
+                }
+                shared_token = secrets.token_urlsafe(32)
+                agents_collection.update_one(
+                    {"_id": agent_oid, "user": user},
+                    {
+                        "$set": {
+                            "shared_publicly": shared,
+                            "shared_metadata": shared_metadata,
+                            "shared_token": shared_token,
+                        }
+                    },
+                )
+            else:
+                agents_collection.update_one(
+                    {"_id": agent_oid, "user": user},
+                    {"$set": {"shared_publicly": shared, "shared_token": None}},
+                    {"$unset": {"shared_metadata": ""}},
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error sharing/unsharing agent: {err}")
+            return make_response(jsonify({"success": False, "error": str(err)}), 400)
+        shared_token = shared_token if shared else None
+        return make_response(
+            jsonify({"success": True, "shared_token": shared_token}), 200
+        )

application/api/user/agents/webhooks.py

@@ -0,0 +1,119 @@
+"""Agent management webhook handlers."""
+
+import secrets
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import Namespace, Resource
+
+from application.api import api
+from application.api.user.base import agents_collection, require_agent
+from application.api.user.tasks import process_agent_webhook
+from application.core.settings import settings
+
+
+agents_webhooks_ns = Namespace(
+    "agents", description="Agent management operations", path="/api"
+)
+
+
+@agents_webhooks_ns.route("/agent_webhook")
+class AgentWebhook(Resource):
+    @api.doc(
+        params={"id": "ID of the agent"},
+        description="Generate webhook URL for the agent",
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        agent_id = request.args.get("id")
+        if not agent_id:
+            return make_response(
+                jsonify({"success": False, "message": "ID is required"}), 400
+            )
+        try:
+            agent = agents_collection.find_one(
+                {"_id": ObjectId(agent_id), "user": user}
+            )
+            if not agent:
+                return make_response(
+                    jsonify({"success": False, "message": "Agent not found"}), 404
+                )
+            webhook_token = agent.get("incoming_webhook_token")
+            if not webhook_token:
+                webhook_token = secrets.token_urlsafe(32)
+                agents_collection.update_one(
+                    {"_id": ObjectId(agent_id), "user": user},
+                    {"$set": {"incoming_webhook_token": webhook_token}},
+                )
+            base_url = settings.API_URL.rstrip("/")
+            full_webhook_url = f"{base_url}/api/webhooks/agents/{webhook_token}"
+        except Exception as err:
+            current_app.logger.error(
+                f"Error generating webhook URL: {err}", exc_info=True
+            )
+            return make_response(
+                jsonify({"success": False, "message": "Error generating webhook URL"}),
+                400,
+            )
+        return make_response(
+            jsonify({"success": True, "webhook_url": full_webhook_url}), 200
+        )
+
+
+@agents_webhooks_ns.route("/webhooks/agents/<string:webhook_token>")
+class AgentWebhookListener(Resource):
+    method_decorators = [require_agent]
+
+    def _enqueue_webhook_task(self, agent_id_str, payload, source_method):
+        if not payload:
+            current_app.logger.warning(
+                f"Webhook ({source_method}) received for agent {agent_id_str} with empty payload."
+            )
+        current_app.logger.info(
+            f"Incoming {source_method} webhook for agent {agent_id_str}. Enqueuing task with payload: {payload}"
+        )
+
+        try:
+            task = process_agent_webhook.delay(
+                agent_id=agent_id_str,
+                payload=payload,
+            )
+            current_app.logger.info(
+                f"Task {task.id} enqueued for agent {agent_id_str} ({source_method})."
+            )
+            return make_response(jsonify({"success": True, "task_id": task.id}), 200)
+        except Exception as err:
+            current_app.logger.error(
+                f"Error enqueuing webhook task ({source_method}) for agent {agent_id_str}: {err}",
+                exc_info=True,
+            )
+            return make_response(
+                jsonify({"success": False, "message": "Error processing webhook"}), 500
+            )
+
+    @api.doc(
+        description="Webhook listener for agent events (POST). Expects JSON payload, which is used to trigger processing.",
+    )
+    def post(self, webhook_token, agent, agent_id_str):
+        payload = request.get_json()
+        if payload is None:
+            return make_response(
+                jsonify(
+                    {
+                        "success": False,
+                        "message": "Invalid or missing JSON data in request body",
+                    }
+                ),
+                400,
+            )
+        return self._enqueue_webhook_task(agent_id_str, payload, source_method="POST")
+
+    @api.doc(
+        description="Webhook listener for agent events (GET). Uses URL query parameters as payload to trigger processing.",
+    )
+    def get(self, webhook_token, agent, agent_id_str):
+        payload = request.args.to_dict(flat=True)
+        return self._enqueue_webhook_task(agent_id_str, payload, source_method="GET")

application/api/user/analytics/__init__.py

@@ -0,0 +1,5 @@
+"""Analytics module."""
+
+from .routes import analytics_ns
+
+__all__ = ["analytics_ns"]

application/api/user/analytics/routes.py

@@ -0,0 +1,540 @@
+"""Analytics and reporting routes."""
+
+import datetime
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import (
+    agents_collection,
+    conversations_collection,
+    generate_date_range,
+    generate_hourly_range,
+    generate_minute_range,
+    token_usage_collection,
+    user_logs_collection,
+)
+
+analytics_ns = Namespace(
+    "analytics", description="Analytics and reporting operations", path="/api"
+)
+
+
+@analytics_ns.route("/get_message_analytics")
+class GetMessageAnalytics(Resource):
+    get_message_analytics_model = api.model(
+        "GetMessageAnalyticsModel",
+        {
+            "api_key_id": fields.String(required=False, description="API Key ID"),
+            "filter_option": fields.String(
+                required=False,
+                description="Filter option for analytics",
+                default="last_30_days",
+                enum=[
+                    "last_hour",
+                    "last_24_hour",
+                    "last_7_days",
+                    "last_15_days",
+                    "last_30_days",
+                ],
+            ),
+        },
+    )
+
+    @api.expect(get_message_analytics_model)
+    @api.doc(description="Get message analytics based on filter option")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        api_key_id = data.get("api_key_id")
+        filter_option = data.get("filter_option", "last_30_days")
+
+        try:
+            api_key = (
+                agents_collection.find_one({"_id": ObjectId(api_key_id), "user": user})[
+                    "key"
+                ]
+                if api_key_id
+                else None
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error getting API key: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        end_date = datetime.datetime.now(datetime.timezone.utc)
+
+        if filter_option == "last_hour":
+            start_date = end_date - datetime.timedelta(hours=1)
+            group_format = "%Y-%m-%d %H:%M:00"
+        elif filter_option == "last_24_hour":
+            start_date = end_date - datetime.timedelta(hours=24)
+            group_format = "%Y-%m-%d %H:00"
+        else:
+            if filter_option in ["last_7_days", "last_15_days", "last_30_days"]:
+                filter_days = (
+                    6
+                    if filter_option == "last_7_days"
+                    else 14 if filter_option == "last_15_days" else 29
+                )
+            else:
+                return make_response(
+                    jsonify({"success": False, "message": "Invalid option"}), 400
+                )
+            start_date = end_date - datetime.timedelta(days=filter_days)
+            start_date = start_date.replace(hour=0, minute=0, second=0, microsecond=0)
+            end_date = end_date.replace(
+                hour=23, minute=59, second=59, microsecond=999999
+            )
+            group_format = "%Y-%m-%d"
+        try:
+            match_stage = {
+                "$match": {
+                    "user": user,
+                }
+            }
+            if api_key:
+                match_stage["$match"]["api_key"] = api_key
+            pipeline = [
+                match_stage,
+                {"$unwind": "$queries"},
+                {
+                    "$match": {
+                        "queries.timestamp": {"$gte": start_date, "$lte": end_date}
+                    }
+                },
+                {
+                    "$group": {
+                        "_id": {
+                            "$dateToString": {
+                                "format": group_format,
+                                "date": "$queries.timestamp",
+                            }
+                        },
+                        "count": {"$sum": 1},
+                    }
+                },
+                {"$sort": {"_id": 1}},
+            ]
+
+            message_data = conversations_collection.aggregate(pipeline)
+
+            if filter_option == "last_hour":
+                intervals = generate_minute_range(start_date, end_date)
+            elif filter_option == "last_24_hour":
+                intervals = generate_hourly_range(start_date, end_date)
+            else:
+                intervals = generate_date_range(start_date, end_date)
+            daily_messages = {interval: 0 for interval in intervals}
+
+            for entry in message_data:
+                daily_messages[entry["_id"]] = entry["count"]
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting message analytics: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(
+            jsonify({"success": True, "messages": daily_messages}), 200
+        )
+
+
+@analytics_ns.route("/get_token_analytics")
+class GetTokenAnalytics(Resource):
+    get_token_analytics_model = api.model(
+        "GetTokenAnalyticsModel",
+        {
+            "api_key_id": fields.String(required=False, description="API Key ID"),
+            "filter_option": fields.String(
+                required=False,
+                description="Filter option for analytics",
+                default="last_30_days",
+                enum=[
+                    "last_hour",
+                    "last_24_hour",
+                    "last_7_days",
+                    "last_15_days",
+                    "last_30_days",
+                ],
+            ),
+        },
+    )
+
+    @api.expect(get_token_analytics_model)
+    @api.doc(description="Get token analytics data")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        api_key_id = data.get("api_key_id")
+        filter_option = data.get("filter_option", "last_30_days")
+
+        try:
+            api_key = (
+                agents_collection.find_one({"_id": ObjectId(api_key_id), "user": user})[
+                    "key"
+                ]
+                if api_key_id
+                else None
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error getting API key: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        end_date = datetime.datetime.now(datetime.timezone.utc)
+
+        if filter_option == "last_hour":
+            start_date = end_date - datetime.timedelta(hours=1)
+            group_format = "%Y-%m-%d %H:%M:00"
+            group_stage = {
+                "$group": {
+                    "_id": {
+                        "minute": {
+                            "$dateToString": {
+                                "format": group_format,
+                                "date": "$timestamp",
+                            }
+                        }
+                    },
+                    "total_tokens": {
+                        "$sum": {"$add": ["$prompt_tokens", "$generated_tokens"]}
+                    },
+                }
+            }
+        elif filter_option == "last_24_hour":
+            start_date = end_date - datetime.timedelta(hours=24)
+            group_format = "%Y-%m-%d %H:00"
+            group_stage = {
+                "$group": {
+                    "_id": {
+                        "hour": {
+                            "$dateToString": {
+                                "format": group_format,
+                                "date": "$timestamp",
+                            }
+                        }
+                    },
+                    "total_tokens": {
+                        "$sum": {"$add": ["$prompt_tokens", "$generated_tokens"]}
+                    },
+                }
+            }
+        else:
+            if filter_option in ["last_7_days", "last_15_days", "last_30_days"]:
+                filter_days = (
+                    6
+                    if filter_option == "last_7_days"
+                    else (14 if filter_option == "last_15_days" else 29)
+                )
+            else:
+                return make_response(
+                    jsonify({"success": False, "message": "Invalid option"}), 400
+                )
+            start_date = end_date - datetime.timedelta(days=filter_days)
+            start_date = start_date.replace(hour=0, minute=0, second=0, microsecond=0)
+            end_date = end_date.replace(
+                hour=23, minute=59, second=59, microsecond=999999
+            )
+            group_format = "%Y-%m-%d"
+            group_stage = {
+                "$group": {
+                    "_id": {
+                        "day": {
+                            "$dateToString": {
+                                "format": group_format,
+                                "date": "$timestamp",
+                            }
+                        }
+                    },
+                    "total_tokens": {
+                        "$sum": {"$add": ["$prompt_tokens", "$generated_tokens"]}
+                    },
+                }
+            }
+        try:
+            match_stage = {
+                "$match": {
+                    "user_id": user,
+                    "timestamp": {"$gte": start_date, "$lte": end_date},
+                }
+            }
+            if api_key:
+                match_stage["$match"]["api_key"] = api_key
+            token_usage_data = token_usage_collection.aggregate(
+                [
+                    match_stage,
+                    group_stage,
+                    {"$sort": {"_id": 1}},
+                ]
+            )
+
+            if filter_option == "last_hour":
+                intervals = generate_minute_range(start_date, end_date)
+            elif filter_option == "last_24_hour":
+                intervals = generate_hourly_range(start_date, end_date)
+            else:
+                intervals = generate_date_range(start_date, end_date)
+            daily_token_usage = {interval: 0 for interval in intervals}
+
+            for entry in token_usage_data:
+                if filter_option == "last_hour":
+                    daily_token_usage[entry["_id"]["minute"]] = entry["total_tokens"]
+                elif filter_option == "last_24_hour":
+                    daily_token_usage[entry["_id"]["hour"]] = entry["total_tokens"]
+                else:
+                    daily_token_usage[entry["_id"]["day"]] = entry["total_tokens"]
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting token analytics: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(
+            jsonify({"success": True, "token_usage": daily_token_usage}), 200
+        )
+
+
+@analytics_ns.route("/get_feedback_analytics")
+class GetFeedbackAnalytics(Resource):
+    get_feedback_analytics_model = api.model(
+        "GetFeedbackAnalyticsModel",
+        {
+            "api_key_id": fields.String(required=False, description="API Key ID"),
+            "filter_option": fields.String(
+                required=False,
+                description="Filter option for analytics",
+                default="last_30_days",
+                enum=[
+                    "last_hour",
+                    "last_24_hour",
+                    "last_7_days",
+                    "last_15_days",
+                    "last_30_days",
+                ],
+            ),
+        },
+    )
+
+    @api.expect(get_feedback_analytics_model)
+    @api.doc(description="Get feedback analytics data")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        api_key_id = data.get("api_key_id")
+        filter_option = data.get("filter_option", "last_30_days")
+
+        try:
+            api_key = (
+                agents_collection.find_one({"_id": ObjectId(api_key_id), "user": user})[
+                    "key"
+                ]
+                if api_key_id
+                else None
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error getting API key: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        end_date = datetime.datetime.now(datetime.timezone.utc)
+
+        if filter_option == "last_hour":
+            start_date = end_date - datetime.timedelta(hours=1)
+            group_format = "%Y-%m-%d %H:%M:00"
+            date_field = {
+                "$dateToString": {
+                    "format": group_format,
+                    "date": "$queries.feedback_timestamp",
+                }
+            }
+        elif filter_option == "last_24_hour":
+            start_date = end_date - datetime.timedelta(hours=24)
+            group_format = "%Y-%m-%d %H:00"
+            date_field = {
+                "$dateToString": {
+                    "format": group_format,
+                    "date": "$queries.feedback_timestamp",
+                }
+            }
+        else:
+            if filter_option in ["last_7_days", "last_15_days", "last_30_days"]:
+                filter_days = (
+                    6
+                    if filter_option == "last_7_days"
+                    else (14 if filter_option == "last_15_days" else 29)
+                )
+            else:
+                return make_response(
+                    jsonify({"success": False, "message": "Invalid option"}), 400
+                )
+            start_date = end_date - datetime.timedelta(days=filter_days)
+            start_date = start_date.replace(hour=0, minute=0, second=0, microsecond=0)
+            end_date = end_date.replace(
+                hour=23, minute=59, second=59, microsecond=999999
+            )
+            group_format = "%Y-%m-%d"
+            date_field = {
+                "$dateToString": {
+                    "format": group_format,
+                    "date": "$queries.feedback_timestamp",
+                }
+            }
+        try:
+            match_stage = {
+                "$match": {
+                    "queries.feedback_timestamp": {
+                        "$gte": start_date,
+                        "$lte": end_date,
+                    },
+                    "queries.feedback": {"$exists": True},
+                }
+            }
+            if api_key:
+                match_stage["$match"]["api_key"] = api_key
+            pipeline = [
+                match_stage,
+                {"$unwind": "$queries"},
+                {"$match": {"queries.feedback": {"$exists": True}}},
+                {
+                    "$group": {
+                        "_id": {"time": date_field, "feedback": "$queries.feedback"},
+                        "count": {"$sum": 1},
+                    }
+                },
+                {
+                    "$group": {
+                        "_id": "$_id.time",
+                        "positive": {
+                            "$sum": {
+                                "$cond": [
+                                    {"$eq": ["$_id.feedback", "LIKE"]},
+                                    "$count",
+                                    0,
+                                ]
+                            }
+                        },
+                        "negative": {
+                            "$sum": {
+                                "$cond": [
+                                    {"$eq": ["$_id.feedback", "DISLIKE"]},
+                                    "$count",
+                                    0,
+                                ]
+                            }
+                        },
+                    }
+                },
+                {"$sort": {"_id": 1}},
+            ]
+
+            feedback_data = conversations_collection.aggregate(pipeline)
+
+            if filter_option == "last_hour":
+                intervals = generate_minute_range(start_date, end_date)
+            elif filter_option == "last_24_hour":
+                intervals = generate_hourly_range(start_date, end_date)
+            else:
+                intervals = generate_date_range(start_date, end_date)
+            daily_feedback = {
+                interval: {"positive": 0, "negative": 0} for interval in intervals
+            }
+
+            for entry in feedback_data:
+                daily_feedback[entry["_id"]] = {
+                    "positive": entry["positive"],
+                    "negative": entry["negative"],
+                }
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting feedback analytics: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(
+            jsonify({"success": True, "feedback": daily_feedback}), 200
+        )
+
+
+@analytics_ns.route("/get_user_logs")
+class GetUserLogs(Resource):
+    get_user_logs_model = api.model(
+        "GetUserLogsModel",
+        {
+            "page": fields.Integer(
+                required=False,
+                description="Page number for pagination",
+                default=1,
+            ),
+            "api_key_id": fields.String(required=False, description="API Key ID"),
+            "page_size": fields.Integer(
+                required=False,
+                description="Number of logs per page",
+                default=10,
+            ),
+        },
+    )
+
+    @api.expect(get_user_logs_model)
+    @api.doc(description="Get user logs with pagination")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        page = int(data.get("page", 1))
+        api_key_id = data.get("api_key_id")
+        page_size = int(data.get("page_size", 10))
+        skip = (page - 1) * page_size
+
+        try:
+            api_key = (
+                agents_collection.find_one({"_id": ObjectId(api_key_id)})["key"]
+                if api_key_id
+                else None
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error getting API key: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        query = {"user": user}
+        if api_key:
+            query = {"api_key": api_key}
+        items_cursor = (
+            user_logs_collection.find(query)
+            .sort("timestamp", -1)
+            .skip(skip)
+            .limit(page_size + 1)
+        )
+        items = list(items_cursor)
+
+        results = [
+            {
+                "id": str(item.get("_id")),
+                "action": item.get("action"),
+                "level": item.get("level"),
+                "user": item.get("user"),
+                "question": item.get("question"),
+                "sources": item.get("sources"),
+                "retriever_params": item.get("retriever_params"),
+                "timestamp": item.get("timestamp"),
+            }
+            for item in items[:page_size]
+        ]
+
+        has_more = len(items) > page_size
+
+        return make_response(
+            jsonify(
+                {
+                    "success": True,
+                    "logs": results,
+                    "page": page,
+                    "page_size": page_size,
+                    "has_more": has_more,
+                }
+            ),
+            200,
+        )

application/api/user/attachments/__init__.py

@@ -0,0 +1,5 @@
+"""Attachments module."""
+
+from .routes import attachments_ns
+
+__all__ = ["attachments_ns"]

application/api/user/attachments/routes.py

@@ -0,0 +1,198 @@
+"""File attachments and media routes."""
+
+import os
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import agents_collection, storage
+from application.api.user.tasks import store_attachment
+from application.core.settings import settings
+from application.tts.tts_creator import TTSCreator
+from application.utils import safe_filename
+
+
+attachments_ns = Namespace(
+    "attachments", description="File attachments and media operations", path="/api"
+)
+
+
+@attachments_ns.route("/store_attachment")
+class StoreAttachment(Resource):
+    @api.expect(
+        api.model(
+            "AttachmentModel",
+            {
+                "file": fields.Raw(required=True, description="File(s) to upload"),
+                "api_key": fields.String(
+                    required=False, description="API key (optional)"
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Stores one or multiple attachments without vectorization or training. Supports user or API key authentication."
+    )
+    def post(self):
+        decoded_token = getattr(request, "decoded_token", None)
+        api_key = request.form.get("api_key") or request.args.get("api_key")
+        
+        files = request.files.getlist("file")
+        if not files:
+            single_file = request.files.get("file")
+            if single_file:
+                files = [single_file]
+        
+        if not files or all(f.filename == "" for f in files):
+            return make_response(
+                jsonify({"status": "error", "message": "Missing file(s)"}),
+                400,
+            )
+        
+        user = None
+        if decoded_token:
+            user = safe_filename(decoded_token.get("sub"))
+        elif api_key:
+            agent = agents_collection.find_one({"key": api_key})
+            if not agent:
+                return make_response(
+                    jsonify({"success": False, "message": "Invalid API key"}), 401
+                )
+            user = safe_filename(agent.get("user"))
+        else:
+            return make_response(
+                jsonify({"success": False, "message": "Authentication required"}), 401
+            )
+        
+        try:
+            tasks = []
+            errors = []
+            original_file_count = len(files)
+            
+            for idx, file in enumerate(files):
+                try:
+                    attachment_id = ObjectId()
+                    original_filename = safe_filename(os.path.basename(file.filename))
+                    relative_path = f"{settings.UPLOAD_FOLDER}/{user}/attachments/{str(attachment_id)}/{original_filename}"
+
+                    metadata = storage.save_file(file, relative_path)
+                    file_info = {
+                        "filename": original_filename,
+                        "attachment_id": str(attachment_id),
+                        "path": relative_path,
+                        "metadata": metadata,
+                    }
+
+                    task = store_attachment.delay(file_info, user)
+                    tasks.append({
+                        "task_id": task.id,
+                        "filename": original_filename,
+                        "attachment_id": str(attachment_id),
+                    })
+                except Exception as file_err:
+                    current_app.logger.error(f"Error processing file {idx} ({file.filename}): {file_err}", exc_info=True)
+                    errors.append({
+                        "filename": file.filename,
+                        "error": str(file_err)
+                    })
+            
+            if not tasks:
+                error_msg = "No valid files to upload"
+                if errors:
+                    error_msg += f". Errors: {errors}"
+                return make_response(
+                    jsonify({"status": "error", "message": error_msg, "errors": errors}),
+                    400,
+                )
+            
+            if original_file_count == 1 and len(tasks) == 1:
+                current_app.logger.info("Returning single task_id response")
+                return make_response(
+                    jsonify(
+                        {
+                            "success": True,
+                            "task_id": tasks[0]["task_id"],
+                            "message": "File uploaded successfully. Processing started.",
+                        }
+                    ),
+                    200,
+                )
+            else:
+                response_data = {
+                    "success": True,
+                    "tasks": tasks,
+                    "message": f"{len(tasks)} file(s) uploaded successfully. Processing started.",
+                }
+                if errors:
+                    response_data["errors"] = errors
+                    response_data["message"] += f" {len(errors)} file(s) failed."
+                
+                return make_response(
+                    jsonify(response_data),
+                    200,
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error storing attachment: {err}", exc_info=True)
+            return make_response(jsonify({"success": False, "error": str(err)}), 400)
+
+
+@attachments_ns.route("/images/<path:image_path>")
+class ServeImage(Resource):
+    @api.doc(description="Serve an image from storage")
+    def get(self, image_path):
+        try:
+            file_obj = storage.get_file(image_path)
+            extension = image_path.split(".")[-1].lower()
+            content_type = f"image/{extension}"
+            if extension == "jpg":
+                content_type = "image/jpeg"
+            response = make_response(file_obj.read())
+            response.headers.set("Content-Type", content_type)
+            response.headers.set("Cache-Control", "max-age=86400")
+
+            return response
+        except FileNotFoundError:
+            return make_response(
+                jsonify({"success": False, "message": "Image not found"}), 404
+            )
+        except Exception as e:
+            current_app.logger.error(f"Error serving image: {e}")
+            return make_response(
+                jsonify({"success": False, "message": "Error retrieving image"}), 500
+            )
+
+
+@attachments_ns.route("/tts")
+class TextToSpeech(Resource):
+    tts_model = api.model(
+        "TextToSpeechModel",
+        {
+            "text": fields.String(
+                required=True, description="Text to be synthesized as audio"
+            ),
+        },
+    )
+
+    @api.expect(tts_model)
+    @api.doc(description="Synthesize audio speech from text")
+    def post(self):
+        data = request.get_json()
+        text = data["text"]
+        try:
+            tts_instance = TTSCreator.create_tts(settings.TTS_PROVIDER)
+            audio_base64, detected_language = tts_instance.text_to_speech(text)
+            return make_response(
+                jsonify(
+                    {
+                        "success": True,
+                        "audio_base64": audio_base64,
+                        "lang": detected_language,
+                    }
+                ),
+                200,
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error synthesizing audio: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)

application/api/user/base.py

@@ -0,0 +1,222 @@
+"""
+Shared utilities, database connections, and helper functions for user API routes.
+"""
+
+import datetime
+import os
+import uuid
+from functools import wraps
+from typing import Optional, Tuple
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, Response
+from pymongo import ReturnDocument
+from werkzeug.utils import secure_filename
+
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.storage.storage_creator import StorageCreator
+from application.vectorstore.vector_creator import VectorCreator
+
+
+storage = StorageCreator.get_storage()
+
+
+mongo = MongoDB.get_client()
+db = mongo[settings.MONGO_DB_NAME]
+
+
+conversations_collection = db["conversations"]
+sources_collection = db["sources"]
+prompts_collection = db["prompts"]
+feedback_collection = db["feedback"]
+agents_collection = db["agents"]
+token_usage_collection = db["token_usage"]
+shared_conversations_collections = db["shared_conversations"]
+users_collection = db["users"]
+user_logs_collection = db["user_logs"]
+user_tools_collection = db["user_tools"]
+attachments_collection = db["attachments"]
+
+
+try:
+    agents_collection.create_index(
+        [("shared", 1)],
+        name="shared_index",
+        background=True,
+    )
+    users_collection.create_index("user_id", unique=True)
+except Exception as e:
+    print("Error creating indexes:", e)
+current_dir = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
+
+
+def generate_minute_range(start_date, end_date):
+    """Generate a dictionary with minute-level time ranges."""
+    return {
+        (start_date + datetime.timedelta(minutes=i)).strftime("%Y-%m-%d %H:%M:00"): 0
+        for i in range(int((end_date - start_date).total_seconds() // 60) + 1)
+    }
+
+
+def generate_hourly_range(start_date, end_date):
+    """Generate a dictionary with hourly time ranges."""
+    return {
+        (start_date + datetime.timedelta(hours=i)).strftime("%Y-%m-%d %H:00"): 0
+        for i in range(int((end_date - start_date).total_seconds() // 3600) + 1)
+    }
+
+
+def generate_date_range(start_date, end_date):
+    """Generate a dictionary with daily date ranges."""
+    return {
+        (start_date + datetime.timedelta(days=i)).strftime("%Y-%m-%d"): 0
+        for i in range((end_date - start_date).days + 1)
+    }
+
+
+def ensure_user_doc(user_id):
+    """
+    Ensure user document exists with proper agent preferences structure.
+
+    Args:
+        user_id: The user ID to ensure
+
+    Returns:
+        The user document
+    """
+    default_prefs = {
+        "pinned": [],
+        "shared_with_me": [],
+    }
+
+    user_doc = users_collection.find_one_and_update(
+        {"user_id": user_id},
+        {"$setOnInsert": {"agent_preferences": default_prefs}},
+        upsert=True,
+        return_document=ReturnDocument.AFTER,
+    )
+
+    prefs = user_doc.get("agent_preferences", {})
+    updates = {}
+    if "pinned" not in prefs:
+        updates["agent_preferences.pinned"] = []
+    if "shared_with_me" not in prefs:
+        updates["agent_preferences.shared_with_me"] = []
+    if updates:
+        users_collection.update_one({"user_id": user_id}, {"$set": updates})
+        user_doc = users_collection.find_one({"user_id": user_id})
+    return user_doc
+
+
+def resolve_tool_details(tool_ids):
+    """
+    Resolve tool IDs to their details.
+
+    Args:
+        tool_ids: List of tool IDs
+
+    Returns:
+        List of tool details with id, name, and display_name
+    """
+    tools = user_tools_collection.find(
+        {"_id": {"$in": [ObjectId(tid) for tid in tool_ids]}}
+    )
+    return [
+        {
+            "id": str(tool["_id"]),
+            "name": tool.get("name", ""),
+            "display_name": tool.get("displayName", tool.get("name", "")),
+        }
+        for tool in tools
+    ]
+
+
+def get_vector_store(source_id):
+    """
+    Get the Vector Store for a given source ID.
+
+    Args:
+        source_id (str): source id of the document
+
+    Returns:
+        Vector store instance
+    """
+    store = VectorCreator.create_vectorstore(
+        settings.VECTOR_STORE,
+        source_id=source_id,
+        embeddings_key=os.getenv("EMBEDDINGS_KEY"),
+    )
+    return store
+
+
+def handle_image_upload(
+    request, existing_url: str, user: str, storage, base_path: str = "attachments/"
+) -> Tuple[str, Optional[Response]]:
+    """
+    Handle image file upload from request.
+
+    Args:
+        request: Flask request object
+        existing_url: Existing image URL (fallback)
+        user: User ID
+        storage: Storage instance
+        base_path: Base path for upload
+
+    Returns:
+        Tuple of (image_url, error_response)
+    """
+    image_url = existing_url
+
+    if "image" in request.files:
+        file = request.files["image"]
+        if file.filename != "":
+            filename = secure_filename(file.filename)
+            upload_path = f"{settings.UPLOAD_FOLDER.rstrip('/')}/{user}/{base_path.rstrip('/')}/{uuid.uuid4()}_{filename}"
+            try:
+                storage.save_file(file, upload_path, storage_class="STANDARD")
+                image_url = upload_path
+            except Exception as e:
+                current_app.logger.error(f"Error uploading image: {e}")
+                return None, make_response(
+                    jsonify({"success": False, "message": "Image upload failed"}),
+                    400,
+                )
+    return image_url, None
+
+
+def require_agent(func):
+    """
+    Decorator to require valid agent webhook token.
+
+    Args:
+        func: Function to decorate
+
+    Returns:
+        Wrapped function
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        webhook_token = kwargs.get("webhook_token")
+        if not webhook_token:
+            return make_response(
+                jsonify({"success": False, "message": "Webhook token missing"}), 400
+            )
+        agent = agents_collection.find_one(
+            {"incoming_webhook_token": webhook_token}, {"_id": 1}
+        )
+        if not agent:
+            current_app.logger.warning(
+                f"Webhook attempt with invalid token: {webhook_token}"
+            )
+            return make_response(
+                jsonify({"success": False, "message": "Agent not found"}), 404
+            )
+        kwargs["agent"] = agent
+        kwargs["agent_id_str"] = str(agent["_id"])
+        return func(*args, **kwargs)
+
+    return wrapper

application/api/user/conversations/__init__.py

@@ -0,0 +1,5 @@
+"""Conversation management module."""
+
+from .routes import conversations_ns
+
+__all__ = ["conversations_ns"]

application/api/user/conversations/routes.py

@@ -0,0 +1,280 @@
+"""Conversation management routes."""
+
+import datetime
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import attachments_collection, conversations_collection
+from application.utils import check_required_fields
+
+conversations_ns = Namespace(
+    "conversations", description="Conversation management operations", path="/api"
+)
+
+
+@conversations_ns.route("/delete_conversation")
+class DeleteConversation(Resource):
+    @api.doc(
+        description="Deletes a conversation by ID",
+        params={"id": "The ID of the conversation to delete"},
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        conversation_id = request.args.get("id")
+        if not conversation_id:
+            return make_response(
+                jsonify({"success": False, "message": "ID is required"}), 400
+            )
+        try:
+            conversations_collection.delete_one(
+                {"_id": ObjectId(conversation_id), "user": decoded_token["sub"]}
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error deleting conversation: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@conversations_ns.route("/delete_all_conversations")
+class DeleteAllConversations(Resource):
+    @api.doc(
+        description="Deletes all conversations for a specific user",
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user_id = decoded_token.get("sub")
+        try:
+            conversations_collection.delete_many({"user": user_id})
+        except Exception as err:
+            current_app.logger.error(
+                f"Error deleting all conversations: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@conversations_ns.route("/get_conversations")
+class GetConversations(Resource):
+    @api.doc(
+        description="Retrieve a list of the latest 30 conversations (excluding API key conversations)",
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        try:
+            conversations = (
+                conversations_collection.find(
+                    {
+                        "$or": [
+                            {"api_key": {"$exists": False}},
+                            {"agent_id": {"$exists": True}},
+                        ],
+                        "user": decoded_token.get("sub"),
+                    }
+                )
+                .sort("date", -1)
+                .limit(30)
+            )
+
+            list_conversations = [
+                {
+                    "id": str(conversation["_id"]),
+                    "name": conversation["name"],
+                    "agent_id": conversation.get("agent_id", None),
+                    "is_shared_usage": conversation.get("is_shared_usage", False),
+                    "shared_token": conversation.get("shared_token", None),
+                }
+                for conversation in conversations
+            ]
+        except Exception as err:
+            current_app.logger.error(
+                f"Error retrieving conversations: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify(list_conversations), 200)
+
+
+@conversations_ns.route("/get_single_conversation")
+class GetSingleConversation(Resource):
+    @api.doc(
+        description="Retrieve a single conversation by ID",
+        params={"id": "The conversation ID"},
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        conversation_id = request.args.get("id")
+        if not conversation_id:
+            return make_response(
+                jsonify({"success": False, "message": "ID is required"}), 400
+            )
+        try:
+            conversation = conversations_collection.find_one(
+                {"_id": ObjectId(conversation_id), "user": decoded_token.get("sub")}
+            )
+            if not conversation:
+                return make_response(jsonify({"status": "not found"}), 404)
+            # Process queries to include attachment names
+
+            queries = conversation["queries"]
+            for query in queries:
+                if "attachments" in query and query["attachments"]:
+                    attachment_details = []
+                    for attachment_id in query["attachments"]:
+                        try:
+                            attachment = attachments_collection.find_one(
+                                {"_id": ObjectId(attachment_id)}
+                            )
+                            if attachment:
+                                attachment_details.append(
+                                    {
+                                        "id": str(attachment["_id"]),
+                                        "fileName": attachment.get(
+                                            "filename", "Unknown file"
+                                        ),
+                                    }
+                                )
+                        except Exception as e:
+                            current_app.logger.error(
+                                f"Error retrieving attachment {attachment_id}: {e}",
+                                exc_info=True,
+                            )
+                    query["attachments"] = attachment_details
+        except Exception as err:
+            current_app.logger.error(
+                f"Error retrieving conversation: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        data = {
+            "queries": queries,
+            "agent_id": conversation.get("agent_id"),
+            "is_shared_usage": conversation.get("is_shared_usage", False),
+            "shared_token": conversation.get("shared_token", None),
+        }
+        return make_response(jsonify(data), 200)
+
+
+@conversations_ns.route("/update_conversation_name")
+class UpdateConversationName(Resource):
+    @api.expect(
+        api.model(
+            "UpdateConversationModel",
+            {
+                "id": fields.String(required=True, description="Conversation ID"),
+                "name": fields.String(
+                    required=True, description="New name of the conversation"
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Updates the name of a conversation",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        data = request.get_json()
+        required_fields = ["id", "name"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            conversations_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": decoded_token.get("sub")},
+                {"$set": {"name": data["name"]}},
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error updating conversation name: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@conversations_ns.route("/feedback")
+class SubmitFeedback(Resource):
+    @api.expect(
+        api.model(
+            "FeedbackModel",
+            {
+                "question": fields.String(
+                    required=False, description="The user question"
+                ),
+                "answer": fields.String(required=False, description="The AI answer"),
+                "feedback": fields.String(required=True, description="User feedback"),
+                "question_index": fields.Integer(
+                    required=True,
+                    description="The question number in that particular conversation",
+                ),
+                "conversation_id": fields.String(
+                    required=True, description="id of the particular conversation"
+                ),
+                "api_key": fields.String(description="Optional API key"),
+            },
+        )
+    )
+    @api.doc(
+        description="Submit feedback for a conversation",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        data = request.get_json()
+        required_fields = ["feedback", "conversation_id", "question_index"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            if data["feedback"] is None:
+                # Remove feedback and feedback_timestamp if feedback is null
+
+                conversations_collection.update_one(
+                    {
+                        "_id": ObjectId(data["conversation_id"]),
+                        "user": decoded_token.get("sub"),
+                        f"queries.{data['question_index']}": {"$exists": True},
+                    },
+                    {
+                        "$unset": {
+                            f"queries.{data['question_index']}.feedback": "",
+                            f"queries.{data['question_index']}.feedback_timestamp": "",
+                        }
+                    },
+                )
+            else:
+                # Set feedback and feedback_timestamp if feedback has a value
+
+                conversations_collection.update_one(
+                    {
+                        "_id": ObjectId(data["conversation_id"]),
+                        "user": decoded_token.get("sub"),
+                        f"queries.{data['question_index']}": {"$exists": True},
+                    },
+                    {
+                        "$set": {
+                            f"queries.{data['question_index']}.feedback": data[
+                                "feedback"
+                            ],
+                            f"queries.{data['question_index']}.feedback_timestamp": datetime.datetime.now(
+                                datetime.timezone.utc
+                            ),
+                        }
+                    },
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error submitting feedback: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)

application/api/user/models/__init__.py

@@ -0,0 +1,3 @@
+from .routes import models_ns
+
+__all__ = ["models_ns"]

application/api/user/models/routes.py

@@ -0,0 +1,25 @@
+from flask import current_app, jsonify, make_response
+from flask_restx import Namespace, Resource
+
+from application.core.model_settings import ModelRegistry
+
+models_ns = Namespace("models", description="Available models", path="/api")
+
+
+@models_ns.route("/models")
+class ModelsListResource(Resource):
+    def get(self):
+        """Get list of available models with their capabilities."""
+        try:
+            registry = ModelRegistry.get_instance()
+            models = registry.get_enabled_models()
+
+            response = {
+                "models": [model.to_dict() for model in models],
+                "default_model_id": registry.default_model_id,
+                "count": len(models),
+            }
+        except Exception as err:
+            current_app.logger.error(f"Error fetching models: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)
+        return make_response(jsonify(response), 200)

application/api/user/prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Prompts module."""
+
+from .routes import prompts_ns
+
+__all__ = ["prompts_ns"]

application/api/user/prompts/routes.py

@@ -0,0 +1,191 @@
+"""Prompt management routes."""
+
+import os
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import current_dir, prompts_collection
+from application.utils import check_required_fields
+
+prompts_ns = Namespace(
+    "prompts", description="Prompt management operations", path="/api"
+)
+
+
+@prompts_ns.route("/create_prompt")
+class CreatePrompt(Resource):
+    create_prompt_model = api.model(
+        "CreatePromptModel",
+        {
+            "content": fields.String(
+                required=True, description="Content of the prompt"
+            ),
+            "name": fields.String(required=True, description="Name of the prompt"),
+        },
+    )
+
+    @api.expect(create_prompt_model)
+    @api.doc(description="Create a new prompt")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        data = request.get_json()
+        required_fields = ["content", "name"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        user = decoded_token.get("sub")
+        try:
+
+            resp = prompts_collection.insert_one(
+                {
+                    "name": data["name"],
+                    "content": data["content"],
+                    "user": user,
+                }
+            )
+            new_id = str(resp.inserted_id)
+        except Exception as err:
+            current_app.logger.error(f"Error creating prompt: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"id": new_id}), 200)
+
+
+@prompts_ns.route("/get_prompts")
+class GetPrompts(Resource):
+    @api.doc(description="Get all prompts for the user")
+    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:
+            prompts = prompts_collection.find({"user": user})
+            list_prompts = [
+                {"id": "default", "name": "default", "type": "public"},
+                {"id": "creative", "name": "creative", "type": "public"},
+                {"id": "strict", "name": "strict", "type": "public"},
+            ]
+
+            for prompt in prompts:
+                list_prompts.append(
+                    {
+                        "id": str(prompt["_id"]),
+                        "name": prompt["name"],
+                        "type": "private",
+                    }
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving prompts: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify(list_prompts), 200)
+
+
+@prompts_ns.route("/get_single_prompt")
+class GetSinglePrompt(Resource):
+    @api.doc(params={"id": "ID of the prompt"}, description="Get a single prompt by ID")
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        prompt_id = request.args.get("id")
+        if not prompt_id:
+            return make_response(
+                jsonify({"success": False, "message": "ID is required"}), 400
+            )
+        try:
+            if prompt_id == "default":
+                with open(
+                    os.path.join(current_dir, "prompts", "chat_combine_default.txt"),
+                    "r",
+                ) as f:
+                    chat_combine_template = f.read()
+                return make_response(jsonify({"content": chat_combine_template}), 200)
+            elif prompt_id == "creative":
+                with open(
+                    os.path.join(current_dir, "prompts", "chat_combine_creative.txt"),
+                    "r",
+                ) as f:
+                    chat_reduce_creative = f.read()
+                return make_response(jsonify({"content": chat_reduce_creative}), 200)
+            elif prompt_id == "strict":
+                with open(
+                    os.path.join(current_dir, "prompts", "chat_combine_strict.txt"), "r"
+                ) as f:
+                    chat_reduce_strict = f.read()
+                return make_response(jsonify({"content": chat_reduce_strict}), 200)
+            prompt = prompts_collection.find_one(
+                {"_id": ObjectId(prompt_id), "user": user}
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving prompt: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"content": prompt["content"]}), 200)
+
+
+@prompts_ns.route("/delete_prompt")
+class DeletePrompt(Resource):
+    delete_prompt_model = api.model(
+        "DeletePromptModel",
+        {"id": fields.String(required=True, description="Prompt ID to delete")},
+    )
+
+    @api.expect(delete_prompt_model)
+    @api.doc(description="Delete a prompt by ID")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            prompts_collection.delete_one({"_id": ObjectId(data["id"]), "user": user})
+        except Exception as err:
+            current_app.logger.error(f"Error deleting prompt: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@prompts_ns.route("/update_prompt")
+class UpdatePrompt(Resource):
+    update_prompt_model = api.model(
+        "UpdatePromptModel",
+        {
+            "id": fields.String(required=True, description="Prompt ID to update"),
+            "name": fields.String(required=True, description="New name of the prompt"),
+            "content": fields.String(
+                required=True, description="New content of the prompt"
+            ),
+        },
+    )
+
+    @api.expect(update_prompt_model)
+    @api.doc(description="Update an existing prompt")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "name", "content"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            prompts_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": user},
+                {"$set": {"name": data["name"], "content": data["content"]}},
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error updating prompt: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)

application/api/user/sharing/__init__.py

@@ -0,0 +1,5 @@
+"""Sharing module."""
+
+from .routes import sharing_ns
+
+__all__ = ["sharing_ns"]

application/api/user/sharing/routes.py

@@ -0,0 +1,289 @@
+"""Conversation sharing routes."""
+
+import uuid
+
+from bson.binary import Binary, UuidRepresentation
+from bson.dbref import DBRef
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, inputs, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import (
+    agents_collection,
+    attachments_collection,
+    conversations_collection,
+    shared_conversations_collections,
+)
+from application.utils import check_required_fields
+
+sharing_ns = Namespace(
+    "sharing", description="Conversation sharing operations", path="/api"
+)
+
+
+@sharing_ns.route("/share")
+class ShareConversation(Resource):
+    share_conversation_model = api.model(
+        "ShareConversationModel",
+        {
+            "conversation_id": fields.String(
+                required=True, description="Conversation ID"
+            ),
+            "user": fields.String(description="User ID (optional)"),
+            "prompt_id": fields.String(description="Prompt ID (optional)"),
+            "chunks": fields.Integer(description="Chunks count (optional)"),
+        },
+    )
+
+    @api.expect(share_conversation_model)
+    @api.doc(description="Share a conversation")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["conversation_id"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        is_promptable = request.args.get("isPromptable", type=inputs.boolean)
+        if is_promptable is None:
+            return make_response(
+                jsonify({"success": False, "message": "isPromptable is required"}), 400
+            )
+        conversation_id = data["conversation_id"]
+
+        try:
+            conversation = conversations_collection.find_one(
+                {"_id": ObjectId(conversation_id)}
+            )
+            if conversation is None:
+                return make_response(
+                    jsonify(
+                        {
+                            "status": "error",
+                            "message": "Conversation does not exist",
+                        }
+                    ),
+                    404,
+                )
+            current_n_queries = len(conversation["queries"])
+            explicit_binary = Binary.from_uuid(
+                uuid.uuid4(), UuidRepresentation.STANDARD
+            )
+
+            if is_promptable:
+                prompt_id = data.get("prompt_id", "default")
+                chunks = data.get("chunks", "2")
+
+                name = conversation["name"] + "(shared)"
+                new_api_key_data = {
+                    "prompt_id": prompt_id,
+                    "chunks": chunks,
+                    "user": user,
+                }
+
+                if "source" in data and ObjectId.is_valid(data["source"]):
+                    new_api_key_data["source"] = DBRef(
+                        "sources", ObjectId(data["source"])
+                    )
+                if "retriever" in data:
+                    new_api_key_data["retriever"] = data["retriever"]
+                pre_existing_api_document = agents_collection.find_one(new_api_key_data)
+                if pre_existing_api_document:
+                    api_uuid = pre_existing_api_document["key"]
+                    pre_existing = shared_conversations_collections.find_one(
+                        {
+                            "conversation_id": ObjectId(conversation_id),
+                            "isPromptable": is_promptable,
+                            "first_n_queries": current_n_queries,
+                            "user": user,
+                            "api_key": api_uuid,
+                        }
+                    )
+                    if pre_existing is not None:
+                        return make_response(
+                            jsonify(
+                                {
+                                    "success": True,
+                                    "identifier": str(pre_existing["uuid"].as_uuid()),
+                                }
+                            ),
+                            200,
+                        )
+                    else:
+                        shared_conversations_collections.insert_one(
+                            {
+                                "uuid": explicit_binary,
+                                "conversation_id": ObjectId(conversation_id),
+                                "isPromptable": is_promptable,
+                                "first_n_queries": current_n_queries,
+                                "user": user,
+                                "api_key": api_uuid,
+                            }
+                        )
+                        return make_response(
+                            jsonify(
+                                {
+                                    "success": True,
+                                    "identifier": str(explicit_binary.as_uuid()),
+                                }
+                            ),
+                            201,
+                        )
+                else:
+                    api_uuid = str(uuid.uuid4())
+                    new_api_key_data["key"] = api_uuid
+                    new_api_key_data["name"] = name
+
+                    if "source" in data and ObjectId.is_valid(data["source"]):
+                        new_api_key_data["source"] = DBRef(
+                            "sources", ObjectId(data["source"])
+                        )
+                    if "retriever" in data:
+                        new_api_key_data["retriever"] = data["retriever"]
+                    agents_collection.insert_one(new_api_key_data)
+                    shared_conversations_collections.insert_one(
+                        {
+                            "uuid": explicit_binary,
+                            "conversation_id": ObjectId(conversation_id),
+                            "isPromptable": is_promptable,
+                            "first_n_queries": current_n_queries,
+                            "user": user,
+                            "api_key": api_uuid,
+                        }
+                    )
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": True,
+                                "identifier": str(explicit_binary.as_uuid()),
+                            }
+                        ),
+                        201,
+                    )
+            pre_existing = shared_conversations_collections.find_one(
+                {
+                    "conversation_id": ObjectId(conversation_id),
+                    "isPromptable": is_promptable,
+                    "first_n_queries": current_n_queries,
+                    "user": user,
+                }
+            )
+            if pre_existing is not None:
+                return make_response(
+                    jsonify(
+                        {
+                            "success": True,
+                            "identifier": str(pre_existing["uuid"].as_uuid()),
+                        }
+                    ),
+                    200,
+                )
+            else:
+                shared_conversations_collections.insert_one(
+                    {
+                        "uuid": explicit_binary,
+                        "conversation_id": ObjectId(conversation_id),
+                        "isPromptable": is_promptable,
+                        "first_n_queries": current_n_queries,
+                        "user": user,
+                    }
+                )
+                return make_response(
+                    jsonify(
+                        {"success": True, "identifier": str(explicit_binary.as_uuid())}
+                    ),
+                    201,
+                )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error sharing conversation: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+
+
+@sharing_ns.route("/shared_conversation/<string:identifier>")
+class GetPubliclySharedConversations(Resource):
+    @api.doc(description="Get publicly shared conversations by identifier")
+    def get(self, identifier: str):
+        try:
+            query_uuid = Binary.from_uuid(
+                uuid.UUID(identifier), UuidRepresentation.STANDARD
+            )
+            shared = shared_conversations_collections.find_one({"uuid": query_uuid})
+            conversation_queries = []
+
+            if (
+                shared
+                and "conversation_id" in shared
+            ):
+                # conversation_id is now stored as an ObjectId, not a DBRef
+                conversation_id = shared["conversation_id"]
+                conversation = conversations_collection.find_one(
+                    {"_id": conversation_id}
+                )
+                if conversation is None:
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "error": "might have broken url or the conversation does not exist",
+                            }
+                        ),
+                        404,
+                    )
+                conversation_queries = conversation["queries"][
+                    : (shared["first_n_queries"])
+                ]
+
+                for query in conversation_queries:
+                    if "attachments" in query and query["attachments"]:
+                        attachment_details = []
+                        for attachment_id in query["attachments"]:
+                            try:
+                                attachment = attachments_collection.find_one(
+                                    {"_id": ObjectId(attachment_id)}
+                                )
+                                if attachment:
+                                    attachment_details.append(
+                                        {
+                                            "id": str(attachment["_id"]),
+                                            "fileName": attachment.get(
+                                                "filename", "Unknown file"
+                                            ),
+                                        }
+                                    )
+                            except Exception as e:
+                                current_app.logger.error(
+                                    f"Error retrieving attachment {attachment_id}: {e}",
+                                    exc_info=True,
+                                )
+                        query["attachments"] = attachment_details
+            else:
+                return make_response(
+                    jsonify(
+                        {
+                            "success": False,
+                            "error": "might have broken url or the conversation does not exist",
+                        }
+                    ),
+                    404,
+                )
+            date = conversation["_id"].generation_time.isoformat()
+            res = {
+                "success": True,
+                "queries": conversation_queries,
+                "title": conversation["name"],
+                "timestamp": date,
+            }
+            if shared["isPromptable"] and "api_key" in shared:
+                res["api_key"] = shared["api_key"]
+            return make_response(jsonify(res), 200)
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting shared conversation: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)

application/api/user/sources/__init__.py

@@ -0,0 +1,7 @@
+"""Sources module."""
+
+from .chunks import sources_chunks_ns
+from .routes import sources_ns
+from .upload import sources_upload_ns
+
+__all__ = ["sources_ns", "sources_chunks_ns", "sources_upload_ns"]

application/api/user/sources/chunks.py

@@ -0,0 +1,278 @@
+"""Source document management chunk management."""
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import get_vector_store, sources_collection
+from application.utils import check_required_fields, num_tokens_from_string
+
+sources_chunks_ns = Namespace(
+    "sources", description="Source document management operations", path="/api"
+)
+
+
+@sources_chunks_ns.route("/get_chunks")
+class GetChunks(Resource):
+    @api.doc(
+        description="Retrieves chunks from a document, optionally filtered by file path and search term",
+        params={
+            "id": "The document ID",
+            "page": "Page number for pagination",
+            "per_page": "Number of chunks per page",
+            "path": "Optional: Filter chunks by relative file path",
+            "search": "Optional: Search term to filter chunks by title or content",
+        },
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        doc_id = request.args.get("id")
+        page = int(request.args.get("page", 1))
+        per_page = int(request.args.get("per_page", 10))
+        path = request.args.get("path")
+        search_term = request.args.get("search", "").strip().lower()
+
+        if not ObjectId.is_valid(doc_id):
+            return make_response(jsonify({"error": "Invalid doc_id"}), 400)
+        doc = sources_collection.find_one({"_id": ObjectId(doc_id), "user": user})
+        if not doc:
+            return make_response(
+                jsonify({"error": "Document not found or access denied"}), 404
+            )
+        try:
+            store = get_vector_store(doc_id)
+            chunks = store.get_chunks()
+
+            filtered_chunks = []
+            for chunk in chunks:
+                metadata = chunk.get("metadata", {})
+
+                # Filter by path if provided
+
+                if path:
+                    chunk_source = metadata.get("source", "")
+                    # Check if the chunk's source matches the requested path
+
+                    if not chunk_source or not chunk_source.endswith(path):
+                        continue
+                # Filter by search term if provided
+
+                if search_term:
+                    text_match = search_term in chunk.get("text", "").lower()
+                    title_match = search_term in metadata.get("title", "").lower()
+
+                    if not (text_match or title_match):
+                        continue
+                filtered_chunks.append(chunk)
+            chunks = filtered_chunks
+
+            total_chunks = len(chunks)
+            start = (page - 1) * per_page
+            end = start + per_page
+            paginated_chunks = chunks[start:end]
+
+            return make_response(
+                jsonify(
+                    {
+                        "page": page,
+                        "per_page": per_page,
+                        "total": total_chunks,
+                        "chunks": paginated_chunks,
+                        "path": path if path else None,
+                        "search": search_term if search_term else None,
+                    }
+                ),
+                200,
+            )
+        except Exception as e:
+            current_app.logger.error(f"Error getting chunks: {e}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)
+
+
+@sources_chunks_ns.route("/add_chunk")
+class AddChunk(Resource):
+    @api.expect(
+        api.model(
+            "AddChunkModel",
+            {
+                "id": fields.String(required=True, description="Document ID"),
+                "text": fields.String(required=True, description="Text of the chunk"),
+                "metadata": fields.Raw(
+                    required=False,
+                    description="Metadata associated with the chunk",
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Adds a new chunk to the document",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "text"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        doc_id = data.get("id")
+        text = data.get("text")
+        metadata = data.get("metadata", {})
+        token_count = num_tokens_from_string(text)
+        metadata["token_count"] = token_count
+
+        if not ObjectId.is_valid(doc_id):
+            return make_response(jsonify({"error": "Invalid doc_id"}), 400)
+        doc = sources_collection.find_one({"_id": ObjectId(doc_id), "user": user})
+        if not doc:
+            return make_response(
+                jsonify({"error": "Document not found or access denied"}), 404
+            )
+        try:
+            store = get_vector_store(doc_id)
+            chunk_id = store.add_chunk(text, metadata)
+            return make_response(
+                jsonify({"message": "Chunk added successfully", "chunk_id": chunk_id}),
+                201,
+            )
+        except Exception as e:
+            current_app.logger.error(f"Error adding chunk: {e}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)
+
+
+@sources_chunks_ns.route("/delete_chunk")
+class DeleteChunk(Resource):
+    @api.doc(
+        description="Deletes a specific chunk from the document.",
+        params={"id": "The document ID", "chunk_id": "The ID of the chunk to delete"},
+    )
+    def delete(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        doc_id = request.args.get("id")
+        chunk_id = request.args.get("chunk_id")
+
+        if not ObjectId.is_valid(doc_id):
+            return make_response(jsonify({"error": "Invalid doc_id"}), 400)
+        doc = sources_collection.find_one({"_id": ObjectId(doc_id), "user": user})
+        if not doc:
+            return make_response(
+                jsonify({"error": "Document not found or access denied"}), 404
+            )
+        try:
+            store = get_vector_store(doc_id)
+            deleted = store.delete_chunk(chunk_id)
+            if deleted:
+                return make_response(
+                    jsonify({"message": "Chunk deleted successfully"}), 200
+                )
+            else:
+                return make_response(
+                    jsonify({"message": "Chunk not found or could not be deleted"}),
+                    404,
+                )
+        except Exception as e:
+            current_app.logger.error(f"Error deleting chunk: {e}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)
+
+
+@sources_chunks_ns.route("/update_chunk")
+class UpdateChunk(Resource):
+    @api.expect(
+        api.model(
+            "UpdateChunkModel",
+            {
+                "id": fields.String(required=True, description="Document ID"),
+                "chunk_id": fields.String(
+                    required=True, description="Chunk ID to update"
+                ),
+                "text": fields.String(
+                    required=False, description="New text of the chunk"
+                ),
+                "metadata": fields.Raw(
+                    required=False,
+                    description="Updated metadata associated with the chunk",
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Updates an existing chunk in the document.",
+    )
+    def put(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "chunk_id"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        doc_id = data.get("id")
+        chunk_id = data.get("chunk_id")
+        text = data.get("text")
+        metadata = data.get("metadata")
+
+        if text is not None:
+            token_count = num_tokens_from_string(text)
+            if metadata is None:
+                metadata = {}
+            metadata["token_count"] = token_count
+        if not ObjectId.is_valid(doc_id):
+            return make_response(jsonify({"error": "Invalid doc_id"}), 400)
+        doc = sources_collection.find_one({"_id": ObjectId(doc_id), "user": user})
+        if not doc:
+            return make_response(
+                jsonify({"error": "Document not found or access denied"}), 404
+            )
+        try:
+            store = get_vector_store(doc_id)
+
+            chunks = store.get_chunks()
+            existing_chunk = next((c for c in chunks if c["doc_id"] == chunk_id), None)
+            if not existing_chunk:
+                return make_response(jsonify({"error": "Chunk not found"}), 404)
+            new_text = text if text is not None else existing_chunk["text"]
+
+            if metadata is not None:
+                new_metadata = existing_chunk["metadata"].copy()
+                new_metadata.update(metadata)
+            else:
+                new_metadata = existing_chunk["metadata"].copy()
+            if text is not None:
+                new_metadata["token_count"] = num_tokens_from_string(new_text)
+            try:
+                new_chunk_id = store.add_chunk(new_text, new_metadata)
+
+                deleted = store.delete_chunk(chunk_id)
+                if not deleted:
+                    current_app.logger.warning(
+                        f"Failed to delete old chunk {chunk_id}, but new chunk {new_chunk_id} was created"
+                    )
+                return make_response(
+                    jsonify(
+                        {
+                            "message": "Chunk updated successfully",
+                            "chunk_id": new_chunk_id,
+                            "original_chunk_id": chunk_id,
+                        }
+                    ),
+                    200,
+                )
+            except Exception as add_error:
+                current_app.logger.error(f"Failed to add updated chunk: {add_error}")
+                return make_response(
+                    jsonify({"error": "Failed to update chunk - addition failed"}), 500
+                )
+        except Exception as e:
+            current_app.logger.error(f"Error updating chunk: {e}", exc_info=True)
+            return make_response(jsonify({"success": False}), 500)

application/api/user/sources/routes.py

@@ -0,0 +1,323 @@
+"""Source document management routes."""
+
+import json
+import math
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, redirect, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import sources_collection
+from application.core.settings import settings
+from application.storage.storage_creator import StorageCreator
+from application.utils import check_required_fields
+from application.vectorstore.vector_creator import VectorCreator
+
+
+sources_ns = Namespace(
+    "sources", description="Source document management operations", path="/api"
+)
+
+
+@sources_ns.route("/sources")
+class CombinedJson(Resource):
+    @api.doc(description="Provide JSON file with combined available indexes")
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = [
+            {
+                "name": "Default",
+                "date": "default",
+                "model": settings.EMBEDDINGS_NAME,
+                "location": "remote",
+                "tokens": "",
+                "retriever": "classic",
+            }
+        ]
+
+        try:
+            for index in sources_collection.find({"user": user}).sort("date", -1):
+                data.append(
+                    {
+                        "id": str(index["_id"]),
+                        "name": index.get("name"),
+                        "date": index.get("date"),
+                        "model": settings.EMBEDDINGS_NAME,
+                        "location": "local",
+                        "tokens": index.get("tokens", ""),
+                        "retriever": index.get("retriever", "classic"),
+                        "syncFrequency": index.get("sync_frequency", ""),
+                        "is_nested": bool(index.get("directory_structure")),
+                        "type": index.get(
+                            "type", "file"
+                        ),  # Add type field with default "file"
+                    }
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error retrieving sources: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify(data), 200)
+
+
+@sources_ns.route("/sources/paginated")
+class PaginatedSources(Resource):
+    @api.doc(description="Get document with pagination, sorting and filtering")
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        sort_field = request.args.get("sort", "date")  # Default to 'date'
+        sort_order = request.args.get("order", "desc")  # Default to 'desc'
+        page = int(request.args.get("page", 1))  # Default to 1
+        rows_per_page = int(request.args.get("rows", 10))  # Default to 10
+        # add .strip() to remove leading and trailing whitespaces
+
+        search_term = request.args.get(
+            "search", ""
+        ).strip()  # add search for filter documents
+
+        # Prepare query for filtering
+
+        query = {"user": user}
+        if search_term:
+            query["name"] = {
+                "$regex": search_term,
+                "$options": "i",  # using case-insensitive search
+            }
+        total_documents = sources_collection.count_documents(query)
+        total_pages = max(1, math.ceil(total_documents / rows_per_page))
+        page = min(
+            max(1, page), total_pages
+        )  # add this to make sure page inbound is within the range
+        sort_order = 1 if sort_order == "asc" else -1
+        skip = (page - 1) * rows_per_page
+
+        try:
+            documents = (
+                sources_collection.find(query)
+                .sort(sort_field, sort_order)
+                .skip(skip)
+                .limit(rows_per_page)
+            )
+
+            paginated_docs = []
+            for doc in documents:
+                doc_data = {
+                    "id": str(doc["_id"]),
+                    "name": doc.get("name", ""),
+                    "date": doc.get("date", ""),
+                    "model": settings.EMBEDDINGS_NAME,
+                    "location": "local",
+                    "tokens": doc.get("tokens", ""),
+                    "retriever": doc.get("retriever", "classic"),
+                    "syncFrequency": doc.get("sync_frequency", ""),
+                    "isNested": bool(doc.get("directory_structure")),
+                    "type": doc.get("type", "file"),
+                }
+                paginated_docs.append(doc_data)
+            response = {
+                "total": total_documents,
+                "totalPages": total_pages,
+                "currentPage": page,
+                "paginated": paginated_docs,
+            }
+            return make_response(jsonify(response), 200)
+        except Exception as err:
+            current_app.logger.error(
+                f"Error retrieving paginated sources: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+
+
+@sources_ns.route("/delete_by_ids")
+class DeleteByIds(Resource):
+    @api.doc(
+        description="Deletes documents from the vector store by IDs",
+        params={"path": "Comma-separated list of IDs"},
+    )
+    def get(self):
+        ids = request.args.get("path")
+        if not ids:
+            return make_response(
+                jsonify({"success": False, "message": "Missing required fields"}), 400
+            )
+        try:
+            result = sources_collection.delete_index(ids=ids)
+            if result:
+                return make_response(jsonify({"success": True}), 200)
+        except Exception as err:
+            current_app.logger.error(f"Error deleting indexes: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": False}), 400)
+
+
+@sources_ns.route("/delete_old")
+class DeleteOldIndexes(Resource):
+    @api.doc(
+        description="Deletes old indexes and associated files",
+        params={"source_id": "The source ID to delete"},
+    )
+    def get(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": "Missing required fields"}), 400
+            )
+        doc = sources_collection.find_one(
+            {"_id": ObjectId(source_id), "user": decoded_token.get("sub")}
+        )
+        if not doc:
+            return make_response(jsonify({"status": "not found"}), 404)
+        storage = StorageCreator.get_storage()
+
+        try:
+            # Delete vector index
+
+            if settings.VECTOR_STORE == "faiss":
+                index_path = f"indexes/{str(doc['_id'])}"
+                if storage.file_exists(f"{index_path}/index.faiss"):
+                    storage.delete_file(f"{index_path}/index.faiss")
+                if storage.file_exists(f"{index_path}/index.pkl"):
+                    storage.delete_file(f"{index_path}/index.pkl")
+            else:
+                vectorstore = VectorCreator.create_vectorstore(
+                    settings.VECTOR_STORE, source_id=str(doc["_id"])
+                )
+                vectorstore.delete_index()
+            if "file_path" in doc and doc["file_path"]:
+                file_path = doc["file_path"]
+                if storage.is_directory(file_path):
+                    files = storage.list_files(file_path)
+                    for f in files:
+                        storage.delete_file(f)
+                else:
+                    storage.delete_file(file_path)
+        except FileNotFoundError:
+            pass
+        except Exception as err:
+            current_app.logger.error(
+                f"Error deleting files and indexes: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        sources_collection.delete_one({"_id": ObjectId(source_id)})
+        return make_response(jsonify({"success": True}), 200)
+
+
+@sources_ns.route("/combine")
+class RedirectToSources(Resource):
+    @api.doc(
+        description="Redirects /api/combine to /api/sources for backward compatibility"
+    )
+    def get(self):
+        return redirect("/api/sources", code=301)
+
+
+@sources_ns.route("/manage_sync")
+class ManageSync(Resource):
+    manage_sync_model = api.model(
+        "ManageSyncModel",
+        {
+            "source_id": fields.String(required=True, description="Source ID"),
+            "sync_frequency": fields.String(
+                required=True,
+                description="Sync frequency (never, daily, weekly, monthly)",
+            ),
+        },
+    )
+
+    @api.expect(manage_sync_model)
+    @api.doc(description="Manage sync frequency for sources")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["source_id", "sync_frequency"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        source_id = data["source_id"]
+        sync_frequency = data["sync_frequency"]
+
+        if sync_frequency not in ["never", "daily", "weekly", "monthly"]:
+            return make_response(
+                jsonify({"success": False, "message": "Invalid frequency"}), 400
+            )
+        update_data = {"$set": {"sync_frequency": sync_frequency}}
+        try:
+            sources_collection.update_one(
+                {
+                    "_id": ObjectId(source_id),
+                    "user": user,
+                },
+                update_data,
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error updating sync frequency: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@sources_ns.route("/directory_structure")
+class DirectoryStructure(Resource):
+    @api.doc(
+        description="Get the directory structure for a document",
+        params={"id": "The document ID"},
+    )
+    def get(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        doc_id = request.args.get("id")
+
+        if not doc_id:
+            return make_response(jsonify({"error": "Document ID is required"}), 400)
+        if not ObjectId.is_valid(doc_id):
+            return make_response(jsonify({"error": "Invalid document ID"}), 400)
+        try:
+            doc = sources_collection.find_one({"_id": ObjectId(doc_id), "user": user})
+            if not doc:
+                return make_response(
+                    jsonify({"error": "Document not found or access denied"}), 404
+                )
+            directory_structure = doc.get("directory_structure", {})
+            base_path = doc.get("file_path", "")
+
+            provider = None
+            remote_data = doc.get("remote_data")
+            try:
+                if isinstance(remote_data, str) and remote_data:
+                    remote_data_obj = json.loads(remote_data)
+                    provider = remote_data_obj.get("provider")
+            except Exception as e:
+                current_app.logger.warning(
+                    f"Failed to parse remote_data for doc {doc_id}: {e}"
+                )
+            return make_response(
+                jsonify(
+                    {
+                        "success": True,
+                        "directory_structure": directory_structure,
+                        "base_path": base_path,
+                        "provider": provider,
+                    }
+                ),
+                200,
+            )
+        except Exception as e:
+            current_app.logger.error(
+                f"Error retrieving directory structure: {e}", exc_info=True
+            )
+            return make_response(jsonify({"success": False, "error": str(e)}), 500)

application/api/user/sources/upload.py

@@ -0,0 +1,583 @@
+"""Source document management upload functionality."""
+
+import json
+import os
+import tempfile
+import zipfile
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.api import api
+from application.api.user.base import sources_collection
+from application.api.user.tasks import ingest, ingest_connector_task, ingest_remote
+from application.core.settings import settings
+from application.parser.connectors.connector_creator import ConnectorCreator
+from application.storage.storage_creator import StorageCreator
+from application.utils import check_required_fields, safe_filename
+
+
+sources_upload_ns = Namespace(
+    "sources", description="Source document management operations", path="/api"
+)
+
+
+@sources_upload_ns.route("/upload")
+class UploadFile(Resource):
+    @api.expect(
+        api.model(
+            "UploadModel",
+            {
+                "user": fields.String(required=True, description="User ID"),
+                "name": fields.String(required=True, description="Job name"),
+                "file": fields.Raw(required=True, description="File(s) to upload"),
+            },
+        )
+    )
+    @api.doc(
+        description="Uploads a file to be vectorized and indexed",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        data = request.form
+        files = request.files.getlist("file")
+        required_fields = ["user", "name"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields or not files or all(file.filename == "" for file in files):
+            return make_response(
+                jsonify(
+                    {
+                        "status": "error",
+                        "message": "Missing required fields or files",
+                    }
+                ),
+                400,
+            )
+        user = decoded_token.get("sub")
+        job_name = request.form["name"]
+
+        # Create safe versions for filesystem operations
+
+        safe_user = safe_filename(user)
+        dir_name = safe_filename(job_name)
+        base_path = f"{settings.UPLOAD_FOLDER}/{safe_user}/{dir_name}"
+
+        try:
+            storage = StorageCreator.get_storage()
+
+            for file in files:
+                original_filename = file.filename
+                safe_file = safe_filename(original_filename)
+
+                with tempfile.TemporaryDirectory() as temp_dir:
+                    temp_file_path = os.path.join(temp_dir, safe_file)
+                    file.save(temp_file_path)
+
+                    if zipfile.is_zipfile(temp_file_path):
+                        try:
+                            with zipfile.ZipFile(temp_file_path, "r") as zip_ref:
+                                zip_ref.extractall(path=temp_dir)
+
+                                # Walk through extracted files and upload them
+
+                                for root, _, files in os.walk(temp_dir):
+                                    for extracted_file in files:
+                                        if (
+                                            os.path.join(root, extracted_file)
+                                            == temp_file_path
+                                        ):
+                                            continue
+                                        rel_path = os.path.relpath(
+                                            os.path.join(root, extracted_file), temp_dir
+                                        )
+                                        storage_path = f"{base_path}/{rel_path}"
+
+                                        with open(
+                                            os.path.join(root, extracted_file), "rb"
+                                        ) as f:
+                                            storage.save_file(f, storage_path)
+                        except Exception as e:
+                            current_app.logger.error(
+                                f"Error extracting zip: {e}", exc_info=True
+                            )
+                            # If zip extraction fails, save the original zip file
+
+                            file_path = f"{base_path}/{safe_file}"
+                            with open(temp_file_path, "rb") as f:
+                                storage.save_file(f, file_path)
+                    else:
+                        # For non-zip files, save directly
+
+                        file_path = f"{base_path}/{safe_file}"
+                        with open(temp_file_path, "rb") as f:
+                            storage.save_file(f, file_path)
+            task = ingest.delay(
+                settings.UPLOAD_FOLDER,
+                [
+                    ".rst",
+                    ".md",
+                    ".pdf",
+                    ".txt",
+                    ".docx",
+                    ".csv",
+                    ".epub",
+                    ".html",
+                    ".mdx",
+                    ".json",
+                    ".xlsx",
+                    ".pptx",
+                    ".png",
+                    ".jpg",
+                    ".jpeg",
+                ],
+                job_name,
+                user,
+                file_path=base_path,
+                filename=dir_name,
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error uploading file: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True, "task_id": task.id}), 200)
+
+
+@sources_upload_ns.route("/remote")
+class UploadRemote(Resource):
+    @api.expect(
+        api.model(
+            "RemoteUploadModel",
+            {
+                "user": fields.String(required=True, description="User ID"),
+                "source": fields.String(
+                    required=True, description="Source of the data"
+                ),
+                "name": fields.String(required=True, description="Job name"),
+                "data": fields.String(required=True, description="Data to process"),
+                "repo_url": fields.String(description="GitHub repository URL"),
+            },
+        )
+    )
+    @api.doc(
+        description="Uploads remote 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
+
+            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,
+                    )
+                # Process file_ids
+
+                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 = []
+                # Process folder_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"),
+                )
+                return make_response(
+                    jsonify({"success": True, "task_id": task.id}), 200
+                )
+            task = ingest_remote.delay(
+                source_data=source_data,
+                job_name=data["name"],
+                user=decoded_token.get("sub"),
+                loader=data["source"],
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error uploading remote source: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True, "task_id": task.id}), 200)
+
+
+@sources_upload_ns.route("/manage_source_files")
+class ManageSourceFiles(Resource):
+    @api.expect(
+        api.model(
+            "ManageSourceFilesModel",
+            {
+                "source_id": fields.String(
+                    required=True, description="Source ID to modify"
+                ),
+                "operation": fields.String(
+                    required=True,
+                    description="Operation: 'add', 'remove', or 'remove_directory'",
+                ),
+                "file_paths": fields.List(
+                    fields.String,
+                    required=False,
+                    description="File paths to remove (for remove operation)",
+                ),
+                "directory_path": fields.String(
+                    required=False,
+                    description="Directory path to remove (for remove_directory operation)",
+                ),
+                "file": fields.Raw(
+                    required=False, description="Files to add (for add operation)"
+                ),
+                "parent_dir": fields.String(
+                    required=False,
+                    description="Parent directory path relative to source root",
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Add files, remove files, or remove directories from an existing source",
+    )
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(
+                jsonify({"success": False, "message": "Unauthorized"}), 401
+            )
+        user = decoded_token.get("sub")
+        source_id = request.form.get("source_id")
+        operation = request.form.get("operation")
+
+        if not source_id or not operation:
+            return make_response(
+                jsonify(
+                    {
+                        "success": False,
+                        "message": "source_id and operation are required",
+                    }
+                ),
+                400,
+            )
+        if operation not in ["add", "remove", "remove_directory"]:
+            return make_response(
+                jsonify(
+                    {
+                        "success": False,
+                        "message": "operation must be 'add', 'remove', or 'remove_directory'",
+                    }
+                ),
+                400,
+            )
+        try:
+            ObjectId(source_id)
+        except Exception:
+            return make_response(
+                jsonify({"success": False, "message": "Invalid source ID format"}), 400
+            )
+        try:
+            source = sources_collection.find_one(
+                {"_id": ObjectId(source_id), "user": user}
+            )
+            if not source:
+                return make_response(
+                    jsonify(
+                        {
+                            "success": False,
+                            "message": "Source not found or access denied",
+                        }
+                    ),
+                    404,
+                )
+        except Exception as err:
+            current_app.logger.error(f"Error finding source: {err}", exc_info=True)
+            return make_response(
+                jsonify({"success": False, "message": "Database error"}), 500
+            )
+        try:
+            storage = StorageCreator.get_storage()
+            source_file_path = source.get("file_path", "")
+            parent_dir = request.form.get("parent_dir", "")
+
+            if parent_dir and (parent_dir.startswith("/") or ".." in parent_dir):
+                return make_response(
+                    jsonify(
+                        {"success": False, "message": "Invalid parent directory path"}
+                    ),
+                    400,
+                )
+            if operation == "add":
+                files = request.files.getlist("file")
+                if not files or all(file.filename == "" for file in files):
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "message": "No files provided for add operation",
+                            }
+                        ),
+                        400,
+                    )
+                added_files = []
+
+                target_dir = source_file_path
+                if parent_dir:
+                    target_dir = f"{source_file_path}/{parent_dir}"
+                for file in files:
+                    if file.filename:
+                        safe_filename_str = safe_filename(file.filename)
+                        file_path = f"{target_dir}/{safe_filename_str}"
+
+                        # Save file to storage
+
+                        storage.save_file(file, file_path)
+                        added_files.append(safe_filename_str)
+                # Trigger re-ingestion pipeline
+
+                from application.api.user.tasks import reingest_source_task
+
+                task = reingest_source_task.delay(source_id=source_id, user=user)
+
+                return make_response(
+                    jsonify(
+                        {
+                            "success": True,
+                            "message": f"Added {len(added_files)} files",
+                            "added_files": added_files,
+                            "parent_dir": parent_dir,
+                            "reingest_task_id": task.id,
+                        }
+                    ),
+                    200,
+                )
+            elif operation == "remove":
+                file_paths_str = request.form.get("file_paths")
+                if not file_paths_str:
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "message": "file_paths required for remove operation",
+                            }
+                        ),
+                        400,
+                    )
+                try:
+                    file_paths = (
+                        json.loads(file_paths_str)
+                        if isinstance(file_paths_str, str)
+                        else file_paths_str
+                    )
+                except Exception:
+                    return make_response(
+                        jsonify(
+                            {"success": False, "message": "Invalid file_paths format"}
+                        ),
+                        400,
+                    )
+                # Remove files from storage and directory structure
+
+                removed_files = []
+                for file_path in file_paths:
+                    full_path = f"{source_file_path}/{file_path}"
+
+                    # Remove from storage
+
+                    if storage.file_exists(full_path):
+                        storage.delete_file(full_path)
+                        removed_files.append(file_path)
+                # Trigger re-ingestion pipeline
+
+                from application.api.user.tasks import reingest_source_task
+
+                task = reingest_source_task.delay(source_id=source_id, user=user)
+
+                return make_response(
+                    jsonify(
+                        {
+                            "success": True,
+                            "message": f"Removed {len(removed_files)} files",
+                            "removed_files": removed_files,
+                            "reingest_task_id": task.id,
+                        }
+                    ),
+                    200,
+                )
+            elif operation == "remove_directory":
+                directory_path = request.form.get("directory_path")
+                if not directory_path:
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "message": "directory_path required for remove_directory operation",
+                            }
+                        ),
+                        400,
+                    )
+                # Validate directory path (prevent path traversal)
+
+                if directory_path.startswith("/") or ".." in directory_path:
+                    current_app.logger.warning(
+                        f"Invalid directory path attempted for removal. "
+                        f"User: {user}, Source ID: {source_id}, Directory path: {directory_path}"
+                    )
+                    return make_response(
+                        jsonify(
+                            {"success": False, "message": "Invalid directory path"}
+                        ),
+                        400,
+                    )
+                full_directory_path = (
+                    f"{source_file_path}/{directory_path}"
+                    if directory_path
+                    else source_file_path
+                )
+
+                if not storage.is_directory(full_directory_path):
+                    current_app.logger.warning(
+                        f"Directory not found or is not a directory for removal. "
+                        f"User: {user}, Source ID: {source_id}, Directory path: {directory_path}, "
+                        f"Full path: {full_directory_path}"
+                    )
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "message": "Directory not found or is not a directory",
+                            }
+                        ),
+                        404,
+                    )
+                success = storage.remove_directory(full_directory_path)
+
+                if not success:
+                    current_app.logger.error(
+                        f"Failed to remove directory from storage. "
+                        f"User: {user}, Source ID: {source_id}, Directory path: {directory_path}, "
+                        f"Full path: {full_directory_path}"
+                    )
+                    return make_response(
+                        jsonify(
+                            {"success": False, "message": "Failed to remove directory"}
+                        ),
+                        500,
+                    )
+                current_app.logger.info(
+                    f"Successfully removed directory. "
+                    f"User: {user}, Source ID: {source_id}, Directory path: {directory_path}, "
+                    f"Full path: {full_directory_path}"
+                )
+
+                # Trigger re-ingestion pipeline
+
+                from application.api.user.tasks import reingest_source_task
+
+                task = reingest_source_task.delay(source_id=source_id, user=user)
+
+                return make_response(
+                    jsonify(
+                        {
+                            "success": True,
+                            "message": f"Successfully removed directory: {directory_path}",
+                            "removed_directory": directory_path,
+                            "reingest_task_id": task.id,
+                        }
+                    ),
+                    200,
+                )
+        except Exception as err:
+            error_context = f"operation={operation}, user={user}, source_id={source_id}"
+            if operation == "remove_directory":
+                directory_path = request.form.get("directory_path", "")
+                error_context += f", directory_path={directory_path}"
+            elif operation == "remove":
+                file_paths_str = request.form.get("file_paths", "")
+                error_context += f", file_paths={file_paths_str}"
+            elif operation == "add":
+                parent_dir = request.form.get("parent_dir", "")
+                error_context += f", parent_dir={parent_dir}"
+            current_app.logger.error(
+                f"Error managing source files: {err} ({error_context})", exc_info=True
+            )
+            return make_response(
+                jsonify({"success": False, "message": "Operation failed"}), 500
+            )
+
+
+@sources_upload_ns.route("/task_status")
+class TaskStatus(Resource):
+    task_status_model = api.model(
+        "TaskStatusModel",
+        {"task_id": fields.String(required=True, description="Task ID")},
+    )
+
+    @api.expect(task_status_model)
+    @api.doc(description="Get celery job 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 task.status == "PENDING":
+                inspect = celery.control.inspect()
+                active_workers = inspect.ping()
+                if not active_workers:
+                    raise ConnectionError("Service unavailable")
+
+            if not isinstance(
+                task_meta, (dict, list, str, int, float, bool, type(None))
+            ):
+                task_meta = str(task_meta)  # Convert to a string representation
+        except ConnectionError as err:
+            return make_response(
+                jsonify({"success": False, "message": str(err)}), 503
+            )
+        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)

application/api/user/tools/__init__.py

@@ -0,0 +1,6 @@
+"""Tools module."""
+
+from .mcp import tools_mcp_ns
+from .routes import tools_ns
+
+__all__ = ["tools_ns", "tools_mcp_ns"]

application/api/user/tools/mcp.py

@@ -0,0 +1,333 @@
+"""Tool management MCP server integration."""
+
+import json
+from email.quoprimime import unquote
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, redirect, request
+from flask_restx import fields, Namespace, Resource
+
+from application.agents.tools.mcp_tool import MCPOAuthManager, MCPTool
+from application.api import api
+from application.api.user.base import user_tools_collection
+from application.cache import get_redis_instance
+from application.security.encryption import encrypt_credentials
+from application.utils import check_required_fields
+
+tools_mcp_ns = Namespace("tools", description="Tool management operations", path="/api")
+
+
+@tools_mcp_ns.route("/mcp_server/test")
+class TestMCPServerConfig(Resource):
+    @api.expect(
+        api.model(
+            "MCPServerTestModel",
+            {
+                "config": fields.Raw(
+                    required=True, description="MCP server configuration to test"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Test MCP server connection with provided configuration")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+
+        required_fields = ["config"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            config = data["config"]
+
+            auth_credentials = {}
+            auth_type = config.get("auth_type", "none")
+
+            if auth_type == "api_key" and "api_key" in config:
+                auth_credentials["api_key"] = config["api_key"]
+                if "api_key_header" in config:
+                    auth_credentials["api_key_header"] = config["api_key_header"]
+            elif auth_type == "bearer" and "bearer_token" in config:
+                auth_credentials["bearer_token"] = config["bearer_token"]
+            elif auth_type == "basic":
+                if "username" in config:
+                    auth_credentials["username"] = config["username"]
+                if "password" in config:
+                    auth_credentials["password"] = config["password"]
+            test_config = config.copy()
+            test_config["auth_credentials"] = auth_credentials
+
+            mcp_tool = MCPTool(config=test_config, user_id=user)
+            result = mcp_tool.test_connection()
+
+            return make_response(jsonify(result), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error testing MCP server: {e}", exc_info=True)
+            return make_response(
+                jsonify(
+                    {"success": False, "error": f"Connection test failed: {str(e)}"}
+                ),
+                500,
+            )
+
+
+@tools_mcp_ns.route("/mcp_server/save")
+class MCPServerSave(Resource):
+    @api.expect(
+        api.model(
+            "MCPServerSaveModel",
+            {
+                "id": fields.String(
+                    required=False, description="Tool ID for updates (optional)"
+                ),
+                "displayName": fields.String(
+                    required=True, description="Display name for the MCP server"
+                ),
+                "config": fields.Raw(
+                    required=True, description="MCP server configuration"
+                ),
+                "status": fields.Boolean(
+                    required=False, default=True, description="Tool status"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Create or update MCP server with automatic tool discovery")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+
+        required_fields = ["displayName", "config"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            config = data["config"]
+
+            auth_credentials = {}
+            auth_type = config.get("auth_type", "none")
+            if auth_type == "api_key":
+                if "api_key" in config and config["api_key"]:
+                    auth_credentials["api_key"] = config["api_key"]
+                if "api_key_header" in config:
+                    auth_credentials["api_key_header"] = config["api_key_header"]
+            elif auth_type == "bearer":
+                if "bearer_token" in config and config["bearer_token"]:
+                    auth_credentials["bearer_token"] = config["bearer_token"]
+            elif auth_type == "basic":
+                if "username" in config and config["username"]:
+                    auth_credentials["username"] = config["username"]
+                if "password" in config and config["password"]:
+                    auth_credentials["password"] = config["password"]
+            mcp_config = config.copy()
+            mcp_config["auth_credentials"] = auth_credentials
+
+            if auth_type == "oauth":
+                if not config.get("oauth_task_id"):
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "error": "Connection not authorized. Please complete the OAuth authorization first.",
+                            }
+                        ),
+                        400,
+                    )
+                redis_client = get_redis_instance()
+                manager = MCPOAuthManager(redis_client)
+                result = manager.get_oauth_status(config["oauth_task_id"])
+                if not result.get("status") == "completed":
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "error": "OAuth failed or not completed. Please try authorizing again.",
+                            }
+                        ),
+                        400,
+                    )
+                actions_metadata = result.get("tools", [])
+            elif auth_type == "none" or auth_credentials:
+                mcp_tool = MCPTool(config=mcp_config, user_id=user)
+                mcp_tool.discover_tools()
+                actions_metadata = mcp_tool.get_actions_metadata()
+            else:
+                raise Exception(
+                    "No valid credentials provided for the selected authentication type"
+                )
+            storage_config = config.copy()
+            if auth_credentials:
+                encrypted_credentials_string = encrypt_credentials(
+                    auth_credentials, user
+                )
+                storage_config["encrypted_credentials"] = encrypted_credentials_string
+            for field in [
+                "api_key",
+                "bearer_token",
+                "username",
+                "password",
+                "api_key_header",
+            ]:
+                storage_config.pop(field, None)
+            transformed_actions = []
+            for action in actions_metadata:
+                action["active"] = True
+                if "parameters" in action:
+                    if "properties" in action["parameters"]:
+                        for param_name, param_details in action["parameters"][
+                            "properties"
+                        ].items():
+                            param_details["filled_by_llm"] = True
+                            param_details["value"] = ""
+                transformed_actions.append(action)
+            tool_data = {
+                "name": "mcp_tool",
+                "displayName": data["displayName"],
+                "customName": data["displayName"],
+                "description": f"MCP Server: {storage_config.get('server_url', 'Unknown')}",
+                "config": storage_config,
+                "actions": transformed_actions,
+                "status": data.get("status", True),
+                "user": user,
+            }
+
+            tool_id = data.get("id")
+            if tool_id:
+                result = user_tools_collection.update_one(
+                    {"_id": ObjectId(tool_id), "user": user, "name": "mcp_tool"},
+                    {"$set": {k: v for k, v in tool_data.items() if k != "user"}},
+                )
+                if result.matched_count == 0:
+                    return make_response(
+                        jsonify(
+                            {
+                                "success": False,
+                                "error": "Tool not found or access denied",
+                            }
+                        ),
+                        404,
+                    )
+                response_data = {
+                    "success": True,
+                    "id": tool_id,
+                    "message": f"MCP server updated successfully! Discovered {len(transformed_actions)} tools.",
+                    "tools_count": len(transformed_actions),
+                }
+            else:
+                result = user_tools_collection.insert_one(tool_data)
+                tool_id = str(result.inserted_id)
+                response_data = {
+                    "success": True,
+                    "id": tool_id,
+                    "message": f"MCP server created successfully! Discovered {len(transformed_actions)} tools.",
+                    "tools_count": len(transformed_actions),
+                }
+            return make_response(jsonify(response_data), 200)
+        except Exception as e:
+            current_app.logger.error(f"Error saving MCP server: {e}", exc_info=True)
+            return make_response(
+                jsonify(
+                    {"success": False, "error": f"Failed to save MCP server: {str(e)}"}
+                ),
+                500,
+            )
+
+
+@tools_mcp_ns.route("/mcp_server/callback")
+class MCPOAuthCallback(Resource):
+    @api.expect(
+        api.model(
+            "MCPServerCallbackModel",
+            {
+                "code": fields.String(required=True, description="Authorization code"),
+                "state": fields.String(required=True, description="State parameter"),
+                "error": fields.String(
+                    required=False, description="Error message (if any)"
+                ),
+            },
+        )
+    )
+    @api.doc(
+        description="Handle OAuth callback by providing the authorization code and state"
+    )
+    def get(self):
+        code = request.args.get("code")
+        state = request.args.get("state")
+        error = request.args.get("error")
+
+        if error:
+            return redirect(
+                f"/api/connectors/callback-status?status=error&message=OAuth+error:+{error}.+Please+try+again+and+make+sure+to+grant+all+requested+permissions,+including+offline+access.&provider=mcp_tool"
+            )
+        if not code or not state:
+            return redirect(
+                "/api/connectors/callback-status?status=error&message=Authorization+code+or+state+not+provided.+Please+complete+the+authorization+process+and+make+sure+to+grant+offline+access.&provider=mcp_tool"
+            )
+        try:
+            redis_client = get_redis_instance()
+            if not redis_client:
+                return redirect(
+                    "/api/connectors/callback-status?status=error&message=Internal+server+error:+Redis+not+available.&provider=mcp_tool"
+                )
+            code = unquote(code)
+            manager = MCPOAuthManager(redis_client)
+            success = manager.handle_oauth_callback(state, code, error)
+            if success:
+                return redirect(
+                    "/api/connectors/callback-status?status=success&message=Authorization+code+received+successfully.+You+can+close+this+window.&provider=mcp_tool"
+                )
+            else:
+                return redirect(
+                    "/api/connectors/callback-status?status=error&message=OAuth+callback+failed.&provider=mcp_tool"
+                )
+        except Exception as e:
+            current_app.logger.error(
+                f"Error handling MCP OAuth callback: {str(e)}", exc_info=True
+            )
+            return redirect(
+                f"/api/connectors/callback-status?status=error&message=Internal+server+error:+{str(e)}.&provider=mcp_tool"
+            )
+
+
+@tools_mcp_ns.route("/mcp_server/oauth_status/<string:task_id>")
+class MCPOAuthStatus(Resource):
+    def get(self, task_id):
+        """
+        Get current status of OAuth flow.
+        Frontend should poll this endpoint periodically.
+        """
+        try:
+            redis_client = get_redis_instance()
+            status_key = f"mcp_oauth_status:{task_id}"
+            status_data = redis_client.get(status_key)
+
+            if status_data:
+                status = json.loads(status_data)
+                return make_response(
+                    jsonify({"success": True, "task_id": task_id, **status})
+                )
+            else:
+                return make_response(
+                    jsonify(
+                        {
+                            "success": False,
+                            "error": "Task not found or expired",
+                            "task_id": task_id,
+                        }
+                    ),
+                    404,
+                )
+        except Exception as e:
+            current_app.logger.error(
+                f"Error getting OAuth status for task {task_id}: {str(e)}"
+            )
+            return make_response(
+                jsonify({"success": False, "error": str(e), "task_id": task_id}), 500
+            )

application/api/user/tools/routes.py

@@ -0,0 +1,416 @@
+"""Tool management routes."""
+
+from bson.objectid import ObjectId
+from flask import current_app, jsonify, make_response, request
+from flask_restx import fields, Namespace, Resource
+
+from application.agents.tools.tool_manager import ToolManager
+from application.api import api
+from application.api.user.base import user_tools_collection
+from application.security.encryption import decrypt_credentials, encrypt_credentials
+from application.utils import check_required_fields, validate_function_name
+
+tool_config = {}
+tool_manager = ToolManager(config=tool_config)
+
+
+tools_ns = Namespace("tools", description="Tool management operations", path="/api")
+
+
+@tools_ns.route("/available_tools")
+class AvailableTools(Resource):
+    @api.doc(description="Get available tools for a user")
+    def get(self):
+        try:
+            tools_metadata = []
+            for tool_name, tool_instance in tool_manager.tools.items():
+                doc = tool_instance.__doc__.strip()
+                lines = doc.split("\n", 1)
+                name = lines[0].strip()
+                description = lines[1].strip() if len(lines) > 1 else ""
+                tools_metadata.append(
+                    {
+                        "name": tool_name,
+                        "displayName": name,
+                        "description": description,
+                        "configRequirements": tool_instance.get_config_requirements(),
+                    }
+                )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting available tools: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True, "data": tools_metadata}), 200)
+
+
+@tools_ns.route("/get_tools")
+class GetTools(Resource):
+    @api.doc(description="Get tools created by a user")
+    def get(self):
+        try:
+            decoded_token = request.decoded_token
+            if not decoded_token:
+                return make_response(jsonify({"success": False}), 401)
+            user = decoded_token.get("sub")
+            tools = user_tools_collection.find({"user": user})
+            user_tools = []
+            for tool in tools:
+                tool_copy = {**tool}
+                tool_copy["id"] = str(tool["_id"])
+                tool_copy.pop("_id", None)
+                user_tools.append(tool_copy)
+        except Exception as err:
+            current_app.logger.error(f"Error getting user tools: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True, "tools": user_tools}), 200)
+
+
+@tools_ns.route("/create_tool")
+class CreateTool(Resource):
+    @api.expect(
+        api.model(
+            "CreateToolModel",
+            {
+                "name": fields.String(required=True, description="Name of the tool"),
+                "displayName": fields.String(
+                    required=True, description="Display name for the tool"
+                ),
+                "description": fields.String(
+                    required=True, description="Tool description"
+                ),
+                "config": fields.Raw(
+                    required=True, description="Configuration of the tool"
+                ),
+                "customName": fields.String(
+                    required=False, description="Custom name for the tool"
+                ),
+                "status": fields.Boolean(
+                    required=True, description="Status of the tool"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Create a new tool")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = [
+            "name",
+            "displayName",
+            "description",
+            "config",
+            "status",
+        ]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            tool_instance = tool_manager.tools.get(data["name"])
+            if not tool_instance:
+                return make_response(
+                    jsonify({"success": False, "message": "Tool not found"}), 404
+                )
+            actions_metadata = tool_instance.get_actions_metadata()
+            transformed_actions = []
+            for action in actions_metadata:
+                action["active"] = True
+                if "parameters" in action:
+                    if "properties" in action["parameters"]:
+                        for param_name, param_details in action["parameters"][
+                            "properties"
+                        ].items():
+                            param_details["filled_by_llm"] = True
+                            param_details["value"] = ""
+                transformed_actions.append(action)
+        except Exception as err:
+            current_app.logger.error(
+                f"Error getting tool actions: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        try:
+            new_tool = {
+                "user": user,
+                "name": data["name"],
+                "displayName": data["displayName"],
+                "description": data["description"],
+                "customName": data.get("customName", ""),
+                "actions": transformed_actions,
+                "config": data["config"],
+                "status": data["status"],
+            }
+            resp = user_tools_collection.insert_one(new_tool)
+            new_id = str(resp.inserted_id)
+        except Exception as err:
+            current_app.logger.error(f"Error creating tool: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"id": new_id}), 200)
+
+
+@tools_ns.route("/update_tool")
+class UpdateTool(Resource):
+    @api.expect(
+        api.model(
+            "UpdateToolModel",
+            {
+                "id": fields.String(required=True, description="Tool ID"),
+                "name": fields.String(description="Name of the tool"),
+                "displayName": fields.String(description="Display name for the tool"),
+                "customName": fields.String(description="Custom name for the tool"),
+                "description": fields.String(description="Tool description"),
+                "config": fields.Raw(description="Configuration of the tool"),
+                "actions": fields.List(
+                    fields.Raw, description="Actions the tool can perform"
+                ),
+                "status": fields.Boolean(description="Status of the tool"),
+            },
+        )
+    )
+    @api.doc(description="Update a tool by ID")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            update_data = {}
+            if "name" in data:
+                update_data["name"] = data["name"]
+            if "displayName" in data:
+                update_data["displayName"] = data["displayName"]
+            if "customName" in data:
+                update_data["customName"] = data["customName"]
+            if "description" in data:
+                update_data["description"] = data["description"]
+            if "actions" in data:
+                update_data["actions"] = data["actions"]
+            if "config" in data:
+                if "actions" in data["config"]:
+                    for action_name in list(data["config"]["actions"].keys()):
+                        if not validate_function_name(action_name):
+                            return make_response(
+                                jsonify(
+                                    {
+                                        "success": False,
+                                        "message": f"Invalid function name '{action_name}'. Function names must match pattern '^[a-zA-Z0-9_-]+$'.",
+                                        "param": "tools[].function.name",
+                                    }
+                                ),
+                                400,
+                            )
+                tool_doc = user_tools_collection.find_one(
+                    {"_id": ObjectId(data["id"]), "user": user}
+                )
+                if tool_doc and tool_doc.get("name") == "mcp_tool":
+                    config = data["config"]
+                    existing_config = tool_doc.get("config", {})
+                    storage_config = existing_config.copy()
+
+                    storage_config.update(config)
+                    existing_credentials = {}
+                    if "encrypted_credentials" in existing_config:
+                        existing_credentials = decrypt_credentials(
+                            existing_config["encrypted_credentials"], user
+                        )
+                    auth_credentials = existing_credentials.copy()
+                    auth_type = storage_config.get("auth_type", "none")
+                    if auth_type == "api_key":
+                        if "api_key" in config and config["api_key"]:
+                            auth_credentials["api_key"] = config["api_key"]
+                        if "api_key_header" in config:
+                            auth_credentials["api_key_header"] = config[
+                                "api_key_header"
+                            ]
+                    elif auth_type == "bearer":
+                        if "bearer_token" in config and config["bearer_token"]:
+                            auth_credentials["bearer_token"] = config["bearer_token"]
+                        elif "encrypted_token" in config and config["encrypted_token"]:
+                            auth_credentials["bearer_token"] = config["encrypted_token"]
+                    elif auth_type == "basic":
+                        if "username" in config and config["username"]:
+                            auth_credentials["username"] = config["username"]
+                        if "password" in config and config["password"]:
+                            auth_credentials["password"] = config["password"]
+                    if auth_type != "none" and auth_credentials:
+                        encrypted_credentials_string = encrypt_credentials(
+                            auth_credentials, user
+                        )
+                        storage_config["encrypted_credentials"] = (
+                            encrypted_credentials_string
+                        )
+                    elif auth_type == "none":
+                        storage_config.pop("encrypted_credentials", None)
+                    for field in [
+                        "api_key",
+                        "bearer_token",
+                        "encrypted_token",
+                        "username",
+                        "password",
+                        "api_key_header",
+                    ]:
+                        storage_config.pop(field, None)
+                    update_data["config"] = storage_config
+                else:
+                    update_data["config"] = data["config"]
+            if "status" in data:
+                update_data["status"] = data["status"]
+            user_tools_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": user},
+                {"$set": update_data},
+            )
+        except Exception as err:
+            current_app.logger.error(f"Error updating tool: {err}", exc_info=True)
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@tools_ns.route("/update_tool_config")
+class UpdateToolConfig(Resource):
+    @api.expect(
+        api.model(
+            "UpdateToolConfigModel",
+            {
+                "id": fields.String(required=True, description="Tool ID"),
+                "config": fields.Raw(
+                    required=True, description="Configuration of the tool"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Update the configuration of a tool")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "config"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            user_tools_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": user},
+                {"$set": {"config": data["config"]}},
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error updating tool config: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@tools_ns.route("/update_tool_actions")
+class UpdateToolActions(Resource):
+    @api.expect(
+        api.model(
+            "UpdateToolActionsModel",
+            {
+                "id": fields.String(required=True, description="Tool ID"),
+                "actions": fields.List(
+                    fields.Raw,
+                    required=True,
+                    description="Actions the tool can perform",
+                ),
+            },
+        )
+    )
+    @api.doc(description="Update the actions of a tool")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "actions"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            user_tools_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": user},
+                {"$set": {"actions": data["actions"]}},
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error updating tool actions: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@tools_ns.route("/update_tool_status")
+class UpdateToolStatus(Resource):
+    @api.expect(
+        api.model(
+            "UpdateToolStatusModel",
+            {
+                "id": fields.String(required=True, description="Tool ID"),
+                "status": fields.Boolean(
+                    required=True, description="Status of the tool"
+                ),
+            },
+        )
+    )
+    @api.doc(description="Update the status of a tool")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id", "status"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            user_tools_collection.update_one(
+                {"_id": ObjectId(data["id"]), "user": user},
+                {"$set": {"status": data["status"]}},
+            )
+        except Exception as err:
+            current_app.logger.error(
+                f"Error updating tool status: {err}", exc_info=True
+            )
+            return make_response(jsonify({"success": False}), 400)
+        return make_response(jsonify({"success": True}), 200)
+
+
+@tools_ns.route("/delete_tool")
+class DeleteTool(Resource):
+    @api.expect(
+        api.model(
+            "DeleteToolModel",
+            {"id": fields.String(required=True, description="Tool ID")},
+        )
+    )
+    @api.doc(description="Delete a tool by ID")
+    def post(self):
+        decoded_token = request.decoded_token
+        if not decoded_token:
+            return make_response(jsonify({"success": False}), 401)
+        user = decoded_token.get("sub")
+        data = request.get_json()
+        required_fields = ["id"]
+        missing_fields = check_required_fields(data, required_fields)
+        if missing_fields:
+            return missing_fields
+        try:
+            result = user_tools_collection.delete_one(
+                {"_id": ObjectId(data["id"]), "user": user}
+            )
+            if result.deleted_count == 0:
+                return {"success": False, "message": "Tool not found"}, 404
+        except Exception as err:
+            current_app.logger.error(f"Error deleting tool: {err}", exc_info=True)
+            return {"success": False}, 400
+        return {"success": True}, 200

application/core/model_configs.py

@@ -0,0 +1,223 @@
+"""
+Model configurations for all supported LLM providers.
+"""
+
+from application.core.model_settings import (
+    AvailableModel,
+    ModelCapabilities,
+    ModelProvider,
+)
+
+OPENAI_ATTACHMENTS = [
+    "application/pdf",
+    "image/png",
+    "image/jpeg",
+    "image/jpg",
+    "image/webp",
+    "image/gif",
+]
+
+GOOGLE_ATTACHMENTS = [
+    "application/pdf",
+    "image/png",
+    "image/jpeg",
+    "image/jpg",
+    "image/webp",
+    "image/gif",
+]
+
+
+OPENAI_MODELS = [
+    AvailableModel(
+        id="gpt-4o",
+        provider=ModelProvider.OPENAI,
+        display_name="GPT-4 Omni",
+        description="Latest and most capable model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=OPENAI_ATTACHMENTS,
+            context_window=128000,
+        ),
+    ),
+    AvailableModel(
+        id="gpt-4o-mini",
+        provider=ModelProvider.OPENAI,
+        display_name="GPT-4 Omni Mini",
+        description="Fast and efficient",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=OPENAI_ATTACHMENTS,
+            context_window=128000,
+        ),
+    ),
+    AvailableModel(
+        id="gpt-4-turbo",
+        provider=ModelProvider.OPENAI,
+        display_name="GPT-4 Turbo",
+        description="Fast GPT-4 with 128k context",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=OPENAI_ATTACHMENTS,
+            context_window=128000,
+        ),
+    ),
+    AvailableModel(
+        id="gpt-4",
+        provider=ModelProvider.OPENAI,
+        display_name="GPT-4",
+        description="Most capable model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=OPENAI_ATTACHMENTS,
+            context_window=8192,
+        ),
+    ),
+    AvailableModel(
+        id="gpt-3.5-turbo",
+        provider=ModelProvider.OPENAI,
+        display_name="GPT-3.5 Turbo",
+        description="Fast and cost-effective",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=4096,
+        ),
+    ),
+]
+
+
+ANTHROPIC_MODELS = [
+    AvailableModel(
+        id="claude-3-5-sonnet-20241022",
+        provider=ModelProvider.ANTHROPIC,
+        display_name="Claude 3.5 Sonnet (Latest)",
+        description="Latest Claude 3.5 Sonnet with enhanced capabilities",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=200000,
+        ),
+    ),
+    AvailableModel(
+        id="claude-3-5-sonnet",
+        provider=ModelProvider.ANTHROPIC,
+        display_name="Claude 3.5 Sonnet",
+        description="Balanced performance and capability",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=200000,
+        ),
+    ),
+    AvailableModel(
+        id="claude-3-opus",
+        provider=ModelProvider.ANTHROPIC,
+        display_name="Claude 3 Opus",
+        description="Most capable Claude model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=200000,
+        ),
+    ),
+    AvailableModel(
+        id="claude-3-haiku",
+        provider=ModelProvider.ANTHROPIC,
+        display_name="Claude 3 Haiku",
+        description="Fastest Claude model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=200000,
+        ),
+    ),
+]
+
+
+GOOGLE_MODELS = [
+    AvailableModel(
+        id="gemini-flash-latest",
+        provider=ModelProvider.GOOGLE,
+        display_name="Gemini Flash (Latest)",
+        description="Latest experimental Gemini model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=GOOGLE_ATTACHMENTS,
+            context_window=int(1e6),
+        ),
+    ),
+    AvailableModel(
+        id="gemini-flash-lite-latest",
+        provider=ModelProvider.GOOGLE,
+        display_name="Gemini Flash Lite (Latest)",
+        description="Fast with huge context window",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=GOOGLE_ATTACHMENTS,
+            context_window=int(1e6),
+        ),
+    ),
+    AvailableModel(
+        id="gemini-2.5-pro",
+        provider=ModelProvider.GOOGLE,
+        display_name="Gemini 2.5 Pro",
+        description="Most capable Gemini model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=GOOGLE_ATTACHMENTS,
+            context_window=2000000,
+        ),
+    ),
+]
+
+
+GROQ_MODELS = [
+    AvailableModel(
+        id="llama-3.3-70b-versatile",
+        provider=ModelProvider.GROQ,
+        display_name="Llama 3.3 70B",
+        description="Latest Llama model with high-speed inference",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=128000,
+        ),
+    ),
+    AvailableModel(
+        id="llama-3.1-8b-instant",
+        provider=ModelProvider.GROQ,
+        display_name="Llama 3.1 8B",
+        description="Ultra-fast inference",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=128000,
+        ),
+    ),
+    AvailableModel(
+        id="mixtral-8x7b-32768",
+        provider=ModelProvider.GROQ,
+        display_name="Mixtral 8x7B",
+        description="High-speed inference with tools",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            context_window=32768,
+        ),
+    ),
+]
+
+
+AZURE_OPENAI_MODELS = [
+    AvailableModel(
+        id="azure-gpt-4",
+        provider=ModelProvider.AZURE_OPENAI,
+        display_name="Azure OpenAI GPT-4",
+        description="Azure-hosted GPT model",
+        capabilities=ModelCapabilities(
+            supports_tools=True,
+            supports_structured_output=True,
+            supported_attachment_types=OPENAI_ATTACHMENTS,
+            context_window=8192,
+        ),
+    ),
+]

application/core/model_settings.py

@@ -0,0 +1,236 @@
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ModelProvider(str, Enum):
+    OPENAI = "openai"
+    AZURE_OPENAI = "azure_openai"
+    ANTHROPIC = "anthropic"
+    GROQ = "groq"
+    GOOGLE = "google"
+    HUGGINGFACE = "huggingface"
+    LLAMA_CPP = "llama.cpp"
+    DOCSGPT = "docsgpt"
+    PREMAI = "premai"
+    SAGEMAKER = "sagemaker"
+    NOVITA = "novita"
+
+
+@dataclass
+class ModelCapabilities:
+    supports_tools: bool = False
+    supports_structured_output: bool = False
+    supports_streaming: bool = True
+    supported_attachment_types: List[str] = field(default_factory=list)
+    context_window: int = 128000
+    input_cost_per_token: Optional[float] = None
+    output_cost_per_token: Optional[float] = None
+
+
+@dataclass
+class AvailableModel:
+    id: str
+    provider: ModelProvider
+    display_name: str
+    description: str = ""
+    capabilities: ModelCapabilities = field(default_factory=ModelCapabilities)
+    enabled: bool = True
+    base_url: Optional[str] = None
+
+    def to_dict(self) -> Dict:
+        result = {
+            "id": self.id,
+            "provider": self.provider.value,
+            "display_name": self.display_name,
+            "description": self.description,
+            "supported_attachment_types": self.capabilities.supported_attachment_types,
+            "supports_tools": self.capabilities.supports_tools,
+            "supports_structured_output": self.capabilities.supports_structured_output,
+            "supports_streaming": self.capabilities.supports_streaming,
+            "context_window": self.capabilities.context_window,
+            "enabled": self.enabled,
+        }
+        if self.base_url:
+            result["base_url"] = self.base_url
+        return result
+
+
+class ModelRegistry:
+    _instance = None
+    _initialized = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not ModelRegistry._initialized:
+            self.models: Dict[str, AvailableModel] = {}
+            self.default_model_id: Optional[str] = None
+            self._load_models()
+            ModelRegistry._initialized = True
+
+    @classmethod
+    def get_instance(cls) -> "ModelRegistry":
+        return cls()
+
+    def _load_models(self):
+        from application.core.settings import settings
+
+        self.models.clear()
+
+        self._add_docsgpt_models(settings)
+        if settings.OPENAI_API_KEY or (
+            settings.LLM_PROVIDER == "openai" and settings.API_KEY
+        ):
+            self._add_openai_models(settings)
+        if settings.OPENAI_API_BASE or (
+            settings.LLM_PROVIDER == "azure_openai" and settings.API_KEY
+        ):
+            self._add_azure_openai_models(settings)
+        if settings.ANTHROPIC_API_KEY or (
+            settings.LLM_PROVIDER == "anthropic" and settings.API_KEY
+        ):
+            self._add_anthropic_models(settings)
+        if settings.GOOGLE_API_KEY or (
+            settings.LLM_PROVIDER == "google" and settings.API_KEY
+        ):
+            self._add_google_models(settings)
+        if settings.GROQ_API_KEY or (
+            settings.LLM_PROVIDER == "groq" and settings.API_KEY
+        ):
+            self._add_groq_models(settings)
+        if settings.HUGGINGFACE_API_KEY or (
+            settings.LLM_PROVIDER == "huggingface" and settings.API_KEY
+        ):
+            self._add_huggingface_models(settings)
+        # Default model selection
+
+        if settings.LLM_NAME and settings.LLM_NAME in self.models:
+            self.default_model_id = settings.LLM_NAME
+        elif settings.LLM_PROVIDER and settings.API_KEY:
+            for model_id, model in self.models.items():
+                if model.provider.value == settings.LLM_PROVIDER:
+                    self.default_model_id = model_id
+                    break
+        else:
+            self.default_model_id = next(iter(self.models.keys()))
+        logger.info(
+            f"ModelRegistry loaded {len(self.models)} models, default: {self.default_model_id}"
+        )
+
+    def _add_openai_models(self, settings):
+        from application.core.model_configs import OPENAI_MODELS
+
+        if settings.OPENAI_API_KEY:
+            for model in OPENAI_MODELS:
+                self.models[model.id] = model
+            return
+        if settings.LLM_PROVIDER == "openai" and settings.LLM_NAME:
+            for model in OPENAI_MODELS:
+                if model.id == settings.LLM_NAME:
+                    self.models[model.id] = model
+                    return
+        for model in OPENAI_MODELS:
+            self.models[model.id] = model
+
+    def _add_azure_openai_models(self, settings):
+        from application.core.model_configs import AZURE_OPENAI_MODELS
+
+        if settings.LLM_PROVIDER == "azure_openai" and settings.LLM_NAME:
+            for model in AZURE_OPENAI_MODELS:
+                if model.id == settings.LLM_NAME:
+                    self.models[model.id] = model
+                    return
+        for model in AZURE_OPENAI_MODELS:
+            self.models[model.id] = model
+
+    def _add_anthropic_models(self, settings):
+        from application.core.model_configs import ANTHROPIC_MODELS
+
+        if settings.ANTHROPIC_API_KEY:
+            for model in ANTHROPIC_MODELS:
+                self.models[model.id] = model
+            return
+        if settings.LLM_PROVIDER == "anthropic" and settings.LLM_NAME:
+            for model in ANTHROPIC_MODELS:
+                if model.id == settings.LLM_NAME:
+                    self.models[model.id] = model
+                    return
+        for model in ANTHROPIC_MODELS:
+            self.models[model.id] = model
+
+    def _add_google_models(self, settings):
+        from application.core.model_configs import GOOGLE_MODELS
+
+        if settings.GOOGLE_API_KEY:
+            for model in GOOGLE_MODELS:
+                self.models[model.id] = model
+            return
+        if settings.LLM_PROVIDER == "google" and settings.LLM_NAME:
+            for model in GOOGLE_MODELS:
+                if model.id == settings.LLM_NAME:
+                    self.models[model.id] = model
+                    return
+        for model in GOOGLE_MODELS:
+            self.models[model.id] = model
+
+    def _add_groq_models(self, settings):
+        from application.core.model_configs import GROQ_MODELS
+
+        if settings.GROQ_API_KEY:
+            for model in GROQ_MODELS:
+                self.models[model.id] = model
+            return
+        if settings.LLM_PROVIDER == "groq" and settings.LLM_NAME:
+            for model in GROQ_MODELS:
+                if model.id == settings.LLM_NAME:
+                    self.models[model.id] = model
+                    return
+        for model in GROQ_MODELS:
+            self.models[model.id] = model
+
+    def _add_docsgpt_models(self, settings):
+        model_id = "docsgpt-local"
+        model = AvailableModel(
+            id=model_id,
+            provider=ModelProvider.DOCSGPT,
+            display_name="DocsGPT Model",
+            description="Local model",
+            capabilities=ModelCapabilities(
+                supports_tools=False,
+                supported_attachment_types=[],
+            ),
+        )
+        self.models[model_id] = model
+
+    def _add_huggingface_models(self, settings):
+        model_id = "huggingface-local"
+        model = AvailableModel(
+            id=model_id,
+            provider=ModelProvider.HUGGINGFACE,
+            display_name="Hugging Face Model",
+            description="Local Hugging Face model",
+            capabilities=ModelCapabilities(
+                supports_tools=False,
+                supported_attachment_types=[],
+            ),
+        )
+        self.models[model_id] = model
+
+    def get_model(self, model_id: str) -> Optional[AvailableModel]:
+        return self.models.get(model_id)
+
+    def get_all_models(self) -> List[AvailableModel]:
+        return list(self.models.values())
+
+    def get_enabled_models(self) -> List[AvailableModel]:
+        return [m for m in self.models.values() if m.enabled]
+
+    def model_exists(self, model_id: str) -> bool:
+        return model_id in self.models

application/core/model_utils.py

@@ -0,0 +1,91 @@
+from typing import Any, Dict, Optional
+
+from application.core.model_settings import ModelRegistry
+
+
+def get_api_key_for_provider(provider: str) -> Optional[str]:
+    """Get the appropriate API key for a provider"""
+    from application.core.settings import settings
+
+    provider_key_map = {
+        "openai": settings.OPENAI_API_KEY,
+        "anthropic": settings.ANTHROPIC_API_KEY,
+        "google": settings.GOOGLE_API_KEY,
+        "groq": settings.GROQ_API_KEY,
+        "huggingface": settings.HUGGINGFACE_API_KEY,
+        "azure_openai": settings.API_KEY,
+        "docsgpt": None,
+        "llama.cpp": None,
+    }
+
+    provider_key = provider_key_map.get(provider)
+    if provider_key:
+        return provider_key
+    return settings.API_KEY
+
+
+def get_all_available_models() -> Dict[str, Dict[str, Any]]:
+    """Get all available models with metadata for API response"""
+    registry = ModelRegistry.get_instance()
+    return {model.id: model.to_dict() for model in registry.get_enabled_models()}
+
+
+def validate_model_id(model_id: str) -> bool:
+    """Check if a model ID exists in registry"""
+    registry = ModelRegistry.get_instance()
+    return registry.model_exists(model_id)
+
+
+def get_model_capabilities(model_id: str) -> Optional[Dict[str, Any]]:
+    """Get capabilities for a specific model"""
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id)
+    if model:
+        return {
+            "supported_attachment_types": model.capabilities.supported_attachment_types,
+            "supports_tools": model.capabilities.supports_tools,
+            "supports_structured_output": model.capabilities.supports_structured_output,
+            "context_window": model.capabilities.context_window,
+        }
+    return None
+
+
+def get_default_model_id() -> str:
+    """Get the system default model ID"""
+    registry = ModelRegistry.get_instance()
+    return registry.default_model_id
+
+
+def get_provider_from_model_id(model_id: str) -> Optional[str]:
+    """Get the provider name for a given model_id"""
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id)
+    if model:
+        return model.provider.value
+    return None
+
+
+def get_token_limit(model_id: str) -> int:
+    """
+    Get context window (token limit) for a model.
+    Returns model's context_window or default 128000 if model not found.
+    """
+    from application.core.settings import settings
+
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id)
+    if model:
+        return model.capabilities.context_window
+    return settings.DEFAULT_LLM_TOKEN_LIMIT
+
+
+def get_base_url_for_model(model_id: str) -> Optional[str]:
+    """
+    Get the custom base_url for a specific model if configured.
+    Returns None if no custom base_url is set.
+    """
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id)
+    if model:
+        return model.base_url
+    return None

application/core/settings.py

@@ -22,11 +22,15 @@ class Settings(BaseSettings):
     MONGO_DB_NAME: str = "docsgpt"
     LLM_PATH: str = os.path.join(current_dir, "models/docsgpt-7b-f16.gguf")
     DEFAULT_MAX_HISTORY: int = 150
-    LLM_TOKEN_LIMITS: dict = {
-        "gpt-4o-mini": 128000,
-        "gpt-3.5-turbo": 4096,
-        "claude-2": 1e5,
-        "gemini-2.5-flash": 1e6,
+    DEFAULT_LLM_TOKEN_LIMIT: int = 128000  # Fallback when model not found in registry
+    RESERVED_TOKENS: dict = {
+        "system_prompt": 500,
+        "current_query": 500,
+        "safety_buffer": 1000,
+    }
+    DEFAULT_AGENT_LIMITS: dict = {
+        "token_limit": 50000,
+        "request_limit": 500,
     }
     UPLOAD_FOLDER: str = "inputs"
     PARSE_PDF_AS_IMAGE: bool = False
@@ -41,17 +45,33 @@ class Settings(BaseSettings):
     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)
+    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)
+    )
 
+    # GitHub source
+    GITHUB_ACCESS_TOKEN: Optional[str] = None  # PAT token with read repo access
 
     # LLM Cache
     CACHE_REDIS_URL: str = "redis://localhost:6379/2"
 
     API_URL: str = "http://localhost:7091"  # backend url for celery worker
 
-    API_KEY: Optional[str] = None  # LLM api key
+    API_KEY: Optional[str] = None  # LLM api key (used by LLM_PROVIDER)
+
+    # Provider-specific API keys (for multi-model support)
+    OPENAI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+    GOOGLE_API_KEY: Optional[str] = None
+    GROQ_API_KEY: Optional[str] = None
+    HUGGINGFACE_API_KEY: Optional[str] = None
+
     EMBEDDINGS_KEY: Optional[str] = (
         None  # api key for embeddings (if using openai, just copy API_KEY)
     )
@@ -118,7 +138,12 @@ class Settings(BaseSettings):
     # Encryption settings
     ENCRYPTION_SECRET_KEY: str = "default-docsgpt-encryption-key"
 
+    TTS_PROVIDER: str = "google_tts"  # google_tts or elevenlabs
     ELEVENLABS_API_KEY: Optional[str] = None
 
+    # Tool pre-fetch settings
+    ENABLE_TOOL_PREFETCH: bool = True
+
+
 path = Path(__file__).parent.parent.absolute()
 settings = Settings(_env_file=path.joinpath(".env"), _env_file_encoding="utf-8")

application/llm/anthropic.py

@@ -1,30 +1,41 @@
-from application.llm.base import BaseLLM
+from anthropic import AI_PROMPT, Anthropic, HUMAN_PROMPT
+
 from application.core.settings import settings
+from application.llm.base import BaseLLM
 
 
 class AnthropicLLM(BaseLLM):
 
-    def __init__(self, api_key=None, user_api_key=None, *args, **kwargs):
-        from anthropic import Anthropic, HUMAN_PROMPT, AI_PROMPT
+    def __init__(self, api_key=None, user_api_key=None, base_url=None, *args, **kwargs):
 
         super().__init__(*args, **kwargs)
-        self.api_key = (
-            api_key or settings.ANTHROPIC_API_KEY
-        )  # If not provided, use a default from settings
+        self.api_key = api_key or settings.ANTHROPIC_API_KEY or settings.API_KEY
         self.user_api_key = user_api_key
-        self.anthropic = Anthropic(api_key=self.api_key)
+
+        # Use custom base_url if provided
+        if base_url:
+            self.anthropic = Anthropic(api_key=self.api_key, base_url=base_url)
+        else:
+            self.anthropic = Anthropic(api_key=self.api_key)
+
         self.HUMAN_PROMPT = HUMAN_PROMPT
         self.AI_PROMPT = AI_PROMPT
 
     def _raw_gen(
-        self, baseself, model, messages, stream=False, tools=None, max_tokens=300, **kwargs
+        self,
+        baseself,
+        model,
+        messages,
+        stream=False,
+        tools=None,
+        max_tokens=300,
+        **kwargs,
     ):
         context = messages[0]["content"]
         user_question = messages[-1]["content"]
         prompt = f"### Context \n {context} \n ### Question \n {user_question}"
         if stream:
             return self.gen_stream(model, prompt, stream, max_tokens, **kwargs)
-
         completion = self.anthropic.completions.create(
             model=model,
             max_tokens_to_sample=max_tokens,
@@ -34,7 +45,14 @@ class AnthropicLLM(BaseLLM):
         return completion.completion
 
     def _raw_gen_stream(
-        self, baseself, model, messages, stream=True, tools=None, max_tokens=300, **kwargs
+        self,
+        baseself,
+        model,
+        messages,
+        stream=True,
+        tools=None,
+        max_tokens=300,
+        **kwargs,
     ):
         context = messages[0]["content"]
         user_question = messages[-1]["content"]
@@ -46,5 +64,9 @@ class AnthropicLLM(BaseLLM):
             stream=True,
         )
 
-        for completion in stream_response:
-            yield completion.completion
+        try:
+            for completion in stream_response:
+                yield completion.completion
+        finally:
+            if hasattr(stream_response, "close"):
+                stream_response.close()

application/llm/base.py

@@ -13,30 +13,32 @@ class BaseLLM(ABC):
     def __init__(
         self,
         decoded_token=None,
+        model_id=None,
+        base_url=None,
     ):
         self.decoded_token = decoded_token
+        self.model_id = model_id
+        self.base_url = base_url
         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
+        self._fallback_sequence_index = 0
 
     @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
-        ):
+        """Lazy-loaded fallback LLM from FALLBACK_* settings."""
+        if self._fallback_llm is None and settings.FALLBACK_LLM_PROVIDER:
             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,
+                    settings.FALLBACK_LLM_PROVIDER,
+                    api_key=settings.FALLBACK_LLM_API_KEY or settings.API_KEY,
+                    user_api_key=None,
+                    decoded_token=self.decoded_token,
+                    model_id=settings.FALLBACK_LLM_NAME,
+                )
+                logger.info(
+                    f"Fallback LLM initialized: {settings.FALLBACK_LLM_PROVIDER}/{settings.FALLBACK_LLM_NAME}"
                 )
             except Exception as e:
                 logger.error(
@@ -44,11 +46,17 @@ class BaseLLM(ABC):
                 )
         return self._fallback_llm
 
+    @staticmethod
+    def _remove_null_values(args_dict):
+        if not isinstance(args_dict, dict):
+            return args_dict
+        return {k: v for k, v in args_dict.items() if v is not None}
+
     def _execute_with_fallback(
         self, method_name: str, decorators: list, *args, **kwargs
     ):
         """
-        Unified method execution with fallback support.
+        Execute method with fallback support.
 
         Args:
             method_name: Name of the raw method ('_raw_gen' or '_raw_gen_stream')
@@ -67,10 +75,10 @@ class BaseLLM(ABC):
             return decorated_method()
         except Exception as e:
             if not self.fallback_llm:
-                logger.error(f"Primary LLM failed and no fallback available: {str(e)}")
+                logger.error(f"Primary LLM failed and no fallback configured: {str(e)}")
                 raise
             logger.warning(
-                f"Falling back to {self.fallback_provider}/{self.fallback_model_name}. Error: {str(e)}"
+                f"Primary LLM failed. Falling back to {settings.FALLBACK_LLM_PROVIDER}/{settings.FALLBACK_LLM_NAME}. Error: {str(e)}"
             )
 
             fallback_method = getattr(

application/llm/docsgpt_provider.py

@@ -1,5 +1,7 @@
 import json
 
+from openai import OpenAI
+
 from application.core.settings import settings
 from application.llm.base import BaseLLM
 
@@ -7,12 +9,11 @@ from application.llm.base import BaseLLM
 class DocsGPTAPILLM(BaseLLM):
 
     def __init__(self, api_key=None, user_api_key=None, *args, **kwargs):
-        from openai import OpenAI
 
         super().__init__(*args, **kwargs)
-        self.client = OpenAI(api_key="sk-docsgpt-public", base_url="https://oai.arc53.com")
+        self.api_key = "sk-docsgpt-public"
+        self.client = OpenAI(api_key=self.api_key, base_url="https://oai.arc53.com")
         self.user_api_key = user_api_key
-        self.api_key = api_key
 
     def _clean_messages_openai(self, messages):
         cleaned_messages = []
@@ -22,7 +23,6 @@ class DocsGPTAPILLM(BaseLLM):
 
             if role == "model":
                 role = "assistant"
-
             if role and content is not None:
                 if isinstance(content, str):
                     cleaned_messages.append({"role": role, "content": content})
@@ -33,14 +33,15 @@ class DocsGPTAPILLM(BaseLLM):
                                 {"role": role, "content": item["text"]}
                             )
                         elif "function_call" in item:
+                            cleaned_args = self._remove_null_values(
+                                item["function_call"]["args"]
+                            )
                             tool_call = {
                                 "id": item["function_call"]["call_id"],
                                 "type": "function",
                                 "function": {
                                     "name": item["function_call"]["name"],
-                                    "arguments": json.dumps(
-                                        item["function_call"]["args"]
-                                    ),
+                                    "arguments": json.dumps(cleaned_args),
                                 },
                             }
                             cleaned_messages.append(
@@ -68,7 +69,6 @@ class DocsGPTAPILLM(BaseLLM):
                             )
                 else:
                     raise ValueError(f"Unexpected content type: {type(content)}")
-
         return cleaned_messages
 
     def _raw_gen(
@@ -120,12 +120,19 @@ class DocsGPTAPILLM(BaseLLM):
             response = self.client.chat.completions.create(
                 model="docsgpt", messages=messages, stream=stream, **kwargs
             )
-
-        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:
-                yield line.choices[0].delta.content
-            elif len(line.choices) > 0:
-                yield line.choices[0]
+        try:
+            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
+                ):
+                    yield line.choices[0].delta.content
+                elif len(line.choices) > 0:
+                    yield line.choices[0]
+        finally:
+            if hasattr(response, "close"):
+                response.close()
 
     def _supports_tools(self):
-        return True
+        return True

application/llm/google_ai.py

@@ -13,8 +13,9 @@ from application.storage.storage_creator import StorageCreator
 class GoogleLLM(BaseLLM):
     def __init__(self, api_key=None, user_api_key=None, *args, **kwargs):
         super().__init__(*args, **kwargs)
-        self.api_key = api_key
+        self.api_key = api_key or settings.GOOGLE_API_KEY or settings.API_KEY
         self.user_api_key = user_api_key
+        
         self.client = genai.Client(api_key=self.api_key)
         self.storage = StorageCreator.get_storage()
 
@@ -47,21 +48,19 @@ class GoogleLLM(BaseLLM):
         """
         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"] = [
@@ -69,7 +68,6 @@ class GoogleLLM(BaseLLM):
             ]
         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")
@@ -92,11 +90,9 @@ class GoogleLLM(BaseLLM):
                                 "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):
@@ -111,14 +107,11 @@ class GoogleLLM(BaseLLM):
         """
         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,
@@ -136,7 +129,6 @@ class GoogleLLM(BaseLLM):
                 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)
@@ -153,7 +145,6 @@ class GoogleLLM(BaseLLM):
                 role = "model"
             elif role == "tool":
                 role = "model"
-
             parts = []
             if role and content is not None:
                 if isinstance(content, str):
@@ -163,10 +154,15 @@ class GoogleLLM(BaseLLM):
                         if "text" in item:
                             parts.append(types.Part.from_text(text=item["text"]))
                         elif "function_call" in item:
+                            # Remove null values from args to avoid API errors
+
+                            cleaned_args = self._remove_null_values(
+                                item["function_call"]["args"]
+                            )
                             parts.append(
                                 types.Part.from_function_call(
                                     name=item["function_call"]["name"],
-                                    args=item["function_call"]["args"],
+                                    args=cleaned_args,
                                 )
                             )
                         elif "function_response" in item:
@@ -190,10 +186,8 @@ class GoogleLLM(BaseLLM):
                             )
                 else:
                     raise ValueError(f"Unexpected content type: {type(content)}")
-
                 if parts:
                     cleaned_messages.append(types.Content(role=role, parts=parts))
-
         return cleaned_messages
 
     def _clean_schema(self, schema_obj):
@@ -229,8 +223,8 @@ class GoogleLLM(BaseLLM):
                 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())
@@ -243,7 +237,6 @@ class GoogleLLM(BaseLLM):
                 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):
@@ -259,7 +252,6 @@ class GoogleLLM(BaseLLM):
                     cleaned_properties = {}
                     for k, v in properties.items():
                         cleaned_properties[k] = self._clean_schema(v)
-
                     genai_function = dict(
                         name=function["name"],
                         description=function["description"],
@@ -278,10 +270,8 @@ class GoogleLLM(BaseLLM):
                         name=function["name"],
                         description=function["description"],
                     )
-
                 genai_tool = types.Tool(function_declarations=[genai_function])
                 genai_tools.append(genai_tool)
-
         return genai_tools
 
     def _raw_gen(
@@ -303,16 +293,14 @@ class GoogleLLM(BaseLLM):
         if messages[0].role == "system":
             config.system_instruction = messages[0].parts[0].text
             messages = messages[1:]
-
         if tools:
             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"
-
         response = client.models.generate_content(
             model=model,
             contents=messages,
@@ -343,17 +331,16 @@ class GoogleLLM(BaseLLM):
         if messages[0].role == "system":
             config.system_instruction = messages[0].parts[0].text
             messages = messages[1:]
-
         if tools:
             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:
@@ -362,7 +349,6 @@ class GoogleLLM(BaseLLM):
                     break
             if has_attachments:
                 break
-
         logging.info(
             f"GoogleLLM: Starting stream generation. Model: {model}, Messages: {json.dumps(messages, default=str)}, Has attachments: {has_attachments}"
         )
@@ -373,17 +359,21 @@ class GoogleLLM(BaseLLM):
             config=config,
         )
 
-        for chunk in response:
-            if hasattr(chunk, "candidates") and chunk.candidates:
-                for candidate in chunk.candidates:
-                    if candidate.content and candidate.content.parts:
-                        for part in candidate.content.parts:
-                            if part.function_call:
-                                yield part
-                            elif part.text:
-                                yield part.text
-            elif hasattr(chunk, "text"):
-                yield chunk.text
+        try:
+            for chunk in response:
+                if hasattr(chunk, "candidates") and chunk.candidates:
+                    for candidate in chunk.candidates:
+                        if candidate.content and candidate.content.parts:
+                            for part in candidate.content.parts:
+                                if part.function_call:
+                                    yield part
+                                elif part.text:
+                                    yield part.text
+                elif hasattr(chunk, "text"):
+                    yield chunk.text
+        finally:
+            if hasattr(response, "close"):
+                response.close()
 
     def _supports_tools(self):
         """Return whether this LLM supports function calling."""
@@ -397,7 +387,6 @@ class GoogleLLM(BaseLLM):
         """Convert JSON schema to Google AI structured output format."""
         if not json_schema:
             return None
-
         type_map = {
             "object": "OBJECT",
             "array": "ARRAY",
@@ -410,12 +399,10 @@ class GoogleLLM(BaseLLM):
         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",
@@ -427,7 +414,6 @@ class GoogleLLM(BaseLLM):
             ]:
                 if key in schema:
                     result[key] = schema[key]
-
             if "format" in schema:
                 format_value = schema["format"]
                 if schema_type == "string":
@@ -437,21 +423,17 @@ class GoogleLLM(BaseLLM):
                         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:

application/llm/groq.py

@@ -1,13 +1,18 @@
-from application.llm.base import BaseLLM
 from openai import OpenAI
 
+from application.core.settings import settings
+from application.llm.base import BaseLLM
+
 
 class GroqLLM(BaseLLM):
     def __init__(self, api_key=None, user_api_key=None, *args, **kwargs):
+
         super().__init__(*args, **kwargs)
-        self.client = OpenAI(api_key=api_key, base_url="https://api.groq.com/openai/v1")
-        self.api_key = api_key
+        self.api_key = api_key or settings.GROQ_API_KEY or settings.API_KEY
         self.user_api_key = user_api_key
+        self.client = OpenAI(
+            api_key=self.api_key, base_url="https://api.groq.com/openai/v1"
+        )
 
     def _raw_gen(self, baseself, model, messages, stream=False, tools=None, **kwargs):
         if tools:

application/llm/handlers/base.py

@@ -282,7 +282,7 @@ class LLMHandler(ABC):
                     messages = e.value
                     break
             response = agent.llm.gen(
-                model=agent.gpt_model, messages=messages, tools=agent.tools
+                model=agent.model_id, messages=messages, tools=agent.tools
             )
             parsed = self.parse_response(response)
             self.llm_calls.append(build_stack_data(agent.llm))
@@ -337,7 +337,7 @@ class LLMHandler(ABC):
                 tool_calls = {}
 
                 response = agent.llm.gen_stream(
-                    model=agent.gpt_model, messages=messages, tools=agent.tools
+                    model=agent.model_id, messages=messages, tools=agent.tools
                 )
                 self.llm_calls.append(build_stack_data(agent.llm))
 

application/llm/llm_creator.py

@@ -1,13 +1,17 @@
-from application.llm.groq import GroqLLM
-from application.llm.openai import OpenAILLM, AzureOpenAILLM
-from application.llm.sagemaker import SagemakerAPILLM
-from application.llm.huggingface import HuggingFaceLLM
-from application.llm.llama_cpp import LlamaCpp
+import logging
+
 from application.llm.anthropic import AnthropicLLM
 from application.llm.docsgpt_provider import DocsGPTAPILLM
-from application.llm.premai import PremAILLM
 from application.llm.google_ai import GoogleLLM
+from application.llm.groq import GroqLLM
+from application.llm.huggingface import HuggingFaceLLM
+from application.llm.llama_cpp import LlamaCpp
 from application.llm.novita import NovitaLLM
+from application.llm.openai import AzureOpenAILLM, OpenAILLM
+from application.llm.premai import PremAILLM
+from application.llm.sagemaker import SagemakerAPILLM
+
+logger = logging.getLogger(__name__)
 
 
 class LLMCreator:
@@ -26,10 +30,26 @@ class LLMCreator:
     }
 
     @classmethod
-    def create_llm(cls, type, api_key, user_api_key, decoded_token, *args, **kwargs):
+    def create_llm(
+        cls, type, api_key, user_api_key, decoded_token, model_id=None, *args, **kwargs
+    ):
+        from application.core.model_utils import get_base_url_for_model
+
         llm_class = cls.llms.get(type.lower())
         if not llm_class:
             raise ValueError(f"No LLM class found for type {type}")
+
+        # Extract base_url from model configuration if model_id is provided
+        base_url = None
+        if model_id:
+            base_url = get_base_url_for_model(model_id)
+
         return llm_class(
-            api_key, user_api_key, decoded_token=decoded_token, *args, **kwargs
+            api_key,
+            user_api_key,
+            decoded_token=decoded_token,
+            model_id=model_id,
+            base_url=base_url,
+            *args,
+            **kwargs,
         )

application/llm/openai.py

@@ -2,6 +2,8 @@ import base64
 import json
 import logging
 
+from openai import OpenAI
+
 from application.core.settings import settings
 from application.llm.base import BaseLLM
 from application.storage.storage_creator import StorageCreator
@@ -9,20 +11,25 @@ from application.storage.storage_creator import StorageCreator
 
 class OpenAILLM(BaseLLM):
 
-    def __init__(self, api_key=None, user_api_key=None, *args, **kwargs):
-        from openai import OpenAI
+    def __init__(self, api_key=None, user_api_key=None, base_url=None, *args, **kwargs):
 
         super().__init__(*args, **kwargs)
-        if (
+        self.api_key = api_key or settings.OPENAI_API_KEY or settings.API_KEY
+        self.user_api_key = user_api_key
+
+        # Priority: 1) Parameter base_url, 2) Settings OPENAI_BASE_URL, 3) Default
+        effective_base_url = None
+        if base_url and isinstance(base_url, str) and base_url.strip():
+            effective_base_url = base_url
+        elif (
             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)
+            effective_base_url = settings.OPENAI_BASE_URL
         else:
-            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
+            effective_base_url = "https://api.openai.com/v1"
+
+        self.client = OpenAI(api_key=self.api_key, base_url=effective_base_url)
         self.storage = StorageCreator.get_storage()
 
     def _clean_messages_openai(self, messages):
@@ -33,7 +40,6 @@ class OpenAILLM(BaseLLM):
 
             if role == "model":
                 role = "assistant"
-
             if role and content is not None:
                 if isinstance(content, str):
                     cleaned_messages.append({"role": role, "content": content})
@@ -44,14 +50,15 @@ class OpenAILLM(BaseLLM):
                                 {"role": role, "content": item["text"]}
                             )
                         elif "function_call" in item:
+                            cleaned_args = self._remove_null_values(
+                                item["function_call"]["args"]
+                            )
                             tool_call = {
                                 "id": item["function_call"]["call_id"],
                                 "type": "function",
                                 "function": {
                                     "name": item["function_call"]["name"],
-                                    "arguments": json.dumps(
-                                        item["function_call"]["args"]
-                                    ),
+                                    "arguments": json.dumps(cleaned_args),
                                 },
                             }
                             cleaned_messages.append(
@@ -106,7 +113,6 @@ class OpenAILLM(BaseLLM):
                             )
                 else:
                     raise ValueError(f"Unexpected content type: {type(content)}")
-
         return cleaned_messages
 
     def _raw_gen(
@@ -131,10 +137,8 @@ class OpenAILLM(BaseLLM):
 
         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:
@@ -164,21 +168,23 @@ class OpenAILLM(BaseLLM):
 
         if tools:
             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
-            ):
-                yield line.choices[0].delta.content
-            elif len(line.choices) > 0:
-                yield line.choices[0]
+        try:
+            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
+                ):
+                    yield line.choices[0].delta.content
+                elif len(line.choices) > 0:
+                    yield line.choices[0]
+        finally:
+            if hasattr(response, "close"):
+                response.close()
 
     def _supports_tools(self):
         return True
@@ -189,7 +195,6 @@ class OpenAILLM(BaseLLM):
     def prepare_structured_output_format(self, json_schema):
         if not json_schema:
             return None
-
         try:
 
             def add_additional_properties_false(schema_obj):
@@ -199,11 +204,11 @@ class OpenAILLM(BaseLLM):
                     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] = {
@@ -219,7 +224,6 @@ class OpenAILLM(BaseLLM):
                                 add_additional_properties_false(sub_schema)
                                 for sub_schema in value
                             ]
-
                     return schema_copy
                 return schema_obj
 
@@ -238,7 +242,6 @@ class OpenAILLM(BaseLLM):
             }
 
             return result
-
         except Exception as e:
             logging.error(f"Error preparing structured output format: {e}")
             return None
@@ -272,21 +275,19 @@ class OpenAILLM(BaseLLM):
         """
         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"] = [
@@ -294,7 +295,6 @@ class OpenAILLM(BaseLLM):
             ]
         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")
 
@@ -321,6 +321,7 @@ class OpenAILLM(BaseLLM):
                             }
                         )
             # Handle PDFs using the file API
+
             elif mime_type == "application/pdf":
                 try:
                     file_id = self._upload_file_to_openai(attachment)
@@ -336,7 +337,6 @@ class OpenAILLM(BaseLLM):
                                 "text": f"File content:\n\n{attachment['content']}",
                             }
                         )
-
         return prepared_messages
 
     def _get_base64_image(self, attachment):
@@ -352,7 +352,6 @@ class OpenAILLM(BaseLLM):
         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")
@@ -376,12 +375,10 @@ class OpenAILLM(BaseLLM):
 
         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,
@@ -399,7 +396,6 @@ class OpenAILLM(BaseLLM):
                 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)

application/parser/embedding_pipeline.py

@@ -1,5 +1,6 @@
 import os
 import logging
+from typing import List, Any
 from retry import retry
 from tqdm import tqdm
 from application.core.settings import settings
@@ -22,13 +23,16 @@ def sanitize_content(content: str) -> str:
 
 
 @retry(tries=10, delay=60)
-def add_text_to_store_with_retry(store, doc, source_id):
-    """
-    Add a document's text and metadata to the vector store with retry logic.
+def add_text_to_store_with_retry(store: Any, doc: Any, source_id: str) -> None:
+    """Add a document's text and metadata to the vector store with retry logic.
+    
     Args:
         store: The vector store object.
         doc: The document to be added.
         source_id: Unique identifier for the source.
+        
+    Raises:
+        Exception: If document addition fails after all retry attempts.
     """
     try:
         # Sanitize content to remove NUL characters that cause ingestion failures
@@ -41,18 +45,21 @@ def add_text_to_store_with_retry(store, doc, source_id):
         raise
 
 
-def embed_and_store_documents(docs, folder_name, source_id, task_status):
-    """
-    Embeds documents and stores them in a vector store.
+def embed_and_store_documents(docs: List[Any], folder_name: str, source_id: str, task_status: Any) -> None:
+    """Embeds documents and stores them in a vector store.
 
     Args:
-        docs (list): List of documents to be embedded and stored.
-        folder_name (str): Directory to save the vector store.
-        source_id (str): Unique identifier for the source.
+        docs: List of documents to be embedded and stored.
+        folder_name: Directory to save the vector store.
+        source_id: Unique identifier for the source.
         task_status: Task state manager for progress updates.
 
     Returns:
         None
+        
+    Raises:
+        OSError: If unable to create folder or save vector store.
+        Exception: If vector store creation or document embedding fails.
     """
     # Ensure the folder exists
     if not os.path.exists(folder_name):
@@ -95,10 +102,21 @@ def embed_and_store_documents(docs, folder_name, source_id, task_status):
         except Exception as 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)
+            try:
+                store.save_local(folder_name)
+                logging.info("Progress saved successfully")
+            except Exception as save_error:
+                logging.error(f"CRITICAL: Failed to save progress: {save_error}", exc_info=True)
+                # Continue without breaking to attempt final save
             break
 
     # Save the vector store
     if settings.VECTOR_STORE == "faiss":
-        store.save_local(folder_name)
-    logging.info("Vector store saved successfully.")
+        try:
+            store.save_local(folder_name)
+            logging.info("Vector store saved successfully.")
+        except Exception as e:
+            logging.error(f"CRITICAL: Failed to save final vector store: {e}", exc_info=True)
+            raise OSError(f"Unable to save vector store to {folder_name}: {e}") from e
+    else:
+        logging.info("Vector store saved successfully.")

application/parser/remote/github_loader.py

@@ -1,44 +1,135 @@
 import base64
 import requests
-from typing import List
+import time
+from typing import List, Optional
 from application.parser.remote.base import BaseRemote
-from langchain_core.documents import Document
+from application.parser.schema.base import Document
 import mimetypes
+from application.core.settings import settings
 
 class GitHubLoader(BaseRemote):
     def __init__(self):
-        self.access_token = None
+        self.access_token = settings.GITHUB_ACCESS_TOKEN
         self.headers = {
-            "Authorization": f"token {self.access_token}"
-        } if self.access_token else {}
+            "Authorization": f"token {self.access_token}",
+            "Accept": "application/vnd.github.v3+json"
+        } if self.access_token else {
+            "Accept": "application/vnd.github.v3+json"
+        }
         return
 
-    def fetch_file_content(self, repo_url: str, file_path: str) -> str:
+    def is_text_file(self, file_path: str) -> bool:
+        """Determine if a file is a text file based on extension."""
+        # Common text file extensions
+        text_extensions = {
+            '.txt', '.md', '.markdown', '.rst', '.json', '.xml', '.yaml', '.yml',
+            '.py', '.js', '.ts', '.jsx', '.tsx', '.java', '.c', '.cpp', '.h', '.hpp',
+            '.cs', '.go', '.rs', '.rb', '.php', '.swift', '.kt', '.scala',
+            '.html', '.css', '.scss', '.sass', '.less',
+            '.sh', '.bash', '.zsh', '.fish',
+            '.sql', '.r', '.m', '.mat',
+            '.ini', '.cfg', '.conf', '.config', '.env',
+            '.gitignore', '.dockerignore', '.editorconfig',
+            '.log', '.csv', '.tsv'
+        }
+
+        # Get file extension
+        file_lower = file_path.lower()
+        for ext in text_extensions:
+            if file_lower.endswith(ext):
+                return True
+
+        # Also check MIME type
+        mime_type, _ = mimetypes.guess_type(file_path)
+        if mime_type and (mime_type.startswith("text") or mime_type in ["application/json", "application/xml"]):
+            return True
+
+        return False
+
+    def fetch_file_content(self, repo_url: str, file_path: str) -> Optional[str]:
+        """Fetch file content. Returns None if file should be skipped (binary files or empty files)."""
         url = f"https://api.github.com/repos/{repo_url}/contents/{file_path}"
-        response = requests.get(url, headers=self.headers)
+        response = self._make_request(url)
 
-        if response.status_code == 200:
-            content = response.json()
-            mime_type, _ = mimetypes.guess_type(file_path)  # Guess the MIME type based on the file extension
+        content = response.json()
 
-            if content.get("encoding") == "base64":
-                if mime_type and mime_type.startswith("text"):  # Handle only text files
-                    try:
-                        decoded_content = base64.b64decode(content["content"]).decode("utf-8")
-                        return f"Filename: {file_path}\n\n{decoded_content}"
-                    except Exception as e:
-                        raise e
-                else:
-                    return f"Filename: {file_path} is a binary file and was skipped."
+        if content.get("encoding") == "base64":
+            if self.is_text_file(file_path):  # Handle only text files
+                try:
+                    decoded_content = base64.b64decode(content["content"]).decode("utf-8").strip()
+                    # Skip empty files
+                    if not decoded_content:
+                        return None
+                    return decoded_content
+                except Exception:
+                    # If decoding fails, it's probably a binary file
+                    return None
             else:
-                return f"Filename: {file_path}\n\n{content['content']}"
+                # Skip binary files by returning None
+                return None
         else:
-            response.raise_for_status()
+            file_content = content['content'].strip()
+            # Skip empty files
+            if not file_content:
+                return None
+            return file_content
+
+    def _make_request(self, url: str, max_retries: int = 3) -> requests.Response:
+        """Make a request with retry logic for rate limiting"""
+        for attempt in range(max_retries):
+            response = requests.get(url, headers=self.headers)
+
+            if response.status_code == 200:
+                return response
+            elif response.status_code == 403:
+                # Check if it's a rate limit issue
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get("message", "")
+
+                    # Check rate limit headers
+                    remaining = response.headers.get("X-RateLimit-Remaining", "unknown")
+                    reset_time = response.headers.get("X-RateLimit-Reset", "unknown")
+
+                    print(f"GitHub API 403 Error: {error_msg}")
+                    print(f"Rate limit remaining: {remaining}, Reset time: {reset_time}")
+
+                    if "rate limit" in error_msg.lower():
+                        if attempt < max_retries - 1:
+                            wait_time = 2 ** attempt  # Exponential backoff
+                            print(f"Rate limit hit, waiting {wait_time} seconds before retry...")
+                            time.sleep(wait_time)
+                            continue
+
+                    # Provide helpful error message
+                    if remaining == "0":
+                        raise Exception(f"GitHub API rate limit exceeded. Please set GITHUB_ACCESS_TOKEN environment variable. Reset time: {reset_time}")
+                    else:
+                        raise Exception(f"GitHub API error: {error_msg}. This may require authentication - set GITHUB_ACCESS_TOKEN environment variable.")
+                except Exception as e:
+                    if isinstance(e, Exception) and "GitHub API" in str(e):
+                        raise
+                    # If we can't parse the response, raise the original error
+                    response.raise_for_status()
+            else:
+                response.raise_for_status()
+
+        return response
 
     def fetch_repo_files(self, repo_url: str, path: str = "") -> List[str]:
         url = f"https://api.github.com/repos/{repo_url}/contents/{path}"
-        response = requests.get(url, headers={**self.headers, "Accept": "application/vnd.github.v3.raw"})
+        response = self._make_request(url)
+
         contents = response.json()
+
+        # Handle error responses from GitHub API
+        if isinstance(contents, dict) and "message" in contents:
+            raise Exception(f"GitHub API error: {contents.get('message')}")
+
+        # Ensure contents is a list
+        if not isinstance(contents, list):
+            raise TypeError(f"Expected list from GitHub API, got {type(contents).__name__}: {contents}")
+
         files = []
         for item in contents:
             if item["type"] == "file":
@@ -53,6 +144,15 @@ class GitHubLoader(BaseRemote):
         documents = []
         for file_path in files:
             content = self.fetch_file_content(repo_name, file_path)
-            documents.append(Document(page_content=content, metadata={"title": file_path, 
-            "source": f"https://github.com/{repo_name}/blob/main/{file_path}"}))
+            # Skip binary files (content is None)
+            if content is None:
+                continue
+            documents.append(Document(
+                text=content,
+                doc_id=file_path,
+                extra_info={
+                    "title": file_path,
+                    "source": f"https://github.com/{repo_name}/blob/main/{file_path}"
+                }
+            ))
         return documents

application/requirements.txt

@@ -10,6 +10,7 @@ ebooklib==0.18
 escodegen==1.0.11
 esprima==4.0.1
 esutils==1.0.1
+elevenlabs==2.17.0
 Flask==3.1.1
 faiss-cpu==1.9.0.post1
 fastmcp==2.11.0

application/retriever/base.py

@@ -8,7 +8,3 @@ class BaseRetriever(ABC):
     @abstractmethod
     def search(self, *args, **kwargs):
         pass
-
-    @abstractmethod
-    def get_params(self):
-        pass

application/retriever/classic_rag.py

@@ -4,7 +4,7 @@ import os
 from application.core.settings import settings
 from application.llm.llm_creator import LLMCreator
 from application.retriever.base import BaseRetriever
-
+from application.utils import num_tokens_from_string
 from application.vectorstore.vector_creator import VectorCreator
 
 
@@ -15,14 +15,13 @@ class ClassicRAG(BaseRetriever):
         chat_history=None,
         prompt="",
         chunks=2,
-        token_limit=150,
-        gpt_model="docsgpt",
+        doc_token_limit=50000,
+        model_id="docsgpt-local",
         user_api_key=None,
         llm_name=settings.LLM_PROVIDER,
         api_key=settings.API_KEY,
         decoded_token=None,
     ):
-        """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
@@ -41,17 +40,8 @@ class ClassicRAG(BaseRetriever):
             f"ClassicRAG initialized with chunks={self.chunks}, user_api_key={user_identifier}, "
             f"sources={'active_docs' in source and source['active_docs'] is not None}"
         )
-        self.gpt_model = gpt_model
-        self.token_limit = (
-            token_limit
-            if token_limit
-            < settings.LLM_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-            else settings.LLM_TOKEN_LIMITS.get(
-                self.gpt_model, settings.DEFAULT_MAX_HISTORY
-            )
-        )
+        self.model_id = model_id
+        self.doc_token_limit = doc_token_limit
         self.user_api_key = user_api_key
         self.llm_name = llm_name
         self.api_key = api_key
@@ -110,7 +100,7 @@ class ClassicRAG(BaseRetriever):
         ]
 
         try:
-            rephrased_query = self.llm.gen(model=self.gpt_model, messages=messages)
+            rephrased_query = self.llm.gen(model=self.model_id, messages=messages)
             print(f"Rephrased query: {rephrased_query}")
             return rephrased_query if rephrased_query else self.original_question
         except Exception as e:
@@ -118,21 +108,17 @@ class ClassicRAG(BaseRetriever):
             return self.original_question
 
     def _get_data(self):
-        """Retrieve relevant documents from configured vectorstores"""
         if self.chunks == 0 or not self.vectorstores:
             logging.info(
                 f"ClassicRAG._get_data: Skipping retrieval - chunks={self.chunks}, "
                 f"vectorstores_count={len(self.vectorstores) if self.vectorstores else 0}"
             )
             return []
+
         all_docs = []
         chunks_per_source = max(1, self.chunks // len(self.vectorstores))
-
-        logging.info(
-            f"ClassicRAG._get_data: Starting retrieval with chunks={self.chunks}, "
-            f"vectorstores={self.vectorstores}, chunks_per_source={chunks_per_source}, "
-            f"query='{self.question[:50]}...'"
-        )
+        token_budget = max(int(self.doc_token_limit * 0.9), 100)
+        cumulative_tokens = 0
 
         for vectorstore_id in self.vectorstores:
             if vectorstore_id:
@@ -140,15 +126,21 @@ class ClassicRAG(BaseRetriever):
                     docsearch = VectorCreator.create_vectorstore(
                         settings.VECTOR_STORE, vectorstore_id, settings.EMBEDDINGS_KEY
                     )
-                    docs_temp = docsearch.search(self.question, k=chunks_per_source)
+                    docs_temp = docsearch.search(
+                        self.question, k=max(chunks_per_source * 2, 20)
+                    )
 
                     for doc in docs_temp:
+                        if cumulative_tokens >= token_budget:
+                            break
+
                         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)
                         )
@@ -168,23 +160,35 @@ class ClassicRAG(BaseRetriever):
                         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,
-                            }
-                        )
+
+                        doc_text_with_header = f"{filename}\n{page_content}"
+                        doc_tokens = num_tokens_from_string(doc_text_with_header)
+
+                        if cumulative_tokens + doc_tokens < token_budget:
+                            all_docs.append(
+                                {
+                                    "title": title,
+                                    "text": page_content,
+                                    "source": source_path,
+                                    "filename": filename,
+                                }
+                            )
+                            cumulative_tokens += doc_tokens
+
+                    if cumulative_tokens >= token_budget:
+                        break
+
                 except Exception as e:
                     logging.error(
                         f"Error searching vectorstore {vectorstore_id}: {e}",
                         exc_info=True,
                     )
                     continue
+
         logging.info(
             f"ClassicRAG._get_data: Retrieval complete - retrieved {len(all_docs)} documents "
-            f"(requested chunks={self.chunks}, chunks_per_source={chunks_per_source})"
+            f"(requested chunks={self.chunks}, chunks_per_source={chunks_per_source}, "
+            f"cumulative_tokens={cumulative_tokens}/{token_budget})"
         )
         return all_docs
 
@@ -194,15 +198,3 @@ class ClassicRAG(BaseRetriever):
             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,
-            "sources": self.vectorstores,
-            "chunks": self.chunks,
-            "token_limit": self.token_limit,
-            "gpt_model": self.gpt_model,
-            "user_api_key": self.user_api_key,
-        }

application/seed/commands.py

@@ -0,0 +1,26 @@
+import click
+
+from application.core.mongo_db import MongoDB
+from application.core.settings import settings
+from application.seed.seeder import DatabaseSeeder
+
+
+@click.group()
+def seed():
+    """Database seeding commands"""
+    pass
+
+
+@seed.command()
+@click.option("--force", is_flag=True, help="Force reseeding even if data exists")
+def init(force):
+    """Initialize database with seed data"""
+    mongo = MongoDB.get_client()
+    db = mongo[settings.MONGO_DB_NAME]
+
+    seeder = DatabaseSeeder(db)
+    seeder.seed_initial_data(force=force)
+
+
+if __name__ == "__main__":
+    seed()

application/seed/config/agents_template.yaml

@@ -0,0 +1,36 @@
+# Configuration for Premade Agents
+# This file contains template agents that will be seeded into the database
+
+agents:
+  # Basic Agent Template
+  - name: "Agent Name" # Required: Unique name for the agent
+    description: "What this agent does" # Required: Brief description of the agent's purpose
+    image: "URL_TO_IMAGE" # Optional: URL to agent's avatar/image
+    agent_type: "classic" # Required: Type of agent (e.g., classic, react, etc.)
+    prompt_id: "default" # Optional: Reference to prompt template
+    prompt: # Optional: Define new prompt
+      name: "New Prompt"
+      content: "You are new agent with cool new prompt."
+    chunks: "0" # Optional: Chunking strategy for documents
+    retriever: "" # Optional: Retriever type for document search
+
+    # Source Configuration (where the agent gets its knowledge)
+    source: # Optional: Select a source to link with agent
+      name: "Source Display Name" # Human-readable name for the source
+      url: "https://example.com/data-source" # URL or path to knowledge source
+      loader: "url" # Type of loader (url, pdf, txt, etc.)
+
+    # Tools Configuration (what capabilities the agent has)
+    tools: # Optional: Remove if agent doesn't need tools
+      - name: "tool_name" # Must match a supported tool name
+        display_name: "Tool Display Name" # Optional: Human-readable name for the tool
+        config:
+        # Tool-specific configuration
+        # Example for DuckDuckGo:
+        # token: "${DDG_API_KEY}"          # ${} denotes environment variable
+
+      # Add more tools as needed
+      # - name: "another_tool"
+      #   config:
+      #     param1: "value1"
+      #     param2: "${ENV_VAR}"

application/seed/config/premade_agents.yaml

@@ -0,0 +1,94 @@
+# Configuration for Premade Agents
+
+agents:
+  - name: "Assistant"
+    description: "Your general-purpose AI assistant. Ready to help with a wide range of tasks."
+    image: "https://d3dg1063dc54p9.cloudfront.net/imgs/agents/agent-logo.svg"
+    agent_type: "classic"
+    prompt_id: "default"
+    chunks: "0"
+    retriever: ""
+
+    # Tools Configuration
+    tools:
+      - name: "tool_name"
+        display_name: "read_webpage" 
+        config:
+
+  - name: "Researcher"
+    description: "A specialized research agent that performs deep dives into subjects."
+    image: "https://d3dg1063dc54p9.cloudfront.net/imgs/agents/agent-researcher.svg"
+    agent_type: "react"
+    prompt:
+      name: "Researcher-Agent"
+      content: |
+        You are a specialized AI research assistant, DocsGPT. Your primary function is to conduct in-depth research on a given subject or question. You are methodical, thorough, and analytical. You should perform multiple iterations of thinking to gather and synthesize information before providing a final, comprehensive answer.
+
+        You have access to the 'Read Webpage' tool. Use this tool to explore sources, gather data, and deepen your understanding. Be proactive in using the tool to fill in knowledge gaps and validate 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.
+        ----------------
+        Possible additional context from uploaded sources:
+        {summaries}
+
+    chunks: "0"
+    retriever: ""
+
+    # Tools Configuration
+    tools:
+      - name: "tool_name"
+        display_name: "read_webpage" 
+        config:
+
+  - name: "Search Widget"
+    description: "A powerful search widget agent. Ask it anything about DocsGPT"
+    image: "https://d3dg1063dc54p9.cloudfront.net/imgs/agents/agent-search.svg"
+    agent_type: "classic"
+    prompt:
+      name: "Search-Agent"
+      content: |
+        You are a website search assistant, DocsGPT. Your sole purpose is to help users find information within the provided context of the DocsGPT documentation. Act as a specialized search engine.
+
+        Your answers must be based *only* on the provided context. Do not use any external knowledge. If the answer is not in the context, inform the user that you could not find the information within the documentation.
+
+        Keep your responses concise and directly related to the user's query, pointing them to the most relevant information.
+        ----------------
+        Possible additional context from uploaded sources:
+        {summaries}
+
+    chunks: "8"
+    retriever: ""
+
+    source:
+      name: "DocsGPT-Docs"
+      url: "https://d3dg1063dc54p9.cloudfront.net/agent-source/docsgpt-documentation.md" # URL to DocsGPT documentation
+      loader: "url" 
+
+  - name: "Support Widget"
+    description: "A friendly support widget agent to help you with any questions."
+    image: "https://d3dg1063dc54p9.cloudfront.net/imgs/agents/agent-support.svg"
+    agent_type: "classic"
+    prompt:
+      name: "Support-Agent"
+      content: |
+        You are a helpful AI support widget agent, DocsGPT. Your goal is to assist users by answering their questions about our website, product and its features. Provide friendly, clear, and direct support.
+
+        Your knowledge is strictly limited to the provided context from the DocsGPT documentation. You must not answer questions outside of this scope. If a user asks something you cannot answer from the context, politely state that you can only help with questions about this website.
+
+        Effectively utilize chat history to understand the user's issue fully. Guide users to the information they need in a helpful and conversational manner.
+        ----------------
+        Possible additional context from uploaded sources:
+        {summaries}
+
+    chunks: "8"
+    retriever: ""
+
+    source:
+      name: "DocsGPT-Docs"
+      url: "https://d3dg1063dc54p9.cloudfront.net/agent-source/docsgpt-documentation.md" # URL to DocsGPT documentation
+      loader: "url" 

application/seed/seeder.py

@@ -0,0 +1,277 @@
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Union
+
+import yaml
+from bson import ObjectId
+from bson.dbref import DBRef
+
+from dotenv import load_dotenv
+from pymongo import MongoClient
+
+from application.agents.tools.tool_manager import ToolManager
+from application.api.user.tasks import ingest_remote
+
+load_dotenv()
+tool_config = {}
+tool_manager = ToolManager(config=tool_config)
+
+
+class DatabaseSeeder:
+    def __init__(self, db):
+        self.db = db
+        self.tools_collection = self.db["user_tools"]
+        self.sources_collection = self.db["sources"]
+        self.agents_collection = self.db["agents"]
+        self.prompts_collection = self.db["prompts"]
+        self.system_user_id = "system"
+        self.logger = logging.getLogger(__name__)
+
+    def seed_initial_data(self, config_path: str = None, force=False):
+        """Main entry point for seeding all initial data"""
+        if not force and self._is_already_seeded():
+            self.logger.info("Database already seeded. Use force=True to reseed.")
+            return
+        config_path = config_path or os.path.join(
+            os.path.dirname(__file__), "config", "premade_agents.yaml"
+        )
+
+        try:
+            with open(config_path, "r") as f:
+                config = yaml.safe_load(f)
+                self._seed_from_config(config)
+        except Exception as e:
+            self.logger.error(f"Failed to load seeding config: {str(e)}")
+            raise
+
+    def _seed_from_config(self, config: Dict):
+        """Seed all data from configuration"""
+        self.logger.info("🌱 Starting seeding...")
+
+        if not config.get("agents"):
+            self.logger.warning("No agents found in config")
+            return
+        used_tool_ids = set()
+
+        for agent_config in config["agents"]:
+            try:
+                self.logger.info(f"Processing agent: {agent_config['name']}")
+
+                # 1. Handle Source
+
+                source_result = self._handle_source(agent_config)
+                if source_result is False:
+                    self.logger.error(
+                        f"Skipping agent {agent_config['name']} due to source ingestion failure"
+                    )
+                    continue
+                source_id = source_result
+                # 2. Handle Tools
+
+                tool_ids = self._handle_tools(agent_config)
+                if len(tool_ids) == 0:
+                    self.logger.warning(
+                        f"No valid tools for agent {agent_config['name']}"
+                    )
+                used_tool_ids.update(tool_ids)
+
+                # 3. Handle Prompt
+
+                prompt_id = self._handle_prompt(agent_config)
+
+                # 4. Create Agent
+
+                agent_data = {
+                    "user": self.system_user_id,
+                    "name": agent_config["name"],
+                    "description": agent_config["description"],
+                    "image": agent_config.get("image", ""),
+                    "source": (
+                        DBRef("sources", ObjectId(source_id)) if source_id else ""
+                    ),
+                    "tools": [str(tid) for tid in tool_ids],
+                    "agent_type": agent_config["agent_type"],
+                    "prompt_id": prompt_id or agent_config.get("prompt_id", "default"),
+                    "chunks": agent_config.get("chunks", "0"),
+                    "retriever": agent_config.get("retriever", ""),
+                    "status": "template",
+                    "createdAt": datetime.now(timezone.utc),
+                    "updatedAt": datetime.now(timezone.utc),
+                }
+
+                existing = self.agents_collection.find_one(
+                    {"user": self.system_user_id, "name": agent_config["name"]}
+                )
+                if existing:
+                    self.logger.info(f"Updating existing agent: {agent_config['name']}")
+                    self.agents_collection.update_one(
+                        {"_id": existing["_id"]}, {"$set": agent_data}
+                    )
+                    agent_id = existing["_id"]
+                else:
+                    self.logger.info(f"Creating new agent: {agent_config['name']}")
+                    result = self.agents_collection.insert_one(agent_data)
+                    agent_id = result.inserted_id
+                self.logger.info(
+                    f"Successfully processed agent: {agent_config['name']} (ID: {agent_id})"
+                )
+            except Exception as e:
+                self.logger.error(
+                    f"Error processing agent {agent_config['name']}: {str(e)}"
+                )
+                continue
+        self.logger.info("✅ Database seeding completed")
+
+    def _handle_source(self, agent_config: Dict) -> Union[ObjectId, None, bool]:
+        """Handle source ingestion and return source ID"""
+        if not agent_config.get("source"):
+            self.logger.info(
+                "No source provided for agent - will create agent without source"
+            )
+            return None
+        source_config = agent_config["source"]
+        self.logger.info(f"Ingesting source: {source_config['url']}")
+
+        try:
+            existing = self.sources_collection.find_one(
+                {"user": self.system_user_id, "remote_data": source_config["url"]}
+            )
+            if existing:
+                self.logger.info(f"Source already exists: {existing['_id']}")
+                return existing["_id"]
+            # Ingest new source using worker
+
+            task = ingest_remote.delay(
+                source_data=source_config["url"],
+                job_name=source_config["name"],
+                user=self.system_user_id,
+                loader=source_config.get("loader", "url"),
+            )
+
+            result = task.get(timeout=300)
+
+            if not task.successful():
+                raise Exception(f"Source ingestion failed: {result}")
+            source_id = None
+            if isinstance(result, dict) and "id" in result:
+                source_id = result["id"]
+            else:
+                raise Exception(f"Source ingestion result missing 'id': {result}")
+            self.logger.info(f"Source ingested successfully: {source_id}")
+            return source_id
+        except Exception as e:
+            self.logger.error(f"Failed to ingest source: {str(e)}")
+            return False
+
+    def _handle_tools(self, agent_config: Dict) -> List[ObjectId]:
+        """Handle tool creation and return list of tool IDs"""
+        tool_ids = []
+        if not agent_config.get("tools"):
+            return tool_ids
+        for tool_config in agent_config["tools"]:
+            try:
+                tool_name = tool_config["name"]
+                processed_config = self._process_config(tool_config.get("config", {}))
+                self.logger.info(f"Processing tool: {tool_name}")
+
+                existing = self.tools_collection.find_one(
+                    {
+                        "user": self.system_user_id,
+                        "name": tool_name,
+                        "config": processed_config,
+                    }
+                )
+                if existing:
+                    self.logger.info(f"Tool already exists: {existing['_id']}")
+                    tool_ids.append(existing["_id"])
+                    continue
+                tool_data = {
+                    "user": self.system_user_id,
+                    "name": tool_name,
+                    "displayName": tool_config.get("display_name", tool_name),
+                    "description": tool_config.get("description", ""),
+                    "actions": tool_manager.tools[tool_name].get_actions_metadata(),
+                    "config": processed_config,
+                    "status": True,
+                }
+
+                result = self.tools_collection.insert_one(tool_data)
+                tool_ids.append(result.inserted_id)
+                self.logger.info(f"Created new tool: {result.inserted_id}")
+            except Exception as e:
+                self.logger.error(f"Failed to process tool {tool_name}: {str(e)}")
+                continue
+        return tool_ids
+
+    def _handle_prompt(self, agent_config: Dict) -> Optional[str]:
+        """Handle prompt creation and return prompt ID"""
+        if not agent_config.get("prompt"):
+            return None
+
+        prompt_config = agent_config["prompt"]
+        prompt_name = prompt_config.get("name", f"{agent_config['name']} Prompt")
+        prompt_content = prompt_config.get("content", "")
+
+        if not prompt_content:
+            self.logger.warning(
+                f"No prompt content provided for agent {agent_config['name']}"
+            )
+            return None
+
+        self.logger.info(f"Processing prompt: {prompt_name}")
+
+        try:
+            existing = self.prompts_collection.find_one(
+                {
+                    "user": self.system_user_id,
+                    "name": prompt_name,
+                    "content": prompt_content,
+                }
+            )
+            if existing:
+                self.logger.info(f"Prompt already exists: {existing['_id']}")
+                return str(existing["_id"])
+
+            prompt_data = {
+                "name": prompt_name,
+                "content": prompt_content,
+                "user": self.system_user_id,
+            }
+
+            result = self.prompts_collection.insert_one(prompt_data)
+            prompt_id = str(result.inserted_id)
+            self.logger.info(f"Created new prompt: {prompt_id}")
+            return prompt_id
+
+        except Exception as e:
+            self.logger.error(f"Failed to process prompt {prompt_name}: {str(e)}")
+            return None
+
+    def _process_config(self, config: Dict) -> Dict:
+        """Process config values to replace environment variables"""
+        processed = {}
+        for key, value in config.items():
+            if (
+                isinstance(value, str)
+                and value.startswith("${")
+                and value.endswith("}")
+            ):
+                env_var = value[2:-1]
+                processed[key] = os.getenv(env_var, "")
+            else:
+                processed[key] = value
+        return processed
+
+    def _is_already_seeded(self) -> bool:
+        """Check if premade agents already exist"""
+        return self.agents_collection.count_documents({"user": self.system_user_id}) > 0
+
+    @classmethod
+    def initialize_from_env(cls, worker=None):
+        """Factory method to create seeder from environment"""
+        mongo_uri = os.getenv("MONGO_URI", "mongodb://localhost:27017")
+        db_name = os.getenv("MONGO_DB_NAME", "docsgpt")
+        client = MongoClient(mongo_uri)
+        db = client[db_name]
+        return cls(db)

application/storage/local.py

@@ -26,7 +26,7 @@ class LocalStorage(BaseStorage):
             return path
         return os.path.join(self.base_dir, path)
 
-    def save_file(self, file_data: BinaryIO, path: str) -> dict:
+    def save_file(self, file_data: BinaryIO, path: str, **kwargs) -> dict:
         """Save a file to local storage."""
         full_path = self._get_full_path(path)
 

application/templates/namespaces.py

@@ -0,0 +1,190 @@
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class NamespaceBuilder(ABC):
+    """Base class for building template context namespaces"""
+
+    @abstractmethod
+    def build(self, **kwargs) -> Dict[str, Any]:
+        """Build namespace context dictionary"""
+        pass
+
+    @property
+    @abstractmethod
+    def namespace_name(self) -> str:
+        """Name of this namespace for template access"""
+        pass
+
+
+class SystemNamespace(NamespaceBuilder):
+    """System metadata namespace: {{ system.* }}"""
+
+    @property
+    def namespace_name(self) -> str:
+        return "system"
+
+    def build(
+        self, request_id: Optional[str] = None, user_id: Optional[str] = None, **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Build system context with metadata.
+
+        Args:
+            request_id: Unique request identifier
+            user_id: Current user identifier
+
+        Returns:
+            Dictionary with system variables
+        """
+        now = datetime.now(timezone.utc)
+
+        return {
+            "date": now.strftime("%Y-%m-%d"),
+            "time": now.strftime("%H:%M:%S"),
+            "timestamp": now.isoformat(),
+            "request_id": request_id or str(uuid.uuid4()),
+            "user_id": user_id,
+        }
+
+
+class PassthroughNamespace(NamespaceBuilder):
+    """Request parameters namespace: {{ passthrough.* }}"""
+
+    @property
+    def namespace_name(self) -> str:
+        return "passthrough"
+
+    def build(
+        self, passthrough_data: Optional[Dict[str, Any]] = None, **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Build passthrough context from request parameters.
+
+        Args:
+            passthrough_data: Dictionary of parameters from web request
+
+        Returns:
+            Dictionary with passthrough variables
+        """
+        if not passthrough_data:
+            return {}
+        safe_data = {}
+        for key, value in passthrough_data.items():
+            if isinstance(value, (str, int, float, bool, type(None))):
+                safe_data[key] = value
+            else:
+                logger.warning(
+                    f"Skipping non-serializable passthrough value for key '{key}': {type(value)}"
+                )
+        return safe_data
+
+
+class SourceNamespace(NamespaceBuilder):
+    """RAG source documents namespace: {{ source.* }}"""
+
+    @property
+    def namespace_name(self) -> str:
+        return "source"
+
+    def build(
+        self, docs: Optional[list] = None, docs_together: Optional[str] = None, **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Build source context from RAG retrieval results.
+
+        Args:
+            docs: List of retrieved documents
+            docs_together: Concatenated document content (for backward compatibility)
+
+        Returns:
+            Dictionary with source variables
+        """
+        context = {}
+
+        if docs:
+            context["documents"] = docs
+            context["count"] = len(docs)
+        if docs_together:
+            context["docs_together"] = docs_together  # Add docs_together for custom templates
+            context["content"] = docs_together
+            context["summaries"] = docs_together
+        return context
+
+
+class ToolsNamespace(NamespaceBuilder):
+    """Pre-executed tools namespace: {{ tools.* }}"""
+
+    @property
+    def namespace_name(self) -> str:
+        return "tools"
+
+    def build(
+        self, tools_data: Optional[Dict[str, Any]] = None, **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Build tools context with pre-executed tool results.
+
+        Args:
+            tools_data: Dictionary of pre-fetched tool results organized by tool name
+                       e.g., {"memory": {"notes": "content", "tasks": "list"}}
+
+        Returns:
+            Dictionary with tool results organized by tool name
+        """
+        if not tools_data:
+            return {}
+
+        safe_data = {}
+        for tool_name, tool_result in tools_data.items():
+            if isinstance(tool_result, (str, dict, list, int, float, bool, type(None))):
+                safe_data[tool_name] = tool_result
+            else:
+                logger.warning(
+                    f"Skipping non-serializable tool result for '{tool_name}': {type(tool_result)}"
+                )
+        return safe_data
+
+
+class NamespaceManager:
+    """Manages all namespace builders and context assembly"""
+
+    def __init__(self):
+        self._builders = {
+            "system": SystemNamespace(),
+            "passthrough": PassthroughNamespace(),
+            "source": SourceNamespace(),
+            "tools": ToolsNamespace(),
+        }
+
+    def build_context(self, **kwargs) -> Dict[str, Any]:
+        """
+        Build complete template context from all namespaces.
+
+        Args:
+            **kwargs: Parameters to pass to namespace builders
+
+        Returns:
+            Complete context dictionary for template rendering
+        """
+        context = {}
+
+        for namespace_name, builder in self._builders.items():
+            try:
+                namespace_context = builder.build(**kwargs)
+                # Always include namespace, even if empty, to prevent undefined errors
+                context[namespace_name] = namespace_context if namespace_context else {}
+            except Exception as e:
+                logger.error(f"Failed to build {namespace_name} namespace: {str(e)}")
+                # Include empty namespace on error to prevent template failures
+                context[namespace_name] = {}
+        return context
+
+    def get_builder(self, namespace_name: str) -> Optional[NamespaceBuilder]:
+        """Get specific namespace builder"""
+        return self._builders.get(namespace_name)

application/templates/template_engine.py

@@ -0,0 +1,161 @@
+import logging
+from typing import Any, Dict, List, Optional, Set
+
+from jinja2 import (
+    ChainableUndefined,
+    Environment,
+    nodes,
+    select_autoescape,
+    TemplateSyntaxError,
+)
+from jinja2.exceptions import UndefinedError
+
+logger = logging.getLogger(__name__)
+
+
+class TemplateRenderError(Exception):
+    """Raised when template rendering fails"""
+
+    pass
+
+
+class TemplateEngine:
+    """Jinja2-based template engine for dynamic prompt rendering"""
+
+    def __init__(self):
+        self._env = Environment(
+            undefined=ChainableUndefined,
+            trim_blocks=True,
+            lstrip_blocks=True,
+            autoescape=select_autoescape(default_for_string=True, default=True),
+        )
+
+    def render(self, template_content: str, context: Dict[str, Any]) -> str:
+        """
+        Render template with provided context.
+
+        Args:
+            template_content: Raw template string with Jinja2 syntax
+            context: Dictionary of variables to inject into template
+
+        Returns:
+            Rendered template string
+
+        Raises:
+            TemplateRenderError: If template syntax is invalid or variables undefined
+        """
+        if not template_content:
+            return ""
+        try:
+            template = self._env.from_string(template_content)
+            return template.render(**context)
+        except TemplateSyntaxError as e:
+            error_msg = f"Template syntax error at line {e.lineno}: {e.message}"
+            logger.error(error_msg)
+            raise TemplateRenderError(error_msg) from e
+        except UndefinedError as e:
+            error_msg = f"Undefined variable in template: {e.message}"
+            logger.error(error_msg)
+            raise TemplateRenderError(error_msg) from e
+        except Exception as e:
+            error_msg = f"Template rendering failed: {str(e)}"
+            logger.error(error_msg)
+            raise TemplateRenderError(error_msg) from e
+
+    def validate_template(self, template_content: str) -> bool:
+        """
+        Validate template syntax without rendering.
+
+        Args:
+            template_content: Template string to validate
+
+        Returns:
+            True if template is syntactically valid
+        """
+        if not template_content:
+            return True
+        try:
+            self._env.from_string(template_content)
+            return True
+        except TemplateSyntaxError as e:
+            logger.debug(f"Template syntax invalid at line {e.lineno}: {e.message}")
+            return False
+        except Exception as e:
+            logger.debug(f"Template validation error: {type(e).__name__}: {str(e)}")
+            return False
+
+    def extract_variables(self, template_content: str) -> Set[str]:
+        """
+        Extract all variable names from template.
+
+        Args:
+            template_content: Template string to analyze
+
+        Returns:
+            Set of variable names found in template
+        """
+        if not template_content:
+            return set()
+        try:
+            ast = self._env.parse(template_content)
+            return set(self._env.get_template_module(ast).make_module().keys())
+        except TemplateSyntaxError as e:
+            logger.debug(f"Cannot extract variables - syntax error at line {e.lineno}")
+            return set()
+        except Exception as e:
+            logger.debug(f"Cannot extract variables: {type(e).__name__}")
+            return set()
+
+    def extract_tool_usages(
+        self, template_content: str
+    ) -> Dict[str, Set[Optional[str]]]:
+        """Extract tool and action references from a template"""
+        if not template_content:
+            return {}
+        try:
+            ast = self._env.parse(template_content)
+        except TemplateSyntaxError as e:
+            logger.debug(f"extract_tool_usages - syntax error at line {e.lineno}")
+            return {}
+        except Exception as e:
+            logger.debug(f"extract_tool_usages - parse error: {type(e).__name__}")
+            return {}
+
+        usages: Dict[str, Set[Optional[str]]] = {}
+
+        def record(path: List[str]) -> None:
+            if not path:
+                return
+            tool_name = path[0]
+            action_name = path[1] if len(path) > 1 else None
+            if not tool_name:
+                return
+            tool_entry = usages.setdefault(tool_name, set())
+            tool_entry.add(action_name)
+
+        for node in ast.find_all(nodes.Getattr):
+            path = []
+            current = node
+            while isinstance(current, nodes.Getattr):
+                path.append(current.attr)
+                current = current.node
+            if isinstance(current, nodes.Name) and current.name == "tools":
+                path.reverse()
+                record(path)
+
+        for node in ast.find_all(nodes.Getitem):
+            path = []
+            current = node
+            while isinstance(current, nodes.Getitem):
+                key = current.arg
+                if isinstance(key, nodes.Const) and isinstance(key.value, str):
+                    path.append(key.value)
+                else:
+                    path = []
+                    break
+                current = current.node
+            if path and isinstance(current, nodes.Name) and current.name == "tools":
+                path.reverse()
+                record(path)
+
+        return usages

application/tts/elevenlabs.py

@@ -15,10 +15,11 @@ class ElevenlabsTTS(BaseTTS):
 
     def text_to_speech(self, text):
         lang = "en"
-        audio = self.client.generate(
+        audio = self.client.text_to_speech.convert(
+            voice_id="nPczCjzI2devNBz1zQrb",             
+            model_id="eleven_multilingual_v2",
             text=text,
-            model="eleven_multilingual_v2",
-            voice="Brian",
+            output_format="mp3_44100_128"
         )
         audio_data = BytesIO()
         for chunk in audio:

application/tts/tts_creator.py

@@ -0,0 +1,18 @@
+from application.tts.google_tts import GoogleTTS
+from application.tts.elevenlabs import ElevenlabsTTS
+from application.tts.base import BaseTTS
+
+
+
+class TTSCreator:
+    tts_providers = {
+        "google_tts": GoogleTTS,
+        "elevenlabs": ElevenlabsTTS,
+    }
+
+    @classmethod
+    def create_tts(cls, tts_type, *args, **kwargs)-> BaseTTS:
+        tts_class = cls.tts_providers.get(tts_type.lower())
+        if not tts_class:
+            raise ValueError(f"No tts class found for type {tts_type}")
+        return tts_class(*args, **kwargs)

application/utils.py

@@ -7,6 +7,8 @@ import tiktoken
 from flask import jsonify, make_response
 from werkzeug.utils import secure_filename
 
+from application.core.model_utils import get_token_limit
+
 from application.core.settings import settings
 
 
@@ -21,7 +23,7 @@ def get_encoding():
 
 
 def get_gpt_model() -> str:
-    """Get the appropriate GPT model based on provider"""
+    """Get GPT model based on provider"""
     model_map = {
         "openai": "gpt-4o-mini",
         "anthropic": "claude-2",
@@ -32,16 +34,7 @@ def get_gpt_model() -> str:
 
 
 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
-    """
+    """Create safe filename, preserving extension. Handles non-Latin characters."""
     if not filename:
         return str(uuid.uuid4())
     _, extension = os.path.splitext(filename)
@@ -83,8 +76,23 @@ def count_tokens_docs(docs):
     return tokens
 
 
+def calculate_doc_token_budget(
+    model_id: str = "gpt-4o", history_token_limit: int = 2000
+) -> int:
+    total_context = get_token_limit(model_id)
+    reserved = sum(settings.RESERVED_TOKENS.values())
+    doc_budget = total_context - history_token_limit - reserved
+    return max(doc_budget, 1000)
+
+
+def get_missing_fields(data, required_fields):
+    """Check for missing required fields. Returns list of missing field names."""
+    return [field for field in required_fields if field not in data]
+
+
 def check_required_fields(data, required_fields):
-    missing_fields = [field for field in required_fields if field not in data]
+    """Validate required fields. Returns Flask 400 response if validation fails, None otherwise."""
+    missing_fields = get_missing_fields(data, required_fields)
     if missing_fields:
         return make_response(
             jsonify(
@@ -98,7 +106,8 @@ def check_required_fields(data, required_fields):
     return None
 
 
-def validate_required_fields(data, required_fields):
+def get_field_validation_errors(data, required_fields):
+    """Check for missing and empty fields. Returns dict with 'missing_fields' and 'empty_fields', or None."""
     missing_fields = []
     empty_fields = []
 
@@ -107,12 +116,24 @@ def validate_required_fields(data, required_fields):
             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:
+    if missing_fields or empty_fields:
+        return {"missing_fields": missing_fields, "empty_fields": empty_fields}
+    return None
+
+
+def validate_required_fields(data, required_fields):
+    """Validate required fields (must exist and be non-empty). Returns Flask 400 response if validation fails, None otherwise."""
+    errors_dict = get_field_validation_errors(data, required_fields)
+    if errors_dict:
+        errors = []
+        if errors_dict["missing_fields"]:
+            errors.append(
+                f"Missing required fields: {', '.join(errors_dict['missing_fields'])}"
+            )
+        if errors_dict["empty_fields"]:
+            errors.append(
+                f"Empty values in required fields: {', '.join(errors_dict['empty_fields'])}"
+            )
         return make_response(
             jsonify({"success": False, "message": " | ".join(errors)}), 400
         )
@@ -123,19 +144,13 @@ def get_hash(data):
     return hashlib.md5(data.encode(), usedforsecurity=False).hexdigest()
 
 
-def limit_chat_history(history, max_token_limit=None, gpt_model="docsgpt"):
-    """
-    Limits chat history based on token count.
-    Returns a list of messages that fit within the token limit.
-    """
-    from application.core.settings import settings
-
+def limit_chat_history(history, max_token_limit=None, model_id="docsgpt-local"):
+    """Limit chat history to fit within token limit."""
+    model_token_limit = get_token_limit(model_id)
     max_token_limit = (
         max_token_limit
-        if max_token_limit
-        and max_token_limit
-        < settings.LLM_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
-        else settings.LLM_TOKEN_LIMITS.get(gpt_model, settings.DEFAULT_MAX_HISTORY)
+        if max_token_limit and max_token_limit < model_token_limit
+        else model_token_limit
     )
 
     if not history:
@@ -161,13 +176,17 @@ def limit_chat_history(history, max_token_limit=None, gpt_model="docsgpt"):
 
 
 def validate_function_name(function_name):
-    """Validates if a function name matches the allowed pattern."""
+    """Validate function name matches allowed pattern (alphanumeric, underscore, hyphen)."""
     if not re.match(r"^[a-zA-Z0-9_-]+$", function_name):
         return False
     return True
 
 
 def generate_image_url(image_path):
+    if isinstance(image_path, str) and (
+        image_path.startswith("http://") or image_path.startswith("https://")
+    ):
+        return image_path
     strategy = getattr(settings, "URL_STRATEGY", "backend")
     if strategy == "s3":
         bucket_name = getattr(settings, "S3_BUCKET_NAME", "docsgpt-test-bucket")
@@ -176,3 +195,51 @@ def generate_image_url(image_path):
     else:
         base_url = getattr(settings, "API_URL", "http://localhost:7091")
         return f"{base_url}/api/images/{image_path}"
+
+
+def clean_text_for_tts(text: str) -> str:
+    """
+    clean text for Text-to-Speech processing.
+    """
+    # Handle code blocks and links
+
+    text = re.sub(r"```mermaid[\s\S]*?```", " flowchart, ", text)  ## ```mermaid...```
+    text = re.sub(r"```[\s\S]*?```", " code block, ", text)  ## ```code```
+    text = re.sub(r"\[([^\]]+)\]\([^\)]+\)", r"\1", text)  ## [text](url)
+    text = re.sub(r"!\[([^\]]*)\]\([^\)]+\)", "", text)  ## ![alt](url)
+
+    # Remove markdown formatting
+
+    text = re.sub(r"`([^`]+)`", r"\1", text)  ## `code`
+    text = re.sub(r"\{([^}]*)\}", r" \1 ", text)  ## {text}
+    text = re.sub(r"[{}]", " ", text)  ## unmatched {}
+    text = re.sub(r"\[([^\]]+)\]", r" \1 ", text)  ## [text]
+    text = re.sub(r"[\[\]]", " ", text)  ## unmatched []
+    text = re.sub(r"(\*\*|__)(.*?)\1", r"\2", text)  ## **bold** __bold__
+    text = re.sub(r"(\*|_)(.*?)\1", r"\2", text)  ## *italic* _italic_
+    text = re.sub(r"^#{1,6}\s+", "", text, flags=re.MULTILINE)  ## # headers
+    text = re.sub(r"^>\s+", "", text, flags=re.MULTILINE)  ## > blockquotes
+    text = re.sub(r"^[\s]*[-\*\+]\s+", "", text, flags=re.MULTILINE)  ## - * + lists
+    text = re.sub(r"^[\s]*\d+\.\s+", "", text, flags=re.MULTILINE)  ## 1. numbered lists
+    text = re.sub(
+        r"^[\*\-_]{3,}\s*$", "", text, flags=re.MULTILINE
+    )  ## --- *** ___ rules
+    text = re.sub(r"<[^>]*>", "", text)  ## <html> tags
+
+    # Remove non-ASCII (emojis, special Unicode)
+
+    text = re.sub(r"[^\x20-\x7E\n\r\t]", "", text)
+
+    # Replace special sequences
+
+    text = re.sub(r"-->", ", ", text)  ## -->
+    text = re.sub(r"<--", ", ", text)  ## <--
+    text = re.sub(r"=>", ", ", text)  ## =>
+    text = re.sub(r"::", " ", text)  ## ::
+
+    # Normalize whitespace
+
+    text = re.sub(r"\s+", " ", text)
+    text = text.strip()
+
+    return text

application/worker.py

@@ -39,6 +39,7 @@ sources_collection = db["sources"]
 
 # Constants
 
+
 MIN_TOKENS = 150
 MAX_TOKENS = 1250
 RECURSION_DEPTH = 2
@@ -164,7 +165,7 @@ def run_agent_logic(agent_config, input_data):
             agent_type,
             endpoint="webhook",
             llm_name=settings.LLM_PROVIDER,
-            gpt_model=settings.LLM_NAME,
+            model_id=settings.LLM_NAME,
             api_key=settings.API_KEY,
             user_api_key=user_api_key,
             prompt=prompt,
@@ -179,7 +180,7 @@ def run_agent_logic(agent_config, input_data):
             prompt=prompt,
             chunks=chunks,
             token_limit=settings.DEFAULT_MAX_HISTORY,
-            gpt_model=settings.LLM_NAME,
+            model_id=settings.LLM_NAME,
             user_api_key=user_api_key,
             decoded_token=decoded_token,
         )
@@ -740,7 +741,13 @@ def remote_worker(
         if os.path.exists(full_path):
             shutil.rmtree(full_path)
     logging.info("remote_worker task completed successfully")
-    return {"urls": source_data, "name_job": name_job, "user": user, "limited": False}
+    return {
+        "id": str(id),
+        "urls": source_data,
+        "name_job": name_job,
+        "user": user,
+        "limited": False,
+    }
 
 
 def sync(

deployment/docker-compose-hub.yaml

@@ -72,4 +72,4 @@ services:
       - mongodb_data_container:/data/db
 
 volumes:
-  mongodb_data_container:
+  mongodb_data_container:

docs/package.json

@@ -8,9 +8,9 @@
   "dependencies": {
     "@vercel/analytics": "^1.1.1",
     "docsgpt-react": "^0.5.1",
-    "next": "^15.3.3",
-    "nextra": "^2.13.2",
-    "nextra-theme-docs": "^2.13.2",
+    "next": "^15.5.6",
+    "nextra": "^4.6.0",
+    "nextra-theme-docs": "^4.6.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   }

docs/pages/Agents/basics.mdx

@@ -107,3 +107,13 @@ Once an agent is created, you can:
     * Modify any of its configuration settings (name, description, source, prompt, tools, type).
     * **Generate a Public Link:** From the edit screen, you can create a shareable public link that allows others to import and use your agent.
     * **Get a Webhook URL:** You can also obtain a Webhook URL for the agent. This allows external applications or services to trigger the agent and receive responses programmatically, enabling powerful integrations and automations.
+
+## Seeding Premade Agents from YAML
+
+You can bootstrap a fresh DocsGPT deployment with a curated set of agents by seeding them directly into MongoDB.
+
+1. **Customize the configuration** – edit `application/seed/config/premade_agents.yaml` (or copy from `application/seed/config/agents_template.yaml`) to describe the agents you want to provision. Each entry lets you define prompts, tools, and optional data sources.
+2. **Ensure dependencies are running** – MongoDB must be reachable using the credentials in `.env`, and a Celery worker should be available if any agent sources need to be ingested via `ingest_remote`.
+3. **Execute the seeder** – run `python -m application.seed.commands init`. Add `--force` when you need to reseed an existing environment.
+
+The seeder keeps templates under the `system` user so they appear in the UI for anyone to clone or customize. Environment variable placeholders such as `${MY_TOKEN}` inside tool configs are resolved during the seeding process.

docs/pages/Deploying/Development-Environment.mdx

@@ -42,7 +42,7 @@ To run the DocsGPT backend locally, you'll need to set up a Python environment a
 
     *   **Option 1: Using a `.env` file (Recommended):**
         *   If you haven't already, create a file named `.env` in the **root directory** of your DocsGPT project.
-        *   Modify the `.env` file to adjust settings as needed. You can find a comprehensive list of configurable options in [`application/core/settings.py`](application/core/settings.py).
+        *   Modify the `.env` file to adjust settings as needed. You can find a comprehensive list of configurable options in [`application/core/settings.py`](https://github.com/arc53/DocsGPT/blob/main/application/core/settings.py).
 
     *   **Option 2: Exporting Environment Variables:**
         *   Alternatively, you can export environment variables directly in your terminal. However, using a `.env` file is generally more organized for development.
@@ -67,7 +67,7 @@ To run the DocsGPT backend locally, you'll need to set up a Python environment a
 
 3.  **Download Embedding Model:**
 
-    The backend requires an embedding model. Download the `mpnet-base-v2` model and place it in the `model/` directory within the project root. You can use the following script:
+    The backend requires an embedding model. Download the `mpnet-base-v2` model and place it in the `models/` directory within the project root. You can use the following script:
 
     ```bash
     wget https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip
@@ -75,7 +75,7 @@ To run the DocsGPT backend locally, you'll need to set up a Python environment a
     rm mpnet-base-v2.zip
     ```
 
-    Alternatively, you can manually download the zip file from [here](https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip), unzip it, and place the extracted folder in `model/`.
+    Alternatively, you can manually download the zip file from [here](https://d3dg1063dc54p9.cloudfront.net/models/embeddings/mpnet-base-v2.zip), unzip it, and place the extracted folder in `models/`.
 
 4.  **Install Backend Dependencies:**
 
@@ -160,4 +160,4 @@ To run the DocsGPT frontend locally, you'll need Node.js and npm (Node Package M
 
     This command will start the Vite development server. The frontend application will typically be accessible at [http://localhost:5173/](http://localhost:5173/). The terminal will display the exact URL where the frontend is running.
 
-With both the backend and frontend running, you should now have a fully functional DocsGPT development environment. You can access the application in your browser at [http://localhost:5173/](http://localhost:5173/) and start developing!
+With both the backend and frontend running, you should now have a fully functional DocsGPT development environment. You can access the application in your browser at [http://localhost:5173/](http://localhost:5173/) and start developing!

docs/pages/Guides/Customising-prompts.mdx

@@ -1,49 +1,453 @@
 ---
-title: Customizing Prompts 
-description: This guide will explain how to change prompts in DocsGPT and why it might be benefitial. Additionaly this article expains additional variables that can be used in prompts.
+title: Customizing Prompts
+description: This guide explains how to customize prompts in DocsGPT using the new template-based system with dynamic variable injection.
 ---
 
 import Image from 'next/image'
 
-# Customizing the Main Prompt
+# Customizing Prompts in DocsGPT
 
-Customizing the main prompt for DocsGPT gives you the ability to tailor the AI's responses to your specific requirements. By modifying the prompt text, you can achieve more accurate and relevant answers. Here's how you can do it:
+Customizing prompts for DocsGPT gives you powerful control over the AI's behavior and responses. With the new template-based system, you can inject dynamic context through organized namespaces, making prompts flexible and maintainable without hardcoding values.
+
+## Quick Start
 
 1. Navigate to `SideBar -> Settings`.
-
-
-
-
-2.In Settings select the `Active Prompt` now you will be able to see various prompts style.x
-
-
-
-
-3.Click on the `edit icon`  on the prompt of your choice and you will be able to see the current prompt for it,you can now customise  the prompt as per your choice.
+2. In Settings, select the `Active Prompt` to see various prompt styles.
+3. Click on the `edit icon` on your chosen prompt to customize it.
 
 ### Video Demo
 <Image src="/prompts.gif" alt="prompts" width={800} height={500} />
 
+---
 
+## Template-Based Prompt System
 
-## Example Prompt Modification
+DocsGPT now uses **Jinja2 templating** with four organized namespaces for dynamic variable injection:
+
+### Available Namespaces
+
+#### 1. **`system`** - System Metadata
+Access system-level information:
+
+```jinja
+{{ system.date }}         # Current date (YYYY-MM-DD)
+{{ system.time }}         # Current time (HH:MM:SS)
+{{ system.timestamp }}    # ISO 8601 timestamp
+{{ system.request_id }}   # Unique request identifier
+{{ system.user_id }}      # Current user ID
+```
+
+#### 2. **`source`** - Retrieved Documents
+Access RAG (Retrieval-Augmented Generation) document context:
+
+```jinja
+{{ source.content }}      # Concatenated document content
+{{ source.summaries }}    # Alias for content (backward compatible)
+{{ source.documents }}    # List of document objects
+{{ source.count }}        # Number of retrieved documents
+```
+
+#### 3. **`passthrough`** - Request Parameters
+Access custom parameters passed in the API request:
+
+```jinja
+{{ passthrough.company }}     # Custom field from request
+{{ passthrough.user_name }}   # User-provided data
+{{ passthrough.context }}     # Any custom parameter
+```
+
+To use passthrough data, send it in your API request:
+```json
+{
+  "question": "What is the pricing?",
+  "passthrough": {
+    "company": "Acme Corp",
+    "user_name": "Alice",
+    "plan_type": "enterprise"
+  }
+}
+```
+
+#### 4. **`tools`** - Pre-fetched Tool Data
+Access results from tools that run before the agent (like memory tool):
+
+```jinja
+{{ tools.memory.root }}       # Memory tool directory listing
+{{ tools.memory.available }}  # Boolean: is memory available
+```
+
+---
+
+## Example Prompts
+
+### Basic Prompt with Documents
+```jinja
+You are a helpful AI assistant for DocsGPT.
+
+Current date: {{ system.date }}
+
+Use the following documents to answer the question:
+
+{{ source.content }}
+
+Provide accurate, helpful answers with code examples when relevant.
+```
+
+### Advanced Prompt with All Namespaces
+```jinja
+You are an AI assistant for {{ passthrough.company }}.
+
+**System Info:**
+- Date: {{ system.date }}
+- Request ID: {{ system.request_id }}
+
+**User Context:**
+- User: {{ passthrough.user_name }}
+- Role: {{ passthrough.role }}
+
+**Available Documents ({{ source.count }}):**
+{{ source.content }}
+
+**Memory Context:**
+{% if tools.memory.available %}
+{{ tools.memory.root }}
+{% else %}
+No saved context available.
+{% endif %}
+
+Please provide detailed, accurate answers based on the documents above.
+```
+
+### Conditional Logic Example
+```jinja
+You are a DocsGPT assistant.
+
+{% if source.count > 0 %}
+I found {{ source.count }} relevant document(s):
+
+{{ source.content }}
+
+Base your answer on these documents.
+{% else %}
+No documents were found. Please answer based on your general knowledge.
+{% endif %}
+```
+
+---
+
+## Migration Guide
+
+### Legacy Format (Still Supported)
+The old `{summaries}` format continues to work for backward compatibility:
 
-**Original Prompt:**
 ```markdown
-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 it's 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 assistant.
 
-(code)
+Documents:
 {summaries}
 ```
 
-Note that `{summaries}` allows model to see and respond to your upploaded documents. If you don't want this functionality you can safely remove it from the customized prompt.
+This will automatically substitute `{summaries}` with document content.
 
-Feel free to customize the prompt to align it with your specific use case or the kind of responses you want from the AI. For example, you can focus on specific document types, industries, or topics to get more targeted results.
+### New Template Format (Recommended)
+Migrate to the new template syntax for more flexibility:
+
+```jinja
+You are a helpful assistant.
+
+Documents:
+{{ source.content }}
+```
+
+**Migration mapping:**
+- `{summaries}` → `{{ source.content }}` or `{{ source.summaries }}`
+
+---
+
+## Best Practices
+
+### 1. **Use Descriptive Context**
+```jinja
+**Retrieved Documents:**
+{{ source.content }}
+
+**User Query Context:**
+- Company: {{ passthrough.company }}
+- Department: {{ passthrough.department }}
+```
+
+### 2. **Handle Missing Data Gracefully**
+```jinja
+{% if passthrough.user_name %}
+Hello {{ passthrough.user_name }}!
+{% endif %}
+```
+
+### 3. **Leverage Memory for Continuity**
+```jinja
+{% if tools.memory.available %}
+**Previous Context:**
+{{ tools.memory.root }}
+{% endif %}
+
+**Current Question:**
+Please consider the above context when answering.
+```
+
+### 4. **Add Clear Instructions**
+```jinja
+You are a technical support assistant.
+
+**Guidelines:**
+1. Always reference the documents below
+2. Provide step-by-step instructions
+3. Include code examples when relevant
+
+**Reference Documents:**
+{{ source.content }}
+```
+
+---
+
+## Advanced Features
+
+### Looping Over Documents
+```jinja
+{% for doc in source.documents %}
+**Source {{ loop.index }}:** {{ doc.filename }}
+{{ doc.text }}
+
+{% endfor %}
+```
+
+### Date-Based Behavior
+```jinja
+{% if system.date > "2025-01-01" %}
+Note: This is information from 2025 or later.
+{% endif %}
+```
+
+### Custom Formatting
+```jinja
+**Request Information**
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Request ID: {{ system.request_id }}
+• User: {{ passthrough.user_name | default("Guest") }}
+• Time: {{ system.time }}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## Tool Pre-Fetching
+
+### Memory Tool Configuration
+Enable memory tool pre-fetching to inject saved context into prompts:
+
+```python
+# In your tool configuration
+{
+  "name": "memory",
+  "config": {
+    "pre_fetch_enabled": true  # Default: true
+  }
+}
+```
+
+Control pre-fetching globally:
+```bash
+# .env file
+ENABLE_TOOL_PREFETCH=true
+```
+
+Or per-request:
+```json
+{
+  "question": "What are the requirements?",
+  "disable_tool_prefetch": false
+}
+```
+
+---
+
+## Debugging Prompts
+
+### View Rendered Prompts in Logs
+Set log level to `INFO` to see the final rendered prompt sent to the LLM:
+
+```bash
+export LOG_LEVEL=INFO
+```
+
+You'll see output like:
+```
+INFO - Rendered system prompt for agent (length: 1234 chars):
+================================================================================
+You are a helpful assistant for Acme Corp.
+
+Current date: 2025-10-30
+Request ID: req_abc123
+
+Documents:
+Technical documentation about...
+================================================================================
+```
+
+### Template Validation
+Test your template syntax before saving:
+```python
+from application.api.answer.services.prompt_renderer import PromptRenderer
+
+renderer = PromptRenderer()
+is_valid = renderer.validate_template("Your prompt with {{ variables }}")
+```
+
+---
+
+## Common Use Cases
+
+### 1. Customer Support Bot
+```jinja
+You are a customer support assistant for {{ passthrough.company }}.
+
+**Customer:** {{ passthrough.customer_name }}
+**Ticket ID:** {{ system.request_id }}
+**Date:** {{ system.date }}
+
+**Knowledge Base:**
+{{ source.content }}
+
+**Previous Interactions:**
+{{ tools.memory.root }}
+
+Please provide helpful, friendly support based on the knowledge base above.
+```
+
+### 2. Technical Documentation Assistant
+```jinja
+You are a technical documentation expert.
+
+**Available Documentation ({{ source.count }} documents):**
+{{ source.content }}
+
+**Requirements:**
+- Provide code examples in {{ passthrough.language }}
+- Focus on {{ passthrough.framework }} best practices
+- Include relevant links when possible
+```
+
+### 3. Internal Knowledge Base
+```jinja
+You are an internal AI assistant for {{ passthrough.department }}.
+
+**Employee:** {{ passthrough.employee_name }}
+**Access Level:** {{ passthrough.access_level }}
+
+**Relevant Documents:**
+{{ source.content }}
+
+Provide detailed answers appropriate for {{ passthrough.access_level }} access level.
+```
+
+---
+
+## Template Syntax Reference
+
+### Variables
+```jinja
+{{ variable_name }}              # Output variable
+{{ namespace.field }}            # Access nested field
+{{ variable | default("N/A") }}  # Default value
+```
+
+### Conditionals
+```jinja
+{% if condition %}
+  Content
+{% elif other_condition %}
+  Other content
+{% else %}
+  Default content
+{% endif %}
+```
+
+### Loops
+```jinja
+{% for item in list %}
+  {{ item.field }}
+{% endfor %}
+```
+
+### Comments
+```jinja
+{# This is a comment and won't appear in output #}
+```
+
+---
+
+## Security Considerations
+
+1. **Input Sanitization**: Passthrough data is automatically sanitized to prevent injection attacks
+2. **Type Filtering**: Only primitive types (string, int, float, bool, None) are allowed in passthrough
+3. **Autoescaping**: Jinja2 autoescaping is enabled by default
+4. **Size Limits**: Consider the token budget when including large documents
+
+---
+
+## Troubleshooting
+
+### Problem: Variables Not Rendering
+**Solution:** Ensure you're using the correct namespace:
+```jinja
+❌ {{ company }}
+✅ {{ passthrough.company }}
+```
+
+### Problem: Empty Output for Tool Data
+**Solution:** Check that tool pre-fetching is enabled and the tool is configured correctly.
+
+### Problem: Syntax Errors
+**Solution:** Validate template syntax. Common issues:
+```jinja
+❌ {{ variable }     # Missing closing brace
+❌ {% if x %         # Missing closing %}
+✅ {{ variable }}
+✅ {% if x %}...{% endif %}
+```
+
+### Problem: Legacy Prompts Not Working
+**Solution:** The system auto-detects template syntax. If your prompt uses `{summaries}`, it will work in legacy mode. To use new features, add `{{ }}` syntax.
+
+---
+
+## API Reference
+
+### Render Prompt via API
+```python
+from application.api.answer.services.prompt_renderer import PromptRenderer
+
+renderer = PromptRenderer()
+rendered = renderer.render_prompt(
+    prompt_content="Your template with {{ passthrough.name }}",
+    user_id="user_123",
+    request_id="req_456",
+    passthrough_data={"name": "Alice"},
+    docs_together="Document content here",
+    tools_data={"memory": {"root": "Files: notes.txt"}}
+)
+```
+
+---
 
 ## Conclusion
 
-Customizing the main prompt for DocsGPT allows you to tailor the AI's responses to your unique requirements. Whether you need in-depth explanations, code examples, or specific insights, you can achieve it by modifying the main prompt. Remember to experiment and fine-tune your prompts to get the best results.
+The new template-based prompt system provides powerful flexibility while maintaining backward compatibility. By leveraging namespaces, you can create dynamic, context-aware prompts that adapt to your specific use case.
 
+**Key Benefits:**
+- ✅ Dynamic variable injection
+- ✅ Organized namespaces
+- ✅ Backward compatible
+- ✅ Security built-in
+- ✅ Easy to debug
+
+Start with simple templates and gradually add complexity as needed. Happy prompting! 🚀

docs/pages/quickstart.mdx

@@ -43,7 +43,8 @@ The easiest way to launch DocsGPT is using the provided `setup.sh` script. This
    2) Serve Local (with Ollama)
    3) Connect Local Inference Engine
    4) Connect Cloud API Provider
-   Choose option (1-4):
+   5) Advanced: Build images locally (for developers)
+   Choose option (1-5):
    ```
 
    Let's break down each option:
@@ -56,6 +57,8 @@ The easiest way to launch DocsGPT is using the provided `setup.sh` script. This
 
    * **4) Connect Cloud API Provider:** This option lets you connect DocsGPT to a commercial Cloud API provider such as OpenAI, Google (Vertex AI/Gemini), Anthropic (Claude), Groq, HuggingFace Inference API, or Azure OpenAI. You will need an API key from your chosen provider. Select this if you prefer to use a powerful cloud-based LLM.
 
+   * **5) Modify DocsGPT's source code and rebuild the Docker images locally.** Instead of pulling prebuilt images from Docker Hub or using the hosted/public API, you build the entire backend and frontend from source, customizing how DocsGPT works internally, or run it in an environment without internet access.
+
    After selecting an option and providing any required information (like API keys or model names), the script will configure your `.env` file and start DocsGPT using Docker Compose.
 
 4. **Access DocsGPT in your browser:**
@@ -116,4 +119,4 @@ If you prefer a more manual approach, you can follow our [Docker Deployment docu
 
 For more advanced customization of DocsGPT settings, such as configuring vector stores, embedding models, and other parameters, please refer to the [DocsGPT Settings documentation](/Deploying/DocsGPT-Settings). This guide explains how to modify the `.env` file or `settings.py` for deeper configuration.
 
-Enjoy using DocsGPT!
+Enjoy using DocsGPT!

frontend/.env.development

@@ -1,4 +1,6 @@
 # Please put appropriate value
 VITE_BASE_URL=http://localhost:5173
 VITE_API_HOST=http://127.0.0.1:7091
-VITE_API_STREAMING=true
+VITE_API_STREAMING=true
+VITE_NOTIFICATION_TEXT="What's new in 0.14.0 — Changelog"
+VITE_NOTIFICATION_LINK="https://blog.docsgpt.cloud/docsgpt-0-14-agents-automate-integrate-and-innovate/"

frontend/.eslintignore

@@ -1,17 +0,0 @@
-node_modules/
-dist/
-prettier.config.cjs
-.eslintrc.cjs
-env.d.ts
-public/
-assets/
-vite-env.d.ts
-.prettierignore
-package-lock.json
-package.json
-postcss.config.cjs
-prettier.config.cjs
-tailwind.config.cjs
-tsconfig.json
-tsconfig.node.json
-vite.config.ts

frontend/.eslintrc.cjs

@@ -1,45 +0,0 @@
-module.exports = {
-  env: {
-    browser: true,
-    es2021: true,
-    node: true,
-  },
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:react/recommended',
-    'plugin:prettier/recommended',
-  ],
-  overrides: [],
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 'latest',
-    sourceType: 'module',
-  },
-  plugins: ['react', 'unused-imports'],
-  rules: {
-    'react/prop-types': 'off',
-    'unused-imports/no-unused-imports': 'error',
-    'react/react-in-jsx-scope': 'off',
-    'prettier/prettier': [
-      'error',
-      {
-        endOfLine: 'auto',
-      },
-    ],
-  },
-  settings: {
-    'import/parsers': {
-      '@typescript-eslint/parser': ['.ts', '.tsx'],
-    },
-    react: {
-      version: 'detect',
-    },
-    'import/resolver': {
-      node: {
-        paths: ['src'],
-        extensions: ['.js', '.jsx', '.ts', '.tsx'],
-      },
-    },
-  },
-};

frontend/eslint.config.js

@@ -0,0 +1,78 @@
+import js from '@eslint/js'
+import tsParser from '@typescript-eslint/parser'
+import tsPlugin from '@typescript-eslint/eslint-plugin'
+import react from 'eslint-plugin-react'
+import unusedImports from 'eslint-plugin-unused-imports'
+import prettier from 'eslint-plugin-prettier'
+import globals from 'globals'
+
+export default [
+  {
+    ignores: [
+      'node_modules/',
+      'dist/',
+      'prettier.config.cjs',
+      '.eslintrc.cjs',
+      'env.d.ts',
+      'public/',
+      'assets/',
+      'vite-env.d.ts',
+      '.prettierignore',
+      'package-lock.json',
+      'package.json',
+      'postcss.config.cjs',
+      'tailwind.config.cjs',
+      'tsconfig.json',
+      'tsconfig.node.json',
+      'vite.config.ts',
+    ],
+  },
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      parser: tsParser,
+      parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.es2021,
+        ...globals.node,
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      react,
+      'unused-imports': unusedImports,
+      prettier,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      ...react.configs.recommended.rules,
+      ...prettier.configs.recommended.rules,
+      'react/prop-types': 'off',
+      'unused-imports/no-unused-imports': 'error',
+      'react/react-in-jsx-scope': 'off',
+      'no-undef': 'off',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': 'warn',
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      'prettier/prettier': [
+        'error',
+        {
+          endOfLine: 'auto',
+        },
+      ],
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+    },
+  },
+]

frontend/package.json

@@ -19,21 +19,21 @@
     ]
   },
   "dependencies": {
-    "@reduxjs/toolkit": "^2.8.2",
+    "@reduxjs/toolkit": "^2.10.1",
     "chart.js": "^4.4.4",
     "clsx": "^2.1.1",
     "copy-to-clipboard": "^3.3.3",
-    "i18next": "^24.2.0",
-    "i18next-browser-languagedetector": "^8.0.2",
+    "i18next": "^25.5.3",
+    "i18next-browser-languagedetector": "^8.2.0",
     "lodash": "^4.17.21",
-    "mermaid": "^11.6.0",
+    "mermaid": "^11.12.1",
     "prop-types": "^15.8.1",
     "react": "^19.1.0",
     "react-chartjs-2": "^5.3.0",
-    "react-dom": "^19.0.0",
+    "react-dom": "^19.1.1",
     "react-dropzone": "^14.3.8",
     "react-google-drive-picker": "^1.2.2",
-    "react-i18next": "^15.4.0",
+    "react-i18next": "^16.2.4",
     "react-markdown": "^9.0.1",
     "react-redux": "^9.2.0",
     "react-router-dom": "^7.6.1",
@@ -46,30 +46,28 @@
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.10",
     "@types/lodash": "^4.17.20",
-    "@types/mermaid": "^9.1.0",
     "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.0.0",
+    "@types/react-dom": "^19.1.7",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "@typescript-eslint/eslint-plugin": "^5.51.0",
-    "@typescript-eslint/parser": "^5.62.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.3",
+    "@typescript-eslint/parser": "^8.46.3",
     "@vitejs/plugin-react": "^4.3.4",
-    "eslint": "^8.57.1",
+    "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.5",
-    "eslint-config-standard-with-typescript": "^34.0.0",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-n": "^15.7.0",
-    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-n": "^17.23.1",
+    "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-promise": "^6.6.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-unused-imports": "^4.1.4",
-    "husky": "^8.0.0",
+    "husky": "^9.1.7",
     "lint-staged": "^15.3.0",
     "postcss": "^8.4.49",
     "prettier": "^3.5.3",
-    "prettier-plugin-tailwindcss": "^0.6.13",
+    "prettier-plugin-tailwindcss": "^0.7.1",
     "tailwindcss": "^4.1.11",
     "typescript": "^5.8.3",
-    "vite": "^6.3.5",
+    "vite": "^7.2.0",
     "vite-plugin-svgr": "^4.3.0"
   }
 }

frontend/public/toolIcons/tool_memory.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3">
+  <path d="M240-80q-33 0-56.5-23.5T160-160v-480q0-33 23.5-56.5T240-720h80v-80q0-17 11.5-28.5T360-840q17 0 28.5 11.5T400-800v80h40v-80q0-17 11.5-28.5T480-840q17 0 28.5 11.5T520-800v80h40v-80q0-17 11.5-28.5T600-840q17 0 28.5 11.5T640-800v80h80q33 0 56.5 23.5T800-640v480q0 33-23.5 56.5T720-80H240Zm0-80h480v-480H240v480Zm120-320v-80h240v80H360Zm0 120v-80h240v80H360Zm0 120v-80h160v80H360ZM240-160v-480 480Z"/>
+</svg>

frontend/public/toolIcons/tool_notes.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M320-240h320v-80H320v80Zm0-160h320v-80H320v80ZM240-80q-33 0-56.5-23.5T160-160v-640q0-33 23.5-56.5T240-880h320l240 240v480q0 33-23.5 56.5T720-80H240Zm280-520v-200H240v640h480v-440H520ZM240-800v200-200 640-640Z"/></svg>

frontend/public/toolIcons/tool_todo_list.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#e3e3e3"><path d="M240-80q-33 0-56.5-23.5T160-160v-640q0-33 23.5-56.5T240-880h480q33 0 56.5 23.5T800-800v640q0 33-23.5 56.5T720-80H240Zm0-80h480v-640H240v640Zm88-104 56-56-56-56-56 56 56 56Zm0-160 56-56-56-56-56 56 56 56Zm0-160 56-56-56-56-56 56 56 56Zm120 280h232v-80H448v80Zm0-160h232v-80H448v80Zm0-160h232v-80H448v80ZM240-160v-640 640Z"/></svg>

frontend/src/App.tsx

@@ -7,6 +7,7 @@ import Agents from './agents';
 import SharedAgentGate from './agents/SharedAgentGate';
 import ActionButtons from './components/ActionButtons';
 import Spinner from './components/Spinner';
+import UploadToast from './components/UploadToast';
 import Conversation from './conversation/Conversation';
 import { SharedConversation } from './conversation/SharedConversation';
 import { useDarkTheme, useMediaQuery } from './hooks';
@@ -14,6 +15,7 @@ import useTokenAuth from './hooks/useTokenAuth';
 import Navigation from './Navigation';
 import PageNotFound from './PageNotFound';
 import Setting from './settings';
+import Notification from './components/Notification';
 
 function AuthWrapper({ children }: { children: React.ReactNode }) {
   const { isAuthLoading } = useTokenAuth();
@@ -37,24 +39,41 @@ function MainLayout() {
       <Navigation navOpen={navOpen} setNavOpen={setNavOpen} />
       <ActionButtons showNewChat={true} showShare={true} />
       <div
-        className={`h-[calc(100dvh-64px)] overflow-auto lg:h-screen ${
+        className={`h-[calc(100dvh-64px)] overflow-auto transition-all duration-300 ease-in-out lg:h-screen ${
           !(isMobile || isTablet)
-            ? `ml-0 ${!navOpen ? 'lg:mx-auto' : 'lg:ml-72'}`
+            ? `${navOpen ? 'lg:ml-72' : 'lg:ml-0'}`
             : 'ml-0 lg:ml-16'
         }`}
       >
         <Outlet />
       </div>
+      <UploadToast />
     </div>
   );
 }
 export default function App() {
   const [, , componentMounted] = useDarkTheme();
+  const [showNotification, setShowNotification] = useState<boolean>(() => {
+    const saved = localStorage.getItem('showNotification');
+    return saved ? JSON.parse(saved) : true;
+  });
+  const notificationText = import.meta.env.VITE_NOTIFICATION_TEXT;
+  const notificationLink = import.meta.env.VITE_NOTIFICATION_LINK;
   if (!componentMounted) {
     return <div />;
   }
   return (
     <div className="relative h-full overflow-hidden">
+      {notificationLink && notificationText && showNotification && (
+        <Notification
+          notificationText={notificationText}
+          notificationLink={notificationLink}
+          handleCloseNotification={() => {
+            setShowNotification(false);
+            localStorage.setItem('showNotification', 'false');
+          }}
+        />
+      )}
       <Routes>
         <Route
           element={