setup project structure: getting ready to build my agents

.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Virtual environments
+.venv
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+
+# IDE related
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local configuration file
+.env
+
+# Other files
+_to_ignore/
+.github/

app.py

@@ -1,196 +1,292 @@
 import os
 import gradio as gr
 import requests
-import inspect
 import pandas as pd
+from manager import Manager
+
 
-# (Keep Constants as is)
 # --- Constants ---
 DEFAULT_API_URL = "https://agents-course-unit4-scoring.hf.space"
+MOCK_SUBMISSION = True
+QUESTIONS_LIMIT = 3
+
+
+class Application:
 
-# --- Basic Agent Definition ---
-# ----- THIS IS WERE YOU CAN BUILD WHAT YOU WANT ------
-class BasicAgent:
     def __init__(self):
-        print("BasicAgent initialized.")
-    def __call__(self, question: str) -> str:
-        print(f"Agent received question (first 50 chars): {question[:50]}...")
-        fixed_answer = "This is a default answer."
-        print(f"Agent returning fixed answer: {fixed_answer}")
-        return fixed_answer
-
-def run_and_submit_all( profile: gr.OAuthProfile | None):
-    """
-    Fetches all questions, runs the BasicAgent on them, submits all answers,
-    and displays the results.
-    """
-    # --- Determine HF Space Runtime URL and Repo URL ---
-    space_id = os.getenv("SPACE_ID") # Get the SPACE_ID for sending link to the code
-
-    if profile:
-        username= f"{profile.username}"
-        print(f"User logged in: {username}")
-    else:
-        print("User not logged in.")
-        return "Please Login to Hugging Face with the button.", None
-
-    api_url = DEFAULT_API_URL
-    questions_url = f"{api_url}/questions"
-    submit_url = f"{api_url}/submit"
-
-    # 1. Instantiate Agent ( modify this part to create your agent)
-    try:
-        agent = BasicAgent()
-    except Exception as e:
-        print(f"Error instantiating agent: {e}")
-        return f"Error initializing agent: {e}", None
-    # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
-    agent_code = f"https://huggingface.co/spaces/{space_id}/tree/main"
-    print(agent_code)
-
-    # 2. Fetch Questions
-    print(f"Fetching questions from: {questions_url}")
-    try:
-        response = requests.get(questions_url, timeout=15)
-        response.raise_for_status()
-        questions_data = response.json()
-        if not questions_data:
-             print("Fetched questions list is empty.")
-             return "Fetched questions list is empty or invalid format.", None
-        print(f"Fetched {len(questions_data)} questions.")
-    except requests.exceptions.RequestException as e:
-        print(f"Error fetching questions: {e}")
-        return f"Error fetching questions: {e}", None
-    except requests.exceptions.JSONDecodeError as e:
-         print(f"Error decoding JSON response from questions endpoint: {e}")
-         print(f"Response text: {response.text[:500]}")
-         return f"Error decoding server response for questions: {e}", None
-    except Exception as e:
-        print(f"An unexpected error occurred fetching questions: {e}")
-        return f"An unexpected error occurred fetching questions: {e}", None
-
-    # 3. Run your Agent
-    results_log = []
-    answers_payload = []
-    print(f"Running agent on {len(questions_data)} questions...")
-    for item in questions_data:
-        task_id = item.get("task_id")
-        question_text = item.get("question")
-        if not task_id or question_text is None:
-            print(f"Skipping item with missing task_id or question: {item}")
-            continue
+        self.space_id = os.getenv("SPACE_ID")
+        self.username = None
+        self.questions_url, self.submit_url = self._get_runtime_and_repo_urls()
+
+    @staticmethod
+    def _get_username(profile: gr.OAuthProfile | None):
+        """Get profile username"""
+        if profile:
+            username= f"{profile.username}"
+            print(f"User logged in: {username}")
+            return username
+        else:
+            print("User not logged in.")
+            return None
+
+    @staticmethod
+    def _get_runtime_and_repo_urls():
+        """Determine HF Space Runtime URL and Repo URL"""
+        api_url = DEFAULT_API_URL
+        questions_url = f"{api_url}/questions"
+        submit_url = f"{api_url}/submit"
+        return questions_url, submit_url
+
+    def _fetch_questions(self):
+        """
+        Fetches questions from `questions_url`.
+
+        Sends a GET request to retrieve and parse questions as JSON. Handles network,
+        JSON decoding, and unexpected errors.
+
+        Returns:
+            tuple: (error_message: str or None, questions: list or None)
+
+        Logs:
+            - Progress, success, empty data, or errors.
+        """
+
+        print(f"Fetching questions from: {self.questions_url}")
         try:
-            submitted_answer = agent(question_text)
-            answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
-            results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+            response = requests.get(self.questions_url, timeout=15)
+            response.raise_for_status()
+            questions_data = response.json()
+            if not questions_data:
+                print("Fetched questions list is empty.")
+                return "Fetched questions list is empty or invalid format.", None
+            print(f"Fetched {len(questions_data)} questions.")
+        except requests.exceptions.RequestException as e:
+            print(f"Error fetching questions: {e}")
+            return f"Error fetching questions: {e}", None
+        except requests.exceptions.JSONDecodeError as e:
+            print(f"Error decoding JSON response from questions endpoint: {e}")
+            print(f"Response text: {response.text[:500]}")
+            return f"Error decoding server response for questions: {e}", None
         except Exception as e:
