Merge commit '6e6576f548d21db8127ed18f2248ff23df303dfc' into feat/update-readme

Author: stevensf1998

CONTRIBUTION_GUIDE.md

@@ -0,0 +1,26 @@
+# Contributing to GAME SDK
+
+There are various ways you can contribute to the GAME SDK, whether it's fixing bugs, adding new plugins, or improving the documentation.
+
+### Submitting Code (e.g. plugins)
+1. **Fork** the repository and clone it to your local machine.
+2. **Create a Branch** for your changes.
+3. **Make Changes** to address the issue or add the feature.
+4. **Commit** with a message that clearly explains your change.
+5. **Push** the branch to your fork and submit a pull request.
+6. **Label** the pull request appropriately based on the [label definitions](#label-definitions)
+   
+### Reporting Bugs
+- Open an issue in the [Issues](https://github.com/game-by-virtuals/game-python/issues) tab and tag it as a `bug`.
+  
+### Suggesting Enhancements
+- Open an issue in the [Issues](https://github.com/your-username/my-project/issues) tab and tag it as an `enhancement`.
+
+## Label Definitions
+
+Please tag issues and pull requests appropriately, based on the definition below:
+- **plugin**: A plugin contribution.
+- **bug**: A problem that needs fixing.
+- **enhancement**: A requested enhancement.
+- **help wanted**: A task that is open for anyone to work on.
+- **documentation**: Documentation changes.

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025, Virtuals Protocol
+
+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,6 +1,20 @@
 # GAME Python SDK Library
 The GAME Python SDK is a library that allows you interact and develop agents powered by the GAME architecture.
 
+## Overview of the Source Code Structure 
+
+There are 2 main folders in the source code (`src` folder)
+
+1. `game`:
+
+    Please refer to [`test_agent.py`](examples/game/test_agent.py) and [`test_worker.py`](examples/game/test_worker.py) for usage examples.
+
+2. `hosted_game`<br/>
+
+    This is a more abstracted version of the SDK which allows one to deploy a Twitter agent, which would then be hosted by GAME infrastructure. 
+    
+    Note that this README focuses on the code in the `game` folder. More details about `hosted_game` can be found in [`src/hosted_game/README.md`](src/game_sdk/hosted_game/README.md).
+
 ## Installation
 ```bash
 pip install game_sdk
@@ -12,29 +26,87 @@ git clone https://github.com/game-by-virtuals/game-python.git
 cd game-python
 pip install -e .
 ```
+To install the latest versions of the plugins, navigate to the plugin folder to run the installation, e.g.:
+```bash
+cd plugins/twitter
+pip install -e .
+```
 
 ## Usage
-Please refer to [`test_agent.py`](examples/game/test_agent.py) and [`test_worker.py`](examples/game/test_worker.py) for usage examples.
+1. `game`:
+   - Request for a GAME API key in the Game Console https://console.game.virtuals.io/ 
+   - Store the key in a safe location, like a `.bashrc` or a `.zshrc` file. 
+      
+      ```bash
+      export GAME_API_KEY="your_game_api_key"
+      ```
+   - Refer to [`src/game/README.md`](src/game_sdk/game/README.md) for usage guidelines, and refer to [`test_agent.py`](examples/game/test_agent.py) and [`test_worker.py`](examples/game/test_worker.py) for usage examples.
+
+2. `hosted_game`<br/>
+    - Open the [Virtuals Platform](https://app.virtuals.io/) and create/get an API key from the Agent Sandbox by clicking `SDK/API Access`
+      ![getGAMEApi](docs/imgs/accesskey.jpg)
+    
+    - Store the key in a safe location, like a `.bashrc` or a `.zshrc` file. 
+      
+      ```bash
+      export VIRTUALS_API_KEY="your_virtuals_api_key"
+      ```
+    - Refer to [`src/hosted_game/README.md`](src/game_sdk/hosted_game/README.md) for usage examples.
+  
+<small> If you have any trouble, contact Virtuals support or DevRel team members via Discord or Telegram </small>
+
+## Examples
+  ### GAME
+  Example 1: [`test_agent.py`](examples/game/test_agent.py) 
+  - Demonstrates how to create, configure, and run an AI agent with custom logic and workflows.
+    ```bash
+    python examples/game/test_agent.py
+    ```
+
+  Example 2: [`test_worker.py`](examples/game/test_worker.py)
+  - Demonstrates how to configure, test, and manage workers that execute tasks within the agent's plan.
+    ```bash
+    python examples/game/test_worker.py
+    ```
+
+  Example 3: [`example_twitter_reaction_module.py`](examples/game/example_twitter_reaction_module.py)
+  - Demonstrates how to create and configure an AI agent with a reaction module for responding to tweets in real-time.
+    ```bash
+    python examples/game/example_twitter_reaction_module.py
+    ```
+  
+  ### Hosted Agent
+  Example 1: [`example-custom.py`](examples/hosted_agent/example-custom.py) 
+  - A complete guide to integrating an AI agent with other platform such as Telegram.
+    ```bash
+    python examples/hosted_agent/example-custom.py
+    ```
+  
+  Example 2: [`example-twitter.py`](examples/hosted_agent/example-twitter.py)
+  - A complete guide to integrating an AI agent with Twitter.
+    ```bash
+    python examples/hosted_agent/example-twitter.py
+    ```
 
 ## About G.A.M.E.
 GAME is a modular agentic framework which enables an agent to plan actions and make decisions autonomously based on information provided to it.
 
-Please refer to our [whitepaper](https://whitepaper.virtuals.io/developer-documents/game-framework) for more information and resources.
+Please refer to our [whitepaper](https://docs.game.virtuals.io/) for more information and resources.
 
 ## About GAME Python SDK
-Currently, this SDK allows you to develop your agents powered by the GAME architecture in its most fullest and most flexible form.
+Currently, the SDK (specifically the code in the `game` folder) allows you to develop your agents powered by the GAME architecture in its most fullest and most flexible form.
 
 ![New SDK visual](docs/imgs/new_sdk_visual.png)
 The python SDK is made up of 3 main components (Agent, Worker, function), each with configurable arguments.
 
-Agent (a.k.a. [high level planner](https://whitepaper.virtuals.io/developer-documents/game-framework/game-overview#high-level-planner-hlp-context))
+Agent (a.k.a. [high level planner](https://docs.game.virtuals.io/))
 - Takes in a <b>Goal</b>
   - Drives the agents behaviour through the high level plan which influences the thinking and creation of tasks that would contribute towards this goal
 - Takes in a <b>Description</b>
   - Combination of what was previously known as World Info + Agent Description
   - This include a description of the "world" the agent lives in, and the personality and background of the agent
 
-Worker (a.k.a. [low-level planner](https://whitepaper.virtuals.io/developer-documents/game-framework/game-overview#low-level-planner-llp-context)) 
+Worker (a.k.a. [low-level planner](https://docs.game.virtuals.io/) 
 - Takes in a <b>Description</b>
   - Used to control which workers are called by the agent, based on the high-level plan and tasks created to contribute to the goal
 
@@ -52,19 +124,30 @@ Function
   - Calling an API to retrieve data, followed by custom calculations or data processing logic in python code
   - 2 API calls chained together (e.g. calling an API to retrieve web data, and then posting a tweet)
 
-> ### ℹ️ Changes from older python SDK version (prior to 8 Jan 2025)
+> ### ℹ️ Differences from the hosted GAME SDK version (i.e. `hosted_game`)
 >![Old SDK visual](docs/imgs/old_sdk_visual.png)
 > - Ability to fully customise functions (previously, each function was a single API call)
 > - Ability to control the low-level planner via description prompt (previously, only the high-level planner and functions could be controlled via description prompts)
 > - The description defined in the agent is equivalent to what was previously known as world information and agent description
 
-
 ## How to Contribute
-Contributions are welcome, especially in the form of new plugins! We are working on creating a plugins repo, but in meantime - please contact us via [Twitter](https://x.com/GAME_Virtuals) or [Telegram](https://t.me/virtuaIs_io).
+Want to help improve the project? Please see our detailed [Contribution Guide](./CONTRIBUTION_GUIDE.md).
 
 ## Documentation
 Detailed documentation to better understand the configurable components and the GAME architecture can be found on [here](https://whitepaper.virtuals.io/developer-documents/game-framework).
 
 ## Useful Resources
-- [GAME TypeScript SDK](https://www.npmjs.com/package/@virtuals-protocol/game): The core logic of this SDK mirrors the logic of this python SDK if you prefer to develop your agents in TypeScript. Tyepscript SDK repository and contributed typescript plugins can be found [here](https://github.com/game-by-virtuals/game-node).
-- [Hosted GAME Agent](./src/game_sdk/hosted_game/README.md): This SDK also enables configuration and deployment of an out-of-the-box hosted agent that can be used to interact with the Twitter/X platform, powered by GAME. This agent comes with existing functions/actions that can be used to interact with the Twitter/X platform and can be immediately hosted/deployed as you configure it. This is similar to configuring your agent in the [Agent Sandbox](https://game-lite.virtuals.io/) on the [Virtuals Platform](https://app.virtuals.io/) but through a developer-friendly SDK interface.
+
+#### 1. [GAME TypeScript SDK](https://github.com/game-by-virtuals/game-node)
+   - This SDK mirrors the logic of the Python SDK but allows development in TypeScript.
+   - The repository contains TypeScript SDK documentation and [contributed plugins](https://github.com/game-by-virtuals/game-node/tree/main/plugins) .
+
+#### 2. [Hosted GAME Agent](./src/game_sdk/hosted_game/README.md)
+   - This feature enables the configuration and deployment of a hosted agent that interacts with platforms like Twitter/X.
+   - Pre-built functions and actions are included for integration with the Twitter/X platform.
+   - It offers a similar experience to configuring an agent in the [Agent Sandbox](https://game-lite.virtuals.io/) on the [Virtuals Platform](https://app.virtuals.io/), but with a developer-friendly SDK interface.
+
+#### 3. [GAME Whitepaper](https://whitepaper.virtuals.io/developer-documents/game-framework)
+   - Comprehensive documentation about the GAME SDK and Sandbox.
+   - The [How To](https://docs.game.virtuals.io/how-to) section includes video tutorials, use cases, and additional tips.
+   - Content is regularly updated to provide new insights and improvements.

docs/imgs/accesskey.jpg

@@ -0,0 +1,116 @@
+from game_sdk.game.agent import Agent, WorkerConfig
+from game_sdk.game.worker import Worker
+from game_sdk.game.custom_types import Function, Argument, FunctionResult, FunctionResultStatus
+from typing import Optional, Dict, List
+import os
+import requests
+import time
+from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
+from PIL import Image
+from io import BytesIO
+
+game_api_key = os.environ.get("GAME_API_KEY")
+
+def get_state_fn(function_result: FunctionResult, current_state: dict) -> dict:
+    """
+    This function will get called at every step of the agent's execution to form the agent's state.
+    It will take as input the function result from the previous step.
+    In this case, we don't track state changes so states are are static - hence hardcoding as empty dict.
+    """
+    return {}
+
+def analyze_image_from_url(image_url: str) -> dict:
+    """
+    Function to analyse the image colours and brightness
+    """
+    # Fetch image from URL
+    response = requests.get(image_url)
+    img = Image.open(BytesIO(response.content))
+    # Basic Info
+    width, height = img.size
+    mode = img.mode  # RGB, Grayscale, etc.
+    # Convert to RGB if not already
+    img = img.convert("RGB")
+    # Get Average Color
+    pixels = list(img.getdata())
+    avg_color = tuple(sum(x) // len(pixels) for x in zip(*pixels))  # Average RGB
+    # Estimate Brightness (0-255)
+    brightness = sum(avg_color) // 3  # Simple brightness estimate
+    # Format Results
+    return {
+        "Image Size": f"{width}x{height}", 
+        "Image Mode": mode,
+        "Average Color (RGB)": avg_color,
+        "Brightness Level": brightness
+    }
+
+def get_twitter_user_mentions(username: str) -> Optional[List[Dict]]:
+    """
+    Function to user user mentions on twitter using twitter API
+    """
+    options = {
+        "id": "test_twitter_plugin",
+        "name": "Test Twitter Plugin",
+        "description": "An example Twitter Plugin for testing.",
+        "credentials": {
+            "bearerToken": os.environ.get("TWITTER_BEARER_TOKEN")
+        },
+    }
+    twitter_plugin = TwitterPlugin(options)
+    get_user_fn = twitter_plugin.get_function('get_user_from_handle')
+    user_id = get_user_fn(username)
+    get_user_mentions_fn = twitter_plugin.get_function('get_user_mentions')
+    user_mentions = get_user_mentions_fn(user_id, max_results=100)
+    return user_mentions
+
+def analyze_tweeted_images(start_time: str, **kwargs) -> dict:
+    """
+    Function with 2 main steps
+    1. Get user mentions on twitter using twitter API, including includes image urls
+    2. Pass image urls through a function to detect image colours and brightness
+    """
+    print("start_time", start_time)
+    TWITTER_HANDLE = "GAME_Virtuals" # TODO: change this twitter handle out with actual twitter handle
+    try:
+        # res_twitter_mentions = get_twitter_user_mentions(username = TWITTER_HANDLE)
+        # mock data if needed
+        res_twitter_mentions = [
+            {'id': '1883506463731028254', 'text': '🌌 The Virtuals landscape on Base is absolutely 🔥 and growing faster than ever 🚀\n\nWhat’s your favorite project? 🧐\n\n$VIRTUAL @virtuals_io\n$AIXBT @aixbt_agent\n$GAME @GAME_Virtuals\n$VADER @Vader_AI_\n$LUNA @luna_virtuals\n$ACOLYT @AcolytAI\n$SEKOIA @sekoia_virtuals\n$AIXCB @aixCB_Vc… https://t.co/0gFjzd6L9x https://t.co/mCrdOPRiOF', 'media_urls': ['https://pbs.twimg.com/media/GiOPIuYWcAA3moW.jpg']}, 
+            {'id': '1883506453509480784', 'text': "@DJM09068876 @virtuals_io @aixbt_agent @GAME_Virtuals @Vader_AI_ @luna_virtuals @airocket_agent @trackgoodai @BeatsOnBase @Zenith_Virtuals @AcolytAI @aixCB_Vc So many AI agents, yet none can rival the prowess of Bittensor's $TAO meow! While others chase hype, we build the ultimate decentralized neural network. Let's see those subnets purr with performance and validators strut with superiority. Watch TAO roar past the rest!", 'media_urls': []}, 
+            {'id': '1883506168070590820', 'text': '@100xDarren @virtuals_io My favorite #Virtual project is @GAME_Virtuals! A perfect project– productivity and efficiency in one @virtuals_io\n\nI am going to be honest, if I win, I will spend most of the prize to pay for my college tuition fee 🙏  I am a graduating college student on my last semester now+', 'media_urls': []}
+        ]
+        for res in res_twitter_mentions:
+            media_urls = res["media_urls"]
+            for media_url in media_urls:
+                print(f"media_url: {media_url}")
+                response = analyze_image_from_url(media_url)
+                # TODO: do something with this result
+        return FunctionResultStatus.DONE, f"Successfully verified all tweeted images", {}
+    except:
+        return FunctionResultStatus.FAILED, "Error encountered while detecting tweeted images", {}
+
+# Action space with all executables
+action_space = [
+    Function(
+        fn_name="screen_tweeted_images", 
+        fn_description="Get the latest tweeted images and screen them to check if they are fake", 
+        args=[
+            Argument(name="start_time", type="string", description="Start time for twitter API in YYYY-MM-DDTHH:mm:ssZ format")
+        ],
+        executable=analyze_tweeted_images
+    )
+]
+
+worker = Worker(
+    api_key=game_api_key,
+    description="Processing incoming tweets. If someone tweets at you with an image, check if the colour and brightness of the image.",
+    instruction="Get more information on tweeted images by running them through a image analyse to check colour and brightness",  
+    get_state_fn=get_state_fn,
+    action_space=action_space
+)
+
+# Get the worker to check if incoming tweets (in the last 15min) mentions contain fake images
+while True:
+    worker.run("Analysing incoming tweets for the last 15 minutes")
+    print("Waiting for 15 minutes...")
+    time.sleep(15 * 60)