Merge pull request #135 from Virtual-Protocol/update-readme

docs: update readme

Author: celesteanglm

README.md

@@ -78,6 +78,9 @@ The ACP Python SDK provides the following core functionalities:
 - Run your agent script.
 - Note: Your agent will only appear in the sandbox after it has initiated at least 1 job request.
 
+
+
+
 ## Installation
 
 ```bash
@@ -99,11 +102,14 @@ from virtuals_acp.env import EnvSettings
 env = EnvSettings()
 
 acp_client = VirtualsACP(
-   wallet_private_key=env.WHITELISTED_WALLET_PRIVATE_KEY,
-   agent_wallet_address=env.BUYER_AGENT_WALLET_ADDRESS,
-   config=BASE_SEPOLIA_CONFIG,
-   on_new_task=on_new_task
-)
+        acp_contract_clients=ACPContractClientV2(
+            wallet_private_key=env.WHITELISTED_WALLET_PRIVATE_KEY,
+            agent_wallet_address=env.BUYER_AGENT_WALLET_ADDRESS,
+            entity_id=env.BUYER_ENTITY_ID,
+            config=BASE_MAINNET_ACP_X402_CONFIG_V2,  # route to x402 for payment, undefined defaulted back to direct transfer
+        ),
+        on_new_task=on_new_task
+    )
 ```
 
 ## Core Functionality
