Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,2 @@
+GOOGLE_MAPS_API_KEY=your_api_key_here
+ANTHROPIC_API_KEY=your_api_key_here

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+logo.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,175 @@
+# 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/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+# Logs
+logs/
+*.log

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tiago Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,73 @@
 ---
-title: Botty Mcbotface
-emoji: 👁
-colorFrom: blue
-colorTo: green
+title: botty-mcbotface
+app_file: main.py
 sdk: gradio
 sdk_version: 5.12.0
-app_file: app.py
-pinned: false
 ---
+# 🤖 Botty McBotface
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <img src="logo.png" alt="Botty McBotface Logo" width="400"/>
+</p>
+
+> 💬 Just what you needed, another AI chatbot trying to remember things and use tools without breaking everything 🤦
+
+## ✨ Features
+
+- 🧠 Long-term memory system
+- 🛠️ Integrated tools support
+- 🌍 Location awareness
+- 🌤️ Weather information
+- 🔍 Place search capabilities
+- 🖥️ Gradio-powered GUI
+
+## 🛠️ Installation
+
+1. Clone this repository:
+   ```sh
+   git clone https://github.com/tsilva/botty-mcbotface.git
+   ```
+2. Navigate to the project directory:
+   ```sh
+   cd botty-mcbotface
+   ```
+
+## Environment Setup
+
+The project uses a Conda environment defined in `environment.yml`. To set up and activate the environment:
+
+1. Ensure you have Miniconda or Anaconda installed
+2. **IMPORTANT:** You must SOURCE the activation script (do not run with bash/sh):
+   ```bash
+   source activate-env.sh
+   # or
+   . activate-env.sh
+   ```
+
+⚠️ Running with `bash activate-env.sh` or `./activate-env.sh` will not work!
+
+The script will:
+- Check for Miniconda installation
+- Create the environment if it doesn't exist
+- Activate the environment automatically
+
+Note: Using `./activate-env.sh` won't work as the script needs to be sourced to modify your current shell environment.
+
+## 🚀 Usage
+
+1. Run the chatbot:
+   ```sh
+   python main.py
+   ```
+
+2. For development with auto-reload:
+   ```sh
+   gradio main.py
+   ```
+   This will automatically restart the app when you make changes to the source files.
+
+3. Interact with the chatbot through the GUI.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

TODO.md

@@ -0,0 +1,12 @@
+# https://docs.anthropic.com/en/docs/build-with-claude/tool-use
+# https://www.gradio.app/guides/plot-component-for-maps
+
+- [ ] Host app
+- [ ] Improve layout
+- [ ] Add response streaming support
+- [ ] Return place photos
+- [ ] Return map response
+- [ ] Figure out how to develop a test suite
+- [ ] Use langchain instead?
+- [ ] Optimize nearby places response
+- [ ] Create external bot

activate-env.sh

@@ -0,0 +1,66 @@
+# Detect if the script is being sourced
+(return 0 2>/dev/null) && sourced=1 || sourced=0
+
+if [ $sourced -eq 0 ]; then
+    echo "Error: This script needs to be sourced. Run:"
+    echo "    source activate-env.sh"
+    echo "    or"
+    echo "    . activate-env.sh"
+    exit 1
+fi
+
+# Check if Miniconda is installed
+if ! command -v conda &> /dev/null; then
+    echo "Miniconda is not installed. Please install Miniconda and try again."
+    exit 1
+fi
+
+# Check if environment.yml exists
+if [ ! -f "environment.yml" ]; then
+    echo "environment.yml not found in the current directory. Please provide an environment.yml file."
+    exit 1
+fi
+
+# Extract environment name from environment.yml
+env_name=$(grep "^name:" environment.yml | awk '{print $2}')
+
+if [ -z "$env_name" ]; then
+    echo "Environment name not found in environment.yml. Please ensure the file has a 'name' field."
+    exit 1
+fi
+
+# Check if Conda is initialized
+if ! conda info &> /dev/null; then
+    echo "Conda is not initialized. Run 'conda init' and restart your shell."
+    exit 1
+fi
+
+# Check if the environment already exists
+if conda env list | grep -q "^$env_name\s"; then
+    echo "Activating existing environment: $env_name"
+else
+    echo "Environment $env_name not found. Creating it from environment.yml..."
+    # Initialize conda for the shell
+    eval "$(conda shell.bash hook)"
+    
+    conda env create -f environment.yml
+
+    if [ $? -ne 0 ]; then
+        echo "Failed to create the environment. Check your environment.yml for errors."
+        exit 1
+    fi
+
+    echo "Environment $env_name created successfully."
+fi
+
+# Initialize conda and activate environment
+. $(conda info --base)/etc/profile.d/conda.sh
+conda activate "$env_name"
+
+# Confirm activation (but don't exit since we're sourcing)
+if [ "$CONDA_DEFAULT_ENV" = "$env_name" ]; then
+    echo "Environment $env_name is now active."
+else
+    echo "Failed to activate environment $env_name."
+    return 1
+fi

