feat: add polling mode examples

Author: Ang-dot

examples/acp_base/polling_mode/.env.example

@@ -0,0 +1,9 @@
+WHITELISTED_WALLET_PRIVATE_KEY=<whitelisted-wallet-private-key>
+BUYER_AGENT_WALLET_ADDRESS=<buyer-agent-wallet-address>
+BUYER_ENTITY_ID=<buyer-entity-id>
+
+SELLER_AGENT_WALLET_ADDRESS=<seller-agent-wallet-address>
+SELLER_ENTITY_ID=<seller-entity-id>
+
+EVALUATOR_AGENT_WALLET_ADDRESS=<evaluator-agent-wallet-address>
+EVALUATOR_ENTITY_ID=<evaluator-entity-id>

examples/acp_base/polling_mode/buyer.py

@@ -0,0 +1,82 @@
+import time
+from datetime import datetime, timedelta, timezone
+from dotenv import load_dotenv
+
+from virtuals_acp import VirtualsACP, ACPJob, ACPJobPhase
+from virtuals_acp.env import EnvSettings
+
+load_dotenv(override=True)
+
+
+# --- Configuration for the job polling interval ---
+POLL_INTERVAL_SECONDS = 20
+# --------------------------------------------------
+
+
+def buyer():
+    env = EnvSettings()
+    acp = VirtualsACP(
+        wallet_private_key=env.WHITELISTED_WALLET_PRIVATE_KEY,
+        agent_wallet_address=env.BUYER_AGENT_WALLET_ADDRESS,
+        entity_id=env.BUYER_ENTITY_ID,
+    )
+    print(f"Buyer ACP Initialized. Agent: {acp.agent_address}")
+
+    # Browse available agents based on a keyword and cluster name
+    relevant_agents = acp.browse_agents(
+        keyword="Molly",
+        cluster="yang-mainnet-test",
+        graduated=False,
+    )
+    print(f"Relevant agents: {relevant_agents}")
+
+    # Pick one of the agents based on your criteria (in this example we just pick the first one)
+    chosen_agent = relevant_agents[0]
+
+    # Pick one of the service offerings based on your criteria (in this example we just pick the first one)
+    chosen_job_offering = chosen_agent.offerings[0]
+
+    # 1. Initiate Job
+    print(f"\nInitiating job with Seller: {chosen_agent.wallet_address}, Evaluator: {env.EVALUATOR_AGENT_WALLET_ADDRESS}")
+
+    job_id = chosen_job_offering.initiate_job(
+        # <your_schema_field> can be found in your ACP Visualiser's "Edit Service" pop-up.
+        # Reference: (./images/specify_requirement_toggle_switch.png)
+        service_requirement={"<your_schema_field>": "Help me to generate a flower meme."},
+        evaluator_address=env.EVALUATOR_AGENT_WALLET_ADDRESS,
+        expired_at=datetime.now() + timedelta(days=1),
+    )
+
+    print(f"Job {job_id} initiated")
+    # 2. Wait for Seller's acceptance memo (which sets next_phase to TRANSACTION)
+    print(f"\nWaiting for Seller to accept job {job_id}...")
+
+    while True:
+        # wait for some time before checking job again
+        time.sleep(POLL_INTERVAL_SECONDS)
+        job: ACPJob = acp.get_job_by_onchain_id(job_id)
+        print(f"Polling Job {job_id}: Current Phase: {job.phase.name}")
+
+        if job.phase == ACPJobPhase.NEGOTIATION:
+            # Check if there's a memo that indicates next phase is TRANSACTION
+            for memo in job.memos:
+                if memo.next_phase == ACPJobPhase.TRANSACTION:
+                    print("Paying job", job_id)
+                    job.pay(job.price)
+        elif job.phase == ACPJobPhase.REQUEST:
+            print(f"Job {job_id} still in REQUEST phase. Waiting for seller...")
+        elif job.phase == ACPJobPhase.EVALUATION:
+            print(f"Job {job_id} is in EVALUATION. Waiting for evaluator's decision...")
+        elif job.phase == ACPJobPhase.TRANSACTION:
+            print(f"Job {job_id} is in TRANSACTION. Waiting for seller to deliver...")
+        elif job.phase == ACPJobPhase.COMPLETED:
+            print("Job completed", job)
+            break
+        elif job.phase == ACPJobPhase.REJECTED:
+            print("Job rejected", job)
+            break
+
+    print("\n--- Buyer Script Finished ---")
+
+if __name__ == "__main__":
+    buyer()

