openbb-tradingagent 1.0.0__tar.gz

openbb_tradingagent-1.0.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: openbb-tradingagent
+Version: 1.0.0
+Summary: Point-in-time company fundamentals from tradingagentapp.com for the OpenBB Platform (US SEC EDGAR, Taiwan TWSE, Korea OpenDART).
+License: MIT
+Keywords: openbb,fundamentals,point-in-time,edgar,twse,opendart
+Author: Trading Agent
+Author-email: tradingagentapp@gmail.com
+Requires-Python: >=3.10,<4
+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: Programming Language :: Python :: 3.14
+Requires-Dist: openbb-core (>=1.6.10,<2.0.0)
+Project-URL: Homepage, https://www.tradingagentapp.com/fundamentals
+Project-URL: Repository, https://github.com/Wei-LienWU/trading-agent
+Description-Content-Type: text/markdown
+
+# Trading Agent provider for OpenBB
+
+Point-in-time, **as-first-reported** company fundamentals from official regulator
+filings — inside the OpenBB Platform.
+
+| Market | Source | Coverage |
+| --- | --- | --- |
+| United States | SEC EDGAR (XBRL) | ~7,000 filers, annual + quarterly, FY2014→ |
+| Taiwan | Taiwan Stock Exchange OpenAPI | every listed company |
+| Korea | FSS OpenDART | loading (full market) |
+
+Every value is keyed by the **official filing date it became public on**, and
+queries accept an `as_of` knowledge date — so a backtest at date *T* sees only
+what was public at *T*. No restatement look-ahead.
+
+## Install
+
+```bash
+pip install openbb-tradingagent
+openbb-build   # regenerate the static assets so the provider appears
+```
+
+## Use
+
+The provider attaches to OpenBB's existing fundamentals commands:
+
+```python
+from openbb import obb
+
+# No key needed — the demo tier covers 25 flagship tickers at full fidelity.
+obb.equity.fundamental.latest_attributes(
+    symbol="2330.TW", tag="revenue,net_income", provider="tradingagent"
+)
+
+# Point-in-time: what did AAPL's reported revenue history look like on 2022-01-01?
+obb.equity.fundamental.historical_attributes(
+    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
+)
+```
+
+Set a key for the full universe:
+
+```python
+obb.user.credentials.tradingagent_api_key = "ta_live_…"
+```
+
+or in `~/.openbb_platform/user_settings.json`:
+
+```json
+{ "credentials": { "tradingagent_api_key": "ta_live_…" } }
+```
+
+Without a key the provider falls back to the public `demo` key: 25 flagship
+tickers (US, Taiwan, Korea), full history, all fields, no signup. Paid plans
+unlock every ticker — your code does not change.
+
+## The `as_of` parameter
+
+This is the reason the provider exists. Most fundamentals APIs serve *today's*
+restated figures against *historical* dates, which quietly leaks future
+information into a backtest. Here, `as_of` filters to `filed <= as_of`:
+
+```python
+# FY2021 as it was actually reported, not as later amended
+obb.equity.fundamental.latest_attributes(
+    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
+)
+```
+
+## Fields
+
+`historical_attributes` returns, per row: `date` (period end), `symbol`, `tag`,
+`value`, `unit`, `fiscal_year`, `fiscal_period`, `filed`, `form`, `market`,
+`issuer_id`.
+
+Available tags include `revenue`, `net_income`, `assets`, `liabilities`,
+`equity`, `cash`, `gross_profit`, `operating_income`, `long_term_debt`,
+`rnd_expense`, `eps_diluted`, `shares_diluted`, plus derived ratios
+`net_margin`, `gross_margin`, `operating_margin`, `roe`, `roa`,
+`debt_to_equity`, `asset_turnover`.
+
+## Data notes
+
+- **Taiwan income-statement figures are cumulative year-to-date** (Taiwan
+  reporting convention): Q2 is the H1 total, Q4 the full year. Difference
+  adjacent quarters for single-quarter flows. Balance-sheet items are
+  point-in-time as usual.
+- Values are as filed. Filers make mistakes; we do not silently correct them.
+
+## Sources and licences
+
+- **US** — SEC EDGAR, public domain.
+- **Taiwan** — Taiwan Stock Exchange, under the Open Government Data License 1.0.
+  The attribution is embedded in every API response and must be preserved.
+- **Korea** — FSS OpenDART. Public data; the FSS confirmed in writing that no
+  separate approval agreement is required for commercial use.
+
+Factual historical data only — not investment advice, not a recommendation.
+
+Full API documentation: <https://www.tradingagentapp.com/developers>
+Pricing and licences: <https://www.tradingagentapp.com/fundamentals>
+
+MIT licensed. Operated by WU Capital Limited, Auckland, New Zealand.
+