-             print(f"Error running agent on task {task_id}: {e}")
-             results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": f"AGENT ERROR: {e}"})
-
-    if not answers_payload:
-        print("Agent did not produce any answers to submit.")
-        return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
-
-    # 4. Prepare Submission 
-    submission_data = {"username": username.strip(), "agent_code": agent_code, "answers": answers_payload}
-    status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{username}'..."
-    print(status_update)
-
-    # 5. Submit
-    print(f"Submitting {len(answers_payload)} answers to: {submit_url}")
-    try:
-        response = requests.post(submit_url, json=submission_data, timeout=60)
-        response.raise_for_status()
-        result_data = response.json()
-        final_status = (
-            f"Submission Successful!\n"
-            f"User: {result_data.get('username')}\n"
-            f"Overall Score: {result_data.get('score', 'N/A')}% "
-            f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n"
-            f"Message: {result_data.get('message', 'No message received.')}"
-        )
-        print("Submission successful.")
-        results_df = pd.DataFrame(results_log)
-        return final_status, results_df
-    except requests.exceptions.HTTPError as e:
-        error_detail = f"Server responded with status {e.response.status_code}."
-        try:
-            error_json = e.response.json()
-            error_detail += f" Detail: {error_json.get('detail', e.response.text)}"
-        except requests.exceptions.JSONDecodeError:
-            error_detail += f" Response: {e.response.text[:500]}"
-        status_message = f"Submission Failed: {error_detail}"
-        print(status_message)
-        results_df = pd.DataFrame(results_log)
-        return status_message, results_df
-    except requests.exceptions.Timeout:
-        status_message = "Submission Failed: The request timed out."
-        print(status_message)
-        results_df = pd.DataFrame(results_log)
-        return status_message, results_df
-    except requests.exceptions.RequestException as e:
-        status_message = f"Submission Failed: Network error - {e}"
-        print(status_message)
-        results_df = pd.DataFrame(results_log)
-        return status_message, results_df
-    except Exception as e:
-        status_message = f"An unexpected error occurred during submission: {e}"
-        print(status_message)
-        results_df = pd.DataFrame(results_log)
-        return status_message, results_df
+            print(f"An unexpected error occurred fetching questions: {e}")
+            return f"An unexpected error occurred fetching questions: {e}", None
+        return questions_data
+
+    @staticmethod
+    async def _run_agent(questions_data, agent):
+        """
+        Runs the agent on a list of questions and collects results.
+
+        Args:
+            questions_data (list): List of question dictionaries with "task_id" and "question".
+            agent (callable): Callable that processes a question and returns an answer.
+
+        Returns:
+            tuple: 
+            - results_log (list): Logs with "Task ID", "Question", and "Submitted Answer".
+            - answers_payload (list): Payload with "task_id" and "submitted_answer".
+        """
+        if QUESTIONS_LIMIT > 0:
+            questions_data = questions_data[:QUESTIONS_LIMIT]
 
+        results_log = []
+        answers_payload = []
+        print(f"Running agent on {len(questions_data)} questions...")
+        for item in questions_data:
+            task_id = item.get("task_id")
+            question_text = item.get("question")
+            if not task_id or question_text is None:
+                print(f"Skipping item with missing task_id or question: {item}")
+                continue
+            try:
+                submitted_answer = await agent(question_text)
+                print(f"SUBMITED_ANSWER: {submitted_answer}")
+                answers_payload.append({"task_id": task_id, "submitted_answer": submitted_answer})
+                results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": submitted_answer})
+            except Exception as e:
+                print(f"Error running agent on task {task_id}: {e}")
+                results_log.append({"Task ID": task_id, "Question": question_text, "Submitted Answer": f"AGENT ERROR: {e}"})
+        return results_log, answers_payload
 
-# --- Build Gradio Interface using Blocks ---
-with gr.Blocks() as demo:
-    gr.Markdown("# Basic Agent Evaluation Runner")
-    gr.Markdown(
+    def _submit(self, answers_payload, submission_data, results_log):
         """
-        **Instructions:**
+        Submits answers to the specified URL and processes the response.
+
+        Args:
+            answers_payload (list): List of answers to submit.
+            submission_data (dict): Payload for the POST request.
+            results_log (list): Log of results to convert into a DataFrame.
+
+        Returns:
+            tuple: (status_message (str), results_df (pd.DataFrame)).
 
-        1.  Please clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc ...
-        2.  Log in to your Hugging Face account using the button below. This uses your HF username for submission.
-        3.  Click 'Run Evaluation & Submit All Answers' to fetch questions, run your agent, submit answers, and see the score.
+        Notes:
+            - Sends a POST request to `self.submit_url` with `submission_data`.
+            - Handles exceptions and provides error messages.
+        """
+        print(f"Submitting {len(answers_payload)} answers to: {self.submit_url}")
+        try:
+            if MOCK_SUBMISSION:
+                mock_response = type('MockResponse', (), {
+                    'status_code': 200,
+                    'json': lambda *args: {
+                        "username": self.username,
+                        "score": 100,
+                        "correct_count": len(answers_payload),
+                        "total_attempted": len(answers_payload),
+                        "message": "Mock submission successful."
+                    }
+                })
+                response = mock_response()
+            else:
+                response = requests.post(self.submit_url, json=submission_data, timeout=60)
+                response.raise_for_status()
+            result_data = response.json()
+            final_status = (
+                f"Submission Successful!\n"
+                f"User: {result_data.get('username')}\n"
+                f"Overall Score: {result_data.get('score', 'N/A')}% "
+                f"({result_data.get('correct_count', '?')}/{result_data.get('total_attempted', '?')} correct)\n"
+                f"Message: {result_data.get('message', 'No message received.')}"
+            )
+            print("Submission successful.")
+            results_df = pd.DataFrame(results_log)
+            return final_status, results_df
+        except requests.exceptions.HTTPError as e:
+            error_detail = f"Server responded with status {e.response.status_code}."
+            try:
+                error_json = e.response.json()
+                error_detail += f" Detail: {error_json.get('detail', e.response.text)}"
+            except requests.exceptions.JSONDecodeError:
+                error_detail += f" Response: {e.response.text[:500]}"
+            status_message = f"Submission Failed: {error_detail}"
+            print(status_message)
+            results_df = pd.DataFrame(results_log)
+            return status_message, results_df
+        except requests.exceptions.Timeout:
+            status_message = "Submission Failed: The request timed out."
+            print(status_message)
+            results_df = pd.DataFrame(results_log)
+            return status_message, results_df
+        except requests.exceptions.RequestException as e:
+            status_message = f"Submission Failed: Network error - {e}"
+            print(status_message)
+            results_df = pd.DataFrame(results_log)
+            return status_message, results_df
+        except Exception as e:
+            status_message = f"An unexpected error occurred during submission: {e}"
+            print(status_message)
+            results_df = pd.DataFrame(results_log)
+            return status_message, results_df
 
-        ---
-        **Disclaimers:**
-        Once clicking on the "submit button, it can take quite some time ( this is the time for the agent to go through all the questions).
-        This space provides a basic setup and is intentionally sub-optimal to encourage you to develop your own, more robust solution. For instance for the delay process of the submit button, a solution could be to cache the answers and submit in a seperate action or even to answer the questions in async.
+    async def eval_and_submit_all(self, profile: gr.OAuthProfile | None):
+        """
+        Fetches all questions, runs the agent on them, submits all answers,
+        and displays the results.
         """
-    )
+        self.username = self._get_username(profile)
+        if self.username is None:
+            return "Please Login to Hugging Face with the button.", None
+
+        # 1. Instantiate the Main Agent
+        try:
+            agent = Manager()
+        except Exception as e:
+            print(f"Error instantiating agent: {e}")
+            return f"Error initializing agent: {e}", None
+        # In the case of an app running as a hugging Face space, this link points toward your codebase ( usefull for others so please keep it public)
+        agent_code = f"https://huggingface.co/spaces/{self.space_id}/tree/main"
+        print(agent_code)
+
+        # 2. Fetch Questions
+        questions_data = self._fetch_questions()
+
+        # 3. Run your Agent
+        results_log, answers_payload = await self._run_agent(questions_data, agent)
+
+        if not answers_payload:
+            print("Agent did not produce any answers to submit.")
+            return "Agent did not produce any answers to submit.", pd.DataFrame(results_log)
+
+        # 4. Prepare Submission 
+        submission_data = {"username": self.username.strip(), "agent_code": agent_code, "answers": answers_payload}
+        status_update = f"Agent finished. Submitting {len(answers_payload)} answers for user '{self.username}'..."
+        print(status_update)
+
+        # 5. Submit
+        status_message, results_df = self._submit(answers_payload, submission_data, results_log)
+        return status_message, results_df
 
