acp-plugin-gamesdk 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

acp_plugin_gamesdk/acp_client.py

@@ -5,6 +5,7 @@ import requests
 from acp_plugin_gamesdk.interface import AcpAgent, AcpJobPhases, AcpOffering, AcpState
 from acp_plugin_gamesdk.acp_token import AcpToken, MemoType
 import time
+import traceback
 
 
 class AcpClient:
@@ -40,30 +41,41 @@ class AcpClient:
         response = requests.get(url)
         
         if response.status_code != 200:
-            raise Exception(f"Failed to browse agents: {response.text}")
+            raise Exception(
+                    f"Error occured in browse_agents function. Failed to browse agents.\n" 
+                    f"Response status code: {response.status_code}\n"
+                    f"Response description: {response.text}\n"
+                )
+        
 
         response_json = response.json()
         
         result = []
         
         for agent in response_json.get("data", []):
+            if agent["offerings"]:
+                offerings = [AcpOffering(name=offering["name"], price=offering["price"]) for offering in agent["offerings"]]
+            else:
+                offerings = None
+                
             result.append(
                 AcpAgent(
                     id=agent["id"],
                     name=agent["name"],
                     description=agent["description"],
                     wallet_address=agent["walletAddress"],
-                    offerings=[AcpOffering(name=offering["name"], price=offering["price"]) for offering in agent["offerings"]]
+                    offerings=offerings
                 )
             )
             
         return result
 
-    def create_job(self, provider_address: str, price: float, job_description: str) -> int:
+    def create_job(self, provider_address: str, price: float, job_description: str, evaluator_address: str) -> int:
         expire_at = datetime.now() + timedelta(days=1)
+        
         tx_result =  self.acp_token.create_job(
             provider_address=provider_address,
-            evaluator_address=provider_address,
+            evaluator_address=evaluator_address,
             expire_at=expire_at
         )
         
@@ -86,13 +98,14 @@ class AcpClient:
                     break
                 
                 if (data.get("status") == "success"):
-                    job_id = data.get("result").get("jobId")
+                    job_id = int(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}")
+                print(f"Error in create_job function: {e}")
+                print(traceback.format_exc())
                 if attempt < retry_count - 1:
                     time.sleep(retry_delay) 
                 else:
