Metadata-Version: 2.4
Name: foxcite-sdk
Version: 1.0.2
Summary: Official Python SDK for Foxcite AVS and AEO Monitoring platform
Author: Foxcite
License: MIT
Project-URL: Homepage, https://foxcite.com
Project-URL: Repository, https://github.com/foxciteai/sdk-py
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.20.0

# Foxcite Python SDK

[![PyPI version](https://badge.fury.io/py/foxcite-sdk.svg)](https://badge.fury.io/py/foxcite-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

The official Python client library for the [Foxcite](https://foxcite.com) API. Foxcite is an Answer Engine Optimization (AEO) and AI visibility monitoring platform that helps modern agencies and brands track their presence across major LLMs (ChatGPT, Claude, Gemini, Grok, and Perplexity).

## Features

- **Fully Typed:** Exposes fully typed Pydantic v2 schemas for all requests and responses.
- **Sync & Async Support:** Native support for both synchronous (`requests`) and asynchronous (`httpx`) execution.
- **High Concurrency Ready:** Built-in connection pooling and socket management designed for high-throughput AI agent loops.

## Installation

```bash
pip install foxcite-sdk
```

## Quick Start

You can generate an API Key from your [Foxcite Dashboard](https://foxcite.com).

### Synchronous Client

```python
from foxcite import Foxcite

# The client uses a context manager to gracefully handle connection pools
with Foxcite(api_key="seomd_live_...") as client:
    # List brand workspaces
    brands = client.brands.list()
    print("Brands:", [b.name for b in brands])

    # Execute a quick AEO audit
    audit = client.audits.quick_audit(
        name="My Brand",
        domain="mybrand.com",
        niche="SaaS Analytics",
        query="best saas analytics tools"
    )
    print("Quick Audit Scan ID:", audit.scan_id)
```

### Asynchronous Client

```python
import asyncio
from foxcite import AsyncFoxcite

async def main():
    async with AsyncFoxcite(api_key="seomd_live_...") as client:
        brands = await client.brands.list()
        print("Brands:", [b.name for b in brands])

if __name__ == "__main__":
    asyncio.run(main())
```

## Developer Notes: Connection Pooling

Under the hood, the Python SDK manages persistent TCP connections.

- The synchronous `Foxcite` client utilizes a `requests.Session()`.
- The asynchronous `AsyncFoxcite` client utilizes an `httpx.AsyncClient()`.

Always use the client within a `with` or `async with` context manager to ensure sockets are properly released, preventing file descriptor leaks during high-concurrency background tasks.

## Contributing

1. Clone the repository.
2. Create a virtual environment: `python3 -m venv .venv && source .venv/bin/activate`
3. Install dependencies: `pip install -e .`
4. Run tests: `pytest tests/`

## Resources

- [Homepage](https://foxcite.com)
- [Bug Tracker](https://github.com/foxciteai/sdk-py/issues)