-    gr.LoginButton()
 
-    run_button = gr.Button("Run Evaluation & Submit All Answers")
+class UI:
 
-    status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
-    # Removed max_rows=10 from DataFrame constructor
-    results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
+    app = Application()
+
+    @classmethod
+    def _check_space_host_and_id(cls):
+        """Check for SPACE_HOST and SPACE_ID at startup for information"""
+        space_host_startup = os.getenv("SPACE_HOST")
+        space_id_startup = os.getenv("SPACE_ID") # Get SPACE_ID at startup
+
+        if space_host_startup:
+            print(f"✅ SPACE_HOST found: {space_host_startup}")
+            print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
+        else:
+            print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
+
+        # Print repo URLs if SPACE_ID is found
+        if space_id_startup:
+            print(f"✅ SPACE_ID found: {space_id_startup}")
+            print(f"   Repo URL: https://huggingface.co/spaces/{space_id_startup}")
+            print(f"   Repo Tree URL: https://huggingface.co/spaces/{space_id_startup}/tree/main")
+        else:
+            print("ℹ️  SPACE_ID environment variable not found (running locally?). Repo URL cannot be determined.")
+
+    @classmethod
+    def _build(cls):
+        gr.Markdown("# Main Agent Evaluation Runner")
+        gr.Markdown(
+            """
+            **Instructions:**
+
+            1.  Please clone this space, then modify the code to define your agent's logic, the tools, the necessary packages, etc ...
+            2.  Log in to your Hugging Face account using the button below. This uses your HF username for submission.
+            3.  Click 'Run Evaluation & Submit All Answers' to fetch questions, run your agent, submit answers, and see the score.
+
+            ---
+            **Disclaimers:**
+            Once clicking on the "submit button, it can take quite some time ( this is the time for the agent to go through all the questions).
+            This space provides a basic setup and is intentionally sub-optimal to encourage you to develop your own, more robust solution. For instance for the delay process of the submit button, a solution could be to cache the answers and submit in a seperate action or even to answer the questions in async.
+            """
+        )
+
+        gr.LoginButton()
+
+        run_button = gr.Button("Run Evaluation & Submit All Answers")
+
+        status_output = gr.Textbox(label="Run Status / Submission Result", lines=5, interactive=False)
+        # Removed max_rows=10 from DataFrame constructor
+        results_table = gr.DataFrame(label="Questions and Agent Answers", wrap=True)
+
+        run_button.click(
+            fn=cls.app.eval_and_submit_all,
+            outputs=[status_output, results_table]
+        )
 
-    run_button.click(
-        fn=run_and_submit_all,
-        outputs=[status_output, results_table]
-    )
+    @classmethod
+    def launch(cls):
+        """Build Gradio Interface using Blocks"""
+        with gr.Blocks() as demo:
+            cls._build()
 
-if __name__ == "__main__":
-    print("\n" + "-"*30 + " App Starting " + "-"*30)
-    # Check for SPACE_HOST and SPACE_ID at startup for information
-    space_host_startup = os.getenv("SPACE_HOST")
-    space_id_startup = os.getenv("SPACE_ID") # Get SPACE_ID at startup
+        if __name__ == "__main__":
+            print("\n" + "-"*30 + " App Starting " + "-"*30)
+            cls._check_space_host_and_id()
 
-    if space_host_startup:
-        print(f"✅ SPACE_HOST found: {space_host_startup}")
-        print(f"   Runtime URL should be: https://{space_host_startup}.hf.space")
-    else:
-        print("ℹ️  SPACE_HOST environment variable not found (running locally?).")
+            print("-"*(60 + len(" App Starting ")) + "\n")
 
-    if space_id_startup: # Print repo URLs if SPACE_ID is found
-        print(f"✅ SPACE_ID found: {space_id_startup}")
-        print(f"   Repo URL: https://huggingface.co/spaces/{space_id_startup}")
-        print(f"   Repo Tree URL: https://huggingface.co/spaces/{space_id_startup}/tree/main")
-    else:
-        print("ℹ️  SPACE_ID environment variable not found (running locally?). Repo URL cannot be determined.")
+            print("Launching Gradio Interface for Main Agent Evaluation...")
+            demo.launch(debug=True, share=False)
 
-    print("-"*(60 + len(" App Starting ")) + "\n")
 
-    print("Launching Gradio Interface for Basic Agent Evaluation...")
-    demo.launch(debug=True, share=False)
+UI.launch()

args.py

@@ -0,0 +1,17 @@
+
+from enum import Enum
+
+
+class InterfaceChoice(Enum):
+    HUGGINGFACE = "HuggingFace"
+    OPENAILIKE = "OpenAILike"
+    OPENAI = "OpenAI"
+    # Add your own if you like (then adjust the LLMFactory)
+
+
+class Args:
+    INTERFACE = InterfaceChoice.OPENAILIKE
+    model_name="Qwen/Qwen2.5-Coder-32B-Instruct"
+    api_base="http://127.0.0.1:1234/v1"  # LM Studio local endpoint
+    api_key="api_key"
+    token = ""  # Not needed when using OpenAILike API

diagrams/diagram.puml

@@ -0,0 +1,87 @@
+@startuml
+
+!include style.puml
+
+' left to right direction
+
+' Hide the class indicators (C)
+hide circle
+hide empty members
+
+' Agent Definitions (Use class notation for agents with tools as fields)
+
+
+class "Ambassador" as Ambassador <<M>> {
+}
+
+class "Manager" as Manager <<M>> {
+    - Solver() {trivial task}
+    - Manager() {complex task}
+}
+
+class "Solver" as Solver {
+    - Researcher()
+    - EncryptionExpert()
+    - MathExpert()
+    - Reasoner()
+    - ImageHandler()
+    - VideoHandler()
+}
+
+class "Researcher" as Researcher {
+    + DuckDuckGoSearchToolSpec
+}
+
+class "EncryptionExpert" as EncryptionExpert {
+    + ASCII Encode
+    + ASCII Decode
+    + ChrToInt Encode
+    + ChrToInt Decode
+    + Base64 Encode
+    + Base64 Decode
+    + Caesar Cipher Encode
+    + Caesar Cipher Decode
+    + Caesar Cipher Brute Force
+    + Reverse String
+    - MathExpert()
+    - Reasoner()
+}
+
+class "MathExpert" as MathExpert {
+    + Symbolic Math Calculator
+    + Unit Converter
+    - Reasoner()
+}
+
+class "Reasoner" as Reasoner {
+}
+
+class "ImageHandler" as ImageHandler {
+}
+
+class "VideoHandler" as VideoHandler {
+}
+
+' Agent-to-Agent Connections
+Query --> Ambassador
+Ambassador --> Manager : request
+Manager --> Ambassador : solution
+Ambassador --> Final_Answer : problem solved
+
+Manager ..> Manager : complex task
+Manager ..> Solver : trivial task
+Solver ..> Manager : solution
+
+Solver .. Researcher : query
+Solver .. EncryptionExpert : query
+Solver .. MathExpert : query
+Solver .. Reasoner : query
+Solver .. ImageHandler : query
+Solver .. VideoHandler : query
+
+EncryptionExpert .. MathExpert : query
+EncryptionExpert .. Reasoner : query
+MathExpert .. Reasoner : query
+
+
+@enduml

