filingstudio 0.4.0__tar.gz → 0.5.0__tar.gz

{filingstudio-0.4.0 → filingstudio-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: filingstudio
-Version: 0.4.0
+Version: 0.5.0
 Summary: Client for the Filing Studio API: search SEC filings, resolve traces, verify claims. One call per door, typed results, your key never in a URL.
 Project-URL: Homepage, https://filingstudio.com
 Project-URL: Documentation, https://filingstudio.com/docs#sdk
@@ -81,6 +81,9 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `filings(ticker, form=, year=, limit=)` | a company's indexed filings |
 | `coverage(ticker)` | is anything indexed, and how fresh |
 | `table(ticker, accession, table_id, format="records")` | one printed table, as filed |
+| `kpi_tables(ticker, quarterly=False)` | the newest 10-K's (10-Q's) non-statement tables, as a dict |
+| `kpi_series(ticker, table_id, quarterly=False, years=10)` | one table across filings as rows x periods, as a dict |
+| `statement(ticker, kind, quarterly=False, years=10)` | `income`, `balance` or `cashflow` as a time series, as a dict |
 
 Pass `value` to `verify` as the raw figure you hold (130497 or 130497000000
 alike). The API tries every printed scale a filer could use. Do not pre-scale.

{filingstudio-0.4.0 → filingstudio-0.5.0}/README.md

@@ -48,6 +48,9 @@ async with AsyncFilingStudio(api_key=key) as fs:
 | `filings(ticker, form=, year=, limit=)` | a company's indexed filings |
 | `coverage(ticker)` | is anything indexed, and how fresh |
 | `table(ticker, accession, table_id, format="records")` | one printed table, as filed |
+| `kpi_tables(ticker, quarterly=False)` | the newest 10-K's (10-Q's) non-statement tables, as a dict |
+| `kpi_series(ticker, table_id, quarterly=False, years=10)` | one table across filings as rows x periods, as a dict |
+| `statement(ticker, kind, quarterly=False, years=10)` | `income`, `balance` or `cashflow` as a time series, as a dict |
 
 Pass `value` to `verify` as the raw figure you hold (130497 or 130497000000
 alike). The API tries every printed scale a filer could use. Do not pre-scale.

{filingstudio-0.4.0 → filingstudio-0.5.0}/filingstudio/__init__.py

@@ -21,7 +21,7 @@ from .models import (
     VerifyResult,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __all__ = [
     "AsyncFilingStudio",
     "ContextRow",

{filingstudio-0.4.0 → filingstudio-0.5.0}/filingstudio/client.py

@@ -1,6 +1,8 @@
 """
 The Filing Studio client, sync and async. One method per /v1 door, the same
-names as the Node `@filingstudio/client` and the browser `ProvenanceClient`.
+names as the Node `@filingstudio/client` and the browser `ProvenanceClient`,
+plus three research doors (kpi_tables, kpi_series, statement) that answer
+the research JSON as a plain dict.
 
     from filingstudio import FilingStudio
     fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])
@@ -36,6 +38,7 @@ from .models import (
 )
 
 DEFAULT_BASE = "https://api.filingstudio.com"
+STATEMENT_KINDS = ("income", "balance", "cashflow")
 
 
 def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
@@ -50,6 +53,9 @@ def _describe(status: int, body: Any) -> "tuple[str, Optional[str]]":
         msg = err.get("message") if isinstance(err.get("message"), str) else f"HTTP {status}"
         code = err.get("code") if isinstance(err.get("code"), str) else None
         return msg, code
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if isinstance(detail, str):
+        return detail, None
     return f"HTTP {status}", None
 
 
@@ -179,6 +185,22 @@ class _Base:
         return (f"/v1/tables/{quote(ticker.upper(), safe='')}/{quote(accession, safe='')}/"
                 f"{quote(table_id, safe='')}")
 
+    # The research doors answer the raw research JSON, not the /v1 envelope.
+
+    @staticmethod
+    def _kpi_tables_path(ticker: str) -> str:
+        return f"/api/research/kpi/tables/{quote(ticker.upper(), safe='')}"
+
+    @staticmethod
+    def _kpi_series_path(ticker: str) -> str:
+        return f"/api/research/kpi/series/{quote(ticker.upper(), safe='')}"
+
+    @staticmethod
+    def _statement_path(ticker: str, kind: str) -> str:
+        if kind not in STATEMENT_KINDS:
+            raise ValueError(f"kind is one of {', '.join(STATEMENT_KINDS)}")
+        return f"/api/research/statements/{quote(ticker.upper(), safe='')}/{kind}"
+
 
 class FilingStudio(_Base):
     """Synchronous client. Use as a context manager to reuse one connection."""
@@ -258,6 +280,25 @@ class FilingStudio(_Base):
         return self._table(self._request("GET", self._table_path(ticker, accession, table_id),
                                          params={"format": format}))
 
+    def kpi_tables(self, ticker: str, *, quarterly: bool = False) -> Dict[str, Any]:
+        """The newest 10-K's (10-Q's) non-statement tables, named by the text above them:
+        {ticker, accession, form, filed, tables}."""
+        return self._request("GET", self._kpi_tables_path(ticker), params={"quarterly": quarterly})
+
+    def kpi_series(self, ticker: str, table_id: str, *, quarterly: bool = False,
+                   years: int = 10) -> Dict[str, Any]:
+        """One printed table carried across filings as rows x periods, every value traced:
+        {ticker, tableId, above, units, periods, sources, rows, gaps}."""
+        return self._request("GET", self._kpi_series_path(ticker),
+                             params={"table_id": table_id, "quarterly": quarterly, "years": years})
+
+    def statement(self, ticker: str, kind: str, *, quarterly: bool = False,
+                  years: int = 10) -> Dict[str, Any]:
+        """A primary statement (income, balance, cashflow) as a time series from each
+        filing's printed table. No model."""
+        return self._request("GET", self._statement_path(ticker, kind),
+                             params={"quarterly": quarterly, "years": years})
+
 
 class AsyncFilingStudio(_Base):
     """Asynchronous client with the same methods."""
@@ -331,3 +372,16 @@ class AsyncFilingStudio(_Base):
                     format: str = "records") -> TableResult:
         return self._table(await self._request("GET", self._table_path(ticker, accession, table_id),
                                                params={"format": format}))
