Metadata-Version: 2.4
Name: xluxx
Version: 0.4.0
Summary: XLUXX Trust Layer SDK — runtime trust scores for 15,000+ MCP servers, Resonance Engine, and Context Gate. Makes AI agents reliable.
Home-page: https://github.com/DrDMT-VR/xluxx-trust
Author: XLUXX
Author-email: XLUXX <hello@xluxx.net>
License: MIT
Project-URL: Homepage, https://xluxx.net
Project-URL: API, https://api.xluxx.net
Project-URL: GitHub, https://github.com/DrDMT-VR/xluxx-trust
Keywords: mcp,ai-agents,trust,reliability,tool-selection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# xluxx — Python SDK for the XLUXX Trust Layer

[![PyPI version](https://img.shields.io/pypi/v/xluxx.svg)](https://pypi.org/project/xluxx/)
[![Python](https://img.shields.io/pypi/pyversions/xluxx.svg)](https://pypi.org/project/xluxx/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/DrDMT-VR/xluxx-trust)

**Runtime trust scores for MCP (Model Context Protocol) tools. Makes AI agents reliable.**

```bash
pip install xluxx
```

## Quick start

```python
from xluxx import TrustLayer

trust = TrustLayer()  # No key needed for the free tier

result = trust.resolve("search the web")
print(result.best_server)    # "brave-search"
print(result.confidence)     # 0.985
print(result.fallback)       # "fetch"
print(result.risk_flags)     # []
```

## With an API key (higher rate limits)

```python
from xluxx import TrustLayer

# Register for a free key
key = TrustLayer.register("your-name", "your@email.com")

trust = TrustLayer(api_key=key)
result = trust.resolve("manage files", min_trust_score=80, max_latency_ms=500)
```

## Use it in your agent

```python
from xluxx import resolve

best = resolve("search the web")

if best.confidence > 0.8:
    call_mcp_tool(best.best_server)
elif best.fallback:
    call_mcp_tool(best.fallback)
else:
    raise RuntimeError("no reliable tool found")
```

## API reference

### `TrustLayer`

```python
TrustLayer(api_key: Optional[str] = None, base_url: str = "https://api.xluxx.net")
```

| Method | Description |
|--------|-------------|
| `resolve(intent, tools=None, category=None, min_trust_score=None, max_latency_ms=None)` | Find the best tool for an intent. Returns `ResolveResult` |
| `rank(tools)` | Rank tool/server IDs by trust score. Returns `RankResult` |
| `server(server_id)` | Get full record for a server |
| `servers(limit=50)` | List all tracked servers, sorted by trust |
| `search(query)` | Search 15,000+ servers by capability |
| `health()` | API health and platform stats |
| `TrustLayer.register(name, email)` *(static)* | Get a free API key |

### Convenience function

```python
from xluxx import resolve
result = resolve("search the web", api_key=optional_key)
```

### Result types

```python
@dataclass
class ResolveResult:
    best_server: Optional[str]
    confidence: float
    expected_latency: str
    risk_flags: List[str]
    fallback: Optional[str]
    candidates: List[Dict]
    intent: str
    resolved_at: str
    raw: Dict[str, Any]   # full API response, including resonance fields

@dataclass
class RankResult:
    ranked: List[Dict]
    ranked_at: str
```

The `raw` field on `ResolveResult` exposes the complete API response, including `resonance_score`, `fractal_reliability`, `coherence_drift`, and `fallback_stability` from the Resonance Engine.

## Errors

```python
from xluxx import TrustLayer, TrustLayerError

try:
    result = trust.resolve("search the web")
except TrustLayerError as e:
    print(e, e.status_code)
```

## Pricing

- **Free** — 100 calls/day, no key required
- **Starter** — $49/mo, 1,000 calls/day
- **Pro** — $149/mo, 10,000 calls/day

## Links

- **API**: https://api.xluxx.net
- **Website**: https://xluxx.net
- **GitHub**: https://github.com/DrDMT-VR/xluxx-trust
- **Node.js SDK**: [`xluxx-trust`](https://www.npmjs.com/package/xluxx-trust) on npm
- **MCP server**: [`xluxx-mcp-server`](https://www.npmjs.com/package/xluxx-mcp-server) on npm

## License

Apache-2.0 — Pablo Solorzano Cohen