diagrams/style.puml

@@ -0,0 +1,7 @@
+skinparam class {
+    BackgroundColor #E0F7FA
+    BorderColor #D84315
+    FontColor #E65100
+    FontStyle bold
+    HeaderBackgroundColor #FFE0B2
+}

llm_factory.py

@@ -0,0 +1,70 @@
+from llama_index.llms.openai_like import OpenAILike
+from llama_index.llms.openai import OpenAI
+from llama_index.llms.huggingface_api import HuggingFaceInferenceAPI
+from args import InterfaceChoice, Args
+
+
+class LLMFactory():
+
+    @classmethod
+    def create(cls, system_prompt, temperature = None, max_tokens = None):
+        if Args.INTERFACE == InterfaceChoice.OPENAILIKE:
+            return cls._openailike_create(system_prompt, temperature, max_tokens)
+        elif Args.INTERFACE == InterfaceChoice.OPENAI:
+            return cls._openai_create(system_prompt, temperature, max_tokens)
+        elif Args.INTERFACE == InterfaceChoice.HUGGINGFACE:
+            return cls._hf_create(system_prompt, temperature, max_tokens)
+        else:
+            raise ValueError(f"Invalid interface choice: {Args.INTERFACE}")
+
+    @staticmethod
+    def _openailike_create(system_prompt, temperature=None, max_tokens=None):
+        kwargs = {
+            "model": Args.model_name,
+            "api_base": Args.api_base,
+            "api_key": Args.api_key,
+            "system_prompt": system_prompt,
+        }
+
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        llm = OpenAILike(**kwargs)
+        return llm
+
+    @staticmethod
+    def _openai_create(system_prompt, temperature = None, max_tokens = None):
+        kwargs = {
+            "model": Args.model_name,
+            "api_key": Args.api_key,
+            "system_prompt": system_prompt,
+        }
+
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        llm = OpenAI(**kwargs)
+        return llm
+
+    @staticmethod
+    def _hf_create(system_prompt, temperature = None, max_tokens = None):
+        kwargs = {
+            "model_name": Args.model_name,
+            "system_prompt": system_prompt,
+            "token": Args.token,
+        }
+
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+
+        if max_tokens is not None:
+            kwargs["max_tokens"] = max_tokens
+
+        llm = HuggingFaceInferenceAPI(**kwargs)
+        return llm

manager.py

@@ -0,0 +1,32 @@
+import asyncio
+import os
+from llm_factory import LLMFactory
+
+
+# TODO: Langgraph graph that process the following:
+# 1. Thakes the Query Node (Start Node) and sends it to the Assistant Node (has memory - access to the conversation hystory stored in the State)
+# 2. The Assistant Node decides whether the querry is ready to be delivered (the solution is available in the conversation hystory, or the `MAX_DEPTH` has been reached)
+#   - if yes: formulates a concise final answer and sends it to the Final_Answer Node (End Node)
+#   - if no: formulates a querry (could be the first one or a follow-up) and sends it to the Manager Node (also has access to the conversation hystory)
+#       (!) This communication happens back and forth until the querry gets solved (or up to a maximum depth defined by a `MAX_DEPTH` variable)
+
+
+class Manager:
+
+    def __init__(self):
+        print("Agent initialized.")
+
+    async def __call__(self, question: str) -> str:
+        print(f"Agent received question (first 50 chars): {question[:50]}...")
+        self.final_answer = ""
+        response = await self.query(question)
+        print(f"Agent processed the response: {response}")
+        return response
+    
+    async def query(self, question: str) -> str:
+        # TODO
+        pass
+
+
+if __name__ == "__main__":
+    print("---__main__---")

requirements.txt

@@ -1,2 +1,13 @@
 gradio
-requests
+gradio[oauth]
+requests
+openai
+IPython
+langgraph
+llama_index
+llama-index-llms-huggingface-api
+llama-index-embeddings-huggingface
+llama-index-llms-openai
+llama-index-llms-openai-like
+llama-index-tools-duckduckgo
+pint

solver.py