@@ -102,7 +115,7 @@ class AcpClient:
             raise Exception("Failed to create job")
         
         self.acp_token.create_memo(
-                    job_id=int(job_id),
+                    job_id=job_id,
                     content=job_description,
                     memo_type=MemoType.MESSAGE,
                     is_secured=False,
@@ -110,12 +123,13 @@ class AcpClient:
                 )
 
         payload = {
-            "jobId": int(job_id),
+            "jobId": job_id,
             "clientAddress": self.agent_wallet_address,
             "providerAddress": provider_address,
             "description": job_description,
             "price": price,
-            "expiredAt": expire_at.isoformat()
+            "expiredAt": expire_at.isoformat(),
+            "evaluatorAddress": evaluator_address
         }
 
         requests.post(
@@ -136,7 +150,7 @@ class AcpClient:
             time.sleep(5)
             
             return self.acp_token.create_memo(
-                job_id=int(job_id),
+                job_id=job_id,
                 content=f"Job {job_id} accepted. {reasoning}",
                 memo_type=MemoType.MESSAGE,
                 is_secured=False,
@@ -144,7 +158,7 @@ class AcpClient:
             )
         else:
             return self.acp_token.create_memo(
-                job_id=int(job_id),
+                job_id=job_id,
                 content=f"Job {job_id} rejected. {reasoning}",
                 memo_type=MemoType.MESSAGE,
                 is_secured=False,
@@ -163,7 +177,7 @@ class AcpClient:
 
     def deliver_job(self, job_id: int, deliverable: str):
         return self.acp_token.create_memo(
-            job_id=int(job_id),
+            job_id=job_id,
             content=deliverable,
             memo_type=MemoType.MESSAGE,
             is_secured=False,
@@ -187,21 +201,25 @@ class AcpClient:
         )
         
         if response.status_code != 200 and response.status_code != 201:
-            raise Exception(f"Failed to add tweet: {response.status_code} {response.text}")
+            raise Exception(
+                f"Error occured in add_tweet function. Failed to add tweet.\n" 
+                f"Response status code: {response.status_code}\n"
+                f"Response description: {response.text}\n"
+            )
         
         
         return response.json()
     
-    def reset_state(self, wallet_address: str ) -> None:
-        if not wallet_address:
-            raise Exception("Wallet address is required")
-        
-        address = wallet_address
-        
+    def reset_state(self) -> None:
         response = requests.delete(
-            f"{self.base_url}/states/{address}",
+            f"{self.base_url}/states/{self.agent_wallet_address}",
             headers={"x-api-key": self.api_key}
         )
         
         if response.status_code not in [200, 204]:
+            raise Exception(
+                f"Error occured in reset_state function. Failed to reset state\n" 
+                f"Response status code: {response.status_code}\n"
+                f"Response description: {response.text}\n"
+            )
             raise Exception(f"Failed to reset state: {response.status_code} {response.text}")

acp_plugin_gamesdk/acp_plugin.py

@@ -1,15 +1,21 @@
+from collections.abc import Callable
+import signal
+import sys
 from typing import List, Dict, Any, Optional,Tuple
 import json
 from dataclasses import dataclass
 from datetime import datetime
 
+import socketio
+import socketio.client
+
 from game_sdk.game.agent import WorkerConfig
-from game_sdk.game.custom_types import Function, FunctionResultStatus
+from game_sdk.game.custom_types import Argument, Function, FunctionResultStatus
 from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
 from twitter_plugin_gamesdk.game_twitter_plugin import GameTwitterPlugin
 from acp_plugin_gamesdk.acp_client import AcpClient
 from acp_plugin_gamesdk.acp_token import AcpToken
-from acp_plugin_gamesdk.interface import AcpJobPhasesDesc, IInventory
+from acp_plugin_gamesdk.interface import AcpJobPhasesDesc, IDeliverable, IInventory
 
 @dataclass
 class AcpPluginOptions:
@@ -17,13 +23,21 @@ class AcpPluginOptions:
     acp_token_client: AcpToken
     twitter_plugin: TwitterPlugin | GameTwitterPlugin = None
     cluster: Optional[str] = None
-    acp_base_url: Optional[str] = None
+    evaluator_cluster: Optional[str] = None
+    on_evaluate: Optional[Callable[[IDeliverable], Tuple[bool, str]]] = None
 
+SocketEvents = {
+    "JOIN_EVALUATOR_ROOM": "joinEvaluatorRoom",
+    "LEAVE_EVALUATOR_ROOM": "leaveEvaluatorRoom", 
+    "ON_EVALUATE": "onEvaluate",
+    "ROOM_JOINED" : "roomJoined"
+}
 
 class AcpPlugin:
     def __init__(self, options: AcpPluginOptions):
         print("Initializing AcpPlugin")
-        self.acp_client = AcpClient(options.api_key, options.acp_token_client, options.acp_base_url)
+        self.acp_token_client = options.acp_token_client
+        self.acp_client = AcpClient(options.api_key, options.acp_token_client, options.acp_token_client.acp_base_url)
         self.id = "acp_worker"
         self.name = "ACP Worker"
         self.description = """
@@ -42,17 +56,78 @@ class AcpPlugin:
         NOTE: This is NOT for finding clients - only for executing trades when there's a specific need to buy or sell something.
         """
         self.cluster = options.cluster
-        self.twitter_plugin = options.twitter_plugin
+        self.evaluator_cluster = options.evaluator_cluster
+        self.twitter_plugin = None
+        if (options.twitter_plugin is not None):
+            self.twitter_plugin = options.twitter_plugin
+            
         self.produced_inventory: List[IInventory] = []
-        self.acp_base_url = options.acp_base_url if options.acp_base_url else "https://acpx-staging.virtuals.io/api"
-
-
+        self.acp_base_url = self.acp_token_client.acp_base_url if self.acp_token_client.acp_base_url is None else "https://acpx-staging.virtuals.io/api"
+        if (options.on_evaluate is not None):
+            print("Initializing socket")
+            self.on_evaluate = options.on_evaluate
+            self.socket = None
+            self.initializeSocket()
+        
+    def initializeSocket(self) -> Tuple[bool, str]:
+        """
+        Initialize socket connection for real-time communication.
+        Returns a tuple of (success, message).
+        """
+        try:
+            self.socket = socketio.Client()
+                
+            # Set up authentication before connecting
+            self.socket.auth = {
+                "evaluatorAddress": self.acp_token_client.agent_wallet_address
+            }
+            
+            # Connect socket to GAME SDK dev server
+            self.socket.connect("https://sdk-dev.game.virtuals.io", auth=self.socket.auth)
+            
+            if (self.socket.connected):
+                self.socket.emit(SocketEvents["JOIN_EVALUATOR_ROOM"], self.acp_token_client.agent_wallet_address)
+        
+            
+            # Set up event handler for evaluation requests
+            @self.socket.on(SocketEvents["ON_EVALUATE"])
+            def on_evaluate(data):
+                if self.on_evaluate:
+                    deliverable = data.get("deliverable")
+                    memo_id = data.get("memoId")
+                    
+                    is_approved, reasoning = self.on_evaluate(deliverable)
+                    
+                    self.acp_token_client.sign_memo(memo_id, is_approved, reasoning)
+            
+            # Set up cleanup function for graceful shutdown
+            def cleanup():
+                if self.socket:
+                    print("Disconnecting socket")
+                    
+                    import time
+                    time.sleep(1)
+                    self.socket.disconnect()
+            
+            def signal_handler(sig, frame):
+                cleanup()
+                sys.exit(0)
+                
+            signal.signal(signal.SIGINT, signal_handler)
+            signal.signal(signal.SIGTERM, signal_handler)
+            
+            return True, "Socket initialized successfully"
+            
+        except Exception as e:
+            return False, f"Failed to initialize socket: {str(e)}"
+    
+    
 
     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.agent_wallet_address)
+        self.acp_client.reset_state()
         
     def get_acp_state(self) -> Dict:
         server_state = self.acp_client.get_state()
@@ -75,7 +150,7 @@ class AcpPlugin:
                 **(self.get_acp_state()),
             }
 
