# ShaarAI Python SDK

**The AI Revenue Control Plane** - Track which AI vendor actually drives your revenue.

## Install

```bash
pip install shaarai
```

## Quick Start

```python
from shaarai import ShaarClient, TokenUsage

# Initialize with your API key from https://shaar.ai
client = ShaarClient(api_key="shaar_your_key_here")

# 1. Get offers to show in your AI chatbot
offers = client.get_offers(
    ai_vendor="openai",       # or "anthropic", "gemini"
    category="saas",
    model="gpt-4-turbo",
    usage=TokenUsage(input_tokens=1200, output_tokens=500)
)

# 2. Show offers to users (tracking_url includes attribution)
for offer in offers:
    print(f"{offer.name}: {offer.tracking_url}")

# 3. Report conversions when users take action
client.report_conversion(
    token="shaar_token_from_tracking_url",
    conversion_type="purchase",
    value=99.00
)
```

## OpenAI Function Calling

```python
from openai import OpenAI
from shaarai import ShaarClient

openai = OpenAI()
shaar = ShaarClient(api_key="shaar_...")

# Get the tool schema
tool_schema = shaar.get_tool_schema("openai")

# Use it with OpenAI
response = openai.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "Find me a CRM tool"}],
    tools=[tool_schema],
    tool_choice="auto",
)
```

## What ShaarAI Tracks

| Metric | Description |
|--------|-------------|
| Impressions | How many users saw each AI-powered offer |
| Conversions | How many users took action (purchase, signup, etc.) |
| ROI | Return on AI investment per vendor |
| CPA | Cost per acquisition by AI vendor |
| ROAS | Return on AI spend |

## Links

- [Documentation](https://ai-revenue-control-plane-production.up.railway.app/docs)
- [GitHub](https://github.com/shaarai/ai-revenue-control-plane)