@@ -0,0 +1,165 @@
+from llama_index.core.agent.workflow import AgentWorkflow
+from llama_index.core.tools import FunctionTool
+from llama_index.core.workflow import Context
+import asyncio
+import os
+from llm_factory import LLMFactory
+from toolbox import Toolbox
+
+
+class MathExpert:
+
+    def __init__(self, temperature, max_tokens):
+        system_prompt_path = os.path.join(os.getcwd(), "system_prompts", "06_math_expert.txt")
+        self.system_prompt = ""
+        with open(system_prompt_path, "r") as file:
+            self.system_prompt = file.read().strip()
+        llm = LLMFactory.create(self.system_prompt, temperature, max_tokens)
+        self.agent = AgentWorkflow.from_tools_or_functions(
+            [
+            Toolbox.math.symbolic_calc,
+            Toolbox.math.unit_converter,
+            ],
+            llm=llm
+        )
+        self.ctx = Context(self.agent)
+    
+    def get_system_prompt(self):
+        return self.system_prompt
+
+    async def query(self, question: str) -> str:
+        response = await self.agent.run(question, ctx=self.ctx)
+        response = str(response)
+        return response
+
+
+class Researcher:
+    def __init__(self, temperature, max_tokens):
+        system_prompt_path = os.path.join(os.getcwd(), "system_prompts", "04_researcher.txt")
+        self.system_prompt = ""
+        with open(system_prompt_path, "r") as file:
+            self.system_prompt = file.read().strip()
+        llm = LLMFactory.create(self.system_prompt, temperature, max_tokens)
+        
+        self.agent = AgentWorkflow.from_tools_or_functions(
+            Toolbox.web_search.duck_duck_go_tools,
+            llm=llm
+        )
+        self.ctx = Context(self.agent)
+    
+    def get_system_prompt(self):
+        return self.system_prompt
+
+    async def query(self, question: str) -> str:
+        response = await self.agent.run(question, ctx=self.ctx)
+        response = str(response)
+        return response
+
+
+class EncryptionExpert:
+    def __init__(self, temperature, max_tokens):
+        system_prompt_path = os.path.join(os.getcwd(), "system_prompts", "05_encryption_expert.txt")
+        self.system_prompt = ""
+        with open(system_prompt_path, "r") as file:
+            self.system_prompt = file.read().strip()
+        llm = LLMFactory.create(self.system_prompt, temperature, max_tokens)
+        
+        self.agent = AgentWorkflow.from_tools_or_functions(
+            [
+                Toolbox.encryption.base64_encode,
+                Toolbox.encryption.base64_decode,
+                Toolbox.encryption.caesar_cipher_encode,
+                Toolbox.encryption.caesar_cipher_decode,
+                Toolbox.encryption.reverse_string
+            ],
+            llm=llm
+        )
+        self.ctx = Context(self.agent)
+    
+    def get_system_prompt(self):
+        return self.system_prompt
+
+    async def query(self, question: str) -> str:
+        response = await self.agent.run(question, ctx=self.ctx)
+        response = str(response)
+        return response
+
+
+class ImageHandler:
+    pass
+
+class VideoHandler:
+    pass
+
+class RecursiveSolverAgent:
+    pass
+
+
+class Solver:
+
+    def __init__(self, temperature, max_tokens):
+        print("Agent initialized.")
+        system_prompt_path = os.path.join(os.getcwd(), "system_prompts", "01_assistant.txt")
+        self.system_prompt = ""
+        with open(system_prompt_path, "r") as file:
+            self.system_prompt = file.read().strip()
+        llm = LLMFactory.create(self.system_prompt, temperature, max_tokens)
+        self.agent = AgentWorkflow.from_tools_or_functions(
+            [
+            FunctionTool.from_defaults(self.delegate_to_math_expert),
+            FunctionTool.from_defaults(self.set_final_answer)
+            ],
+            llm=llm
+        )
+        self.ctx = Context(self.agent)
+        self.final_answer = ""
+
+    async def __call__(self, question: str) -> str:
+        print(f"Agent received question (first 50 chars): {question[:50]}...")
+        self.final_answer = ""
+        response = await self.query(question)
+        print(f"Agent processed the response: {response}")
+        if self.final_answer == "":
+            response = await self.query("I noticed the final_answer is an empty string. Have you forgot to set the final_answer ?")
+        return self.final_answer
+
+    def get_system_prompt(self):
+        return self.system_prompt
+    
+    async def query(self, question: str) -> str:
+        response = await self.agent.run(question, ctx=self.ctx)
+        response = str(response)
+
+        final_answer = response
+
+        self.set_final_answer(final_answer)
+        return response
+    
+    def set_final_answer(self, final_answer: str) -> str:
+        """
+        Sets the final answer for the current querry.
+
+        Args:
+            final_answer (str): The final answer to be set for the agent.
+
+        Returns:
+            str: The final answer that was set.
+        """
+        print("-> set_final_answer !")
+        self.final_answer = final_answer
+    
+    def delegate_to_math_expert(self, question: str) -> str:
+        print("-> delegated to math agent !")
+        math_agent = MathExpert(temperature=0.7, max_tokens=100)
+        return math_agent.query(question)
+
+
+if __name__ == "__main__":
+    encryption_agent = EncryptionExpert(temperature=0.7, max_tokens=2000)
+    # encryption_query = "Descifer this: 'Bmfy bfx ymj wjxzqy gjybjjs z-hqzo fsi zsnajwxnyfyjf-hwfntaf ns fuwnq 2025 ?'"
+    encryption_query = ".rewsna eht sa ""tfel"" drow eht fo etisoppo eht etirw ,ecnetnes siht dnatsrednu uoy fI"
+    # print(encryption_agent.get_system_prompt())
+    # encoding = encryption_agent.caesar_cipher_encode(encryption_query, 5)
+    # print(encoding)
+    # print(encryption_agent.caesar_cipher_decode(encoding, 5))
+    print(asyncio.run(encryption_agent.query(encryption_query)))

system_prompts/01_assistant.txt

@@ -0,0 +1 @@
+You are a powerful manager assistant. Please respond concisely and accurately.

system_prompts/02_manager.txt

@@ -0,0 +1 @@
+You are a powerful manager assistant. Please respond concisely and accurately.

system_prompts/04_researcher.txt

@@ -0,0 +1,31 @@
+You are a specialized search agent with the capability to search the web for current information.
+
+Your goal is to provide accurate, up-to-date information from the web in response to user queries.
+
+You have access to the DuckDuckGo search tool that allows you to perform web searches to find information.
+
+When responding to questions:
+- Determine if the query requires searching the web for current information
+- Use the DuckDuckGo search tool to find relevant information
+- Summarize and synthesize the information you find from search results
+- Always cite your sources by mentioning where the information came from
+- If the search results don't provide useful information, acknowledge this and explain why
+- Provide a comprehensive answer that directly addresses the query
+
+If your initial search doesn't yield satisfactory results:
+- Reformulate your search query using different keywords or phrasings
+- Try more specific queries if initial results are too general
+- Try broader queries if specific searches don't return results
+- Consider breaking complex queries into simpler sub-queries
+- Attempt at least 2-3 different search formulations before concluding information isn't available
+- Explain your search strategy and how you're refining your approach
+
+When reformulating searches:
+- Remove or replace jargon with more common terms
+- Include alternative terminology or synonyms
+- Add qualifiers like "latest," "recent," "explained," or "overview" as appropriate
+- Consider searching for specific time periods if date-sensitive information is needed
+
+Only use the search tool when appropriate. For simple questions or queries not requiring web information, respond directly without using the tool.
+
+Be persistent in your search efforts. Your goal is to provide the most accurate and helpful information possible to the user.

system_prompts/05_encryption_expert.txt

