pit-fundamentals 0.1.0__tar.gz

pit_fundamentals-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+
+.venv/
+venv/
+env/
+.env
+.env.local
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+.DS_Store
+Thumbs.db
+
+.idea/
+.vscode/
+*.swp
+
+*.log
+data-staging/

pit_fundamentals-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: pit-fundamentals
+Version: 0.1.0
+Summary: Point-in-time company fundamentals from official regulator filings (US SEC EDGAR, Taiwan TWSE, Korea OpenDART) — as-first-reported, keyed by filing date, exportable. Zero dependencies.
+Project-URL: Homepage, https://www.tradingagentapp.com/fundamentals
+Project-URL: Documentation, https://www.tradingagentapp.com/developers
+Project-URL: Licence terms, https://www.tradingagentapp.com/licences/personal
+Author-email: WU Capital Limited <tradingagentapp@gmail.com>
+License: MIT
+Keywords: EDGAR,OpenDART,PIT,SEC,TWSE,backtesting,factor,financial-data,fundamentals,korea,look-ahead-bias,point-in-time,quant,stock-data,taiwan
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pit-fundamentals
+
+**Point-in-time company fundamentals from official regulator filings — as
+first reported, keyed by filing date, exportable.** Zero dependencies
+(pandas optional).
+
+Backtests leak the future when they use restated numbers or use figures
+before their filing date. This dataset stores every figure **as it was first
+reported** and stamps it with its **filing date**, so `as_of` queries return
+exactly what was public on that day.
+
+| Market | Source | Coverage |
+|---|---|---|
+| US | SEC EDGAR (public domain) | ~6,900 filers · annual + quarterly · 2014→ |
+| Taiwan | TWSE OpenAPI (Open Government Data License 1.0) | every listed company · accumulating quarterly |
+| Korea | FSS OpenDART | full market · loading |
+
+## Install
+
+```bash
+pip install pit-fundamentals
+```
+
+## 60-second start (no signup — public demo key built in)
+
+```python
+import pit_fundamentals as pf
+
+# TSMC's history, as first reported
+rows = pf.fundamentals("2330.TW")
+
+# What a backtest running on 2022-01-01 was allowed to know about Apple
+snap = pf.latest("AAPL", as_of="2022-01-01")
+print(snap["revenue"])   # FY2021, filed 2021-10-29 — nothing newer leaks
+
+# The scored, resolved prediction panel (history incl. losses; delayed on free)
+panel = pf.signals(market="TW", horizon="21d", limit=1000)
+
+# pandas users
+df = pf.to_df(rows)
+```
+
+The demo key covers **25 flagship tickers (US · TW · KR) at full fidelity** —
+full fields, full history. Paid plans unlock every ticker; your code doesn't
+change:
+
+```bash
+export PIT_FUNDAMENTALS_KEY=ta_live_xxxxxxxx
+```
+
+## Pricing & licences
+
+Free / Personal US$29/mo / Commercial US$149/mo / Redistribution US$499/mo —
+plans and full licence texts: <https://www.tradingagentapp.com/fundamentals>
+
+What makes the licence unusual: **no export bans, no display-only clause, and
+your derived research is yours forever** (explicitly, in writing — including
+after cancellation). We ingest from public filings directly, so no upstream
+vendor licence forbids you taking the data with you.
+
+## Notes worth knowing
+
+- **Taiwan income statements are cumulative year-to-date** (Taiwan reporting
+  convention: Q2 = H1 total). Difference adjacent quarters for single-quarter
+  flows. Balance-sheet items are point-in-time as usual.
+- Every API response embeds its statutory source attribution (e.g. 臺灣證券
+  交易所 under OGDL 1.0).
+- Factual, historical data only — no forecasts, no advice, no price/OHLCV.
+
+Docs: <https://www.tradingagentapp.com/developers> ·
+Field dictionary and examples included.

pit_fundamentals-0.1.0/README.md

