Metadata-Version: 2.4
Name: spoken-alpha
Version: 0.1.0
Summary: Python SDK for the Spoken Alpha API — structured earnings-call data for AI agents.
Project-URL: Homepage, https://spokenalpha.com
Project-URL: Documentation, https://api.spokenalpha.com/v1/docs
Project-URL: Repository, https://github.com/Spoken-Alpha/earnings-signal
Project-URL: Bug Tracker, https://github.com/Spoken-Alpha/earnings-signal/issues
Author-email: Spoken Alpha <hello@spokenalpha.com>
License: MIT
Keywords: api,earnings,finance,nlp,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# spoken-alpha · Python SDK

[![PyPI](https://img.shields.io/pypi/v/spoken-alpha)](https://pypi.org/project/spoken-alpha/)
[![Python](https://img.shields.io/pypi/pyversions/spoken-alpha)](https://pypi.org/project/spoken-alpha/)

Structured earnings-call data for AI agents.

Full API reference: <https://api.spokenalpha.com/v1/docs>

> **Note:** The PyPI package is `spoken-alpha` (hyphen). The npm scope uses an underscore (`@spoken_alpha/sdk`) — see `sdks/README.md` for the reason.

## Install

```bash
pip install spoken-alpha
```

## Quick start

```python
from spoken_alpha import Client

with Client(api_key="sa-...") as client:
    ir = client.companies.get_ir_page("AAPL")
    print(ir.ir_page.confidence)

    for call in client.companies.list_earnings_calls("AAPL").iterate_all():
        print(call.call_date, call.fiscal_quarter)

    summary = client.calls.get_summary("call_AAPL_2026Q2_earnings")
    print(summary.summary)
```

The API key can also be set via the `SPOKEN_ALPHA_API_KEY` environment variable — `Client()` picks it up automatically.

## Async

```python
from spoken_alpha import AsyncClient

async with AsyncClient() as client:
    results = await client.language_patterns.search("supply chain normalization")
    for r in results.results:
        print(r.ticker, r.snippet)
```

## Error handling

```python
from spoken_alpha import Client, SpokenAlphaNotFoundError, SpokenAlphaRateLimitError

with Client() as client:
    try:
        ir = client.companies.get_ir_page("ZZZZ")
    except SpokenAlphaNotFoundError:
        print("ticker not found")
    except SpokenAlphaRateLimitError as e:
        print(f"rate limited; resets at {e.reset_at}")
```

All exceptions inherit from `SpokenAlphaAPIError`. Subclasses:

| Class | HTTP |
|---|---|
| `SpokenAlphaAuthError` | 401 |
| `SpokenAlphaForbiddenError` | 403 |
| `SpokenAlphaNotFoundError` | 404 |
| `SpokenAlphaValidationError` | 422 |
| `SpokenAlphaRateLimitError` | 429 |
| `SpokenAlphaScaffoldedError` | 503 (planned endpoint) |
| `SpokenAlphaServerError` | 5xx |
| `SpokenAlphaTimeoutError` | timeout |
| `SpokenAlphaNetworkError` | network |

## Configuration

```python
Client(
    api_key="sa-...",          # default: SPOKEN_ALPHA_API_KEY env var
    base_url="https://...",    # default: https://api.spokenalpha.com/v1
    timeout=30.0,              # seconds, default 30
    max_retries=2,             # auto-retry on 5xx, default 2
)
```

## License

MIT