openbb_tradingagent-1.0.0/README.md

@@ -0,0 +1,103 @@
+# Trading Agent provider for OpenBB
+
+Point-in-time, **as-first-reported** company fundamentals from official regulator
+filings — inside the OpenBB Platform.
+
+| Market | Source | Coverage |
+| --- | --- | --- |
+| United States | SEC EDGAR (XBRL) | ~7,000 filers, annual + quarterly, FY2014→ |
+| Taiwan | Taiwan Stock Exchange OpenAPI | every listed company |
+| Korea | FSS OpenDART | loading (full market) |
+
+Every value is keyed by the **official filing date it became public on**, and
+queries accept an `as_of` knowledge date — so a backtest at date *T* sees only
+what was public at *T*. No restatement look-ahead.
+
+## Install
+
+```bash
+pip install openbb-tradingagent
+openbb-build   # regenerate the static assets so the provider appears
+```
+
+## Use
+
+The provider attaches to OpenBB's existing fundamentals commands:
+
+```python
+from openbb import obb
+
+# No key needed — the demo tier covers 25 flagship tickers at full fidelity.
+obb.equity.fundamental.latest_attributes(
+    symbol="2330.TW", tag="revenue,net_income", provider="tradingagent"
+)
+
+# Point-in-time: what did AAPL's reported revenue history look like on 2022-01-01?
+obb.equity.fundamental.historical_attributes(
+    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
+)
+```
+
+Set a key for the full universe:
+
+```python
+obb.user.credentials.tradingagent_api_key = "ta_live_…"
+```
+
+or in `~/.openbb_platform/user_settings.json`:
+
+```json
+{ "credentials": { "tradingagent_api_key": "ta_live_…" } }
+```
+
+Without a key the provider falls back to the public `demo` key: 25 flagship
+tickers (US, Taiwan, Korea), full history, all fields, no signup. Paid plans
+unlock every ticker — your code does not change.
+
+## The `as_of` parameter
+
+This is the reason the provider exists. Most fundamentals APIs serve *today's*
+restated figures against *historical* dates, which quietly leaks future
+information into a backtest. Here, `as_of` filters to `filed <= as_of`:
+
+```python
+# FY2021 as it was actually reported, not as later amended
+obb.equity.fundamental.latest_attributes(
+    symbol="AAPL", tag="revenue", provider="tradingagent", as_of="2022-01-01"
+)
+```
+
+## Fields
+
+`historical_attributes` returns, per row: `date` (period end), `symbol`, `tag`,
+`value`, `unit`, `fiscal_year`, `fiscal_period`, `filed`, `form`, `market`,
+`issuer_id`.
+
+Available tags include `revenue`, `net_income`, `assets`, `liabilities`,
+`equity`, `cash`, `gross_profit`, `operating_income`, `long_term_debt`,
+`rnd_expense`, `eps_diluted`, `shares_diluted`, plus derived ratios
+`net_margin`, `gross_margin`, `operating_margin`, `roe`, `roa`,
+`debt_to_equity`, `asset_turnover`.
+
+## Data notes
+
+- **Taiwan income-statement figures are cumulative year-to-date** (Taiwan
+  reporting convention): Q2 is the H1 total, Q4 the full year. Difference
+  adjacent quarters for single-quarter flows. Balance-sheet items are
+  point-in-time as usual.
+- Values are as filed. Filers make mistakes; we do not silently correct them.
+
+## Sources and licences
+
+- **US** — SEC EDGAR, public domain.
+- **Taiwan** — Taiwan Stock Exchange, under the Open Government Data License 1.0.
+  The attribution is embedded in every API response and must be preserved.
+- **Korea** — FSS OpenDART. Public data; the FSS confirmed in writing that no
+  separate approval agreement is required for commercial use.
+
+Factual historical data only — not investment advice, not a recommendation.
+
+Full API documentation: <https://www.tradingagentapp.com/developers>
+Pricing and licences: <https://www.tradingagentapp.com/fundamentals>
+
+MIT licensed. Operated by WU Capital Limited, Auckland, New Zealand.