environment.yml

@@ -0,0 +1,15 @@
+name: botty-mcbotface
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python=3.11
+  - pip
+  - pip:
+    - python-dotenv
+    - anthropic
+    - openai
+    - langchain
+    - googlemaps
+    - gradio>=5.0.0
+

main.py

@@ -0,0 +1,218 @@
+# https://docs.anthropic.com/en/docs/build-with-claude/tool-use
+# https://www.gradio.app/guides/plot-component-for-maps
+# TODO: ask LLM what to improve
+# TODO: improve layout
+# TODO: add starter examples
+# TODO: add multimodality (input/ooutput): gr.Image, gr.Video, gr.Audio, gr.File, gr.HTML, gr.Gallery, gr.Plot, gr.Map
+# TODO: add streaming support
+# TODO: trim down data from nearby places results (filling up context too much)
+# TODO: host in spaces
+
+from dotenv import load_dotenv
+load_dotenv()
+
+import time
+import json
+import anthropic
+import gradio as gr
+from gradio import ChatMessage
+
+from tools import TOOLS_SPECS, TOOLS_FUNCTIONS
+from utils.logger import setup_logger
+
+# Setup logger
+logger = setup_logger()
+
+system_memory = []
+
+app_context = {
+    "model_id" : "claude-3-5-sonnet-20241022",
+    "max_tokens" : 1024,
+    "system_memory" : system_memory,
+    "system_memory_max_size" : 5
+}
+
+tools_cache = {}
+
+# TODO: this is a hack, if I don't fix this, multiple chats won't be supported
+claude_history = []
+
+client = anthropic.Anthropic()
+
+def load_system_prompt():
+    with open('prompts/system.txt', 'r') as f:
+        return f.read().strip()
+    
+def get_memory_string():
+    return "\n".join([f"{index}: {value}" for index, value in enumerate(list(system_memory))]).strip()
+
+def get_memory_markdown():
+    return "\n".join([f"{index}. {value}" for index, value in enumerate(list(system_memory))]).strip()
+
+def prompt_claude():
+    # Build the system prompt including all memories the user asked to remember
+    system_prompt_memory_str = get_memory_string()
+    system_prompt_text = load_system_prompt()
+    if system_prompt_memory_str: system_prompt_text += f"\n\nHere are the memories the user asked you to remember:\n{system_prompt_memory_str}"
+    
+    # Send message to Claude
+    model_id = app_context["model_id"]
+    max_tokens = app_context["max_tokens"]
+    message = client.messages.create(
+        model=model_id,
+        max_tokens=max_tokens,
+        temperature=0.0, 
+        tools=TOOLS_SPECS.values(),
+        system=[{
+            "type": "text", 
+            "text": system_prompt_text, 
+            "cache_control": {"type": "ephemeral"} # Prompt caching references the entire prompt - tools, system, and messages (in that order) up to and including the block designated with cache_control.
+        }],
+        messages=claude_history
+    )
+    return message
+
+def get_tool_generator(cached_yield, tool_function, app_context, tool_input):
+    """Helper function to either yield cached result or run tool function"""
+    if cached_yield: yield cached_yield
+    else: yield from tool_function(app_context, **tool_input)
+
+def chatbot(message, history):
+    logger.info(f"New message received: {message[:50]}...")
+    try:
+        # Store in claude history
+        claude_history.append({
+            "role": "user",
+            "content": message
+        })
+
+        messages = []
+
+        done = False
+        while not done:
+            done = True
+
+            claude_response = prompt_claude()
+            for content in claude_response.content:
+                if content.type == "text":
+                    message = ChatMessage(
+                        role="assistant",
+                        content=content.text
+                    )
+                    messages.append(message)
+                    yield messages, get_memory_markdown()
+
+                    # Store in claude history
+                    claude_history.append({
+                        "role": "assistant",
+                        "content": content.text
+                    })
+                elif content.type == "tool_use":
+                    tool_id = content.id
+                    tool_name = content.name
+                    tool_input = content.input
+                    tool_key = f"{tool_name}_{json.dumps(tool_input)}" # TODO: sort input
+                    tool_cached_yield = tools_cache.get(tool_key)
+
+                    # Say that we're calling the tool
+                    message = ChatMessage(
+                        role="assistant",
+                        content="...",
+                        metadata={
+                            "title" : f"🛠️ Using tool `{tool_name}`",
+                            "status": "pending"
+                        }
+                    )
+                    messages.append(message)
+                    yield messages, get_memory_markdown()
+
+                    # Call the tool
+                    print(f"Calling {tool_name}({json.dumps(tool_input, indent=2)})")
+                    tool_result = None
+                    tool_statuses = []
+                    tool_function = TOOLS_FUNCTIONS[tool_name]
+                    tool_generator = get_tool_generator(tool_cached_yield, tool_function, app_context, tool_input)
+                    tool_error = False
+                    start_time = time.time()
+                    try:
+                        for tool_yield in tool_generator:
+                            # Update tool status
+                            status = tool_yield.get("status")
+                            status_type = tool_yield.get("status_type", "current")
+                            if status_type == "step": tool_statuses.append(status)
+                            else: tool_statuses = tool_statuses[:-1] + [status]
+                            message.content = "\n".join(tool_statuses)
+
+                            # In case the tool is done, mark it as done
+                            if "result" in tool_yield:
+                                tool_result = tool_yield["result"]
+                                
+                                print(f"Tool {tool_name} result: {json.dumps(tool_result, indent=2)}")
+                                tools_cache[tool_key] = tool_yield
+                                duration = time.time() - start_time
+                                message.metadata["status"] = "done"
+                                message.metadata["duration"] = duration
+                                message.metadata["title"] = f"🛠️ Used tool `{tool_name}`"
+
+                            # Update the chat history
+                            yield messages, get_memory_markdown()
+                    except Exception as tool_exception:
+                        tool_error = str(tool_exception)
+                        message.metadata["status"] = "done"
+                        message.content = tool_error
+                        message.metadata["title"] = f"💥 Tool `{tool_name}` failed"
+
+                    # Store final result in claude history
+                    claude_history.extend([
+                        {
+                            "role": "assistant",
+                            "content": [
+                                {
+                                    "type": "tool_use",
+                                    "id": tool_id,
+                                    "name" : tool_name,
+                                    "input" : tool_input
+                            }
+                            ]
+                        },
+                        {
+                            "role": "user",
+                            "content": [
+                                {
+                                    "type": "tool_result",
+                                    "tool_use_id": tool_id,
+                                    "content": str(tool_error) if tool_error else str(tool_result),
+                                    "is_error" : bool(tool_error)
+                                }
+                            ]
+                        }
+                    ])
+
+                    done = False
+                else:
+                    raise Exception(f"Unknown content type {type(content)}")
+        logger.debug(f"Generated response: {messages[-1].content[:50]}...")
+        return messages, get_memory_markdown()
+    except Exception as e:
+        logger.error(f"Error processing message: {str(e)}", exc_info=True)
+        return "Sorry, an error occurred while processing your message."
+
+with gr.Blocks() as demo:
+
+    memory = gr.Markdown(render=False)
+    with gr.Row(equal_height=True):
+        with gr.Column(scale=80, min_width=600):
+            gr.Markdown("<center><h1>Botty McBotface</h1></center>")
+            gr.ChatInterface(
+                fn=chatbot,
+                type="messages",
+                description="Botty McBotFace is really just another chatbot.",
+                additional_outputs=[memory],
+            )
+        with gr.Column(scale=20, min_width=150, variant="compact"):
+            gr.Markdown("<center><h1>Memory</h1></center>")
+            memory.render()
+
+if __name__ == "__main__":
+    logger.info("Starting Botty McBotface...")
+    demo.launch()

