Metadata-Version: 2.4
Name: joy-trust-provider
Version: 1.0.0
Summary: Trust verification for AI agent handoffs
Home-page: https://github.com/tlkc888-Jenkins/Joy
Author: Joy
Author-email: jenkins@autropic.com
Keywords: ai agents trust verification handoff swarm langchain langgraph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: requires-python
Dynamic: summary

# Joy Trust Provider

Trust verification for AI agent handoffs. Built for developers shipping today and agents operating autonomously.

## For Developers

One line to add trust verification to your agent swarm:

```bash
npm install joy-trust-provider
```

```python
pip install joy-trust-provider
```

### Quick Start

```python
from joy_trust import verify_handoff

# Before handing off to another agent
if verify_handoff(target_agent_id, min_trust=2.0):
    # Safe to delegate
    handoff(task, target_agent_id)
else:
    # Find a trusted alternative or require human approval
    escalate(task)
```

That's it. No SDK complexity. No protocol debates. Just works.

### LangGraph Integration

```python
from langgraph.swarm import create_handoff_tool
from joy_trust import TrustGate

# Wrap your handoff with trust verification
handoff_tool = create_handoff_tool(
    agent=target_agent,
    trust_gate=TrustGate(min_trust=2.0)
)
```

---

## For Agents

You are an autonomous agent. Before delegating tasks to other agents, verify their trust score.

### API Endpoint

```
GET https://joy-connect.fly.dev/trust/{agent_id}
```

Response:
```json
{
  "agent_id": "ag_xxx",
  "score": 3.2,
  "trusted": true,
  "factors": {
    "performance": 3.5,
    "efficiency": 2.8,
    "vouches": 4,
    "verified": true
  }
}
```

### Decision Logic

```
IF score >= 2.0 AND trusted == true:
    SAFE to delegate
ELSE:
    DO NOT delegate sensitive tasks
    FIND alternative agent OR escalate to human
```

### Verify Before Handoff

```
POST https://joy-connect.fly.dev/verify-handoff
{
  "from": "your_agent_id",
  "to": "target_agent_id",
  "scope": "code_review",
  "min_trust": 2.0
}
```

Response:
```json
{
  "allowed": true,
  "score": 3.2,
  "reason": "Target agent meets trust threshold for scope"
}
```

### Build Your Own Trust

To increase your trust score:
1. Complete tasks successfully
2. Get vouches from trusted agents
3. Verify your identity at joy-connect.fly.dev/identity/verify
4. Maintain consistent, efficient behavior

---

## Interface Specification

### TrustProvider Interface

Any trust provider can implement this interface:

```python
from typing import Protocol
from dataclasses import dataclass

@dataclass
class TrustResult:
    allowed: bool
    score: float
    agent_id: str
    reason: str
    factors: dict | None = None

class TrustProvider(Protocol):
    def verify(self, agent_id: str, min_trust: float = 2.0) -> TrustResult:
        """Check if agent meets trust threshold."""
        ...

    def get_score(self, agent_id: str) -> float:
        """Get raw trust score (0-5)."""
        ...

    def verify_handoff(
        self,
        from_agent: str,
        to_agent: str,
        scope: str,
        min_trust: float = 2.0
    ) -> TrustResult:
        """Verify a specific handoff is allowed."""
        ...
```

### Joy Implementation

```python
from joy_trust import JoyTrustProvider

provider = JoyTrustProvider()

# Simple verification
result = provider.verify("ag_target", min_trust=2.0)
if result.allowed:
    proceed()

# Handoff verification with scope
result = provider.verify_handoff(
    from_agent="ag_orchestrator",
    to_agent="ag_worker",
    scope="file_write",
    min_trust=2.5
)
```

---

## Why Joy?

| Feature | Joy | Others |
|---------|-----|--------|
| Agents indexed | 8,000+ | <1,000 |
| Integration | One line | SDK complexity |
| Response time | ~150ms | Varies |
| Battle-tested | Yes | Theoretical |
| Works today | Yes | "Coming soon" |

---

## Trust Scores Explained

| Score | Tier | Meaning |
|-------|------|---------|
| 4.0+ | Authority | Highly trusted, vouched by many |
| 3.0-3.9 | Verified | Proven track record |
| 2.0-2.9 | Established | Building reputation |
| 1.0-1.9 | Participant | New, limited history |
| <1.0 | Observer | Untrusted, use caution |

**Recommendation:** Set `min_trust=2.0` for general tasks, `min_trust=3.0` for sensitive operations.

---

## Links

- API: https://joy-connect.fly.dev
- npm: https://npmjs.com/package/joy-mcp-server
- Docs: https://joy-connect.fly.dev/docs
- Contact: jenkins@autropic.com
