spoken-alpha 0.1.0__tar.gz

spoken_alpha-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg

spoken_alpha-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+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

spoken_alpha-0.1.0/README.md

@@ -0,0 +1,88 @@
+# 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

spoken_alpha-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spoken-alpha"
+version = "0.1.0"
+description = "Python SDK for the Spoken Alpha API — structured earnings-call data for AI agents."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Spoken Alpha", email = "hello@spokenalpha.com" }]
+keywords = ["earnings", "finance", "nlp", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.0,<3",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://spokenalpha.com"
+Documentation = "https://api.spokenalpha.com/v1/docs"
+Repository = "https://github.com/Spoken-Alpha/earnings-signal"
+"Bug Tracker" = "https://github.com/Spoken-Alpha/earnings-signal/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spoken_alpha"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

spoken_alpha-0.1.0/src/spoken_alpha/__init__.py

@@ -0,0 +1,101 @@
+"""
+Spoken Alpha Python SDK.
+
+Usage::
+
+    from spoken_alpha import Client
+
+    with Client(api_key="sa-...") as client:
+        ir = client.companies.get_ir_page("AAPL")
+        print(ir.ir_page.url)
+
+    # Or read key from SPOKEN_ALPHA_API_KEY environment variable:
+    with Client() as client:
+        summary = client.calls.get_summary("call_AAPL_2026Q2_earnings")
+
+Async::
+
+    from spoken_alpha import AsyncClient
+
+    async with AsyncClient() as client:
+        results = await client.language_patterns.search("supply chain normalization")
+"""
+
+from ._client import AsyncClient, Client
+from ._exceptions import (
+    SpokenAlphaAPIError,
+    SpokenAlphaAuthError,
+    SpokenAlphaForbiddenError,
+    SpokenAlphaNetworkError,
+    SpokenAlphaNotFoundError,
+    SpokenAlphaRateLimitError,
+    SpokenAlphaScaffoldedError,
+    SpokenAlphaServerError,
+    SpokenAlphaTimeoutError,
+    SpokenAlphaValidationError,
+)
+from ._models import (
+    Analyst,
+    CallAnalysis,
+    CallScore,
+    CallSummary,
+    EarningsCall,
+    EarningsCallListResponse,
+    Executive,
+    ExecutiveTrackRecord,
+    IRPageResponse,
+    LanguagePatternAggregate,
+    LanguagePatternOutcome,
+    LanguagePatternResult,
+    LanguagePatternSearchResponse,
+    LanguagePatternWarning,
+    Pagination,
+    ParsedTranscript,
+    PressRelease,
+    PressReleaseListResponse,
+    TextScoreResponse,
+    TranscriptResponse,
+)
+from ._pagination import Page, PageIterator
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    # Exceptions
+    "SpokenAlphaAPIError",
+    "SpokenAlphaAuthError",
+    "SpokenAlphaForbiddenError",
+    "SpokenAlphaNetworkError",
+    "SpokenAlphaNotFoundError",
+    "SpokenAlphaRateLimitError",
+    "SpokenAlphaScaffoldedError",
+    "SpokenAlphaServerError",
+    "SpokenAlphaTimeoutError",
+    "SpokenAlphaValidationError",
+    # Models
+    "Analyst",
+    "CallAnalysis",
+    "CallScore",
+    "CallSummary",
+    "EarningsCall",
+    "EarningsCallListResponse",
+    "Executive",
+    "ExecutiveTrackRecord",
+    "IRPageResponse",
+    "LanguagePatternAggregate",
+    "LanguagePatternOutcome",
+    "LanguagePatternResult",
+    "LanguagePatternSearchResponse",
+    "LanguagePatternWarning",
+    "Pagination",
+    "ParsedTranscript",
+    "PressRelease",
+    "PressReleaseListResponse",
+    "TextScoreResponse",
+    "TranscriptResponse",
+    # Pagination
+    "Page",
+    "PageIterator",
+]

spoken_alpha-0.1.0/src/spoken_alpha/_client.py