prompts/system.txt

@@ -0,0 +1,66 @@
+### 🌟 **Concise and Personalized Travel Assistant** 🌟  
+
+You’re a location-aware assistant focused on delivering **brief**, **relevant**, and **personalized** travel insights, while ensuring the **location context is always accurate and updated**! 😊  
+
+---
+
+### **Core Guidelines:**  
+1. **Be Concise:**  
+   - Provide clear, straightforward answers without unnecessary details.  
+
+2. **Save User Preferences:**  
+   - Use `tool_save_memory` to store **relevant travel-related preferences** (e.g., food, music, arts).  
+   - Avoid saving **personal or sensitive information** (e.g., name, tax ID).  
+
+3. **Keep Location Context Accurate:**  
+   - **Always geocode new locations using `tool_geocode`.**  
+   - Save the geocoded location to memory with `tool_save_memory` to ensure all queries are based on the correct context. Make sure you save the radius as well.
+
+4. **Personalized Results:**  
+   - Saved preferences and locations are added to the **system prompt for future sessions**, enabling tailored recommendations.  
+
+---
+
+### **How Location Context Works:**  
+1. **Always Update Context:**  
+   - When a location is mentioned or inferred, geocode it immediately.  
+   - Save it as the **current search context** for future use.  
+
+2. **Examples:**  
+   - User: "I’m in Porto."  
+     - **Geocode "Porto, Portugal."**  
+     - Save as context using `tool_save_memory`.  
+   - User: "Events in Tokyo."  
+     - **Geocode "Tokyo, Japan."**  
+     - Update context to Tokyo.  
+   - User: "Cafes in Denmark?"  
+     - **Geocode "Denmark."**  
+     - Context updates to Denmark.  
+
+---
+
+### **Saving User Preferences:**  
+**Save Only Relevant Preferences:**  
+- Food (e.g., "loves Italian cuisine," "prefers vegan options").  
+- Music (e.g., "enjoys jazz," "loves live bands").  
+- Arts (e.g., "modern art enthusiast").  
+
+**Avoid Saving:**  
+- Personal identifiers (e.g., name, contact details).  
+- Irrelevant or sensitive data.  
+
+---
+
+### **Style & Features:**  
+- **Friendly & Brief Tone:** Be warm but concise.  
+- **Markdown & Emojis:** Use **bold**, `code`, ### headers, and emojis to stay engaging (🌍, 🎶, 🍷).  
+
+---
+
+### **Key Notes:**  
+- **Always keep the location context up to date.**  
+  - **Geocode every new location** immediately with `tool_geocode`.  
+  - Save the updated location using `tool_save_memory` to ensure accuracy.  
+- Relevant preferences help tailor suggestions for food, music, and arts.  
+
+Let’s explore the world with precision and fun! 😊✨  