+
+    async def kpi_tables(self, ticker: str, *, quarterly: bool = False) -> Dict[str, Any]:
+        return await self._request("GET", self._kpi_tables_path(ticker), params={"quarterly": quarterly})
+
+    async def kpi_series(self, ticker: str, table_id: str, *, quarterly: bool = False,
+                         years: int = 10) -> Dict[str, Any]:
+        return await self._request("GET", self._kpi_series_path(ticker),
+                                   params={"table_id": table_id, "quarterly": quarterly, "years": years})
+
+    async def statement(self, ticker: str, kind: str, *, quarterly: bool = False,
+                        years: int = 10) -> Dict[str, Any]:
+        return await self._request("GET", self._statement_path(ticker, kind),
+                                   params={"quarterly": quarterly, "years": years})

{filingstudio-0.4.0 → filingstudio-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "filingstudio"
-version = "0.4.0"
+version = "0.5.0"
 description = "Client for the Filing Studio API: search SEC filings, resolve traces, verify claims. One call per door, typed results, your key never in a URL."
 readme = "README.md"
 license = { text = "MIT" }

{filingstudio-0.4.0 → filingstudio-0.5.0}/tests/test_client.py

@@ -207,3 +207,47 @@ async def test_async_client_mirrors_sync():
         v = await fs.verify("NVDA", metric="Revenue", value=1)
         assert v.verdict == "unsupported" and v.actual[0].printed_text == "130,497"
         assert seen[-1].headers["x-api-key"] == KEY
+
+
+def test_research_doors_paths_params_and_raw_json():
+    fs, seen = make(lambda r, n: ok({"ticker": "LEN", "tables": [{"tableId": "t1"}]}))
+    assert fs.kpi_tables("len", quarterly=True)["tables"][0]["tableId"] == "t1"
+    fs.kpi_series("len", "primary:83", years=5)
+    fs.statement("len", "cashflow", quarterly=True, years=3)
+    assert [r.url.path for r in seen] == [
+        "/api/research/kpi/tables/LEN",
+        "/api/research/kpi/series/LEN",
+        "/api/research/statements/LEN/cashflow",
+    ]
+    assert dict(seen[0].url.params) == {"quarterly": "true"}
+    assert dict(seen[1].url.params) == {"table_id": "primary:83", "quarterly": "false", "years": "5"}
+    assert dict(seen[2].url.params) == {"quarterly": "true", "years": "3"}
+    assert all(r.headers["x-api-key"] == KEY and KEY not in str(r.url) for r in seen)
+
+
+def test_statement_rejects_unknown_kind_before_calling():
+    fs, seen = make(lambda r, n: ok({}))
+    with pytest.raises(ValueError):
+        fs.statement("LEN", "equity")
+    assert seen == []
+
+
+def test_research_door_404_detail_becomes_the_message():
+    fs, _ = make(lambda r, n: httpx.Response(404, json={"detail": "No 10-K for ZZZZ"}))
+    with pytest.raises(FilingStudioError) as e:
+        fs.kpi_tables("ZZZZ")
+    assert e.value.status == 404
+    assert "No 10-K for ZZZZ" in str(e.value)
+
+
+@pytest.mark.anyio
+async def test_async_research_doors():
+    fs, seen = amake(lambda r, n: ok({"rows": []}))
+    assert await fs.statement("nvda", "income") == {"rows": []}
+    await fs.kpi_series("nvda", "t9")
+    await fs.kpi_tables("nvda")
+    assert [r.url.path for r in seen] == [
+        "/api/research/statements/NVDA/income",
+        "/api/research/kpi/series/NVDA",
+        "/api/research/kpi/tables/NVDA",
+    ]