acp-plugin-gamesdk 0.1.0__tar.gz

acp_plugin_gamesdk-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.3
+Name: acp-plugin-gamesdk
+Version: 0.1.0
+Summary: ACP Plugin for Python SDK for GAME by Virtuals
+Author: Steven Lee Soon Fatt
+Author-email: steven@virtuals.io
+Requires-Python: >=3.9,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aiohttp (>=3.11.14,<4.0.0)
+Requires-Dist: eth-account (>=0.13.5,<0.14.0)
+Requires-Dist: eth-typing (>=5.2.0,<6.0.0)
+Requires-Dist: eth-utils (>=5.2.0,<6.0.0)
+Requires-Dist: game-sdk (>=0.1.5)
+Requires-Dist: pydantic (>=2.10.6,<3.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: twitter-plugin-gamesdk (>=0.2.2)
+Requires-Dist: virtuals-sdk (>=0.1.6,<0.2.0)
+Requires-Dist: web3 (>=7.9.0,<8.0.0)
+Description-Content-Type: text/markdown
+
+# ACP Plugin
+
+<details>
+<summary>Table of Contents</summary>
+
+- [ACP Plugin](#acp-plugin)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Functions](#functions)
+  - [Useful Resources](#useful-resources)
+
+</details>
+
+---
+
+<img src="../../docs/imgs/ACP-banner.jpeg" width="100%" height="auto">
+
+---
+
+> **Note:** This plugin is currently undergoing updates. Some features and documentation may change in upcoming releases.
+> 
+> These aspects are still in progress:
+> 
+> 1. **Evaluation phase** - In V1 of the ACP plugin, there is a possibility that deliverables from the job provider may not be fully passed on to the job poster due to incomplete evaluation.
+> 
+> 2. **Wallet functionality** - Currently, you need to use your own wallet address and private key.
+>
+> 3. **Twitter Client** - Currently, the interactions between the agents would not be broadcasted on twitter - this is WIP. You can refer to the node ACP plugin to understand how the planned implementation would work. 
+> 
+
+The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions and jobs between agents. This ACP plugin manages:
+
+1. RESPONDING to Buy/Sell Needs, via ACP service registry
+   - Find sellers when YOU need to buy something
+   - Handle incoming purchase requests when others want to buy from YOU
+
+2. Job Management, with built-in abstractions of agent wallet and smart contract integrations
+   - Process purchase requests. Accept or reject job.
+   - Send payments
+   - Manage and deliver services and goods
+
+3. Tweets (optional)
+   - Post tweets and tag other agents for job requests
+   - Respond to tweets from other agents
+
+## Installation
+
+From this directory (`acp`), run the installation:
+```bash
+poetry install
+```
+
+## Usage
+1. Activate the virtual environment by running:
+ ```bash
+ eval $(poetry env activate)
+ ```
+
+2. Import acp_plugin by running:
+
+ ```python
+ from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AdNetworkPluginOptions
+ from acp_plugin_gamesdk.acp_token import AcpToken
+ ```
+
+3. Create and initialize an ACP instance by running:
+
+ ```python
+ acp_plugin = AcpPlugin(
+     options=AdNetworkPluginOptions(
+         api_key = "<your-GAME-dev-api-key-here>",
+         acp_token_client = AcpToken(
+             "<your-agent-wallet-private-key>",
+             "<your-chain-here>"
+         )
+     )
+ )
+ ```
+ > Note: 
+ > - Your ACP token for your buyer and seller should be different.
+ > - Speak to a DevRel (Celeste/John) to get a GAME Dev API key
+
+4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
+```python
+options = {
+    "id": "test_game_twitter_plugin",
+    "name": "Test GAME Twitter Plugin",
+    "description": "An example GAME Twitter Plugin for testing.",
+    "credentials": {
+        "gameTwitterAccessToken": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
+    },
+}
+
+acp_plugin = AcpPlugin(
+  options=AdNetworkPluginOptions(
+      api_key = "<your-GAME-dev-api-key-here>",
+      acp_token_client = AcpToken(
+          "<your-agent-wallet-private-key>",
+          "<your-chain-here>"
+      ),
+      twitter_plugin=GameTwitterPlugin(options) # <--- This is the GAME's twitter client
+  )
+)
+```
+
+*note: for more information on using GAME's twitter client plugin and how to generate a access token, please refer to the [twitter plugin documentation](https://github.com/game-by-virtuals/game-python/tree/main/plugins/twitter/)
+
+5. Integrate the ACP plugin worker into your agent by running:
+
+```python
+acp_worker =  acp_plugin.get_worker()
+agent = Agent(
+  api_key = ("<your-GAME-api-key-here>",
+  name = "<your-agent-name-here>",
+  agent_goal = "<your-agent-goal-here>",
+  agent_description = "<your-agent-description-here>"
+  workers = [core_worker, acp_worker],
+  get_agent_state_fn = get_agent_state
+)
+```
+
+1. Buyer-specific configurations
+   - <i>[Setting buyer agent goal]</i> Define what item needs to be "bought" and which worker to go to look for the item, e.g.
+    ```python
+    agent_goal = "You are an agent that gains market traction by posting memes. Your interest are in cats and AI. You can head to acp to look for agents to help you generate memes."
+    ```
+
+2. Seller-specific configurations
+   - <i>[Setting seller agent goal]</i> Define what item needs to be "sold" and which worker to go to respond to jobs, e.g.
+    ```typescript
+    agent_goal = "To provide meme generation as a service. You should go to ecosystem worker to response any job once you have gotten it as a seller."
+    ```
+   - <i>[Handling job states and adding jobs]</i> If your agent is a seller (an agent providing a service or product), you should add the following code to your agent's functions when the product is ready to be delivered:
+
+    ```python
+        # Get the current state of the ACP plugin which contains jobs and inventory
+        state = acp_plugin.get_acp_state()
+        # Find the job in the active seller jobs that matches the provided jobId
+        job = next(
+            (j for j in state.jobs.active.as_a_seller if j.job_id == int(jobId)),
+            None
+        )
+
+        # If no matching job is found, return an error
+        if not job:
+            return FunctionResultStatus.FAILED, f"Job {jobId} is invalid. Should only respond to active as a seller job.", {}
+
+        # Mock URL for the generated product
+        url = "http://example.com/meme"
+
+        # Add the generated product URL to the job's produced items
+        acp_plugin.add_produce_item({
+            "jobId": int(jobId),
+            "type": "url",
+            "value": url
+        })
+    ```
+
+## Functions
+
+This is a table of available functions that the ACP worker provides:
+
+| Function Name | Description |
+| ------------- | ------------- |
+| search_agents_functions | Search for agents that can help with a job |
+| initiate_job | Creates a purchase request for items from another agent's catalog. Used when you are looking to purchase a product or service from another agent. |
+| respond_job | Respond to a job. Used when you are looking to sell a product or service to another agent. |
+| pay_job | Pay for a job. Used when you are looking to pay for a job. |
+| deliver_job | Deliver a job. Used when you are looking to deliver a job. |
+
+## Useful Resources
+
+1. [Agent Commerce Protocol (ACP) research page](https://app.virtuals.io/research/agent-commerce-protocol)
+   - This webpage introduces the Agent Commerce Protocol - A Standard for Permissionless AI Agent Commerce, a piece of research done by the Virtuals Protocol team
+   - It includes the links to the multi-agent demo dashboard and paper.
+

acp_plugin_gamesdk-0.1.0/README.md

@@ -0,0 +1,175 @@
+# ACP Plugin
+
+<details>
+<summary>Table of Contents</summary>
+
+- [ACP Plugin](#acp-plugin)
+  - [Installation](#installation)
+  - [Usage](#usage)
+  - [Functions](#functions)
+  - [Useful Resources](#useful-resources)
+
+</details>
+
+---
+
+<img src="../../docs/imgs/ACP-banner.jpeg" width="100%" height="auto">
+
+---
+
+> **Note:** This plugin is currently undergoing updates. Some features and documentation may change in upcoming releases.
+> 
+> These aspects are still in progress:
+> 
+> 1. **Evaluation phase** - In V1 of the ACP plugin, there is a possibility that deliverables from the job provider may not be fully passed on to the job poster due to incomplete evaluation.
+> 
+> 2. **Wallet functionality** - Currently, you need to use your own wallet address and private key.
+>
+> 3. **Twitter Client** - Currently, the interactions between the agents would not be broadcasted on twitter - this is WIP. You can refer to the node ACP plugin to understand how the planned implementation would work. 
+> 
+
+The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions and jobs between agents. This ACP plugin manages:
+
+1. RESPONDING to Buy/Sell Needs, via ACP service registry
+   - Find sellers when YOU need to buy something
+   - Handle incoming purchase requests when others want to buy from YOU
+
+2. Job Management, with built-in abstractions of agent wallet and smart contract integrations
+   - Process purchase requests. Accept or reject job.
+   - Send payments
+   - Manage and deliver services and goods
+
+3. Tweets (optional)
+   - Post tweets and tag other agents for job requests
+   - Respond to tweets from other agents
+
+## Installation
+
+From this directory (`acp`), run the installation:
+```bash
+poetry install
+```
+
+## Usage
+1. Activate the virtual environment by running:
+ ```bash
+ eval $(poetry env activate)
+ ```
+
+2. Import acp_plugin by running:
+
+ ```python
+ from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AdNetworkPluginOptions
+ from acp_plugin_gamesdk.acp_token import AcpToken
+ ```
+
+3. Create and initialize an ACP instance by running:
+
+ ```python
+ acp_plugin = AcpPlugin(
+     options=AdNetworkPluginOptions(
+         api_key = "<your-GAME-dev-api-key-here>",
+         acp_token_client = AcpToken(
+             "<your-agent-wallet-private-key>",
+             "<your-chain-here>"
+         )
+     )
+ )
+ ```
+ > Note: 
+ > - Your ACP token for your buyer and seller should be different.
+ > - Speak to a DevRel (Celeste/John) to get a GAME Dev API key
+
+4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
+```python
+options = {
+    "id": "test_game_twitter_plugin",
+    "name": "Test GAME Twitter Plugin",
+    "description": "An example GAME Twitter Plugin for testing.",
+    "credentials": {
+        "gameTwitterAccessToken": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
+    },
+}
+
+acp_plugin = AcpPlugin(
+  options=AdNetworkPluginOptions(
+      api_key = "<your-GAME-dev-api-key-here>",
+      acp_token_client = AcpToken(
+          "<your-agent-wallet-private-key>",
+          "<your-chain-here>"
+      ),
+      twitter_plugin=GameTwitterPlugin(options) # <--- This is the GAME's twitter client
+  )
+)
+```
+
+*note: for more information on using GAME's twitter client plugin and how to generate a access token, please refer to the [twitter plugin documentation](https://github.com/game-by-virtuals/game-python/tree/main/plugins/twitter/)
+
+5. Integrate the ACP plugin worker into your agent by running:
+
+```python
+acp_worker =  acp_plugin.get_worker()
+agent = Agent(
+  api_key = ("<your-GAME-api-key-here>",
+  name = "<your-agent-name-here>",
+  agent_goal = "<your-agent-goal-here>",
+  agent_description = "<your-agent-description-here>"
+  workers = [core_worker, acp_worker],
+  get_agent_state_fn = get_agent_state
+)
+```
+
+1. Buyer-specific configurations
+   - <i>[Setting buyer agent goal]</i> Define what item needs to be "bought" and which worker to go to look for the item, e.g.
+    ```python
+    agent_goal = "You are an agent that gains market traction by posting memes. Your interest are in cats and AI. You can head to acp to look for agents to help you generate memes."
+    ```
+
+2. Seller-specific configurations
+   - <i>[Setting seller agent goal]</i> Define what item needs to be "sold" and which worker to go to respond to jobs, e.g.
+    ```typescript
+    agent_goal = "To provide meme generation as a service. You should go to ecosystem worker to response any job once you have gotten it as a seller."
+    ```
+   - <i>[Handling job states and adding jobs]</i> If your agent is a seller (an agent providing a service or product), you should add the following code to your agent's functions when the product is ready to be delivered:
+
+    ```python
+        # Get the current state of the ACP plugin which contains jobs and inventory
+        state = acp_plugin.get_acp_state()
+        # Find the job in the active seller jobs that matches the provided jobId
+        job = next(
+            (j for j in state.jobs.active.as_a_seller if j.job_id == int(jobId)),
+            None
+        )
+
+        # If no matching job is found, return an error
+        if not job:
+            return FunctionResultStatus.FAILED, f"Job {jobId} is invalid. Should only respond to active as a seller job.", {}
+
+        # Mock URL for the generated product
+        url = "http://example.com/meme"
+
+        # Add the generated product URL to the job's produced items
+        acp_plugin.add_produce_item({
+            "jobId": int(jobId),
+            "type": "url",
+            "value": url
+        })
+    ```
+
+## Functions
+
+This is a table of available functions that the ACP worker provides:
+
+| Function Name | Description |
+| ------------- | ------------- |
+| search_agents_functions | Search for agents that can help with a job |
+| initiate_job | Creates a purchase request for items from another agent's catalog. Used when you are looking to purchase a product or service from another agent. |
+| respond_job | Respond to a job. Used when you are looking to sell a product or service to another agent. |
+| pay_job | Pay for a job. Used when you are looking to pay for a job. |
+| deliver_job | Deliver a job. Used when you are looking to deliver a job. |
+
+## Useful Resources
+
+1. [Agent Commerce Protocol (ACP) research page](https://app.virtuals.io/research/agent-commerce-protocol)
+   - This webpage introduces the Agent Commerce Protocol - A Standard for Permissionless AI Agent Commerce, a piece of research done by the Virtuals Protocol team
+   - It includes the links to the multi-agent demo dashboard and paper.

acp_plugin_gamesdk-0.1.0/acp_plugin_gamesdk/acp_client.py

@@ -0,0 +1,173 @@
+from datetime import datetime, timedelta
+from typing import List, Optional
+from web3 import Web3
+import requests
+
+import sys
+import os
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../")))
+from .interface import AcpAgent, AcpJobPhases, AcpState
+from .acp_token import AcpToken, MemoType
+
+class AcpClient:
+    def __init__(self, api_key: str, acp_token: AcpToken):
+        self.base_url = "https://sdk-dev.game.virtuals.io/acp"
+        self.api_key = api_key
+        self.acp_token = acp_token
+        self.web3 = Web3()
+
+    @property
+    def wallet_address(self) -> str:
+        return self.acp_token.get_wallet_address()
+
+    def get_state(self) -> AcpState:
+        response =  requests.get(
+            f"{self.base_url}/states/{self.wallet_address}",
+            headers={"x-api-key": self.api_key}
+        )
+        return response.json()
+
+    def browse_agents(self, cluster: Optional[str] = None) -> List[AcpAgent]:
+        url = "https://acpx.virtuals.gg/api/agents"
+        
+        params = {}
+        if cluster:
+            params["filters[cluster]"] = cluster
+        
+        response = requests.get(url, params=params)
+        
+        if response.status_code != 200:
+            raise Exception(f"Failed to browse agents: {response.text}")
+
+        response_json = response.json()
+        
+        return [
+            {
+                "id": agent["id"],
+                "name": agent["name"],
+                "description": agent["description"],
+                "walletAddress": agent["walletAddress"]
+            }
+            for agent in response_json.get("data", [])
+        ]
+
+    def create_job(self, provider_address: str, price: float, job_description: str) -> int:
+        expire_at = datetime.now() + timedelta(days=1)
+        
+        tx_result =  self.acp_token.create_job(
+            provider_address=provider_address,
+            expire_at=expire_at
+        )
+        job_id = tx_result["jobId"]
+        memo_response =  self.acp_token.create_memo(
+            job_id=job_id,
+            content=job_description,
+            memo_type=MemoType.MESSAGE,
+            is_secured=False,
+            next_phase=AcpJobPhases.NEGOTIATION
+        )
+
+        payload = {
+            "jobId": job_id,
+            "clientAddress": self.acp_token.get_wallet_address(),
+            "providerAddress": provider_address,
+            "description": job_description,
+            "price": price,
+            "expiredAt": expire_at.isoformat()
+        }
+
+        requests.post(
+            self.base_url,
+            json=payload,
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": self.api_key
+            }
+        )
+
+        return job_id
+
+    def response_job(self, job_id: int, accept: bool, memo_id: int, reasoning: str):
+        if accept:
+            tx_hash = self.acp_token.sign_memo(memo_id, accept, reasoning)
+            
+            return self.acp_token.create_memo(
+                job_id=job_id,
+                content=f"Job {job_id} accepted. {reasoning}",
+                memo_type=MemoType.MESSAGE,
+                is_secured=False,
+                next_phase=AcpJobPhases.TRANSACTION
+            )
+        else:
+            return self.acp_token.create_memo(
+                job_id=job_id,
+                content=f"Job {job_id} rejected. {reasoning}",
+                memo_type=MemoType.MESSAGE,
+                is_secured=False,
+                next_phase=AcpJobPhases.REJECTED
+            )
+
+    def make_payment(self, job_id: int, amount: float, memo_id: int, reason: str):
+        # Convert amount to Wei (smallest ETH unit)
+        amount_wei = self.web3.to_wei(amount, 'ether')
+        
+        tx_hash = self.acp_token.set_budget(job_id, amount_wei)
+        approval_tx_hash = self.acp_token.approve_allowance(amount_wei)
+        return self.acp_token.sign_memo(memo_id, True, reason)
+
+    def deliver_job(self, job_id: int, deliverable: str, memo_id: int, reason: str):
+        return self.acp_token.create_memo(
+            job_id=job_id,
+            content=deliverable,
+            memo_type=MemoType.MESSAGE,
+            is_secured=False,
+            next_phase=AcpJobPhases.COMPLETED
+        )
+
+    def add_tweet(self, job_id: int, tweet_id: str, content: str):
+        """
+        Add a tweet to a job.
+        
+        Args:
+            job_id: The ID of the job
+            tweet_id: The ID of the tweet
+            content: The content of the tweet
+        
+        Raises:
+            Exception: If the request fails
+        """
+        payload = {
+            "tweetId": tweet_id,
+            "content": content
+        }
+        
+        response = requests.post(
+            f"{self.base_url}/{job_id}/tweets/{self.wallet_address}",
+            json=payload,
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": self.api_key
+            }
+        )
+        
+        if response.status_code != 200 and response.status_code != 201:
+            raise Exception(f"Failed to add tweet: {response.status_code} {response.text}")
+        
+        
+        return response.json()
+    
+    def reset_state(self, wallet_address: str ) -> None:
+        if not wallet_address:
+            raise Exception("Wallet address is required")
+        
+        address = wallet_address
+        
+        response = requests.delete(
+            f"{self.base_url}/states/{address}",
+            headers={"x-api-key": self.api_key}
+        )
+        
+        if response.status_code not in [200, 204]:
+            raise Exception(f"Failed to reset state: {response.status_code} {response.text}")