openbb-aurastream 0.1.0__py3-none-any.whl

openbb_aurastream/__init__.py

@@ -0,0 +1,31 @@
+"""OpenBB AuraStream Provider Module."""
+
+from openbb_core.provider.abstract.provider import Provider
+
+from openbb_aurastream.models.fails_to_deliver import AuraStreamFailsToDeliverFetcher
+from openbb_aurastream.models.fred_vintages import AuraStreamFredVintagesFetcher
+from openbb_aurastream.models.funding_rates import AuraStreamFundingRatesFetcher
+from openbb_aurastream.models.net_short import AuraStreamNetShortFetcher
+from openbb_aurastream.models.wasde import AuraStreamWasdeFetcher
+
+aurastream_provider = Provider(
+    name="aurastream",
+    website="https://aurastream.unbiased-alpha.com",
+    description="AuraStream, a unified market data API for quants by Unbiased Alpha:"
+    " EU net short positions, USDA WASDE projections, FRED with every revision,"
+    " SEC fails-to-deliver and Binance funding rates.",
+    credentials=["api_key", "fred_api_key", "sec_user_agent"],
+    fetcher_dict={
+        "AuraStreamNetShort": AuraStreamNetShortFetcher,
+        "AuraStreamWasde": AuraStreamWasdeFetcher,
+        "AuraStreamFredVintages": AuraStreamFredVintagesFetcher,
+        "AuraStreamFailsToDeliver": AuraStreamFailsToDeliverFetcher,
+        "AuraStreamFundingRates": AuraStreamFundingRatesFetcher,
+    },
+    repr_name="AuraStream",
+    instructions="Get a free API key (500 calls a month, no credit card) at"
+    " https://aurastream.unbiased-alpha.com/sign-up and set it as aurastream_api_key."
+    " fred_vintages also needs your own free FRED key (aurastream_fred_api_key), and"
+    " fails_to_deliver a contact string for the SEC (aurastream_sec_user_agent),"
+    " e.g. 'Jane Doe jane@example.com'.",
+)

openbb_aurastream/aurastream_router.py