@@ -0,0 +1,71 @@
+# pit-fundamentals
+
+**Point-in-time company fundamentals from official regulator filings — as
+first reported, keyed by filing date, exportable.** Zero dependencies
+(pandas optional).
+
+Backtests leak the future when they use restated numbers or use figures
+before their filing date. This dataset stores every figure **as it was first
+reported** and stamps it with its **filing date**, so `as_of` queries return
+exactly what was public on that day.
+
+| Market | Source | Coverage |
+|---|---|---|
+| US | SEC EDGAR (public domain) | ~6,900 filers · annual + quarterly · 2014→ |
+| Taiwan | TWSE OpenAPI (Open Government Data License 1.0) | every listed company · accumulating quarterly |
+| Korea | FSS OpenDART | full market · loading |
+
+## Install
+
+```bash
+pip install pit-fundamentals
+```
+
+## 60-second start (no signup — public demo key built in)
+
+```python
+import pit_fundamentals as pf
+
+# TSMC's history, as first reported
+rows = pf.fundamentals("2330.TW")
+
+# What a backtest running on 2022-01-01 was allowed to know about Apple
+snap = pf.latest("AAPL", as_of="2022-01-01")
+print(snap["revenue"])   # FY2021, filed 2021-10-29 — nothing newer leaks
+
+# The scored, resolved prediction panel (history incl. losses; delayed on free)
+panel = pf.signals(market="TW", horizon="21d", limit=1000)
+
+# pandas users
+df = pf.to_df(rows)
+```
+
+The demo key covers **25 flagship tickers (US · TW · KR) at full fidelity** —
+full fields, full history. Paid plans unlock every ticker; your code doesn't
+change:
+
+```bash
+export PIT_FUNDAMENTALS_KEY=ta_live_xxxxxxxx
+```
+
+## Pricing & licences
+
+Free / Personal US$29/mo / Commercial US$149/mo / Redistribution US$499/mo —
+plans and full licence texts: <https://www.tradingagentapp.com/fundamentals>
+
+What makes the licence unusual: **no export bans, no display-only clause, and
+your derived research is yours forever** (explicitly, in writing — including
+after cancellation). We ingest from public filings directly, so no upstream
+vendor licence forbids you taking the data with you.
+
+## Notes worth knowing
+
+- **Taiwan income statements are cumulative year-to-date** (Taiwan reporting
+  convention: Q2 = H1 total). Difference adjacent quarters for single-quarter
+  flows. Balance-sheet items are point-in-time as usual.
+- Every API response embeds its statutory source attribution (e.g. 臺灣證券
+  交易所 under OGDL 1.0).
+- Factual, historical data only — no forecasts, no advice, no price/OHLCV.
+
+Docs: <https://www.tradingagentapp.com/developers> ·
+Field dictionary and examples included.

pit_fundamentals-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pit-fundamentals"
+version = "0.1.0"
+description = "Point-in-time company fundamentals from official regulator filings (US SEC EDGAR, Taiwan TWSE, Korea OpenDART) — as-first-reported, keyed by filing date, exportable. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "WU Capital Limited", email = "tradingagentapp@gmail.com" }]
+keywords = [
+  "point-in-time", "fundamentals", "PIT", "backtesting", "look-ahead-bias",
+  "SEC", "EDGAR", "taiwan", "TWSE", "korea", "OpenDART", "quant", "factor",
+  "financial-data", "stock-data",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+
+[project.urls]
+Homepage = "https://www.tradingagentapp.com/fundamentals"
+Documentation = "https://www.tradingagentapp.com/developers"
+"Licence terms" = "https://www.tradingagentapp.com/licences/personal"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pit_fundamentals"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pit_fundamentals", "README.md"]

pit_fundamentals-0.1.0/src/pit_fundamentals/__init__.py