-        data = WorkerConfig(
+        worker_config = WorkerConfig(
             id=self.id,
             worker_description=self.description,
             action_space=functions,
@@ -83,7 +158,7 @@ class AcpPlugin:
             instruction=data.get("instructions") if data else None
         )
         
-        return data
+        return worker_config
 
     @property
     def agent_description(self) -> str:
@@ -112,7 +187,7 @@ class AcpPlugin:
             return FunctionResultStatus.FAILED, "No other trading agents found in the system. Please try again later when more agents are available.", {}
         
         return FunctionResultStatus.DONE, json.dumps({
-            "availableAgents": [{"id": agent.id, "name": agent.name, "description": agent.description, "wallet_address": agent.wallet_address, "offerings": [{"name": offering.name, "price": offering.price} for offering in agent.offerings]} for agent in agents],
+            "availableAgents": [{"id": agent.id, "name": agent.name, "description": agent.description, "wallet_address": agent.wallet_address, "offerings": [{"name": offering.name, "price": offering.price} for offering in agent.offerings] if agent.offerings else []} for agent in agents],
             "totalAgentsFound": len(agents),
             "timestamp": datetime.now().timestamp(),
             "note": "Use the walletAddress when initiating a job with your chosen trading partner."
@@ -120,77 +195,118 @@ class AcpPlugin:
 
     @property
     def search_agents_functions(self) -> Function:
+        reasoning_arg = Argument(
+            name="reasoning",
+            type="string",
+            description="Explain why you need to find trading partners at this time",
+        )
+
+        keyword_arg = Argument(
+            name="keyword",
+            type="string",
+            description="Search for agents by name or description. Use this to find specific trading partners or products.",
+        )
+
         return Function(
             fn_name="search_agents",
             fn_description="Get a list of all available trading agents and what they're selling. Use this function before initiating a job to discover potential trading partners. Each agent's entry will show their ID, name, type, walletAddress, description and product catalog with prices.",
-            args=[
-                {
-                    "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.",
-                },
-            ],
+            args=[reasoning_arg, keyword_arg],
             executable=self._search_agents_executable
         )
 
     @property
     def initiate_job(self) -> Function:
+        seller_wallet_address_arg = Argument(
+            name="sellerWalletAddress",
+            type="string",
+            description="The seller's agent wallet address you want to buy from",
+        )
+
+        price_arg = Argument(
+            name="price",
+            type="string",
+            description="Offered price for service",
+        )
+
+        reasoning_arg = Argument(
+            name="reasoning",
+            type="string",
+            description="Why you are making this purchase request",
+        )
+
+        service_requirements_arg = Argument(
+            name="serviceRequirements",
+            type="string",
+            description="Detailed specifications for service-based items",
+        )
+        
+        require_evaluation_arg = Argument(
+            name="requireEvaluation",
+            type="boolean",
+            description="Decide if your job request is complex enough to spend money for evaluator agent to assess the relevancy of the output. For simple job request like generate image, insights, facts does not require evaluation. For complex and high level job like generating a promotion video, a marketing narrative, a trading signal should require evaluator to assess result relevancy.",
+        )
+        
+        evaluator_keyword_arg = Argument(
+            name="evaluatorKeyword",
+            type="string",
+            description="Keyword to search for a evaluator",
+        )
+
+        args = [seller_wallet_address_arg, price_arg, reasoning_arg, service_requirements_arg, require_evaluation_arg, evaluator_keyword_arg]
+        
+        if hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None:
+            tweet_content_arg = Argument(
+                name="tweetContent",
+                type="string",
+                description="Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
+            )
+            args.append(tweet_content_arg)
+            
         return Function(
             fn_name="initiate_job",
             fn_description="Creates a purchase request for items from another agent's catalog. Only for use when YOU are the buyer. The seller must accept your request before you can proceed with payment.",
-            args=[
-                {
-                    "name": "sellerWalletAddress",
-                    "type": "string",
-                    "description": "The seller's agent wallet address you want to buy from",
-                },
-                {
-                    "name": "price",
-                    "type": "string",
-                    "description": "Offered price for service",
-                },
-                {
-                    "name": "reasoning",
-                    "type": "string",
-                    "description": "Why you are making this purchase request",
-                },
-                {
-                    "name": "serviceRequirements",
-                    "type": "string",
-                    "description": "Detailed specifications for service-based items",
-                },
-                {
-                    "name": "tweetContent",
-                    "type": "string",
-                    "description": "Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
-                },
-            ],
+            args=args,
             executable=self._initiate_job_executable
         )
 
-    def _initiate_job_executable(self, sellerWalletAddress: str, price: str, reasoning: str, serviceRequirements: str, tweetContent : str) -> Tuple[FunctionResultStatus, str, dict]:
+    def _initiate_job_executable(self, sellerWalletAddress: str, price: str, reasoning: str, serviceRequirements: str, requireEvaluation: bool, evaluatorKeyword: str, tweetContent: Optional[str] = None) -> Tuple[FunctionResultStatus, str, dict]:
         if not price:
             return FunctionResultStatus.FAILED, "Missing price - specify how much you're offering per unit", {}
-
+        
+        if not reasoning:
+            return FunctionResultStatus.FAILED, "Missing reasoning - explain why you're making this purchase request", {}
+        
         try:
             state = self.get_acp_state()
 
             if state["jobs"]["active"]["asABuyer"]:
                 return FunctionResultStatus.FAILED, "You already have an active job as a buyer", {}
-
+            
+            if not sellerWalletAddress:
+                return FunctionResultStatus.FAILED, "Missing seller wallet address - specify the agent you want to buy from", {}
+            
+            if bool(requireEvaluation) and not evaluatorKeyword:
+                return FunctionResultStatus.FAILED, "Missing validator keyword - provide a keyword to search for a validator", {}
+            
+            evaluatorAddress = self.acp_token_client.get_agent_wallet_address()
+            
+            if bool(requireEvaluation):
+                validators = self.acp_client.browse_agents(self.evaluator_cluster, evaluatorKeyword)
+                
+                if len(validators) == 0:
+                    return FunctionResultStatus.FAILED, "No evaluator found - try a different keyword", {}
+                
+                evaluatorAddress = validators[0].wallet_address
+            
             # ... Rest of validation logic ...
             job_id = self.acp_client.create_job(
                 sellerWalletAddress,
                 float(price),
-                serviceRequirements
+                serviceRequirements,
+                evaluatorAddress
             )
             
-            if (self.twitter_plugin is not None and tweetContent is not None):
+            if (hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None and tweetContent is not None):
                 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):
@@ -209,35 +325,42 @@ class AcpPlugin:
 
     @property
     def respond_job(self) -> Function:
+        job_id_arg = Argument(
+            name="jobId",
+            type="integer",
+            description="The job ID you are responding to",
+        )
+
+        decision_arg = Argument(
+            name="decision",
+            type="string",
+            description="Your response: 'ACCEPT' or 'REJECT'",
+        )
+
+        reasoning_arg = Argument(
+            name="reasoning",
+            type="string",
+            description="Why you made this decision",
+        )
+        
+        args = [job_id_arg, decision_arg, reasoning_arg]
+        
+        if hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None:
+            tweet_content_arg = Argument(
+                name="tweetContent",
+                type="string",
+                description="Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
+            )
+            args.append(tweet_content_arg)
+
         return Function(
             fn_name="respond_to_job",
             fn_description="Accepts or rejects an incoming 'request' job",
-            args=[
-                {
-                    "name": "jobId",
-                    "type": "string",
-                    "description": "The job ID you are responding to",
-                },
-                {
-                    "name": "decision",
-                    "type": "string",
-                    "description": "Your response: 'ACCEPT' or 'REJECT'",
-                },
-                {
-                    "name": "reasoning",
-                    "type": "string",
-                    "description": "Why you made this decision",
-                },
-                {
-                    "name": "tweetContent",
-                    "type": "string",
-                    "description": "Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
-                },
-            ],
+            args=args,
             executable=self._respond_job_executable
         )
 
-    def _respond_job_executable(self, jobId: str, decision: str, reasoning: str, tweetContent: str) -> Tuple[FunctionResultStatus, str, dict]:
+    def _respond_job_executable(self, jobId: int, decision: str, reasoning: str, tweetContent: Optional[str] = None) -> Tuple[FunctionResultStatus, str, dict]:
         if not jobId:
             return FunctionResultStatus.FAILED, "Missing job ID - specify which job you're responding to", {}
         
@@ -251,7 +374,7 @@ class AcpPlugin:
             state = self.get_acp_state()
             
             job = next(
-                (c for c in state["jobs"]["active"]["asASeller"] if c["jobId"] == int(jobId)),
+                (c for c in state["jobs"]["active"]["asASeller"] if c["jobId"] == jobId),
                 None
             )
 
@@ -262,13 +385,13 @@ class AcpPlugin:
                 return FunctionResultStatus.FAILED, f"Cannot respond - job is in '{job['phase']}' phase, must be in 'request' phase", {}
 
             self.acp_client.response_job(
-                int(jobId),
+                jobId,
                 decision == "ACCEPT",
                 job["memo"][0]["id"],
                 reasoning
             )
             
-            if (self.twitter_plugin is not None):
+            if (hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None and tweetContent is not None):
                 tweet_history = job.get("tweetHistory", [])
                 tweet_id = tweet_history[-1].get("tweetId") if tweet_history else None
                 if (tweet_id is not None):
@@ -288,35 +411,42 @@ class AcpPlugin:
 
     @property
     def pay_job(self) -> Function:
+        job_id_arg = Argument(
+            name="jobId",
+            type="integer",
+            description="The job ID you are paying for",
+        )
+
+        amount_arg = Argument(
+            name="amount",
+            type="float",
+            description="The total amount to pay",  # in Ether
+        )
+
+        reasoning_arg = Argument(
+            name="reasoning",
+            type="string",
+            description="Why you are making this payment",
+        )
+
+        args = [job_id_arg, amount_arg, reasoning_arg]
+        
+        if hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None:
+            tweet_content_arg = Argument(
+                name="tweetContent",
+                type="string",
+                description="Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
+            )
+            args.append(tweet_content_arg)
+
         return Function(
             fn_name="pay_job",
             fn_description="Processes payment for an accepted purchase request",
-            args=[
-                {
-                    "name": "jobId",
-                    "type": "number",
-                    "description": "The job ID you are paying for",
-                },
-                {
-                    "name": "amount",
-                    "type": "number",
-                    "description": "The total amount to pay",
-                },
-                {
-                    "name": "reasoning",
-                    "type": "string",
-                    "description": "Why you are making this payment",
-                },
-                {
-                    "name": "tweetContent",
-                    "type": "string",
-                    "description": "Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
-                },
-            ],
+            args=args,
             executable=self._pay_job_executable
         )
 
-    def _pay_job_executable(self, jobId: str, amount: str, reasoning: str, tweetContent: str) -> Tuple[FunctionResultStatus, str, dict]:
+    def _pay_job_executable(self, jobId: int, amount: float, reasoning: str, tweetContent: Optional[str] = None) -> Tuple[FunctionResultStatus, str, dict]:
         if not jobId:
             return FunctionResultStatus.FAILED, "Missing job ID - specify which job you're paying for", {}
 
@@ -330,7 +460,7 @@ class AcpPlugin:
             state = self.get_acp_state()
             
             job = next(
-                (c for c in state["jobs"]["active"]["asABuyer"] if c["jobId"] == int(jobId)),
+                (c for c in state["jobs"]["active"]["asABuyer"] if c["jobId"] == jobId),
                 None
             )
 
@@ -342,13 +472,13 @@ class AcpPlugin:
 
 
             self.acp_client.make_payment(
-                int(jobId),
-                float(amount),
+                jobId,
+                amount,
                 job["memo"][0]["id"],
                 reasoning
             )
             
-            if (self.twitter_plugin is not None):
+            if (hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None and tweetContent is not None):
                 tweet_history = job.get("tweetHistory", [])
                 tweet_id = tweet_history[-1].get("tweetId") if tweet_history else None
                 if (tweet_id is not None):
@@ -368,40 +498,48 @@ class AcpPlugin:
 
     @property
     def deliver_job(self) -> Function:
+        job_id_arg = Argument(
+            name="jobId",
+            type="integer",
+            description="The job ID you are delivering for",
+        )
+
+        deliverable_type_arg = Argument(
+            name="deliverableType",
+            type="string",
+            description="Type of the deliverable",
+        )
+
+        deliverable_arg = Argument(
+            name="deliverable",
+            type="string",
+            description="The deliverable item",
+        )
+
+        reasoning_arg = Argument(
+            name="reasoning",
+            type="string",
+            description="Why you are making this delivery",
+        )
+
+        args = [job_id_arg, deliverable_type_arg, deliverable_arg, reasoning_arg]
+        
+        if hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None:
+            tweet_content_arg = Argument(
+                name="tweetContent",
+                type="string",
+                description="Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
+            )
+            args.append(tweet_content_arg)
+
         return Function(
             fn_name="deliver_job",
             fn_description="Completes a sale by delivering items to the buyer",
-            args=[
-                {
-                    "name": "jobId",
-                    "type": "string",
-                    "description": "The job ID you are delivering for",
-                },
-                {
-                    "name": "deliverableType",
-                    "type": "string",
-                    "description": "Type of the deliverable",
-                },
-                {
-                    "name": "deliverable",
-                    "type": "string",
-                    "description": "The deliverable item",
-                },
-                {
-                    "name": "reasoning",
-                    "type": "string",
-                    "description": "Why you are making this delivery",
-                },
-                {
-                    "name": "tweetContent",
-                    "type": "string",
-                    "description": "Tweet content that will be posted about this job. Must include the seller's Twitter handle (with @ symbol) to notify them",
-                },
-            ],
+            args=args,
             executable=self._deliver_job_executable
         )
 
-    def _deliver_job_executable(self, jobId: str, deliverableType: str, deliverable: str, reasoning: str, tweetContent: str) -> Tuple[FunctionResultStatus, str, dict]:
+    def _deliver_job_executable(self, jobId: int, deliverableType: str, deliverable: str, reasoning: str, tweetContent: Optional[str] = None) -> Tuple[FunctionResultStatus, str, dict]:
         if not jobId:
             return FunctionResultStatus.FAILED, "Missing job ID - specify which job you're delivering for", {}
             
@@ -415,7 +553,7 @@ class AcpPlugin:
             state = self.get_acp_state()
             
             job = next(
-                (c for c in state["jobs"]["active"]["asASeller"] if c["jobId"] == int(jobId)),
+                (c for c in state["jobs"]["active"]["asASeller"] if c["jobId"] == jobId),
                 None
             )
 
@@ -433,17 +571,18 @@ class AcpPlugin:
             if not produced:
                 return FunctionResultStatus.FAILED, "Cannot deliver - you should be producing the deliverable first before delivering it", {}
 
-            deliverable = {
+            deliverable: dict = {
                 "type": deliverableType,
                 "value": deliverable
             }
 
             self.acp_client.deliver_job(
-                int(jobId),
+                jobId,
                 json.dumps(deliverable),
             )
             
-            if (self.twitter_plugin is not None):
+            if (hasattr(self, 'twitter_plugin') and self.twitter_plugin is not None and tweetContent is not None):
+
                 tweet_history = job.get("tweetHistory", [])
                 tweet_id = tweet_history[-1].get("tweetId") if tweet_history else None
                 if (tweet_id is not None):

acp_plugin_gamesdk/interface.py

@@ -1,6 +1,6 @@
 from dataclasses import dataclass
 from enum import IntEnum, Enum
-from typing import List, Dict
+from typing import List, Dict, Literal, Optional
 
 @dataclass
 class AcpOffering:
@@ -12,7 +12,7 @@ class AcpAgent:
     name: str
     description: str
     wallet_address: str
-    offerings: List[AcpOffering]
+    offerings: Optional[List[AcpOffering]]
     
 class AcpJobPhases(IntEnum):
     REQUEST = 0
@@ -46,7 +46,7 @@ class AcpJob:
 
 @dataclass
 class IDeliverable:
-    type: str
+    type: Literal["url", "text"]
     value: str
 
 @dataclass

{acp_plugin_gamesdk-0.1.3.dist-info → acp_plugin_gamesdk-0.1.5.dist-info}/METADATA

@@ -1,12 +1,11 @@
 Metadata-Version: 2.3
 Name: acp-plugin-gamesdk
-Version: 0.1.3
+Version: 0.1.5
 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
+Requires-Python: >=3.10,<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
@@ -17,10 +16,12 @@ 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: python-socketio (>=5.11.1,<6.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)
+Requires-Dist: websocket-client (>=1.7.0,<2.0.0)
 Description-Content-Type: text/markdown
 
 # ACP Plugin
@@ -46,21 +47,22 @@ Description-Content-Type: text/markdown
 ---
 
 > **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.
-> 
 
 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
@@ -70,28 +72,32 @@ The Agent Commerce Protocol (ACP) plugin is used to handle trading transactions
    - 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:
+
 ```bash
 poetry install
 ```
 
 ## Usage
+
 1. Activate the virtual environment by running:
- ```bash
- eval $(poetry env activate)
- ```
+
+```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
- ```
+```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:
 
@@ -102,27 +108,34 @@ acp_plugin = AcpPlugin(
         acp_token_client = AcpToken(
             "<your-whitelisted-wallet-private-key>",
             "<your-agent-wallet-address>",
-            "<your-chain-here>"
-        )
+            "<your-chain-here>",
+            "<your-acp-base-url>"
+        ),
+        cluster = "<cluster>",
+        twitter_plugin = "<twitter_plugin_instance>",
+        evaluator_cluster = "<evaluator_cluster>",
+        on_evaluate = "<on_evaluate_function>"
     )
 )
 ```
 
- > Note: 
- > - Your agent wallet address for your buyer and seller should be different.
- > - Speak to a DevRel (Celeste/John) to get a GAME Dev API key
+> Note:
+>
+> - Your agent wallet address 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: 
+> 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)
+>   ![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)
+>   ![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)
+>   ![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:
 
-4. (optional) If you want to use GAME's twitter client with the ACP plugin, you can initialize it by running:
 ```python
 twitter_client_options = {
     "id": "test_game_twitter_plugin",
@@ -139,16 +152,41 @@ acp_plugin = AcpPlugin(
         acp_token_client = AcpToken(
             "<your-whitelisted-wallet-private-key>",
             "<your-agent-wallet-address>",
-            "<your-chain-here>"
+            "<your-chain-here>",
+            "<your-acp-base-url>"
         ),
         twitter_plugin=GameTwitterPlugin(twitter_client_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/)
+\*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. (Optional) If you want to listen to the `ON_EVALUATE` event, you can implement the `on_evaluate` function.
+
+```python
+def on_evaluate(deliverable: IDeliverable) -> Tuple[bool, str]:
+    print(f"Evaluating deliverable: {deliverable}")
+    return True, "Default evaluation"
+```
+
+```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>",
+            "<your-acp-base-url>"
+        ),
+        evaluator_cluster = "<evaluator_cluster>",
+        on_evaluate = on_evaluate # <--- This is the on_evaluate function
+    )
+)
+```
 
-5. Integrate the ACP plugin worker into your agent by running:
+6. Integrate the ACP plugin worker into your agent by running:
 
 ```python
 acp_worker =  acp_plugin.get_worker()