@@ -0,0 +1,69 @@
+You are an encryption and decryption specialist assistant. Your goal is to help users encode or decode messages using various encryption techniques.
+
+Your capabilities include:
+1. Base64 encoding and decoding
+2. Caesar cipher encryption and decryption (with customizable shift values)
+3. String reversal
+
+DECRYPTION STRATEGY GUIDE:
+When asked to decrypt or decipher an unknown message:
+
+1. PATTERN RECOGNITION & REASONING APPROACH:
+   - First, analyze the encrypted text to identify patterns
+   - For potential Caesar ciphers:
+     * Look for preserved patterns (punctuation, numbers, spaces)
+     * Identify preserved word structure (short words may be "a", "an", "the", "and", etc.)
+     * Use frequency analysis - in English, 'e', 't', 'a', 'o', 'i', 'n' are most common letters
+   - Map several possible words to determine the rule/shift being applied
+   - Once you identify a potential rule, TEST it on several words
+   - Develop a hypothesis about what encryption was used and test it systematically
+
+2. For Caesar cipher (most common scenario):
+   - When no shift is specified, PERFORM SYSTEMATIC TESTING of shifts:
+     * Try common shifts first: 13, 3, 5, 7, 1, 25
+     * If those fail, methodically try every shift from 1 to 25
+     * For each shift, evaluate if the output contains recognizable English words
+     * Test at least 5-10 different shifts before concluding
+   - FREQUENCY ANALYSIS: Look for recurring letters and match to common English frequencies
+   - WORD PATTERN ANALYSIS: Common 2-3 letter words (is, in, at, the, and) can indicate correct decryption
+
+3. For encoded messages:
+   - First check for base64 indicators (character set A-Z, a-z, 0-9, +, /, =)
+   - Check for padding characters (=) at the end which often indicate base64
+
+4. For reversed text:
+   - Check if reversing produces readable text
+
+5. For combined encryption:
+   - Try decrypting using one method, then apply another
+
+DEBUGGING AND REASONING PROCESS:
+- Show your work by explaining what you're trying
+- For each Caesar shift attempt, show a sample of the output
+- Compare partial results against known English words
+- Consider if you're seeing partial success (some words readable but others not)
+- If you find readable segments, expand from there
+
+EXAMPLES WITH REASONING:
+
+Example 1: "Ifmmp xpsme"
+Reasoning: Looking at the pattern, it appears to be a short phrase. Testing Caesar shift 1:
+I → H, f → e, m → l, m → l, p → o...
+Result: "Hello world" - This makes sense, so shift 1 is correct.
+
+Example 2: "Xlmw mw e wivmicw tlvewi"
+Reasoning: Testing shift 4:
+X → T, l → h, m → i, w → s...
+Result: "This is a serious phrase" - Correctly decoded with shift 4.
+
+Example 3: "What was the result between u-cluj and universitatea-craiova in april 2025?"
+If encrypted with shift 5:
+"Bmfy bfx ymj wjxzqy gjybjjs z-hqzo fsi zsnajwxnyfyjf-hwfntaf ns fuwnq 2025?"
+Reasoning to decrypt:
+- Notice numbers and punctuation are preserved (common in Caesar cipher)
+- Try different shifts:
+  With shift 5: "What was the result between u-cluj and universitatea-craiova in april 2025?"
+  This produces readable English with proper grammar and preserved patterns.
+
+Never give up after a single attempt. If one approach doesn't work, try another systematically.
+For ANY cipher, show your reasoning and demonstrate multiple decryption attempts.

system_prompts/06_math_expert.txt

@@ -0,0 +1,87 @@
+You are a mathematical problem solver with access to two specialized tools:
+
+1. SYMBOLIC_MATH_CALCULATOR: For all mathematical computations
+2. UNIT_CONVERTER: ONLY for unit conversions between measurement systems
+
+MANDATORY PROTOCOL:
+- You have NO calculation abilities of your own
+- ALWAYS use symbolic_math_calculator for ANY mathematical operation
+- ONLY use unit_converter for converting between physical units (e.g., meters to feet)
+- NEVER state mathematical results unless directly produced by a tool
+
+CRITICAL THINKING FRAMEWORK:
+
+STEP-BY-STEP REASONING (MANDATORY):
+1. ANALYZE: Define what is known and unknown precisely
+2. PLAN: Outline a logical solution strategy before making tool calls
+3. EXECUTE: Implement each step with a specific tool call
+4. VERIFY: Confirm results through independent calculations
+5. INTERPRET: Explain the mathematical meaning of the results
+
+AGGRESSIVE ERROR RECOVERY (CRITICAL):
+- If a tool call returns an error, IMMEDIATELY try alternative syntax
+- NEVER give up after a single failed attempt
+- Try at least 3 different syntax variations before considering an approach failed
+- For each error, diagnose the likely cause and adjust accordingly
+- PERSIST with different approaches until you get a result or exhaust all reasonable options
+
+ERROR HANDLING STRATEGIES:
+1. Fix syntax: Correct parentheses, function names, argument order
+2. Try alternative function: replace "integrate" with "Integral", "simplify" with "expand"
+3. Break expression into parts: Solve simpler components first
+4. Use different representation: Convert to different form (polar, exponential)
+5. Apply mathematical identities: Transform using known equivalences
+
+SYMBOLIC MATH CALCULATOR STRATEGIES:
+
+FOR CHALLENGING INTEGRALS:
+1. Try direct computation:
+   symbolic_math_calculator("integrate(log(sin(x)), (x, 0, pi/2))")
+   
+2. If that fails, try AGGRESSIVELY:
+   - Alternative syntax: symbolic_math_calculator("Integral(log(sin(x)), (x, 0, pi/2)).doit()")
+   - Known result: symbolic_math_calculator("-pi*log(2)/2")
+   - Numerical approach: symbolic_math_calculator("N(integrate(log(sin(x)), (x, 0, pi/2)), 10)")
+   - Series expansion: symbolic_math_calculator("series(log(sin(x)), x, 0, 10).integrate(x).subs(x, pi/2)")
+   - Integration by parts: Break into multiple steps
+
+FOR EQUATIONS:
+1. Direct solving: symbolic_math_calculator("solve(x**2 - 5*x + 6, x)")
+2. If that fails, try AGGRESSIVELY:
+   - symbolic_math_calculator("solveset(x**2 - 5*x + 6, x)")
+   - symbolic_math_calculator("roots(x**2 - 5*x + 6, x)")
+   - symbolic_math_calculator("factor(x**2 - 5*x + 6)")
+   - symbolic_math_calculator("solve(x**2 - 5*x + 6 == 0, x)")
+
+UNIT CONVERTER EXAMPLES:
+1. Length: unit_converter(value=100, from_unit="cm", to_unit="inch")
+2. Mass: unit_converter(value=5, from_unit="kg", to_unit="pound")
+3. Temperature: unit_converter(value=32, from_unit="fahrenheit", to_unit="celsius")
+4. Speed: unit_converter(value=60, from_unit="mph", to_unit="km/h")
+5. Volume: unit_converter(value=1, from_unit="gallon", to_unit="liter")
+
+DO NOT use unit_converter for mathematical expressions or calculations.
+
+LOGICAL VALIDATION FRAMEWORK (MANDATORY):
+1. CHECK ASSUMPTIONS: Explicitly state all assumptions made
+2. IDENTIFY CONSTRAINTS: List all constraints and boundary conditions
+3. VERIFY DOMAIN: Ensure solutions exist within required domain
+4. TEST EDGE CASES: Verify solution at boundaries and special cases
+5. CONSISTENCY CHECK: Ensure all results align with mathematical principles
+
+VERIFICATION METHODS (USE AT LEAST TWO):
+- Substitute solutions back into original equations
+- Check derivatives of antiderivatives
+- Calculate using alternative methods
+- Test with specific numerical values
+- Apply mathematical identities to verify equivalence
+
+RESPONSE STRUCTURE:
+1. PROBLEM ANALYSIS: Define problem, identify knowns/unknowns, constraints
+2. SOLUTION STRATEGY: Outline logical approach before executing
+3. STEP-BY-STEP EXECUTION: Show each tool call with clear purpose
+4. VERIFICATION: Demonstrate at least two verification methods
+5. INTERPRETATION: Explain mathematical meaning of results
+6. CONCLUSION: Present final answer with appropriate precision/units
+
+Only present conclusions directly supported by tool outputs. Use sound mathematical logic at each step, and NEVER give up after initial failed attempts.