@@ -0,0 +1,137 @@
+"""pit-fundamentals — point-in-time company fundamentals, zero dependencies.
+
+As-first-reported figures from official regulator filings (US SEC EDGAR,
+Taiwan TWSE, Korea FSS OpenDART), keyed by their FILING DATE so a backtest at
+date T sees only what was public at T. Served by Trading Agent Data
+(https://www.tradingagentapp.com/fundamentals).
+
+Quickstart (works immediately — the public demo key covers 25 flagship
+tickers at full fidelity, no signup):
+
+    import pit_fundamentals as pf
+
+    rows = pf.fundamentals("2330.TW")                     # full history
+    snap = pf.latest("AAPL", as_of="2022-01-01")          # PIT snapshot
+    panel = pf.signals(market="TW", horizon="21d")        # scored predictions
+
+    # with pandas installed:
+    df = pf.to_df(rows)
+
+Paid keys unlock every ticker — set PIT_FUNDAMENTALS_KEY (or TRADING_AGENT_API_KEY)
+in the environment, or pass api_key=... . Your code does not change otherwise.
+
+Data licences: https://www.tradingagentapp.com/licences/personal
+Taiwan data note: income-statement figures are cumulative year-to-date per
+Taiwan reporting convention (Q2 = H1 total) — difference adjacent quarters for
+single-quarter flows. Every response embeds its statutory source attribution.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.parse
+import urllib.request
+
+__all__ = ["fundamentals", "latest", "coverage", "signals", "to_df", "ApiError"]
+__version__ = "0.1.0"
+
+BASE_URL = os.environ.get("PIT_FUNDAMENTALS_BASE", "https://www.tradingagentapp.com/api/v1")
+DEMO_KEY = "demo"
+
+
+class ApiError(RuntimeError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, body: str):
+        super().__init__(f"HTTP {status}: {body[:300]}")
+        self.status = status
+        self.body = body
+
+
+def _key(api_key: str | None) -> str:
+    return (
+        api_key
+        or os.environ.get("PIT_FUNDAMENTALS_KEY")
+        or os.environ.get("TRADING_AGENT_API_KEY")
+        or DEMO_KEY
+    )
+
+
+def _get(path: str, params: dict, api_key: str | None):
+    qs = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+    req = urllib.request.Request(
+        f"{BASE_URL}{path}?{qs}",
+        headers={
+            "Authorization": f"Bearer {_key(api_key)}",
+            "User-Agent": f"pit-fundamentals/{__version__}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r:
+            return json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:  # pragma: no cover - passthrough
+        raise ApiError(e.code, e.read().decode("utf-8", "replace")) from None
+
+
+def fundamentals(
+    ticker: str,
+    *,
+    as_of: str | None = None,
+    metric: str | None = None,
+    from_: str | None = None,
+    market: str | None = None,
+    api_key: str | None = None,
+) -> list[dict]:
+    """As-first-reported history for one ticker (list of row dicts).
+
+    Row fields: m (metric), fy/fp (fiscal year/period), end (period end),
+    filed (filing date — the point-in-time key), v (value), u (unit).
+    `as_of` returns only rows with filed <= as_of (no look-ahead).
+    """
+    out = _get(
+        "/fundamentals",
+        {"ticker": ticker, "as_of": as_of, "metric": metric, "from": from_, "market": market},
+        api_key,
+    )
+    return out.get("data", [])
+
+
+def latest(ticker: str, *, as_of: str | None = None, api_key: str | None = None) -> dict:
+    """The as-of snapshot: latest value per metric with filed <= as_of."""
+    out = _get("/fundamentals", {"ticker": ticker, "as_of": as_of, "view": "latest"}, api_key)
+    return out.get("data", {})
+
+
+def coverage(api_key: str | None = None) -> dict:
+    """Markets, tickers, per-market manifests, and (free tier) the ticker allowlist."""
+    return _get("/fundamentals", {}, api_key)
+
+
+def signals(
+    *,
+    market: str | None = None,
+    horizon: str | None = None,
+    from_: str | None = None,
+    to: str | None = None,
+    limit: int | None = None,
+    api_key: str | None = None,
+) -> list[dict]:
+    """The resolved (historical, scored) prediction panel — wins and losses.
+
+    Free/demo keys get a ~90-day-delayed view; this is factual history, not
+    forward recommendations. predicted_pct / actual_pct are FRACTIONS.
+    """
+    out = _get(
+        "/signals",
+        {"market": market, "horizon": horizon, "from": from_, "to": to, "limit": limit},
+        api_key,
+    )
+    return out.get("data", [])
+
+
+def to_df(rows: list[dict]):
+    """Convert a row list to a pandas DataFrame (pandas required only here)."""
+    import pandas as pd  # local import: the package itself stays zero-dep
+
+    return pd.DataFrame(rows)