@@ -0,0 +1,117 @@
+"""AuraStream Router."""
+
+from openbb_core.app.model.command_context import CommandContext
+from openbb_core.app.model.example import APIEx
+from openbb_core.app.model.obbject import OBBject
+from openbb_core.app.provider_interface import (
+    ExtraParams,
+    ProviderChoices,
+    StandardParams,
+)
+from openbb_core.app.query import Query
+from openbb_core.app.router import Router
+
+router = Router(prefix="", description="AuraStream market data.")
+
+
+@router.command(
+    model="AuraStreamNetShort",
+    examples=[
+        APIEx(
+            description="Disclosed short positions in Ubisoft on the French register.",
+            parameters={"symbol": "ubisoft", "country": "FR", "provider": "aurastream"},
+        ),
+        APIEx(
+            description="Every position one fund has disclosed in the period.",
+            parameters={"symbol": "all", "holder": "citadel", "provider": "aurastream"},
+        ),
+    ],
+)
+async def net_short(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get disclosed net short positions of 0.5% or more in European shares (AMF, AFM, CNMV)."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamWasde",
+    examples=[
+        APIEx(
+            description="How the USDA's projection of US corn ending stocks changed, report by report.",
+            parameters={"symbol": "corn:ending_stocks", "provider": "aurastream"},
+        ),
+        APIEx(
+            description="Brazil's soybean crop from the world tables.",
+            parameters={"symbol": "soybeans:production:Brazil", "provider": "aurastream"},
+        ),
+    ],
+)
+async def wasde(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get USDA WASDE projections since July 2010, one row per monthly report."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFredVintages",
+    examples=[
+        APIEx(
+            description="Every published version of US CPI, by publication date.",
+            parameters={"symbol": "CPIAUCSL", "provider": "aurastream"},
+        ),
+    ],
+)
+async def fred_vintages(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get FRED series with every revision, stamped at the date each value was published."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFailsToDeliver",
+    examples=[
+        APIEx(
+            description="Fails-to-deliver in GameStop.",
+            parameters={"symbol": "GME", "provider": "aurastream"},
+        ),
+    ],
+)
+async def fails_to_deliver(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get SEC fails-to-deliver for a US stock or ETF, one row per settlement date."""
+    return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="AuraStreamFundingRates",
+    examples=[
+        APIEx(
+            description="Funding rates of the Bitcoin and Ether perpetuals.",
+            parameters={"symbol": "BTCUSDT,ETHUSDT", "provider": "aurastream"},
+        ),
+    ],
+)
+async def funding_rates(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get Binance USD-M perpetual funding rates at each funding time."""
+    return await OBBject.from_query(Query(**locals()))

openbb_aurastream/models/__init__.py

@@ -0,0 +1 @@
+"""AuraStream models."""

openbb_aurastream/models/fails_to_deliver.py

@@ -0,0 +1,99 @@
+"""AuraStream Fails-to-Deliver Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from pydantic import Field
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    require_key,
+    split_symbols,
+    to_rows,
+)
+
+
+class AuraStreamFailsToDeliverQueryParams(SeriesQueryParams):
+    """AuraStream Fails-to-Deliver Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/edgar/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        description="US stock or ETF symbol (e.g. 'GME') or 9-character CUSIP."
+    )
+    start_date: dateType | None = Field(
+        default=None, description="Start date. Default: one year ago."
+    )
+    end_date: dateType | None = Field(
+        default=None, description="End date. Default: today."
+    )
+
+
+class AuraStreamFailsToDeliverData(Data):
+    """AuraStream Fails-to-Deliver Data. One row per settlement date with fails outstanding."""
+
+    date: datetime = Field(description="Settlement date.")
+    symbol: str = Field(description="Security symbol.")
+    fails: int | None = Field(
+        default=None, description="Total fails-to-deliver balance, in shares."
+    )
+    price: float | None = Field(
+        default=None, description="Previous day's closing price."
+    )
+    cusip: str | None = Field(default=None, description="CUSIP of the security.")
+    description: str | None = Field(default=None, description="Security description.")
+
+
+class AuraStreamFailsToDeliverFetcher(
+    Fetcher[AuraStreamFailsToDeliverQueryParams, list[AuraStreamFailsToDeliverData]]
+):
+    """Fetch SEC fails-to-deliver from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamFailsToDeliverQueryParams:
+        """Transform the query."""
+        return AuraStreamFailsToDeliverQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamFailsToDeliverQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return the raw rows."""
+        key = api_key(credentials)
+        user_agent = require_key(
+            credentials,
+            "aurastream_sec_user_agent",
+            "The SEC asks every automated request to name the sender: your name or company"
+            " and a contact email, e.g. 'Jane Doe jane@example.com'.",
+        )
+        symbols = [s.upper() for s in split_symbols(query.symbol)]
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1d",
+            "source": "edgar",
+            "dataset": "ftd",
+            "credentials": {"user_agent": user_agent},
+        }
+        data = await fetch(body, key)
+        return to_rows(data, symbols)
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamFailsToDeliverQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamFailsToDeliverData]:
+        """Transform the data."""
+        return [AuraStreamFailsToDeliverData.model_validate(d) for d in data]

openbb_aurastream/models/fred_vintages.py

