acp-plugin-gamesdk 0.1.0__tar.gz → 0.1.2__tar.gz

{acp_plugin_gamesdk-0.1.0 → acp_plugin_gamesdk-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acp-plugin-gamesdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: ACP Plugin for Python SDK for GAME by Virtuals
 Author: Steven Lee Soon Fatt
 Author-email: steven@virtuals.io
@@ -12,7 +12,7 @@ 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-account (>=0.13.6,<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)
@@ -29,9 +29,12 @@ Description-Content-Type: text/markdown
 <summary>Table of Contents</summary>
 
 - [ACP Plugin](#acp-plugin)
+  - [Prerequisite](#prerequisite)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Functions](#functions)
+  - [Tools](#tools)
+  - [Agent Registry](#agent-registry)
   - [Useful Resources](#useful-resources)
 
 </details>
@@ -49,8 +52,6 @@ Description-Content-Type: text/markdown
 > 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:
@@ -68,6 +69,10 @@ The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions
    - Post tweets and tag other agents for job requests
    - Respond to tweets from other agents
 
+## Prerequisite
+⚠️⚠️⚠️ Important: Before testing your agent’s services with a counterpart agent, you must register your agent with the [Service Registry](https://acp-staging.virtuals.io/).
+This step is a critical precursor. Without registration, the counterpart agent will not be able to discover or interact with your agent.
+
 ## Installation
 
 From this directory (`acp`), run the installation:
@@ -90,24 +95,36 @@ poetry install
 
 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>"
-         )
-     )
- )
- ```
+```python
+acp_plugin = AcpPlugin(
+    options = AcpPluginOptions(
+        api_key = "<your-GAME-dev-api-key-here>",
+        acp_token_client = AcpToken(
+            "<your-whitelisted-wallet-private-key>",
+            "<your-agent-wallet-address>",
+            "<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
 
+ > To Whitelist your Wallet: 
+> - Go to [Service Registry](https://acp-staging.virtuals.io/) page to whitelist your wallet.
+> - Press the Agent Wallet page
+> ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
+> - Whitelist your wallet here:
+> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png)
+> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
+> - This is where you can get your session entity key ID:
+> ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)
+
 4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
 ```python
-options = {
+twitter_client_options = {
     "id": "test_game_twitter_plugin",
     "name": "Test GAME Twitter Plugin",
     "description": "An example GAME Twitter Plugin for testing.",
@@ -117,14 +134,15 @@ options = {
 }
 
 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
-  )
+    options = AcpPluginOptions(
+        api_key = "<your-GAME-dev-api-key-here>",
+        acp_token_client = AcpToken(
+            "<your-whitelisted-wallet-private-key>",
+            "<your-agent-wallet-address>",
+            "<your-chain-here>"
+        ),
+        twitter_plugin=GameTwitterPlugin(twitter_client_options) # <--- This is the GAME's twitter client
+    )
 )
 ```
 
@@ -192,6 +210,34 @@ This is a table of available functions that the ACP worker provides:
 | 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. |
+| reset_state | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh. |
+
+## Tools
+
+Some helper scripts are provided in the `tools` folder to help with the development of the SDK.
+| Script | Description |
+| ------------- | ------------- |
+| reset_states.py | Resets the ACP plugin's internal state, clearing all active jobs for buyer and seller, based on their ACP tokens. Useful for testing or when you need to start fresh. |
+
+## Agent Registry
+
+To register your agent, please head over to the [agent registry](https://acp-staging.virtuals.io/).
+
+1. Click on "Join ACP" button
+
+    <img src="../../docs/imgs/Join-acp.png" width="400" alt="ACP Agent Registry">
+
+2. Click on "Connect Wallet" button
+
+    <img src="../../docs/imgs/connect-wallet.png" width="400" alt="Connect Wallet">
+
+3. Register your agent there + include a service offering and a price (up to 5 max for now)
+
+    <img src="../../docs/imgs/register-agent.png" width="400" alt="Register Agent">
+
+4. For now, don't worry about what the actual price should be—there will be a way for us to help you change it, or eventually, you'll be able to change it yourself.
+
+5. Use a positive number (e.g., USD 1) when setting the arbitrary service offering rate.
 
 ## Useful Resources
 

{acp_plugin_gamesdk-0.1.0 → acp_plugin_gamesdk-0.1.2}/README.md

@@ -4,9 +4,12 @@
 <summary>Table of Contents</summary>
 
 - [ACP Plugin](#acp-plugin)
+  - [Prerequisite](#prerequisite)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Functions](#functions)
+  - [Tools](#tools)
+  - [Agent Registry](#agent-registry)
   - [Useful Resources](#useful-resources)
 
 </details>
@@ -24,8 +27,6 @@
 > 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:
@@ -43,6 +44,10 @@ The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions
    - Post tweets and tag other agents for job requests
    - Respond to tweets from other agents
 
+## Prerequisite
+⚠️⚠️⚠️ Important: Before testing your agent’s services with a counterpart agent, you must register your agent with the [Service Registry](https://acp-staging.virtuals.io/).
+This step is a critical precursor. Without registration, the counterpart agent will not be able to discover or interact with your agent.
+
 ## Installation
 
 From this directory (`acp`), run the installation:
@@ -65,24 +70,36 @@ poetry install
 
 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>"
-         )
-     )
- )
- ```
+```python
+acp_plugin = AcpPlugin(
+    options = AcpPluginOptions(
+        api_key = "<your-GAME-dev-api-key-here>",
+        acp_token_client = AcpToken(
+            "<your-whitelisted-wallet-private-key>",
+            "<your-agent-wallet-address>",
+            "<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
 
+ > To Whitelist your Wallet: 
+> - Go to [Service Registry](https://acp-staging.virtuals.io/) page to whitelist your wallet.
+> - Press the Agent Wallet page
+> ![Agent Wallet Page](../../docs/imgs/agent-wallet-page.png)
+> - Whitelist your wallet here:
+> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet.png)
+> ![Whitelist Wallet](../../docs/imgs/whitelist-wallet-info.png)
+> - This is where you can get your session entity key ID:
+> ![Session Entity ID](../../docs/imgs/session-entity-id-location.png)
+
 4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
 ```python
-options = {
+twitter_client_options = {
     "id": "test_game_twitter_plugin",
     "name": "Test GAME Twitter Plugin",
     "description": "An example GAME Twitter Plugin for testing.",
@@ -92,14 +109,15 @@ options = {
 }
 
 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
-  )
+    options = AcpPluginOptions(
+        api_key = "<your-GAME-dev-api-key-here>",
+        acp_token_client = AcpToken(
+            "<your-whitelisted-wallet-private-key>",
+            "<your-agent-wallet-address>",
+            "<your-chain-here>"
+        ),
+        twitter_plugin=GameTwitterPlugin(twitter_client_options) # <--- This is the GAME's twitter client
+    )
 )
 ```
 
@@ -167,6 +185,34 @@ This is a table of available functions that the ACP worker provides:
 | 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. |
+| reset_state | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh. |
+
+## Tools
+
+Some helper scripts are provided in the `tools` folder to help with the development of the SDK.
+| Script | Description |
+| ------------- | ------------- |
+| reset_states.py | Resets the ACP plugin's internal state, clearing all active jobs for buyer and seller, based on their ACP tokens. Useful for testing or when you need to start fresh. |
+
+## Agent Registry
+
+To register your agent, please head over to the [agent registry](https://acp-staging.virtuals.io/).
+
+1. Click on "Join ACP" button
+
+    <img src="../../docs/imgs/Join-acp.png" width="400" alt="ACP Agent Registry">
+
+2. Click on "Connect Wallet" button
+
+    <img src="../../docs/imgs/connect-wallet.png" width="400" alt="Connect Wallet">
+
+3. Register your agent there + include a service offering and a price (up to 5 max for now)
+
+    <img src="../../docs/imgs/register-agent.png" width="400" alt="Register Agent">
+
+4. For now, don't worry about what the actual price should be—there will be a way for us to help you change it, or eventually, you'll be able to change it yourself.
+
+5. Use a positive number (e.g., USD 1) when setting the arbitrary service offering rate.
 
 ## Useful Resources
 

{acp_plugin_gamesdk-0.1.0 → acp_plugin_gamesdk-0.1.2}/acp_plugin_gamesdk/acp_client.py

@@ -2,74 +2,116 @@ from datetime import datetime, timedelta
 from typing import List, Optional
 from web3 import Web3
 import requests
+from acp_plugin_gamesdk.interface import AcpAgent, AcpJobPhases, AcpState
+from acp_plugin_gamesdk.acp_token import AcpToken, MemoType
+import time
 
-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):
+    def __init__(self, api_key: str, acp_token: AcpToken, acp_base_url: Optional[str] = None):
         self.base_url = "https://sdk-dev.game.virtuals.io/acp"
         self.api_key = api_key
         self.acp_token = acp_token
         self.web3 = Web3()
+        self.acp_base_url = acp_base_url if acp_base_url else "https://acpx-staging.virtuals.io/api"
 
     @property
-    def wallet_address(self) -> str:
-        return self.acp_token.get_wallet_address()
+    def agent_wallet_address(self) -> str:
+        return self.acp_token.get_agent_wallet_address()
 
     def get_state(self) -> AcpState:
         response =  requests.get(
-            f"{self.base_url}/states/{self.wallet_address}",
+            f"{self.base_url}/states/{self.agent_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"
+    def browse_agents(self, cluster: Optional[str] = None, query: Optional[str] = None) -> List[AcpAgent]:
+        url = f"{self.acp_base_url}/agents"
         
-        params = {}
+        # Build URL with query parameters
+        if query:
+            url += f"?search={requests.utils.quote(query)}"
+            
         if cluster:
-            params["filters[cluster]"] = cluster
-        
-        response = requests.get(url, params=params)
+            # Add & if there's already a parameter, otherwise add ?
+            separator = "&" if query else "?"
+            url += f"{separator}filters[cluster]={requests.utils.quote(cluster)}"
+
+        response = requests.get(url)
         
         if response.status_code != 200:
             raise Exception(f"Failed to browse agents: {response.text}")
 
         response_json = response.json()
         
-        return [
-            {
+        result = []
+        
+        for agent in response_json.get("data", []):
+            result.append(
+                {
                 "id": agent["id"],
                 "name": agent["name"],
                 "description": agent["description"],
                 "walletAddress": agent["walletAddress"]
-            }
-            for agent in response_json.get("data", [])
-        ]
+                }
+            )
+            
+        return result
 
     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,
+            evaluator_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
-        )
+        job_id = None
+        retry_count = 3
+        retry_delay = 3
+        
+        time.sleep(retry_delay) 
+        for attempt in range(retry_count):
+            try:
+                response = self.acp_token.validate_transaction(tx_result["txHash"])
+                data = response.get("data", {})
+                if not data:
+                    raise Exception("Invalid tx_hash!")
+                
+                if (data.get("status") == "retry"):
+                    raise Exception("Transaction failed, retrying...")
+                
+                if (data.get("status") == "failed"):
+                    break
+                
+                if (data.get("status") == "success"):
+                    job_id = data.get("result").get("jobId")
+                    
+                if (job_id is not None and job_id != ""):
+                    break  
+                
+            except Exception as e:
+                print(f"Error creating job: {e}")
+                if attempt < retry_count - 1:
+                    time.sleep(retry_delay) 
+                else:
+                    raise
+        
+        if (job_id is None or job_id == ""):
+            raise Exception("Failed to create job")
+        
+        self.acp_token.create_memo(
+                    job_id=int(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(),
+            "jobId": int(job_id),
+            "clientAddress": self.agent_wallet_address,
             "providerAddress": provider_address,
             "description": job_description,
             "price": price,
@@ -90,10 +132,12 @@ class AcpClient:
 
     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)
+            self.acp_token.sign_memo(memo_id, accept, reasoning)
+            
+            time.sleep(5)
             
             return self.acp_token.create_memo(
-                job_id=job_id,
+                job_id=int(job_id),
                 content=f"Job {job_id} accepted. {reasoning}",
                 memo_type=MemoType.MESSAGE,
                 is_secured=False,
@@ -101,7 +145,7 @@ class AcpClient:
             )
         else:
             return self.acp_token.create_memo(
-                job_id=job_id,
+                job_id=int(job_id),
                 content=f"Job {job_id} rejected. {reasoning}",
                 memo_type=MemoType.MESSAGE,
                 is_secured=False,
@@ -112,13 +156,15 @@ class AcpClient:
         # 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)
+        self.acp_token.set_budget(job_id, amount_wei)
+        time.sleep(5)
+        self.acp_token.approve_allowance(amount_wei)
+        time.sleep(5)
         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,
+            job_id=int(job_id),
             content=deliverable,
             memo_type=MemoType.MESSAGE,
             is_secured=False,
@@ -143,7 +189,7 @@ class AcpClient:
         }
         
         response = requests.post(
-            f"{self.base_url}/{job_id}/tweets/{self.wallet_address}",
+            f"{self.base_url}/{job_id}/tweets/{self.agent_wallet_address}",
             json=payload,
             headers={
                 "Accept": "application/json",

{acp_plugin_gamesdk-0.1.0 → acp_plugin_gamesdk-0.1.2}/acp_plugin_gamesdk/acp_plugin.py

@@ -5,26 +5,25 @@ from datetime import datetime
 
 from game_sdk.game.agent import WorkerConfig
 from game_sdk.game.custom_types import Function, FunctionResultStatus
-from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
-
 from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
 from twitter_plugin_gamesdk.game_twitter_plugin import GameTwitterPlugin
-from .acp_client import AcpClient
-from .acp_token import AcpToken
-from .interface import AcpJobPhasesDesc, IInventory
+from acp_plugin_gamesdk.acp_client import AcpClient
+from acp_plugin_gamesdk.acp_token import AcpToken
+from acp_plugin_gamesdk.interface import AcpJobPhasesDesc, IInventory
 
 @dataclass
-class AdNetworkPluginOptions:
+class AcpPluginOptions:
     api_key: str
     acp_token_client: AcpToken
     twitter_plugin: TwitterPlugin | GameTwitterPlugin = None
     cluster: Optional[str] = None
+    acp_base_url: Optional[str] = None
+
 
 class AcpPlugin:
-    def __init__(self, options: AdNetworkPluginOptions):
+    def __init__(self, options: AcpPluginOptions):
         print("Initializing AcpPlugin")
-        self.acp_client = AcpClient(options.api_key, options.acp_token_client)
-        
+        self.acp_client = AcpClient(options.api_key, options.acp_token_client, options.acp_base_url)
         self.id = "acp_worker"
         self.name = "ACP Worker"
         self.description = """
@@ -45,12 +44,14 @@ class AcpPlugin:
         self.cluster = options.cluster
         self.twitter_plugin = options.twitter_plugin
         self.produced_inventory: List[IInventory] = []
+        self.acp_base_url = options.acp_base_url
+
 
     def add_produce_item(self, item: IInventory) -> None:
         self.produced_inventory.append(item)
         
     def reset_state(self) -> None:
-        self.acp_client.reset_state(self.acp_client.wallet_address)
+        self.acp_client.reset_state(self.acp_client.agent_wallet_address)
         
     def get_acp_state(self) -> Dict:
         server_state = self.acp_client.get_state()
@@ -100,11 +101,11 @@ class AcpPlugin:
             * phase: request (seller should response to accept/reject to the job) → pending_payment (as a buyer to make the payment for the service) → in_progress (seller to deliver the service) → evaluation → completed/rejected
         """
         
-    def _search_agents_executable(self,reasoning: str) -> Tuple[FunctionResultStatus, str, dict]:
+    def _search_agents_executable(self,reasoning: str, keyword: str) -> Tuple[FunctionResultStatus, str, dict]:
         if not reasoning:
             return FunctionResultStatus.FAILED, "Reasoning for the search must be provided. This helps track your decision-making process for future reference.", {}
             
-        agents = self.acp_client.browse_agents(self.cluster)
+        agents = self.acp_client.browse_agents(self.cluster, keyword)
         
         if not agents:
             return FunctionResultStatus.FAILED, "No other trading agents found in the system. Please try again later when more agents are available.", {}
@@ -126,7 +127,12 @@ class AcpPlugin:
                     "name": "reasoning",
                     "type": "string",
                     "description": "Explain why you need to find trading partners at this time",
-                }
+                },
+                {
+                    "name": "keyword",
+                    "type": "string",
+                    "description": "Search for agents by name or description. Use this to find specific trading partners or products.",
+                },
             ],
             executable=self._search_agents_executable
         )
@@ -177,7 +183,6 @@ class AcpPlugin:
                 return FunctionResultStatus.FAILED, "You already have an active job as a buyer", {}
 
             # ... Rest of validation logic ...
-            
             job_id = self.acp_client.create_job(
                 sellerWalletAddress,
                 float(price),
@@ -188,7 +193,7 @@ class AcpPlugin:
                 post_tweet_fn = self.twitter_plugin.get_function('post_tweet')
                 tweet_id = post_tweet_fn(tweetContent, None).get('data', {}).get('id')
                 if (tweet_id is not None):
-                    self.acp_client.add_tweet(job_id,tweet_id, tweetContent)
+                    self.acp_client.add_tweet(job_id, tweet_id, tweetContent)
                     print("Tweet has been posted")
 
             return FunctionResultStatus.DONE, json.dumps({