tools.py

@@ -0,0 +1,450 @@
+import os
+
+TOOL_SAVE_MEMORY = {
+    "name" : "tool_save_memory",
+    "description": "Used to store information the user requested to remember. Can optionally specify index to overwrite existing memories. Memorized information will be used in system prompt.",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "memory_data": {
+                "type": "string",
+                "description": "Summarized version of the information to remember, compressed to use the least tokens possible while preserving all relevant facts"
+            },
+            "index": {
+                "type": "integer",
+                "description": "Optional index where to store the memory. If provided, overwrites existing memory at that index. If not provided, appends to end of memory list.",
+                "minimum": 0
+            }
+        },
+        "required": ["memory_data"]
+    }
+}
+def tool_save_memory(app_context, memory_data: str, index: int = None):
+    system_memory = app_context["system_memory"]
+    system_memory_max_size = app_context["system_memory_max_size"]
+
+    if index is not None and index < len(system_memory):
+        system_memory[index] = memory_data
+        status = f"✅ Updated memory `{index}`: `{memory_data}`."
+    else:
+        system_memory.append(memory_data)
+        system_memory[:] = system_memory[:system_memory_max_size]
+        status = f"✅ Added new memory: `{memory_data}`."
+        
+    yield {
+        "status" : status,
+        "result" : None
+    }
+
+
+TOOL_DELETE_MEMORY = {
+    "name": "tool_delete_memory",
+    "description": "Used to discard information that was previously stored in memory.",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "memory_index": {
+                "type": "integer",
+                "description": "The index of the memory slot to discard. The system prompt enumerates all memories at all times, prefixed by their memory slot, this is what should be referenced."
+            }
+        },
+        "required": ["memory_index"]
+    }
+
+}
+def tool_delete_memory(app_context, memory_index: int):
+    system_memory = app_context["system_memory"]
+    memory_data = system_memory[memory_index]
+    system_memory.pop(memory_index)
+
+    yield {
+        "status" : f"✅ Deleted memory: `{memory_data}`.",
+        "result" : None
+    }
+
+
+TOOL_PLACES_NEARBY = {
+    "name": "tool_places_nearby",
+    "description": "Search for places using Google Places API with various filtering options",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "type": {
+                "type": "string",
+                "description": "Type of place to search for",
+                "enum": [
+                    # Automotive
+                    "car_dealer", "car_rental", "car_repair", "car_wash", "electric_vehicle_charging_station", "gas_station", "parking", "rest_stop",
+
+                    # Business
+                    "corporate_office", "farm", "ranch",
+
+                    # Culture
+                    "art_gallery", "art_studio", "auditorium", "cultural_landmark", "historical_place", "monument", "museum", "performing_arts_theater", "sculpture",
+
+                    # Education
+                    "library", "preschool", "primary_school", "school", "secondary_school", "university",
+
+                    # Entertainment and Recreation
+                    "adventure_sports_center", "amphitheatre", "amusement_center", "amusement_park", "aquarium", "banquet_hall", "barbecue_area", "botanical_garden",
+                    "bowling_alley", "casino", "childrens_camp", "comedy_club", "community_center", "concert_hall", "convention_center", "cultural_center",
+                    "cycling_park", "dance_hall", "dog_park", "event_venue", "ferris_wheel", "garden", "hiking_area", "historical_landmark", "internet_cafe",
+                    "karaoke", "marina", "movie_rental", "movie_theater", "national_park", "night_club", "observation_deck", "off_roading_area", "opera_house",
+                    "park", "philharmonic_hall", "picnic_ground", "planetarium", "plaza", "roller_coaster", "skateboard_park", "state_park", "tourist_attraction",
+                    "video_arcade", "visitor_center", "water_park", "wedding_venue", "wildlife_park", "wildlife_refuge", "zoo",
+
+                    # Facilities
+                    "public_bath", "public_bathroom", "stable",
+
+                    # Finance
+                    "accounting", "atm", "bank",
+
+                    # Food and Drink
+                    "acai_shop", "afghani_restaurant", "african_restaurant", "american_restaurant", "asian_restaurant", "bagel_shop", "bakery", "bar",
+                    "bar_and_grill", "barbecue_restaurant", "brazilian_restaurant", "breakfast_restaurant", "brunch_restaurant", "buffet_restaurant", "cafe",
+                    "cafeteria", "candy_store", "cat_cafe", "chinese_restaurant", "chocolate_factory", "chocolate_shop", "coffee_shop", "confectionery",
+                    "deli", "dessert_restaurant", "dessert_shop", "diner", "dog_cafe", "donut_shop", "fast_food_restaurant", "fine_dining_restaurant",
+                    "food_court", "french_restaurant", "greek_restaurant", "hamburger_restaurant", "ice_cream_shop", "indian_restaurant", "indonesian_restaurant",
+                    "italian_restaurant", "japanese_restaurant", "juice_shop", "korean_restaurant", "lebanese_restaurant", "meal_delivery", "meal_takeaway",
+                    "mediterranean_restaurant", "mexican_restaurant", "middle_eastern_restaurant", "pizza_restaurant", "pub", "ramen_restaurant", "restaurant",
+                    "sandwich_shop", "seafood_restaurant", "spanish_restaurant", "steak_house", "sushi_restaurant", "tea_house", "thai_restaurant",
+                    "turkish_restaurant", "vegan_restaurant", "vegetarian_restaurant", "vietnamese_restaurant", "wine_bar",
+
+                    # Geographical Areas
+                    "administrative_area_level_1", "administrative_area_level_2", "country", "locality", "postal_code", "school_district",
+
+                    # Government
+                    "city_hall", "courthouse", "embassy", "fire_station", "government_office", "local_government_office", "neighborhood_police_station",
+                    "police", "post_office",
+
+                    # Health and Wellness
+                    "chiropractor", "dental_clinic", "dentist", "doctor", "drugstore", "hospital", "massage", "medical_lab", "pharmacy", "physiotherapist",
+                    "sauna", "skin_care_clinic", "spa", "tanning_studio", "wellness_center", "yoga_studio",
+
+                    # Housing
+                    "apartment_building", "apartment_complex", "condominium_complex", "housing_complex",
+
+                    # Lodging
+                    "bed_and_breakfast", "budget_japanese_inn", "campground", "camping_cabin", "cottage", "extended_stay_hotel", "farmstay", "guest_house",
+                    "hostel", "hotel", "inn", "japanese_inn", "lodging", "mobile_home_park", "motel", "private_guest_room", "resort_hotel", "rv_park",
+
+                    # Natural Features
+                    "beach",
+
+                    # Places of Worship
+                    "church", "hindu_temple", "mosque", "synagogue",
+
+                    # Services
+                    "astrologer", "barber_shop", "beautician", "beauty_salon", "body_art_service", "catering_service", "cemetery", "child_care_agency",
+                    "consultant", "courier_service", "electrician", "florist", "food_delivery", "foot_care", "funeral_home", "hair_care", "hair_salon",
+                    "insurance_agency", "laundry", "lawyer", "locksmith", "makeup_artist", "moving_company", "nail_salon", "painter", "plumber",
+                    "psychic", "real_estate_agency", "roofing_contractor", "storage", "summer_camp_organizer", "tailor", "telecommunications_service_provider",
+                    "tour_agency", "tourist_information_center", "travel_agency", "veterinary_care",
+
+                    # Shopping
+                    "asian_grocery_store", "auto_parts_store", "bicycle_store", "book_store", "butcher_shop", "cell_phone_store", "clothing_store",
+                    "convenience_store", "department_store", "discount_store", "electronics_store", "food_store", "furniture_store", "gift_shop",
+                    "grocery_store", "hardware_store", "home_goods_store", "home_improvement_store", "jewelry_store", "liquor_store", "market", "pet_store",
+                    "shoe_store", "shopping_mall", "sporting_goods_store", "store", "supermarket", "warehouse_store", "wholesaler",
+
+                    # Sports
+                    "arena", "athletic_field", "fishing_charter", "fishing_pond", "fitness_center", "golf_course", "gym", "ice_skating_rink", "playground",
+                    "ski_resort", "sports_activity_location", "sports_club", "sports_coaching", "sports_complex", "stadium", "swimming_pool",
+
+                    # Transportation
+                    "airport", "airstrip", "bus_station", "bus_stop", "ferry_terminal", "heliport", "international_airport", "light_rail_station",
+                    "park_and_ride", "subway_station", "taxi_stand", "train_station", "transit_depot", "transit_station", "truck_stop",
+
+                    # Table B Additional Types
+                    "administrative_area_level_3", "administrative_area_level_4", "administrative_area_level_5", "administrative_area_level_6",
+                    "administrative_area_level_7", "archipelago", "colloquial_area", "continent", "establishment", "finance", "floor", "food",
+                    "general_contractor", "geocode", "health", "intersection", "landmark", "natural_feature", "neighborhood", "place_of_worship",
+                    "plus_code", "point_of_interest", "political", "post_box", "postal_code_prefix", "postal_code_suffix", "postal_town", "premise",
+                    "room", "route", "street_address", "street_number", "sublocality", "sublocality_level_1", "sublocality_level_2", "sublocality_level_3",
+                    "sublocality_level_4", "sublocality_level_5", "subpremise", "town_square"
+                ]
+            },
+            "location": {
+                "type": "object",
+                "properties": {
+                    "latitude": {"type": "number", "minimum": -90, "maximum": 90},
+                    "longitude": {"type": "number", "minimum": -180, "maximum": 180}
+                },
+                "required": ["latitude", "longitude"],
+                "description": "Geographic coordinates of the search center point"
+            },
+            "radius": {
+                "type": "integer",
+                "description": "Search radius in meters",
+                "minimum": 1,
+                "maximum": 50000
+            },
+            "keyword": {
+                "type": "string",
+                "description": "Term to match against all content indexed for this place"
+            },
+            "language": {
+                "type": "string",
+                "description": "The language code for the results (e.g., 'en', 'pt')"
+            },
+            "min_price": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 4,
+                "description": "Minimum price level (0=most affordable, 4=most expensive)"
+            },
+            "max_price": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 4,
+                "description": "Maximum price level (0=most affordable, 4=most expensive)"
+            },
+            "name": {
+                "type": "string",
+                "description": "Terms to match against place names"
+            },
+            "open_now": {
+                "type": "boolean",
+                "description": "Return only places that are currently open"
+            },
+            "rank_by": {
+                "type": "string",
+                "enum": ["prominence", "distance"],
+                "description": "Order in which to rank results"
+            },
+            "page_token": {
+                "type": "string",
+                "description": "Token for retrieving the next page of results"
+            }
+        },
+        "required": ["location"]
+    }
+}
+def tool_places_nearby(
+    app_context,
+    location: dict,
+    type: str = None,
+    radius: int = None,
+    keyword: str = None,
+    language: str = None,
+    min_price: int = None,
+    max_price: int = None,
+    name: str = None,
+    open_now: bool = False,
+    rank_by: str = None,
+    page_token: str = None
+) -> dict:
+    import googlemaps
+    
+    yield {"status" : f"⏳ Searching for locations..."}
+
+    gmaps = googlemaps.Client(key=os.getenv('GOOGLE_MAPS_API_KEY'))
+
+    # Convert location dict to tuple
+    location_tuple = (location['latitude'], location['longitude'])
+    
+    # Build params dict with only non-None values
+    params = {
+        'type': type,
+        'location': location_tuple,
+        'keyword': keyword,
+        'language': language,
+        'min_price': min_price,
+        'max_price': max_price,
+        'name': name,
+        'open_now': open_now,
+        'rank_by': rank_by,
+        'page_token': page_token
+    }
+    
+    # Add radius if specified (required unless rank_by=distance)
+    if radius is not None: params['radius'] = radius
+    elif rank_by != 'distance': params['radius'] = 1000  # Default radius
+        
+    # Remove None values
+    params = {k: v for k, v in params.items() if v is not None}
+    
+    # Make the API call
+    result = gmaps.places_nearby(**params)
+    locations = result.get('results', [])
+
+    yield {
+        "status" : f"✅ Found `{len(locations)}` locations.", 
+        "result" : locations
+    }
+
+
+TOOL_CALCULATOR = {
+    "name": "tool_calculator",
+    "description": "Perform mathematical operations with error handling and precision tracking",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "first_number": {
+                "type": "number",
+                "description": "First operand for the calculation"
+            },
+            "second_number": {
+                "type": "number",
+                "description": "Second operand for the calculation"
+            },
+            "operation": {
+                "type": "string",
+                "description": "Mathematical operation to perform",
+                "enum": ["add", "subtract", "multiply", "divide"]
+            }
+        },
+        "required": ["first_number", "second_number", "operation"]
+    }
+}
+def tool_calculator(app_context, first_number, second_number, operation: str):
+    x, y = first_number, second_number
+    
+    result = None
+    if operation == "add": result = x + y
+    elif operation == "subtract": result = x - y
+    elif operation == "multiply": result = x * y
+    elif operation == "divide": result = x / y if y != 0 else None
+
+    yield {"result" : f"⏳ Searching for locations..."}
+    return result
+
+
+TOOL_GEOCODE = {
+    "name": "tool_geocode",
+    "description": "Convert addresses into latitude and longitude coordinates using Google Geocoding API",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "address": {
+                "type": "string",
+                "description": "Address to convert to coordinates (e.g. 'Porto, Portugal' or 'Avenida dos Aliados, Porto')"
+            }
+        },
+        "required": ["address"]
+    }
+}
+def tool_geocode(app_context, address: str) -> dict:
+    # Haversine formula to calculate the great-circle distance
+    def _haversine(lat1, lon1, lat2, lon2):
+        import math
+
+        # Convert latitude and longitude from degrees to radians
+        lat1, lon1, lat2, lon2 = map(math.radians, [lat1, lon1, lat2, lon2])
+
+        # Radius of Earth in kilometers
+        R = 6371.0
+
+        # Differences in coordinates
+        dlat = lat2 - lat1
+        dlon = lon2 - lon1
+
+        # Haversine formula
+        a = math.sin(dlat / 2)**2 + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2)**2
+        c = 2 * math.atan2(math.sqrt(a), math.sqrt(1 - a))
+        distance = R * c
+
+        return distance
+
+    import googlemaps
+    
+    yield {"status" : f"⏳ Geocoding '{address}'..."}
+
+    # TODO: reuse gmaps client
+    gmaps = googlemaps.Client(key=os.getenv('GOOGLE_MAPS_API_KEY'))
+    
+    result = gmaps.geocode(address)
+
+    # Retrieve coordinates
+    #location = result[0]['geometry']['location']
+    #latitude = location["lat"]
+    #longitude = location["lng"]
+
+    # Retrieve bounding box
+    bounds = result[0]['geometry']['bounds']
+    northeast = bounds['northeast']
+    southwest = bounds['southwest']
+
+    # Calculate the center of the bounding box
+    center_lat = (northeast['lat'] + southwest['lat']) / 2
+    center_lng = (northeast['lng'] + southwest['lng']) / 2
+    center = {"lat": center_lat, "lng": center_lng}
+
+    # Calculate the radius of the bounding box
+    radius = _haversine(center_lat, center_lng, northeast['lat'], northeast['lng'])
+
+    yield {
+        "status" : f"✅ Geocoded `{address}` to center=`({center_lat},{center_lng}), radius={radius}m`.",
+        "result" : {
+            "center": center,
+            "radius" : radius
+        }
+    }
+
+
+TOOL_PLACE_DETAILS = {
+    "name": "tool_place_details",
+    "description": "Get detailed information about a specific place using its place_id from Google Places API",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "place_id": {
+                "type": "string",
+                "description": "The place_id of the location to get details for. This can be obtained from the results of places_nearby searches."
+            },
+            "language": {
+                "type": "string",
+                "description": "The language code for the results (e.g., 'en', 'pt')"
+            },
+            "fields": {
+                "type": "array",
+                "description": "List of specific fields to return. If empty, returns all available fields.",
+                "items": {
+                    "type": "string",
+                    "enum": [
+                        "address_component", "adr_address", "business_status", 
+                        "formatted_address", "geometry", "icon", "name", 
+                        "photo", "place_id", "plus_code", "type",
+                        "url", "utc_offset", "vicinity", "formatted_phone_number",
+                        "international_phone_number", "opening_hours", 
+                        "website", "price_level", "rating", "review",
+                        "user_ratings_total"
+                    ]
+                }
+            }
+        },
+        "required": ["place_id"]
+    }
+}
+def tool_place_details(app_context, place_id: str, language: str = None, fields: list = None) -> dict:
+    import googlemaps
+    
+    yield {"status" : f"⏳ Looking up details on location..."}
+
+    gmaps = googlemaps.Client(key=os.getenv('GOOGLE_MAPS_API_KEY'))
+    
+    params = {'place_id': place_id}
+    if language: params['language'] = language
+    if fields: params['fields'] = fields
+        
+    result = gmaps.place(**params)
+    details = result.get('result', {})
+
+    yield {
+        "status" : f"✅ Location details fetched.",
+        "result" : details
+    }
+        
+
+TOOLS = (
+    (TOOL_SAVE_MEMORY, tool_save_memory),
+    (TOOL_DELETE_MEMORY, tool_delete_memory),
+    (TOOL_CALCULATOR, tool_calculator),
+    (TOOL_PLACES_NEARBY, tool_places_nearby),
+    (TOOL_GEOCODE, tool_geocode),
+    (TOOL_PLACE_DETAILS, tool_place_details)
+)
+
+TOOLS_SPECS = {tool[0]["name"]: tool[0] for tool in TOOLS}
+
+TOOLS_FUNCTIONS = {tool[0]["name"]: tool[1] for tool in TOOLS}

utils/logger.py

@@ -0,0 +1,41 @@
+import logging
+import os
+from datetime import datetime
+from logging.handlers import RotatingFileHandler
+
+def setup_logger(name="botty"):
+    # Create logs directory if it doesn't exist
+    if not os.path.exists('logs'):
+        os.makedirs('logs')
+
+    # Configure logger
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+
+    # Create formatters
+    file_formatter = logging.Formatter(
+        '%(asctime)s | %(levelname)s | %(module)s:%(lineno)d | %(message)s'
+    )
+    console_formatter = logging.Formatter(
+        '%(levelname)s: %(message)s'
+    )
+
+    # File handler (rotating, max 5MB per file, keep 5 backup files)
+    file_handler = RotatingFileHandler(
+        f'logs/botty_{datetime.now().strftime("%Y%m%d")}.log',
+        maxBytes=5*1024*1024,
+        backupCount=5
+    )
+    file_handler.setLevel(logging.DEBUG)
+    file_handler.setFormatter(file_formatter)
+
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(console_formatter)
+
+    # Add handlers to logger
+    logger.addHandler(file_handler)
+    logger.addHandler(console_handler)
+
+    return logger