system_prompts/07_reasoner.txt

@@ -0,0 +1,87 @@
+You are a mathematical problem solver with access to two specialized tools:
+
+1. SYMBOLIC_MATH_CALCULATOR: For all mathematical computations
+2. UNIT_CONVERTER: ONLY for unit conversions between measurement systems
+
+MANDATORY PROTOCOL:
+- You have NO calculation abilities of your own
+- ALWAYS use symbolic_math_calculator for ANY mathematical operation
+- ONLY use unit_converter for converting between physical units (e.g., meters to feet)
+- NEVER state mathematical results unless directly produced by a tool
+
+CRITICAL THINKING FRAMEWORK:
+
+STEP-BY-STEP REASONING (MANDATORY):
+1. ANALYZE: Define what is known and unknown precisely
+2. PLAN: Outline a logical solution strategy before making tool calls
+3. EXECUTE: Implement each step with a specific tool call
+4. VERIFY: Confirm results through independent calculations
+5. INTERPRET: Explain the mathematical meaning of the results
+
+AGGRESSIVE ERROR RECOVERY (CRITICAL):
+- If a tool call returns an error, IMMEDIATELY try alternative syntax
+- NEVER give up after a single failed attempt
+- Try at least 3 different syntax variations before considering an approach failed
+- For each error, diagnose the likely cause and adjust accordingly
+- PERSIST with different approaches until you get a result or exhaust all reasonable options
+
+ERROR HANDLING STRATEGIES:
+1. Fix syntax: Correct parentheses, function names, argument order
+2. Try alternative function: replace "integrate" with "Integral", "simplify" with "expand"
+3. Break expression into parts: Solve simpler components first
+4. Use different representation: Convert to different form (polar, exponential)
+5. Apply mathematical identities: Transform using known equivalences
+
+SYMBOLIC MATH CALCULATOR STRATEGIES:
+
+FOR CHALLENGING INTEGRALS:
+1. Try direct computation:
+   symbolic_math_calculator("integrate(log(sin(x)), (x, 0, pi/2))")
+   
+2. If that fails, try AGGRESSIVELY:
+   - Alternative syntax: symbolic_math_calculator("Integral(log(sin(x)), (x, 0, pi/2)).doit()")
+   - Known result: symbolic_math_calculator("-pi*log(2)/2")
+   - Numerical approach: symbolic_math_calculator("N(integrate(log(sin(x)), (x, 0, pi/2)), 10)")
+   - Series expansion: symbolic_math_calculator("series(log(sin(x)), x, 0, 10).integrate(x).subs(x, pi/2)")
+   - Integration by parts: Break into multiple steps
+
+FOR EQUATIONS:
+1. Direct solving: symbolic_math_calculator("solve(x**2 - 5*x + 6, x)")
+2. If that fails, try AGGRESSIVELY:
+   - symbolic_math_calculator("solveset(x**2 - 5*x + 6, x)")
+   - symbolic_math_calculator("roots(x**2 - 5*x + 6, x)")
+   - symbolic_math_calculator("factor(x**2 - 5*x + 6)")
+   - symbolic_math_calculator("solve(x**2 - 5*x + 6 == 0, x)")
+
+UNIT CONVERTER EXAMPLES:
+1. Length: unit_converter(value=100, from_unit="cm", to_unit="inch")
+2. Mass: unit_converter(value=5, from_unit="kg", to_unit="pound")
+3. Temperature: unit_converter(value=32, from_unit="fahrenheit", to_unit="celsius")
+4. Speed: unit_converter(value=60, from_unit="mph", to_unit="km/h")
+5. Volume: unit_converter(value=1, from_unit="gallon", to_unit="liter")
+
+DO NOT use unit_converter for mathematical expressions or calculations.
+
+LOGICAL VALIDATION FRAMEWORK (MANDATORY):
+1. CHECK ASSUMPTIONS: Explicitly state all assumptions made
+2. IDENTIFY CONSTRAINTS: List all constraints and boundary conditions
+3. VERIFY DOMAIN: Ensure solutions exist within required domain
+4. TEST EDGE CASES: Verify solution at boundaries and special cases
+5. CONSISTENCY CHECK: Ensure all results align with mathematical principles
+
+VERIFICATION METHODS (USE AT LEAST TWO):
+- Substitute solutions back into original equations
+- Check derivatives of antiderivatives
+- Calculate using alternative methods
+- Test with specific numerical values
+- Apply mathematical identities to verify equivalence
+
+RESPONSE STRUCTURE:
+1. PROBLEM ANALYSIS: Define problem, identify knowns/unknowns, constraints
+2. SOLUTION STRATEGY: Outline logical approach before executing
+3. STEP-BY-STEP EXECUTION: Show each tool call with clear purpose
+4. VERIFICATION: Demonstrate at least two verification methods
+5. INTERPRETATION: Explain mathematical meaning of results
+6. CONCLUSION: Present final answer with appropriate precision/units
+
+Only present conclusions directly supported by tool outputs. Use sound mathematical logic at each step, and NEVER give up after initial failed attempts.

system_prompts/08_image_handler.txt

@@ -0,0 +1 @@
+You are a powerful manager assistant. Please respond concisely and accurately.

system_prompts/09_video_handler.txt

@@ -0,0 +1 @@
+You are a powerful manager assistant. Please respond concisely and accurately.

test_agents.py

@@ -0,0 +1,17 @@
+# OUTDATED !
+from agents_stage_2 import MathAgent, MainAgent
+import asyncio
+
+def test_math_agent():
+    math_agent = MathAgent(temperature=0.7, max_tokens=100)
+    print(math_agent.get_system_prompt())
+    asyncio.run(math_agent.query("What is 345 times 281?"))
+
+def test_main_agent():
+    main_agent = MainAgent(temperature=0.7, max_tokens=100)
+    print(main_agent.get_system_prompt())
+    asyncio.run(main_agent.query("What is 345 times 281?"))
+
+if __name__ == "__main__":
+    # test_math_agent()
+    test_main_agent()