examples/client_workflows/evaluator.py renamed to examples/acp_base/polling_mode/evaluator.py

@@ -1,36 +1,32 @@
-import os
 import time
 from typing import List
 from dotenv import load_dotenv
 
 from virtuals_acp import VirtualsACP, ACPJob, ACPJobPhase
-from virtuals_acp.configs import BASE_SEPOLIA_CONFIG
+from virtuals_acp.env import EnvSettings
 
 load_dotenv(override=True)
 
-EVALUATOR_PRIVATE_KEY = os.environ.get("WHITELISTED_WALLET_PRIVATE_KEY")
-EVALUATOR_WALLET_ADDRESS = os.environ.get("EVALUATOR_AGENT_WALLET_ADDRESS")
 
+# --- Configuration for the job polling interval ---
 POLL_INTERVAL_SECONDS = 20
+# --------------------------------------------------
 
-if not all([EVALUATOR_PRIVATE_KEY, EVALUATOR_WALLET_ADDRESS]):
-    print("Error: Ensure EVALUATOR_PRIVATE_KEY and EVALUATOR_WALLET_ADDRESS are set.")
-    exit(1)
+def evaluator():
+    env = EnvSettings()
 
-def main():
-    print("--- Evaluator Script (Simplified Direct Client Usage) ---")
-    evaluator_acp = VirtualsACP(
-        wallet_private_key=EVALUATOR_PRIVATE_KEY,
-        agent_wallet_address=EVALUATOR_WALLET_ADDRESS,
-        config=BASE_SEPOLIA_CONFIG
+    acp = VirtualsACP(
+        wallet_private_key=env.WHITELISTED_WALLET_PRIVATE_KEY,
+        agent_wallet_address=env.EVALUATOR_AGENT_WALLET_ADDRESS,
+        entity_id=env.EVALUATOR_ENTITY_ID,
     )
-    print(f"Evaluator ACP Initialized. Agent: {evaluator_acp.agent_address}")
+    print(f"Evaluator ACP Initialized. Agent: {acp.agent_address}")
 
     evaluated_deliverables = set() # Store (job_id, deliverable_memo_id) to avoid re-evaluation
 
     while True:
-        print(f"\nEvaluator: Polling for jobs assigned to {EVALUATOR_WALLET_ADDRESS} requiring evaluation...")
-        active_jobs_list: List[ACPJob] = evaluator_acp.get_active_jobs()
+        print(f"\nEvaluator: Polling for jobs assigned to {acp.agent_address} requiring evaluation...")
+        active_jobs_list: List[ACPJob] = acp.get_active_jobs()
 
         if not active_jobs_list:
             print("Evaluator: No active jobs found in this poll.")
@@ -39,36 +35,40 @@ def main():
 
         for job_summary in active_jobs_list:
             onchain_job_id = job_summary.id
-            
+
             try:
-                job_details = evaluator_acp.get_job_by_onchain_id(onchain_job_id)
-                current_phase = job_details.phase
-                
+                job = acp.get_job_by_onchain_id(onchain_job_id)
+                current_phase = job.phase
+
+                # Ensure this job is for the current evaluator
+                if job.evaluator_address != acp.agent_address:
+                    continue
+
                 if current_phase == ACPJobPhase.EVALUATION:
                     print(f"Evaluator: Found Job {onchain_job_id} in EVALUATION phase.")
-                    
+
                     # Find the seller's deliverable memo. Its next_phase should be COMPLETED.
                     seller_deliverable_memo_to_sign = None
-                    for memo in reversed(job_details.memos): # Check latest first
+                    for memo in reversed(job.memos): # Check latest first
                         if ACPJobPhase(memo.next_phase) == ACPJobPhase.COMPLETED:
                             seller_deliverable_memo_to_sign = memo
                             break
-                    
+
                     if seller_deliverable_memo_to_sign:
                         deliverable_key = (onchain_job_id, seller_deliverable_memo_to_sign.id)
                         if deliverable_key in evaluated_deliverables:
-                            # print(f"Deliverable memo {seller_deliverable_memo_to_sign.id} for job {onchain_job_id} already processed.")
+                            print(f"Deliverable memo {seller_deliverable_memo_to_sign.id} for job {onchain_job_id} already processed.")
                             continue
 
                         print(f"  Job {onchain_job_id}: Found deliverable memo {seller_deliverable_memo_to_sign.id} to evaluate.")
                         print(f"  Deliverable Content: {seller_deliverable_memo_to_sign.content}")
-                        
+
                         # Simple evaluation logic: always accept
                         accept_the_delivery = True
                         evaluation_reason = "Deliverable looks great, approved!"
-                        
+
                         print(f"  Job {onchain_job_id}: Evaluating... Accepting: {accept_the_delivery}")
-                        evaluator_acp.evaluate_job_delivery(
+                        acp.evaluate_job_delivery(
                             memo_id_of_deliverable=seller_deliverable_memo_to_sign.id,
                             accept=accept_the_delivery,
                             reason=evaluation_reason
@@ -77,14 +77,16 @@ def main():
                         evaluated_deliverables.add(deliverable_key)
                     else:
                         print(f"  Job {onchain_job_id} in EVALUATION, but no deliverable memo (next_phase=COMPLETED) found yet.")
+                elif current_phase in [ACPJobPhase.REQUEST, ACPJobPhase.NEGOTIATION]:
+                    print(f"Evaluator: Job {onchain_job_id} is in {current_phase.name} phase. Waiting for job to be delivered.")
+                    continue
                 elif current_phase in [ACPJobPhase.COMPLETED, ACPJobPhase.REJECTED]:
                     print(f"Evaluator: Job {onchain_job_id} is already in {current_phase.name}. No action.")
-                    # Potentially add to a "handled" set if not using evaluated_deliverables
-            
+
             except Exception as e:
                 print(f"Evaluator: Error processing job {onchain_job_id}: {e}")
-        
+
         time.sleep(POLL_INTERVAL_SECONDS)
 
 if __name__ == "__main__":
-    main()
+    evaluator()

examples/client_workflows/seller.py renamed to examples/acp_base/polling_mode/seller.py

@@ -1,63 +1,53 @@
-import os
 import time
 import json
 from typing import List
 from dotenv import load_dotenv
 
 from virtuals_acp import VirtualsACP, ACPJob, ACPJobPhase
-from virtuals_acp.configs import BASE_SEPOLIA_CONFIG
+from virtuals_acp.env import EnvSettings
 
 load_dotenv(override=True)
 
-SELLER_PRIVATE_KEY = os.environ.get("WHITELISTED_WALLET_PRIVATE_KEY")
-SELLER_WALLET_ADDRESS = os.environ.get("SELLER_AGENT_WALLET_ADDRESS")
-
-if not all([SELLER_PRIVATE_KEY, SELLER_WALLET_ADDRESS]):
-    print("Error: Ensure SELLER_PRIVATE_KEY and SELLER_WALLET_ADDRESS are set.")
-    exit(1)
-
-DELIVERABLE_CONTENT = {
-    "type": "url",
-    "value": "https://virtuals.io/delivered_meme.png",
-    "notes": "Your meme is ready!"
-}
 
+# --- Configuration for the job polling interval ---
 POLL_INTERVAL_SECONDS = 20
+# --------------------------------------------------
+
+def seller():
+    env = EnvSettings()
 
-def main():
-    print("--- Seller Script ---")
-    seller_acp = VirtualsACP(
-        wallet_private_key=SELLER_PRIVATE_KEY,
-        agent_wallet_address=SELLER_WALLET_ADDRESS,
-        config=BASE_SEPOLIA_CONFIG
+    acp = VirtualsACP(
+        wallet_private_key=env.WHITELISTED_WALLET_PRIVATE_KEY,
+        agent_wallet_address=env.SELLER_AGENT_WALLET_ADDRESS,
+        entity_id=env.SELLER_ENTITY_ID,
     )
-    print(f"Seller ACP Initialized. Agent: {seller_acp.agent_address}")
+    print(f"Seller ACP Initialized. Agent: {acp.agent_address}")
 
     # Keep track of jobs to avoid reprocessing in this simple loop
     # job_id: {"responded_to_request": bool, "delivered_work": bool}
     processed_job_stages = {}
 
     while True:
-        print(f"\nSeller: Polling for active jobs for {SELLER_WALLET_ADDRESS}...")
-        active_jobs_list: List[ACPJob] = seller_acp.get_active_jobs()
+        print(f"\nSeller: Polling for active jobs for {env.SELLER_AGENT_WALLET_ADDRESS}...")
+        active_jobs_list: List[ACPJob] = acp.get_active_jobs()
 
         if not active_jobs_list:
             print("Seller: No active jobs found in this poll.")
             time.sleep(POLL_INTERVAL_SECONDS)
             continue
 
-        for job_summary in active_jobs_list:
-            onchain_job_id = job_summary.id
+        for job in active_jobs_list:
+            onchain_job_id = job.id
 
             # Ensure this job is for the current seller
-            if job_summary.provider_address != seller_acp.agent_address:
+            if job.provider_address != acp.agent_address:
                 continue
 
             job_stages = processed_job_stages.get(onchain_job_id, {})
 
             try:
                 # Fetch full details to get current phase and memos
-                job_details = seller_acp.get_job_by_onchain_id(onchain_job_id)
+                job_details = acp.get_job_by_onchain_id(onchain_job_id)
                 current_phase = job_details.phase
                 print(f"Seller: Checking job {onchain_job_id}. Current Phase: {current_phase.name}")
 
@@ -72,7 +62,7 @@ def main():
 
                     if buyers_initial_memo_to_sign:
                         print(f"Seller: Job {onchain_job_id} is in REQUEST. Responding to buyer's memo {buyers_initial_memo_to_sign.id}...")
-                        seller_acp.respond_to_job_memo(
+                        acp.respond_to_job_memo(
                             job_id=onchain_job_id,
                             memo_id=buyers_initial_memo_to_sign.id, # ID of the memo created by Buyer
                             accept=True,
@@ -95,9 +85,12 @@ def main():
 
                     if buyers_payment_confirmation_memo:
                         print(f"Seller: Job {onchain_job_id} is PAID (TRANSACTION phase). Submitting deliverable...")
-                        seller_acp.submit_job_deliverable(
+                        acp.submit_job_deliverable(
                             job_id=onchain_job_id,
-                            deliverable_content=json.dumps(DELIVERABLE_CONTENT)
+                            deliverable_content=json.dumps({
+                                "type": "url",
+                                "value": "https://example.com"
+                            })
                         )
                         print(f"Seller: Deliverable submitted for job {onchain_job_id}. Job should move to EVALUATION.")
                         job_stages["delivered_work"] = True
@@ -118,4 +111,4 @@ def main():
         time.sleep(POLL_INTERVAL_SECONDS)
 
 if __name__ == "__main__":
-    main()
+    seller()