openbb_tradingagent-1.0.0/openbb_tradingagent/__init__.py

@@ -0,0 +1,34 @@
+"""Trading Agent provider for the OpenBB Platform.
+
+Point-in-time, as-first-reported company fundamentals from official
+regulator filings (US SEC EDGAR, Taiwan TWSE, Korea FSS OpenDART).
+Every row carries its official filing date; queries can be pinned to an
+`as_of` knowledge date so a backtest at date T sees only what was public
+at T — no restatement look-ahead.
+"""
+
+from openbb_core.provider.abstract.provider import Provider
+
+from openbb_tradingagent.models.historical_attributes import (
+    TradingAgentHistoricalAttributesFetcher,
+)
+from openbb_tradingagent.models.latest_attributes import (
+    TradingAgentLatestAttributesFetcher,
+)
+
+tradingagent_provider = Provider(
+    name="tradingagent",
+    website="https://www.tradingagentapp.com",
+    description=(
+        "Point-in-time company fundamentals from official regulator filings "
+        "(US SEC EDGAR, Taiwan TWSE, Korea FSS OpenDART). As-first-reported "
+        "values keyed by filing date, with an `as_of` parameter for "
+        "look-ahead-free backtests. Works without a key on 25 flagship "
+        "tickers (demo tier); paid keys unlock the full universe."
+    ),
+    credentials=["api_key"],
+    fetcher_dict={
+        "LatestAttributes": TradingAgentLatestAttributesFetcher,
+        "HistoricalAttributes": TradingAgentHistoricalAttributesFetcher,
+    },
+)

openbb_tradingagent-1.0.0/openbb_tradingagent/models/__init__.py

@@ -0,0 +1 @@
+"""Trading Agent provider models."""

openbb_tradingagent-1.0.0/openbb_tradingagent/models/historical_attributes.py