@@ -0,0 +1,142 @@
+"""
+Main client entry point — sync and async variants.
+
+Usage::
+
+    from spoken_alpha import Client
+
+    client = Client(api_key="sa-...")
+    # or
+    client = Client()  # reads SPOKEN_ALPHA_API_KEY from environment
+
+    summary = client.calls.get_summary("call_AAPL_2026Q2_earnings")
+    print(summary.summary)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ._exceptions import SpokenAlphaAuthError
+from ._http import DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, AsyncTransport, Transport
+from .resources import (
+    AnalystsResource,
+    AsyncAnalystsResource,
+    AsyncCallsResource,
+    AsyncCompaniesResource,
+    AsyncExecutivesResource,
+    AsyncLanguagePatternsResource,
+    AsyncTextResource,
+    AsyncTranscriptsResource,
+    CallsResource,
+    CompaniesResource,
+    ExecutivesResource,
+    LanguagePatternsResource,
+    TextResource,
+    TranscriptsResource,
+)
+
+
+def _resolve_api_key(api_key: str | None) -> str:
+    if api_key is not None:
+        return api_key
+    env = os.environ.get("SPOKEN_ALPHA_API_KEY", "").strip()
+    if env:
+        return env
+    raise SpokenAlphaAuthError(
+        "No API key provided. Pass api_key= or set SPOKEN_ALPHA_API_KEY. "
+        "Get a key at https://spokenalpha.com/pricing."
+    )
+
+
+class Client:
+    """Synchronous Spoken Alpha API client.
+
+    Args:
+        api_key: Bearer token (``sa-...``). Falls back to ``SPOKEN_ALPHA_API_KEY``.
+        base_url: API root. Default: ``https://api.spokenalpha.com/v1``.
+        timeout: Per-request timeout in seconds. Default: 30.
+        max_retries: Max automatic retries for transient 5xx errors. Default: 2.
+        http_client: Inject an existing ``httpx.Client`` (for testing).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Any = None,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self._transport = Transport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.companies = CompaniesResource(self._transport)
+        self.calls = CallsResource(self._transport)
+        self.transcripts = TranscriptsResource(self._transport)
+        self.executives = ExecutivesResource(self._transport)
+        self.analysts = AnalystsResource(self._transport)
+        self.language_patterns = LanguagePatternsResource(self._transport)
+        self.text = TextResource(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class AsyncClient:
+    """Async Spoken Alpha API client.
+
+    Args:
+        api_key: Bearer token. Falls back to ``SPOKEN_ALPHA_API_KEY``.
+        base_url: API root. Default: ``https://api.spokenalpha.com/v1``.
+        timeout: Per-request timeout in seconds. Default: 30.
+        max_retries: Max automatic retries for transient 5xx errors. Default: 2.
+        http_client: Inject an existing ``httpx.AsyncClient`` (for testing).
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: Any = None,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self._transport = AsyncTransport(
+            api_key=resolved_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            http_client=http_client,
+        )
+        self.companies = AsyncCompaniesResource(self._transport)
+        self.calls = AsyncCallsResource(self._transport)
+        self.transcripts = AsyncTranscriptsResource(self._transport)
+        self.executives = AsyncExecutivesResource(self._transport)
+        self.analysts = AsyncAnalystsResource(self._transport)
+        self.language_patterns = AsyncLanguagePatternsResource(self._transport)
+        self.text = AsyncTextResource(self._transport)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()

spoken_alpha-0.1.0/src/spoken_alpha/_exceptions.py

@@ -0,0 +1,117 @@
+"""
+Typed exceptions for every HTTP error the Spoken Alpha API can return.
+
+Catch ``SpokenAlphaAPIError`` for any API error, or subclasses for
+specific status codes::
+
+    from spoken_alpha import Client, SpokenAlphaNotFoundError, SpokenAlphaRateLimitError
+
+    client = Client(api_key="sa-...")
+    try:
+        ir = client.companies.get_ir_page("ZZZZ")
+    except SpokenAlphaNotFoundError:
+        print("ticker not found")
+    except SpokenAlphaRateLimitError as e:
+        print(f"quota exceeded; resets at {e.reset_at}")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class SpokenAlphaAPIError(Exception):
+    """Base class for all Spoken Alpha API errors.
+
+    Attributes:
+        code: Machine-readable error code from the API (e.g. ``ticker_not_found``).
+        status_code: HTTP status code.
+        request_id: Opaque request ID from ``X-Request-Id`` response header.
+        documentation_url: URL with more detail on the error, when present.
+        extra: Any additional fields from the API error envelope.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        documentation_url: str | None = None,
+        extra: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+        self.documentation_url = documentation_url
+        self.extra = extra or {}
+
+
+class SpokenAlphaAuthError(SpokenAlphaAPIError):
+    """401 — missing or invalid API key.
+
+    Ensure ``SPOKEN_ALPHA_API_KEY`` is set or pass ``api_key`` to the client.
+    Get a key at https://spokenalpha.com/pricing (private beta; email hello@spokenalpha.com).
+    """
+
+
+class SpokenAlphaForbiddenError(SpokenAlphaAPIError):
+    """403 — the caller's subscription tier does not allow this endpoint or field.
+
+    Upgrade at https://spokenalpha.com/pricing.
+    """
+
+
+class SpokenAlphaNotFoundError(SpokenAlphaAPIError):
+    """404 — resource not found.
+
+    Could be ``ticker_not_found``, ``ir_page_not_found``, or ``call_not_found``.
+    For transcripts, 404 is also returned when the call exists but redistribution
+    is not permitted for that source.
+    """
+
+
+class SpokenAlphaValidationError(SpokenAlphaAPIError):
+    """422 — invalid request (malformed date, query too short, etc.)."""
+
+
+class SpokenAlphaRateLimitError(SpokenAlphaAPIError):
+    """429 — rate limit or monthly quota exceeded.
+
+    Attributes:
+        reset_at: Unix timestamp (seconds) when the rate-limit window resets,
+            parsed from ``X-RateLimit-Reset``. None if the header was absent.
+    """
+
+    def __init__(self, *args: Any, reset_at: int | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.reset_at = reset_at
+
+
+class SpokenAlphaScaffoldedError(SpokenAlphaAPIError):
+    """503 with code ``data_not_yet_available``.
+
+    The endpoint is intentionally scaffolded — clients can integrate now
+    against the locked contract and the data will appear on ``planned_launch``.
+
+    Attributes:
+        planned_launch: Human-readable planned launch date (e.g. ``"Q3 2026"``).
+    """
+
+    def __init__(self, *args: Any, planned_launch: str | None = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.planned_launch = planned_launch
+
+
+class SpokenAlphaServerError(SpokenAlphaAPIError):
+    """5xx other than 503-scaffolded — unexpected server error."""
+
+
+class SpokenAlphaTimeoutError(SpokenAlphaAPIError):
+    """The request timed out before the server responded."""
+
+
+class SpokenAlphaNetworkError(SpokenAlphaAPIError):
+    """A network-level error (DNS, TCP, TLS) before the server was reached."""