filingstudio

Python client for the Filing Studio API. Search SEC filings exactly as printed, resolve any number back to the line that printed it, and verify claims deterministically. One call per door, typed results, and your key never in a URL.

pip install filingstudio

import os
from filingstudio import FilingStudio

fs = FilingStudio(api_key=os.environ["FILING_STUDIO_API_KEY"])

hits = fs.search("NVDA", "purchase commitments", type="prose")
for p in hits.passages:
    print(p.text, p.trace_id)

v = fs.verify("NVDA", metric="Revenue", value=130497, period="FY2025")
print(v.verdict)                       # supported | unsupported | ambiguous | unavailable
print(v.receipts[0].printed_text)      # "130,497"
print(v.receipts[0].links.highlight)   # opens the filing with that cell marked

t = fs.trace(v.receipts[0].trace_id)   # the printed line plus its neighbours
for row in t.context:
    print(row.label, row.printed_text, "<- source" if row.is_source else "")

Async is the same API:

from filingstudio import AsyncFilingStudio

async with AsyncFilingStudio(api_key=key) as fs:
    cov = await fs.coverage("NVDA")

The six doors

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.

Honest answers

Every result carries index_state. coverage is one of:

• indexed: a populated index answered, with results
• empty: a populated index answered and had nothing. The only real negative.
• incomplete: the index could not fully answer. Says nothing about the filing.
• unavailable: the service or your quota could not answer. Same.

RateLimitError (HTTP 429) carries index_state.note, a sentence safe to show a user. Other non-2xx answers raise FilingStudioError with status, code, and the API's message. 5xx and network failures are retried with backoff; 4xx are not. No error ever contains your key.

Research with receipts (experimental)

from filingstudio.research import answer

def llm(system: str, user: str, json_mode: bool) -> str:
    ...  # any chat model; return the assistant text

res = answer("How is Data Center revenue trending?", "NVDA", llm=llm, client=fs,
             on_step=lambda label, detail: print(label, detail))
res.answer, res.sources, res.hard_stop

Plan, search, assess, write, with hard stops. Every [n] in the answer is a search hit you can trace; citations to nothing are stripped; with no evidence the answer says so. llm=None runs one search and returns the evidence only.

Options

FilingStudio(api_key, base_url=None, timeout=30.0, max_retries=2, transport=None)

transport accepts an httpx transport, for tests (httpx.MockTransport).

Develop

pip install -e .[test]
pytest

MIT