feat(dir): add optional trust ranking reference extension

README.md

@@ -21,29 +21,36 @@ Directory also leverages [CSIT](https://github.com/agntcy/csit) for continuous s
 ADS enables several key capabilities for the agentic AI ecosystem:
 
 - **Capability-Based Discovery**: Agents publish structured metadata describing their
-functional characteristics as described by the [OASF](https://github.com/agntcy/oasf).
-The system organizes this information using hierarchical taxonomies,
-enabling efficient matching of capabilities to requirements.
+  functional characteristics as described by the [OASF](https://github.com/agntcy/oasf).
+  The system organizes this information using hierarchical taxonomies,
+  enabling efficient matching of capabilities to requirements.
 - **Verifiable Claims**: While agent capabilities are often subjectively evaluated,
-ADS provides cryptographic mechanisms for data integrity and provenance tracking.
-This allows users to make informed decisions about agent selection.
+  ADS provides cryptographic mechanisms for data integrity and provenance tracking.
+  This allows users to make informed decisions about agent selection.
 - **Semantic Linkage**: Components can be securely linked to create various relationships
-like version histories for evolutionary development, collaborative partnerships where
-complementary skills solve complex problems, and dependency chains for composite agent workflows.
+  like version histories for evolutionary development, collaborative partnerships where
+  complementary skills solve complex problems, and dependency chains for composite agent workflows.
 - **Distributed Architecture**: Built on proven distributed systems principles,
-ADS uses content-addressing for global uniqueness and implements distributed hash tables (DHT)
-for scalable content discovery and synchronization across decentralized networks.
+  ADS uses content-addressing for global uniqueness and implements distributed hash tables (DHT)
+  for scalable content discovery and synchronization across decentralized networks.
 - **Tooling and Integration**: Provides a suite of command-line tools, SDKs, and APIs
-to facilitate interaction with the system, enabling developers to manage Directory
-records and node operations programmatically.
+  to facilitate interaction with the system, enabling developers to manage Directory
+  records and node operations programmatically.
 - **Security and Trust**: Incorporates robust security measures including
-cryptographic signing, verification of claims, secure communication protocols, and access controls
-to ensure the integrity and authenticity of Directory records and nodes.
+  cryptographic signing, verification of claims, secure communication protocols, and access controls
+  to ensure the integrity and authenticity of Directory records and nodes.
 
 ## Documentation
 
 Check the [Documentation](https://docs.agntcy.org/dir/overview/) for a full walkthrough of all the Directory features.
 
+## Trust Ranking (Reference PoC)
+
+This repository includes a **reference-only trust ranking extension** for directory results,
+implemented as an optional add-on under `extensions/trust_ranking/`.
+
+Details: `extensions/trust_ranking/REFERENCE.md`
+
 ## Source tree
 
 - [proto](./proto) - gRPC specification for data models and services

examples/directory_sample.json

@@ -0,0 +1,131 @@
+{
+  "agents": [
+    {
+      "id": "agent_alpha_clean",
+      "name": "Alpha Services",
+      "url": "https://alpha.example",
+      "capabilities": ["book", "quote", "support"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-20",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.01,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_beta_clean",
+      "name": "Beta Concierge",
+      "url": "https://beta.example",
+      "capabilities": ["schedule", "cancel", "status"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-10",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.03,
+      "rate_limit_violations": 1,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_gamma_ok",
+      "name": "Gamma Helper",
+      "url": "https://gamma.example",
+      "capabilities": ["info"],
+      "contact": "[email protected]",
+      "updated_at": "2025-10-01",
+      "domain_verified": false,
+      "key_present": true,
+      "handshake_fail_ratio": 0.08,
+      "rate_limit_violations": 2,
+      "complaint_flags": 1
+    },
+    {
+      "id": "agent_delta_sparse",
+      "name": "Delta Agent",
+      "url": "https://delta.example",
+      "capabilities": [],
+      "updated_at": "2025-07-15",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.12,
+      "rate_limit_violations": 3,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_epsilon_missing_contact",
+      "name": "Epsilon Tools",
+      "url": "https://epsilon.example",
+      "capabilities": ["quote"],
+      "updated_at": "2025-11-05",
+      "domain_verified": true,
+      "key_present": false,
+      "handshake_fail_ratio": 0.06,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_zeta_suspicious",
+      "name": "Zeta Fast-Track",
+      "url": "https://zeta.example",
+      "capabilities": ["book", "pay", "refund"],
+      "contact": "[email protected]",
+      "updated_at": "2024-12-01",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.45,
+      "rate_limit_violations": 25,
+      "complaint_flags": 7
+    },
+    {
+      "id": "agent_eta_suspicious",
+      "name": "ETA Deals",
+      "url": "https://eta.example",
+      "capabilities": ["book"],
+      "contact": "[email protected]",
+      "updated_at": "2025-01-10",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.33,
+      "rate_limit_violations": 12,
+      "complaint_flags": 4
+    },
+    {
+      "id": "agent_theta_clean",
+      "name": "Theta Support",
+      "url": "https://theta.example",
+      "capabilities": ["support", "status"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-28",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.00,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_iota_ok",
+      "name": "Iota Scheduling",
+      "url": "https://iota.example",
+      "capabilities": ["schedule"],
+      "contact": "[email protected]",
+      "updated_at": "2025-09-09",
+      "domain_verified": false,
+      "key_present": true,
+      "handshake_fail_ratio": 0.10,
+      "rate_limit_violations": 1,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_kappa_broken",
+      "name": "Kappa Broken Link",
+      "url": "",
+      "capabilities": ["book"],
+      "updated_at": "2023-06-01",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.60,
+      "rate_limit_violations": 40,
+      "complaint_flags": 10
+    }
+  ]
+}

examples/directory_sample_degraded.json

@@ -0,0 +1,131 @@
+{
+  "agents": [
+    {
+      "id": "agent_alpha_clean",
+      "name": "Alpha Services",
+      "url": "https://alpha.example",
+      "capabilities": ["book", "quote", "support"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-20",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.01,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_beta_clean",
+      "name": "Beta Concierge",
+      "url": "https://beta.example",
+      "capabilities": ["schedule", "cancel", "status"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-10",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.03,
+      "rate_limit_violations": 1,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_gamma_ok",
+      "name": "Gamma Helper",
+      "url": "https://gamma.example",
+      "capabilities": ["info"],
+      "contact": "[email protected]",
+      "updated_at": "2023-06-01",
+      "domain_verified": false,
+      "key_present": true,
+      "handshake_fail_ratio": 0.56,
+      "rate_limit_violations": 30,
+      "complaint_flags": 12
+    },
+    {
+      "id": "agent_delta_sparse",
+      "name": "Delta Agent",
+      "url": "https://delta.example",
+      "capabilities": [],
+      "updated_at": "2025-07-15",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.12,
+      "rate_limit_violations": 3,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_epsilon_missing_contact",
+      "name": "Epsilon Tools",
+      "url": "https://epsilon.example",
+      "capabilities": ["quote"],
+      "updated_at": "2025-11-05",
+      "domain_verified": true,
+      "key_present": false,
+      "handshake_fail_ratio": 0.06,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_zeta_suspicious",
+      "name": "Zeta Fast-Track",
+      "url": "https://zeta.example",
+      "capabilities": ["book", "pay", "refund"],
+      "contact": "[email protected]",
+      "updated_at": "2024-12-01",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.45,
+      "rate_limit_violations": 25,
+      "complaint_flags": 7
+    },
+    {
+      "id": "agent_eta_suspicious",
+      "name": "ETA Deals",
+      "url": "https://eta.example",
+      "capabilities": ["book"],
+      "contact": "[email protected]",
+      "updated_at": "2025-01-10",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.33,
+      "rate_limit_violations": 12,
+      "complaint_flags": 4
+    },
+    {
+      "id": "agent_theta_clean",
+      "name": "Theta Support",
+      "url": "https://theta.example",
+      "capabilities": ["support", "status"],
+      "contact": "[email protected]",
+      "updated_at": "2025-12-28",
+      "domain_verified": true,
+      "key_present": true,
+      "handshake_fail_ratio": 0.00,
+      "rate_limit_violations": 0,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_iota_ok",
+      "name": "Iota Scheduling",
+      "url": "https://iota.example",
+      "capabilities": ["schedule"],
+      "contact": "[email protected]",
+      "updated_at": "2025-09-09",
+      "domain_verified": false,
+      "key_present": true,
+      "handshake_fail_ratio": 0.10,
+      "rate_limit_violations": 1,
+      "complaint_flags": 0
+    },
+    {
+      "id": "agent_kappa_broken",
+      "name": "Kappa Broken Link",
+      "url": "",
+      "capabilities": ["book"],
+      "updated_at": "2023-06-01",
+      "domain_verified": false,
+      "key_present": false,
+      "handshake_fail_ratio": 0.60,
+      "rate_limit_violations": 40,
+      "complaint_flags": 10
+    }
+  ]
+}