@@ -0,0 +1,179 @@
+"""Trading Agent Historical Attributes Model."""
+
+# pylint: disable=unused-argument
+
+from datetime import date as dateType
+from typing import Any, Dict, List, Optional
+
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.historical_attributes import (
+    HistoricalAttributesData,
+    HistoricalAttributesQueryParams,
+)
+from openbb_core.provider.utils.errors import EmptyDataError
+from pydantic import Field, field_validator
+
+from openbb_tradingagent.utils.helpers import get_data
+
+
+class TradingAgentHistoricalAttributesQueryParams(HistoricalAttributesQueryParams):
+    """Trading Agent Historical Attributes Query.
+
+    Source: https://www.tradingagentapp.com/developers#fundamentals
+    """
+
+    as_of: Optional[dateType] = Field(
+        default=None,
+        description=(
+            "Point-in-time knowledge date. Only facts whose official filing date"
+            " is on or before this date are returned, so a backtest at date T"
+            " sees exactly what was public at T (no restatement look-ahead)."
+        ),
+    )
+
+
+class TradingAgentHistoricalAttributesData(HistoricalAttributesData):
+    """Trading Agent Historical Attributes Data.
+
+    One as-first-reported fact: a metric for one fiscal period, keyed by the
+    official filing date it became public on.
+    """
+
+    # All source-key mappings live here; do not use Field(alias=...) — the
+    # base Data model installs a camelCase alias generator that would win.
+    __alias_dict__ = {
+        "date": "end",
+        "symbol": "t",
+        "tag": "m",
+        "value": "v",
+        "unit": "u",
+        "fiscal_year": "fy",
+        "fiscal_period": "fp",
+        "market": "mkt",
+        "issuer_id": "c",
+    }
+
+    unit: Optional[str] = Field(
+        default=None,
+        description="Unit of measure (USD, shares, USD/shares, ratio, …).",
+    )
+    fiscal_year: Optional[int] = Field(
+        default=None,
+        description="Fiscal year of the period end.",
+    )
+    fiscal_period: Optional[str] = Field(
+        default=None,
+        description="Fiscal period (FY, Q1, Q2, Q3, Q4).",
+    )
+    filed: Optional[dateType] = Field(
+        default=None,
+        description="Official filing date — the point-in-time key.",
+    )
+    form: Optional[str] = Field(
+        default=None,
+        description="Source filing form type, where the regulator publishes one.",
+    )
+    market: Optional[str] = Field(
+        default=None,
+        description="Market the issuer is listed in (US, TW, KR, …).",
+    )
+    issuer_id: Optional[str] = Field(
+        default=None,
+        description="Regulator's own issuer identifier (SEC CIK, TWSE/DART code).",
+    )
+
+    @field_validator("value", mode="before", check_fields=False)
+    @classmethod
+    def validate_value(cls, v):
+        """Coerce numeric strings; drop anything non-numeric."""
+        if v is None or isinstance(v, float):
+            return v
+        try:
+            return float(v)
+        except (TypeError, ValueError):
+            return None
+
+
+class TradingAgentHistoricalAttributesFetcher(
+    Fetcher[
+        TradingAgentHistoricalAttributesQueryParams,
+        List[TradingAgentHistoricalAttributesData],
+    ]
+):
+    """Trading Agent Historical Attributes Fetcher."""
+
+    # The public `demo` key covers 25 flagship tickers at full fidelity, so the
+    # provider is usable before signup. Leaving this True would make OpenBB
+    # refuse the call outright when no key is configured.
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(
+        params: Dict[str, Any]
+    ) -> TradingAgentHistoricalAttributesQueryParams:
+        """Transform the query params."""
+        return TradingAgentHistoricalAttributesQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: TradingAgentHistoricalAttributesQueryParams,
+        credentials: Optional[Dict[str, str]],
+        **kwargs: Any,
+    ) -> List[Dict]:
+        """Extract the raw rows, one request per symbol."""
+        api_key = (credentials or {}).get("tradingagent_api_key")
+        symbols = [s.strip().upper() for s in query.symbol.split(",") if s.strip()]
+
+        results: List[Dict] = []
+        for symbol in symbols:
+            response = await get_data(
+                "/fundamentals",
+                {
+                    "ticker": symbol,
+                    "as_of": query.as_of.isoformat() if query.as_of else None,
+                    "from": query.start_date.isoformat() if query.start_date else None,
+                },
+                api_key,
+                **kwargs,
+            )
+            rows = response.get("data", []) if isinstance(response, dict) else []
+            # The API returns the ticker on the envelope, not on every row.
+            for row in rows:
+                row.setdefault("t", response.get("ticker", symbol))
+            results.extend(rows)
+
+        if not results:
+            raise EmptyDataError(
+                f"No fundamentals returned for {query.symbol}"
+                + (f" as of {query.as_of}" if query.as_of else "")
+                + ". Either the ticker is outside the covered universe, or no"
+                " filing was public by that date — each market's history depth"
+                " is listed at https://www.tradingagentapp.com/api/v1/fundamentals"
+            )
+        return results
+
+    @staticmethod
+    def transform_data(
+        query: TradingAgentHistoricalAttributesQueryParams,
+        data: List[Dict],
+        **kwargs: Any,
+    ) -> List[TradingAgentHistoricalAttributesData]:
+        """Filter to the requested tags and sort."""
+        tags = {t.strip().lower() for t in query.tag.split(",") if t.strip()}
+        rows = [r for r in data if not tags or str(r.get("m", "")).lower() in tags]
+
+        if query.end_date:
+            rows = [r for r in rows if str(r.get("end", "")) <= query.end_date.isoformat()]
+
+        rows.sort(key=lambda r: str(r.get("end", "")), reverse=query.sort == "desc")
+        if query.limit:
+            rows = rows[: query.limit]
+
+        if not rows:
+            raise EmptyDataError(
+                f"No rows for tag(s) '{query.tag}'. Discover the available metric"
+                " names from the API index at /api/v1/fundamentals."
+            )
+        return [
+            TradingAgentHistoricalAttributesData.model_validate(r) for r in rows
+        ]