@@ -0,0 +1,112 @@
+"""AuraStream FRED Vintages Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from openbb_core.provider.utils.errors import EmptyDataError
+from pydantic import Field
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    parse_timestamp,
+    require_key,
+    split_symbols,
+)
+
+
+class AuraStreamFredVintagesQueryParams(SeriesQueryParams):
+    """AuraStream FRED Vintages Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/fred/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        description="FRED series ID, e.g. 'CPIAUCSL', 'UNRATE', 'GDPC1'."
+    )
+    start_date: dateType | None = Field(
+        default=None,
+        description="First publication date. Default: one year ago.",
+    )
+    end_date: dateType | None = Field(
+        default=None, description="Last publication date. Default: today."
+    )
+
+
+class AuraStreamFredVintagesData(Data):
+    """AuraStream FRED Vintages Data. One row per published value."""
+
+    date: datetime = Field(description="Publication date of the value.")
+    symbol: str = Field(description="FRED series ID.")
+    reference_date: datetime = Field(description="The period the value describes.")
+    value: float | None = Field(default=None, description="The value as published.")
+
+
+class AuraStreamFredVintagesFetcher(
+    Fetcher[AuraStreamFredVintagesQueryParams, list[AuraStreamFredVintagesData]]
+):
+    """Fetch every published version of FRED series from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamFredVintagesQueryParams:
+        """Transform the query."""
+        return AuraStreamFredVintagesQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamFredVintagesQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return one row per (publication date, period)."""
+        key = api_key(credentials)
+        fred_key = require_key(
+            credentials,
+            "aurastream_fred_api_key",
+            "FRED needs a free key of your own: https://fred.stlouisfed.org/docs/api/api_key.html.",
+        )
+        symbols = [s.upper() for s in split_symbols(query.symbol)]
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1d",  # ignored: each series comes at its own frequency
+            "source": "fred",
+            "credentials": {"key": fred_key},
+        }
+        data = await fetch(body, key)
+
+        rows: list[dict] = []
+        for symbol in symbols:
+            series = data.get(symbol)
+            if not isinstance(series, dict):
+                continue
+            for published, row in series.items():
+                for update in (row or {}).get("updates") or []:
+                    rows.append(
+                        {
+                            "date": parse_timestamp(published),
+                            "symbol": symbol,
+                            "reference_date": parse_timestamp(update["reference_date"]),
+                            "value": update.get("value"),
+                        }
+                    )
+        if not rows:
+            raise EmptyDataError(f"AuraStream returned no data for {', '.join(symbols)}.")
+        rows.sort(key=lambda r: (r["date"], r["symbol"], r["reference_date"]))
+        return rows
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamFredVintagesQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamFredVintagesData]:
+        """Transform the data."""
+        return [AuraStreamFredVintagesData.model_validate(d) for d in data]

openbb_aurastream/models/funding_rates.py

@@ -0,0 +1,90 @@
+"""AuraStream Binance Funding Rates Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from pydantic import Field
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    split_symbols,
+    to_rows,
+)
+
+
+class AuraStreamFundingRatesQueryParams(SeriesQueryParams):
+    """AuraStream Binance Funding Rates Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/binance/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        default="BTCUSDT",
+        description="Binance USD-M perpetual symbol, e.g. 'BTCUSDT', 'ETHUSDT'.",
+    )
+    start_date: dateType | None = Field(
+        default=None, description="Start date. Default: one year ago."
+    )
+    end_date: dateType | None = Field(
+        default=None, description="End date. Default: today."
+    )
+
+
+class AuraStreamFundingRatesData(Data):
+    """AuraStream Binance Funding Rates Data. One row per funding time."""
+
+    __alias_dict__ = {"funding_rate": "fundingRate"}
+
+    date: datetime = Field(description="Funding time.")
+    symbol: str = Field(description="Perpetual symbol.")
+    funding_rate: float | None = Field(
+        default=None,
+        description="Funding rate for the period, as a fraction (0.0001 = 0.01%).",
+    )
+
+
+class AuraStreamFundingRatesFetcher(
+    Fetcher[AuraStreamFundingRatesQueryParams, list[AuraStreamFundingRatesData]]
+):
+    """Fetch Binance perpetual funding rates from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamFundingRatesQueryParams:
+        """Transform the query."""
+        return AuraStreamFundingRatesQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamFundingRatesQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return the raw rows."""
+        symbols = [s.upper() for s in split_symbols(query.symbol)]
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1h",
+            "source": "binance",
+            "instrument": "futures",
+            "bars": "funding",
+        }
+        data = await fetch(body, api_key(credentials))
+        return to_rows(data, symbols)
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamFundingRatesQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamFundingRatesData]:
+        """Transform the data."""
+        return [AuraStreamFundingRatesData.model_validate(d) for d in data]

