Metadata-Version: 2.5
Name: suprsonic
Version: 0.3.2
Summary: Suprsonic Python SDK. One API key, dozens of capabilities for your AI agent.
Project-URL: Homepage, https://suprsonic.ai
Project-URL: Documentation, https://suprsonic.ai/apis
Project-URL: Repository, https://github.com/O-mega-Enterprise/suprsonic-mcp
License: MIT
Keywords: ai-agent,mcp,suprsonic,unified-api
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

# suprsonic

Python SDK for [Suprsonic](https://suprsonic.ai). One API key, dozens of capabilities for your AI agent.

## Install

```bash
pip install suprsonic
```

## Usage

```python
from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

# Search the web
result = client.search("latest AI funding rounds")
print(result.data)

# Find a professional email
result = client.emails.find(first_name="Yuma", last_name="Heymans", domain="o-mega.ai")
print(result.data["email"])  # yuma@o-mega.ai

# Scrape a webpage
result = client.scrape("https://example.com")
print(result.data["content"])

# Any capability via .run()
result = client.run("screenshot", url="https://example.com")
```

## Response Format

Every method returns a unified response object:

```json
{
  "success": true,
  "data": {
    "results": [
      { "title": "OpenAI raises $6.6B", "url": "https://...", "snippet": "..." }
    ]
  },
  "error": null,
  "metadata": {
    "provider_used": "serperdev",
    "providers_tried": ["serperdev"],
    "response_time_ms": 1200,
    "request_id": "req_abc123"
  },
  "credits_used": 1
}
```

On failure, `success` is `false` and `error` contains the details (see below).

## Error Handling

```python
from suprsonic import Suprsonic, SuprsonicError

client = Suprsonic("omk_your_key")

try:
    result = client.search("latest AI funding rounds")
    if not result.success:
        # API returned an error response
        print(result.error["detail"])
        if result.error["is_retriable"]:
            # Safe to retry after the suggested delay
            time.sleep(result.error["retry_after_seconds"])
except SuprsonicError as e:
    print(e.status, e.detail)
```

Error object structure:

```json
{
  "type": "billing_error",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Your account has 0 credits remaining. Add credits at suprsonic.ai/app/billing.",
  "is_retriable": false,
  "retry_after_seconds": null,
  "error_category": "billing"
}
```

Error categories: `transient` (retry safe), `permanent` (bad request), `authentication` (invalid key), `billing` (out of credits).

## Agent Framework Examples

### LangChain

```python
from langchain.tools import StructuredTool
from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

search_tool = StructuredTool.from_function(
    func=lambda query: client.search(query).data,
    name="web_search",
    description="Search the web for current information",
)

# Use in any LangChain agent
agent = initialize_agent(tools=[search_tool], llm=llm)
```

### CrewAI

```python
from crewai import Agent, Task, Crew
from crewai.tools import tool
from suprsonic import Suprsonic

client = Suprsonic("omk_your_key")

@tool("Web Search")
def search(query: str) -> dict:
    """Search the web for current information."""
    return client.search(query).data

researcher = Agent(
    role="Research Analyst",
    goal="Find accurate, current information",
    tools=[search],
)
```

### OpenAI Function Calling

Use the `/v1/tools` endpoint to get Suprsonic capabilities as OpenAI-compatible function definitions:

```python
import requests, openai

tools = requests.get(
    "https://suprsonic.ai/v1/tools",
    headers={"Authorization": "Bearer omk_your_key"},
).json()

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Search for recent SpaceX launches"}],
    tools=tools,
)
```

## All Capabilities

search, scrape, profiles, emails, images, tts, stt, sms, documents, companies, email-verify, transcribe, invoice-parse, subtitle, file-convert, bg-remove, screenshot

Full API reference with all parameters and example responses: [suprsonic.ai/apis](https://suprsonic.ai/apis)

Get your API key at [suprsonic.ai](https://suprsonic.ai).