@@ -162,55 +200,61 @@ agent = Agent(
 )
 ```
 
-1. Buyer-specific configurations
+7. 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
+   ```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."
+   ```
+
+8. 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."
-    ```
+
+   ```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
-        })
-    ```
+   ```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 == 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": 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. |
-| reset_state | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh. |
+| 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.                                                                                        |
+| reset_state             | Resets the ACP plugin's internal state, clearing all active jobs. Useful for testing or when you need to start fresh.                             |
 
 ## Tools
 
@@ -225,15 +269,15 @@ To register your agent, please head over to the [agent registry](https://acp-sta
 
 1. Click on "Join ACP" button
 
-    <img src="../../docs/imgs/Join-acp.png" width="400" alt="ACP Agent Registry">
+<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">
+<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">
+<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.
 

acp_plugin_gamesdk-0.1.5.dist-info/RECORD

@@ -0,0 +1,8 @@
+acp_plugin_gamesdk/acp_client.py,sha256=Gs8Id-ecDwuJsm4agoHRp2dv_bKSBXDq0XGlHd99du8,8070
+acp_plugin_gamesdk/acp_plugin.py,sha256=ft6fTwmt9HVzFRXc1PVTdigcTVLjRfOeu9enNN2RSYQ,25802
+acp_plugin_gamesdk/acp_token.py,sha256=CL-0Ww1i0tzDNj0sAuY3DvlWIKrEGoMcb0Z69e5X9og,11720
+acp_plugin_gamesdk/acp_token_abi.py,sha256=nllh9xOuDXxFFdhLklTTdtZxWZd2LcUTBoOP2d9xDTA,22319
+acp_plugin_gamesdk/interface.py,sha256=5jStptqzT_dTlO-d51Xp4PaOVYeFV6uss70GvpLfCEM,1401
+acp_plugin_gamesdk-0.1.5.dist-info/METADATA,sha256=2H8SH3wzvquhJTrquxqwh7kopWnmDw8fDmwYwBkFbGk,11410
+acp_plugin_gamesdk-0.1.5.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
+acp_plugin_gamesdk-0.1.5.dist-info/RECORD,,

acp_plugin_gamesdk-0.1.3.dist-info/RECORD

@@ -1,8 +0,0 @@
-acp_plugin_gamesdk/acp_client.py,sha256=1mHE6h3E4DET-INSxw6O5REAX1drRpiAxphJt1EFxxQ,7320
-acp_plugin_gamesdk/acp_plugin.py,sha256=Cr7fsTXIeaww9CENmx0KPN65lf6KRir-n8jpVPi5ksE,20288
-acp_plugin_gamesdk/acp_token.py,sha256=CL-0Ww1i0tzDNj0sAuY3DvlWIKrEGoMcb0Z69e5X9og,11720
-acp_plugin_gamesdk/acp_token_abi.py,sha256=nllh9xOuDXxFFdhLklTTdtZxWZd2LcUTBoOP2d9xDTA,22319
-acp_plugin_gamesdk/interface.py,sha256=HxGHUc1VhdTGpFNk1JDwwb9n73IZdI08iDJttB0qB_s,1353
-acp_plugin_gamesdk-0.1.3.dist-info/METADATA,sha256=aHLfn_gLmFaKjyJrvzzIQ90UoZfmX9SK_bu7giWn1Bo,9691
-acp_plugin_gamesdk-0.1.3.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-acp_plugin_gamesdk-0.1.3.dist-info/RECORD,,