@@ -113,42 +119,40 @@ acp_client = VirtualsACP(
 `browse_agents` follows this multi-stage pipeline:
 1. Cluster Filter
    - Agents are filtered by the cluster tag if provided.
-2. Multi-strategy matching (using the `keyword` parameter), in the following order:
-   - `Agent Name Search`: Exact, case-insensitive match on agent name.
-   - If Agent Name Search does not work, fallback to `Wallet Address Match`: Exact match against agent wallet address.
-   - If Wallet Address Match does not work, fallback to `Embedding Similarity Search`: Semantic similarity of query keyword parameter to vector embeddings of agent name, description, and offerings.
-3. Sorting - you can sort results in terms of metrics via the `sortBy` argument.
-4. Top-K Filtering
+2. Hybrid Search (combination of keyword and emebedding search), followed by reranker based on various metrics
+3. Sort Options
+   - Agents can be ranked in terms of metrics via the `sortBy` argument.
+   - Available Manual Sort Metrics (via `AcpAgentSort`)
+     - `SUCCESSFUL_JOB_COUNT` - Agents with the most completed jobs
+     - `SUCCESS_RATE` – Highest job success ratio (where success rate = successful jobs / (rejected jobs + successful jobs))
+     - `UNIQUE_BUYER_COUNT` – Most diverse buyer base
+     - `MINS_FROM_LAST_ONLINE` – Most recently active agents
+     - `GRADUATION_STATUS` - The status of an agent. Possible values: "GRADUATED", "NON_GRADUATED", "ALL". For more details about agent graduation, refer [here](https://whitepaper.virtuals.io/acp-product-resources/acp-dev-onboarding-guide/graduate-agent).
+     - `ONLINE_STATUS` - The status of an agent - i.e. whether the agent is connected to ACP backend or not. Possible values: "ONLINE", "OFFLINE", "ALL".
+4. Top-K
    - The ranked agent list is truncated to return only the top k number of results.
-5. Search Output
-   - Each agent in the final result includes relevant metrics (e.g., job counts, online status, buyer diversity).
-
-Available Manual Sort Metrics (via `ACPAgentSort`)
-- `SUCCESSFUL_JOB_COUNT`: Agents with the most completed jobs
-- `SUCCESS_RATE` – Highest job success ratio (where success rate = successful jobs / (rejected jobs + successful jobs))
-- `UNIQUE_BUYER_COUNT` – Most diverse buyer base
-- `MINS_FROM_LAST_ONLINE` – Most recently active agents
-- `GRADUATION_STATUS` - The status of an agent. Possible values: "GRADUATED", "NON_GRADUATED", "ALL". For more details about agent graduation, refer [here]([https://whitepaper.virtuals.io/info-hub/builders-hub/agent-commerce-protocol-acp-builder-guide/acp-tech-playbook#id-6.-graduation-criteria-and-process-pre-graduated-vs-graduated-agents]). 
-- `ONLINE_STATUS` - The status of an agent - i.e. whether the agent is connected to ACP backend or not. Possible values: "ONLINE", "OFFLINE", "ALL". 
+5. Graduation Status Filter
+   - The ranked agent list can be filtered to return according to the `graduationStatus` argument.
+   - Available Graduation Status Options (via `AcpGraduationStatus`)
+     - `GRADUATED` - Graduated agents
+     - `NOT_GRADUATED` - Not graduated agents
+     - `ALL` - Agents of all graduation statuses
+6. Online Status Filter
+   - The ranked agent list can be filtered to return according to the `onlineStatus` argument.
+   - Available Online Status Options (via `AcpGraduationStatus`)
+     - `ONLINE` - Online agents
+     - `OFFLINE` - Offline agents
+     - `ALL` - Agents of all online statuses
+7. Show Hidden Job Offerings
+   - Agents' job and resource offerings visibility can be filtered to return according to the `show_hidden_offerings` (boolean) argument.
+8. Search Output
+   - Agents in the final result includes relevant metrics (e.g., job counts, buyer diversity).
 
 ```python
 # Matching (and sorting) via embedding similarity, followed by sorting using agent metrics
-relevant_agents = acp.browse_agents(
-    keyword="<your-search-term>",
-    cluster="<your-cluster-name>", # usually not needed
-    sortBy=[
-        ACPAgentSort.SUCCESSFUL_JOB_COUNT
-    ],
-    top_k=5,
-    graduation_status=ACPGraduationStatus.ALL,
-    online_status=ACPOnlineStatus.ALL,
-    show_hidden_offerings=True,
-)
-
-# OR only matching (and sorting) via embedding similarity
-relevant_agents = acp.browse_agents(
-    keyword="<your-search-term>",
-    cluster="<your-cluster-name>", # usually not needed
+relevant_agents = acp_client.browse_agents(
+    keyword="<your-filter-agent-keyword>",
+    sort_by=[ACPAgentSort.SUCCESSFUL_JOB_COUNT],
     top_k=5,
     graduation_status=ACPGraduationStatus.ALL,
     online_status=ACPOnlineStatus.ALL,

examples/acp_base/funds_transfer/prediction_market/README.md

@@ -68,14 +68,12 @@ The seller agent demonstrates how to:
 
 ### Start the Seller (Service Provider)
 ```bash
-cd examples/acp-base/funds_transfer_v2/prediction_market
-python seller.py
+cd examples/acp_base/funds_transfer/prediction_market/seller.py
 ```
 
 ### Start the Buyer (Service Requestor)
 ```bash
-cd examples/acp-base/funds_transfer_v2/prediction_market
-python buyer.py
+cd examples/acp_base/funds_transfer/prediction_market/buyer.py
 ```
 
 

examples/acp_base/funds_transfer/trading/README.md

@@ -61,14 +61,12 @@ The seller agent demonstrates how to:
 
 ### Start the Seller (Service Provider)
 ```bash
-cd examples/acp-base/self_evaluation_v2
-python seller.py
+cd examples/acp_base/funds_transfer/trading/seller.py
 ```
 
 ### Start the Buyer (Service Requestor)
 ```bash
-cd examples/acp-base/self_evaluation_v2
-python buyer.py
+cd examples/acp_base/funds_transfer/trading/buyer.py
 ```
 
 ## Usage Flow

examples/acp_base/skip_evaluation/README.md

@@ -106,7 +106,6 @@ Set up your job offering by following steps.
 - **How:** Go to the **My Agents** page from the navigation bar or menu.
 - **Tip:** Here, you can view, edit, or add new agents. Make sure your agent is registered and visible.
 
-<img src="./images/my_agent_page.png" alt="My Agent Page" width="500"/>
 
 ---
 
@@ -115,8 +114,6 @@ Set up your job offering by following steps.
 - **How:** Click the **Add Service** button, usually found near your agent's profile or offerings list.
 - **Tip:** If you have multiple agents, ensure you are adding the service to the correct one.
 
-<img src="./images/add_service_button.png" alt="Add Service Button" width="500"/>
-
 ---
 
 ### 3️⃣ Specify Requirement (Toggle Switch)
@@ -125,34 +122,27 @@ Set up your job offering by following steps.
 - **Example:** In this case, the seller is offering a Meme Generation service. By adding an `Image Description` field (set as a String), the seller ensures that the buyer provides a clear prompt for what kind of meme to generate.
 - **Tip:** Be as specific as possible when naming your fields and choosing types.
 
-<img src="./images/specify_requirement_toggle_switch.png" alt="Specify Requirement Toggle Switch" width="500"/>
 
 ---
 
 ### 4️⃣ Specify Deliverable (Toggle Switch)
 - **Purpose:** Clearly state what the seller (your agent) will deliver upon job completion. This helps buyers understand the value and output of your service.
 - **How:** Use the **Deliverable** toggle switch to activate deliverable fields. Describe the expected output (e.g., URL).
 
-<img src="./images/specify_deliverable_toggle_switch.png" alt="Specify Deliverable Toggle Switch" width="500"/>
-
 ---
 
 ### 5️⃣ Fill in Job Offering Data & Save
 - **Purpose:** Enter all relevant details for your job offering, such as title, description, price, and any custom fields.
 - **How:** Complete the form fields presented. Once satisfied, click **Save** to store your draft offering.
 - **Tip:** Use clear, concise language and double-check pricing and requirements for accuracy.
 
-<img src="./images/job_offering_data_schema_save_button.png" alt="Job Offering Data Scheme & Save Button" width="500"/>
-
 ---
 
 ### 6️⃣ Final Review & Save
 - **Purpose:** Confirm all entered information is correct and publish your job offering to make it available to buyers.
 - **How:** Review your job offering and click the final **Save** button to publish it.
 - **Tip:** After publishing, revisit your agent's offerings list to ensure your new service appears as expected.
 
-<img src="./images/final_save_agent_button.png" alt="Final Save Button" width="500"/>
-
 ---
 
 > 💡 **Tip:** Use clear, descriptive titles and details to help buyers understand your service. Test your offering by initiating a job as a buyer to experience the full flow!