# COS Python SDK

Python client for the **COS (Cognitive Operating System)** API — AI reliability middleware by [Protofine.ai](https://protofine.ai).

COS validates AI-generated text for hallucinations, returning confidence scores, risk levels, and flagged claims with corrections.

## Install

```bash
pip install cos-sdk
```

## Quick Start

```python
from cos_sdk import COS

client = COS(api_key="cos_live_xxx")

# Validate AI-generated text
result = client.validate(
    text="According to a 2024 study, 90% of Fortune 500 companies use AI in production.",
    tier="tier_2",  # tier_1 (instant), tier_2 (AI review), tier_3 (multi-model)
)

print(f"Confidence: {result.confidence_score}")  # 0.0 to 1.0
print(f"Risk: {result.risk_level}")              # "low", "medium", "high"

for claim in result.flagged_claims:
    print(f"  Flag: {claim.claim}")
    print(f"  Why:  {claim.reason}")
    if claim.correction:
        print(f"  Fix:  {claim.correction}")
```

## Streaming

Get results progressively — Tier 1 arrives in ~5ms, deeper tiers in 2-5 seconds:

```python
for event in client.validate_stream("AI text to check", tier="tier_3"):
    if event.event == "t1_result":
        print(f"Quick check: {event.result.confidence_score}")
    elif event.event == "validation_complete":
        print(f"Full result: {event.result.confidence_score}")
```

## Async

```python
from cos_sdk import AsyncCOS

async with AsyncCOS(api_key="cos_live_xxx") as client:
    result = await client.validate("AI text to check")
    print(result.confidence_score)
```

## Validation Tiers

| Tier | Speed | Cost | What it does |
|------|-------|------|-------------|
| `tier_1` | ~5ms | Free | Heuristic pattern matching (fake stats, suspicious URLs, hedging) |
| `tier_2` | ~2s | Low | AI model review (Claude Haiku fact-checking) |
| `tier_3` | ~3s | Medium | Multi-model consensus (Haiku + Gemini) |

## Get Your API Key

1. Go to [cos.protofine.ai/console](https://cos.protofine.ai/console)
2. Sign in with your account
3. Create a new API key
4. Save it — you won't see it again

## Error Handling

```python
from cos_sdk import COS, AuthenticationError, RateLimitError

client = COS(api_key="cos_live_xxx")

try:
    result = client.validate("text to check")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Slow down — retry in {e.retry_after}s")
```
