Metadata-Version: 2.4
Name: cos-sdk
Version: 0.1.0
Summary: Python SDK for COS (Cognitive Operating System) — AI reliability middleware by Protofine.ai
Author-email: "Protofine.ai" <support@protofine.ai>
License: MIT
Project-URL: Homepage, https://protofine.ai
Project-URL: Documentation, https://cos.protofine.ai/console
Project-URL: Repository, https://github.com/protofine/cos-python-sdk
Keywords: ai,reliability,hallucination,validation,cos
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# 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")
```