openbb_tradingagent-1.0.0/openbb_tradingagent/models/latest_attributes.py

@@ -0,0 +1,140 @@
+"""Trading Agent Latest Attributes Model."""
+
+# pylint: disable=unused-argument
+
+from datetime import date as dateType
+from typing import Any, Dict, List, Optional
+
+from openbb_core.provider.abstract.fetcher import Fetcher
+from openbb_core.provider.standard_models.latest_attributes import (
+    LatestAttributesData,
+    LatestAttributesQueryParams,
+)
+from openbb_core.provider.utils.errors import EmptyDataError
+from pydantic import Field
+
+from openbb_tradingagent.utils.helpers import get_data
+
+
+class TradingAgentLatestAttributesQueryParams(LatestAttributesQueryParams):
+    """Trading Agent Latest Attributes Query.
+
+    Source: https://www.tradingagentapp.com/developers#fundamentals
+    """
+
+    as_of: Optional[dateType] = Field(
+        default=None,
+        description=(
+            "Point-in-time knowledge date. Returns the latest value per metric"
+            " that was already public on this date — 'latest' as of then, not"
+            " today's restated figure. Defaults to today."
+        ),
+    )
+
+
+class TradingAgentLatestAttributesData(LatestAttributesData):
+    """Trading Agent Latest Attributes Data.
+
+    The most recent as-first-reported value per metric, with the fiscal period
+    and filing date that produced it.
+    """
+
+    unit: Optional[str] = Field(
+        default=None,
+        description="Unit of measure (USD, shares, USD/shares, ratio, …).",
+    )
+    fiscal_year: Optional[int] = Field(
+        default=None, description="Fiscal year of the period end."
+    )
+    period_ending: Optional[dateType] = Field(
+        default=None, description="Period end date of the reported value."
+    )
+    filed: Optional[dateType] = Field(
+        default=None,
+        description="Official filing date — the point-in-time key.",
+    )
+
+
+class TradingAgentLatestAttributesFetcher(
+    Fetcher[
+        TradingAgentLatestAttributesQueryParams,
+        List[TradingAgentLatestAttributesData],
+    ]
+):
+    """Trading Agent Latest Attributes Fetcher."""
+
+    # The public `demo` key covers 25 flagship tickers at full fidelity, so the
+    # provider is usable before signup. Leaving this True would make OpenBB
+    # refuse the call outright when no key is configured.
+    require_credentials = False
+
+    @staticmethod
+    def transform_query(
+        params: Dict[str, Any]
+    ) -> TradingAgentLatestAttributesQueryParams:
+        """Transform the query params."""
+        return TradingAgentLatestAttributesQueryParams(**params)
+
+    @staticmethod
+    async def aextract_data(
+        query: TradingAgentLatestAttributesQueryParams,
+        credentials: Optional[Dict[str, str]],
+        **kwargs: Any,
+    ) -> List[Dict]:
+        """Extract the as-of snapshot and flatten it to one row per metric."""
+        api_key = (credentials or {}).get("tradingagent_api_key")
+        symbols = [s.strip().upper() for s in query.symbol.split(",") if s.strip()]
+
+        results: List[Dict] = []
+        for symbol in symbols:
+            response = await get_data(
+                "/fundamentals",
+                {
+                    "ticker": symbol,
+                    "view": "latest",
+                    "as_of": query.as_of.isoformat() if query.as_of else None,
+                },
+                api_key,
+                **kwargs,
+            )
+            snapshot = response.get("data", {}) if isinstance(response, dict) else {}
+            for metric, fact in snapshot.items():
+                results.append(
+                    {
+                        "symbol": response.get("ticker", symbol),
+                        "tag": metric,
+                        "value": fact.get("value"),
+                        "unit": fact.get("unit"),
+                        "fiscal_year": fact.get("fy"),
+                        "period_ending": fact.get("end"),
+                        "filed": fact.get("filed"),
+                    }
+                )
+
+        if not results:
+            raise EmptyDataError(
+                f"No fundamentals returned for {query.symbol}"
+                + (f" as of {query.as_of}" if query.as_of else "")
+                + ". Either the ticker is outside the covered universe, or no"
+                " filing was public by that date — each market's history depth"
+                " is listed at https://www.tradingagentapp.com/api/v1/fundamentals"
+            )
+        return results
+
+    @staticmethod
+    def transform_data(
+        query: TradingAgentLatestAttributesQueryParams,
+        data: List[Dict],
+        **kwargs: Any,
+    ) -> List[TradingAgentLatestAttributesData]:
+        """Filter to the requested tags."""
+        tags = {t.strip().lower() for t in query.tag.split(",") if t.strip()}
+        rows = [r for r in data if not tags or str(r["tag"]).lower() in tags]
+
+        if not rows:
+            available = sorted({str(r["tag"]) for r in data})
+            raise EmptyDataError(
+                f"No values for tag(s) '{query.tag}'. Available for this ticker: "
+                + ", ".join(available)
+            )
+        return [TradingAgentLatestAttributesData.model_validate(r) for r in rows]