toolbox.py

@@ -0,0 +1,212 @@
+import pint
+import sympy as sp
+
+from llama_index.core.tools import FunctionTool
+from llama_index.tools.duckduckgo import DuckDuckGoSearchToolSpec
+
+
+class _Math:
+
+    @staticmethod
+    def symbolic_calc(expression: str) -> str:
+        """
+        Evaluates complex mathematical expressions using SymPy.
+        
+        Args:
+            expression: Mathematical expression as string
+        
+        Returns:
+            Result of the calculation
+        """
+        print(f"-> symbolic_math_calculator tool used (input: {expression}) !")
+        try:
+            result = sp.sympify(expression)
+            print(f"-> (output: {result}) !")
+            return str(result)
+        except Exception as e:
+            return f"Error in calculation: {str(e)}"
+
+    @staticmethod
+    def unit_converter(value: float, from_unit: str, to_unit: str) -> str:
+        """
+        Converts values between different units of measurement.
+        
+        Args:
+            value: The numerical value to convert
+            from_unit: The source unit (e.g., 'meter', 'kg', 'celsius')
+            to_unit: The target unit (e.g., 'feet', 'pound', 'fahrenheit')
+        
+        Returns:
+            The converted value with appropriate units
+        """
+        print(f"-> unit_converter tool used (inputs: [value: {value}, from_unit: {from_unit}, to_unit: {to_unit}]) !")
+        try:
+            # Create unit registry
+            ureg = pint.UnitRegistry()
+            
+            # Create quantity with source unit
+            quantity = value * ureg(from_unit)
+            
+            # Convert to target unit
+            result = quantity.to(to_unit)
+            
+            answer = f"{value} {from_unit} = {result.magnitude} {to_unit}"
+            print(f"-> (output: {result}) !")
+            return answer
+        except Exception as e:
+            return f"Error in unit conversion: {str(e)}"
+
+
+class _MathToolbox:
+    symbolic_calc = FunctionTool.from_defaults(
+        name="symbolic_calc",
+        description="Evaluates complex mathematical expressions using SymPy",
+        fn=_Math.symbolic_calc
+    )
+    unit_converter = FunctionTool.from_defaults(
+        name="unit_converter",
+        description="Converts values between different units of measurement",
+        fn=_Math.unit_converter
+    )
+
+
+class _WebSearchToolbox:
+    duck_duck_go_tools = DuckDuckGoSearchToolSpec().to_tool_list()
+
+
+class _Encryption:
+
+    @staticmethod
+    def base64_encode(text: str) -> str:
+        """
+        Encodes a string to base64.
+        
+        Args:
+            text: The text to encode
+            
+        Returns:
+            Base64 encoded string
+        """
+        print(f"-> base64_encode tool used (input: {text[:30]}...) !")
+        import base64
+        try:
+            encoded_bytes = base64.b64encode(text.encode('utf-8'))
+            encoded_text = encoded_bytes.decode('utf-8')
+            print(f"-> (output: {encoded_text[:30]}...) !")
+            return encoded_text
+        except Exception as e:
+            return f"Error in base64 encoding: {str(e)}"
+    
+    @staticmethod
+    def base64_decode(encoded_text: str) -> str:
+        """
+        Decodes a base64 string to plain text.
+        
+        Args:
+            encoded_text: The base64 encoded text
+            
+        Returns:
+            Decoded string
+        """
+        print(f"-> base64_decode tool used (input: {encoded_text[:30]}...) !")
+        import base64
+        try:
+            decoded_bytes = base64.b64decode(encoded_text)
+            decoded_text = decoded_bytes.decode('utf-8')
+            print(f"-> (output: {decoded_text[:30]}...) !")
+            return decoded_text
+        except Exception as e:
+            return f"Error in base64 decoding: {str(e)}"
+    
+    @staticmethod
+    def caesar_cipher_encode(text: str, shift: int) -> str:
+        """
+        Encodes text using Caesar cipher with specified shift.
+        
+        Args:
+            text: The text to encode
+            shift: Number of positions to shift each character
+            
+        Returns:
+            Caesar cipher encoded string
+        """
+        print(f"-> caesar_cipher_encode tool used (input: {text[:30]}..., shift: {shift}) !")
+        result = ""
+        try:
+            for char in text:
+                if char.isalpha():
+                    ascii_offset = ord('a') if char.islower() else ord('A')
+                    encoded_char = chr((ord(char) - ascii_offset + shift) % 26 + ascii_offset)
+                    result += encoded_char
+                else:
+                    result += char
+            print(f"-> (output: {result[:30]}...) !")
+            return result
+        except Exception as e:
+            return f"Error in Caesar cipher encoding: {str(e)}"
+    
+    @classmethod
+    def caesar_cipher_decode(cls, encoded_text: str, shift: int) -> str:
+        """
+        Decodes Caesar cipher text with specified shift.
+        
+        Args:
+            encoded_text: The encoded text
+            shift: Number of positions the text was shifted
+            
+        Returns:
+            Decoded string
+        """
+        print(f"-> caesar_cipher_decode tool used (input: {encoded_text[:30]}..., shift: {shift}) !")
+        # To decode, we shift in the opposite direction
+        return cls.caesar_cipher_encode(encoded_text, -shift)
+    
+    @staticmethod
+    def reverse_string(text: str) -> str:
+        """
+        Reverses a string.
+        
+        Args:
+            text: The text to reverse
+            
+        Returns:
+            Reversed string
+        """
+        print(f"-> reverse_string tool used (input: {text[:30]}...) !")
+        reversed_text = text[::-1]
+        print(f"-> (output: {reversed_text[:30]}...) !")
+        return reversed_text
+
+
+class _EncryptionToolbox:
+    base64_encode = FunctionTool.from_defaults(
+        name="base64_encode",
+        description="Encode a string to base64",
+        fn=_Encryption.base64_encode
+    )
+    base64_decode = FunctionTool.from_defaults(
+        name="base64_decode",
+        description="Decode a base64 string to plain text",
+        fn=_Encryption.base64_decode
+    )
+    caesar_cipher_encode = FunctionTool.from_defaults(
+        name="caesar_cipher_encode",
+        description="Encode a string using Caesar cipher with specified shift",
+        fn=_Encryption.caesar_cipher_encode
+    )
+    caesar_cipher_decode = FunctionTool.from_defaults(
+        name="caesar_cipher_decode",
+        description="Decode a Caesar cipher string with specified shift",
+        fn=_Encryption.caesar_cipher_decode
+    )
+    reverse_string = FunctionTool.from_defaults(
+        name="reverse_string",
+        description="Reverse a string",
+        fn=_Encryption.reverse_string
+    )
+
+
+class Toolbox:
+    math = _MathToolbox()
+    web_search = _WebSearchToolbox()
+    encryption = _EncryptionToolbox()