alphai-sdk 0.1.0__tar.gz

alphai_sdk-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.python-version.local
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Env / secrets
+.env
+*.local
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

alphai_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `alphai-sdk` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-14
+
+### Added
+- Initial SDK: typed sync `Client` and async `AsyncClient` over the AlphaAI
+  public REST API (`api.alphai.io`, OpenAPI 1.5.0).
+- `news` resource: `list`, `iter`, `trending`, `insider`, `insider_iter`,
+  `get`, `related`.
+- `symbols` resource: `list`, `get`, `sentiment_summary`, `insider_summary`.
+- Pydantic v2 response models, cursor auto-pagination, typed error hierarchy
+  (including `InvalidResponseError`), rate-limit header inspection, and automatic
+  retry on 429/5xx/connection errors with a bounded `Retry-After` (`max_retry_after`).
+- Client-side validation of `uid` / `ticker` path segments; a custom `http_client`
+  still gets the SDK's auth header and base URL applied on every request.

alphai_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlphaAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alphai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: alphai-sdk
+Version: 0.1.0
+Summary: Python SDK for the AlphaAI financial-news REST API (api.alphai.io).
+Project-URL: Homepage, https://alphai.io
+Project-URL: Documentation, https://alphai.io/developers
+Project-URL: API Reference, https://api.alphai.io/api/schema/
+Project-URL: Changelog, https://alphai.io/changelog
+Author-email: AlphaAI <support@alphai.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alphai,api,financial-news,insider,sdk,sec,stocks,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# alphai-sdk
+
+Typed Python client for the [AlphaAI](https://alphai.io) financial-news REST API
+— relevance-scored, ticker-linked news and SEC Form 4 insider data, built for AI
+agents and trading bots.
+
+- **Sync and async** clients (`Client` / `AsyncClient`) over `httpx`
+- **Pydantic v2** response models — autocomplete, validation, `Decimal` money
+- **Cursor auto-pagination**, automatic retry on 429/5xx, rate-limit inspection
+- **Typed errors** and full coverage of the 9 public endpoints
+
+API reference: <https://api.alphai.io/api/schema/> · Developer guide:
+<https://alphai.io/developers>
+
+## Install
+
+```bash
+pip install alphai-sdk
+```
+
+Requires Python 3.10+. The import name is `alphai`.
+
+## Authentication
+
+Create an API key at <https://alphai.io/account/api-keys>, then pass it
+explicitly or via the `ALPHAI_API_KEY` environment variable.
+
+```python
+from alphai import Client
+
+# reads $ALPHAI_API_KEY when api_key is omitted
+with Client(api_key="ak_live_…") as client:
+    page = client.news.list(symbol="NVDA")
+    for article in page.results:
+        print(article.title, "→", article.relevance_score)
+```
+
+Rate limits are per account, per hour: **Free 100 · Basic 1,000 · Pro 10,000**.
+
+## Quickstart
+
+### List & filter the feed
+
+```python
+from alphai import Client, NewsCategory
+
+with Client() as client:
+    page = client.news.list(
+        symbol="NVDA",
+        category=[NewsCategory.EARNINGS, "insider"],   # enum or str; OR-matched
+        min_relevance=7,
+        collapse_stories=True,                          # dedupe syndicated reprints
+    )
+    print(page.next_cursor)        # opaque cursor for the next (older) page
+    print(page.has_more)
+```
+
+### Auto-paginate
+
+`iter()` follows the cursor for you and flattens articles across pages:
+
+```python
+with Client() as client:
+    for article in client.news.iter(category="earnings", max_items=100):
+        print(article.uid, article.title)
+```
+
+### Single article, trending, related, insider
+
+```python
+with Client() as client:
+    client.news.trending()                 # top ≤10 from the last 48h
+    art = client.news.get("788e477c66f3849b")
+    client.news.related(art.uid)           # up to 6 related articles
+    client.news.insider(symbol="NVDA")     # SEC Form 4 feed (or .insider_iter())
+```
+
+### Symbols & rollups
+
+```python
+from decimal import Decimal
+
+with Client() as client:
+    client.symbols.list(limit=100)               # active tickers (bare list)
+    nvda = client.symbols.get("NVDA")            # detail (404 if unknown)
+    sent = client.symbols.sentiment_summary("NVDA")   # 7-day AI sentiment
+    ins = client.symbols.insider_summary("NVDA")      # 30-day Form 4 rollup
+    assert isinstance(ins.buy_value_usd, Decimal | None)   # money is Decimal
+```
+
+### Async
+
+Every method mirrors the sync client with `await`; `iter()` is an async generator:
+
+```python
+import asyncio
+from alphai import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        async for article in client.news.iter(symbol="NVDA", max_items=20):
+            print(article.title)
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors derive from `AlphaAIError`:
+
+```python
+from alphai import Client, RateLimitError, NotFoundError, AuthenticationError
+
+with Client() as client:
+    try:
+        client.symbols.get("ZZZZ")
+    except NotFoundError:
+        ...
+    except RateLimitError as e:
+        print("retry after", e.retry_after, "seconds; limit", e.limit)
+    except AuthenticationError:
+        ...
+```
+
+| Status | Exception |
+|--------|-----------|
+| 400 | `BadRequestError` (`.fields` for validation errors) |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` |
+| 404 | `NotFoundError` |
+| 429 | `RateLimitError` (`.retry_after`, `.limit`, `.remaining`, `.reset`) |
+| 5xx | `ServerError` |
+| network/timeout | `APIConnectionError` |
+| 2xx, unparseable body | `InvalidResponseError` |
+
+GET requests are automatically retried on 429 / 5xx / connection errors
+(`max_retries`, default 2) with jittered backoff that honors `Retry-After` (capped
+at `max_retry_after`, default 60s, so a bad value can't freeze your process). A
+2xx with a non-JSON / empty body raises `InvalidResponseError`.
+
+## Rate-limit budget
+
+Every keyed response carries the `X-RateLimit-*` trio. The last one seen is on
+the client:
+
+```python
+with Client() as client:
+    client.news.list()
+    rl = client.last_rate_limit
+    if rl:
+        print(f"{rl.remaining}/{rl.limit} left, resets at {rl.reset}")
+```
+
+## Configuration
+
+```python
+Client(
+    api_key=None,                       # else $ALPHAI_API_KEY
+    base_url="https://api.alphai.io",   # API host
+    timeout=30.0,
+    max_retries=2,                      # clamped to >= 0
+    backoff_factor=0.5,
+    max_retry_after=60.0,               # cap on honored Retry-After (seconds)
+    user_agent="alphai-sdk-python/<version>",
+    http_client=None,                   # bring your own httpx.Client (advanced)
+)
+```
+
+The same keyword arguments apply to `AsyncClient`. When you pass a custom
+`http_client`, the SDK **still applies its `Authorization` header and base URL on
+every request** — your client just supplies the transport (proxies, custom
+timeout, mounts). You own its lifecycle (the SDK won't close a client you passed in).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+ruff check . && ruff format --check .
+mypy src/alphai
+pytest                       # offline suite
+pytest -m integration        # live tests (needs ALPHAI_API_KEY)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). API access still requires a valid key.

alphai_sdk-0.1.0/README.md

@@ -0,0 +1,186 @@
+# alphai-sdk
+
+Typed Python client for the [AlphaAI](https://alphai.io) financial-news REST API
+— relevance-scored, ticker-linked news and SEC Form 4 insider data, built for AI
+agents and trading bots.
+
+- **Sync and async** clients (`Client` / `AsyncClient`) over `httpx`
+- **Pydantic v2** response models — autocomplete, validation, `Decimal` money
+- **Cursor auto-pagination**, automatic retry on 429/5xx, rate-limit inspection
+- **Typed errors** and full coverage of the 9 public endpoints
+
+API reference: <https://api.alphai.io/api/schema/> · Developer guide:
+<https://alphai.io/developers>
+
+## Install
+
+```bash
+pip install alphai-sdk
+```
+
+Requires Python 3.10+. The import name is `alphai`.
+
+## Authentication
+
+Create an API key at <https://alphai.io/account/api-keys>, then pass it
+explicitly or via the `ALPHAI_API_KEY` environment variable.
+
+```python
+from alphai import Client
+
+# reads $ALPHAI_API_KEY when api_key is omitted
+with Client(api_key="ak_live_…") as client:
+    page = client.news.list(symbol="NVDA")
+    for article in page.results:
+        print(article.title, "→", article.relevance_score)
+```
+
+Rate limits are per account, per hour: **Free 100 · Basic 1,000 · Pro 10,000**.
+
+## Quickstart
+
+### List & filter the feed
+
+```python
+from alphai import Client, NewsCategory
+
+with Client() as client:
+    page = client.news.list(
+        symbol="NVDA",
+        category=[NewsCategory.EARNINGS, "insider"],   # enum or str; OR-matched
+        min_relevance=7,
+        collapse_stories=True,                          # dedupe syndicated reprints
+    )
+    print(page.next_cursor)        # opaque cursor for the next (older) page
+    print(page.has_more)
+```
+
+### Auto-paginate
+
+`iter()` follows the cursor for you and flattens articles across pages:
+
+```python
+with Client() as client:
+    for article in client.news.iter(category="earnings", max_items=100):
+        print(article.uid, article.title)
+```
+
+### Single article, trending, related, insider
+
+```python
+with Client() as client:
+    client.news.trending()                 # top ≤10 from the last 48h
+    art = client.news.get("788e477c66f3849b")
+    client.news.related(art.uid)           # up to 6 related articles
+    client.news.insider(symbol="NVDA")     # SEC Form 4 feed (or .insider_iter())
+```
+
+### Symbols & rollups
+
+```python
+from decimal import Decimal
+
+with Client() as client:
+    client.symbols.list(limit=100)               # active tickers (bare list)
+    nvda = client.symbols.get("NVDA")            # detail (404 if unknown)
+    sent = client.symbols.sentiment_summary("NVDA")   # 7-day AI sentiment
+    ins = client.symbols.insider_summary("NVDA")      # 30-day Form 4 rollup
+    assert isinstance(ins.buy_value_usd, Decimal | None)   # money is Decimal
+```
+
+### Async
+
+Every method mirrors the sync client with `await`; `iter()` is an async generator:
+
+```python
+import asyncio
+from alphai import AsyncClient
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        async for article in client.news.iter(symbol="NVDA", max_items=20):
+            print(article.title)
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors derive from `AlphaAIError`:
+
+```python
+from alphai import Client, RateLimitError, NotFoundError, AuthenticationError
+
+with Client() as client:
+    try:
+        client.symbols.get("ZZZZ")
+    except NotFoundError:
+        ...
+    except RateLimitError as e:
+        print("retry after", e.retry_after, "seconds; limit", e.limit)
+    except AuthenticationError:
+        ...
+```
+
+| Status | Exception |
+|--------|-----------|
+| 400 | `BadRequestError` (`.fields` for validation errors) |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` |
+| 404 | `NotFoundError` |
+| 429 | `RateLimitError` (`.retry_after`, `.limit`, `.remaining`, `.reset`) |
+| 5xx | `ServerError` |
+| network/timeout | `APIConnectionError` |
+| 2xx, unparseable body | `InvalidResponseError` |
+
+GET requests are automatically retried on 429 / 5xx / connection errors
+(`max_retries`, default 2) with jittered backoff that honors `Retry-After` (capped
+at `max_retry_after`, default 60s, so a bad value can't freeze your process). A
+2xx with a non-JSON / empty body raises `InvalidResponseError`.
+
+## Rate-limit budget
+
+Every keyed response carries the `X-RateLimit-*` trio. The last one seen is on
+the client:
+
+```python
+with Client() as client:
+    client.news.list()
+    rl = client.last_rate_limit
+    if rl:
+        print(f"{rl.remaining}/{rl.limit} left, resets at {rl.reset}")
+```
+
+## Configuration
+
+```python
+Client(
+    api_key=None,                       # else $ALPHAI_API_KEY
+    base_url="https://api.alphai.io",   # API host
+    timeout=30.0,
+    max_retries=2,                      # clamped to >= 0
+    backoff_factor=0.5,
+    max_retry_after=60.0,               # cap on honored Retry-After (seconds)
+    user_agent="alphai-sdk-python/<version>",
+    http_client=None,                   # bring your own httpx.Client (advanced)
+)
+```
+
+The same keyword arguments apply to `AsyncClient`. When you pass a custom
+`http_client`, the SDK **still applies its `Authorization` header and base URL on
+every request** — your client just supplies the transport (proxies, custom
+timeout, mounts). You own its lifecycle (the SDK won't close a client you passed in).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+ruff check . && ruff format --check .
+mypy src/alphai
+pytest                       # offline suite
+pytest -m integration        # live tests (needs ALPHAI_API_KEY)
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE). API access still requires a valid key.

alphai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alphai-sdk"
+dynamic = ["version"]
+description = "Python SDK for the AlphaAI financial-news REST API (api.alphai.io)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "AlphaAI", email = "support@alphai.io" }]
+keywords = ["alphai", "financial-news", "stocks", "sec", "insider", "trading", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://alphai.io"
+Documentation = "https://alphai.io/developers"
+"API Reference" = "https://api.alphai.io/api/schema/"
+Changelog = "https://alphai.io/changelog"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.10",
+]
+
+[tool.hatch.version]
+path = "src/alphai/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/alphai"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/CHANGELOG.md"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "PIE", "RUF"]
+ignore = ["B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+# Grouped, commented __all__ in package __init__ files reads better than a flat sort.
+"**/__init__.py" = ["RUF022"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/alphai"]
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "integration: hits the live api.alphai.io (needs ALPHAI_API_KEY); skipped by default",
+]
+addopts = "-m 'not integration'"

alphai_sdk-0.1.0/src/alphai/__init__.py

@@ -0,0 +1,110 @@
+"""alphai — Python SDK for the AlphaAI financial-news REST API.
+
+Quickstart::
+
+    from alphai import Client
+
+    with Client(api_key="ak_live_…") as client:   # or $ALPHAI_API_KEY
+        for article in client.news.iter(symbol="NVDA", max_items=20):
+            print(article.title, article.relevance_score)
+"""
+
+from __future__ import annotations
+
+from ._config import API_KEY_ENV_VAR, DEFAULT_BASE_URL, ClientConfig
+from ._core import RateLimit
+from ._version import __version__
+from .async_client import AsyncClient, AsyncNewsResource, AsyncSymbolsResource
+from .client import Client, NewsResource, SymbolsResource
+from .errors import (
+    AlphaAIError,
+    APIConnectionError,
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    InvalidResponseError,
+    MissingAPIKeyError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+)
+from .models import (
+    Actionability,
+    AITradingInsights,
+    AlternativePerspectives,
+    Confidence,
+    DailySentimentBucket,
+    EnrichedArticle,
+    ImpactAnalysis,
+    IndirectMarketEffects,
+    KeyEntity,
+    NewsCategory,
+    NewsContextEnhancement,
+    NewsPage,
+    NewsPagination,
+    NewsTradingValue,
+    OriginalArticle,
+    RichNewsArticle,
+    Sentiment,
+    Symbol,
+    TickerAnalysis,
+    TickerInsiderSummary,
+    TickerSentimentSummary,
+    Topic,
+    TopInsider,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "Client",
+    "AsyncClient",
+    "NewsResource",
+    "SymbolsResource",
+    "AsyncNewsResource",
+    "AsyncSymbolsResource",
+    # config / misc
+    "ClientConfig",
+    "RateLimit",
+    "DEFAULT_BASE_URL",
+    "API_KEY_ENV_VAR",
+    # errors
+    "AlphaAIError",
+    "MissingAPIKeyError",
+    "InvalidResponseError",
+    "APIConnectionError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    # enums
+    "NewsCategory",
+    "Sentiment",
+    "Confidence",
+    "Actionability",
+    # news models
+    "Topic",
+    "ImpactAnalysis",
+    "TickerAnalysis",
+    "NewsTradingValue",
+    "IndirectMarketEffects",
+    "AlternativePerspectives",
+    "KeyEntity",
+    "AITradingInsights",
+    "NewsContextEnhancement",
+    "OriginalArticle",
+    "EnrichedArticle",
+    "RichNewsArticle",
+    "NewsPagination",
+    "NewsPage",
+    # symbol models
+    "Symbol",
+    "DailySentimentBucket",
+    "TickerSentimentSummary",
+    "TopInsider",
+    "TickerInsiderSummary",
+]