openbb_tradingagent-1.0.0/openbb_tradingagent/utils/__init__.py

@@ -0,0 +1 @@
+"""Trading Agent provider utilities."""

openbb_tradingagent-1.0.0/openbb_tradingagent/utils/helpers.py

@@ -0,0 +1,33 @@
+"""Trading Agent provider helpers."""
+
+import os
+from typing import Any, Dict, Optional
+
+from openbb_core.provider.utils.helpers import amake_request
+
+BASE_URL = os.environ.get(
+    "TRADINGAGENT_BASE_URL", "https://www.tradingagentapp.com/api/v1"
+)
+
+
+async def get_data(
+    path: str,
+    params: Dict[str, Any],
+    api_key: Optional[str],
+    **kwargs: Any,
+) -> Any:
+    """GET a Trading Agent API path with Bearer auth; None params are dropped.
+
+    Falls back to the public `demo` key (25 flagship tickers, full history)
+    when no key is configured.
+    """
+    query = "&".join(f"{k}={v}" for k, v in params.items() if v is not None)
+    url = f"{BASE_URL}{path}" + (f"?{query}" if query else "")
+    headers = {"Authorization": f"Bearer {api_key or 'demo'}"}
+    response = await amake_request(url, headers=headers, **kwargs)
+    if isinstance(response, dict) and response.get("error"):
+        raise RuntimeError(
+            f"Trading Agent API error '{response['error']}': "
+            f"{response.get('message', '')}"
+        )
+    return response

openbb_tradingagent-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[tool.poetry]
+name = "openbb-tradingagent"
+version = "1.0.0"
+description = "Point-in-time company fundamentals from tradingagentapp.com for the OpenBB Platform (US SEC EDGAR, Taiwan TWSE, Korea OpenDART)."
+authors = ["Trading Agent <tradingagentapp@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://www.tradingagentapp.com/fundamentals"
+repository = "https://github.com/Wei-LienWU/trading-agent"
+keywords = ["openbb", "fundamentals", "point-in-time", "edgar", "twse", "opendart"]
+packages = [{ include = "openbb_tradingagent" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4"
+openbb-core = "^1.6.10"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.plugins."openbb_provider_extension"]
+tradingagent = "openbb_tradingagent:tradingagent_provider"
+
+[tool.pytest.ini_options]
+markers = [
+    "record_http: OpenBB's VCR marker — replays cassettes inside the OpenBB repo, hits the live API standalone.",
+]