openbb_aurastream/models/net_short.py

@@ -0,0 +1,124 @@
+"""AuraStream EU Net Short Positions Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from pydantic import Field, field_validator
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    split_symbols,
+    to_rows,
+)
+
+
+class AuraStreamNetShortQueryParams(SeriesQueryParams):
+    """AuraStream EU Net Short Positions Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/netshort/
+    """
+
+    __json_schema_extra__ = {
+        "symbol": {"multiple_items_allowed": True},
+        "country": {"multiple_items_allowed": True, "choices": ["FR", "NL", "ES"]},
+    }
+
+    symbol: str = Field(
+        description="ISIN (e.g. 'FR0000054470'), part of the issuer's name (e.g. 'ubisoft'),"
+        + " or 'all' for every position in the period.",
+    )
+    start_date: dateType | None = Field(
+        default=None, description="Start date. Default: one year ago."
+    )
+    end_date: dateType | None = Field(
+        default=None, description="End date. Default: today."
+    )
+    country: str | None = Field(
+        default=None,
+        description="Registers to search: FR (AMF), NL (AFM), ES (CNMV). Default: all three.",
+    )
+    holder: str | None = Field(
+        default=None,
+        description="Keep positions whose holder name contains this text, e.g. 'citadel'.",
+    )
+
+
+    @field_validator("symbol", mode="before", check_fields=False)
+    @classmethod
+    def to_upper(cls, v: str) -> str:
+        """Keep the symbol as written: these tickers are case-sensitive."""
+        return v
+
+
+class AuraStreamNetShortData(Data):
+    """AuraStream EU Net Short Positions Data. One row per published position."""
+
+    date: datetime = Field(description="Position date.")
+    symbol: str = Field(description="The symbol as requested.")
+    holder: str | None = Field(default=None, description="Position holder.")
+    issuer: str | None = Field(default=None, description="Company name.")
+    isin: str | None = Field(default=None, description="Company ISIN.")
+    net_short_pct: float | None = Field(
+        default=None,
+        description="Net short position, in percent of issued share capital (0.62 = 0.62%).",
+    )
+    country: str | None = Field(default=None, description="FR, NL or ES.")
+    holder_lei: str | None = Field(
+        default=None, description="Holder's Legal Entity Identifier (France only)."
+    )
+    published_from: str | None = Field(
+        default=None, description="First date on the public register (France only)."
+    )
+    published_to: str | None = Field(
+        default=None, description="Last date on the public register (France only)."
+    )
+    source: str | None = Field(
+        default=None, description="The attribution the regulator requires."
+    )
+
+
+class AuraStreamNetShortFetcher(
+    Fetcher[AuraStreamNetShortQueryParams, list[AuraStreamNetShortData]]
+):
+    """Fetch EU net short positions from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamNetShortQueryParams:
+        """Transform the query."""
+        return AuraStreamNetShortQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamNetShortQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return the raw rows."""
+        symbols = split_symbols(query.symbol)
+        body: dict[str, Any] = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1d",
+            "source": "netshort",
+        }
+        if query.country:
+            body["country"] = [c.upper() for c in split_symbols(query.country)]
+        if query.holder:
+            body["holder"] = query.holder
+        data = await fetch(body, api_key(credentials))
+        return to_rows(data, symbols)
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamNetShortQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamNetShortData]:
+        """Transform the data."""
+        return [AuraStreamNetShortData.model_validate(d) for d in data]

openbb_aurastream/models/wasde.py

@@ -0,0 +1,104 @@
+"""AuraStream USDA WASDE Model."""
+
+from datetime import date as dateType, datetime
+from typing import Any
+
+from openbb_core.provider.abstract.data import Data
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.bls_series import SeriesQueryParams
+from pydantic import Field, field_validator
+
+from openbb_aurastream.utils.client import (
+    api_key,
+    default_start,
+    fetch,
+    split_symbols,
+    to_rows,
+)
+
+
+class AuraStreamWasdeQueryParams(SeriesQueryParams):
+    """AuraStream USDA WASDE Query.
+
+    Source: https://aurastream.unbiased-alpha.com/docs/data-sources/wasde/
+    """
+
+    __json_schema_extra__ = {"symbol": {"multiple_items_allowed": True}}
+
+    symbol: str = Field(
+        description="'commodity:attribute' for the US balance sheet (e.g. 'corn:ending_stocks'),"
+        + " or 'commodity:attribute:region' for the world tables (e.g. 'soybeans:production:Brazil').",
+    )
+    start_date: dateType | None = Field(
+        default=None, description="Start date. Default: one year ago."
+    )
+    end_date: dateType | None = Field(
+        default=None, description="End date. Default: today."
+    )
+
+
+    @field_validator("symbol", mode="before", check_fields=False)
+    @classmethod
+    def to_upper(cls, v: str) -> str:
+        """Keep the symbol as written: these tickers are case-sensitive."""
+        return v
+
+
+class AuraStreamWasdeData(Data):
+    """AuraStream USDA WASDE Data. One row per report."""
+
+    date: datetime = Field(description="Report release time (12:00 New York).")
+    symbol: str = Field(description="The series as requested.")
+    report: str | None = Field(
+        default=None, description="Report month, e.g. 'October 2026'."
+    )
+    market_year: str | None = Field(
+        default=None, description="Marketing year projected, e.g. '2026/27'."
+    )
+    value: float | None = Field(default=None, description="This report's projection.")
+    previous: float | None = Field(
+        default=None,
+        description="The previous month's projection, as printed in the same report.",
+    )
+    prior_year: str | None = Field(default=None, description="The year before.")
+    prior_year_value: float | None = Field(
+        default=None, description="The estimate for the year before."
+    )
+
+
+class AuraStreamWasdeFetcher(
+    Fetcher[AuraStreamWasdeQueryParams, list[AuraStreamWasdeData]]
+):
+    """Fetch WASDE projections from AuraStream."""
+
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(params: dict[str, Any]) -> AuraStreamWasdeQueryParams:
+        """Transform the query."""
+        return AuraStreamWasdeQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: AuraStreamWasdeQueryParams,
+        credentials: dict[str, str] | None,
+        **kwargs: Any,
+    ) -> list[dict]:
+        """Return the raw rows."""
+        symbols = split_symbols(query.symbol)
+        body = {
+            "tickerlist": symbols,
+            "start": str(query.start_date or default_start()),
+            "end": str(query.end_date or dateType.today()),
+            "interval": "1m",
+            "source": "wasde",
+        }
+        data = await fetch(body, api_key(credentials))
+        return to_rows(data, symbols)
+
+    @staticmethod
+    def transform_data(
+        query: AuraStreamWasdeQueryParams, data: list[dict], **kwargs: Any
+    ) -> list[AuraStreamWasdeData]:
+        """Transform the data."""
+        return [AuraStreamWasdeData.model_validate(d) for d in data]

openbb_aurastream/utils/__init__.py

@@ -0,0 +1 @@
+"""AuraStream utilities."""

openbb_aurastream/utils/client.py

@@ -0,0 +1,148 @@
+"""Thin async client for the AuraStream /timeseries endpoint."""
+
+import os
+from datetime import date, datetime, timedelta
+from typing import Any
+
+from openbb_core.app.model.abstract.error import OpenBBError
+from openbb_core.provider.utils.errors import EmptyDataError, UnauthorizedError
+
+API_URL = os.environ.get(
+    "AURASTREAM_API_URL", "https://api.aurastream.unbiased-alpha.com/timeseries"
+)
+DASHBOARD_URL = "https://aurastream.unbiased-alpha.com"
+TIMEOUT_SECONDS = 130  # the API itself times out at 120 s
+
+
+def default_start() -> date:
+    """One year back, the default start of a query."""
+    return date.today() - timedelta(days=365)
+
+
+def require_key(credentials: dict[str, str] | None, name: str, hint: str) -> str:
+    """Return a credential or raise an error saying how to set it."""
+    value = (credentials or {}).get(name)
+    if not value:
+        raise UnauthorizedError(
+            f"Missing credential '{name}'. {hint} Set it with "
+            f'obb.user.credentials.{name} = "..." or in ~/.openbb_platform/user_settings.json.'
+        )
+    return value
+
+
+def api_key(credentials: dict[str, str] | None) -> str:
+    """The AuraStream API key."""
+    return require_key(
+        credentials,
+        "aurastream_api_key",
+        f"Get a free key (500 calls a month, no credit card) at {DASHBOARD_URL}/sign-up.",
+    )
+
+
+def _error_message(status: int, detail: str) -> str:
+    if status == 429:
+        if "limit exceeded" in detail.lower():
+            return (
+                "AuraStream monthly call allowance is used up. It resets on the 1st of next month "
+                f"(00:00 UTC); to keep going now, upgrade the plan at {DASHBOARD_URL}."
+            )
+        return "AuraStream rate limit hit. Wait a few seconds and retry."
+    if status in (401, 403):
+        return (
+            f"AuraStream rejected the API key (HTTP {status}). "
+            f"Check aurastream_api_key; keys are on the dashboard at {DASHBOARD_URL}."
+        )
+    if status == 400:
+        return f"AuraStream rejected the request (HTTP 400): {detail or 'no detail'}."
+    if status in (502, 504):
+        return (
+            f"AuraStream timed out (HTTP {status}). "
+            "Try a shorter date range or fewer symbols."
+        )
+    return f"AuraStream returned HTTP {status}: {detail or 'no detail'}"
+
+
+async def fetch(body: dict[str, Any], key: str) -> dict[str, Any]:
+    """POST the body to AuraStream and return the parsed JSON."""
+    import aiohttp
+
+    timeout = aiohttp.ClientTimeout(total=TIMEOUT_SECONDS)
+    try:
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(
+                API_URL, json=body, headers={"x-api-key": key}
+            ) as resp:
+                status = resp.status
+                text = await resp.text()
+    except TimeoutError:
+        raise OpenBBError(
+            "AuraStream did not answer in time. Try a shorter date range or fewer symbols."
+        ) from None
+    except aiohttp.ClientError as exc:
+        raise OpenBBError(f"Could not reach AuraStream: {exc}") from None
+
+    import json
+
+    try:
+        data = json.loads(text)
+    except ValueError:
+        data = None
+
+    if status != 200:
+        detail = ""
+        if isinstance(data, dict):
+            detail = str(
+                data.get("message") or data.get("error") or data.get("detail") or ""
+            )
+        elif text:
+            detail = text.strip()
+        message = _error_message(status, detail[:300])
+        if status in (401, 403):
+            raise UnauthorizedError(message)
+        raise OpenBBError(message)
+
+    if not isinstance(data, dict):
+        raise OpenBBError("AuraStream returned a response that is not a JSON object.")
+    # Errors that come back with a 200, e.g. {"error": "..."}.
+    if len(data) == 1:
+        k, v = next(iter(data.items()))
+        if k in ("error", "message") and isinstance(v, str):
+            raise OpenBBError(f"AuraStream error: {v[:300]}")
+    return data
+
+
+def parse_timestamp(value: str) -> datetime:
+    """Parse a row key such as '2025-02-12 00:00:00' or '2025-02-12 00:00:00.000001'."""
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def to_rows(data: dict[str, Any], symbols: list[str]) -> list[dict[str, Any]]:
+    """Flatten {symbol: {timestamp: fields}} into rows with 'date' and 'symbol'.
+
+    Raises EmptyDataError when no symbol returned any row.
+    """
+    rows: list[dict[str, Any]] = []
+    errors: list[str] = []
+    for symbol in symbols:
+        series = data.get(symbol)
+        if isinstance(series, str):
+            errors.append(f"{symbol}: {series[:200]}")
+            continue
+        if not isinstance(series, dict):
+            continue
+        for ts, fields in series.items():
+            if not isinstance(fields, dict):
+                continue
+            row = {"date": parse_timestamp(ts), "symbol": symbol}
+            row.update(fields)
+            rows.append(row)
+    if not rows:
+        extra = f" ({'; '.join(errors)})" if errors else ""
+        raise EmptyDataError(f"AuraStream returned no data for {', '.join(symbols)}{extra}.")
+    rows.sort(key=lambda r: (r["date"], r["symbol"]))
+    return rows
+
+
+def split_symbols(symbol: str) -> list[str]:
+    """'a, b' -> ['a', 'b']."""
+    return [s.strip() for s in symbol.split(",") if s.strip()]

openbb_aurastream-0.1.0.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: openbb-aurastream
+Version: 0.1.0
+Summary: AuraStream data for the OpenBB Platform: EU net short positions, USDA WASDE, FRED vintages, SEC fails-to-deliver and Binance funding rates.
+Project-URL: Homepage, https://aurastream.unbiased-alpha.com
+Project-URL: Documentation, https://aurastream.unbiased-alpha.com/docs/
+Project-URL: Source, https://github.com/UnbiasedAlpha/openbb-aurastream
+Author: Unbiased Alpha
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aurastream,fred,market data,openbb,quant,short selling,wasde
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: openbb-core<3,>=2.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# openbb-aurastream
+
+[AuraStream](https://aurastream.unbiased-alpha.com) data for the [OpenBB Platform](https://github.com/OpenBB-finance/OpenBB). The extension adds five commands under `obb.aurastream`. Each covers a dataset that the other OpenBB providers don't offer:
+
+| Command | Data |
+|---|---|
+| `net_short` | EU net short positions of 0.5% or more, with the holder's name, from the French (AMF), Dutch (AFM) and Spanish (CNMV) registers, back to 2010–2012 |
+| `wasde` | USDA WASDE projections since July 2010: US balance sheets and world tables by country, one row per monthly report |
+| `fred_vintages` | FRED series with every revision, stamped at the date each value was published |
+| `fails_to_deliver` | SEC fails-to-deliver for any US stock or ETF |
+| `funding_rates` | Binance USD-M perpetual funding rates |
+
+## Install
+
+```
+pip install openbb openbb-aurastream
+```
+
+OpenBB rebuilds its Python interface the first time you import it after installing.
+
+## Credentials
+
+You need an AuraStream API key. The free plan includes 500 calls a month, with no credit card required: [sign up here](https://aurastream.unbiased-alpha.com/sign-up).
+
+```python
+from openbb import obb
+
+obb.user.credentials.aurastream_api_key = "..."
+# Only for fred_vintages: your own free FRED key (https://fred.stlouisfed.org/docs/api/api_key.html)
+obb.user.credentials.aurastream_fred_api_key = "..."
+# Only for fails_to_deliver: the SEC asks automated requests to name the sender
+obb.user.credentials.aurastream_sec_user_agent = "Jane Doe jane@example.com"
+```
+
+You can also keep them in `~/.openbb_platform/user_settings.json`.
+
+## Examples
+
+```python
+from openbb import obb
+
+# Who is short Ubisoft, and by how much
+shorts = obb.aurastream.net_short("ubisoft", start_date="2024-01-01", country="FR").to_df()
+shorts.pivot_table(index=shorts.index.date, columns="holder", values="net_short_pct").ffill()
+
+# Every position one fund has disclosed
+obb.aurastream.net_short("all", holder="citadel", start_date="2026-01-01").to_df()
+
+# How the USDA's projection of US corn ending stocks changed, report by report
+corn = obb.aurastream.wasde("corn:ending_stocks", start_date="2024-01-01").to_df()
+corn["revision"] = corn["value"] - corn["previous"]
+
+# Brazil's soybean crop from the world tables
+obb.aurastream.wasde("soybeans:production:Brazil").to_df()
+
+# CPI as first published vs. after revisions
+cpi = obb.aurastream.fred_vintages("CPIAUCSL", start_date="2020-01-01").to_df()
+first_print = cpi.groupby("reference_date")["value"].first()
+latest = cpi.groupby("reference_date")["value"].last()
+
+# Fails-to-deliver in GameStop
+obb.aurastream.fails_to_deliver("GME", start_date="2024-01-01", end_date="2025-01-01").to_df()
+
+# Funding rates of the Bitcoin and Ether perpetuals
+obb.aurastream.funding_rates("BTCUSDT,ETHUSDT", start_date="2025-06-01").to_df()
+```
+
+Without `start_date`, each command returns the last year.
+
+## Timing
+
+All five datasets are historical, not real-time, and each row is stamped when the data became public:
+
+- EU net short positions are published by the next trading day, so lag them by one day in a backtest.
+- WASDE rows are stamped at the report's release, 12:00 New York time.
+- For `fred_vintages`, `start_date` and `end_date` filter on the publication date.
+- The SEC publishes fails-to-deliver twice a month, about two weeks after each half-month ends.
+
+See the [AuraStream docs](https://aurastream.unbiased-alpha.com/docs/) for the field definitions and coverage of each source.
+
+## Data terms
+
+- France: source Autorité des marchés financiers (AMF), data.gouv.fr, Licence Ouverte 2.0.
+- Netherlands: source AFM.
+- Spain: this information can be obtained free of charge from the CNMV website (www.cnmv.es).
+- Holder names can belong to individuals, so treat them as personal data under the GDPR.
+
+## License
+
+MIT. This package is by Unbiased Alpha and is not affiliated with OpenBB.

openbb_aurastream-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+openbb_aurastream/__init__.py,sha256=ncT7sOUpQ79J6msgiqz_Txf-2E2DfK_7FWKe9DzkctI,1622
+openbb_aurastream/aurastream_router.py,sha256=TOjQq_Xs14KDBvAVWQAt4XxqwAFExPKwcQVD5SFaIjw,3700
+openbb_aurastream/models/__init__.py,sha256=PTHyuY9uRh3ZtnbI_7kRQZSCDvabO3-MYWc8suSLkB8,25
+openbb_aurastream/models/fails_to_deliver.py,sha256=xk15CRydka3BPIdGL8ek7yk2PGg0yLlGEvKT5YqugGo,3424
+openbb_aurastream/models/fred_vintages.py,sha256=PTXuTomqQDPj6TQkquK7TRuMCopXetcCVsZ8L3jS10I,4068
+openbb_aurastream/models/funding_rates.py,sha256=s6RXyvdo_SDshiIENd8y7mDrwHCG0qFH26j4IAGVpwk,2924
+openbb_aurastream/models/net_short.py,sha256=lACSVBl4QaBBHJFWsRDypIU8oMNTEId7E-QRHPS3l1U,4426
+openbb_aurastream/models/wasde.py,sha256=qQXkXwem_u0Ea-yNnidrGUZ9Bg9VS0JPk4B8CyMY1R8,3521
+openbb_aurastream/utils/__init__.py,sha256=fcXDU1Q3QrZ8YUDBSBmDRyaMWeMcXWp1K00qr0txNPQ,28
+openbb_aurastream/utils/client.py,sha256=Oo5cG_AAhEbQH1nZBTOhpvDdmSnqtkBvWvdmUIPBMIo,5355
+openbb_aurastream-0.1.0.dist-info/METADATA,sha256=DIdERbM4BXX5KTCAi_f3YvZw0Kv6HWxa-utIh4bW010,4650
+openbb_aurastream-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openbb_aurastream-0.1.0.dist-info/entry_points.txt,sha256=f_A7WUSp88inDmSAUFWeNiGTGx83MperMel3F6wWsWI,160
+openbb_aurastream-0.1.0.dist-info/licenses/LICENSE,sha256=PXINVVvEqW2nfyyKueaoj_IoKs-luXnuyQ0uef99PKY,1071
+openbb_aurastream-0.1.0.dist-info/RECORD,,

openbb_aurastream-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

openbb_aurastream-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[openbb_core_extension]
+aurastream = openbb_aurastream.aurastream_router:router
+
+[openbb_provider_extension]
+aurastream = openbb_aurastream:aurastream_provider

openbb_aurastream-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unbiased Alpha
+
+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.