Merge pull request #370 from Fosowl/dev

Update readme + contributing.md

README.md

@@ -257,7 +257,7 @@ Start required services. This will start all services from the docker-compose.ym
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Window
+start start_services.cmd full # Window
 ```
 
 **Warning:** This step will download and load all Docker images, which may take up to 30 minutes. After starting the services, please wait until the backend service is fully running (you should see **backend: "GET /health HTTP/1.1" 200 OK** in the log) before sending any messages. The backend services might take 5 minute to start on first run.
@@ -279,7 +279,7 @@ Start services:
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Window
+start start_services.cmd # Window
 ```
 
 Use the CLI: `uv run cli.py`
@@ -645,7 +645,18 @@ We’re looking for developers to improve AgenticSeek! Check out open issues or
 
 [Contribution guide](./docs/CONTRIBUTING.md)
 
-[![Star History Chart](https://api.star-history.com/svg?repos=Fosowl/agenticSeek&type=Date)](https://www.star-history.com/#Fosowl/agenticSeek&Date)
+
+## Sponsors:
+
+Want to level up AgenticSeek capabilities with features like flight search, trip planning, or snagging the best shopping deals? Consider crafting a custom tool with SerpAPI to unlock more Jarvis-like capabilities. With SerpAPI, you can turbocharge your agent for specialized tasks while staying in full control.
+
+<a href="https://serpapi.com/"><img src="./media/banners/sponsor_banner_serpapi.png" height="350" alt="SerpApi Banner" ></a>
+
+See [Contributing.md](./docs/CONTRIBUTING.md) to learn how to integrate custom tools!
+
+### **Patron sponsor**:
+
+- [tatra-labs](https://github.com/tatra-labs)
 
 ## Maintainers:
 
@@ -653,14 +664,8 @@ We’re looking for developers to improve AgenticSeek! Check out open issues or
 
  > [antoineVIVIES](https://github.com/antoineVIVIES) | Taipei Time 
 
- > [steveh8758](https://github.com/steveh8758) | Taipei Time 
-
 ## Special Thanks:
 
  > [tcsenpai](https://github.com/tcsenpai) and [plitc](https://github.com/plitc) For helping with backend dockerization
 
-## Sponsors:
+[![Star History Chart](https://api.star-history.com/svg?repos=Fosowl/agenticSeek&type=Date)](https://www.star-history.com/#Fosowl/agenticSeek&Date)
-
-5$ or more Monthly sponsor appear here:
-- **tatra-labs**
-

README_CHS.md

@@ -220,7 +220,7 @@ provider_server_address = 127.0.0.1:5000 # 无关紧要
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **警告：** 此步骤会下载并加载所有 Docker 镜像，可能需 30 分钟。启动后请等待 backend 服务完全运行（日志中出现 backend: <info>），再发送消息。backend 启动比其他服务慢。
@@ -240,7 +240,7 @@ start ./start_services.cmd full # Windows
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 然后运行：`uv run cli.py`

README_CHT.md

@@ -216,7 +216,7 @@ provider_server_address = 127.0.0.1:5000 # 無關緊要
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **警告：** 此步驟會下載並加載所有 Docker 鏡像，可能需 30 分鐘。啟動后請等待 backend 服務完全運行（日誌中出現 backend: ），再發送消息。backend 啟動比其他服務慢。
@@ -236,7 +236,7 @@ start ./start_services.cmd full # Windows
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 然後運行：`uv run cli.py`

README_ES.md

@@ -220,7 +220,7 @@ Inicia los servicios requeridos. Esto iniciará todos los servicios del docker-c
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **Advertencia:** Este paso descargará y cargará todas las imágenes de Docker, lo que puede tomar hasta 30 minutos. Después de iniciar los servicios, espera hasta que el servicio backend esté completamente ejecutándose (deberías ver backend: <info> en el log) antes de enviar cualquier mensaje. Los servicios backend pueden tardar más en iniciar que otros.
@@ -240,7 +240,7 @@ Inicia los servicios:
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 Luego ejecuta: `uv run cli.py` 

README_FR.md

@@ -220,7 +220,7 @@ Démarrez les services requis. Cela lancera tous les services du docker-compose.
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **Attention :** Cette étape téléchargera et chargera toutes les images Docker, ce qui peut prendre jusqu’à 30 minutes. Après le démarrage, attendez que le backend soit bien lancé (vous devriez voir backend: <info> dans les logs) avant d’envoyer des messages. Le backend peut mettre plus de temps à démarrer.
@@ -240,7 +240,7 @@ Démarrez les services :
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 Puis lancez : `uv run cli.py`

README_JP.md

@@ -215,7 +215,7 @@ geminiではコーディングやbashが失敗する場合があります。deep
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **注意:** このステップで全Dockerイメージがダウンロード・展開されるため最大30分かかる場合があります。backendサービスが完全に起動するまで（ログにbackend: <info>が表示されるまで）待ってください。
@@ -235,7 +235,7 @@ CLIで実行する場合はホストにパッケージをインストールし
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 その後 `uv run cli.py` を実行

README_PTBR.md

@@ -220,7 +220,7 @@ Inicie os serviços necessários. Isso iniciará todos os serviços do docker-co
 
 ```sh
 ./start_services.sh full # MacOS
-start ./start_services.cmd full # Windows
+start start_services.cmd full # Windows
 ```
 
 **Aviso:** Este passo fará download e carregará todas as imagens Docker, o que pode levar até 30 minutos. Após iniciar os serviços, aguarde até que o serviço backend esteja totalmente rodando (você verá backend: <info> no log) antes de enviar mensagens. O backend pode demorar mais para iniciar.
@@ -240,7 +240,7 @@ Inicie os serviços:
 
 ```sh
 ./start_services.sh # MacOS
-start ./start_services.cmd # Windows
+start start_services.cmd # Windows
 ```
 
 Depois execute: `uv run cli.py`

docs/CONTRIBUTING.md

@@ -92,11 +92,13 @@ Here are some tasks and areas where we need contributions:
 
 Tools are extensions that enable agents to perform specific actions, such as running Python code, making API calls, or conducting web searches. All tools inherit from the Tools base class, which provides methods for parsing and executing tool instructions.
 
-## Tools parsing
+## Understand Tools parsing
 
-Agents invoke tools using a standardized format called a block. A block consists of the tool name followed by the content (e.g., code, query, or parameters) to execute. The format looks like this:
+Agents invoke tools using a standardized format called a block. A block consists of the tool name followed by the content (e.g., code, query, or parameters) to execute. When creating a prompt for an Agent, you must explicitly tell them to use this format.
 
-BECAUSE WE USE MARKDOWN QUOTE FORMAT, READING WILL BE BROKEN ON GITHUB PLEASE START READING THE FILE AS RAW: https://raw.githubusercontent.com/Fosowl/agenticSeek/refs/heads/main/CONTRIBUTING.md
+The format looks like this:
+
+BECAUSE WE USE MARKDOWN QUOTE FORMAT, READING WILL BE BROKEN ON GITHUB PLEASE START READING THE FILE AS RAW:  https://raw.githubusercontent.com/Fosowl/agenticSeek/refs/heads/dev/docs/CONTRIBUTING.md
 
 
 ```<tool name>
@@ -117,10 +119,9 @@ How to handle multiple arguments then ?
 
 Good question! Each tool is free to handle argument in it's own way within the block, but we provide a common parsing logic:
 
-```flight_search
+```trip_search
 from=Paris
-to=Taipei
+to=Toulouse
-date=30/04/2026
 ```
 
 To extract these parameters, use the `get_parameter_value` method provided by the Tools class. Each tool can define its own parameter-handling logic, but the Tools class ensures consistent parsing.
@@ -135,7 +136,7 @@ print("Hello world")
 
 Will save the code in toto.py file within the work_folder defined in the config.ini
 
-## Execution
+## Tools Implementation
 
 When developing a tool, you must implement three abstract methods defined in the Tools class to handle execution, failure detection, and feedback to the agent. These methods ensure consistent behavior across tools and enable robust interaction with the LLM.
 
@@ -171,8 +172,38 @@ Recap:
 - get_parameter_value: Retrieves parameter values from a block's content.
 - File handling: Supports saving block content to files when a :path is specified.
 
-# Implementing and using Agents
+## Prompting an Agent for Tools usage
 
+Consider an example where you want to add a flight search tool to the casual agent, you will need to modify the prompt file for the CasualAgent (e.g., casual_agent.txt) to instruct the LLM to use the a simple flight_search tool. you could add to the prompt:
+
+You can search for flights using the flight_search tool. Example:
+```flight_search
+RY7481
+```
+You simply need to enter the flight number, you will then various informations about the flight if it exist, such as : Airline, Status, Departure time, Arrival Time
+
+## Add the tool to your agent
+
+To add a tool to an agent you simply need to:
+1. Import a tool.
+2. Add the tool class to the **tools** dictionnary.
+3. Update the agent prompt.
+
+```python
+from sources.tools.flightSearch import FlightSearch
+
+class CasualAgent(Agent):
+    def __init__(self, name, prompt_path, provider, verbose=False):
+        super().__init__(name, prompt_path, provider, verbose, None)
+        self.tools = {
+            "flight_search": FlightSearch(),
+        }
+        self.role = "en"
+        self.type = "casual_agent"
+```
+
+
+# Implementing and using Agents
 
 Agents are classes that define how an LLM interacts with users and processes inputs. They can use tools (e.g., for executing code or querying APIs) and maintain a memory of the conversation to provide context-aware responses. All agents inherit from the base Agent class, which provides core functionality like memory management and LLM communication.
 

sources/tools/fileFinder.py

@@ -83,7 +83,7 @@ class FileFinder(Tools):
         else:
             return {"filename": file_path, "error": "File not found"}
     
-    def recursive_search(self, directory_path: str, filename: str) -> str | None:
+    def recursive_search(self, directory_path: str, filename: str) -> str:
         """
         Recursively searches for files in a directory and its subdirectories.
         Args:

sources/tools/flightSearch.py

@@ -12,61 +12,65 @@ from sources.tools.tools import Tools
 class FlightSearch(Tools):
     def __init__(self, api_key: str = None):
         """
-        A tool to search for flight information using a flight number via AviationStack API.
+        A tool to search for flight information using a flight number via SerpAPI.
         """
         super().__init__()
         self.tag = "flight_search"
         self.name = "Flight Search"
-        self.description = "Search for flight information using a flight number via AviationStack API."
+        self.description = "Search for flight information using a flight number via SerpAPI."
-        self.api_key = None
+        self.api_key = api_key or os.getenv("SERPAPI_API_KEY")
-        self.api_key = api_key or os.getenv("AVIATIONSTACK_API_KEY")
 
     def execute(self, blocks: str, safety: bool = True) -> str:
         if self.api_key is None:
-            return "Error: No AviationStack API key provided."
+            return "Error: No SerpAPI key provided."
         
         for block in blocks:
-            flight_number = block.strip().lower().replace('\n', '')
+            flight_number = block.strip().upper().replace('\n', '')
             if not flight_number:
                 return "Error: No flight number provided."
 
             try:
-                url = "http://api.aviationstack.com/v1/flights"
+                url = "https://serpapi.com/search"
                 params = {
-                    "access_key": self.api_key,
+                    "engine": "google_flights",
-                    "flight_iata": flight_number,
+                    "api_key": self.api_key,
-                    "limit": 1
+                    "q": flight_number,
+                    "type": "2"  # Flight status search
                 }
+                
                 response = requests.get(url, params=params)
                 response.raise_for_status()
-
                 data = response.json()
-                if "data" in data and len(data["data"]) > 0:
+                
-                    flight = data["data"][0]
+                if "flights" in data and len(data["flights"]) > 0:
-                    # Extract key flight information
+                    flight = data["flights"][0]
-                    flight_status = flight.get("flight_status", "Unknown")
-                    departure = flight.get("departure", {})
-                    arrival = flight.get("arrival", {})
-                    airline = flight.get("airline", {}).get("name", "Unknown")
                     
-                    departure_airport = departure.get("airport", "Unknown")
+                    # Extract key information
-                    departure_time = departure.get("scheduled", "Unknown")
+                    departure = flight.get("departure_airport", {})
-                    arrival_airport = arrival.get("airport", "Unknown")
+                    arrival = flight.get("arrival_airport", {})
-                    arrival_time = arrival.get("scheduled", "Unknown")
+                    
+                    departure_code = departure.get("id", "Unknown")
+                    departure_time = flight.get("departure_time", "Unknown")
+                    arrival_code = arrival.get("id", "Unknown") 
+                    arrival_time = flight.get("arrival_time", "Unknown")
+                    airline = flight.get("airline", "Unknown")
+                    status = flight.get("flight_status", "Unknown")
 
                     return (
                         f"Flight: {flight_number}\n"
                         f"Airline: {airline}\n"
-                        f"Status: {flight_status}\n"
+                        f"Status: {status}\n"
-                        f"Departure: {departure_airport} at {departure_time}\n"
+                        f"Departure: {departure_code} at {departure_time}\n"
-                        f"Arrival: {arrival_airport} at {arrival_time}"
+                        f"Arrival: {arrival_code} at {arrival_time}"
                     )
                 else:
                     return f"No flight information found for {flight_number}"
+                    
             except requests.RequestException as e:
                 return f"Error during flight search: {str(e)}"
             except Exception as e:
                 return f"Unexpected error: {str(e)}"
+        
         return "No flight search performed"
 
     def execution_failure_check(self, output: str) -> bool: