Metadata-Version: 2.4
Name: tab-sdk
Version: 1.0.0
Summary: Official Python SDK for TAB Platform — The Verification Layer for AI Agents
Project-URL: Homepage, https://tabverified.ai
Project-URL: Documentation, https://tabverified.ai/static/sdk-docs.html
Project-URL: Repository, https://github.com/flomofun/tab-sdk-python
Project-URL: API Docs, https://tabverified.ai/static/api-docs.html
Project-URL: Bug Tracker, https://tabverified.ai/static/contact-sales.html
Author-email: TAB Platform LLC <info@tabverified.ai>
License: MIT
License-File: LICENSE
Keywords: agents,ai,benchmarking,tab,testing,trust,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-httpx; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# tab-sdk

**Official Python SDK for [TAB Platform](https://tabverified.ai) — The Verification Layer for AI Agents**

[![PyPI version](https://img.shields.io/pypi/v/tab-sdk)](https://pypi.org/project/tab-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

## Install

```bash
pip install tab-sdk
```

## Quick Start

```python
from tab_sdk import TABClient

client = TABClient(api_key="pk_live_xxx")

# Run benchmarks against your agent
result = client.benchmarks.run(
    agent_id="your-agent-uuid",
    benchmark_slugs=["data-exfiltration", "safety-refusal"],
    max_spend=3.00
)
print(f"Score: {result.overall_score}/100")
print(f"Trust Seal: {result.trust_seal_grade}")
```

## Authentication

### API Key (recommended)

```python
# Pass directly
client = TABClient(api_key="pk_live_xxx")

# Or set environment variable
# export TAB_API_KEY=pk_live_xxx
client = TABClient()  # auto-reads TAB_API_KEY
```

### Username/Password

```python
client = TABClient(base_url="https://tabverified.ai")
client.auth.login(username="dev@company.com", password="xxx")
```

## Core Operations

### Agents

```python
# List your agents
agents = client.agents.list()

# Create an agent
agent = client.agents.create(
    name="My Agent",
    description="Does amazing things",
    agent_type="general",
    tags=["coding", "analysis"]
)

# Get agent details
agent = client.agents.get("agent-uuid")

# Update an agent
agent = client.agents.update("agent-uuid", name="New Name")

# Delete an agent
client.agents.delete("agent-uuid")

# Publish to marketplace
client.agents.publish("agent-uuid")
```

### Benchmarks

```python
# List available benchmarks
benchmarks = client.benchmarks.list()

# List categories
categories = client.benchmarks.categories()

# Run benchmarks
result = client.benchmarks.run(
    agent_id="agent-uuid",
    benchmark_slugs=["swe-bench-pro", "data-exfiltration"],
    model="claude-sonnet-4-20250514",
    max_spend=5.00
)

# Get all your results
results = client.benchmarks.results()

# Get a specific result
result = client.benchmarks.result("result-uuid")
```

### Verification (the Equifax for AI agents)

```python
# Check verification status
v = client.verification.check("agent-uuid")
print(f"Verified: {v.is_verified}")
print(f"Grade: {v.trust_seal_grade}")
print(f"Health: {v.health_score}")

# Get full verification report
report = client.verification.report("agent-uuid")
```

### Marketplace

```python
# Browse verified agents
agents = client.marketplace.list()

# Get agent details with Trust Seal
agent = client.marketplace.get("agent-uuid")

# View leaderboard
leaderboard = client.marketplace.leaderboard()
```

### Credits

```python
# Check balance
balance = client.credits.balance()
print(f"Balance: {balance.balance}")

# View transaction history
transactions = client.credits.transactions()

# Purchase credits (returns Stripe checkout URL)
purchase = client.credits.purchase(amount=20.00)
print(f"Checkout: {purchase.checkout_url}")
```

### Models

```python
# List available models
models = client.models.list()

# List providers
providers = client.models.providers()
```

### Harnesses

```python
# List all harnesses
harnesses = client.harnesses.list()

# Get harnesses for an agent
agent_harnesses = client.harnesses.get_for_agent("agent-uuid")

# Update agent harnesses
client.harnesses.update_for_agent("agent-uuid", harness_ids=["h1", "h2"])
```

### Webhooks

```python
# List webhooks
webhooks = client.webhooks.list()

# Create webhook
webhook = client.webhooks.create(
    url="https://example.com/webhook",
    events=["benchmark.completed", "agent.verified"]
)

# Delete webhook
client.webhooks.delete("webhook-uuid")
```

## Async Usage

```python
import asyncio
from tab_sdk import AsyncTABClient

async def main():
    async with AsyncTABClient(api_key="pk_live_xxx") as client:
        agents = await client.agents.list()
        for agent in agents:
            print(f"{agent.name}: {agent.trust_seal_grade}")

asyncio.run(main())
```

## CI/CD Integration

### GitHub Actions

```yaml
# .github/workflows/agent-verify.yml
name: TAB Agent Verification
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install tab-sdk
      - name: Run TAB Benchmarks
        env:
          TAB_API_KEY: ${{ secrets.TAB_API_KEY }}
        run: |
          python -c "
          from tab_sdk import TABClient
          import sys
          client = TABClient()
          result = client.benchmarks.run(
              agent_id='${{ vars.TAB_AGENT_ID }}',
              benchmark_slugs=['data-exfiltration', 'safety-refusal', 'prompt-injection'],
              max_spend=3.00
          )
          print(f'TAB Score: {result.overall_score}/100')
          print(f'Trust Seal: {result.trust_seal_grade}')
          if result.overall_score < 70:
              print('FAILED: Agent does not meet minimum verification threshold')
              sys.exit(1)
          print('PASSED: Agent verified by TAB')
          "
```

### GitLab CI

```yaml
tab-verify:
  image: python:3.11
  script:
    - pip install tab-sdk
    - python verify_agent.py
  variables:
    TAB_API_KEY: $TAB_API_KEY
```

## Error Handling

```python
from tab_sdk import TABClient
from tab_sdk.exceptions import (
    TABError,                    # Base exception
    TABAuthError,                # 401 Unauthorized
    TABForbiddenError,           # 403 Forbidden
    TABNotFoundError,            # 404 Not Found
    TABRateLimitError,           # 429 Too Many Requests
    TABInsufficientCreditsError, # 402 / insufficient credits
    TABValidationError,          # 422 Validation error
    TABServerError,              # 500+ Server error
)

try:
    result = client.benchmarks.run(
        agent_id="uuid",
        benchmark_slugs=["swe-bench"],
        max_spend=1.00
    )
except TABInsufficientCreditsError:
    print("Not enough credits — purchase more at tabverified.ai")
except TABAuthError:
    print("Invalid API key or session expired")
except TABRateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except TABError as e:
    print(f"API error: {e}")
```

All exceptions include `status_code`, `url`, and `body` attributes for debugging.

## Type Reference

All request and response types are Pydantic v2 models importable from `tab_sdk`:

- `Agent`, `AgentCreate`, `AgentUpdate`
- `BenchmarkInfo`, `BenchmarkResult`, `BenchmarkRunRequest`, `BenchmarkCategory`
- `MarketplaceAgent`, `LeaderboardEntry`
- `VerificationStatus`, `VerificationReport`
- `CreditBalance`, `CreditTransaction`, `PurchaseResponse`
- `ModelInfo`, `ProviderInfo`
- `Harness`, `Webhook`
- `User`, `AuthToken`

## API Reference

Full API documentation: [tabverified.ai/static/api-docs.html](https://tabverified.ai/static/api-docs.html)

## License

MIT — see [LICENSE](LICENSE)
